diff --git a/bun.lock b/bun.lock
index 88eb689d1..87744835e 100644
--- a/bun.lock
+++ b/bun.lock
@@ -21,7 +21,7 @@
     },
     "packages/cli": {
       "name": "@hyperframes/cli",
-      "version": "0.4.31",
+      "version": "0.5.0-alpha.14",
       "bin": {
         "hyperframes": "./dist/cli.js",
       },
@@ -62,7 +62,7 @@
     },
     "packages/core": {
       "name": "@hyperframes/core",
-      "version": "0.4.31",
+      "version": "0.5.0-alpha.14",
       "dependencies": {
         "@chenglou/pretext": "^0.0.5",
         "postcss": "^8.5.8",
@@ -89,7 +89,7 @@
     },
     "packages/engine": {
       "name": "@hyperframes/engine",
-      "version": "0.4.31",
+      "version": "0.5.0-alpha.14",
       "dependencies": {
         "@hono/node-server": "^1.13.0",
         "@hyperframes/core": "workspace:^",
@@ -107,7 +107,7 @@
     },
     "packages/player": {
       "name": "@hyperframes/player",
-      "version": "0.4.31",
+      "version": "0.5.0-alpha.14",
       "devDependencies": {
         "@types/bun": "^1.1.0",
         "gsap": "^3.12.5",
@@ -119,7 +119,7 @@
     },
     "packages/producer": {
       "name": "@hyperframes/producer",
-      "version": "0.4.31",
+      "version": "0.5.0-alpha.14",
       "dependencies": {
         "@fontsource/archivo-black": "^5.2.8",
         "@fontsource/eb-garamond": "^5.2.7",
@@ -158,7 +158,7 @@
     },
     "packages/shader-transitions": {
       "name": "@hyperframes/shader-transitions",
-      "version": "0.4.31",
+      "version": "0.5.0-alpha.14",
       "dependencies": {
         "html2canvas": "^1.4.1",
       },
@@ -170,7 +170,7 @@
     },
     "packages/studio": {
       "name": "@hyperframes/studio",
-      "version": "0.4.31",
+      "version": "0.5.0-alpha.14",
       "dependencies": {
         "@codemirror/autocomplete": "^6.20.1",
         "@codemirror/commands": "^6.10.3",
@@ -186,6 +186,7 @@
         "@hyperframes/player": "workspace:*",
         "@phosphor-icons/react": "^2.1.10",
         "codemirror": "^6.0.1",
+        "mediabunny": "^1.43.0",
         "motion": "^12.38.0",
       },
       "devDependencies": {
@@ -750,6 +751,10 @@
 
     "@types/deep-eql": ["@types/deep-eql@4.0.2", "", {}, "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw=="],
 
+    "@types/dom-mediacapture-transform": ["@types/dom-mediacapture-transform@0.1.11", "", { "dependencies": { "@types/dom-webcodecs": "*" } }, "sha512-Y2p+nGf1bF2XMttBnsVPHUWzRRZzqUoJAKmiP10b5umnO6DDrWI0BrGDJy1pOHoOULVmGSfFNkQrAlC5dcj6nQ=="],
+
+    "@types/dom-webcodecs": ["@types/dom-webcodecs@0.1.13", "", {}, "sha512-O5hkiFIcjjszPIYyUSyvScyvrBoV3NOEEZx/pMlsu44TKzWNkLVBBxnxJz42in5n3QIolYOcBYFCPZZ0h8SkwQ=="],
+
     "@types/estree": ["@types/estree@1.0.8", "", {}, "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w=="],
 
     "@types/jsdom": ["@types/jsdom@28.0.1", "", { "dependencies": { "@types/node": "24.12.0", "@types/tough-cookie": "4.0.5", "parse5": "7.3.0", "undici-types": "7.24.5" } }, "sha512-GJq2QE4TAZ5ajSoCasn5DOFm8u1mI3tIFvM5tIq3W5U/RTB6gsHwc6Yhpl91X9VSDOUVblgXmG+2+sSvFQrdlw=="],
@@ -1234,6 +1239,8 @@
 
     "mdn-data": ["mdn-data@2.27.1", "", {}, "sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ=="],
 
+    "mediabunny": ["mediabunny@1.43.0", "", { "dependencies": { "@types/dom-mediacapture-transform": "^0.1.11", "@types/dom-webcodecs": "0.1.13" } }, "sha512-QGj6PcXXQvhs+29Pl25z3THv17g31k18zHUrJ25UQc5KWVN0vMKbMbB8KuHXNcseALIhbs6nh+wskimaeH/EEw=="],
+
     "meow": ["meow@13.2.0", "", {}, "sha512-pxQJQzB6djGPXh08dacEloMFopsOqGVRKFPYvPOt9XDZ1HasbgDZA74CJGreSU4G3Ak7EFJGoiH2auq+yXISgA=="],
 
     "merge2": ["merge2@1.4.1", "", {}, "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg=="],
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
 
 <CodeGroup>
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 50d08880b..245ddac43 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -201,7 +201,8 @@
             "pages": [
               "contributing",
               "contributing/release-channels",
-              "contributing/testing-local-changes"
+              "contributing/testing-local-changes",
+              "contributing/studio-manual-dom-editing"
             ]
           }
         ]
diff --git a/packages/cli/package.json b/packages/cli/package.json
index c1f00c03a..6e38aa99f 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/cli",
-  "version": "0.4.41",
+  "version": "0.5.0-alpha.14",
   "description": "HyperFrames CLI — create, preview, and render HTML video compositions",
   "repository": {
     "type": "git",
diff --git a/packages/cli/src/server/fileWatcher.ts b/packages/cli/src/server/fileWatcher.ts
index ffe0620a9..747077f8b 100644
--- a/packages/cli/src/server/fileWatcher.ts
+++ b/packages/cli/src/server/fileWatcher.ts
@@ -9,6 +9,13 @@ export interface ProjectWatcher {
 }
 
 const WATCHED_EXTENSIONS = new Set([".html", ".css", ".js", ".json"]);
+const IGNORED_SEGMENTS = new Set([
+  ".git",
+  ".hyperframes",
+  ".thumbnails",
+  "node_modules",
+  "renders",
+]);
 const DEBOUNCE_MS = 300;
 
 export function createProjectWatcher(projectDir: string): ProjectWatcher {
@@ -19,6 +26,8 @@ export function createProjectWatcher(projectDir: string): ProjectWatcher {
   try {
     watcher = watch(projectDir, { recursive: true }, (_event, filename) => {
       if (!filename) return;
+      const segments = filename.split(/[\\/]/).filter(Boolean);
+      if (segments.some((segment) => IGNORED_SEGMENTS.has(segment))) return;
       const ext = "." + filename.split(".").pop()?.toLowerCase();
       if (!WATCHED_EXTENSIONS.has(ext)) return;
 
diff --git a/packages/cli/src/server/studioServer.ts b/packages/cli/src/server/studioServer.ts
index 0f4d06024..c55e35757 100644
--- a/packages/cli/src/server/studioServer.ts
+++ b/packages/cli/src/server/studioServer.ts
@@ -260,23 +260,34 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
         await new Promise((r) => setTimeout(r, 200));
         let clip: { x: number; y: number; width: number; height: number } | undefined;
         if (opts.selector) {
-          clip = await page.evaluate((selector: string) => {
-            const el = document.querySelector(selector);
-            if (!(el instanceof HTMLElement)) return undefined;
-            const rect = el.getBoundingClientRect();
-            if (rect.width < 4 || rect.height < 4) return undefined;
-            const pad = 8;
-            const x = Math.max(0, rect.left - pad);
-            const y = Math.max(0, rect.top - pad);
-            const maxWidth = window.innerWidth - x;
-            const maxHeight = window.innerHeight - y;
-            return {
-              x,
-              y,
-              width: Math.max(1, Math.min(rect.width + pad * 2, maxWidth)),
-              height: Math.max(1, Math.min(rect.height + pad * 2, maxHeight)),
-            };
-          }, opts.selector);
+          clip = await page.evaluate(
+            (selector: string, selectorIndex: number | 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;
+              const pad = 8;
+              const x = Math.max(0, rect.left - pad);
+              const y = Math.max(0, rect.top - pad);
+              const maxWidth = window.innerWidth - x;
+              const maxHeight = window.innerHeight - y;
+              return {
+                x,
+                y,
+                width: Math.max(1, Math.min(rect.width + pad * 2, maxWidth)),
+                height: Math.max(1, Math.min(rect.height + pad * 2, maxHeight)),
+              };
+            },
+            opts.selector,
+            opts.selectorIndex,
+          );
         }
         const screenshot = (await page.screenshot(
           opts.format === "png"
@@ -330,6 +341,30 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
     return serve();
   });
 
+  const api = createStudioApi(adapter);
+  let recentApiWriteAt = 0;
+
+  watcher.addListener((relativePath) => {
+    if (Date.now() - recentApiWriteAt < 3000) return;
+    void api
+      .fetch(
+        new Request(
+          `http://studio/projects/${encodeURIComponent(project.id)}/history/adopt-external`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              paths: [relativePath],
+              actor: { type: "external" },
+            }),
+          },
+        ),
+      )
+      .catch((error) => {
+        console.warn("[studio] Failed to adopt external file edit:", error);
+      });
+  });
+
   app.get("/api/events", (c) => {
     return streamSSE(c, async (stream) => {
       const listener = () => {
@@ -345,10 +380,12 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
   // Mount the shared studio API at /api.
   // Use fetch() forwarding (not .route()) so the sub-app sees paths without
   // the /api prefix — the shared module's path extraction uses c.req.path.
-  const api = createStudioApi(adapter);
   app.all("/api/*", async (c) => {
     const url = new URL(c.req.url);
     url.pathname = url.pathname.slice(4); // Strip "/api" prefix
+    if (/^\/projects\/[^/]+\/(?:edits|history\/(?:undo|redo|record-applied))/.test(url.pathname)) {
+      recentApiWriteAt = Date.now();
+    }
     const forwardReq = new Request(url.toString(), {
       method: c.req.method,
       headers: c.req.raw.headers,
diff --git a/packages/core/package.json b/packages/core/package.json
index 35570678a..3a3c6ea56 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/core",
-  "version": "0.4.41",
+  "version": "0.5.0-alpha.14",
   "description": "",
   "repository": {
     "type": "git",
@@ -30,10 +30,18 @@
       "types": "./src/compiler/index.ts"
     },
     "./runtime": "./dist/hyperframe.runtime.iife.js",
+    "./runtime/lottie-readiness": {
+      "import": "./src/runtime/adapters/lottieReadiness.ts",
+      "types": "./src/runtime/adapters/lottieReadiness.ts"
+    },
     "./studio-api": {
       "import": "./src/studio-api/index.ts",
       "types": "./src/studio-api/index.ts"
     },
+    "./studio-history": {
+      "import": "./src/studio-api/history/editHistory.ts",
+      "types": "./src/studio-api/history/editHistory.ts"
+    },
     "./text": {
       "import": "./src/text/index.ts",
       "types": "./src/text/index.ts"
@@ -61,10 +69,18 @@
         "types": "./dist/compiler/index.d.ts"
       },
       "./runtime": "./dist/hyperframe.runtime.iife.js",
+      "./runtime/lottie-readiness": {
+        "import": "./dist/runtime/adapters/lottieReadiness.js",
+        "types": "./dist/runtime/adapters/lottieReadiness.d.ts"
+      },
       "./studio-api": {
         "import": "./dist/studio-api/index.js",
         "types": "./dist/studio-api/index.d.ts"
       },
+      "./studio-history": {
+        "import": "./dist/studio-api/history/editHistory.js",
+        "types": "./dist/studio-api/history/editHistory.d.ts"
+      },
       "./text": {
         "import": "./dist/text/index.js",
         "types": "./dist/text/index.d.ts"
diff --git a/packages/core/src/compiler/htmlBundler.ts b/packages/core/src/compiler/htmlBundler.ts
index 34e139a01..d730daa57 100644
--- a/packages/core/src/compiler/htmlBundler.ts
+++ b/packages/core/src/compiler/htmlBundler.ts
@@ -3,7 +3,11 @@ import { join, resolve, isAbsolute, sep } from "path";
 import { parseHTML } from "linkedom";
 import { transformSync } from "esbuild";
 import { compileHtml, type MediaDurationProber } from "./htmlCompiler";
-import { rewriteAssetPaths, rewriteCssAssetUrls } from "./rewriteSubCompPaths";
+import {
+  rewriteAssetPaths,
+  rewriteCssAssetUrls,
+  rewriteInlineStyleAssetUrls,
+} from "./rewriteSubCompPaths";
 import { scopeCssToComposition, wrapScopedCompositionScript } from "./compositionScoping";
 import { validateHyperframeHtmlContract } from "./staticGuard";
 
@@ -538,6 +542,17 @@ 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");
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<T>(
   }
 }
 
+/**
+ * Rewrite CSS url(...) references inside inline style attributes.
+ */
+export function rewriteInlineStyleAssetUrls<T>(
+  elements: Iterable<T>,
+  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 = `
+<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <script>
+      window.__timelines = window.__timelines || {};
+      var tl = gsap.timeline({ paused: true });
+      var sceneCaption = document.querySelector("#scene-caption");
+      CARDS.forEach(function(group, gi) {
+        var groupEl = document.createElement("div");
+        groupEl.id = "card-" + gi;
+        tl.to(groupEl, { opacity: 0, duration: 0.12 }, 2);
+      });
+      window.__timelines["main"] = tl;
+    </script>
+  </div>
+</body></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 = `
 <html><body>
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/runtime/adapters/hfMotion.test.ts b/packages/core/src/runtime/adapters/hfMotion.test.ts
new file mode 100644
index 000000000..ddd34ce3a
--- /dev/null
+++ b/packages/core/src/runtime/adapters/hfMotion.test.ts
@@ -0,0 +1,274 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  createHfMotionAdapter,
+  parseHfMotionAttribute,
+  parseHfMotionVarsAttribute,
+} from "./hfMotion";
+
+describe("hf motion adapter", () => {
+  const originalRequestAnimationFrame = window.requestAnimationFrame;
+  const originalCancelAnimationFrame = window.cancelAnimationFrame;
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    window.requestAnimationFrame = originalRequestAnimationFrame;
+    window.cancelAnimationFrame = originalCancelAnimationFrame;
+  });
+
+  it("has correct name", () => {
+    expect(createHfMotionAdapter().name).toBe("hf-motion");
+  });
+
+  it("parses the v1 data-hf-motion contract", () => {
+    expect(
+      parseHfMotionAttribute(
+        "v=1;preset=fade-up;start=0;duration=0.6;ease=outCubic;x=0;y=32;opacity=0:1;scale=1:1",
+      ),
+    ).toEqual({
+      version: 1,
+      preset: "fade-up",
+      start: 0,
+      duration: 0.6,
+      ease: "outCubic",
+      x: { from: 0, to: 0 },
+      y: { from: 32, to: 0 },
+      opacity: { from: 0, to: 1 },
+      scale: { from: 1, to: 1 },
+    });
+  });
+
+  it("parses extended and custom easing values", () => {
+    expect(
+      parseHfMotionAttribute(
+        "v=1;preset=fade-up;start=0;duration=0.6;ease=outBack;x=0;y=32;opacity=0:1;scale=1:1",
+      )?.ease,
+    ).toBe("outBack");
+    expect(
+      parseHfMotionAttribute(
+        "v=1;preset=fade-up;start=0;duration=0.6;ease=cubic-bezier(0.2,1.25,0.4,1);x=0;y=32;opacity=0:1;scale=1:1",
+      )?.ease,
+    ).toBe("bezier(0.2,1.25,0.4,1)");
+    expect(
+      parseHfMotionAttribute(
+        "v=1;preset=fade-up;start=0;duration=0.6;ease=bezier(1.2,0,0.4,1);x=0;y=32;opacity=0:1;scale=1:1",
+      ),
+    ).toBeNull();
+  });
+
+  it("rejects malformed motion values without throwing", () => {
+    expect(parseHfMotionAttribute("v=2;preset=fade-up;duration=0.6")).toBeNull();
+    expect(parseHfMotionAttribute("v=1;preset=fade-up;duration=-1")).toBeNull();
+    expect(parseHfMotionAttribute("v=1;preset=<script>;duration=1")).toBeNull();
+    expect(() => parseHfMotionAttribute("v=1;preset=fade-up;duration=abc")).not.toThrow();
+  });
+
+  it("parses the v1 data-hf-motion-vars contract", () => {
+    expect(
+      parseHfMotionVarsAttribute(
+        "v=1;id=headline;lanes=x,y,scale,rotate,opacity;owner=hf;driver=hf",
+      ),
+    ).toEqual({
+      version: 1,
+      id: "headline",
+      lanes: ["x", "y", "scale", "rotate", "opacity"],
+      owner: "hf",
+      driver: "hf",
+    });
+
+    expect(
+      parseHfMotionVarsAttribute("v=1;id=headline;lanes=x,unknown;owner=hf;driver=hf"),
+    ).toBeNull();
+    expect(
+      parseHfMotionVarsAttribute("v=1;id=headline;lanes=x;owner=lottie;driver=runtime"),
+    ).toBeNull();
+  });
+
+  it("seeks custom cubic-bezier easing deterministically", () => {
+    const el = document.createElement("div");
+    el.setAttribute(
+      "data-hf-motion",
+      "v=1;preset=fade-up;start=0;duration=1;ease=bezier(0,0,1,1);x=0;y=20;opacity=1:1;scale=1:1",
+    );
+    document.body.appendChild(el);
+
+    const adapter = createHfMotionAdapter();
+    adapter.discover();
+    adapter.seek({ time: 0.5 });
+
+    expect(el.style.transform).toBe("translate(0px, 10px) scale(1)");
+  });
+
+  it("writes deterministic HF Motion into canonical CSS variable lanes", () => {
+    const el = document.createElement("div");
+    el.style.opacity = "0.5";
+    el.style.transform = "rotate(3deg)";
+    el.setAttribute(
+      "data-hf-motion",
+      "v=1;preset=fade-up;start=0;duration=1;ease=linear;x=0;y=20;opacity=0:1;scale=1:1",
+    );
+    el.setAttribute(
+      "data-hf-motion-vars",
+      "v=1;id=headline;lanes=x,y,scale,rotate,opacity;owner=hf;driver=hf",
+    );
+    document.body.appendChild(el);
+
+    const adapter = createHfMotionAdapter();
+    adapter.discover();
+    adapter.seek({ time: 0.5 });
+
+    expect(el.style.getPropertyValue("--hf-motion-x")).toBe("0px");
+    expect(el.style.getPropertyValue("--hf-motion-y")).toBe("10px");
+    expect(el.style.getPropertyValue("--hf-motion-scale")).toBe("1");
+    expect(el.style.getPropertyValue("--hf-motion-rotate")).toBe("0deg");
+    expect(el.style.getPropertyValue("--hf-motion-opacity")).toBe("0.25");
+    expect(el.style.transform).toBe(
+      "rotate(3deg) translate3d(var(--hf-motion-x, 0px), var(--hf-motion-y, 0px), 0) rotate(var(--hf-motion-rotate, 0deg)) scale(var(--hf-motion-scale, 1))",
+    );
+    expect(el.style.opacity).toBe("var(--hf-motion-opacity, 0.5)");
+  });
+
+  it("applies the variable transform template for runtime-driven variable lanes", () => {
+    const el = document.createElement("div");
+    el.setAttribute(
+      "data-hf-motion-vars",
+      "v=1;id=headline;lanes=x,y,scale,rotate,opacity;owner=gsap;driver=runtime",
+    );
+    document.body.appendChild(el);
+
+    const adapter = createHfMotionAdapter();
+    adapter.discover();
+    adapter.seek({ time: 0.5 });
+
+    expect(el.style.transform).toBe(
+      "translate3d(var(--hf-motion-x, 0px), var(--hf-motion-y, 0px), 0) rotate(var(--hf-motion-rotate, 0deg)) scale(var(--hf-motion-scale, 1))",
+    );
+    expect(el.style.getPropertyValue("--hf-motion-x")).toBe("");
+  });
+
+  it("seeks authored motion deterministically and clamps progress", () => {
+    const el = document.createElement("div");
+    el.style.opacity = "0.5";
+    el.setAttribute(
+      "data-hf-motion",
+      "v=1;preset=fade-up;start=0;duration=1;ease=linear;x=0;y=20;opacity=0:1;scale=1:1",
+    );
+    document.body.appendChild(el);
+
+    const adapter = createHfMotionAdapter();
+    adapter.discover();
+
+    adapter.seek({ time: -1 });
+    expect(el.style.opacity).toBe("0");
+    expect(el.style.transform).toBe("translate(0px, 20px) scale(1)");
+
+    adapter.seek({ time: 0.5 });
+    expect(el.style.opacity).toBe("0.25");
+    expect(el.style.transform).toBe("translate(0px, 10px) scale(1)");
+
+    adapter.seek({ time: 2 });
+    expect(el.style.opacity).toBe("0.5");
+    expect(el.style.transform).toBe("");
+  });
+
+  it("drives authored motion while runtime playback is active", () => {
+    let currentTime = 0;
+    let nextFrameId = 1;
+    const callbacks = new Map<number, FrameRequestCallback>();
+    window.requestAnimationFrame = vi.fn((callback: FrameRequestCallback) => {
+      const id = nextFrameId;
+      nextFrameId += 1;
+      callbacks.set(id, callback);
+      return id;
+    }) as typeof window.requestAnimationFrame;
+    window.cancelAnimationFrame = vi.fn((id: number) => {
+      callbacks.delete(id);
+    }) as typeof window.cancelAnimationFrame;
+
+    const el = document.createElement("div");
+    el.setAttribute(
+      "data-hf-motion",
+      "v=1;preset=fade-up;start=0;duration=1;ease=linear;x=0;y=20;opacity=1:1;scale=1:1",
+    );
+    document.body.appendChild(el);
+
+    const adapter = createHfMotionAdapter({ getCurrentTime: () => currentTime });
+    adapter.discover();
+    adapter.play?.();
+
+    expect(el.style.transform).toBe("translate(0px, 20px) scale(1)");
+
+    currentTime = 0.5;
+    const firstFrame = callbacks.entries().next().value as
+      | [number, FrameRequestCallback]
+      | undefined;
+    expect(firstFrame).toBeDefined();
+    if (firstFrame) {
+      callbacks.delete(firstFrame[0]);
+      firstFrame[1](16);
+    }
+
+    expect(el.style.transform).toBe("translate(0px, 10px) scale(1)");
+    expect(callbacks.size).toBe(1);
+
+    adapter.pause();
+
+    expect(callbacks.size).toBe(0);
+  });
+
+  it("resolves motion start relative to the selected element", () => {
+    const el = document.createElement("div");
+    el.setAttribute(
+      "data-hf-motion",
+      "v=1;preset=fade-up;start=0.5;duration=1;ease=linear;x=0;y=40;opacity=0:1;scale=1:1",
+    );
+    document.body.appendChild(el);
+
+    const adapter = createHfMotionAdapter({ resolveStartSeconds: () => 2 });
+    adapter.discover();
+
+    adapter.seek({ time: 2.5 });
+    expect(el.style.opacity).toBe("0");
+    expect(el.style.transform).toBe("translate(0px, 40px) scale(1)");
+
+    adapter.seek({ time: 3 });
+    expect(el.style.opacity).toBe("0.5");
+    expect(el.style.transform).toBe("translate(0px, 20px) scale(1)");
+  });
+
+  it("appends authored transform to the base transform", () => {
+    const el = document.createElement("div");
+    el.style.transform = "rotate(3deg)";
+    el.setAttribute(
+      "data-hf-motion",
+      "v=1;preset=slide;start=0;duration=1;ease=linear;x=20;y=0;opacity=1:1;scale=1:1",
+    );
+    document.body.appendChild(el);
+
+    const adapter = createHfMotionAdapter();
+    adapter.discover();
+    adapter.seek({ time: 0.5 });
+
+    expect(el.style.transform).toBe("rotate(3deg) translate(10px, 0px) scale(1)");
+  });
+
+  it("reverts inline styles it owns", () => {
+    const el = document.createElement("div");
+    el.style.opacity = "0.4";
+    el.style.transform = "rotate(3deg)";
+    el.setAttribute(
+      "data-hf-motion",
+      "v=1;preset=pop;start=0;duration=1;ease=linear;x=0;y=0;opacity=0:1;scale=0.9:1",
+    );
+    document.body.appendChild(el);
+
+    const adapter = createHfMotionAdapter();
+    adapter.discover();
+    adapter.seek({ time: 0.5 });
+    expect(el.style.opacity).toBe("0.2");
+    expect(el.style.transform).toBe("rotate(3deg) translate(0px, 0px) scale(0.95)");
+
+    adapter.revert?.();
+    expect(el.style.opacity).toBe("0.4");
+    expect(el.style.transform).toBe("rotate(3deg)");
+  });
+});
diff --git a/packages/core/src/runtime/adapters/hfMotion.ts b/packages/core/src/runtime/adapters/hfMotion.ts
new file mode 100644
index 000000000..b785a6ece
--- /dev/null
+++ b/packages/core/src/runtime/adapters/hfMotion.ts
@@ -0,0 +1,767 @@
+import type { RuntimeDeterministicAdapter } from "../types";
+
+export type HfMotionEasePreset =
+  | "linear"
+  | "ease"
+  | "inSine"
+  | "outSine"
+  | "inOutSine"
+  | "inQuad"
+  | "outQuad"
+  | "inOutQuad"
+  | "inCubic"
+  | "outCubic"
+  | "inOutCubic"
+  | "inQuart"
+  | "outQuart"
+  | "inOutQuart"
+  | "inQuint"
+  | "outQuint"
+  | "inOutQuint"
+  | "inExpo"
+  | "outExpo"
+  | "inOutExpo"
+  | "inCirc"
+  | "outCirc"
+  | "inOutCirc"
+  | "inBack"
+  | "outBack"
+  | "inOutBack"
+  | "inBounce"
+  | "outBounce"
+  | "inOutBounce"
+  | "inElastic"
+  | "outElastic"
+  | "inOutElastic";
+
+export type HfMotionEase = HfMotionEasePreset | `bezier(${string})`;
+
+export interface HfMotionRange {
+  from: number;
+  to: number;
+}
+
+export interface HfMotionConfig {
+  version: 1;
+  preset: string;
+  start: number;
+  duration: number;
+  ease: HfMotionEase;
+  x: HfMotionRange;
+  y: HfMotionRange;
+  opacity: HfMotionRange;
+  scale: HfMotionRange;
+}
+
+export type HfMotionVarLane = "x" | "y" | "scale" | "rotate" | "opacity";
+export type HfMotionVarOwner = "hf" | "gsap" | "anime" | "css" | "waapi";
+export type HfMotionVarDriver = "hf" | "runtime";
+
+export interface HfMotionVarsConfig {
+  version: 1;
+  id: string;
+  lanes: HfMotionVarLane[];
+  owner: HfMotionVarOwner;
+  driver: HfMotionVarDriver;
+}
+
+type HfMotionEntry = {
+  el: HTMLElement;
+  attributeValue: string;
+  config: HfMotionConfig | null;
+  varsAttributeValue: string;
+  varsConfig: HfMotionVarsConfig | null;
+  baseInlineOpacity: string;
+  baseOpacity: number;
+  baseInlineTransform: string;
+  baseInlineVars: Partial<Record<HfMotionVarName, string>>;
+};
+
+const MOTION_ATTR = "data-hf-motion";
+const MOTION_VARS_ATTR = "data-hf-motion-vars";
+const EPSILON = 0.0001;
+const HF_MOTION_TRANSFORM_TEMPLATE =
+  "translate3d(var(--hf-motion-x, 0px), var(--hf-motion-y, 0px), 0) rotate(var(--hf-motion-rotate, 0deg)) scale(var(--hf-motion-scale, 1))";
+const HF_MOTION_VAR_NAMES = [
+  "--hf-motion-x",
+  "--hf-motion-y",
+  "--hf-motion-scale",
+  "--hf-motion-rotate",
+  "--hf-motion-opacity",
+] as const;
+type HfMotionVarName = (typeof HF_MOTION_VAR_NAMES)[number];
+const SUPPORTED_VAR_LANES = new Set<HfMotionVarLane>(["x", "y", "scale", "rotate", "opacity"]);
+const SUPPORTED_VAR_OWNERS = new Set<HfMotionVarOwner>(["hf", "gsap", "anime", "css", "waapi"]);
+const SUPPORTED_VAR_DRIVERS = new Set<HfMotionVarDriver>(["hf", "runtime"]);
+let cssPropertiesRegistered = false;
+const SUPPORTED_EASES = new Set<string>([
+  "linear",
+  "ease",
+  "inSine",
+  "outSine",
+  "inOutSine",
+  "inQuad",
+  "outQuad",
+  "inOutQuad",
+  "inCubic",
+  "outCubic",
+  "inOutCubic",
+  "inQuart",
+  "outQuart",
+  "inOutQuart",
+  "inQuint",
+  "outQuint",
+  "inOutQuint",
+  "inExpo",
+  "outExpo",
+  "inOutExpo",
+  "inCirc",
+  "outCirc",
+  "inOutCirc",
+  "inBack",
+  "outBack",
+  "inOutBack",
+  "inBounce",
+  "outBounce",
+  "inOutBounce",
+  "inElastic",
+  "outElastic",
+  "inOutElastic",
+]);
+
+interface CubicBezierEase {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+}
+
+export function parseHfMotionAttribute(value: string | null | undefined): HfMotionConfig | null {
+  if (!value) return null;
+
+  const parts = new Map<string, string>();
+  for (const rawPart of value.split(";")) {
+    const part = rawPart.trim();
+    if (!part) continue;
+    const separatorIndex = part.indexOf("=");
+    if (separatorIndex <= 0) return null;
+    const key = part.slice(0, separatorIndex).trim();
+    const partValue = part.slice(separatorIndex + 1).trim();
+    if (!key || !partValue) return null;
+    parts.set(key, partValue);
+  }
+
+  if (parts.get("v") !== "1") return null;
+  const preset = parts.get("preset");
+  if (!preset || !/^[a-z0-9-]{1,40}$/.test(preset)) return null;
+
+  const start = parseFiniteNumber(parts.get("start") ?? "0");
+  const duration = parseFiniteNumber(parts.get("duration"));
+  if (start == null || start < 0 || duration == null || duration <= 0) return null;
+
+  const ease = normalizeHfMotionEase(parts.get("ease") ?? "linear");
+  if (!ease) return null;
+
+  const x = parseRange(parts.get("x"), { from: 0, to: 0 }, 0);
+  const y = parseRange(parts.get("y"), { from: 0, to: 0 }, 0);
+  const opacity = parseRange(parts.get("opacity"), { from: 1, to: 1 });
+  const scale = parseRange(parts.get("scale"), { from: 1, to: 1 });
+  if (!x || !y || !opacity || !scale) return null;
+  if (!isUnitRange(opacity) || scale.from < 0 || scale.to < 0) return null;
+
+  return {
+    version: 1,
+    preset,
+    start,
+    duration,
+    ease,
+    x,
+    y,
+    opacity,
+    scale,
+  };
+}
+
+export function parseHfMotionVarsAttribute(
+  value: string | null | undefined,
+): HfMotionVarsConfig | null {
+  if (!value) return null;
+
+  const parts = new Map<string, string>();
+  for (const rawPart of value.split(";")) {
+    const part = rawPart.trim();
+    if (!part) continue;
+    const separatorIndex = part.indexOf("=");
+    if (separatorIndex <= 0) return null;
+    const key = part.slice(0, separatorIndex).trim();
+    const partValue = part.slice(separatorIndex + 1).trim();
+    if (!key || !partValue) return null;
+    parts.set(key, partValue);
+  }
+
+  if (parts.get("v") !== "1") return null;
+  const id = parts.get("id");
+  if (!id || !/^[a-z0-9][a-z0-9-]{0,63}$/.test(id)) return null;
+
+  const rawLanes =
+    parts
+      .get("lanes")
+      ?.split(",")
+      .map((lane) => lane.trim()) ?? [];
+  if (rawLanes.length === 0) return null;
+  const lanes: HfMotionVarLane[] = [];
+  for (const lane of rawLanes) {
+    if (!SUPPORTED_VAR_LANES.has(lane as HfMotionVarLane)) return null;
+    if (!lanes.includes(lane as HfMotionVarLane)) lanes.push(lane as HfMotionVarLane);
+  }
+
+  const owner = parts.get("owner") as HfMotionVarOwner | undefined;
+  if (!owner || !SUPPORTED_VAR_OWNERS.has(owner)) return null;
+  const driver = parts.get("driver") as HfMotionVarDriver | undefined;
+  if (!driver || !SUPPORTED_VAR_DRIVERS.has(driver)) return null;
+
+  return {
+    version: 1,
+    id,
+    lanes,
+    owner,
+    driver,
+  };
+}
+
+export function createHfMotionAdapter(params?: {
+  resolveStartSeconds?: (element: Element) => number;
+  getCurrentTime?: () => number;
+}): RuntimeDeterministicAdapter {
+  let entries: HfMotionEntry[] = [];
+  const entryByElement = new WeakMap<HTMLElement, HfMotionEntry>();
+  let playbackRafId: number | null = null;
+
+  const restoreOpacity = (entry: HfMotionEntry) => {
+    if (entry.baseInlineOpacity) {
+      entry.el.style.opacity = entry.baseInlineOpacity;
+    } else {
+      entry.el.style.removeProperty("opacity");
+    }
+  };
+
+  const restoreTransform = (entry: HfMotionEntry) => {
+    if (entry.baseInlineTransform) {
+      entry.el.style.transform = entry.baseInlineTransform;
+    } else {
+      entry.el.style.removeProperty("transform");
+    }
+  };
+
+  const restoreVars = (entry: HfMotionEntry) => {
+    for (const name of HF_MOTION_VAR_NAMES) {
+      const value = entry.baseInlineVars[name];
+      if (value) {
+        entry.el.style.setProperty(name, value);
+      } else {
+        entry.el.style.removeProperty(name);
+      }
+    }
+  };
+
+  const restoreEntry = (entry: HfMotionEntry) => {
+    restoreVars(entry);
+    restoreOpacity(entry);
+    restoreTransform(entry);
+  };
+
+  const syncEntries = () => {
+    registerHfMotionCssProperties();
+    const nextEntries: HfMotionEntry[] = [];
+    const seen = new Set<HTMLElement>();
+    const motionElements = document.querySelectorAll(`[${MOTION_ATTR}], [${MOTION_VARS_ATTR}]`);
+    for (const rawEl of motionElements) {
+      if (!(rawEl instanceof HTMLElement)) continue;
+      const attributeValue = rawEl.getAttribute(MOTION_ATTR) ?? "";
+      const config = parseHfMotionAttribute(attributeValue);
+      const varsAttributeValue = rawEl.getAttribute(MOTION_VARS_ATTR) ?? "";
+      const varsConfig = parseHfMotionVarsAttribute(varsAttributeValue);
+      if (!config && !varsConfig) continue;
+
+      seen.add(rawEl);
+      const existing = entryByElement.get(rawEl);
+      if (existing) {
+        existing.attributeValue = attributeValue;
+        existing.config = config;
+        existing.varsAttributeValue = varsAttributeValue;
+        existing.varsConfig = varsConfig;
+        nextEntries.push(existing);
+        continue;
+      }
+
+      const nextEntry = {
+        el: rawEl,
+        attributeValue,
+        config,
+        varsAttributeValue,
+        varsConfig,
+        baseInlineOpacity: rawEl.style.opacity || "",
+        baseOpacity: resolveBaseOpacity(rawEl),
+        baseInlineTransform: rawEl.style.transform || "",
+        baseInlineVars: snapshotInlineVars(rawEl),
+      };
+      entryByElement.set(rawEl, nextEntry);
+      nextEntries.push(nextEntry);
+    }
+
+    for (const entry of entries) {
+      if (seen.has(entry.el)) continue;
+      if (entry.el.isConnected) restoreEntry(entry);
+      entryByElement.delete(entry.el);
+    }
+
+    entries = nextEntries;
+  };
+
+  const seekAllAtTime = (timeSeconds: number) => {
+    syncEntries();
+    const time = Math.max(0, Number(timeSeconds) || 0);
+    for (const entry of entries) {
+      if (!entry.el.isConnected) continue;
+      applyVariableTemplate(entry);
+      if (!entry.config) continue;
+      applyMotionAtTime(entry, time, params?.resolveStartSeconds);
+    }
+  };
+
+  const stopPlaybackLoop = () => {
+    if (playbackRafId == null) return;
+    window.cancelAnimationFrame(playbackRafId);
+    playbackRafId = null;
+  };
+
+  const tickPlayback = () => {
+    playbackRafId = null;
+    const getCurrentTime = params?.getCurrentTime;
+    if (!getCurrentTime) return;
+    seekAllAtTime(getCurrentTime());
+    playbackRafId = window.requestAnimationFrame(tickPlayback);
+  };
+
+  const startPlaybackLoop = () => {
+    if (playbackRafId != null) return;
+    syncEntries();
+    if (!params?.getCurrentTime || !entries.some((entry) => entry.config)) return;
+    seekAllAtTime(params.getCurrentTime());
+    playbackRafId = window.requestAnimationFrame(tickPlayback);
+  };
+
+  return {
+    name: "hf-motion",
+
+    discover: () => {
+      syncEntries();
+    },
+
+    seek: (ctx) => {
+      seekAllAtTime(ctx.time);
+    },
+
+    pause: () => {
+      stopPlaybackLoop();
+    },
+
+    play: () => {
+      startPlaybackLoop();
+    },
+
+    revert: () => {
+      stopPlaybackLoop();
+      for (const entry of entries) {
+        if (!entry.el.isConnected) continue;
+        restoreEntry(entry);
+      }
+      entries = [];
+    },
+  };
+}
+
+function parseFiniteNumber(value: string | undefined): number | null {
+  if (value == null) return null;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) && String(value).trim() !== "" ? parsed : null;
+}
+
+function parseRange(
+  value: string | undefined,
+  fallback: HfMotionRange,
+  singleValueTo?: number,
+): HfMotionRange | null {
+  if (value == null || value.trim() === "") return fallback;
+  const parts = value.split(":");
+  if (parts.length > 2) return null;
+  const from = parseFiniteNumber(parts[0]);
+  if (from == null) return null;
+  const to =
+    parts.length === 2 ? parseFiniteNumber(parts[1]) : singleValueTo != null ? singleValueTo : from;
+  if (to == null) return null;
+  return { from, to };
+}
+
+function isUnitRange(range: HfMotionRange): boolean {
+  return range.from >= 0 && range.from <= 1 && range.to >= 0 && range.to <= 1;
+}
+
+function resolveBaseOpacity(el: HTMLElement): number {
+  const inlineOpacity = parseFiniteNumber(el.style.opacity);
+  if (inlineOpacity != null) return inlineOpacity;
+  try {
+    const computedOpacity = parseFiniteNumber(window.getComputedStyle(el).opacity);
+    return computedOpacity ?? 1;
+  } catch {
+    return 1;
+  }
+}
+
+function applyMotionAtTime(
+  entry: HfMotionEntry,
+  time: number,
+  resolveStartSeconds: ((element: Element) => number) | undefined,
+): void {
+  if (!entry.config) return;
+  const clipStart = resolveStartSeconds ? resolveStartSeconds(entry.el) : 0;
+  const localTime = time - Math.max(0, Number(clipStart) || 0) - entry.config.start;
+  const rawProgress = localTime / entry.config.duration;
+  const progress = easeProgress(clamp(rawProgress, 0, 1), entry.config.ease);
+  const x = interpolate(entry.config.x, progress);
+  const y = interpolate(entry.config.y, progress);
+  const opacityMultiplier = interpolate(entry.config.opacity, progress);
+  const scale = interpolate(entry.config.scale, progress);
+
+  if (entry.varsConfig?.driver === "hf") {
+    applyVariableMotion(entry, x, y, scale, entry.baseOpacity * opacityMultiplier);
+    return;
+  }
+
+  applyOpacity(entry, entry.baseOpacity * opacityMultiplier);
+  applyTransform(entry, x, y, scale);
+}
+
+function snapshotInlineVars(el: HTMLElement): Partial<Record<HfMotionVarName, string>> {
+  const vars: Partial<Record<HfMotionVarName, string>> = {};
+  for (const name of HF_MOTION_VAR_NAMES) {
+    const value = el.style.getPropertyValue(name);
+    if (value) vars[name] = value;
+  }
+  return vars;
+}
+
+function registerHfMotionCssProperties(): void {
+  if (cssPropertiesRegistered) return;
+  cssPropertiesRegistered = true;
+  const cssGlobal = window.CSS as
+    | (typeof CSS & {
+        registerProperty?: (definition: {
+          name: string;
+          syntax: string;
+          inherits: boolean;
+          initialValue: string;
+        }) => void;
+      })
+    | undefined;
+  const registerProperty = cssGlobal?.registerProperty;
+  if (typeof registerProperty !== "function") return;
+
+  const definitions = [
+    { name: "--hf-motion-x", syntax: "<length>", initialValue: "0px" },
+    { name: "--hf-motion-y", syntax: "<length>", initialValue: "0px" },
+    { name: "--hf-motion-scale", syntax: "<number>", initialValue: "1" },
+    { name: "--hf-motion-rotate", syntax: "<angle>", initialValue: "0deg" },
+    { name: "--hf-motion-opacity", syntax: "<number>", initialValue: "1" },
+  ];
+
+  for (const definition of definitions) {
+    try {
+      registerProperty.call(cssGlobal, {
+        ...definition,
+        inherits: false,
+      });
+    } catch {
+      // Browsers throw when a custom property is registered twice.
+    }
+  }
+}
+
+function applyVariableTemplate(entry: HfMotionEntry): void {
+  if (!entry.varsConfig) return;
+  const baseTransform = entry.baseInlineTransform.trim();
+  entry.el.style.transform = baseTransform
+    ? `${baseTransform} ${HF_MOTION_TRANSFORM_TEMPLATE}`
+    : HF_MOTION_TRANSFORM_TEMPLATE;
+  entry.el.style.opacity = `var(--hf-motion-opacity, ${formatNumber(entry.baseOpacity)})`;
+}
+
+function applyVariableMotion(
+  entry: HfMotionEntry,
+  x: number,
+  y: number,
+  scale: number,
+  opacity: number,
+): void {
+  applyVariableTemplate(entry);
+  const clampedScale = Math.max(0, scale);
+  entry.el.style.setProperty("--hf-motion-x", `${formatNumber(x)}px`);
+  entry.el.style.setProperty("--hf-motion-y", `${formatNumber(y)}px`);
+  entry.el.style.setProperty("--hf-motion-scale", formatNumber(clampedScale));
+  entry.el.style.setProperty("--hf-motion-rotate", "0deg");
+  entry.el.style.setProperty("--hf-motion-opacity", formatNumber(clamp(opacity, 0, 1)));
+}
+
+function applyOpacity(entry: HfMotionEntry, value: number): void {
+  const clampedValue = clamp(value, 0, 1);
+  if (Math.abs(clampedValue - entry.baseOpacity) < EPSILON) {
+    if (entry.baseInlineOpacity) {
+      entry.el.style.opacity = entry.baseInlineOpacity;
+    } else {
+      entry.el.style.removeProperty("opacity");
+    }
+    return;
+  }
+  entry.el.style.opacity = formatNumber(clampedValue);
+}
+
+function applyTransform(entry: HfMotionEntry, x: number, y: number, scale: number): void {
+  const clampedScale = Math.max(0, scale);
+  const isNeutral =
+    Math.abs(x) < EPSILON && Math.abs(y) < EPSILON && Math.abs(clampedScale - 1) < EPSILON;
+  if (isNeutral) {
+    if (entry.baseInlineTransform) {
+      entry.el.style.transform = entry.baseInlineTransform;
+    } else {
+      entry.el.style.removeProperty("transform");
+    }
+    return;
+  }
+
+  const motionTransform = `translate(${formatNumber(x)}px, ${formatNumber(y)}px) scale(${formatNumber(
+    clampedScale,
+  )})`;
+  entry.el.style.transform = [entry.baseInlineTransform, motionTransform].filter(Boolean).join(" ");
+}
+
+function interpolate(range: HfMotionRange, progress: number): number {
+  return range.from + (range.to - range.from) * progress;
+}
+
+function easeProgress(progress: number, ease: HfMotionEase): number {
+  const bezier = parseHfMotionBezierEase(ease);
+  if (bezier) return cubicBezierProgress(progress, bezier);
+
+  const c1 = 1.70158;
+  const c2 = c1 * 1.525;
+  const c3 = c1 + 1;
+  const c4 = (2 * Math.PI) / 3;
+  const c5 = (2 * Math.PI) / 4.5;
+
+  switch (ease) {
+    case "ease":
+      return cubicBezierProgress(progress, { x1: 0.25, y1: 0.1, x2: 0.25, y2: 1 });
+    case "inSine":
+      return 1 - Math.cos((progress * Math.PI) / 2);
+    case "outSine":
+      return Math.sin((progress * Math.PI) / 2);
+    case "inOutSine":
+      return -(Math.cos(Math.PI * progress) - 1) / 2;
+    case "inQuad":
+      return progress * progress;
+    case "outQuad":
+      return 1 - (1 - progress) * (1 - progress);
+    case "inOutQuad":
+      return progress < 0.5 ? 2 * progress * progress : 1 - Math.pow(-2 * progress + 2, 2) / 2;
+    case "inCubic":
+      return progress * progress * progress;
+    case "outCubic":
+      return 1 - Math.pow(1 - progress, 3);
+    case "inOutCubic":
+      return progress < 0.5
+        ? 4 * progress * progress * progress
+        : 1 - Math.pow(-2 * progress + 2, 3) / 2;
+    case "inQuart":
+      return progress * progress * progress * progress;
+    case "outQuart":
+      return 1 - Math.pow(1 - progress, 4);
+    case "inOutQuart":
+      return progress < 0.5 ? 8 * Math.pow(progress, 4) : 1 - Math.pow(-2 * progress + 2, 4) / 2;
+    case "inQuint":
+      return Math.pow(progress, 5);
+    case "outQuint":
+      return 1 - Math.pow(1 - progress, 5);
+    case "inOutQuint":
+      return progress < 0.5 ? 16 * Math.pow(progress, 5) : 1 - Math.pow(-2 * progress + 2, 5) / 2;
+    case "inExpo":
+      return progress === 0 ? 0 : Math.pow(2, 10 * progress - 10);
+    case "outExpo":
+      return progress === 1 ? 1 : 1 - Math.pow(2, -10 * progress);
+    case "inOutExpo":
+      return progress === 0
+        ? 0
+        : progress === 1
+          ? 1
+          : progress < 0.5
+            ? Math.pow(2, 20 * progress - 10) / 2
+            : (2 - Math.pow(2, -20 * progress + 10)) / 2;
+    case "inCirc":
+      return 1 - Math.sqrt(1 - Math.pow(progress, 2));
+    case "outCirc":
+      return Math.sqrt(1 - Math.pow(progress - 1, 2));
+    case "inOutCirc":
+      return progress < 0.5
+        ? (1 - Math.sqrt(1 - Math.pow(2 * progress, 2))) / 2
+        : (Math.sqrt(1 - Math.pow(-2 * progress + 2, 2)) + 1) / 2;
+    case "inBack":
+      return c3 * progress * progress * progress - c1 * progress * progress;
+    case "outBack":
+      return 1 + c3 * Math.pow(progress - 1, 3) + c1 * Math.pow(progress - 1, 2);
+    case "inOutBack":
+      return progress < 0.5
+        ? (Math.pow(2 * progress, 2) * ((c2 + 1) * 2 * progress - c2)) / 2
+        : (Math.pow(2 * progress - 2, 2) * ((c2 + 1) * (progress * 2 - 2) + c2) + 2) / 2;
+    case "inBounce":
+      return 1 - outBounce(1 - progress);
+    case "outBounce":
+      return outBounce(progress);
+    case "inOutBounce":
+      return progress < 0.5
+        ? (1 - outBounce(1 - 2 * progress)) / 2
+        : (1 + outBounce(2 * progress - 1)) / 2;
+    case "inElastic":
+      return progress === 0
+        ? 0
+        : progress === 1
+          ? 1
+          : -Math.pow(2, 10 * progress - 10) * Math.sin((progress * 10 - 10.75) * c4);
+    case "outElastic":
+      return progress === 0
+        ? 0
+        : progress === 1
+          ? 1
+          : Math.pow(2, -10 * progress) * Math.sin((progress * 10 - 0.75) * c4) + 1;
+    case "inOutElastic":
+      return progress === 0
+        ? 0
+        : progress === 1
+          ? 1
+          : progress < 0.5
+            ? -(Math.pow(2, 20 * progress - 10) * Math.sin((20 * progress - 11.125) * c5)) / 2
+            : (Math.pow(2, -20 * progress + 10) * Math.sin((20 * progress - 11.125) * c5)) / 2 + 1;
+    case "linear":
+    default:
+      return progress;
+  }
+}
+
+function normalizeHfMotionEase(value: string): HfMotionEase | null {
+  const trimmed = value.trim();
+  if (isHfMotionEasePreset(trimmed)) return trimmed;
+  const bezier = parseHfMotionBezierEase(trimmed);
+  return bezier ? formatBezierEase(bezier) : null;
+}
+
+function isHfMotionEasePreset(value: string): value is HfMotionEasePreset {
+  return SUPPORTED_EASES.has(value);
+}
+
+function parseHfMotionBezierEase(value: string): CubicBezierEase | null {
+  const trimmed = value.trim();
+  const bezierPrefix = "bezier(";
+  const cssPrefix = "cubic-bezier(";
+  const prefix = trimmed.startsWith(bezierPrefix)
+    ? bezierPrefix
+    : trimmed.startsWith(cssPrefix)
+      ? cssPrefix
+      : null;
+  if (!prefix || !trimmed.endsWith(")")) return null;
+
+  const body = trimmed.slice(prefix.length, -1);
+  const parts = body.split(",").map((part) => parseFiniteNumber(part));
+  if (parts.length !== 4 || parts.some((part) => part == null)) return null;
+  const [x1, y1, x2, y2] = parts;
+  if (x1 == null || y1 == null || x2 == null || y2 == null) return null;
+  if (x1 < 0 || x1 > 1 || x2 < 0 || x2 > 1) return null;
+  if (y1 < -4 || y1 > 4 || y2 < -4 || y2 > 4) return null;
+  return { x1, y1, x2, y2 };
+}
+
+function formatBezierEase(bezier: CubicBezierEase): HfMotionEase {
+  return `bezier(${formatNumber(bezier.x1)},${formatNumber(bezier.y1)},${formatNumber(
+    bezier.x2,
+  )},${formatNumber(bezier.y2)})`;
+}
+
+function cubicBezierProgress(progress: number, bezier: CubicBezierEase): number {
+  if (progress <= 0 || progress >= 1) return progress;
+
+  let t = progress;
+  for (let index = 0; index < 8; index += 1) {
+    const x = cubicBezierAxis(t, bezier.x1, bezier.x2) - progress;
+    const dx = cubicBezierAxisDerivative(t, bezier.x1, bezier.x2);
+    if (Math.abs(x) < 0.000001) break;
+    if (Math.abs(dx) < 0.000001) {
+      t = solveBezierTByBisection(progress, bezier);
+      break;
+    }
+    t = clamp(t - x / dx, 0, 1);
+  }
+
+  return cubicBezierAxis(t, bezier.y1, bezier.y2);
+}
+
+function solveBezierTByBisection(progress: number, bezier: CubicBezierEase): number {
+  let lower = 0;
+  let upper = 1;
+  let t = progress;
+  for (let index = 0; index < 16; index += 1) {
+    t = (lower + upper) / 2;
+    const x = cubicBezierAxis(t, bezier.x1, bezier.x2);
+    if (Math.abs(x - progress) < 0.000001) break;
+    if (x < progress) {
+      lower = t;
+    } else {
+      upper = t;
+    }
+  }
+  return t;
+}
+
+function cubicBezierAxis(t: number, p1: number, p2: number): number {
+  const inverseT = 1 - t;
+  return 3 * inverseT * inverseT * t * p1 + 3 * inverseT * t * t * p2 + t * t * t;
+}
+
+function cubicBezierAxisDerivative(t: number, p1: number, p2: number): number {
+  const inverseT = 1 - t;
+  return 3 * inverseT * inverseT * p1 + 6 * inverseT * t * (p2 - p1) + 3 * t * t * (1 - p2);
+}
+
+function outBounce(progress: number): number {
+  const n1 = 7.5625;
+  const d1 = 2.75;
+  if (progress < 1 / d1) return n1 * progress * progress;
+  if (progress < 2 / d1) {
+    const shifted = progress - 1.5 / d1;
+    return n1 * shifted * shifted + 0.75;
+  }
+  if (progress < 2.5 / d1) {
+    const shifted = progress - 2.25 / d1;
+    return n1 * shifted * shifted + 0.9375;
+  }
+  const shifted = progress - 2.625 / d1;
+  return n1 * shifted * shifted + 0.984375;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+function formatNumber(value: number): string {
+  const normalized = Math.abs(value) < EPSILON ? 0 : value;
+  const rounded = Math.round(normalized * 10000) / 10000;
+  return Number.isInteger(rounded)
+    ? `${rounded}`
+    : rounded.toFixed(4).replace(/0+$/, "").replace(/\.$/, "");
+}
diff --git a/packages/core/src/runtime/init.test.ts b/packages/core/src/runtime/init.test.ts
index 24c11cb9c..3b6497231 100644
--- a/packages/core/src/runtime/init.test.ts
+++ b/packages/core/src/runtime/init.test.ts
@@ -282,4 +282,27 @@ describe("initSandboxRuntimeModular", () => {
     expect(video.paused).toBe(true);
     expect(video.currentTime).toBe(0);
   });
+
+  it("uses root data-duration as the duration for timeline-less compositions", () => {
+    const root = document.createElement("div");
+    root.setAttribute("data-composition-id", "main");
+    root.setAttribute("data-root", "true");
+    root.setAttribute("data-width", "1920");
+    root.setAttribute("data-height", "1080");
+    root.setAttribute("data-duration", "3");
+    document.body.appendChild(root);
+
+    initSandboxRuntimeModular();
+
+    const player = (
+      window as Window & {
+        __player?: { getDuration: () => number; play: () => void; isPlaying: () => boolean };
+      }
+    ).__player;
+    expect(player).toBeDefined();
+    expect(player?.getDuration()).toBe(3);
+
+    player?.play();
+    expect(player?.isPlaying()).toBe(true);
+  });
 });
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index 5c5d8a84d..4f7bcddb6 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -2,6 +2,7 @@ import { installRuntimeControlBridge, postRuntimeMessage } from "./bridge";
 import { initRuntimeAnalytics, emitAnalyticsEvent } from "./analytics";
 import { createCssAdapter } from "./adapters/css";
 import { createGsapAdapter } from "./adapters/gsap";
+import { createHfMotionAdapter } from "./adapters/hfMotion";
 import { createAnimeJsAdapter } from "./adapters/animejs";
 import { createLottieAdapter } from "./adapters/lottie";
 import { createThreeAdapter } from "./adapters/three";
@@ -468,12 +469,17 @@ export function initSandboxRuntimeModular(): void {
   const resolveAuthoredCompositionDurationFloorSeconds = (): number | null => {
     const rootEl = resolveRootCompositionElement();
     if (!rootEl) return null;
+    const rootDeclaredDuration = Number(rootEl.getAttribute("data-duration"));
+    const rootDeclaredEnd = Number(rootEl.getAttribute("data-end"));
+    let maxWindowEndSeconds = Math.max(
+      Number.isFinite(rootDeclaredDuration) && rootDeclaredDuration > 0 ? rootDeclaredDuration : 0,
+      Number.isFinite(rootDeclaredEnd) && rootDeclaredEnd > 0 ? rootDeclaredEnd : 0,
+    );
     const timelines = (window.__timelines ?? {}) as Record<string, RuntimeTimelineLike | undefined>;
     const startResolver = createRuntimeStartTimeResolver({
       timelineRegistry: timelines,
       includeAuthoredTimingAttrs: true,
     });
-    let maxWindowEndSeconds = 0;
     const compositionNodes = Array.from(
       rootEl.querySelectorAll("[data-composition-id][data-start]"),
     );
@@ -1498,6 +1504,7 @@ export function initSandboxRuntimeModular(): void {
     getPlaybackRate: () => state.playbackRate,
     setPlaybackRate: applyPlaybackRate,
     getCanonicalFps: () => state.canonicalFps,
+    getCurrentTime: () => state.currentTime,
     onSyncMedia: (timeSeconds, playing) => {
       state.currentTime = Math.max(0, Number(timeSeconds) || 0);
       state.isPlaying = playing;
@@ -1600,6 +1607,10 @@ export function initSandboxRuntimeModular(): void {
     createLottieAdapter(),
     createThreeAdapter(),
     createGsapAdapter({ getTimeline: () => state.capturedTimeline }),
+    createHfMotionAdapter({
+      resolveStartSeconds: (element) => resolveStartForElement(element, 0),
+      getCurrentTime: () => state.capturedTimeline?.time() ?? state.currentTime,
+    }),
   ] as RuntimeDeterministicAdapter[];
   installRuntimeErrorDiagnostics();
   runAdapters("discover");
@@ -1609,6 +1620,7 @@ export function initSandboxRuntimeModular(): void {
   }
   let timelinePollTick = 0;
   let lastObservedTimelineTime: number | null = null;
+  let lastTimelineLessPlaybackAtMs: number | null = null;
   let lastExplicitSeekAtMs = 0;
   let loopGuardRebindTriggered = false;
   let loopWrapCandidateCount = 0;
@@ -1636,6 +1648,29 @@ export function initSandboxRuntimeModular(): void {
       bindMediaMetadataListeners();
     }
     syncCurrentTimeFromTimeline();
+    if (state.isPlaying && !state.capturedTimeline) {
+      const now = performance.now();
+      const previousTick = lastTimelineLessPlaybackAtMs ?? now;
+      lastTimelineLessPlaybackAtMs = now;
+      const elapsedSeconds = Math.max(0, (now - previousTick) / 1000);
+      const safeDuration = getSafeTimelineDurationSeconds(null, 0);
+      const nextTime = Math.max(0, (state.currentTime || 0) + elapsedSeconds * state.playbackRate);
+      state.currentTime = safeDuration > 0 && nextTime >= safeDuration ? safeDuration : nextTime;
+      for (const adapter of state.deterministicAdapters) {
+        try {
+          adapter.seek({ time: state.currentTime });
+        } catch {
+          // ignore adapter failure
+        }
+      }
+      syncMediaForCurrentState();
+      if (safeDuration > 0 && state.currentTime >= safeDuration) {
+        player.pause();
+      }
+      postState(false);
+      return;
+    }
+    lastTimelineLessPlaybackAtMs = null;
     if (state.isPlaying && state.capturedTimeline) {
       const currentObserved = Math.max(0, state.currentTime || 0);
       const previousObserved = lastObservedTimelineTime;
diff --git a/packages/core/src/runtime/player.test.ts b/packages/core/src/runtime/player.test.ts
index 9ade8ced4..cf9bd44f8 100644
--- a/packages/core/src/runtime/player.test.ts
+++ b/packages/core/src/runtime/player.test.ts
@@ -31,6 +31,7 @@ function createMockTimeline(opts?: { time?: number; duration?: number }): Runtim
 function createMockDeps(timeline?: RuntimeTimelineLike | null) {
   let isPlaying = false;
   let playbackRate = 1;
+  let currentTime = 0;
   return {
     getTimeline: vi.fn(() => timeline ?? null),
     setTimeline: vi.fn(),
@@ -43,6 +44,10 @@ function createMockDeps(timeline?: RuntimeTimelineLike | null) {
       playbackRate = v;
     }),
     getCanonicalFps: vi.fn(() => 30),
+    getCurrentTime: vi.fn(() => currentTime),
+    setCurrentTime: (v: number) => {
+      currentTime = v;
+    },
     onSyncMedia: vi.fn(),
     onStatePost: vi.fn(),
     onDeterministicSeek: vi.fn(),
@@ -129,11 +134,14 @@ function createNestedTimelineHarness() {
 
 describe("createRuntimePlayer", () => {
   describe("play", () => {
-    it("does nothing without a timeline", () => {
+    it("starts adapter-driven playback without a timeline", () => {
       const deps = createMockDeps(null);
       const player = createRuntimePlayer(deps);
       player.play();
-      expect(deps.setIsPlaying).not.toHaveBeenCalled();
+      expect(deps.setIsPlaying).toHaveBeenCalledWith(true);
+      expect(deps.onDeterministicPlay).toHaveBeenCalled();
+      expect(deps.onShowNativeVideos).toHaveBeenCalled();
+      expect(deps.onStatePost).toHaveBeenCalledWith(true);
     });
 
     it("does nothing if already playing", () => {
@@ -178,11 +186,15 @@ describe("createRuntimePlayer", () => {
   });
 
   describe("pause", () => {
-    it("does nothing without a timeline", () => {
+    it("pauses adapter-driven playback without a timeline", () => {
       const deps = createMockDeps(null);
+      deps.getCurrentTime = vi.fn(() => 2);
       const player = createRuntimePlayer(deps);
       player.pause();
-      expect(deps.setIsPlaying).not.toHaveBeenCalled();
+      expect(deps.onDeterministicSeek).toHaveBeenCalledWith(2);
+      expect(deps.onDeterministicPause).toHaveBeenCalled();
+      expect(deps.setIsPlaying).toHaveBeenCalledWith(false);
+      expect(deps.onSyncMedia).toHaveBeenCalledWith(2, false);
     });
 
     it("pauses the timeline and syncs media", () => {
@@ -301,11 +313,13 @@ describe("createRuntimePlayer", () => {
   });
 
   describe("seek", () => {
-    it("does nothing without a timeline", () => {
+    it("seeks adapter-driven playback without a timeline", () => {
       const deps = createMockDeps(null);
       const player = createRuntimePlayer(deps);
       player.seek(5);
-      expect(deps.onDeterministicSeek).not.toHaveBeenCalled();
+      expect(deps.onDeterministicSeek).toHaveBeenCalledWith(5);
+      expect(deps.setIsPlaying).toHaveBeenCalledWith(false);
+      expect(deps.onSyncMedia).toHaveBeenCalledWith(5, false);
     });
 
     it("seeks to quantized time and pauses", () => {
@@ -418,16 +432,17 @@ describe("createRuntimePlayer", () => {
       expect(player.getDuration()).toBe(30);
     });
 
-    it("getTime returns 0 without timeline", () => {
+    it("getTime returns adapter-driven current time without timeline", () => {
       const deps = createMockDeps(null);
+      deps.getCurrentTime = vi.fn(() => 4.5);
       const player = createRuntimePlayer(deps);
-      expect(player.getTime()).toBe(0);
+      expect(player.getTime()).toBe(4.5);
     });
 
-    it("getDuration returns 0 without timeline", () => {
+    it("getDuration returns safe duration without timeline", () => {
       const deps = createMockDeps(null);
       const player = createRuntimePlayer(deps);
-      expect(player.getDuration()).toBe(0);
+      expect(player.getDuration()).toBe(10);
     });
 
     it("isPlaying delegates to deps", () => {
diff --git a/packages/core/src/runtime/player.ts b/packages/core/src/runtime/player.ts
index d14776b0f..81b77bbe5 100644
--- a/packages/core/src/runtime/player.ts
+++ b/packages/core/src/runtime/player.ts
@@ -9,6 +9,7 @@ type PlayerDeps = {
   getPlaybackRate: () => number;
   setPlaybackRate: (rate: number) => void;
   getCanonicalFps: () => number;
+  getCurrentTime?: () => number;
   onSyncMedia: (timeSeconds: number, playing: boolean) => void;
   onStatePost: (force: boolean) => void;
   onDeterministicSeek: (timeSeconds: number) => void;
@@ -97,7 +98,22 @@ export function createRuntimePlayer(deps: PlayerDeps): RuntimePlayer {
     _timeline: null,
     play: () => {
       const timeline = deps.getTimeline();
-      if (!timeline || deps.getIsPlaying()) return;
+      if (deps.getIsPlaying()) return;
+      if (!timeline) {
+        const safeDuration = Math.max(0, Number(deps.getSafeDuration?.() ?? 0) || 0);
+        const currentTime = Math.max(0, Number(deps.getCurrentTime?.() ?? 0) || 0);
+        if (safeDuration > 0 && currentTime >= safeDuration) {
+          deps.onDeterministicSeek(0);
+          deps.setIsPlaying(false);
+          deps.onSyncMedia(0, false);
+          deps.onRenderFrameSeek(0);
+        }
+        deps.onDeterministicPlay();
+        deps.setIsPlaying(true);
+        deps.onShowNativeVideos();
+        deps.onStatePost(true);
+        return;
+      }
       const safeDuration = Math.max(
         0,
         Number(deps.getSafeDuration?.() ?? timeline.duration() ?? 0) || 0,
@@ -128,7 +144,16 @@ export function createRuntimePlayer(deps: PlayerDeps): RuntimePlayer {
     },
     pause: () => {
       const timeline = deps.getTimeline();
-      if (!timeline) return;
+      if (!timeline) {
+        const time = Math.max(0, Number(deps.getCurrentTime?.() ?? 0) || 0);
+        deps.onDeterministicSeek(time);
+        deps.onDeterministicPause();
+        deps.setIsPlaying(false);
+        deps.onSyncMedia(time, false);
+        deps.onRenderFrameSeek(time);
+        deps.onStatePost(true);
+        return;
+      }
       timeline.pause();
       forEachSiblingTimeline(deps.getTimelineRegistry?.(), timeline, (tl) => {
         tl.pause();
@@ -143,8 +168,16 @@ export function createRuntimePlayer(deps: PlayerDeps): RuntimePlayer {
     },
     seek: (timeSeconds: number) => {
       const timeline = deps.getTimeline();
-      if (!timeline) return;
       const safeTime = Math.max(0, Number(timeSeconds) || 0);
+      if (!timeline) {
+        const quantized = quantizeTimeToFrame(safeTime, deps.getCanonicalFps());
+        deps.onDeterministicSeek(quantized);
+        deps.setIsPlaying(false);
+        deps.onSyncMedia(quantized, false);
+        deps.onRenderFrameSeek(quantized);
+        deps.onStatePost(true);
+        return;
+      }
       const quantized = seekMasterAndSiblingTimelinesDeterministically(
         deps.getTimelineRegistry?.(),
         timeline,
@@ -179,8 +212,8 @@ export function createRuntimePlayer(deps: PlayerDeps): RuntimePlayer {
       deps.onRenderFrameSeek(quantized);
       deps.onStatePost(true);
     },
-    getTime: () => Number(deps.getTimeline()?.time() ?? 0),
-    getDuration: () => Number(deps.getTimeline()?.duration() ?? 0),
+    getTime: () => Number(deps.getTimeline()?.time() ?? deps.getCurrentTime?.() ?? 0),
+    getDuration: () => Number(deps.getTimeline()?.duration() ?? deps.getSafeDuration?.() ?? 0),
     isPlaying: () => deps.getIsPlaying(),
     setPlaybackRate: (rate: number) => deps.setPlaybackRate(rate),
     getPlaybackRate: () => deps.getPlaybackRate(),
diff --git a/packages/core/src/studio-api/createStudioApi.ts b/packages/core/src/studio-api/createStudioApi.ts
index a7a94bb62..a579be518 100644
--- a/packages/core/src/studio-api/createStudioApi.ts
+++ b/packages/core/src/studio-api/createStudioApi.ts
@@ -7,6 +7,9 @@ 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";
+import { registerHistoryRoutes } from "./routes/history.js";
+import { createStudioEventBus } from "./events.js";
 
 /**
  * Create a Hono sub-app with all studio API routes.
@@ -16,14 +19,17 @@ import { registerWaveformRoutes } from "./routes/waveform.js";
  */
 export function createStudioApi(adapter: StudioApiAdapter): Hono {
   const api = new Hono();
+  const events = createStudioEventBus();
 
   registerProjectRoutes(api, adapter);
   registerFileRoutes(api, adapter);
+  registerHistoryRoutes(api, adapter, events);
   registerPreviewRoutes(api, adapter);
   registerLintRoutes(api, adapter);
   registerRenderRoutes(api, adapter);
   registerThumbnailRoutes(api, adapter);
   registerWaveformRoutes(api, adapter);
+  registerFontRoutes(api);
 
   return api;
 }
diff --git a/packages/core/src/studio-api/events.ts b/packages/core/src/studio-api/events.ts
new file mode 100644
index 000000000..c8d052c4c
--- /dev/null
+++ b/packages/core/src/studio-api/events.ts
@@ -0,0 +1,62 @@
+import type {
+  EditHistoryActor,
+  EditHistoryKind,
+  ProjectHistorySummary,
+} from "./history/editHistory.js";
+
+export type StudioProjectEvent =
+  | {
+      type: "project-edit";
+      projectId: string;
+      entryId: string;
+      label: string;
+      kind: EditHistoryKind;
+      actor?: EditHistoryActor;
+      changedPaths: string[];
+      unmanagedPaths?: string[];
+      history: ProjectHistorySummary;
+    }
+  | {
+      type: "history-updated";
+      projectId: string;
+      changedPaths: string[];
+      unmanagedPaths?: string[];
+      history: ProjectHistorySummary;
+    }
+  | {
+      type: "file-change";
+      projectId: string;
+      changedPaths: string[];
+      unmanagedPaths?: string[];
+      source: "studio" | "agent" | "external";
+    };
+
+export type StudioProjectEventListener = (event: StudioProjectEvent) => void;
+
+export interface StudioEventBus {
+  publish(event: StudioProjectEvent): void;
+  subscribe(projectId: string, listener: StudioProjectEventListener): () => void;
+}
+
+export function createStudioEventBus(): StudioEventBus {
+  const listeners = new Map<string, Set<StudioProjectEventListener>>();
+
+  return {
+    publish(event) {
+      const projectListeners = listeners.get(event.projectId);
+      if (!projectListeners) return;
+      for (const listener of projectListeners) {
+        listener(event);
+      }
+    },
+    subscribe(projectId, listener) {
+      const projectListeners = listeners.get(projectId) ?? new Set<StudioProjectEventListener>();
+      projectListeners.add(listener);
+      listeners.set(projectId, projectListeners);
+      return () => {
+        projectListeners.delete(listener);
+        if (projectListeners.size === 0) listeners.delete(projectId);
+      };
+    },
+  };
+}
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": `<template id="hero-template">
   <div data-composition-id="hero" data-width="1920" data-height="1080">
     <img src="../logo.png" alt="Logo" />
+    <div style="background-image: url('../poster.png')"></div>
     <style>
       @font-face {
         font-family: "Brand Sans";
@@ -42,8 +43,10 @@ describe("buildSubCompositionHtml", () => {
 
     expect(html).toContain('<base href="/api/projects/demo/preview/">');
     expect(html).toContain('src="logo.png"');
+    expect(html).toContain("background-image: url('poster.png')");
     expect(html).toContain('url("fonts/brand.woff2")');
     expect(html).not.toContain('src="../logo.png"');
+    expect(html).not.toContain("url('../poster.png')");
     expect(html).not.toContain('url("../fonts/brand.woff2")');
   });
 });
diff --git a/packages/core/src/studio-api/helpers/subComposition.ts b/packages/core/src/studio-api/helpers/subComposition.ts
index 5fb7cb574..859779a3d 100644
--- a/packages/core/src/studio-api/helpers/subComposition.ts
+++ b/packages/core/src/studio-api/helpers/subComposition.ts
@@ -1,7 +1,11 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parseHTML } from "linkedom";
-import { rewriteAssetPaths, rewriteCssAssetUrls } from "../../compiler/rewriteSubCompPaths.js";
+import {
+  rewriteAssetPaths,
+  rewriteCssAssetUrls,
+  rewriteInlineStyleAssetUrls,
+} from "../../compiler/rewriteSubCompPaths.js";
 
 /**
  * Build a standalone HTML page for a sub-composition.
@@ -36,6 +40,14 @@ export function buildSubCompositionHtml(
       el.setAttribute(attr, value);
     },
   );
+  rewriteInlineStyleAssetUrls(
+    contentDoc.querySelectorAll("[style]"),
+    compPath,
+    (el: Element) => el.getAttribute("style"),
+    (el: Element, value: string) => {
+      el.setAttribute("style", value);
+    },
+  );
   for (const styleEl of contentDoc.querySelectorAll("style")) {
     styleEl.textContent = rewriteCssAssetUrls(styleEl.textContent || "", compPath);
   }
diff --git a/packages/core/src/studio-api/history/editHistory.test.ts b/packages/core/src/studio-api/history/editHistory.test.ts
new file mode 100644
index 000000000..acbaeccd4
--- /dev/null
+++ b/packages/core/src/studio-api/history/editHistory.test.ts
@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildEditHistoryEntry,
+  canApplyEditHistoryEntry,
+  createEmptyEditHistory,
+  hashEditHistoryContent,
+  pushEditHistoryEntry,
+  redoEditHistory,
+  undoEditHistory,
+} from "./editHistory.js";
+
+describe("shared edit history", () => {
+  it("records actor metadata and changed file snapshots", () => {
+    const entry = buildEditHistoryEntry({
+      id: "entry-1",
+      projectId: "project-1",
+      label: "Agent edit",
+      kind: "agent",
+      actor: { type: "agent", id: "codex", label: "Codex" },
+      now: 100,
+      files: {
+        "index.html": { before: "before", after: "after" },
+        "same.html": { before: "same", after: "same" },
+      },
+    });
+
+    const state = pushEditHistoryEntry(createEmptyEditHistory(), entry);
+
+    expect(state.undo).toHaveLength(1);
+    expect(state.undo[0].actor).toEqual({ type: "agent", id: "codex", label: "Codex" });
+    expect(Object.keys(state.undo[0].files)).toEqual(["index.html"]);
+    expect(state.undo[0].files["index.html"].beforeHash).toBe(hashEditHistoryContent("before"));
+    expect(state.undo[0].files["index.html"].afterHash).toBe(hashEditHistoryContent("after"));
+  });
+
+  it("moves entries through undo and redo with content-hash checks", () => {
+    const entry = buildEditHistoryEntry({
+      id: "entry-1",
+      projectId: "project-1",
+      label: "Move layer",
+      now: 100,
+      files: {
+        "index.html": { before: "before", after: "after" },
+      },
+    });
+    const state = pushEditHistoryEntry(createEmptyEditHistory(), entry);
+
+    const undo = undoEditHistory(state, { "index.html": hashEditHistoryContent("after") }, 200);
+    expect(undo.ok).toBe(true);
+    expect(undo.filesToWrite).toEqual({ "index.html": "before" });
+
+    const redo = redoEditHistory(
+      undo.state,
+      { "index.html": hashEditHistoryContent("before") },
+      300,
+    );
+    expect(redo.ok).toBe(true);
+    expect(redo.filesToWrite).toEqual({ "index.html": "after" });
+  });
+
+  it("rejects history application when any current hash does not match", () => {
+    const entry = buildEditHistoryEntry({
+      id: "entry-1",
+      projectId: "project-1",
+      label: "Update files",
+      now: 100,
+      files: {
+        "index.html": { before: "a", after: "b" },
+        "scene.html": { before: "c", after: "d" },
+      },
+    });
+
+    expect(
+      canApplyEditHistoryEntry(entry, "undo", {
+        "index.html": hashEditHistoryContent("b"),
+        "scene.html": hashEditHistoryContent("external"),
+      }),
+    ).toEqual({ ok: false, reason: "content-mismatch", path: "scene.html" });
+  });
+
+  it("coalesces matching edit groups inside the coalesce window", () => {
+    const first = buildEditHistoryEntry({
+      id: "entry-1",
+      projectId: "project-1",
+      label: "Edit source",
+      kind: "source",
+      coalesceKey: "source:index.html",
+      now: 100,
+      files: {
+        "index.html": { before: "a", after: "b" },
+      },
+    });
+    const second = buildEditHistoryEntry({
+      id: "entry-2",
+      projectId: "project-1",
+      label: "Edit source",
+      kind: "source",
+      coalesceKey: "source:index.html",
+      now: 300,
+      files: {
+        "index.html": { before: "b", after: "c" },
+      },
+    });
+
+    const state = pushEditHistoryEntry(
+      pushEditHistoryEntry(createEmptyEditHistory(), first),
+      second,
+      { coalesceMs: 1000 },
+    );
+
+    expect(state.undo).toHaveLength(1);
+    expect(state.undo[0].id).toBe("entry-2");
+    expect(state.undo[0].files["index.html"].before).toBe("a");
+    expect(state.undo[0].files["index.html"].after).toBe("c");
+  });
+});
diff --git a/packages/core/src/studio-api/history/editHistory.ts b/packages/core/src/studio-api/history/editHistory.ts
new file mode 100644
index 000000000..521d501e4
--- /dev/null
+++ b/packages/core/src/studio-api/history/editHistory.ts
@@ -0,0 +1,258 @@
+export type EditHistoryKind = "manual" | "timeline" | "source" | "motion" | "agent";
+
+export interface EditHistoryActor {
+  type: "user" | "agent" | "system" | "external";
+  id?: string;
+  label?: string;
+}
+
+export interface EditHistoryFileSnapshot {
+  before: string;
+  after: string;
+  beforeHash: string;
+  afterHash: string;
+}
+
+export interface EditHistoryEntry {
+  id: string;
+  projectId: string;
+  label: string;
+  kind: EditHistoryKind;
+  actor?: EditHistoryActor;
+  coalesceKey?: string;
+  createdAt: number;
+  files: Record<string, EditHistoryFileSnapshot>;
+}
+
+export interface EditHistoryState {
+  version: 1;
+  updatedAt: number;
+  undo: EditHistoryEntry[];
+  redo: EditHistoryEntry[];
+}
+
+export interface EditHistoryOptions {
+  maxEntries?: number;
+  coalesceMs?: number;
+}
+
+export interface BuildEditHistoryEntryInput {
+  id: string;
+  projectId: string;
+  label: string;
+  kind?: EditHistoryKind;
+  actor?: EditHistoryActor;
+  coalesceKey?: string;
+  now: number;
+  files: Record<string, { before: string; after: string }>;
+}
+
+export type EditHistoryDirection = "undo" | "redo";
+
+export type EditHistoryApplyCheck =
+  | { ok: true }
+  | { ok: false; reason: "content-mismatch"; path: string };
+
+export type EditHistoryTransitionResult =
+  | {
+      ok: true;
+      state: EditHistoryState;
+      entry: EditHistoryEntry;
+      filesToWrite: Record<string, string>;
+    }
+  | {
+      ok: false;
+      reason: "empty" | "content-mismatch";
+      state: EditHistoryState;
+      filesToWrite: Record<string, string>;
+      path?: string;
+    };
+
+const DEFAULT_MAX_ENTRIES = 100;
+const DEFAULT_COALESCE_MS = 1500;
+
+export function hashEditHistoryContent(content: string): string {
+  let hash = 2166136261;
+  for (let index = 0; index < content.length; index += 1) {
+    hash ^= content.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+export function createEmptyEditHistory(_options?: EditHistoryOptions): EditHistoryState {
+  return {
+    version: 1,
+    updatedAt: 0,
+    undo: [],
+    redo: [],
+  };
+}
+
+export function buildEditHistoryEntry(input: BuildEditHistoryEntryInput): EditHistoryEntry {
+  const files: Record<string, EditHistoryFileSnapshot> = {};
+  for (const [path, snapshot] of Object.entries(input.files)) {
+    if (snapshot.before === snapshot.after) continue;
+    files[path] = {
+      before: snapshot.before,
+      after: snapshot.after,
+      beforeHash: hashEditHistoryContent(snapshot.before),
+      afterHash: hashEditHistoryContent(snapshot.after),
+    };
+  }
+
+  return {
+    id: input.id,
+    projectId: input.projectId,
+    label: input.label,
+    kind: input.kind ?? "manual",
+    actor: input.actor,
+    coalesceKey: input.coalesceKey,
+    createdAt: input.now,
+    files,
+  };
+}
+
+export function pushEditHistoryEntry(
+  state: EditHistoryState,
+  entry: EditHistoryEntry,
+  options?: EditHistoryOptions,
+): EditHistoryState {
+  if (Object.keys(entry.files).length === 0) return state;
+
+  const coalesceMs = options?.coalesceMs ?? DEFAULT_COALESCE_MS;
+  const maxEntries = options?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  const previous = state.undo[state.undo.length - 1];
+  let undo = state.undo;
+
+  if (
+    previous &&
+    previous.coalesceKey &&
+    previous.coalesceKey === entry.coalesceKey &&
+    entry.createdAt - previous.createdAt <= coalesceMs
+  ) {
+    const files: Record<string, EditHistoryFileSnapshot> = {};
+    for (const [path, snapshot] of Object.entries(entry.files)) {
+      const previousSnapshot = previous.files[path];
+      files[path] = previousSnapshot
+        ? {
+            before: previousSnapshot.before,
+            after: snapshot.after,
+            beforeHash: previousSnapshot.beforeHash,
+            afterHash: snapshot.afterHash,
+          }
+        : snapshot;
+    }
+    undo = [...state.undo.slice(0, -1), { ...entry, files }];
+  } else {
+    undo = [...state.undo, entry];
+  }
+
+  return {
+    version: 1,
+    updatedAt: entry.createdAt,
+    undo: undo.slice(Math.max(0, undo.length - maxEntries)),
+    redo: [],
+  };
+}
+
+export function canApplyEditHistoryEntry(
+  entry: EditHistoryEntry,
+  direction: EditHistoryDirection,
+  currentHashes: Record<string, string>,
+): EditHistoryApplyCheck {
+  for (const [path, snapshot] of Object.entries(entry.files)) {
+    const expected = direction === "undo" ? snapshot.afterHash : snapshot.beforeHash;
+    if (currentHashes[path] !== expected) {
+      return { ok: false, reason: "content-mismatch", path };
+    }
+  }
+  return { ok: true };
+}
+
+export function undoEditHistory(
+  state: EditHistoryState,
+  currentHashes: Record<string, string>,
+  now: number,
+): EditHistoryTransitionResult {
+  const entry = state.undo[state.undo.length - 1];
+  if (!entry) return { ok: false, reason: "empty", state, filesToWrite: {} };
+
+  const check = canApplyEditHistoryEntry(entry, "undo", currentHashes);
+  if (!check.ok) {
+    return { ok: false, reason: check.reason, path: check.path, state, filesToWrite: {} };
+  }
+
+  return {
+    ok: true,
+    entry,
+    filesToWrite: Object.fromEntries(
+      Object.entries(entry.files).map(([path, snapshot]) => [path, snapshot.before]),
+    ),
+    state: {
+      version: 1,
+      updatedAt: now,
+      undo: state.undo.slice(0, -1),
+      redo: [...state.redo, entry],
+    },
+  };
+}
+
+export function redoEditHistory(
+  state: EditHistoryState,
+  currentHashes: Record<string, string>,
+  now: number,
+): EditHistoryTransitionResult {
+  const entry = state.redo[state.redo.length - 1];
+  if (!entry) return { ok: false, reason: "empty", state, filesToWrite: {} };
+
+  const check = canApplyEditHistoryEntry(entry, "redo", currentHashes);
+  if (!check.ok) {
+    return { ok: false, reason: check.reason, path: check.path, state, filesToWrite: {} };
+  }
+
+  return {
+    ok: true,
+    entry,
+    filesToWrite: Object.fromEntries(
+      Object.entries(entry.files).map(([path, snapshot]) => [path, snapshot.after]),
+    ),
+    state: {
+      version: 1,
+      updatedAt: now,
+      undo: [...state.undo, entry],
+      redo: state.redo.slice(0, -1),
+    },
+  };
+}
+
+export interface ProjectHistorySummary {
+  projectId: string;
+  canUndo: boolean;
+  canRedo: boolean;
+  undoLabel?: string;
+  redoLabel?: string;
+  updatedAt: number;
+  revision: number;
+}
+
+export interface ProjectEditRequest {
+  label: string;
+  kind: EditHistoryKind;
+  actor?: EditHistoryActor;
+  coalesceKey?: string;
+  files: Record<
+    string,
+    {
+      after: string;
+      beforeHash?: string;
+    }
+  >;
+}
+
+export interface ProjectEditResult {
+  ok: true;
+  entryId: string;
+  changedPaths: string[];
+  history: ProjectHistorySummary;
+}
diff --git a/packages/core/src/studio-api/history/projectHistoryStore.test.ts b/packages/core/src/studio-api/history/projectHistoryStore.test.ts
new file mode 100644
index 000000000..7e131a733
--- /dev/null
+++ b/packages/core/src/studio-api/history/projectHistoryStore.test.ts
@@ -0,0 +1,155 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import type { ResolvedProject } from "../types.js";
+import { hashEditHistoryContent } from "./editHistory.js";
+import {
+  adoptExternalProjectChanges,
+  applyProjectHistoryTransition,
+  ProjectHistoryError,
+  readProjectHistorySnapshot,
+  recordAppliedProjectEdit,
+  recordProjectEdit,
+} from "./projectHistoryStore.js";
+import { primeProjectSnapshotCache } from "./projectSnapshotCache.js";
+
+const cleanupDirs: string[] = [];
+
+function createProject(): ResolvedProject {
+  const dir = mkdtempSync(join(tmpdir(), "hf-history-"));
+  cleanupDirs.push(dir);
+  return { id: "project-1", dir, title: "Project 1" };
+}
+
+afterEach(() => {
+  for (const dir of cleanupDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("project history store", () => {
+  it("records a transaction edit and applies undo/redo", async () => {
+    const project = createProject();
+    writeFileSync(join(project.dir, "index.html"), "before", "utf-8");
+
+    const result = await recordProjectEdit(project, {
+      label: "Agent edit",
+      kind: "agent",
+      actor: { type: "agent", id: "codex" },
+      files: {
+        "index.html": {
+          beforeHash: hashEditHistoryContent("before"),
+          after: "after",
+        },
+      },
+    });
+
+    expect(result.changedPaths).toEqual(["index.html"]);
+    expect(readFileSync(join(project.dir, "index.html"), "utf-8")).toBe("after");
+    expect((await readProjectHistorySnapshot(project)).canUndo).toBe(true);
+
+    const undo = await applyProjectHistoryTransition(project, "undo");
+    expect(undo.ok).toBe(true);
+    expect(readFileSync(join(project.dir, "index.html"), "utf-8")).toBe("before");
+
+    const redo = await applyProjectHistoryTransition(project, "redo");
+    expect(redo.ok).toBe(true);
+    expect(readFileSync(join(project.dir, "index.html"), "utf-8")).toBe("after");
+  });
+
+  it("rejects stale before hashes", async () => {
+    const project = createProject();
+    writeFileSync(join(project.dir, "index.html"), "current", "utf-8");
+
+    await expect(
+      recordProjectEdit(project, {
+        label: "Agent edit",
+        kind: "agent",
+        files: {
+          "index.html": {
+            beforeHash: hashEditHistoryContent("stale"),
+            after: "after",
+          },
+        },
+      }),
+    ).rejects.toMatchObject({
+      code: "content-mismatch",
+      path: "index.html",
+    } satisfies Partial<ProjectHistoryError>);
+  });
+
+  it("records already-applied Studio edits without writing files again", async () => {
+    const project = createProject();
+    writeFileSync(join(project.dir, "index.html"), "after", "utf-8");
+
+    const result = await recordAppliedProjectEdit(project, {
+      label: "Move layer",
+      kind: "manual",
+      files: {
+        "index.html": { before: "before", after: "after" },
+      },
+    });
+
+    expect(result.changedPaths).toEqual(["index.html"]);
+    expect((await readProjectHistorySnapshot(project)).undoLabel).toBe("Move layer");
+  });
+
+  it("adopts free-form external edits when a previous snapshot is cached", async () => {
+    const project = createProject();
+    writeFileSync(join(project.dir, "index.html"), "before", "utf-8");
+    primeProjectSnapshotCache(project);
+    writeFileSync(join(project.dir, "index.html"), "after", "utf-8");
+
+    const result = await adoptExternalProjectChanges(project, {
+      paths: ["index.html"],
+      actor: { type: "agent", id: "codex" },
+    });
+
+    expect(result.changedPaths).toEqual(["index.html"]);
+    expect(result.unmanagedPaths).toEqual([]);
+    expect((await readProjectHistorySnapshot(project)).undoLabel).toBe("Agent edit");
+  });
+
+  it("does not create undo history when previous content is missing", async () => {
+    const project = createProject();
+    writeFileSync(join(project.dir, "index.html"), "after", "utf-8");
+
+    const result = await adoptExternalProjectChanges(project, {
+      paths: ["index.html"],
+      actor: { type: "external" },
+    });
+
+    expect(result.changedPaths).toEqual([]);
+    expect(result.unmanagedPaths).toEqual(["index.html"]);
+    expect((await readProjectHistorySnapshot(project)).canUndo).toBe(false);
+  });
+
+  it("does not adopt a server undo write as a new external edit", async () => {
+    const project = createProject();
+    writeFileSync(join(project.dir, "index.html"), "before", "utf-8");
+    primeProjectSnapshotCache(project);
+    await recordProjectEdit(project, {
+      label: "Agent edit",
+      kind: "agent",
+      files: {
+        "index.html": {
+          beforeHash: hashEditHistoryContent("before"),
+          after: "after",
+        },
+      },
+    });
+
+    const undo = await applyProjectHistoryTransition(project, "undo");
+    expect(undo.ok).toBe(true);
+    const adopted = await adoptExternalProjectChanges(project, {
+      paths: ["index.html"],
+      actor: { type: "external" },
+    });
+
+    expect(adopted.changedPaths).toEqual([]);
+    const summary = await readProjectHistorySnapshot(project);
+    expect(summary.canUndo).toBe(false);
+    expect(summary.canRedo).toBe(true);
+  });
+});
diff --git a/packages/core/src/studio-api/history/projectHistoryStore.ts b/packages/core/src/studio-api/history/projectHistoryStore.ts
new file mode 100644
index 000000000..2338b58c1
--- /dev/null
+++ b/packages/core/src/studio-api/history/projectHistoryStore.ts
@@ -0,0 +1,592 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import type { ResolvedProject } from "../types.js";
+import { isSafePath } from "../helpers/safePath.js";
+import {
+  buildEditHistoryEntry,
+  createEmptyEditHistory,
+  hashEditHistoryContent,
+  pushEditHistoryEntry,
+  redoEditHistory,
+  undoEditHistory,
+  type BuildEditHistoryEntryInput,
+  type EditHistoryActor,
+  type EditHistoryState,
+  type ProjectEditRequest,
+  type ProjectEditResult,
+  type ProjectHistorySummary,
+} from "./editHistory.js";
+import {
+  primeProjectSnapshotCache,
+  readCachedProjectChanges,
+  updateProjectSnapshotCache,
+} from "./projectSnapshotCache.js";
+
+interface PersistedProjectHistory {
+  version: 1;
+  revision: number;
+  state: EditHistoryState;
+}
+
+export interface ProjectHistoryStoreResult {
+  entryId?: string;
+  label?: string;
+  changedPaths: string[];
+  unmanagedPaths?: string[];
+  history: ProjectHistorySummary;
+}
+
+export type ProjectHistoryFailureReason = "empty" | "content-mismatch";
+
+export class ProjectHistoryError extends Error {
+  readonly code:
+    | "content-mismatch"
+    | "invalid-path"
+    | "not-found"
+    | "invalid-request"
+    | "write-failed";
+  readonly path?: string;
+  readonly expectedHash?: string;
+  readonly actualHash?: string;
+  readonly status: number;
+
+  constructor(
+    code: ProjectHistoryError["code"],
+    message: string,
+    options?: { path?: string; expectedHash?: string; actualHash?: string; status?: number },
+  ) {
+    super(message);
+    this.name = "ProjectHistoryError";
+    this.code = code;
+    this.path = options?.path;
+    this.expectedHash = options?.expectedHash;
+    this.actualHash = options?.actualHash;
+    this.status = options?.status ?? (code === "content-mismatch" ? 409 : 400);
+  }
+}
+
+const HISTORY_PATH = ".hyperframes/studio-history-v1.json";
+const projectQueues = new Map<string, Promise<void>>();
+const recentInternalWrites = new Map<string, number>();
+const INTERNAL_WRITE_SUPPRESSION_MS = 2000;
+
+function historyFilePath(project: ResolvedProject): string {
+  return resolve(project.dir, HISTORY_PATH);
+}
+
+function makeSummary(
+  projectId: string,
+  state: EditHistoryState,
+  revision: number,
+): ProjectHistorySummary {
+  const undoEntry = state.undo[state.undo.length - 1];
+  const redoEntry = state.redo[state.redo.length - 1];
+  return {
+    projectId,
+    canUndo: Boolean(undoEntry),
+    canRedo: Boolean(redoEntry),
+    undoLabel: undoEntry?.label,
+    redoLabel: redoEntry?.label,
+    updatedAt: state.updatedAt,
+    revision,
+  };
+}
+
+function readPersistedHistory(project: ResolvedProject): PersistedProjectHistory {
+  const filePath = historyFilePath(project);
+  if (!existsSync(filePath)) {
+    return { version: 1, revision: 0, state: createEmptyEditHistory() };
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      "version" in parsed &&
+      parsed.version === 1 &&
+      "revision" in parsed &&
+      typeof parsed.revision === "number" &&
+      "state" in parsed &&
+      typeof parsed.state === "object" &&
+      parsed.state !== null
+    ) {
+      const state = parsed.state as EditHistoryState;
+      if (state.version === 1 && Array.isArray(state.undo) && Array.isArray(state.redo)) {
+        return { version: 1, revision: parsed.revision, state };
+      }
+    }
+  } catch {
+    /* fall back to empty history */
+  }
+
+  return { version: 1, revision: 0, state: createEmptyEditHistory() };
+}
+
+function writePersistedHistory(project: ResolvedProject, history: PersistedProjectHistory): void {
+  const filePath = historyFilePath(project);
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tempPath, JSON.stringify(history, null, 2), "utf-8");
+  renameSync(tempPath, filePath);
+}
+
+function normalizeProjectPath(project: ResolvedProject, path: string): string {
+  if (!path || path.includes("\0")) {
+    throw new ProjectHistoryError("invalid-path", "Invalid project path", { path, status: 400 });
+  }
+  const absPath = resolve(project.dir, path);
+  if (!isSafePath(project.dir, absPath)) {
+    throw new ProjectHistoryError("invalid-path", "Project path escapes project directory", {
+      path,
+      status: 403,
+    });
+  }
+  const relativePath = path.split("\\").join("/");
+  if (relativePath === HISTORY_PATH || relativePath.startsWith(".hyperframes/")) {
+    throw new ProjectHistoryError("invalid-path", "Studio history files cannot be edited", {
+      path,
+      status: 403,
+    });
+  }
+  return relativePath;
+}
+
+function readExistingTextFile(project: ResolvedProject, path: string): string {
+  const absPath = resolve(project.dir, path);
+  if (!existsSync(absPath) || !statSync(absPath).isFile()) {
+    throw new ProjectHistoryError("not-found", "File not found", { path, status: 404 });
+  }
+  return readFileSync(absPath, "utf-8");
+}
+
+function writeTextFilesWithRollback(
+  project: ResolvedProject,
+  files: Record<string, string>,
+  rollbackFiles: Record<string, string>,
+): void {
+  const writtenPaths: string[] = [];
+  try {
+    for (const [path, content] of Object.entries(files)) {
+      const absPath = resolve(project.dir, path);
+      const dir = dirname(absPath);
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+      writeFileSync(absPath, content, "utf-8");
+      writtenPaths.push(path);
+    }
+  } catch (error) {
+    try {
+      for (const path of writtenPaths.reverse()) {
+        const rollback = rollbackFiles[path];
+        if (typeof rollback === "string") {
+          writeFileSync(resolve(project.dir, path), rollback, "utf-8");
+        }
+      }
+    } catch (rollbackError) {
+      throw new AggregateError(
+        [error, rollbackError],
+        "Failed to write project files and rollback did not complete",
+      );
+    }
+    throw new ProjectHistoryError("write-failed", "Failed to write project files", {
+      status: 500,
+    });
+  }
+}
+
+function createEntryId(): string {
+  return `edit-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+}
+
+function internalWriteKey(project: ResolvedProject, path: string): string {
+  return `${resolve(project.dir)}:${path}`;
+}
+
+function markInternalWrites(project: ResolvedProject, paths: string[]): void {
+  const now = Date.now();
+  for (const path of paths) {
+    recentInternalWrites.set(internalWriteKey(project, path), now);
+  }
+}
+
+function isRecentInternalWrite(project: ResolvedProject, path: string): boolean {
+  const key = internalWriteKey(project, path);
+  const timestamp = recentInternalWrites.get(key);
+  if (!timestamp) return false;
+  if (Date.now() - timestamp > INTERNAL_WRITE_SUPPRESSION_MS) {
+    recentInternalWrites.delete(key);
+    return false;
+  }
+  return true;
+}
+
+function entryMatchesSnapshots(
+  entry: { files: ReturnType<typeof buildEditHistoryEntry>["files"] },
+  snapshots: BuildEditHistoryEntryInput["files"],
+): boolean {
+  const entryPaths = Object.keys(entry.files).sort();
+  const snapshotPaths = Object.keys(snapshots).sort();
+  if (entryPaths.length !== snapshotPaths.length) return false;
+  for (let index = 0; index < entryPaths.length; index += 1) {
+    const path = entryPaths[index];
+    if (!path || path !== snapshotPaths[index]) return false;
+    const entrySnapshot = entry.files[path];
+    const snapshot = snapshots[path];
+    if (!entrySnapshot || !snapshot) return false;
+    if (
+      entrySnapshot.beforeHash !== hashEditHistoryContent(snapshot.before) ||
+      entrySnapshot.afterHash !== hashEditHistoryContent(snapshot.after)
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function entryInvertsSnapshots(
+  entry: { files: ReturnType<typeof buildEditHistoryEntry>["files"] },
+  snapshots: BuildEditHistoryEntryInput["files"],
+): boolean {
+  const entryPaths = Object.keys(entry.files).sort();
+  const snapshotPaths = Object.keys(snapshots).sort();
+  if (entryPaths.length !== snapshotPaths.length) return false;
+  for (let index = 0; index < entryPaths.length; index += 1) {
+    const path = entryPaths[index];
+    if (!path || path !== snapshotPaths[index]) return false;
+    const entrySnapshot = entry.files[path];
+    const snapshot = snapshots[path];
+    if (!entrySnapshot || !snapshot) return false;
+    if (
+      entrySnapshot.afterHash !== hashEditHistoryContent(snapshot.before) ||
+      entrySnapshot.beforeHash !== hashEditHistoryContent(snapshot.after)
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+async function withProjectQueue<T>(project: ResolvedProject, fn: () => T | Promise<T>): Promise<T> {
+  const key = resolve(project.dir);
+  const previous = projectQueues.get(key) ?? Promise.resolve();
+  let release: () => void = () => {};
+  const next = new Promise<void>((resolveQueue) => {
+    release = resolveQueue;
+  });
+  const chained = previous.then(
+    () => next,
+    () => next,
+  );
+  projectQueues.set(key, chained);
+
+  await previous.catch(() => {});
+  try {
+    return await fn();
+  } finally {
+    release();
+    if (projectQueues.get(key) === chained) projectQueues.delete(key);
+  }
+}
+
+export async function readProjectHistorySnapshot(
+  project: ResolvedProject,
+): Promise<ProjectHistorySummary> {
+  primeProjectSnapshotCache(project);
+  const history = readPersistedHistory(project);
+  return makeSummary(project.id, history.state, history.revision);
+}
+
+export async function recordProjectEdit(
+  project: ResolvedProject,
+  request: ProjectEditRequest,
+): Promise<ProjectEditResult> {
+  return withProjectQueue(project, () => {
+    const persisted = readPersistedHistory(project);
+    const snapshots: BuildEditHistoryEntryInput["files"] = {};
+    const rollbackFiles: Record<string, string> = {};
+
+    for (const [path, file] of Object.entries(request.files)) {
+      const relativePath = normalizeProjectPath(project, path);
+      const before = readExistingTextFile(project, relativePath);
+      const beforeHash = hashEditHistoryContent(before);
+      if (file.beforeHash && file.beforeHash !== beforeHash) {
+        throw new ProjectHistoryError("content-mismatch", "File changed before edit was applied", {
+          path: relativePath,
+          expectedHash: file.beforeHash,
+          actualHash: beforeHash,
+        });
+      }
+      if (before !== file.after) {
+        snapshots[relativePath] = { before, after: file.after };
+        rollbackFiles[relativePath] = before;
+      }
+    }
+
+    const changedPaths = Object.keys(snapshots);
+    const entryId = createEntryId();
+    if (changedPaths.length === 0) {
+      return {
+        ok: true,
+        entryId,
+        changedPaths,
+        history: makeSummary(project.id, persisted.state, persisted.revision),
+      };
+    }
+
+    writeTextFilesWithRollback(
+      project,
+      Object.fromEntries(
+        Object.entries(snapshots).map(([path, snapshot]) => [path, snapshot.after]),
+      ),
+      rollbackFiles,
+    );
+    markInternalWrites(project, changedPaths);
+
+    const entry = buildEditHistoryEntry({
+      id: entryId,
+      projectId: project.id,
+      label: request.label,
+      kind: request.kind,
+      actor: request.actor,
+      coalesceKey: request.coalesceKey,
+      now: Date.now(),
+      files: snapshots,
+    });
+    const state = pushEditHistoryEntry(persisted.state, entry);
+    const revision = persisted.revision + 1;
+    writePersistedHistory(project, { version: 1, revision, state });
+    updateProjectSnapshotCache(project, changedPaths);
+
+    return {
+      ok: true,
+      entryId,
+      changedPaths,
+      history: makeSummary(project.id, state, revision),
+    };
+  });
+}
+
+export async function recordAppliedProjectEdit(
+  project: ResolvedProject,
+  input: {
+    label: string;
+    kind: ProjectEditRequest["kind"];
+    actor?: EditHistoryActor;
+    coalesceKey?: string;
+    files: BuildEditHistoryEntryInput["files"];
+  },
+): Promise<ProjectHistoryStoreResult> {
+  return withProjectQueue(project, () => {
+    const persisted = readPersistedHistory(project);
+    const snapshots: BuildEditHistoryEntryInput["files"] = {};
+
+    for (const [path, snapshot] of Object.entries(input.files)) {
+      const relativePath = normalizeProjectPath(project, path);
+      const current = readExistingTextFile(project, relativePath);
+      const currentHash = hashEditHistoryContent(current);
+      const expectedHash = hashEditHistoryContent(snapshot.after);
+      if (currentHash !== expectedHash) {
+        throw new ProjectHistoryError("content-mismatch", "Applied file content does not match", {
+          path: relativePath,
+          expectedHash,
+          actualHash: currentHash,
+        });
+      }
+      if (snapshot.before !== snapshot.after) {
+        snapshots[relativePath] = snapshot;
+      }
+    }
+
+    const changedPaths = Object.keys(snapshots);
+    if (changedPaths.length === 0) {
+      return {
+        changedPaths,
+        history: makeSummary(project.id, persisted.state, persisted.revision),
+      };
+    }
+
+    const latestEntry = persisted.state.undo[persisted.state.undo.length - 1];
+    if (latestEntry && entryMatchesSnapshots(latestEntry, snapshots)) {
+      updateProjectSnapshotCache(project, changedPaths);
+      return {
+        entryId: latestEntry.id,
+        label: latestEntry.label,
+        changedPaths: [],
+        history: makeSummary(project.id, persisted.state, persisted.revision),
+      };
+    }
+
+    const entryId = createEntryId();
+    const entry = buildEditHistoryEntry({
+      id: entryId,
+      projectId: project.id,
+      label: input.label,
+      kind: input.kind,
+      actor: input.actor,
+      coalesceKey: input.coalesceKey,
+      now: Date.now(),
+      files: snapshots,
+    });
+    const state = pushEditHistoryEntry(persisted.state, entry);
+    const revision = persisted.revision + 1;
+    writePersistedHistory(project, { version: 1, revision, state });
+    updateProjectSnapshotCache(project, changedPaths);
+    return {
+      entryId,
+      label: input.label,
+      changedPaths,
+      history: makeSummary(project.id, state, revision),
+    };
+  });
+}
+
+export async function applyProjectHistoryTransition(
+  project: ResolvedProject,
+  direction: "undo" | "redo",
+): Promise<
+  | (ProjectHistoryStoreResult & { ok: true })
+  | {
+      ok: false;
+      reason: ProjectHistoryFailureReason;
+      path?: string;
+      history: ProjectHistorySummary;
+    }
+> {
+  return withProjectQueue(project, () => {
+    const persisted = readPersistedHistory(project);
+    const entry =
+      direction === "undo"
+        ? persisted.state.undo[persisted.state.undo.length - 1]
+        : persisted.state.redo[persisted.state.redo.length - 1];
+    if (!entry) {
+      return {
+        ok: false,
+        reason: "empty",
+        history: makeSummary(project.id, persisted.state, persisted.revision),
+      };
+    }
+
+    const currentFiles: Record<string, string> = {};
+    const currentHashes: Record<string, string> = {};
+    for (const path of Object.keys(entry.files)) {
+      const current = readExistingTextFile(project, normalizeProjectPath(project, path));
+      currentFiles[path] = current;
+      currentHashes[path] = hashEditHistoryContent(current);
+    }
+
+    const result =
+      direction === "undo"
+        ? undoEditHistory(persisted.state, currentHashes, Date.now())
+        : redoEditHistory(persisted.state, currentHashes, Date.now());
+    if (!result.ok) {
+      return {
+        ok: false,
+        reason: result.reason,
+        path: result.path,
+        history: makeSummary(project.id, persisted.state, persisted.revision),
+      };
+    }
+
+    writeTextFilesWithRollback(project, result.filesToWrite, currentFiles);
+    const revision = persisted.revision + 1;
+    writePersistedHistory(project, { version: 1, revision, state: result.state });
+    const changedPaths = Object.keys(result.filesToWrite);
+    markInternalWrites(project, changedPaths);
+    updateProjectSnapshotCache(project, changedPaths);
+
+    return {
+      ok: true,
+      entryId: result.entry.id,
+      label: result.entry.label,
+      changedPaths,
+      history: makeSummary(project.id, result.state, revision),
+    };
+  });
+}
+
+export async function adoptExternalProjectChanges(
+  project: ResolvedProject,
+  input: { paths: string[]; label?: string; actor?: EditHistoryActor },
+): Promise<ProjectHistoryStoreResult> {
+  return withProjectQueue(project, () => {
+    const persisted = readPersistedHistory(project);
+    const normalizedPaths = input.paths.map((path) => normalizeProjectPath(project, path));
+    const suppressedPaths = normalizedPaths.filter((path) => isRecentInternalWrite(project, path));
+    if (suppressedPaths.length > 0) updateProjectSnapshotCache(project, suppressedPaths);
+    const { changes, unmanagedPaths } = readCachedProjectChanges(project, normalizedPaths);
+    const snapshots: BuildEditHistoryEntryInput["files"] = {};
+    for (const change of changes) {
+      snapshots[change.path] = { before: change.before, after: change.after };
+    }
+
+    const changedPaths = Object.keys(snapshots);
+    if (changedPaths.length === 0) {
+      updateProjectSnapshotCache(project, unmanagedPaths);
+      return {
+        changedPaths,
+        unmanagedPaths,
+        history: makeSummary(project.id, persisted.state, persisted.revision),
+      };
+    }
+
+    const latestEntry = persisted.state.undo[persisted.state.undo.length - 1];
+    if (latestEntry && entryMatchesSnapshots(latestEntry, snapshots)) {
+      updateProjectSnapshotCache(project, [...changedPaths, ...unmanagedPaths]);
+      return {
+        entryId: latestEntry.id,
+        label: latestEntry.label,
+        changedPaths: [],
+        unmanagedPaths,
+        history: makeSummary(project.id, persisted.state, persisted.revision),
+      };
+    }
+    if (latestEntry && entryInvertsSnapshots(latestEntry, snapshots)) {
+      updateProjectSnapshotCache(project, [...changedPaths, ...unmanagedPaths]);
+      return {
+        entryId: latestEntry.id,
+        label: latestEntry.label,
+        changedPaths: [],
+        unmanagedPaths,
+        history: makeSummary(project.id, persisted.state, persisted.revision),
+      };
+    }
+    const redoEntry = persisted.state.redo[persisted.state.redo.length - 1];
+    if (redoEntry && entryInvertsSnapshots(redoEntry, snapshots)) {
+      updateProjectSnapshotCache(project, [...changedPaths, ...unmanagedPaths]);
+      return {
+        entryId: redoEntry.id,
+        label: redoEntry.label,
+        changedPaths: [],
+        unmanagedPaths,
+        history: makeSummary(project.id, persisted.state, persisted.revision),
+      };
+    }
+
+    const entryId = createEntryId();
+    const label = input.label ?? (input.actor?.type === "agent" ? "Agent edit" : "External edit");
+    const entry = buildEditHistoryEntry({
+      id: entryId,
+      projectId: project.id,
+      label,
+      kind: input.actor?.type === "agent" ? "agent" : "manual",
+      actor: input.actor,
+      coalesceKey: `external:${changedPaths.sort().join(",")}`,
+      now: Date.now(),
+      files: snapshots,
+    });
+    const state = pushEditHistoryEntry(persisted.state, entry, { coalesceMs: 500 });
+    const revision = persisted.revision + 1;
+    writePersistedHistory(project, { version: 1, revision, state });
+    updateProjectSnapshotCache(project, [...changedPaths, ...unmanagedPaths]);
+
+    return {
+      entryId,
+      label,
+      changedPaths,
+      unmanagedPaths,
+      history: makeSummary(project.id, state, revision),
+    };
+  });
+}
diff --git a/packages/core/src/studio-api/history/projectSnapshotCache.ts b/packages/core/src/studio-api/history/projectSnapshotCache.ts
new file mode 100644
index 000000000..470644e9f
--- /dev/null
+++ b/packages/core/src/studio-api/history/projectSnapshotCache.ts
@@ -0,0 +1,157 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import type { ResolvedProject } from "../types.js";
+import { isSafePath } from "../helpers/safePath.js";
+import { hashEditHistoryContent } from "./editHistory.js";
+
+export interface ProjectSnapshotCacheEntry {
+  content: string;
+  hash: string;
+  mtimeMs: number;
+  size: number;
+}
+
+export interface CachedProjectChange {
+  path: string;
+  before: string;
+  after: string;
+  beforeHash: string;
+  afterHash: string;
+}
+
+const TEXT_EXTENSIONS = new Set([
+  ".html",
+  ".css",
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".json",
+  ".md",
+  ".mdx",
+  ".svg",
+]);
+const IGNORED_DIRS = new Set([".git", ".hyperframes", ".thumbnails", "node_modules", "renders"]);
+const MAX_CACHED_BYTES = 2 * 1024 * 1024;
+
+const projectCaches = new Map<string, Map<string, ProjectSnapshotCacheEntry>>();
+
+function normalizeProjectPath(path: string): string {
+  return path.split(sep).join("/");
+}
+
+function getExtension(path: string): string {
+  const index = path.lastIndexOf(".");
+  return index === -1 ? "" : path.slice(index).toLowerCase();
+}
+
+function shouldCachePath(path: string): boolean {
+  if (!path || path.includes("\0")) return false;
+  const parts = path.split(/[\\/]/).filter(Boolean);
+  if (parts.some((part) => part === ".." || IGNORED_DIRS.has(part))) return false;
+  return TEXT_EXTENSIONS.has(getExtension(path));
+}
+
+function getProjectCache(project: ResolvedProject): Map<string, ProjectSnapshotCacheEntry> {
+  const key = resolve(project.dir);
+  const existing = projectCaches.get(key);
+  if (existing) return existing;
+  const cache = new Map<string, ProjectSnapshotCacheEntry>();
+  projectCaches.set(key, cache);
+  return cache;
+}
+
+function readCacheEntry(project: ResolvedProject, path: string): ProjectSnapshotCacheEntry | null {
+  if (!shouldCachePath(path)) return null;
+  const absPath = resolve(project.dir, path);
+  if (!isSafePath(project.dir, absPath) || !existsSync(absPath)) return null;
+  const stat = statSync(absPath);
+  if (!stat.isFile() || stat.size > MAX_CACHED_BYTES) return null;
+  const content = readFileSync(absPath, "utf-8");
+  return {
+    content,
+    hash: hashEditHistoryContent(content),
+    mtimeMs: stat.mtimeMs,
+    size: stat.size,
+  };
+}
+
+function walkCacheableFiles(projectDir: string, dir: string, paths: string[]): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (IGNORED_DIRS.has(entry.name)) continue;
+      walkCacheableFiles(projectDir, join(dir, entry.name), paths);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const relPath = normalizeProjectPath(relative(projectDir, join(dir, entry.name)));
+    if (shouldCachePath(relPath)) paths.push(relPath);
+  }
+}
+
+export function primeProjectSnapshotCache(project: ResolvedProject): void {
+  const cache = getProjectCache(project);
+  const paths: string[] = [];
+  walkCacheableFiles(resolve(project.dir), resolve(project.dir), paths);
+  for (const path of paths) {
+    const entry = readCacheEntry(project, path);
+    if (entry) cache.set(path, entry);
+  }
+}
+
+export function getCachedProjectSnapshot(
+  project: ResolvedProject,
+  path: string,
+): ProjectSnapshotCacheEntry | null {
+  return getProjectCache(project).get(normalizeProjectPath(path)) ?? null;
+}
+
+export function updateProjectSnapshotCache(project: ResolvedProject, paths: string[]): void {
+  const cache = getProjectCache(project);
+  for (const path of paths) {
+    const normalizedPath = normalizeProjectPath(path);
+    const entry = readCacheEntry(project, normalizedPath);
+    if (entry) {
+      cache.set(normalizedPath, entry);
+    } else {
+      cache.delete(normalizedPath);
+    }
+  }
+}
+
+export function readCachedProjectChanges(
+  project: ResolvedProject,
+  paths: string[],
+): { changes: CachedProjectChange[]; unmanagedPaths: string[] } {
+  const cache = getProjectCache(project);
+  const changes: CachedProjectChange[] = [];
+  const unmanagedPaths: string[] = [];
+
+  for (const path of paths) {
+    const normalizedPath = normalizeProjectPath(path);
+    if (!shouldCachePath(normalizedPath)) continue;
+    const cached = cache.get(normalizedPath);
+    const current = readCacheEntry(project, normalizedPath);
+    if (!current) {
+      if (cached) unmanagedPaths.push(normalizedPath);
+      cache.delete(normalizedPath);
+      continue;
+    }
+    if (!cached) {
+      unmanagedPaths.push(normalizedPath);
+      cache.set(normalizedPath, current);
+      continue;
+    }
+    if (cached.hash !== current.hash) {
+      changes.push({
+        path: normalizedPath,
+        before: cached.content,
+        after: current.content,
+        beforeHash: cached.hash,
+        afterHash: current.hash,
+      });
+    }
+  }
+
+  return { changes, unmanagedPaths };
+}
diff --git a/packages/core/src/studio-api/routes/fonts.ts b/packages/core/src/studio-api/routes/fonts.ts
new file mode 100644
index 000000000..256a6acc9
--- /dev/null
+++ b/packages/core/src/studio-api/routes/fonts.ts
@@ -0,0 +1,247 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import type { Hono } from "hono";
+
+const FONT_EXT_RE = /\.(otf|ttf|ttc|woff2?)$/i;
+const MAX_FONT_RESULTS = 2000;
+const GOOGLE_FONTS_METADATA_URL = "https://fonts.google.com/metadata/fonts";
+const GOOGLE_FONTS_FETCH_TIMEOUT_MS = 3000;
+let cachedFonts: string[] | null = null;
+let cachedGoogleFonts: string[] | null = null;
+
+const STYLE_SUFFIXES = new Set([
+  "black",
+  "bold",
+  "book",
+  "condensed",
+  "demi",
+  "demibold",
+  "display",
+  "extra",
+  "extrabold",
+  "hairline",
+  "heavy",
+  "italic",
+  "light",
+  "medium",
+  "normal",
+  "regular",
+  "roman",
+  "semibold",
+  "thin",
+  "ultra",
+  "ultralight",
+]);
+
+const GOOGLE_FONT_FALLBACKS = [
+  "Inter",
+  "Roboto",
+  "Open Sans",
+  "Montserrat",
+  "Poppins",
+  "Lato",
+  "Oswald",
+  "Raleway",
+  "Nunito",
+  "Playfair Display",
+  "Merriweather",
+  "Source Sans 3",
+  "Source Serif 4",
+  "Source Code Pro",
+  "DM Sans",
+  "Space Grotesk",
+  "Space Mono",
+  "Bebas Neue",
+  "Outfit",
+  "JetBrains Mono",
+];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function fontDirectories(): string[] {
+  const home = homedir();
+  if (platform() === "darwin") {
+    return [
+      join(home, "Library", "Fonts"),
+      "/Library/Fonts",
+      "/System/Library/Fonts",
+      "/System/Library/Fonts/Supplemental",
+    ];
+  }
+  if (platform() === "win32") {
+    return [join(process.env.WINDIR || "C:\\Windows", "Fonts")];
+  }
+  return [
+    join(home, ".fonts"),
+    join(home, ".local", "share", "fonts"),
+    "/usr/local/share/fonts",
+    "/usr/share/fonts",
+  ];
+}
+
+function toFamilyName(fileName: string): string | null {
+  const withoutExt = fileName.replace(FONT_EXT_RE, "");
+  if (!withoutExt || withoutExt.startsWith(".")) return null;
+
+  const spaced = withoutExt
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .replace(/\s+/g, " ")
+    .trim();
+  const words = spaced.split(" ").filter(Boolean);
+  while (words.length > 1 && STYLE_SUFFIXES.has((words.at(-1) ?? "").toLowerCase())) {
+    words.pop();
+  }
+
+  const family = words.join(" ").trim();
+  return family.length >= 2 ? family : null;
+}
+
+function collectMacSystemProfilerFonts(): string[] {
+  if (platform() !== "darwin") return [];
+
+  let parsed: unknown;
+  try {
+    const raw = execFileSync("system_profiler", ["SPFontsDataType", "-json"], {
+      encoding: "utf8",
+      maxBuffer: 12 * 1024 * 1024,
+      timeout: 5000,
+    });
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+
+  if (!isRecord(parsed) || !Array.isArray(parsed.SPFontsDataType)) return [];
+  const fonts: string[] = [];
+
+  for (const fontEntry of parsed.SPFontsDataType) {
+    if (!isRecord(fontEntry)) continue;
+    const typefaces = fontEntry.typefaces;
+    if (!Array.isArray(typefaces)) continue;
+
+    for (const typeface of typefaces) {
+      if (!isRecord(typeface)) continue;
+      const family = typeface.family;
+      const fullName = typeface.fullname;
+      const name = typeface._name;
+      if (typeof family === "string" && family.trim()) {
+        fonts.push(family.trim());
+      } else if (typeof fullName === "string" && fullName.trim()) {
+        fonts.push(fullName.trim());
+      } else if (typeof name === "string" && name.trim()) {
+        fonts.push(name.trim());
+      }
+    }
+  }
+
+  return fonts;
+}
+
+function collectFontsFromDir(dir: string, depth = 0): string[] {
+  if (!existsSync(dir) || depth > 2) return [];
+  const fonts: string[] = [];
+
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      fonts.push(...collectFontsFromDir(fullPath, depth + 1));
+      continue;
+    }
+    if (!entry.isFile() || !FONT_EXT_RE.test(entry.name)) continue;
+    try {
+      if (!statSync(fullPath).isFile()) continue;
+    } catch {
+      continue;
+    }
+    const family = toFamilyName(entry.name);
+    if (family) fonts.push(family);
+  }
+
+  return fonts;
+}
+
+function listInstalledFontFamilies(): string[] {
+  if (cachedFonts) return cachedFonts;
+  const families = new Set<string>();
+
+  for (const family of collectMacSystemProfilerFonts()) {
+    families.add(family);
+    if (families.size >= MAX_FONT_RESULTS) break;
+  }
+
+  for (const dir of fontDirectories()) {
+    for (const family of collectFontsFromDir(dir)) {
+      families.add(family);
+      if (families.size >= MAX_FONT_RESULTS) break;
+    }
+    if (families.size >= MAX_FONT_RESULTS) break;
+  }
+
+  cachedFonts = Array.from(families).sort((a, b) => a.localeCompare(b));
+  return cachedFonts;
+}
+
+function parseGoogleFontMetadata(value: unknown): string[] {
+  if (!isRecord(value) || !Array.isArray(value.familyMetadataList)) return [];
+  const families: string[] = [];
+  for (const entry of value.familyMetadataList) {
+    if (!isRecord(entry) || typeof entry.family !== "string") continue;
+    families.push(entry.family);
+  }
+  return families;
+}
+
+function stripGoogleJsonGuard(raw: string): string {
+  const prefix = ")]}'";
+  if (!raw.startsWith(prefix)) return raw;
+
+  let index = prefix.length;
+  while (
+    index < raw.length &&
+    (raw[index] === " " ||
+      raw[index] === "\n" ||
+      raw[index] === "\r" ||
+      raw[index] === "\t" ||
+      raw[index] === "\f")
+  ) {
+    index += 1;
+  }
+
+  return raw.slice(index);
+}
+
+async function listGoogleFontFamilies(): Promise<string[]> {
+  if (cachedGoogleFonts) return cachedGoogleFonts;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), GOOGLE_FONTS_FETCH_TIMEOUT_MS);
+
+  try {
+    const response = await fetch(GOOGLE_FONTS_METADATA_URL, { signal: controller.signal });
+    if (!response.ok) {
+      cachedGoogleFonts = GOOGLE_FONT_FALLBACKS;
+      return cachedGoogleFonts;
+    }
+    const raw = await response.text();
+    const jsonText = stripGoogleJsonGuard(raw);
+    const families = parseGoogleFontMetadata(JSON.parse(jsonText));
+    cachedGoogleFonts = families.length > 0 ? families : GOOGLE_FONT_FALLBACKS;
+  } catch {
+    cachedGoogleFonts = GOOGLE_FONT_FALLBACKS;
+  } finally {
+    clearTimeout(timer);
+  }
+
+  return cachedGoogleFonts;
+}
+
+export function registerFontRoutes(api: Hono): void {
+  api.get("/fonts", (c) => c.json({ fonts: listInstalledFontFamilies() }));
+  api.get("/fonts/google", async (c) => c.json({ fonts: await listGoogleFontFamilies() }));
+}
diff --git a/packages/core/src/studio-api/routes/history.ts b/packages/core/src/studio-api/routes/history.ts
new file mode 100644
index 000000000..9b9dad1a1
--- /dev/null
+++ b/packages/core/src/studio-api/routes/history.ts
@@ -0,0 +1,271 @@
+import type { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+import type { StudioEventBus } from "../events.js";
+import type { EditHistoryActor, ProjectEditRequest } from "../history/editHistory.js";
+import {
+  adoptExternalProjectChanges,
+  applyProjectHistoryTransition,
+  ProjectHistoryError,
+  readProjectHistorySnapshot,
+  recordAppliedProjectEdit,
+  recordProjectEdit,
+} from "../history/projectHistoryStore.js";
+import type { StudioApiAdapter } from "../types.js";
+
+function errorResponse(c: { json: (data: unknown, status?: number) => Response }, error: unknown) {
+  if (error instanceof ProjectHistoryError) {
+    return c.json(
+      {
+        error: error.code,
+        message: error.message,
+        path: error.path,
+        expectedHash: error.expectedHash,
+        actualHash: error.actualHash,
+      },
+      error.status,
+    );
+  }
+  throw error;
+}
+
+export function registerHistoryRoutes(
+  api: Hono,
+  adapter: StudioApiAdapter,
+  events: StudioEventBus,
+): void {
+  api.get("/projects/:id/history", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    return c.json(await readProjectHistorySnapshot(project));
+  });
+
+  api.get("/projects/:id/edit-contract", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    return c.json({
+      version: 1,
+      projectId: project.id,
+      endpoints: {
+        submitEdit: `/api/projects/${project.id}/edits`,
+        adoptExternal: `/api/projects/${project.id}/history/adopt-external`,
+        undo: `/api/projects/${project.id}/history/undo`,
+        redo: `/api/projects/${project.id}/history/redo`,
+        events: `/api/projects/${project.id}/events`,
+      },
+      editRequest: {
+        label: "Agent edit",
+        kind: "agent",
+        actor: { type: "agent", id: "codex" },
+        files: {
+          "index.html": {
+            beforeHash: "hash from current content",
+            after: "new file content",
+          },
+        },
+      },
+    });
+  });
+
+  api.post("/projects/:id/edits", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    const body = (await c.req.json().catch(() => null)) as ProjectEditRequest | null;
+    if (!body?.label || !body.kind || !body.files || typeof body.files !== "object") {
+      return c.json({ error: "invalid-request" }, 400);
+    }
+
+    try {
+      const result = await recordProjectEdit(project, body);
+      if (result.changedPaths.length > 0) {
+        events.publish({
+          type: "project-edit",
+          projectId: project.id,
+          entryId: result.entryId,
+          label: body.label,
+          kind: body.kind,
+          actor: body.actor,
+          changedPaths: result.changedPaths,
+          history: result.history,
+        });
+        events.publish({
+          type: "file-change",
+          projectId: project.id,
+          changedPaths: result.changedPaths,
+          source: body.actor?.type === "agent" ? "agent" : "studio",
+        });
+      }
+      return c.json(result);
+    } catch (error) {
+      return errorResponse(c, error);
+    }
+  });
+
+  api.post("/projects/:id/history/record-applied", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    const body = (await c.req.json().catch(() => null)) as {
+      label?: string;
+      kind?: ProjectEditRequest["kind"];
+      actor?: EditHistoryActor;
+      coalesceKey?: string;
+      files?: Record<string, { before: string; after: string }>;
+    } | null;
+    if (!body?.label || !body.kind || !body.files || typeof body.files !== "object") {
+      return c.json({ error: "invalid-request" }, 400);
+    }
+
+    try {
+      const result = await recordAppliedProjectEdit(project, {
+        label: body.label,
+        kind: body.kind,
+        actor: body.actor,
+        coalesceKey: body.coalesceKey,
+        files: body.files,
+      });
+      if (result.entryId && result.changedPaths.length > 0) {
+        events.publish({
+          type: "project-edit",
+          projectId: project.id,
+          entryId: result.entryId,
+          label: body.label,
+          kind: body.kind,
+          actor: body.actor,
+          changedPaths: result.changedPaths,
+          history: result.history,
+        });
+      }
+      return c.json({ ok: true, ...result });
+    } catch (error) {
+      return errorResponse(c, error);
+    }
+  });
+
+  api.post("/projects/:id/history/undo", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    try {
+      const result = await applyProjectHistoryTransition(project, "undo");
+      if (result.ok) {
+        events.publish({
+          type: "history-updated",
+          projectId: project.id,
+          changedPaths: result.changedPaths,
+          history: result.history,
+        });
+        events.publish({
+          type: "file-change",
+          projectId: project.id,
+          changedPaths: result.changedPaths,
+          source: "studio",
+        });
+      }
+      return c.json(
+        result.ok ? result : { ...result, error: result.reason },
+        result.ok ? 200 : 409,
+      );
+    } catch (error) {
+      return errorResponse(c, error);
+    }
+  });
+
+  api.post("/projects/:id/history/redo", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    try {
+      const result = await applyProjectHistoryTransition(project, "redo");
+      if (result.ok) {
+        events.publish({
+          type: "history-updated",
+          projectId: project.id,
+          changedPaths: result.changedPaths,
+          history: result.history,
+        });
+        events.publish({
+          type: "file-change",
+          projectId: project.id,
+          changedPaths: result.changedPaths,
+          source: "studio",
+        });
+      }
+      return c.json(
+        result.ok ? result : { ...result, error: result.reason },
+        result.ok ? 200 : 409,
+      );
+    } catch (error) {
+      return errorResponse(c, error);
+    }
+  });
+
+  api.post("/projects/:id/history/adopt-external", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    const body = (await c.req.json().catch(() => null)) as {
+      paths?: string[];
+      label?: string;
+      actor?: EditHistoryActor;
+    } | null;
+    if (!body?.paths || !Array.isArray(body.paths)) {
+      return c.json({ error: "invalid-request" }, 400);
+    }
+
+    try {
+      const result = await adoptExternalProjectChanges(project, {
+        paths: body.paths,
+        label: body.label,
+        actor: body.actor ?? { type: "external" },
+      });
+      if (result.changedPaths.length > 0 || (result.unmanagedPaths?.length ?? 0) > 0) {
+        if (result.entryId) {
+          events.publish({
+            type: "project-edit",
+            projectId: project.id,
+            entryId: result.entryId,
+            label: result.label ?? "External edit",
+            kind: body.actor?.type === "agent" ? "agent" : "manual",
+            actor: body.actor ?? { type: "external" },
+            changedPaths: result.changedPaths,
+            unmanagedPaths: result.unmanagedPaths,
+            history: result.history,
+          });
+        }
+        events.publish({
+          type: "file-change",
+          projectId: project.id,
+          changedPaths: result.changedPaths,
+          unmanagedPaths: result.unmanagedPaths,
+          source: body.actor?.type === "agent" ? "agent" : "external",
+        });
+      }
+      return c.json({ ok: true, ...result });
+    } catch (error) {
+      return errorResponse(c, error);
+    }
+  });
+
+  api.get("/projects/:id/events", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+
+    return streamSSE(c, async (stream) => {
+      const unsubscribe = events.subscribe(project.id, (event) => {
+        stream
+          .writeSSE({
+            event: event.type,
+            data: JSON.stringify(event),
+          })
+          .catch(() => {});
+      });
+      try {
+        while (true) {
+          await stream.writeSSE({
+            event: "heartbeat",
+            data: JSON.stringify({ projectId: project.id, now: Date.now() }),
+          });
+          await stream.sleep(15000);
+        }
+      } finally {
+        unsubscribe();
+      }
+    });
+  });
+}
diff --git a/packages/core/src/studio-api/routes/preview.ts b/packages/core/src/studio-api/routes/preview.ts
index 1713ee990..bfd7fa28c 100644
--- a/packages/core/src/studio-api/routes/preview.ts
+++ b/packages/core/src/studio-api/routes/preview.ts
@@ -6,6 +6,15 @@ import { isSafePath } from "../helpers/safePath.js";
 import { getMimeType } from "../helpers/mime.js";
 import { buildSubCompositionHtml } from "../helpers/subComposition.js";
 
+function htmlNoStore(html: string): Response {
+  return new Response(html, {
+    headers: {
+      "Content-Type": "text/html; charset=UTF-8",
+      "Cache-Control": "no-store",
+    },
+  });
+}
+
 export function registerPreviewRoutes(api: Hono, adapter: StudioApiAdapter): void {
   // Bundled composition preview
   api.get("/projects/:id/preview", async (c) => {
@@ -37,10 +46,10 @@ export function registerPreviewRoutes(api: Hono, adapter: StudioApiAdapter): voi
         bundled = bundled.replace(/<head>/i, `<head><base href="${baseHref}">`);
       }
 
-      return c.html(bundled);
+      return htmlNoStore(bundled);
     } catch {
       const file = resolve(project.dir, "index.html");
-      if (existsSync(file)) return c.html(readFileSync(file, "utf-8"));
+      if (existsSync(file)) return htmlNoStore(readFileSync(file, "utf-8"));
       return c.text("not found", 404);
     }
   });
@@ -63,7 +72,7 @@ export function registerPreviewRoutes(api: Hono, adapter: StudioApiAdapter): voi
     const baseHref = `/api/projects/${project.id}/preview/`;
     const html = buildSubCompositionHtml(project.dir, compPath, adapter.runtimeUrl, baseHref);
     if (!html) return c.text("not found", 404);
-    return c.html(html);
+    return htmlNoStore(html);
   });
 
   // Static asset serving (with range request support for audio/video seeking)
diff --git a/packages/core/src/studio-api/routes/projects.ts b/packages/core/src/studio-api/routes/projects.ts
index 8df310433..c8690cd30 100644
--- a/packages/core/src/studio-api/routes/projects.ts
+++ b/packages/core/src/studio-api/routes/projects.ts
@@ -1,6 +1,7 @@
 import type { Hono } from "hono";
 import type { StudioApiAdapter } from "../types.js";
 import { walkDir } from "../helpers/safePath.js";
+import { primeProjectSnapshotCache } from "../history/projectSnapshotCache.js";
 
 export function registerProjectRoutes(api: Hono, adapter: StudioApiAdapter): void {
   // List all projects
@@ -24,7 +25,8 @@ export function registerProjectRoutes(api: Hono, adapter: StudioApiAdapter): voi
   api.get("/projects/:id", async (c) => {
     const project = await adapter.resolveProject(c.req.param("id"));
     if (!project) return c.json({ error: "not found" }, 404);
+    primeProjectSnapshotCache(project);
     const files = walkDir(project.dir);
-    return c.json({ id: project.id, files });
+    return c.json({ id: project.id, dir: project.dir, title: project.title, files });
   });
 }
diff --git a/packages/core/src/studio-api/routes/thumbnail.test.ts b/packages/core/src/studio-api/routes/thumbnail.test.ts
index 9d8c75753..6e576107f 100644
--- a/packages/core/src/studio-api/routes/thumbnail.test.ts
+++ b/packages/core/src/studio-api/routes/thumbnail.test.ts
@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { Hono } from "hono";
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { registerThumbnailRoutes } from "./thumbnail";
@@ -75,4 +75,60 @@ describe("registerThumbnailRoutes", () => {
       }),
     );
   });
+
+  it("forwards selector occurrence indexes to thumbnail generation", async () => {
+    const adapter = createAdapter();
+    const app = new Hono();
+    registerThumbnailRoutes(app, adapter);
+
+    const response = await app.request(
+      "http://localhost/projects/demo/thumbnail/index.html?t=1.2&selector=.card&selectorIndex=2",
+    );
+
+    expect(response.status).toBe(200);
+    expect(adapter.generateThumbnail).toHaveBeenCalledWith(
+      expect.objectContaining({
+        selector: ".card",
+        selectorIndex: 2,
+      }),
+    );
+  });
+
+  it("keeps url thumbnail versions separated in the disk cache", async () => {
+    const adapter = createAdapter();
+    const app = new Hono();
+    registerThumbnailRoutes(app, adapter);
+
+    await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=old");
+    await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=old");
+    await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=new");
+
+    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
+  });
+
+  it("keeps changed composition dimensions separated in the disk cache", async () => {
+    const adapter = createAdapter();
+    const project = await adapter.resolveProject("demo");
+    if (!project) throw new Error("missing project");
+    const app = new Hono();
+    registerThumbnailRoutes(app, adapter);
+
+    const indexPath = join(project.dir, "index.html");
+    writeFileSync(indexPath, `<div data-composition-id="main" data-width="640" data-height="360">`);
+    await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=test");
+
+    writeFileSync(
+      indexPath,
+      `<div data-composition-id="main" data-width="1280" data-height="720">`,
+    );
+    await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=test");
+
+    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
+    expect(adapter.generateThumbnail).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        width: 1280,
+        height: 720,
+      }),
+    );
+  });
 });
diff --git a/packages/core/src/studio-api/routes/thumbnail.ts b/packages/core/src/studio-api/routes/thumbnail.ts
index afff8e688..06ce462a9 100644
--- a/packages/core/src/studio-api/routes/thumbnail.ts
+++ b/packages/core/src/studio-api/routes/thumbnail.ts
@@ -1,9 +1,9 @@
 import type { Hono } from "hono";
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import type { StudioApiAdapter } from "../types.js";
 
-const THUMBNAIL_CACHE_VERSION = "v2";
+const THUMBNAIL_CACHE_VERSION = "v3";
 
 export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): void {
   api.get("/projects/:id/thumbnail/*", async (c) => {
@@ -25,13 +25,19 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
     const selector = url.searchParams.get("selector") || undefined;
     const format = url.searchParams.get("format") === "png" ? "png" : "jpeg";
     const contentType = format === "png" ? "image/png" : "image/jpeg";
+    const rawSelectorIndex = Number.parseInt(url.searchParams.get("selectorIndex") || "0", 10);
+    const selectorIndex =
+      Number.isFinite(rawSelectorIndex) && rawSelectorIndex > 0 ? rawSelectorIndex : undefined;
+    const urlVersion = url.searchParams.get("v") || "";
 
     // Determine composition dimensions from HTML
     let compW = vpWidth || 1920;
     let compH = vpHeight || 1080;
+    let sourceMtime = 0;
     if (!vpWidth) {
       const htmlFile = join(project.dir, compPath);
       if (existsSync(htmlFile)) {
+        sourceMtime = Math.round(statSync(htmlFile).mtimeMs);
         const html = readFileSync(htmlFile, "utf-8");
         const wMatch = html.match(/data-width=["'](\d+)["']/);
         const hMatch = html.match(/data-height=["'](\d+)["']/);
@@ -48,9 +54,12 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
     // Cache
     const cacheDir = join(project.dir, ".thumbnails");
     const selectorKey = selector
-      ? `_${selector.replace(/[^a-zA-Z0-9_-]+/g, "_").slice(0, 80)}`
+      ? `_${selector.replace(/[^a-zA-Z0-9_-]+/g, "_").slice(0, 80)}_${selectorIndex ?? 0}`
       : "";
-    const cacheKey = `${THUMBNAIL_CACHE_VERSION}_${format}_${compPath.replace(/\//g, "_")}_${seekTime.toFixed(2)}${selectorKey}.${format === "png" ? "png" : "jpg"}`;
+    const urlVersionKey = urlVersion
+      ? `_${urlVersion.replace(/[^a-zA-Z0-9_-]+/g, "_").slice(0, 32)}`
+      : "";
+    const cacheKey = `${THUMBNAIL_CACHE_VERSION}${urlVersionKey}_${format}_${compPath.replace(/\//g, "_")}_${compW}x${compH}_${sourceMtime}_${seekTime.toFixed(2)}${selectorKey}.${format === "png" ? "png" : "jpg"}`;
     const cachePath = join(cacheDir, cacheKey);
     if (existsSync(cachePath)) {
       return new Response(new Uint8Array(readFileSync(cachePath)), {
@@ -68,6 +77,7 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
         previewUrl,
         selector,
         format,
+        selectorIndex,
       });
       if (!buffer) {
         return c.json({ error: "Thumbnail generation returned null" }, 500);
diff --git a/packages/core/src/studio-api/types.ts b/packages/core/src/studio-api/types.ts
index 71aa96371..62c00eb2c 100644
--- a/packages/core/src/studio-api/types.ts
+++ b/packages/core/src/studio-api/types.ts
@@ -73,6 +73,7 @@ export interface StudioApiAdapter {
     previewUrl: string;
     selector?: string;
     format?: "jpeg" | "png";
+    selectorIndex?: number;
   }) => Promise<Buffer | null>;
 
   /** Optional: resolve session ID to project (multi-project mode). */
diff --git a/packages/engine/package.json b/packages/engine/package.json
index fb9a5ef1c..ab8240b17 100644
--- a/packages/engine/package.json
+++ b/packages/engine/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.4.41",
+  "version": "0.5.0-alpha.14",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
diff --git a/packages/player/package.json b/packages/player/package.json
index 3c13cca15..1552255db 100644
--- a/packages/player/package.json
+++ b/packages/player/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/player",
-  "version": "0.4.41",
+  "version": "0.5.0-alpha.14",
   "description": "Embeddable web component for HyperFrames compositions",
   "repository": {
     "type": "git",
diff --git a/packages/producer/package.json b/packages/producer/package.json
index d90dea92f..385f3157e 100644
--- a/packages/producer/package.json
+++ b/packages/producer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.4.41",
+  "version": "0.5.0-alpha.14",
   "description": "HTML-to-video rendering engine using Chrome's BeginFrame API",
   "repository": {
     "type": "git",
diff --git a/packages/shader-transitions/package.json b/packages/shader-transitions/package.json
index 98389019f..98ad9dd4b 100644
--- a/packages/shader-transitions/package.json
+++ b/packages/shader-transitions/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/shader-transitions",
-  "version": "0.4.41",
+  "version": "0.5.0-alpha.14",
   "description": "WebGL shader transitions for HyperFrames compositions",
   "repository": {
     "type": "git",
diff --git a/packages/studio/index.html b/packages/studio/index.html
index 718c43415..7e8dc88ae 100644
--- a/packages/studio/index.html
+++ b/packages/studio/index.html
@@ -3,6 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>HyperFrames Studio</title>
   </head>
   <body>
diff --git a/packages/studio/package.json b/packages/studio/package.json
index 220a2c5ee..a3e77f001 100644
--- a/packages/studio/package.json
+++ b/packages/studio/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.4.41",
+  "version": "0.5.0-alpha.14",
   "description": "",
   "repository": {
     "type": "git",
@@ -40,6 +40,7 @@
     "@hyperframes/player": "workspace:*",
     "@phosphor-icons/react": "^2.1.10",
     "codemirror": "^6.0.1",
+    "mediabunny": "^1.43.0",
     "motion": "^12.38.0"
   },
   "devDependencies": {
diff --git a/packages/studio/public/favicon.svg b/packages/studio/public/favicon.svg
new file mode 100644
index 000000000..de375e946
--- /dev/null
+++ b/packages/studio/public/favicon.svg
@@ -0,0 +1,14 @@
+<svg width="100" height="100" viewBox="0 0 100 100" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <path d="M10.1851 57.8021L33.1145 73.8313C36.2202 75.9978 41.5173 73.5433 42.4816 69.4984L51.7611 30.4271C52.7253 26.3822 48.5802 23.9277 44.4602 26.0942L13.917 42.1235C6.96677 45.7676 4.97564 54.1579 10.1851 57.8021Z" fill="url(#paint0_linear_2204_3074)" />
+  <path d="M87.5129 57.5141L56.9696 73.5433C52.8371 75.7098 48.7046 73.2553 49.6688 69.2104L58.9483 30.1391C59.9125 26.0942 65.2097 23.6397 68.3154 25.8062L91.2447 41.8354C96.4668 45.4796 94.4631 53.8699 87.5129 57.5141Z" fill="url(#paint1_linear_2204_3074)" />
+  <defs>
+    <linearGradient id="paint0_linear_2204_3074" x1="48.5676" y1="25" x2="44.7804" y2="71.9384" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#06E3FA" />
+      <stop offset="1" stop-color="#4FDB5E" />
+    </linearGradient>
+    <linearGradient id="paint1_linear_2204_3074" x1="54.8282" y1="73.8392" x2="72.0989" y2="32.8932" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#06E3FA" />
+      <stop offset="1" stop-color="#4FDB5E" />
+    </linearGradient>
+  </defs>
+</svg>
diff --git a/packages/studio/src/App.tsx b/packages/studio/src/App.tsx
index 3fb271749..d6f01e964 100644
--- a/packages/studio/src/App.tsx
+++ b/packages/studio/src/App.tsx
@@ -1,31 +1,24 @@
-import {
-  useState,
-  useCallback,
-  useRef,
-  useEffect,
-  useMemo,
-  type MouseEvent,
-  type ReactNode,
-} from "react";
+import { useState, useCallback, useRef, useEffect, useMemo, type MouseEvent } from "react";
 import { useMountEffect } from "./hooks/useMountEffect";
 import { NLELayout } from "./components/nle/NLELayout";
 import { SourceEditor } from "./components/editor/SourceEditor";
 import { LeftSidebar } from "./components/sidebar/LeftSidebar";
 import { RenderQueue } from "./components/renders/RenderQueue";
 import { useRenderQueue } from "./components/renders/useRenderQueue";
-import { CompositionThumbnail, VideoThumbnail, liveTime, usePlayerStore } from "./player";
-import { AudioWaveform } from "./player/components/AudioWaveform";
+import { liveTime, usePlayerStore } from "./player";
 import type { TimelineElement } from "./player";
 import { LintModal } from "./components/LintModal";
 import type { LintFinding } from "./components/LintModal";
 import { MediaPreview } from "./components/MediaPreview";
-import { isMediaFile } from "./utils/mediaTypes";
+import { RotateCcw, RotateCw } from "./icons/SystemIcons";
+import { FONT_EXT, isMediaFile } from "./utils/mediaTypes";
 import {
   buildTimelineAssetId,
   buildTimelineAssetInsertHtml,
   buildTimelineFileDropPlacements,
   getTimelineAssetKind,
   insertTimelineAssetIntoSource,
+  resolveTimelineAssetInitialGeometry,
   resolveTimelineAssetSrc,
   type TimelineAssetKind,
 } from "./utils/timelineAssetDrop";
@@ -35,7 +28,15 @@ import { CaptionTimeline } from "./captions/components/CaptionTimeline";
 import { useCaptionStore } from "./captions/store";
 import { useCaptionSync } from "./captions/hooks/useCaptionSync";
 import { parseCaptionComposition } from "./captions/parser";
-import { applyPatchByTarget, readAttributeByTarget } from "./utils/sourcePatcher";
+import { copyTextToClipboard } from "./utils/clipboard";
+import { useSharedEditHistory } from "./hooks/useSharedEditHistory";
+import {
+  applyPatchByTarget,
+  findSourceLocationByTarget,
+  readAttributeByTarget,
+  readTagSnippetByTarget,
+  type PatchOperation,
+} from "./utils/sourcePatcher";
 import {
   buildTrackZIndexMap,
   formatTimelineAttributeNumber,
@@ -50,6 +51,57 @@ import {
 } from "./utils/timelineDiscovery";
 import { buildFrameCaptureFilename, buildFrameCaptureUrl } from "./utils/frameCapture";
 import { Camera } from "./icons/SystemIcons";
+import { PropertyPanel } from "./components/editor/PropertyPanel";
+import { TimelineThumbnailContent } from "./player/components/TimelineThumbnailContent";
+import { AudioWaveform } from "./player/components/AudioWaveform";
+import { googleFontStylesheetUrl } from "./components/editor/fontCatalog";
+import {
+  fontFamilyFromAssetPath,
+  importedFontFaceCss,
+  type ImportedFontAsset,
+} from "./components/editor/fontAssets";
+import { DomEditOverlay } from "./components/editor/DomEditOverlay";
+import { TimelineLayerPanel } from "./components/editor/TimelineLayerPanel";
+import {
+  buildDefaultDomEditTextField,
+  buildDomEditDetachPatchOperations,
+  buildDomEditMovePatchOperations,
+  buildDomEditResizePatchOperations,
+  buildDomEditStylePatchOperation,
+  buildDomEditTextPatchOperation,
+  buildElementAgentPrompt,
+  collectDomEditLayerItems,
+  countDomEditChildLayers,
+  findElementForSelection,
+  getDomEditLayerKey,
+  isTextEditableSelection,
+  serializeDomEditTextFields,
+  resolveDomEditCapabilities,
+  resolveDomEditSelection,
+  type DomEditLayerItem,
+  type DomEditTextField,
+  type DomEditSelection,
+} from "./components/editor/domEditing";
+import {
+  buildMotionAgentContext,
+  buildDomEditMotionPatchOperations,
+  buildMotionVarsId,
+  clampMotionDraftToTimeline,
+  detectMotionOwnership,
+  parseMotionDraft,
+  type MotionDraft,
+} from "./components/editor/motionEditing";
+import { saveProjectFilesWithHistory } from "./utils/studioFileHistory";
+import { getStudioThumbnailService } from "./thumbnails/studioThumbnailService";
+import { hashThumbnailSource } from "./thumbnails/sourceHash";
+import {
+  canInspectTimelineElement,
+  getTimelineLayerVisibilityInPreview,
+  getTimelineElementKey,
+  isTimelineLayerVisibleInPreview,
+  isAudioTimelineElement,
+  shouldShowTimelineInspectorBounds,
+} from "./utils/timelineInspector";
 
 interface EditingFile {
   path: string;
@@ -61,8 +113,654 @@ interface AppToast {
   tone: "error" | "info";
 }
 
-function getTimelineElementLabel(element: TimelineElement): string {
-  return element.label || element.id || element.tag;
+interface PreviewPlayerCompat {
+  getTime: () => number;
+  renderSeek: (timeSeconds: number) => void;
+}
+
+type RightPanelTab = "design" | "renders";
+
+function getPreviewPlayer(win: Window | null | undefined): PreviewPlayerCompat | null {
+  const player = (win as (Window & { __player?: unknown }) | null | undefined)?.__player;
+  if (!player || typeof player !== "object") return null;
+  const maybePlayer = player as Partial<PreviewPlayerCompat>;
+  return typeof maybePlayer.getTime === "function" && typeof maybePlayer.renderSeek === "function"
+    ? (maybePlayer as PreviewPlayerCompat)
+    : null;
+}
+
+function parseFiniteSeconds(value: string | null): number | null {
+  if (value == null || value.trim() === "") return null;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function resolveLayerVisibleSeekTime(
+  layerElement: HTMLElement,
+  timelineElement: TimelineElement | null,
+  player: PreviewPlayerCompat | null,
+): number | null {
+  if (!timelineElement || !player) return null;
+
+  const clipStart = Math.max(0, timelineElement.start);
+  const clipEnd = Math.max(clipStart, clipStart + Math.max(0, timelineElement.duration));
+  const authoredStart = parseFiniteSeconds(
+    layerElement.getAttribute("data-start") ??
+      layerElement.closest<HTMLElement>("[data-start]")?.getAttribute("data-start") ??
+      null,
+  );
+  const preferredTime =
+    authoredStart == null
+      ? clipStart
+      : Math.min(clipEnd, Math.max(clipStart, clipStart + authoredStart));
+
+  const candidates = [preferredTime, clipStart];
+  const duration = Math.max(0, clipEnd - clipStart);
+  if (duration > 0) {
+    const maxSamples = 180;
+    const frameStep = 1 / 24;
+    const step = Math.max(frameStep, duration / maxSamples);
+    for (let time = clipStart; time <= clipEnd + 0.0001; time += step) {
+      candidates.push(Math.min(clipEnd, time));
+    }
+  }
+  candidates.push(clipEnd);
+
+  let lastTried = preferredTime;
+  let clearestVisibleTime: number | null = null;
+  let clearestVisibleOpacity = 0;
+  const seen = new Set<string>();
+  for (const candidate of candidates) {
+    const time = Math.min(clipEnd, Math.max(clipStart, candidate));
+    const key = time.toFixed(4);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    lastTried = time;
+    player.renderSeek(time);
+    const visibility = getTimelineLayerVisibilityInPreview(layerElement);
+    if (visibility.visible && visibility.compositeOpacity > clearestVisibleOpacity) {
+      clearestVisibleTime = time;
+      clearestVisibleOpacity = visibility.compositeOpacity;
+    }
+    if (isTimelineLayerVisibleInPreview(layerElement, { minCompositeOpacity: 0.9 })) return time;
+  }
+
+  return clearestVisibleTime ?? lastTried;
+}
+
+const GENERIC_FONT_FAMILIES = new Set([
+  "inherit",
+  "initial",
+  "revert",
+  "revert-layer",
+  "serif",
+  "sans-serif",
+  "monospace",
+  "cursive",
+  "fantasy",
+  "system-ui",
+  "ui-sans-serif",
+  "ui-serif",
+  "ui-monospace",
+  "ui-rounded",
+  "emoji",
+  "math",
+  "fangsong",
+]);
+
+function primaryFontFamilyFromCss(value: string): string {
+  const first = value.split(",")[0] ?? "";
+  return first.trim().replace(/^["']|["']$/g, "");
+}
+
+function injectPreviewGoogleFont(doc: Document, fontFamilyValue: string): void {
+  const family = primaryFontFamilyFromCss(fontFamilyValue);
+  if (!family || GENERIC_FONT_FAMILIES.has(family.toLowerCase())) return;
+
+  const id = `studio-preview-google-font-${family.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
+  if (doc.getElementById(id)) return;
+
+  const link = doc.createElement("link");
+  link.id = id;
+  link.rel = "stylesheet";
+  link.href = googleFontStylesheetUrl(family);
+  doc.head.appendChild(link);
+}
+
+function primaryFontFamilyValue(value: string): string {
+  return (
+    value
+      .split(",")[0]
+      ?.trim()
+      .replace(/^["']|["']$/g, "")
+      .trim() ?? ""
+  );
+}
+
+function injectPreviewImportedFont(doc: Document, asset: ImportedFontAsset): void {
+  const id = `studio-imported-font-${asset.family.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
+  if (doc.getElementById(id)) return;
+  const style = doc.createElement("style");
+  style.id = id;
+  style.textContent = importedFontFaceCss(asset);
+  doc.head.appendChild(style);
+}
+
+function normalizeProjectAssetPath(value: string): string {
+  const trimmed = value.trim();
+  const maybeUrl = /^[a-z]+:\/\//i.test(trimmed) ? new URL(trimmed).pathname : trimmed;
+  return decodeURIComponent(maybeUrl)
+    .replace(/\\/g, "/")
+    .replace(/^\.?\//, "");
+}
+
+function normalizeRelativeProjectPath(path: string): string | null {
+  const parts: string[] = [];
+  for (const part of path.replace(/\\/g, "/").split("/")) {
+    if (!part || part === ".") continue;
+    if (part === "..") {
+      if (parts.length === 0) return null;
+      parts.pop();
+      continue;
+    }
+    parts.push(part);
+  }
+  return parts.join("/");
+}
+
+function extractPreviewAssetPath(value: string): string | null {
+  try {
+    const parsed = /^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? new URL(value) : null;
+    const path = parsed?.pathname ?? value;
+    const marker = "/preview/";
+    const markerIndex = path.indexOf(marker);
+    if (markerIndex < 0) return null;
+    const encodedPath = path.slice(markerIndex + marker.length);
+    if (!encodedPath || encodedPath.startsWith("comp/")) return null;
+    return normalizeRelativeProjectPath(decodeURIComponent(encodedPath));
+  } catch {
+    return null;
+  }
+}
+
+function resolveTimelineAudioAssetPath(
+  element: Pick<TimelineElement, "tag" | "src" | "sourceFile">,
+): string | null {
+  if (!isAudioTimelineElement(element) || !element.src) return null;
+  const src = element.src.trim();
+  if (!src || src.startsWith("data:") || src.startsWith("blob:")) return null;
+
+  const previewPath = extractPreviewAssetPath(src);
+  if (previewPath) return previewPath;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(src)) return null;
+
+  const cleanPath = src.split(/[?#]/)[0] ?? src;
+  const baseDir = element.sourceFile?.includes("/")
+    ? element.sourceFile.slice(0, element.sourceFile.lastIndexOf("/"))
+    : "";
+  return normalizeRelativeProjectPath(baseDir ? `${baseDir}/${cleanPath}` : cleanPath);
+}
+
+function encodeProjectRoutePath(path: string): string {
+  return path
+    .split("/")
+    .map((part) => encodeURIComponent(part))
+    .join("/");
+}
+
+function buildWaveformUrl(projectId: string, assetPath: string): string {
+  return `/api/projects/${encodeURIComponent(projectId)}/waveform/${encodeProjectRoutePath(assetPath)}`;
+}
+
+function getPreviewCompositionPathFromIframe(iframe: HTMLIFrameElement | null): string | null {
+  if (!iframe?.src) return null;
+  try {
+    const pathname = new URL(iframe.src).pathname;
+    const marker = "/preview/comp/";
+    const markerIndex = pathname.indexOf(marker);
+    if (markerIndex < 0) return null;
+    const encodedPath = pathname.slice(markerIndex + marker.length).replace(/^\/+/, "");
+    return encodedPath ? decodeURIComponent(encodedPath) : null;
+  } catch {
+    return null;
+  }
+}
+
+function getRenderedPreviewIframe(): HTMLIFrameElement | null {
+  if (typeof document === "undefined") return null;
+  const player = document.querySelector("hyperframes-player");
+  const iframe = player?.shadowRoot?.querySelector("iframe");
+  return iframe instanceof HTMLIFrameElement ? iframe : null;
+}
+
+function getCurrentPreviewIframe(
+  refIframe: HTMLIFrameElement | null,
+  stateIframe: HTMLIFrameElement | null,
+): HTMLIFrameElement | null {
+  return getRenderedPreviewIframe() ?? refIframe ?? stateIframe;
+}
+
+function toRelativeProjectAssetPath(sourceFile: string, assetPath: string): string {
+  const fromParts = normalizeProjectAssetPath(sourceFile).split("/").filter(Boolean);
+  const targetParts = normalizeProjectAssetPath(assetPath).split("/").filter(Boolean);
+
+  fromParts.pop();
+
+  while (fromParts.length > 0 && targetParts.length > 0 && fromParts[0] === targetParts[0]) {
+    fromParts.shift();
+    targetParts.shift();
+  }
+
+  return [...fromParts.map(() => ".."), ...targetParts].join("/") || assetPath;
+}
+
+function isAbsoluteFilePath(value: string): boolean {
+  return /^(?:\/|[A-Za-z]:[\\/]|\\\\)/.test(value);
+}
+
+function toProjectAbsolutePath(projectDir: string | null, sourceFile: string): string | undefined {
+  const trimmedSource = sourceFile.trim();
+  if (!trimmedSource) return undefined;
+
+  const normalizedSource = trimmedSource.replace(/\\/g, "/");
+  if (isAbsoluteFilePath(normalizedSource)) return normalizedSource;
+
+  const normalizedRoot = projectDir?.trim().replace(/\\/g, "/").replace(/\/+$/, "");
+  if (!normalizedRoot) return undefined;
+
+  return `${normalizedRoot}/${normalizedSource.replace(/^\.?\//, "")}`;
+}
+
+function formatElementLocatorClipboardText({
+  selection,
+  absolutePath,
+  sourceLocation,
+  currentTime,
+}: {
+  selection: DomEditSelection;
+  absolutePath: string;
+  sourceLocation: NonNullable<ReturnType<typeof findSourceLocationByTarget>> | null;
+  currentTime: number;
+}): string {
+  const pathWithLocation = sourceLocation
+    ? `${absolutePath}:${sourceLocation.line}:${sourceLocation.column}`
+    : absolutePath;
+  const lines = [
+    pathWithLocation,
+    "",
+    "HyperFrames selected element locator",
+    `Absolute path: ${absolutePath}`,
+    sourceLocation
+      ? `LOC: ${sourceLocation.line}:${sourceLocation.column}`
+      : "LOC: unavailable from current source",
+    `Source file: ${selection.sourceFile}`,
+    `Composition: ${selection.compositionPath}`,
+    `Selector: ${selection.selector ?? "(none)"}`,
+    `Selector index: ${selection.selectorIndex ?? 0}`,
+    `DOM id: ${selection.id ?? "(none)"}`,
+    `Tag: <${selection.tagName}>`,
+    `Playback time: ${currentTime.toFixed(3)}s`,
+  ];
+
+  return lines.join("\n");
+}
+
+function ensureImportedFontFace(
+  html: string,
+  asset: ImportedFontAsset,
+  sourceFile: string,
+): string {
+  const css = importedFontFaceCss(asset, toRelativeProjectAssetPath(sourceFile, asset.path));
+  if (html.includes(css)) return html;
+
+  const styleRe = /<style\b[^>]*data-hf-studio-fonts=(["'])true\1[^>]*>([\s\S]*?)<\/style>/i;
+  const styleMatch = styleRe.exec(html);
+  if (styleMatch) {
+    const nextCss = `${styleMatch[2].trim()}\n${css}`.trim();
+    return html.replace(styleMatch[0], `<style data-hf-studio-fonts="true">\n${nextCss}\n</style>`);
+  }
+
+  const styleTag = `<style data-hf-studio-fonts="true">\n${css}\n</style>`;
+  if (/<\/head>/i.test(html)) {
+    return html.replace(/<\/head>/i, `  ${styleTag}\n  </head>`);
+  }
+  return `${styleTag}\n${html}`;
+}
+function normalizeDomEditStyleValue(property: string, value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) return trimmed;
+
+  if (
+    ["left", "top", "width", "height", "border-radius", "font-size"].includes(property) &&
+    /^-?\d+(\.\d+)?$/.test(trimmed)
+  ) {
+    return `${trimmed}px`;
+  }
+
+  return trimmed;
+}
+
+function isImageBackgroundValue(value: string): boolean {
+  return /^url\(/i.test(value.trim());
+}
+
+function shouldDetachOppositeEdges(selection: DomEditSelection): boolean {
+  return Boolean(
+    selection.inlineStyles.inset || selection.inlineStyles.right || selection.inlineStyles.bottom,
+  );
+}
+
+function buildOppositeEdgePatchOperations(
+  selection: DomEditSelection,
+  dimension: "width" | "height" | "both",
+): PatchOperation[] {
+  if (!shouldDetachOppositeEdges(selection)) return [];
+  const operations: PatchOperation[] = [];
+  if (dimension === "width" || dimension === "both") {
+    operations.push({ type: "inline-style", property: "right", value: "auto" });
+  }
+  if (dimension === "height" || dimension === "both") {
+    operations.push({ type: "inline-style", property: "bottom", value: "auto" });
+  }
+  return operations;
+}
+
+function getEventTargetElement(target: EventTarget | null): HTMLElement | null {
+  if (!target || typeof target !== "object") return null;
+  const maybeNode = target as {
+    nodeType?: number;
+    parentElement?: Element | null;
+  };
+  if (maybeNode.nodeType === 1) return target as HTMLElement;
+  if (maybeNode.nodeType === 3 && maybeNode.parentElement) {
+    return maybeNode.parentElement as HTMLElement;
+  }
+  return null;
+}
+
+function shouldIgnoreHistoryShortcut(target: EventTarget | null): boolean {
+  const el = getEventTargetElement(target);
+  if (!el) return false;
+  return Boolean(
+    el.closest("input, textarea, select, [contenteditable='true'], [role='textbox'], .cm-editor"),
+  );
+}
+
+function getHistoryShortcutLabel(action: "undo" | "redo"): string {
+  const isMac =
+    typeof navigator !== "undefined" && /Mac|iPhone|iPad|iPod/i.test(navigator.platform);
+  const modifier = isMac ? "Cmd" : "Ctrl";
+  return action === "undo" ? `${modifier}+Z` : `${modifier}+Shift+Z`;
+}
+
+function isDomHTMLElement(value: unknown): value is HTMLElement {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "nodeType" in value &&
+    (value as { nodeType?: unknown }).nodeType === 1 &&
+    "getBoundingClientRect" in value &&
+    typeof (value as { getBoundingClientRect?: unknown }).getBoundingClientRect === "function"
+  );
+}
+
+function getDomEditCoalesceKey(
+  selection: Pick<DomEditSelection, "id" | "selector" | "sourceFile">,
+  action: "move" | "resize" | "motion",
+): string {
+  const target = selection.id || selection.selector || "selection";
+  return `${action}:${selection.sourceFile || "index.html"}:${target}`;
+}
+
+function findMatchingTimelineElementId(
+  selection: Pick<
+    DomEditSelection,
+    "id" | "selector" | "selectorIndex" | "sourceFile" | "compositionSrc" | "isCompositionHost"
+  >,
+  elements: TimelineElement[],
+): string | null {
+  for (const element of elements) {
+    if (selection.id && element.domId === selection.id) {
+      return element.key ?? element.id;
+    }
+    if (
+      selection.isCompositionHost &&
+      selection.compositionSrc &&
+      element.compositionSrc === selection.compositionSrc
+    ) {
+      return element.key ?? element.id;
+    }
+    if (
+      selection.selector &&
+      element.selector === selection.selector &&
+      (element.selectorIndex ?? 0) === (selection.selectorIndex ?? 0) &&
+      (element.sourceFile ?? "index.html") === selection.sourceFile
+    ) {
+      return element.key ?? element.id;
+    }
+  }
+
+  return null;
+}
+
+function findMappedCompositionHost(
+  target: HTMLElement,
+  timelineElements: TimelineElement[],
+  compIdToSrc: Map<string, string>,
+  fileTree: string[],
+): { host: HTMLElement; compositionSrc: string } | null {
+  const rootCompositionId =
+    target.ownerDocument
+      .querySelector("[data-composition-id]")
+      ?.getAttribute("data-composition-id") ?? null;
+
+  let nestedCurrent: HTMLElement | null = target;
+  while (nestedCurrent) {
+    const nestedCompId = nestedCurrent.getAttribute("data-composition-id");
+    if (nestedCompId && nestedCompId !== rootCompositionId) {
+      const hostCandidate = nestedCurrent.parentElement?.closest(".clip");
+      if (isDomHTMLElement(hostCandidate)) {
+        const hostCompId = hostCandidate.getAttribute("data-composition-id");
+        const compositionSrc =
+          hostCandidate.getAttribute("data-composition-src") ??
+          hostCandidate.getAttribute("data-composition-file") ??
+          (hostCompId ? compIdToSrc.get(hostCompId) : undefined) ??
+          compIdToSrc.get(nestedCompId) ??
+          fileTree.find((path) => path.endsWith(`${nestedCompId}.html`)) ??
+          undefined;
+        if (compositionSrc) {
+          return { host: hostCandidate, compositionSrc };
+        }
+      }
+    }
+    nestedCurrent = nestedCurrent.parentElement;
+  }
+
+  let current: HTMLElement | null = target;
+  while (current) {
+    const compId = current.getAttribute("data-composition-id");
+    const directSrc =
+      current.getAttribute("data-composition-src") ??
+      current.getAttribute("data-composition-file") ??
+      undefined;
+    const timelineMatch =
+      timelineElements.find(
+        (element) =>
+          Boolean(element.compositionSrc) &&
+          (element.domId === current?.id ||
+            (current?.id && element.id === current.id) ||
+            (compId && element.id === compId)),
+      ) ?? null;
+    const compositionSrc =
+      directSrc ??
+      timelineMatch?.compositionSrc ??
+      (compId ? compIdToSrc.get(compId) : undefined) ??
+      (compId ? fileTree.find((path) => path.endsWith(`${compId}.html`)) : undefined);
+    if (compositionSrc) {
+      return { host: current, compositionSrc };
+    }
+    current = current.parentElement;
+  }
+
+  return null;
+}
+
+function isMoveStyleProperty(property: string): boolean {
+  return property === "left" || property === "top";
+}
+
+function isResizeStyleProperty(property: string): boolean {
+  return property === "width" || property === "height";
+}
+
+function getDomDetachCoordinateRoot(element: HTMLElement): HTMLElement {
+  const offsetParent = element.offsetParent;
+  if (isDomHTMLElement(offsetParent)) return offsetParent;
+
+  let current = element.parentElement;
+  while (current) {
+    if (current.hasAttribute("data-composition-id")) return current;
+    current = current.parentElement;
+  }
+
+  return element.ownerDocument.body;
+}
+
+function measureDomDetachRect(element: HTMLElement): {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+} {
+  const root = getDomDetachCoordinateRoot(element);
+  const rect = element.getBoundingClientRect();
+  const rootRect = root.getBoundingClientRect();
+
+  return {
+    left: rect.left - rootRect.left + root.scrollLeft,
+    top: rect.top - rootRect.top + root.scrollTop,
+    width: rect.width,
+    height: rect.height,
+  };
+}
+
+// ── Ask Agent Modal ──
+
+function AskAgentModal({
+  selectionLabel,
+  motionContextIncluded,
+  onSubmit,
+  onClose,
+}: {
+  selectionLabel: string;
+  motionContextIncluded?: boolean;
+  onSubmit: (instruction: string) => void;
+  onClose: () => void;
+}) {
+  const [value, setValue] = useState("");
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+
+  useMountEffect(() => {
+    requestAnimationFrame(() => inputRef.current?.focus());
+  });
+
+  const handleSubmit = () => {
+    if (!value.trim()) return;
+    onSubmit(value.trim());
+  };
+
+  return (
+    <div
+      className="fixed inset-0 z-[100] flex items-center justify-center bg-black/60 backdrop-blur-sm"
+      onClick={onClose}
+    >
+      <div
+        className="w-[480px] rounded-2xl border border-neutral-800 bg-neutral-950 shadow-2xl"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="flex items-center justify-between px-5 py-4 border-b border-neutral-800/60">
+          <div>
+            <h3 className="text-sm font-medium text-neutral-200">Ask agent</h3>
+            <p className="text-xs text-neutral-500 mt-0.5">
+              {selectionLabel.length > 50 ? `${selectionLabel.slice(0, 49)}…` : selectionLabel}
+            </p>
+            {motionContextIncluded && (
+              <div className="mt-2 inline-flex rounded-full border border-[#3ce6ac]/30 bg-[#3ce6ac]/10 px-2 py-0.5 text-[10px] font-semibold uppercase tracking-[0.12em] text-[#c4fff0]">
+                Motion context included
+              </div>
+            )}
+          </div>
+          <button
+            className="p-1 rounded-md text-neutral-500 hover:text-neutral-300 hover:bg-neutral-800/50"
+            onClick={onClose}
+          >
+            <svg
+              width="14"
+              height="14"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+            >
+              <line x1="18" y1="6" x2="6" y2="18" />
+              <line x1="6" y1="6" x2="18" y2="18" />
+            </svg>
+          </button>
+        </div>
+        <div className="px-5 py-4">
+          <textarea
+            ref={inputRef}
+            className="w-full h-24 px-3 py-2 rounded-lg border border-neutral-800 bg-neutral-900/60 text-sm text-neutral-200 placeholder-neutral-600 resize-none focus:outline-none focus:border-studio-accent/60 focus:ring-1 focus:ring-studio-accent/30"
+            placeholder="Describe what you want to change…"
+            value={value}
+            onChange={(e) => setValue(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) handleSubmit();
+              if (e.key === "Escape") onClose();
+            }}
+          />
+        </div>
+        <div className="flex items-center justify-between px-5 py-3 border-t border-neutral-800/60">
+          <span className="text-[11px] text-neutral-600">
+            {navigator.platform.includes("Mac") ? "⌘" : "Ctrl"}+Enter to copy
+          </span>
+          <button
+            className="px-4 py-1.5 rounded-lg bg-studio-accent/90 text-xs font-medium text-neutral-950 hover:bg-studio-accent disabled:opacity-40 disabled:cursor-not-allowed"
+            disabled={!value.trim()}
+            onClick={handleSubmit}
+          >
+            Copy prompt
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function selectionHasMotionAgentContext(selection: DomEditSelection): boolean {
+  if (selection.dataAttributes["hf-motion"]) return true;
+  return (
+    detectMotionOwnership({
+      element: selection.element,
+      dataAttributes: selection.dataAttributes,
+      computedStyles: selection.computedStyles,
+    }).badges.length > 0
+  );
+}
+
+function resolveSelectionMotionMaxDuration(
+  selection: DomEditSelection | null,
+  fallbackDuration: number,
+): number {
+  const clipElement = selection?.element.closest(".clip") ?? selection?.element ?? null;
+  const rawDuration =
+    clipElement?.getAttribute("data-duration") ?? selection?.element.getAttribute("data-duration");
+  const parsedDuration = rawDuration != null ? Number.parseFloat(rawDuration) : null;
+  if (parsedDuration != null && Number.isFinite(parsedDuration) && parsedDuration > 0) {
+    return parsedDuration;
+  }
+  return fallbackDuration;
 }
 
 const DEFAULT_TIMELINE_ASSET_DURATION: Record<TimelineAssetKind, number> = {
@@ -143,6 +841,7 @@ export function StudioApp() {
   });
 
   const [editingFile, setEditingFile] = useState<EditingFile | null>(null);
+  const [projectDir, setProjectDir] = useState<string | null>(null);
   const [activeCompPath, setActiveCompPath] = useState<string | null>(null);
   const [fileTree, setFileTree] = useState<string[]>([]);
   const [compIdToSrc, setCompIdToSrc] = useState<Map<string, string>>(new Map());
@@ -156,6 +855,14 @@ export function StudioApp() {
   const [rightWidth, setRightWidth] = useState(400);
   const [leftCollapsed, setLeftCollapsed] = useState(false);
   const [rightCollapsed, setRightCollapsed] = useState(true);
+  const [rightPanelTab, setRightPanelTab] = useState<RightPanelTab>("renders");
+  const [domEditSelection, setDomEditSelection] = useState<DomEditSelection | null>(null);
+  const [agentPromptTagSnippet, setAgentPromptTagSnippet] = useState<string | undefined>();
+  const [copiedAgentPrompt, setCopiedAgentPrompt] = useState(false);
+  const [copiedElementLocator, setCopiedElementLocator] = useState(false);
+  const [agentModalOpen, setAgentModalOpen] = useState(false);
+  const [previewIframe, setPreviewIframe] = useState<HTMLIFrameElement | null>(null);
+  const [previewDocumentVersion, setPreviewDocumentVersion] = useState(0);
   // Auto-enter caption edit mode when the iframe contains .caption-group elements.
   // This is a subscription to external events (postMessage from runtime) — useEffect
   // is appropriate here. The runtime fires "state"/"timeline" messages after all
@@ -255,6 +962,12 @@ export function StudioApp() {
     const handleMessage = (e: MessageEvent) => {
       const data = e.data;
       if (data?.source === "hf-preview" && (data?.type === "state" || data?.type === "timeline")) {
+        const currentIframe = getRenderedPreviewIframe();
+        if (currentIframe && currentIframe !== previewIframeRef.current) {
+          previewIframeRef.current = currentIframe;
+          setPreviewIframe(currentIframe);
+        }
+        setPreviewDocumentVersion((version) => version + 1);
         tryActivateCaptions();
       }
     };
@@ -279,26 +992,86 @@ export function StudioApp() {
   const [appToast, setAppToast] = useState<AppToast | null>(null);
   const [timelineVisible, setTimelineVisible] = useState(true);
   const [captureFrameTime, setCaptureFrameTime] = useState(0);
+  const [thumbnailedTimelineElementIds, setThumbnailedTimelineElementIds] = useState<Set<string>>(
+    () => new Set(),
+  );
+  const [inspectedTimelineElementId, setInspectedTimelineElementId] = useState<string | null>(null);
   const dragCounterRef = useRef(0);
   const toastTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const lastBlockedTimelineToastAtRef = useRef(0);
+  const lastBlockedDomMoveToastAtRef = useRef(0);
+  const selectedTimelineLayerRevealTimeRef = useRef<number | null>(null);
+  const selectedTimelineLayerRevealUntilRef = useRef(0);
+  const importedFontAssetsRef = useRef<ImportedFontAsset[]>([]);
   const previewHotkeyWindowRef = useRef<Window | null>(null);
   const panelDragRef = useRef<{
     side: "left" | "right";
     startX: number;
     startW: number;
   } | null>(null);
+  const previewIframeRef = useRef<HTMLIFrameElement | null>(null);
+  const refreshPreviewDocumentVersion = useCallback(() => {
+    setPreviewDocumentVersion((version) => version + 1);
+    window.setTimeout(() => setPreviewDocumentVersion((version) => version + 1), 50);
+    window.setTimeout(() => setPreviewDocumentVersion((version) => version + 1), 250);
+    window.setTimeout(() => setPreviewDocumentVersion((version) => version + 1), 1000);
+  }, []);
 
-  // Derive active preview URL from composition path (for drilled-down thumbnails)
-  const activePreviewUrl = activeCompPath
-    ? `/api/projects/${projectId}/preview/comp/${activeCompPath}`
-    : null;
+  const isMasterView = !activeCompPath || activeCompPath === "index.html";
+  const layerInspectionCompositionPath = useMemo(() => {
+    void previewDocumentVersion;
+    if (activeCompPath && activeCompPath !== "index.html") return activeCompPath;
+    return (
+      getPreviewCompositionPathFromIframe(
+        getCurrentPreviewIframe(previewIframeRef.current, previewIframe),
+      ) ?? activeCompPath
+    );
+  }, [activeCompPath, previewDocumentVersion, previewIframe]);
+  const layerInspectionIsMasterView =
+    !layerInspectionCompositionPath || layerInspectionCompositionPath === "index.html";
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!layerInspectionCompositionPath) return;
+    let attempts = 0;
+    let intervalId: number | null = null;
+    const tick = () => {
+      const iframe = getCurrentPreviewIframe(previewIframeRef.current, previewIframe);
+      const hasCompositionRoot = Boolean(
+        iframe?.contentDocument?.querySelector("[data-composition-id]"),
+      );
+      setPreviewDocumentVersion((version) => version + 1);
+      attempts += 1;
+      if ((hasCompositionRoot || attempts >= 20) && intervalId != null) {
+        window.clearInterval(intervalId);
+        intervalId = null;
+      }
+    };
+
+    tick();
+    intervalId = window.setInterval(tick, 100);
+    return () => {
+      if (intervalId != null) window.clearInterval(intervalId);
+    };
+  }, [layerInspectionCompositionPath, previewIframe]);
   const zoomMode = usePlayerStore((s) => s.zoomMode);
   const manualZoomPercent = usePlayerStore((s) => s.manualZoomPercent);
   const setZoomMode = usePlayerStore((s) => s.setZoomMode);
   const setManualZoomPercent = usePlayerStore((s) => s.setManualZoomPercent);
+  const currentTime = usePlayerStore((s) => s.currentTime);
   const timelineElements = usePlayerStore((s) => s.elements);
+  const setSelectedTimelineElementId = usePlayerStore((s) => s.setSelectedElementId);
   const timelineDuration = usePlayerStore((s) => s.duration);
+  const inspectedTimelineElement = useMemo(
+    () =>
+      timelineElements.find(
+        (element) => getTimelineElementKey(element) === inspectedTimelineElementId,
+      ) ?? null,
+    [inspectedTimelineElementId, timelineElements],
+  );
+  const showInspectedTimelineBounds = useMemo(
+    () => shouldShowTimelineInspectorBounds(currentTime, inspectedTimelineElement),
+    [currentTime, inspectedTimelineElement],
+  );
   const effectiveTimelineDuration = useMemo(() => {
     const maxEnd =
       timelineElements.length > 0
@@ -306,10 +1079,39 @@ export function StudioApp() {
         : 0;
     return Math.max(timelineDuration, maxEnd);
   }, [timelineDuration, timelineElements]);
+  const selectedMotionMaxDuration = useMemo(
+    () => resolveSelectionMotionMaxDuration(domEditSelection, effectiveTimelineDuration),
+    [domEditSelection, effectiveTimelineDuration],
+  );
   const displayedTimelineZoomPercent = useMemo(
     () => getTimelineZoomPercent(zoomMode, manualZoomPercent),
     [zoomMode, manualZoomPercent],
   );
+  useEffect(() => {
+    setThumbnailedTimelineElementIds((current) => {
+      if (current.size === 0) return current;
+      const available = new Set(
+        timelineElements
+          .map(getTimelineElementKey)
+          .filter((id): id is string => typeof id === "string"),
+      );
+      const next = new Set([...current].filter((id) => available.has(id)));
+      return next.size === current.size ? current : next;
+    });
+  }, [timelineElements]);
+  const handleTimelineElementThumbnailToggle = useCallback((element: TimelineElement) => {
+    const elementKey = getTimelineElementKey(element);
+    if (!elementKey) return;
+    setThumbnailedTimelineElementIds((current) => {
+      const next = new Set(current);
+      if (next.has(elementKey)) {
+        next.delete(elementKey);
+      } else {
+        next.add(elementKey);
+      }
+      return next;
+    });
+  }, []);
   const toggleTimelineVisibility = useCallback(() => {
     setTimelineVisible((visible) => !visible);
   }, []);
@@ -375,118 +1177,6 @@ export function StudioApp() {
     [handleTimelineToggleHotkey],
   );
 
-  const renderClipContent = useCallback(
-    (el: TimelineElement, style: { clip: string; label: string }): ReactNode => {
-      const pid = projectIdRef.current;
-      if (!pid) return null;
-
-      // Resolve composition source path using the compIdToSrc map
-      let compSrc = el.compositionSrc;
-      if (compSrc && compIdToSrc.size > 0) {
-        const resolved =
-          compIdToSrc.get(el.id) ||
-          compIdToSrc.get(compSrc.replace(/^compositions\//, "").replace(/\.html$/, ""));
-        if (resolved) compSrc = resolved;
-      }
-
-      // Composition clips — always use the comp's own preview URL for thumbnails.
-      // This renders the composition in isolation so we get clean frames
-      // instead of capturing the master at a time when the comp is fading in.
-      if (compSrc) {
-        return (
-          <CompositionThumbnail
-            previewUrl={`/api/projects/${pid}/preview/comp/${compSrc}`}
-            label={getTimelineElementLabel(el)}
-            labelColor={style.label}
-            accentColor={style.clip}
-            selector={el.selector}
-            seekTime={0}
-            duration={el.duration}
-          />
-        );
-      }
-
-      // When drilled into a composition, render all inner elements via
-      // CompositionThumbnail at their start time — most accurate visual.
-      if (activePreviewUrl && el.duration > 0) {
-        return (
-          <CompositionThumbnail
-            previewUrl={activePreviewUrl}
-            label={getTimelineElementLabel(el)}
-            labelColor={style.label}
-            accentColor={style.clip}
-            selector={el.selector}
-            seekTime={el.start}
-            duration={el.duration}
-          />
-        );
-      }
-
-      const htmlPreviewEligible =
-        el.duration > 0 &&
-        effectiveTimelineDuration > 0 &&
-        el.duration < effectiveTimelineDuration * 0.92 &&
-        !/(backdrop|background|overlay|scrim|mask)/i.test(el.id);
-
-      // Audio clips — waveform visualization
-      if (el.tag === "audio") {
-        const previewBase = `/api/projects/${pid}/preview/`;
-        const previewIdx = el.src?.startsWith("http") ? el.src.indexOf(previewBase) : -1;
-        const srcRelative = el.src
-          ? previewIdx !== -1
-            ? decodeURIComponent(el.src.slice(previewIdx + previewBase.length))
-            : el.src.startsWith("http")
-              ? null
-              : el.src
-          : null;
-        const audioUrl = srcRelative
-          ? `/api/projects/${pid}/preview/${srcRelative}`
-          : (el.src ?? "");
-        const waveformUrl = srcRelative
-          ? `/api/projects/${pid}/waveform/${srcRelative}`
-          : undefined;
-        return (
-          <AudioWaveform
-            audioUrl={audioUrl}
-            waveformUrl={waveformUrl}
-            label={getTimelineElementLabel(el)}
-            labelColor={style.label}
-          />
-        );
-      }
-
-      if ((el.tag === "video" || el.tag === "img") && el.src) {
-        const mediaSrc = el.src.startsWith("http")
-          ? el.src
-          : `/api/projects/${pid}/preview/${el.src}`;
-        return (
-          <VideoThumbnail
-            videoSrc={mediaSrc}
-            label={getTimelineElementLabel(el)}
-            labelColor={style.label}
-            duration={el.duration}
-          />
-        );
-      }
-
-      if (htmlPreviewEligible) {
-        return (
-          <CompositionThumbnail
-            previewUrl={`/api/projects/${pid}/preview`}
-            label={getTimelineElementLabel(el)}
-            labelColor={style.label}
-            accentColor={style.clip}
-            selector={el.selector}
-            seekTime={el.start}
-            duration={el.duration}
-          />
-        );
-      }
-
-      return null;
-    },
-    [compIdToSrc, activePreviewUrl, effectiveTimelineDuration],
-  );
   const timelineToolbar = (
     <div className="border-b border-neutral-800/40 bg-neutral-950/96">
       <div className="flex items-center justify-between px-3 py-2">
@@ -564,13 +1254,23 @@ export function StudioApp() {
   const refreshTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const saveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const projectIdRef = useRef(projectId);
-  const previewIframeRef = useRef<HTMLIFrameElement | null>(null);
   const consoleErrorsRef = useRef<LintFinding[]>([]);
+  const copiedAgentTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const copiedElementLocatorTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const domEditSelectionRef = useRef<DomEditSelection | null>(domEditSelection);
+  const lastPreviewClickRef = useRef<{ key: string; at: number } | null>(null);
+  const domEditSaveTimestampRef = useRef(0);
+  const domTextCommitVersionRef = useRef(0);
+  const fileContentCacheRef = useRef<Map<string, string>>(new Map());
 
   // Listen for external file changes (user editing HTML outside the editor).
   // In dev: use Vite HMR. In embedded/production: use SSE from /api/events.
+  // Suppress file-change events that echo back from a recent DOM edit save —
+  // those changes are already applied to the iframe DOM and a full reload
+  // would flash the preview.
   useMountEffect(() => {
     const handler = () => {
+      if (Date.now() - domEditSaveTimestampRef.current < 1200) return;
       if (refreshTimerRef.current) clearTimeout(refreshTimerRef.current);
       refreshTimerRef.current = setTimeout(() => setRefreshKey((k) => k + 1), 400);
     };
@@ -584,6 +1284,7 @@ export function StudioApp() {
     return () => es.close();
   });
   projectIdRef.current = projectId;
+  domEditSelectionRef.current = domEditSelection;
 
   // Load file tree when projectId changes.
   // Note: This is one of the few places where useEffect with deps is acceptable —
@@ -593,63 +1294,224 @@ export function StudioApp() {
   useEffect(() => {
     if (!projectId) return;
     let cancelled = false;
+    fileContentCacheRef.current.clear();
     fetch(`/api/projects/${projectId}`)
       .then((r) => r.json())
-      .then((data: { files?: string[] }) => {
+      .then((data: { files?: string[]; dir?: string }) => {
         if (!cancelled && data.files) setFileTree(data.files);
+        if (!cancelled) setProjectDir(typeof data.dir === "string" ? data.dir : null);
       })
-      .catch(() => {});
+      .catch(() => {
+        if (!cancelled) setProjectDir(null);
+      });
     return () => {
       cancelled = true;
     };
   }, [projectId]);
 
-  const handleFileSelect = useCallback((path: string) => {
+  const loadFileIntoEditor = useCallback((path: string, options?: { expandPanel?: boolean }) => {
     const pid = projectIdRef.current;
     if (!pid) return;
-    // Expand left panel to 50vw when opening a file in Code tab
-    setLeftWidth((prev) => Math.max(prev, Math.floor(window.innerWidth * 0.5)));
+    if (options?.expandPanel !== false) {
+      setLeftWidth((prev) => Math.max(prev, Math.floor(window.innerWidth * 0.5)));
+    }
     // Skip fetching binary content for media files — just set the path for preview
     if (isMediaFile(path)) {
       setEditingFile({ path, content: null });
       return;
     }
+    const cacheKey = `${pid}\0${path}`;
+    const cached = fileContentCacheRef.current.get(cacheKey);
+    if (cached != null) {
+      setEditingFile({ path, content: cached });
+      return;
+    }
+    setEditingFile({ path, content: null });
     fetch(`/api/projects/${pid}/files/${encodeURIComponent(path)}`)
       .then((r) => r.json())
       .then((data: { content?: string }) => {
         if (data.content != null) {
+          fileContentCacheRef.current.set(cacheKey, data.content);
+          if (editingPathRef.current && editingPathRef.current !== path) return;
           setEditingFile({ path, content: data.content });
         }
       })
       .catch(() => {});
   }, []);
 
+  const handleFileSelect = useCallback(
+    (path: string) => loadFileIntoEditor(path, { expandPanel: true }),
+    [loadFileIntoEditor],
+  );
+
+  const handleCompositionSelect = useCallback(
+    (comp: string) => {
+      setActiveCompPath(comp === "index.html" || comp.startsWith("compositions/") ? comp : null);
+      loadFileIntoEditor(comp, { expandPanel: false });
+    },
+    [loadFileIntoEditor],
+  );
+
   const editingPathRef = useRef(editingFile?.path);
   editingPathRef.current = editingFile?.path;
+  const editHistory = useSharedEditHistory({ projectId });
 
-  const handleContentChange = useCallback((content: string) => {
+  const readProjectFile = useCallback(async (path: string): Promise<string> => {
     const pid = projectIdRef.current;
-    if (!pid) return;
-    const path = editingPathRef.current;
-    if (!path) return;
-
-    // Debounce the server write (600ms)
-    if (saveTimerRef.current) clearTimeout(saveTimerRef.current);
-    saveTimerRef.current = setTimeout(() => {
-      fetch(`/api/projects/${pid}/files/${encodeURIComponent(path)}`, {
-        method: "PUT",
-        headers: { "Content-Type": "text/plain" },
-        body: content,
-      })
-        .then(() => {
-          if (refreshTimerRef.current) clearTimeout(refreshTimerRef.current);
-          refreshTimerRef.current = setTimeout(() => setRefreshKey((k) => k + 1), 600);
-        })
-        .catch(() => {});
-    }, 600);
+    if (!pid) throw new Error("No active project");
+    const response = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(path)}`);
+    if (!response.ok) throw new Error(`Failed to read ${path}`);
+    const data = (await response.json()) as { content?: string };
+    if (typeof data.content !== "string") throw new Error(`Missing file contents for ${path}`);
+    fileContentCacheRef.current.set(`${pid}\0${path}`, data.content);
+    return data.content;
   }, []);
 
-  const handleTimelineElementMove = useCallback(
+  const writeProjectFile = useCallback(async (path: string, content: string): Promise<void> => {
+    const pid = projectIdRef.current;
+    if (!pid) throw new Error("No active project");
+    const response = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(path)}`, {
+      method: "PUT",
+      headers: { "Content-Type": "text/plain" },
+      body: content,
+    });
+    if (!response.ok) throw new Error(`Failed to save ${path}`);
+    fileContentCacheRef.current.set(`${pid}\0${path}`, content);
+    if (editingPathRef.current === path) {
+      setEditingFile({ path, content });
+    }
+  }, []);
+
+  const resolveCompositionSourceHash = useCallback(
+    async (path: string): Promise<string> => hashThumbnailSource(await readProjectFile(path)),
+    [readProjectFile],
+  );
+
+  const renderTimelineClipContent = useCallback(
+    (element: TimelineElement, style: { clip: string; label: string; accent?: string }) => {
+      const activeProjectId = projectIdRef.current ?? projectId ?? "";
+      if (isAudioTimelineElement(element)) {
+        const audioAssetPath = resolveTimelineAudioAssetPath(element);
+        return (
+          <AudioWaveform
+            audioUrl={element.src ?? ""}
+            waveformUrl={
+              activeProjectId && audioAssetPath
+                ? buildWaveformUrl(activeProjectId, audioAssetPath)
+                : undefined
+            }
+            label={element.label || element.id || element.tag}
+            labelColor={style.label}
+          />
+        );
+      }
+      return (
+        <TimelineThumbnailContent
+          element={element}
+          projectId={activeProjectId}
+          style={style}
+          resolveSourceHash={resolveCompositionSourceHash}
+        />
+      );
+    },
+    [projectId, resolveCompositionSourceHash],
+  );
+
+  // Project-scoped edit events cover shared history transactions and adopted
+  // external/agent writes. The older HMR/file-change listener above remains as
+  // a broad preview invalidation fallback for dev and embedded servers.
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!projectId) return;
+
+    const refreshFromProjectEvent = (event: MessageEvent | Event) => {
+      let changedPaths: string[] = [];
+      try {
+        const data =
+          event instanceof MessageEvent
+            ? (JSON.parse(event.data) as { changedPaths?: unknown; unmanagedPaths?: unknown })
+            : ((event as CustomEvent).detail as {
+                changedPaths?: unknown;
+                unmanagedPaths?: unknown;
+              });
+        if (Array.isArray(data.changedPaths)) {
+          changedPaths = data.changedPaths.filter(
+            (path): path is string => typeof path === "string",
+          );
+        }
+        if (Array.isArray(data.unmanagedPaths)) {
+          changedPaths.push(
+            ...data.unmanagedPaths.filter((path): path is string => typeof path === "string"),
+          );
+        }
+      } catch {
+        changedPaths = [];
+      }
+      if (changedPaths.length === 0) {
+        fileContentCacheRef.current.clear();
+        void getStudioThumbnailService().clearProject(projectId);
+      } else {
+        for (const path of changedPaths) {
+          fileContentCacheRef.current.delete(`${projectId}\0${path}`);
+        }
+      }
+
+      const activePath = editingPathRef.current;
+      if (activePath && (changedPaths.length === 0 || changedPaths.includes(activePath))) {
+        readProjectFile(activePath)
+          .then((content) => setEditingFile({ path: activePath, content }))
+          .catch(() => {});
+      }
+
+      // NLELayout owns the actual preview refresh. Keep project events on the
+      // same path as timeline/source edits so refreshPlayer() can preserve the
+      // current player instance and seek position.
+      if (refreshTimerRef.current) clearTimeout(refreshTimerRef.current);
+      refreshTimerRef.current = setTimeout(() => setRefreshKey((key) => key + 1), 250);
+    };
+
+    const events = new EventSource(`/api/projects/${projectId}/events`);
+    events.addEventListener("file-change", refreshFromProjectEvent);
+    events.addEventListener("project-edit", refreshFromProjectEvent);
+    events.addEventListener("history-updated", refreshFromProjectEvent);
+    window.addEventListener("hf:project-history-event", refreshFromProjectEvent);
+    return () => {
+      events.close();
+      window.removeEventListener("hf:project-history-event", refreshFromProjectEvent);
+    };
+  }, [projectId, readProjectFile]);
+
+  const handleContentChange = useCallback(
+    (content: string) => {
+      const pid = projectIdRef.current;
+      if (!pid) return;
+      const path = editingPathRef.current;
+      if (!path) return;
+
+      // Debounce the server write (600ms)
+      if (saveTimerRef.current) clearTimeout(saveTimerRef.current);
+      saveTimerRef.current = setTimeout(() => {
+        saveProjectFilesWithHistory({
+          projectId: pid,
+          label: "Edit source",
+          kind: "source",
+          coalesceKey: `source:${path}`,
+          files: { [path]: content },
+          readFile: readProjectFile,
+          writeFile: writeProjectFile,
+          recordEdit: editHistory.recordEdit,
+        })
+          .then(() => {
+            if (refreshTimerRef.current) clearTimeout(refreshTimerRef.current);
+            refreshTimerRef.current = setTimeout(() => setRefreshKey((k) => k + 1), 600);
+          })
+          .catch(() => {});
+      }, 600);
+    },
+    [editHistory.recordEdit, readProjectFile, writeProjectFile],
+  );
+
+  const handleTimelineElementMove = useCallback(
     async (element: TimelineElement, updates: Pick<TimelineElement, "start" | "track">) => {
       const pid = projectIdRef.current;
       if (!pid) throw new Error("No active project");
@@ -689,6 +1551,7 @@ export function StudioApp() {
       const trackZIndices = buildTrackZIndexMap(
         relevantElements.map((timelineElement) => timelineElement.track),
       );
+      const movedElementZIndex = trackZIndices.get(updates.track);
 
       let patchedContent = applyPatchByTarget(originalContent, patchTarget, {
         type: "attribute",
@@ -700,26 +1563,11 @@ export function StudioApp() {
         property: "track-index",
         value: String(updates.track),
       });
-      for (const timelineElement of relevantElements) {
-        const elementTarget = timelineElement.domId
-          ? {
-              id: timelineElement.domId,
-              selector: timelineElement.selector,
-              selectorIndex: timelineElement.selectorIndex,
-            }
-          : timelineElement.selector
-            ? {
-                selector: timelineElement.selector,
-                selectorIndex: timelineElement.selectorIndex,
-              }
-            : null;
-        if (!elementTarget) continue;
-        const nextZIndex = trackZIndices.get(timelineElement.track);
-        if (nextZIndex == null) continue;
-        patchedContent = applyPatchByTarget(patchedContent, elementTarget, {
+      if (movedElementZIndex != null) {
+        patchedContent = applyPatchByTarget(patchedContent, patchTarget, {
           type: "inline-style",
           property: "z-index",
-          value: String(nextZIndex),
+          value: String(movedElementZIndex),
         });
       }
 
@@ -727,25 +1575,19 @@ export function StudioApp() {
         throw new Error(`Unable to patch timeline element ${element.id} in ${targetPath}`);
       }
 
-      const saveResponse = await fetch(
-        `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
-        {
-          method: "PUT",
-          headers: { "Content-Type": "text/plain" },
-          body: patchedContent,
-        },
-      );
-      if (!saveResponse.ok) {
-        throw new Error(`Failed to save ${targetPath}`);
-      }
-
-      if (editingPathRef.current === targetPath) {
-        setEditingFile({ path: targetPath, content: patchedContent });
-      }
+      await saveProjectFilesWithHistory({
+        projectId: pid,
+        label: "Move timeline clip",
+        kind: "timeline",
+        files: { [targetPath]: patchedContent },
+        readFile: async () => originalContent,
+        writeFile: writeProjectFile,
+        recordEdit: editHistory.recordEdit,
+      });
 
       setRefreshKey((k) => k + 1);
     },
-    [activeCompPath, timelineElements],
+    [activeCompPath, editHistory.recordEdit, timelineElements, writeProjectFile],
   );
 
   const handleTimelineElementResize = useCallback(
@@ -813,195 +1655,1422 @@ export function StudioApp() {
         });
       }
 
-      if (patchedContent === originalContent) {
-        throw new Error(`Unable to patch timeline element ${element.id} in ${targetPath}`);
-      }
+      if (patchedContent === originalContent) {
+        throw new Error(`Unable to patch timeline element ${element.id} in ${targetPath}`);
+      }
+
+      await saveProjectFilesWithHistory({
+        projectId: pid,
+        label: "Resize timeline clip",
+        kind: "timeline",
+        files: { [targetPath]: patchedContent },
+        readFile: async () => originalContent,
+        writeFile: writeProjectFile,
+        recordEdit: editHistory.recordEdit,
+      });
+
+      setRefreshKey((k) => k + 1);
+    },
+    [activeCompPath, editHistory.recordEdit, writeProjectFile],
+  );
+
+  const showToast = useCallback((message: string, tone: AppToast["tone"] = "error") => {
+    if (toastTimerRef.current) clearTimeout(toastTimerRef.current);
+    setAppToast({ message, tone });
+    toastTimerRef.current = setTimeout(() => setAppToast(null), 4000);
+  }, []);
+
+  const handleCaptureFrameClick = useCallback(
+    async (event: MouseEvent<HTMLAnchorElement>) => {
+      if (!projectId) return;
+      event.preventDefault();
+
+      const currentTime = usePlayerStore.getState().currentTime;
+      setCaptureFrameTime(currentTime);
+      const href = buildFrameCaptureUrl({
+        projectId,
+        compositionPath: activeCompPath,
+        currentTime,
+      });
+      const filename = buildFrameCaptureFilename(activeCompPath, currentTime);
+
+      try {
+        const response = await fetch(href, { cache: "no-store" });
+        if (!response.ok) {
+          throw new Error(`Capture failed (${response.status})`);
+        }
+        const blob = await response.blob();
+        const blobUrl = URL.createObjectURL(blob);
+        const link = document.createElement("a");
+        link.href = blobUrl;
+        link.download = filename;
+        document.body.appendChild(link);
+        link.click();
+        link.remove();
+        setTimeout(() => URL.revokeObjectURL(blobUrl), 0);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Capture failed";
+        showToast(message);
+      }
+    },
+    [activeCompPath, projectId, showToast],
+  );
+
+  const handleTimelineElementDelete = useCallback(
+    async (element: TimelineElement) => {
+      const pid = projectIdRef.current;
+      if (!pid) throw new Error("No active project");
+
+      const targetPath = element.sourceFile || activeCompPath || "index.html";
+      try {
+        const response = await fetch(
+          `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
+        );
+        if (!response.ok) {
+          throw new Error(`Failed to read ${targetPath}`);
+        }
+
+        const data = (await response.json()) as { content?: string };
+        const originalContent = data.content;
+        if (typeof originalContent !== "string") {
+          throw new Error(`Missing file contents for ${targetPath}`);
+        }
+
+        const patchTarget = element.domId
+          ? { id: element.domId, selector: element.selector, selectorIndex: element.selectorIndex }
+          : element.selector
+            ? { selector: element.selector, selectorIndex: element.selectorIndex }
+            : null;
+        if (!patchTarget) {
+          throw new Error(`Timeline element ${element.id} is missing a patchable target`);
+        }
+
+        const resolvedTargetPath = targetPath || "index.html";
+        const remainingElements = timelineElements.filter(
+          (timelineElement) =>
+            (timelineElement.key ?? timelineElement.id) !== (element.key ?? element.id) &&
+            (timelineElement.sourceFile || activeCompPath || "index.html") === resolvedTargetPath,
+        );
+        const trackZIndices = buildTrackZIndexMap(
+          remainingElements.map((timelineElement) => timelineElement.track),
+        );
+
+        const removeResponse = await fetch(
+          `/api/projects/${pid}/file-mutations/remove-element/${encodeURIComponent(targetPath)}`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ target: patchTarget }),
+          },
+        );
+        if (!removeResponse.ok) {
+          throw new Error(`Failed to delete ${element.id} from ${targetPath}`);
+        }
+
+        const removeData = (await removeResponse.json()) as {
+          changed?: boolean;
+          content?: string;
+        };
+        let patchedContent =
+          typeof removeData.content === "string" ? removeData.content : originalContent;
+        for (const timelineElement of remainingElements) {
+          const elementTarget = timelineElement.domId
+            ? {
+                id: timelineElement.domId,
+                selector: timelineElement.selector,
+                selectorIndex: timelineElement.selectorIndex,
+              }
+            : timelineElement.selector
+              ? {
+                  selector: timelineElement.selector,
+                  selectorIndex: timelineElement.selectorIndex,
+                }
+              : null;
+          if (!elementTarget) continue;
+          const nextZIndex = trackZIndices.get(timelineElement.track);
+          if (nextZIndex == null) continue;
+          patchedContent = applyPatchByTarget(patchedContent, elementTarget, {
+            type: "inline-style",
+            property: "z-index",
+            value: String(nextZIndex),
+          });
+        }
+
+        await saveProjectFilesWithHistory({
+          projectId: pid,
+          label: "Delete timeline clip",
+          kind: "timeline",
+          files: { [targetPath]: patchedContent },
+          readFile: async () => originalContent,
+          writeFile: writeProjectFile,
+          recordEdit: editHistory.recordEdit,
+        });
+
+        usePlayerStore
+          .getState()
+          .setElements(
+            timelineElements.filter(
+              (timelineElement) =>
+                (timelineElement.key ?? timelineElement.id) !== (element.key ?? element.id),
+            ),
+          );
+        usePlayerStore.getState().setSelectedElementId(null);
+        setRefreshKey((k) => k + 1);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Failed to delete timeline clip";
+        showToast(message);
+      }
+    },
+    [activeCompPath, editHistory.recordEdit, showToast, timelineElements, writeProjectFile],
+  );
+
+  const handleBlockedTimelineEdit = useCallback(
+    (_element: TimelineElement) => {
+      const now = Date.now();
+      if (now - lastBlockedTimelineToastAtRef.current < 1500) return;
+      lastBlockedTimelineToastAtRef.current = now;
+      showToast("This clip can’t be moved or resized from the timeline yet.", "info");
+    },
+    [showToast],
+  );
+
+  const handleBlockedDomMove = useCallback(
+    (selection: DomEditSelection) => {
+      const now = Date.now();
+      if (now - lastBlockedDomMoveToastAtRef.current < 1500) return;
+      lastBlockedDomMoveToastAtRef.current = now;
+      showToast(
+        selection.capabilities.canDetachFromLayout
+          ? "This layer is controlled by layout. Use Make movable in the panel to detach it."
+          : (selection.capabilities.reasonIfDisabled ??
+              "This element can’t be moved directly from the preview."),
+        "info",
+      );
+    },
+    [showToast],
+  );
+
+  const applyDomSelection = useCallback(
+    (
+      selection: DomEditSelection | null,
+      options?: { revealPanel?: boolean; preserveTimelineSelection?: boolean },
+    ) => {
+      setDomEditSelection(selection);
+      setAgentPromptTagSnippet(undefined);
+      setCopiedAgentPrompt(false);
+      if (selection) {
+        if (options?.revealPanel !== false) {
+          setRightCollapsed(false);
+          setRightPanelTab("design");
+        }
+        const nextSelectedTimelineId = findMatchingTimelineElementId(selection, timelineElements);
+        if (!options?.preserveTimelineSelection) {
+          setSelectedTimelineElementId(nextSelectedTimelineId);
+        }
+        return;
+      }
+
+      if (!options?.preserveTimelineSelection) {
+        setSelectedTimelineElementId(null);
+      }
+    },
+    [setSelectedTimelineElementId, timelineElements],
+  );
+
+  const clearDomSelection = useCallback(() => {
+    selectedTimelineLayerRevealTimeRef.current = null;
+    selectedTimelineLayerRevealUntilRef.current = 0;
+    setInspectedTimelineElementId(null);
+    applyDomSelection(null, { revealPanel: false });
+  }, [applyDomSelection]);
+
+  useEffect(() => {
+    if (!inspectedTimelineElementId || inspectedTimelineElement) return;
+    setInspectedTimelineElementId(null);
+    applyDomSelection(null, { revealPanel: false });
+  }, [applyDomSelection, inspectedTimelineElement, inspectedTimelineElementId]);
+
+  const handleUndo = useCallback(async () => {
+    const result = await editHistory.undo({
+      readFile: readProjectFile,
+      writeFile: writeProjectFile,
+    });
+    if (!result.ok && result.reason === "content-mismatch") {
+      showToast("File changed outside Studio. Undo history was not applied.", "info");
+      return;
+    }
+    if (result.ok && result.label) {
+      clearDomSelection();
+      setRefreshKey((key) => key + 1);
+      showToast(`Undid ${result.label}`, "info");
+    }
+  }, [clearDomSelection, editHistory, readProjectFile, showToast, writeProjectFile]);
+
+  const handleRedo = useCallback(async () => {
+    const result = await editHistory.redo({
+      readFile: readProjectFile,
+      writeFile: writeProjectFile,
+    });
+    if (!result.ok && result.reason === "content-mismatch") {
+      showToast("File changed outside Studio. Redo history was not applied.", "info");
+      return;
+    }
+    if (result.ok && result.label) {
+      clearDomSelection();
+      setRefreshKey((key) => key + 1);
+      showToast(`Redid ${result.label}`, "info");
+    }
+  }, [clearDomSelection, editHistory, readProjectFile, showToast, writeProjectFile]);
+
+  const handleUndoRef = useRef(handleUndo);
+  const handleRedoRef = useRef(handleRedo);
+  handleUndoRef.current = handleUndo;
+  handleRedoRef.current = handleRedo;
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    const handler = (event: KeyboardEvent) => {
+      if (!(event.metaKey || event.ctrlKey)) return;
+      if (shouldIgnoreHistoryShortcut(event.target)) return;
+      const key = event.key.toLowerCase();
+      if (key === "z" && !event.shiftKey) {
+        event.preventDefault();
+        void handleUndoRef.current();
+        return;
+      }
+      if ((key === "z" && event.shiftKey) || (event.ctrlKey && !event.metaKey && key === "y")) {
+        event.preventDefault();
+        void handleRedoRef.current();
+      }
+    };
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  }, []);
+
+  const buildDomSelectionFromTarget = useCallback(
+    (target: HTMLElement, options?: { preferClipAncestor?: boolean }) => {
+      if (isMasterView) {
+        const mappedHost = findMappedCompositionHost(
+          target,
+          timelineElements,
+          compIdToSrc,
+          fileTree,
+        );
+        if (mappedHost) {
+          const hostSelection = resolveDomEditSelection(mappedHost.host, {
+            activeCompositionPath: activeCompPath,
+            isMasterView,
+            preferClipAncestor: options?.preferClipAncestor,
+          });
+          if (!hostSelection) return null;
+          return {
+            ...hostSelection,
+            compositionSrc: mappedHost.compositionSrc,
+            isCompositionHost: true,
+            capabilities: resolveDomEditCapabilities({
+              selector: hostSelection.selector,
+              tagName: hostSelection.tagName,
+              className: hostSelection.element.getAttribute("class") ?? "",
+              inlineStyles: hostSelection.inlineStyles,
+              computedStyles: hostSelection.computedStyles,
+              hasStudioOwnedMotion: Boolean(hostSelection.dataAttributes["hf-motion"]),
+              isCompositionHost: true,
+              isMasterView: true,
+            }),
+          } satisfies DomEditSelection;
+        }
+      }
+
+      return resolveDomEditSelection(target, {
+        activeCompositionPath: activeCompPath,
+        isMasterView,
+        preferClipAncestor: options?.preferClipAncestor,
+      });
+    },
+    [activeCompPath, compIdToSrc, fileTree, isMasterView, timelineElements],
+  );
+
+  const buildDomSelectionForTimelineElement = useCallback(
+    (element: TimelineElement): DomEditSelection | null => {
+      const iframe = getCurrentPreviewIframe(previewIframeRef.current, previewIframe);
+      const doc = iframe?.contentDocument;
+      if (!doc) return null;
+      const effectiveCompositionPath = layerInspectionCompositionPath;
+
+      const target = findElementForSelection(
+        doc,
+        {
+          id: element.domId,
+          selector: element.selector,
+          selectorIndex: element.selectorIndex,
+          sourceFile: element.sourceFile ?? effectiveCompositionPath ?? "index.html",
+        },
+        effectiveCompositionPath,
+      );
+      if (target) {
+        if (!layerInspectionIsMasterView) {
+          return (
+            resolveDomEditSelection(target, {
+              activeCompositionPath: effectiveCompositionPath,
+              isMasterView: false,
+              preferClipAncestor: false,
+            }) ?? buildDomSelectionFromTarget(target)
+          );
+        }
+        return buildDomSelectionFromTarget(target);
+      }
+
+      if (!layerInspectionIsMasterView) {
+        const compositionRoot = doc.querySelector("[data-composition-id]");
+        if (isDomHTMLElement(compositionRoot)) {
+          return resolveDomEditSelection(compositionRoot, {
+            activeCompositionPath: effectiveCompositionPath,
+            isMasterView: false,
+            preferClipAncestor: false,
+          });
+        }
+      }
+
+      return null;
+    },
+    [
+      buildDomSelectionFromTarget,
+      layerInspectionCompositionPath,
+      layerInspectionIsMasterView,
+      previewIframe,
+    ],
+  );
+
+  const timelineLayerChildCounts = useMemo(() => {
+    void previewDocumentVersion;
+    const counts = new Map<string, number>();
+    if (!getCurrentPreviewIframe(previewIframeRef.current, previewIframe)) return counts;
+
+    for (const element of timelineElements) {
+      if (!canInspectTimelineElement(element)) continue;
+      const elementKey = getTimelineElementKey(element);
+      if (!elementKey) continue;
+      const selection = buildDomSelectionForTimelineElement(element);
+      const childCount = countDomEditChildLayers(selection?.element, {
+        activeCompositionPath: layerInspectionCompositionPath,
+        isMasterView: layerInspectionIsMasterView,
+      });
+      if (childCount > 0) counts.set(elementKey, childCount);
+    }
+
+    return counts;
+  }, [
+    buildDomSelectionForTimelineElement,
+    layerInspectionCompositionPath,
+    layerInspectionIsMasterView,
+    previewDocumentVersion,
+    previewIframe,
+    timelineElements,
+  ]);
+
+  const inspectedTimelineLayers = useMemo(() => {
+    void previewDocumentVersion;
+    if (!inspectedTimelineElement) return [];
+    const selection = buildDomSelectionForTimelineElement(inspectedTimelineElement);
+    return collectDomEditLayerItems(selection?.element, {
+      activeCompositionPath: layerInspectionCompositionPath,
+      isMasterView: layerInspectionIsMasterView,
+    });
+  }, [
+    buildDomSelectionForTimelineElement,
+    inspectedTimelineElement,
+    layerInspectionCompositionPath,
+    layerInspectionIsMasterView,
+    previewDocumentVersion,
+  ]);
+
+  const selectedTimelineLayerKey = useMemo(
+    () => (domEditSelection ? getDomEditLayerKey(domEditSelection) : null),
+    [domEditSelection],
+  );
+  const selectedNestedTimelineLayer = Boolean(
+    selectedTimelineLayerKey &&
+    inspectedTimelineLayers.length > 0 &&
+    selectedTimelineLayerKey !== inspectedTimelineLayers[0]?.key,
+  );
+  const showDomEditSelectionOverlay = Boolean(
+    !rightCollapsed &&
+    rightPanelTab === "design" &&
+    inspectedTimelineElementId &&
+    domEditSelection &&
+    (showInspectedTimelineBounds || selectedNestedTimelineLayer),
+  );
+  const revealTimelineLayerElement = useCallback(
+    (element: HTMLElement, options?: { settle?: boolean; preferStoredTime?: boolean }) => {
+      const currentIframe = getCurrentPreviewIframe(previewIframeRef.current, previewIframe);
+      const player = getPreviewPlayer(currentIframe?.contentWindow);
+      const storedTime = selectedTimelineLayerRevealTimeRef.current;
+      const targetTime =
+        options?.preferStoredTime && storedTime != null
+          ? storedTime
+          : resolveLayerVisibleSeekTime(element, inspectedTimelineElement, player);
+      if (targetTime == null || !player) return;
+
+      selectedTimelineLayerRevealTimeRef.current = targetTime;
+      player.renderSeek(targetTime);
+      liveTime.notify(targetTime);
+      usePlayerStore.getState().setCurrentTime(targetTime);
+
+      if (options?.settle) {
+        selectedTimelineLayerRevealUntilRef.current = Date.now() + 2000;
+        window.setTimeout(
+          () => revealTimelineLayerElement(element, { preferStoredTime: true }),
+          50,
+        );
+        window.setTimeout(
+          () => revealTimelineLayerElement(element, { preferStoredTime: true }),
+          250,
+        );
+        window.setTimeout(
+          () => revealTimelineLayerElement(element, { preferStoredTime: true }),
+          750,
+        );
+        window.setTimeout(
+          () => revealTimelineLayerElement(element, { preferStoredTime: true }),
+          1500,
+        );
+      }
+    },
+    [inspectedTimelineElement, previewIframe],
+  );
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!selectedNestedTimelineLayer || !domEditSelection) return;
+    if (selectedTimelineLayerRevealTimeRef.current == null) return;
+    if (Date.now() > selectedTimelineLayerRevealUntilRef.current) return;
+
+    const currentIframe = getCurrentPreviewIframe(previewIframeRef.current, previewIframe);
+    const doc = currentIframe?.contentDocument;
+    if (!doc) return;
+
+    const element = findElementForSelection(doc, domEditSelection, domEditSelection.sourceFile);
+    if (!element) return;
+
+    revealTimelineLayerElement(element, { preferStoredTime: true });
+  }, [
+    domEditSelection,
+    previewDocumentVersion,
+    previewIframe,
+    revealTimelineLayerElement,
+    selectedNestedTimelineLayer,
+  ]);
+
+  const handleTimelineElementSelect = useCallback(
+    (element: TimelineElement | null) => {
+      if (!element) {
+        selectedTimelineLayerRevealTimeRef.current = null;
+        selectedTimelineLayerRevealUntilRef.current = 0;
+        setInspectedTimelineElementId(null);
+        applyDomSelection(null, { revealPanel: false });
+        return;
+      }
+
+      const elementKey = getTimelineElementKey(element);
+      if (!elementKey || inspectedTimelineElementId !== elementKey) {
+        selectedTimelineLayerRevealTimeRef.current = null;
+        selectedTimelineLayerRevealUntilRef.current = 0;
+        setInspectedTimelineElementId(null);
+        applyDomSelection(null, { revealPanel: false, preserveTimelineSelection: true });
+      }
+    },
+    [applyDomSelection, inspectedTimelineElementId],
+  );
+
+  const handleTimelineLayerSelect = useCallback(
+    (layer: DomEditLayerItem) => {
+      const initialSelection =
+        resolveDomEditSelection(layer.element, {
+          activeCompositionPath: layerInspectionCompositionPath,
+          isMasterView: false,
+          preferClipAncestor: false,
+        }) ?? buildDomSelectionFromTarget(layer.element);
+      if (!initialSelection) {
+        showToast("Could not select that nested layer in the preview.", "info");
+        return;
+      }
+      if (inspectedTimelineElementId) {
+        setSelectedTimelineElementId(inspectedTimelineElementId);
+      }
+      revealTimelineLayerElement(layer.element);
+      const selection =
+        resolveDomEditSelection(layer.element, {
+          activeCompositionPath: layerInspectionCompositionPath,
+          isMasterView: false,
+          preferClipAncestor: false,
+        }) ??
+        buildDomSelectionFromTarget(layer.element) ??
+        initialSelection;
+      applyDomSelection(selection, { preserveTimelineSelection: true });
+    },
+    [
+      applyDomSelection,
+      buildDomSelectionFromTarget,
+      inspectedTimelineElementId,
+      layerInspectionCompositionPath,
+      revealTimelineLayerElement,
+      setSelectedTimelineElementId,
+      showToast,
+    ],
+  );
+
+  const handleTimelineLayerPanelClose = useCallback(() => {
+    selectedTimelineLayerRevealTimeRef.current = null;
+    selectedTimelineLayerRevealUntilRef.current = 0;
+    setInspectedTimelineElementId(null);
+    applyDomSelection(null, { revealPanel: false, preserveTimelineSelection: true });
+  }, [applyDomSelection]);
+
+  const handleTimelineElementInspect = useCallback(
+    (element: TimelineElement) => {
+      const elementKey = getTimelineElementKey(element);
+      if (!elementKey) return;
+
+      if (!canInspectTimelineElement(element)) {
+        selectedTimelineLayerRevealTimeRef.current = null;
+        selectedTimelineLayerRevealUntilRef.current = 0;
+        setInspectedTimelineElementId(null);
+        applyDomSelection(null, { revealPanel: false, preserveTimelineSelection: true });
+        showToast(
+          "Audio clips use timeline timing controls, not the visual design inspector.",
+          "info",
+        );
+        return;
+      }
+
+      if (inspectedTimelineElementId === elementKey) {
+        selectedTimelineLayerRevealTimeRef.current = null;
+        selectedTimelineLayerRevealUntilRef.current = 0;
+        setInspectedTimelineElementId(null);
+        applyDomSelection(null, { revealPanel: false, preserveTimelineSelection: true });
+        return;
+      }
+
+      const selection = buildDomSelectionForTimelineElement(element);
+      if (!selection) {
+        showToast("Could not find that clip in the preview.", "info");
+        return;
+      }
+
+      setSelectedTimelineElementId(elementKey);
+      setInspectedTimelineElementId(elementKey);
+      applyDomSelection(selection);
+
+      const targetTime = Math.max(0, element.start);
+      const currentIframe = getCurrentPreviewIframe(previewIframeRef.current, previewIframe);
+      const player = getPreviewPlayer(currentIframe?.contentWindow);
+      if (player) {
+        player.renderSeek(targetTime);
+      }
+      liveTime.notify(targetTime);
+      usePlayerStore.getState().setCurrentTime(targetTime);
+    },
+    [
+      applyDomSelection,
+      buildDomSelectionForTimelineElement,
+      inspectedTimelineElementId,
+      previewIframe,
+      setSelectedTimelineElementId,
+      showToast,
+    ],
+  );
+
+  const preloadAgentPromptSnippet = useCallback(
+    async (selection: DomEditSelection) => {
+      const pid = projectIdRef.current;
+      if (!pid) return;
+
+      const targetPath = selection.sourceFile || activeCompPath || "index.html";
+      try {
+        const response = await fetch(
+          `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
+        );
+        if (!response.ok) return;
+
+        const data = (await response.json()) as { content?: string };
+        const html = data.content;
+        const tagSnippet =
+          typeof html === "string" ? readTagSnippetByTarget(html, selection) : undefined;
+
+        setAgentPromptTagSnippet((current) => {
+          if (domEditSelectionRef.current !== selection) return current;
+          return tagSnippet;
+        });
+      } catch {
+        // Runtime outerHTML is still available as a synchronous copy fallback.
+      }
+    },
+    [activeCompPath],
+  );
+
+  const resolveImportedFontAsset = useCallback(
+    (fontFamilyValue: string): ImportedFontAsset | null => {
+      const family = primaryFontFamilyValue(fontFamilyValue);
+      if (!family) return null;
+      const imported = importedFontAssetsRef.current.find(
+        (font) => font.family.toLowerCase() === family.toLowerCase(),
+      );
+      if (imported) return imported;
+      const asset = fileTree.find(
+        (path) =>
+          FONT_EXT.test(path) &&
+          fontFamilyFromAssetPath(path).toLowerCase() === family.toLowerCase(),
+      );
+      if (!asset) return null;
+      return {
+        family: fontFamilyFromAssetPath(asset),
+        path: asset,
+        url: `/api/projects/${projectId}/preview/${asset}`,
+      };
+    },
+    [fileTree, projectId],
+  );
+
+  const persistDomEditOperations = useCallback(
+    async (
+      selection: DomEditSelection,
+      operations: Parameters<typeof applyPatchByTarget>[2][],
+      options?: {
+        label?: string;
+        kind?: "manual" | "timeline" | "source" | "motion";
+        coalesceKey?: string;
+        skipRefresh?: boolean;
+        prepareContent?: (html: string, sourceFile: string) => string;
+        shouldSave?: () => boolean;
+      },
+    ) => {
+      const pid = projectIdRef.current;
+      if (!pid) throw new Error("No active project");
+      if (options?.shouldSave && !options.shouldSave()) return;
+
+      const targetPath = selection.sourceFile || activeCompPath || "index.html";
+      const response = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`);
+      if (!response.ok) {
+        throw new Error(`Failed to read ${targetPath}`);
+      }
+
+      const data = (await response.json()) as { content?: string };
+      const originalContent = data.content;
+      if (typeof originalContent !== "string") {
+        throw new Error(`Missing file contents for ${targetPath}`);
+      }
+
+      let patchedContent = originalContent;
+      for (const operation of operations) {
+        patchedContent = applyPatchByTarget(patchedContent, selection, operation);
+      }
+      if (options?.prepareContent) {
+        patchedContent = options.prepareContent(patchedContent, targetPath);
+      }
+      if (options?.shouldSave && !options.shouldSave()) return;
+
+      if (patchedContent === originalContent) {
+        throw new Error(`Unable to patch ${selection.selector ?? selection.id ?? "selection"}`);
+      }
+
+      await saveProjectFilesWithHistory({
+        projectId: pid,
+        label: options?.label ?? "Edit layer",
+        kind: options?.kind ?? "manual",
+        coalesceKey: options?.coalesceKey,
+        files: { [targetPath]: patchedContent },
+        readFile: async () => originalContent,
+        writeFile: writeProjectFile,
+        recordEdit: editHistory.recordEdit,
+      });
+
+      if (options?.skipRefresh) {
+        domEditSaveTimestampRef.current = Date.now();
+      } else {
+        setRefreshKey((k) => k + 1);
+      }
+    },
+    [activeCompPath, editHistory.recordEdit, writeProjectFile],
+  );
+
+  const handleDomMoveCommit = useCallback(
+    async (selection: DomEditSelection, next: { left: number; top: number }) => {
+      await persistDomEditOperations(
+        selection,
+        [
+          ...buildDomEditMovePatchOperations(next.left, next.top),
+          ...buildOppositeEdgePatchOperations(selection, "both"),
+        ],
+        {
+          skipRefresh: true,
+          label: "Move layer",
+          coalesceKey: getDomEditCoalesceKey(selection, "move"),
+        },
+      );
+    },
+    [persistDomEditOperations],
+  );
+
+  const handleDomResizeCommit = useCallback(
+    async (selection: DomEditSelection, next: { width: number; height: number }) => {
+      if (shouldDetachOppositeEdges(selection)) {
+        selection.element.style.right = "auto";
+        selection.element.style.bottom = "auto";
+      }
+      await persistDomEditOperations(
+        selection,
+        [
+          ...buildDomEditResizePatchOperations(next.width, next.height),
+          ...buildOppositeEdgePatchOperations(selection, "both"),
+        ],
+        {
+          skipRefresh: true,
+          label: "Resize layer",
+          coalesceKey: getDomEditCoalesceKey(selection, "resize"),
+        },
+      );
+    },
+    [persistDomEditOperations],
+  );
+
+  const handleDomDetachFromLayout = useCallback(async () => {
+    const selection = domEditSelection;
+    if (!selection?.capabilities.canDetachFromLayout) return;
+
+    const doc = previewIframeRef.current?.contentDocument;
+    const element = doc
+      ? findElementForSelection(doc, selection, selection.sourceFile)
+      : selection.element;
+    if (!element) {
+      showToast("Could not find the selected layer in the preview.", "info");
+      return;
+    }
+
+    const rect = measureDomDetachRect(element);
+    const operations = buildDomEditDetachPatchOperations(rect);
+
+    for (const operation of operations) {
+      element.style.setProperty(operation.property, operation.value);
+    }
+
+    await persistDomEditOperations(selection, operations, {
+      skipRefresh: true,
+      label: "Make layer movable",
+    });
+
+    const refreshed = doc ? findElementForSelection(doc, selection, selection.sourceFile) : element;
+    if (refreshed) {
+      const nextSelection = buildDomSelectionFromTarget(refreshed);
+      if (nextSelection) {
+        applyDomSelection(nextSelection, { revealPanel: false });
+      }
+    }
+    showToast("Layer detached from layout. You can move it now.", "info");
+  }, [
+    applyDomSelection,
+    buildDomSelectionFromTarget,
+    domEditSelection,
+    persistDomEditOperations,
+    showToast,
+  ]);
+
+  const handleDomStyleCommit = useCallback(
+    async (property: string, value: string) => {
+      if (!domEditSelection) return;
+      const isMoveStyle = isMoveStyleProperty(property);
+      const isResizeStyle = isResizeStyleProperty(property);
+      if (isMoveStyle && !domEditSelection.capabilities.canMove) return;
+      if (isResizeStyle && !domEditSelection.capabilities.canResize) return;
+      if (!isMoveStyle && !isResizeStyle && !domEditSelection.capabilities.canEditStyles) return;
+      const importedFont = property === "font-family" ? resolveImportedFontAsset(value) : null;
+      const iframe = previewIframeRef.current;
+      const doc = iframe?.contentDocument;
+      let liveElement: HTMLElement | null = null;
+      if (doc) {
+        const el = findElementForSelection(doc, domEditSelection, domEditSelection.sourceFile);
+        if (el) {
+          liveElement = el;
+          el.style.setProperty(property, normalizeDomEditStyleValue(property, value));
+          if (property === "font-family") {
+            injectPreviewGoogleFont(doc, value);
+            if (importedFont) injectPreviewImportedFont(doc, importedFont);
+          }
+          if (shouldDetachOppositeEdges(domEditSelection)) {
+            if (property === "width") el.style.right = "auto";
+            if (property === "height") el.style.bottom = "auto";
+          }
+          if (property === "background-image" && isImageBackgroundValue(value)) {
+            el.style.setProperty("background-position", "center");
+            el.style.setProperty("background-repeat", "no-repeat");
+            el.style.setProperty("background-size", "contain");
+          }
+        }
+      }
+      const operations: PatchOperation[] = [
+        buildDomEditStylePatchOperation(property, normalizeDomEditStyleValue(property, value)),
+      ];
+      if (property === "width") {
+        operations.push(...buildOppositeEdgePatchOperations(domEditSelection, "width"));
+      } else if (property === "height") {
+        operations.push(...buildOppositeEdgePatchOperations(domEditSelection, "height"));
+      } else if (property === "background-image" && isImageBackgroundValue(value)) {
+        operations.push(
+          buildDomEditStylePatchOperation("background-position", "center"),
+          buildDomEditStylePatchOperation("background-repeat", "no-repeat"),
+          buildDomEditStylePatchOperation("background-size", "contain"),
+        );
+      }
+      await persistDomEditOperations(domEditSelection, operations, {
+        label: "Edit layer style",
+        skipRefresh: true,
+        prepareContent: importedFont
+          ? (html, sourceFile) => ensureImportedFontFace(html, importedFont, sourceFile)
+          : undefined,
+      });
+      if (doc && liveElement) {
+        const refreshed = findElementForSelection(
+          doc,
+          domEditSelection,
+          domEditSelection.sourceFile,
+        );
+        if (refreshed) {
+          const nextSelection = buildDomSelectionFromTarget(refreshed);
+          if (nextSelection) {
+            applyDomSelection(nextSelection, { revealPanel: false });
+          }
+          revealTimelineLayerElement(refreshed, { preferStoredTime: true, settle: true });
+        }
+      }
+    },
+    [
+      applyDomSelection,
+      buildDomSelectionFromTarget,
+      domEditSelection,
+      persistDomEditOperations,
+      resolveImportedFontAsset,
+      revealTimelineLayerElement,
+    ],
+  );
+
+  const handleDomMotionCommit = useCallback(
+    async (motion: MotionDraft | null) => {
+      if (!domEditSelection) return;
+      if (!domEditSelection.capabilities.canEditStyles) return;
+
+      const nextMotion = motion
+        ? clampMotionDraftToTimeline(motion, selectedMotionMaxDuration)
+        : null;
+      const motionVarsId = buildMotionVarsId(
+        domEditSelection.id || domEditSelection.selector || domEditSelection.label,
+      );
+      const operations = buildDomEditMotionPatchOperations(nextMotion, motionVarsId);
+      const iframe = previewIframeRef.current;
+      const doc = iframe?.contentDocument;
+      let refreshedElement: HTMLElement | null = null;
+
+      if (doc) {
+        const el = findElementForSelection(doc, domEditSelection, domEditSelection.sourceFile);
+        if (el) {
+          for (const operation of operations) {
+            const attr = operation.property.startsWith("data-")
+              ? operation.property
+              : `data-${operation.property}`;
+            if (operation.value == null) {
+              el.removeAttribute(attr);
+            } else {
+              el.setAttribute(attr, operation.value);
+            }
+          }
+          refreshedElement = el;
+          const player = getPreviewPlayer(iframe.contentWindow);
+          if (player) {
+            player.renderSeek(player.getTime());
+          }
+        }
+      }
+
+      await persistDomEditOperations(domEditSelection, operations, {
+        label: nextMotion ? "Edit layer motion" : "Clear layer motion",
+        kind: "motion",
+        coalesceKey: getDomEditCoalesceKey(domEditSelection, "motion"),
+        skipRefresh: true,
+      });
+
+      if (refreshedElement) {
+        const nextSelection = buildDomSelectionFromTarget(refreshedElement);
+        if (nextSelection) {
+          applyDomSelection(nextSelection, { revealPanel: false });
+        }
+      }
+    },
+    [
+      applyDomSelection,
+      buildDomSelectionFromTarget,
+      domEditSelection,
+      persistDomEditOperations,
+      selectedMotionMaxDuration,
+    ],
+  );
+
+  const handleDomTextCommit = useCallback(
+    async (value: string, fieldKey?: string) => {
+      if (!domEditSelection) return;
+      if (!isTextEditableSelection(domEditSelection)) return;
+      const commitVersion = domTextCommitVersionRef.current + 1;
+      domTextCommitVersionRef.current = commitVersion;
+      const nextTextFields =
+        domEditSelection.textFields.length > 0
+          ? domEditSelection.textFields.map((field) =>
+              field.key === fieldKey ? { ...field, value } : field,
+            )
+          : [];
+      const nextContent =
+        nextTextFields.length > 1 || nextTextFields.some((field) => field.source === "child")
+          ? serializeDomEditTextFields(nextTextFields)
+          : value;
+      const iframe = previewIframeRef.current;
+      const doc = iframe?.contentDocument;
+      if (doc) {
+        const el = findElementForSelection(doc, domEditSelection, domEditSelection.sourceFile);
+        if (el) {
+          if (
+            nextTextFields.length > 1 ||
+            nextTextFields.some((field) => field.source === "child")
+          ) {
+            el.innerHTML = nextContent;
+          } else {
+            el.textContent = value;
+          }
+        }
+      }
+      await persistDomEditOperations(
+        domEditSelection,
+        [buildDomEditTextPatchOperation(nextContent)],
+        {
+          label: "Edit text",
+          skipRefresh: true,
+          shouldSave: () => domTextCommitVersionRef.current === commitVersion,
+        },
+      );
+      if (domTextCommitVersionRef.current !== commitVersion) return;
+
+      if (doc) {
+        const refreshed = findElementForSelection(
+          doc,
+          domEditSelection,
+          domEditSelection.sourceFile,
+        );
+        if (refreshed) {
+          const nextSelection = buildDomSelectionFromTarget(refreshed);
+          if (nextSelection) {
+            applyDomSelection(nextSelection, { revealPanel: false });
+          }
+          revealTimelineLayerElement(refreshed, { preferStoredTime: true, settle: true });
+        }
+      }
+    },
+    [
+      applyDomSelection,
+      buildDomSelectionFromTarget,
+      domEditSelection,
+      persistDomEditOperations,
+      revealTimelineLayerElement,
+    ],
+  );
+
+  const commitDomTextFields = useCallback(
+    async (
+      selection: DomEditSelection,
+      nextTextFields: DomEditTextField[],
+      options?: { importedFont?: ImportedFontAsset | null },
+    ) => {
+      const nextContent =
+        nextTextFields.length > 1 || nextTextFields.some((field) => field.source === "child")
+          ? serializeDomEditTextFields(nextTextFields)
+          : (nextTextFields[0]?.value ?? "");
+
+      const iframe = previewIframeRef.current;
+      const doc = iframe?.contentDocument;
+      if (doc) {
+        const el = findElementForSelection(doc, selection, selection.sourceFile);
+        if (el) {
+          if (
+            nextTextFields.length > 1 ||
+            nextTextFields.some((field) => field.source === "child")
+          ) {
+            el.innerHTML = nextContent;
+          } else {
+            el.textContent = nextContent;
+          }
+        }
+      }
+
+      const importedFont = options?.importedFont ?? null;
+      await persistDomEditOperations(selection, [buildDomEditTextPatchOperation(nextContent)], {
+        label: "Edit text",
+        skipRefresh: true,
+        prepareContent: importedFont
+          ? (html, sourceFile) => ensureImportedFontFace(html, importedFont, sourceFile)
+          : undefined,
+      });
+
+      if (doc) {
+        const refreshed = findElementForSelection(doc, selection, selection.sourceFile);
+        if (refreshed) {
+          const nextSelection = buildDomSelectionFromTarget(refreshed);
+          if (nextSelection) {
+            applyDomSelection(nextSelection, { revealPanel: false });
+          }
+          revealTimelineLayerElement(refreshed, { preferStoredTime: true, settle: true });
+        }
+      }
+    },
+    [
+      applyDomSelection,
+      buildDomSelectionFromTarget,
+      persistDomEditOperations,
+      revealTimelineLayerElement,
+    ],
+  );
+
+  const handleDomTextFieldStyleCommit = useCallback(
+    async (fieldKey: string, property: string, value: string) => {
+      if (!domEditSelection) return;
+      const field = domEditSelection.textFields.find((entry) => entry.key === fieldKey);
+      if (!field) return;
 
-      const saveResponse = await fetch(
-        `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
-        {
-          method: "PUT",
-          headers: { "Content-Type": "text/plain" },
-          body: patchedContent,
-        },
-      );
-      if (!saveResponse.ok) {
-        throw new Error(`Failed to save ${targetPath}`);
+      if (field.source === "self") {
+        await handleDomStyleCommit(property, value);
+        return;
       }
 
-      if (editingPathRef.current === targetPath) {
-        setEditingFile({ path: targetPath, content: patchedContent });
+      const normalizedValue = normalizeDomEditStyleValue(property, value);
+      const importedFont = property === "font-family" ? resolveImportedFontAsset(value) : null;
+      if (property === "font-family") {
+        const doc = previewIframeRef.current?.contentDocument;
+        if (doc) {
+          injectPreviewGoogleFont(doc, normalizedValue);
+          if (importedFont) injectPreviewImportedFont(doc, importedFont);
+        }
       }
+      const nextTextFields = domEditSelection.textFields.map((entry) =>
+        entry.key === fieldKey
+          ? {
+              ...entry,
+              inlineStyles: {
+                ...entry.inlineStyles,
+                [property]: normalizedValue,
+              },
+              computedStyles: {
+                ...entry.computedStyles,
+                [property]: normalizedValue,
+              },
+            }
+          : entry,
+      );
 
-      setRefreshKey((k) => k + 1);
+      await commitDomTextFields(domEditSelection, nextTextFields, { importedFont });
     },
-    [activeCompPath],
+    [commitDomTextFields, domEditSelection, handleDomStyleCommit, resolveImportedFontAsset],
   );
 
-  const showToast = useCallback((message: string, tone: AppToast["tone"] = "error") => {
-    if (toastTimerRef.current) clearTimeout(toastTimerRef.current);
-    setAppToast({ message, tone });
-    toastTimerRef.current = setTimeout(() => setAppToast(null), 4000);
-  }, []);
+  const handleDomAddTextField = useCallback(
+    async (afterFieldKey?: string) => {
+      if (!domEditSelection) return null;
+      if (!domEditSelection.textFields.some((field) => field.source === "child")) return null;
 
-  const handleCaptureFrameClick = useCallback(
-    async (event: MouseEvent<HTMLAnchorElement>) => {
-      if (!projectId) return;
-      event.preventDefault();
+      const insertionIndex = domEditSelection.textFields.findIndex(
+        (field) => field.key === afterFieldKey,
+      );
+      const baseField =
+        domEditSelection.textFields[insertionIndex >= 0 ? insertionIndex : 0] ??
+        domEditSelection.textFields[0];
+      const nextField = buildDefaultDomEditTextField(baseField);
+      const nextTextFields = [...domEditSelection.textFields];
+      nextTextFields.splice(
+        insertionIndex >= 0 ? insertionIndex + 1 : nextTextFields.length,
+        0,
+        nextField,
+      );
 
-      const currentTime = usePlayerStore.getState().currentTime;
-      setCaptureFrameTime(currentTime);
-      const href = buildFrameCaptureUrl({
-        projectId,
-        compositionPath: activeCompPath,
+      await commitDomTextFields(domEditSelection, nextTextFields);
+      return nextField.key;
+    },
+    [commitDomTextFields, domEditSelection],
+  );
+
+  const handleDomRemoveTextField = useCallback(
+    async (fieldKey: string) => {
+      if (!domEditSelection) return;
+      const field = domEditSelection.textFields.find((entry) => entry.key === fieldKey);
+      if (!field) return;
+
+      if (field.source === "self") {
+        await handleDomTextCommit("", fieldKey);
+        return;
+      }
+
+      const nextTextFields = domEditSelection.textFields.filter((entry) => entry.key !== fieldKey);
+      await commitDomTextFields(domEditSelection, nextTextFields);
+    },
+    [commitDomTextFields, domEditSelection, handleDomTextCommit],
+  );
+
+  const handleAskAgent = useCallback(() => {
+    if (!domEditSelection) return;
+    setAgentPromptTagSnippet(undefined);
+    void preloadAgentPromptSnippet(domEditSelection);
+    setAgentModalOpen(true);
+  }, [domEditSelection, preloadAgentPromptSnippet]);
+
+  const handleAgentModalSubmit = useCallback(
+    async (userInstruction: string) => {
+      if (!domEditSelection) return;
+
+      const targetPath = domEditSelection.sourceFile || activeCompPath || "index.html";
+      const tagSnippet = agentPromptTagSnippet ?? domEditSelection.element.outerHTML;
+      const hfMotionAttribute = domEditSelection.dataAttributes["hf-motion"];
+      const motionOwnership = detectMotionOwnership({
+        element: domEditSelection.element,
+        dataAttributes: domEditSelection.dataAttributes,
+        computedStyles: domEditSelection.computedStyles,
+      });
+      const parsedMotionDraft = parseMotionDraft(hfMotionAttribute);
+      const motionContext =
+        hfMotionAttribute || motionOwnership.badges.length > 0
+          ? buildMotionAgentContext({
+              hfMotionAttribute,
+              draft: parsedMotionDraft
+                ? clampMotionDraftToTimeline(parsedMotionDraft, selectedMotionMaxDuration)
+                : null,
+              ownership: motionOwnership,
+            })
+          : undefined;
+      const prompt = buildElementAgentPrompt({
+        selection: domEditSelection,
         currentTime,
+        tagSnippet,
+        userInstruction,
+        sourceFilePath: toProjectAbsolutePath(projectDir, targetPath),
+        motionContext,
       });
-      const filename = buildFrameCaptureFilename(activeCompPath, currentTime);
 
-      try {
-        const response = await fetch(href, { cache: "no-store" });
-        if (!response.ok) {
-          throw new Error(`Capture failed (${response.status})`);
-        }
-        const blob = await response.blob();
-        const blobUrl = URL.createObjectURL(blob);
-        const link = document.createElement("a");
-        link.href = blobUrl;
-        link.download = filename;
-        document.body.appendChild(link);
-        link.click();
-        link.remove();
-        setTimeout(() => URL.revokeObjectURL(blobUrl), 0);
-      } catch (err) {
-        const message = err instanceof Error ? err.message : "Capture failed";
-        showToast(message);
+      const copied = await copyTextToClipboard(prompt);
+      if (!copied) {
+        showToast("Could not copy prompt to clipboard.", "error");
+        return;
       }
+
+      setAgentModalOpen(false);
+      if (copiedAgentTimerRef.current) clearTimeout(copiedAgentTimerRef.current);
+      setCopiedAgentPrompt(true);
+      copiedAgentTimerRef.current = setTimeout(() => setCopiedAgentPrompt(false), 1600);
     },
-    [activeCompPath, projectId, showToast],
+    [
+      activeCompPath,
+      agentPromptTagSnippet,
+      currentTime,
+      domEditSelection,
+      projectDir,
+      selectedMotionMaxDuration,
+      showToast,
+    ],
   );
 
-  const handleTimelineElementDelete = useCallback(
-    async (element: TimelineElement) => {
-      const pid = projectIdRef.current;
-      if (!pid) throw new Error("No active project");
+  const handleCopyElementLocator = useCallback(async () => {
+    if (!domEditSelection) return;
 
-      const targetPath = element.sourceFile || activeCompPath || "index.html";
+    const pid = projectIdRef.current;
+    const targetPath = domEditSelection.sourceFile || activeCompPath || "index.html";
+    const absolutePath = toProjectAbsolutePath(projectDir, targetPath) ?? targetPath;
+    let sourceLocation: NonNullable<ReturnType<typeof findSourceLocationByTarget>> | null = null;
+
+    if (pid) {
       try {
         const response = await fetch(
           `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
         );
-        if (!response.ok) {
-          throw new Error(`Failed to read ${targetPath}`);
+        if (response.ok) {
+          const data = (await response.json()) as { content?: string };
+          if (typeof data.content === "string") {
+            sourceLocation = findSourceLocationByTarget(data.content, domEditSelection);
+          }
         }
+      } catch {
+        // The absolute file path and DOM selector still make a useful locator.
+      }
+    }
 
-        const data = (await response.json()) as { content?: string };
-        const originalContent = data.content;
-        if (typeof originalContent !== "string") {
-          throw new Error(`Missing file contents for ${targetPath}`);
-        }
+    const locator = formatElementLocatorClipboardText({
+      selection: domEditSelection,
+      absolutePath,
+      sourceLocation,
+      currentTime,
+    });
+    const copied = await copyTextToClipboard(locator);
+    if (!copied) {
+      showToast("Could not copy element location to clipboard.", "error");
+      return;
+    }
 
-        const patchTarget = element.domId
-          ? { id: element.domId, selector: element.selector, selectorIndex: element.selectorIndex }
-          : element.selector
-            ? { selector: element.selector, selectorIndex: element.selectorIndex }
-            : null;
-        if (!patchTarget) {
-          throw new Error(`Timeline element ${element.id} is missing a patchable target`);
-        }
+    if (copiedElementLocatorTimerRef.current) {
+      clearTimeout(copiedElementLocatorTimerRef.current);
+    }
+    setCopiedElementLocator(true);
+    copiedElementLocatorTimerRef.current = setTimeout(() => setCopiedElementLocator(false), 1600);
+    showToast("Copied element location.", "info");
+  }, [activeCompPath, currentTime, domEditSelection, projectDir, showToast]);
 
-        const resolvedTargetPath = targetPath || "index.html";
-        const remainingElements = timelineElements.filter(
-          (timelineElement) =>
-            (timelineElement.key ?? timelineElement.id) !== (element.key ?? element.id) &&
-            (timelineElement.sourceFile || activeCompPath || "index.html") === resolvedTargetPath,
-        );
-        const trackZIndices = buildTrackZIndexMap(
-          remainingElements.map((timelineElement) => timelineElement.track),
-        );
+  const handlePreviewIframeRef = useCallback(
+    (iframe: HTMLIFrameElement | null) => {
+      previewIframeRef.current = iframe;
+      setPreviewIframe(iframe);
+      refreshPreviewDocumentVersion();
+      syncPreviewTimelineHotkey(iframe);
+      consoleErrorsRef.current = [];
+      setConsoleErrors(null);
+    },
+    [refreshPreviewDocumentVersion, syncPreviewTimelineHotkey],
+  );
 
-        const removeResponse = await fetch(
-          `/api/projects/${pid}/file-mutations/remove-element/${encodeURIComponent(targetPath)}`,
-          {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ target: patchTarget }),
-          },
-        );
-        if (!removeResponse.ok) {
-          throw new Error(`Failed to delete ${element.id} from ${targetPath}`);
-        }
+  const handlePreviewCanvasMouseDown = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>, _options?: { preferClipAncestor?: boolean }) => {
+      if (captionEditMode) return;
+      if (inspectedTimelineElementId) {
+        e.preventDefault();
+        e.stopPropagation();
+      }
+      lastPreviewClickRef.current = null;
+    },
+    [captionEditMode, inspectedTimelineElementId],
+  );
 
-        const removeData = (await removeResponse.json()) as {
-          changed?: boolean;
-          content?: string;
-        };
-        let patchedContent =
-          typeof removeData.content === "string" ? removeData.content : originalContent;
-        for (const timelineElement of remainingElements) {
-          const elementTarget = timelineElement.domId
-            ? {
-                id: timelineElement.domId,
-                selector: timelineElement.selector,
-                selectorIndex: timelineElement.selectorIndex,
-              }
-            : timelineElement.selector
-              ? {
-                  selector: timelineElement.selector,
-                  selectorIndex: timelineElement.selectorIndex,
-                }
-              : null;
-          if (!elementTarget) continue;
-          const nextZIndex = trackZIndices.get(timelineElement.track);
-          if (nextZIndex == null) continue;
-          patchedContent = applyPatchByTarget(patchedContent, elementTarget, {
-            type: "inline-style",
-            property: "z-index",
-            value: String(nextZIndex),
-          });
-        }
+  const handlePreviewCanvasDoubleClick = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>) => {
+      if (captionEditMode) return;
+      if (inspectedTimelineElementId) {
+        e.preventDefault();
+        e.stopPropagation();
+      }
+      lastPreviewClickRef.current = null;
+    },
+    [captionEditMode, inspectedTimelineElementId],
+  );
 
-        const saveResponse = await fetch(
-          `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
-          {
-            method: "PUT",
-            headers: { "Content-Type": "text/plain" },
-            body: patchedContent,
-          },
-        );
-        if (!saveResponse.ok) {
-          throw new Error(`Failed to save ${targetPath}`);
-        }
+  const handleSelectedOverlayDoubleClick = useCallback(() => {
+    const selection = domEditSelectionRef.current;
+    if (!selection?.isCompositionHost || !selection.compositionSrc) return;
+    applyDomSelection(null, { revealPanel: false });
+    setActiveCompPath(selection.compositionSrc);
+  }, [applyDomSelection]);
 
-        if (editingPathRef.current === targetPath) {
-          setEditingFile({ path: targetPath, content: patchedContent });
-        }
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!previewIframe || captionEditMode) return;
 
-        usePlayerStore
-          .getState()
-          .setElements(
-            timelineElements.filter(
-              (timelineElement) =>
-                (timelineElement.key ?? timelineElement.id) !== (element.key ?? element.id),
-            ),
-          );
-        usePlayerStore.getState().setSelectedElementId(null);
-        setRefreshKey((k) => k + 1);
-      } catch (error) {
-        const message = error instanceof Error ? error.message : "Failed to delete timeline clip";
-        showToast(message);
+    const syncSelectionFromDocument = () => {
+      const currentSelection = domEditSelectionRef.current;
+      if (!currentSelection) return;
+      let doc: Document | null = null;
+      try {
+        doc = previewIframe.contentDocument;
+      } catch {
+        return;
+      }
+      if (!doc) return;
+
+      const syncCompositionPath = inspectedTimelineElementId
+        ? layerInspectionCompositionPath
+        : activeCompPath;
+      const nextElement = findElementForSelection(doc, currentSelection, syncCompositionPath);
+      if (!nextElement) {
+        applyDomSelection(null, { revealPanel: false });
+        return;
       }
-    },
-    [activeCompPath, showToast, timelineElements],
-  );
 
-  const handleBlockedTimelineEdit = useCallback(
-    (_element: TimelineElement) => {
-      const now = Date.now();
-      if (now - lastBlockedTimelineToastAtRef.current < 1500) return;
-      lastBlockedTimelineToastAtRef.current = now;
-      showToast("This clip can’t be moved or resized from the timeline yet.", "info");
+      const nextSelection = inspectedTimelineElementId
+        ? (resolveDomEditSelection(nextElement, {
+            activeCompositionPath: layerInspectionCompositionPath,
+            isMasterView: false,
+            preferClipAncestor: false,
+          }) ?? buildDomSelectionFromTarget(nextElement))
+        : buildDomSelectionFromTarget(nextElement);
+      if (nextSelection) {
+        applyDomSelection(nextSelection, { revealPanel: false });
+      }
+    };
+
+    const attachErrorCapture = () => {
+      try {
+        const win = previewIframe.contentWindow as (Window & typeof globalThis) | null;
+        if (!win) return;
+        if ((win as unknown as Record<string, unknown>).__hfErrorCapture) return;
+        (win as unknown as Record<string, unknown>).__hfErrorCapture = true;
+        const origError = win.console.error.bind(win.console);
+        win.console.error = function (...args: unknown[]) {
+          origError(...args);
+          const text = args.map((a) => (a instanceof Error ? a.message : String(a))).join(" ");
+          if (text.includes("favicon")) return;
+          consoleErrorsRef.current = [
+            ...consoleErrorsRef.current,
+            { severity: "error", message: text },
+          ];
+          setConsoleErrors([...consoleErrorsRef.current]);
+        };
+        win.addEventListener("error", (e: ErrorEvent) => {
+          const text = e.message || String(e);
+          consoleErrorsRef.current = [
+            ...consoleErrorsRef.current,
+            { severity: "error", message: text },
+          ];
+          setConsoleErrors([...consoleErrorsRef.current]);
+        });
+      } catch {
+        // same-origin only
+      }
+    };
+
+    attachErrorCapture();
+    syncSelectionFromDocument();
+
+    const handleLoad = () => {
+      consoleErrorsRef.current = [];
+      setConsoleErrors(null);
+      refreshPreviewDocumentVersion();
+      attachErrorCapture();
+      syncSelectionFromDocument();
+    };
+
+    previewIframe.addEventListener("load", handleLoad);
+    return () => {
+      previewIframe.removeEventListener("load", handleLoad);
+    };
+  }, [
+    activeCompPath,
+    applyDomSelection,
+    buildDomSelectionFromTarget,
+    captionEditMode,
+    inspectedTimelineElementId,
+    layerInspectionCompositionPath,
+    previewIframe,
+    refreshPreviewDocumentVersion,
+  ]);
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!captionEditMode) return;
+    applyDomSelection(null, { revealPanel: false });
+  }, [applyDomSelection, captionEditMode]);
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(
+    () => () => {
+      if (copiedAgentTimerRef.current) clearTimeout(copiedAgentTimerRef.current);
+      if (copiedElementLocatorTimerRef.current) {
+        clearTimeout(copiedElementLocatorTimerRef.current);
+      }
     },
-    [showToast],
+    [],
   );
 
   const refreshFileTree = useCallback(async () => {
@@ -1137,24 +3206,19 @@ export function StudioApp() {
             duration: normalizedDuration,
             track: placement.track,
             zIndex: trackZIndices.get(placement.track) ?? 1,
+            geometry: resolveTimelineAssetInitialGeometry(originalContent),
           }),
         );
 
-        const saveResponse = await fetch(
-          `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
-          {
-            method: "PUT",
-            headers: { "Content-Type": "text/plain" },
-            body: patchedContent,
-          },
-        );
-        if (!saveResponse.ok) {
-          throw new Error(`Failed to save ${targetPath}`);
-        }
-
-        if (editingPathRef.current === targetPath) {
-          setEditingFile({ path: targetPath, content: patchedContent });
-        }
+        await saveProjectFilesWithHistory({
+          projectId: pid,
+          label: "Add timeline asset",
+          kind: "timeline",
+          files: { [targetPath]: patchedContent },
+          readFile: async () => originalContent,
+          writeFile: writeProjectFile,
+          recordEdit: editHistory.recordEdit,
+        });
 
         setRefreshKey((k) => k + 1);
       } catch (error) {
@@ -1163,7 +3227,7 @@ export function StudioApp() {
         showToast(message);
       }
     },
-    [activeCompPath, showToast, timelineElements],
+    [activeCompPath, editHistory.recordEdit, showToast, timelineElements, writeProjectFile],
   );
 
   const handleTimelineFileDrop = useCallback(
@@ -1321,7 +3385,33 @@ export function StudioApp() {
 
   const handleImportFiles = useCallback(
     async (files: FileList | File[], dir?: string) => {
-      void uploadProjectFiles(Array.from(files), dir);
+      return uploadProjectFiles(Array.from(files), dir);
+    },
+    [uploadProjectFiles],
+  );
+
+  const handleImportFonts = useCallback(
+    async (files: FileList | File[]) => {
+      const uploaded = await uploadProjectFiles(
+        Array.from(files).filter((file) => FONT_EXT.test(file.name)),
+        "assets/fonts",
+      );
+      const pid = projectIdRef.current;
+      const imported = uploaded
+        .filter((asset) => FONT_EXT.test(asset))
+        .map((asset) => ({
+          family: fontFamilyFromAssetPath(asset),
+          path: asset,
+          url: `/api/projects/${pid}/preview/${asset}`,
+        }));
+      importedFontAssetsRef.current = [
+        ...imported,
+        ...importedFontAssetsRef.current.filter(
+          (existing) =>
+            !imported.some((font) => font.family.toLowerCase() === existing.family.toLowerCase()),
+        ),
+      ];
+      return imported;
     },
     [uploadProjectFiles],
   );
@@ -1393,6 +3483,17 @@ export function StudioApp() {
       fileTree.filter((f) => !f.endsWith(".html") && !f.endsWith(".md") && !f.endsWith(".json")),
     [fileTree],
   );
+  const fontAssets = useMemo<ImportedFontAsset[]>(
+    () =>
+      assets
+        .filter((asset) => FONT_EXT.test(asset))
+        .map((asset) => ({
+          family: fontFamilyFromAssetPath(asset),
+          path: asset,
+          url: `/api/projects/${projectId}/preview/${asset}`,
+        })),
+    [assets, projectId],
+  );
 
   if (resolving || !projectId) {
     return (
@@ -1438,6 +3539,42 @@ export function StudioApp() {
         </div>
         {/* Right: toolbar buttons */}
         <div className="flex items-center gap-1.5">
+          <button
+            type="button"
+            onClick={() => void handleUndo()}
+            disabled={!editHistory.canUndo}
+            className={`h-7 w-7 flex items-center justify-center rounded-md border transition-colors ${
+              editHistory.canUndo
+                ? "border-neutral-700 text-neutral-300 hover:border-neutral-500 hover:bg-neutral-800"
+                : "border-neutral-900 text-neutral-700"
+            }`}
+            title={
+              editHistory.undoLabel
+                ? `Undo ${editHistory.undoLabel} (${getHistoryShortcutLabel("undo")})`
+                : `Undo (${getHistoryShortcutLabel("undo")})`
+            }
+            aria-label="Undo"
+          >
+            <RotateCcw size={14} />
+          </button>
+          <button
+            type="button"
+            onClick={() => void handleRedo()}
+            disabled={!editHistory.canRedo}
+            className={`h-7 w-7 flex items-center justify-center rounded-md border transition-colors ${
+              editHistory.canRedo
+                ? "border-neutral-700 text-neutral-300 hover:border-neutral-500 hover:bg-neutral-800"
+                : "border-neutral-900 text-neutral-700"
+            }`}
+            title={
+              editHistory.redoLabel
+                ? `Redo ${editHistory.redoLabel} (${getHistoryShortcutLabel("redo")})`
+                : `Redo (${getHistoryShortcutLabel("redo")})`
+            }
+            aria-label="Redo"
+          >
+            <RotateCw size={14} />
+          </button>
           <a
             href={captureFrameHref}
             download={captureFrameFilename}
@@ -1452,7 +3589,15 @@ export function StudioApp() {
             <span>Capture</span>
           </a>
           <button
-            onClick={() => setRightCollapsed((v) => !v)}
+            onClick={() => {
+              if (rightCollapsed || rightPanelTab !== "design") {
+                setRightPanelTab("design");
+                setRightCollapsed(false);
+                return;
+              }
+              clearDomSelection();
+              setRightCollapsed(true);
+            }}
             className={`h-7 flex items-center gap-1.5 px-2.5 rounded-md text-[11px] font-medium border transition-colors ${
               !rightCollapsed
                 ? "text-studio-accent bg-studio-accent/10 border-studio-accent/30"
@@ -1470,8 +3615,7 @@ export function StudioApp() {
               <circle cx="12" cy="12" r="10" />
               <polygon points="10 8 16 12 10 16" fill="currentColor" stroke="none" />
             </svg>
-            Renders
-            {renderQueue.jobs.length > 0 ? ` (${renderQueue.jobs.length})` : ""}
+            Inspector
           </button>
         </div>
       </div>
@@ -1510,22 +3654,9 @@ export function StudioApp() {
             projectId={projectId}
             compositions={compositions}
             assets={assets}
-            activeComposition={editingFile?.path ?? null}
-            onSelectComposition={(comp) => {
-              // Set active composition for preview drill-down
-              // Don't increment refreshKey — that reloads the master iframe and
-              // overrides the composition navigation. Let activeCompositionPath
-              // handle the preview change via the composition stack.
-              setActiveCompPath(
-                comp === "index.html" || comp.startsWith("compositions/") ? comp : null,
-              );
-              // Load file content for code editor
-              setEditingFile({ path: comp, content: null });
-              fetch(`/api/projects/${projectId}/files/${comp}`)
-                .then((r) => r.json())
-                .then((data) => setEditingFile({ path: comp, content: data.content }))
-                .catch(() => {});
-            }}
+            activeComposition={activeCompPath ?? editingFile?.path ?? null}
+            onSelectComposition={handleCompositionSelect}
+            resolveCompositionSourceContent={readProjectFile}
             fileTree={fileTree}
             editingFile={editingFile}
             onSelectFile={handleFileSelect}
@@ -1575,69 +3706,56 @@ export function StudioApp() {
             refreshKey={refreshKey}
             activeCompositionPath={activeCompPath}
             timelineToolbar={timelineToolbar}
-            renderClipContent={renderClipContent}
             onDeleteElement={handleTimelineElementDelete}
             onAssetDrop={handleTimelineAssetDrop}
             onFileDrop={handleTimelineFileDrop}
             onMoveElement={handleTimelineElementMove}
             onResizeElement={handleTimelineElementResize}
             onBlockedEditAttempt={handleBlockedTimelineEdit}
+            onSelectTimelineElement={handleTimelineElementSelect}
+            onInspectTimelineElement={handleTimelineElementInspect}
+            inspectedTimelineElementId={inspectedTimelineElementId}
+            timelineLayerChildCounts={timelineLayerChildCounts}
+            thumbnailedTimelineElementIds={thumbnailedTimelineElementIds}
+            onToggleTimelineElementThumbnail={handleTimelineElementThumbnailToggle}
             onCompIdToSrcChange={setCompIdToSrc}
+            renderClipContent={renderTimelineClipContent}
             onCompositionChange={(compPath) => {
               // Sync activeCompPath when user drills down via timeline double-click
               // or navigates back via breadcrumb — keeps sidebar + thumbnails in sync.
               setActiveCompPath(compPath);
             }}
-            onIframeRef={(iframe) => {
-              previewIframeRef.current = iframe;
-              syncPreviewTimelineHotkey(iframe);
-              consoleErrorsRef.current = [];
-              setConsoleErrors(null);
-              if (!iframe) return;
-
-              // Attach error capture after each iframe load (content resets on navigation)
-              const attachErrorCapture = () => {
-                try {
-                  const win = iframe.contentWindow as (Window & typeof globalThis) | null;
-                  if (!win) return;
-                  // Guard against double-patching
-                  if ((win as unknown as Record<string, unknown>).__hfErrorCapture) return;
-                  (win as unknown as Record<string, unknown>).__hfErrorCapture = true;
-                  const origError = win.console.error.bind(win.console);
-                  win.console.error = function (...args: unknown[]) {
-                    origError(...args);
-                    const text = args
-                      .map((a) => (a instanceof Error ? a.message : String(a)))
-                      .join(" ");
-                    if (text.includes("favicon")) return;
-                    consoleErrorsRef.current = [
-                      ...consoleErrorsRef.current,
-                      { severity: "error", message: text },
-                    ];
-                    setConsoleErrors([...consoleErrorsRef.current]);
-                  };
-                  win.addEventListener("error", (e: ErrorEvent) => {
-                    const text = e.message || String(e);
-                    consoleErrorsRef.current = [
-                      ...consoleErrorsRef.current,
-                      { severity: "error", message: text },
-                    ];
-                    setConsoleErrors([...consoleErrorsRef.current]);
-                  });
-                } catch {
-                  // cross-origin — can't attach
-                }
-              };
-              // Attach now (iframe may already be loaded) and on future loads
-              attachErrorCapture();
-              iframe.addEventListener("load", () => {
-                consoleErrorsRef.current = [];
-                setConsoleErrors(null);
-                attachErrorCapture();
-              });
-            }}
+            onIframeRef={handlePreviewIframeRef}
             previewOverlay={
-              captionEditMode ? <CaptionOverlay iframeRef={previewIframeRef} /> : undefined
+              captionEditMode ? (
+                <CaptionOverlay iframeRef={previewIframeRef} />
+              ) : (
+                <>
+                  <DomEditOverlay
+                    iframeRef={previewIframeRef}
+                    selection={showDomEditSelectionOverlay ? domEditSelection : null}
+                    onCanvasMouseDown={handlePreviewCanvasMouseDown}
+                    onCanvasDoubleClick={handlePreviewCanvasDoubleClick}
+                    onSelectedDoubleClick={handleSelectedOverlayDoubleClick}
+                    onBlockedMove={handleBlockedDomMove}
+                    onMoveCommit={handleDomMoveCommit}
+                    onResizeCommit={handleDomResizeCommit}
+                  />
+                  {inspectedTimelineElement && inspectedTimelineLayers.length > 0 && (
+                    <TimelineLayerPanel
+                      clipLabel={
+                        inspectedTimelineElement.label ||
+                        inspectedTimelineElement.id ||
+                        inspectedTimelineElement.tag
+                      }
+                      layers={inspectedTimelineLayers}
+                      selectedLayerKey={selectedTimelineLayerKey}
+                      onSelectLayer={handleTimelineLayerSelect}
+                      onClose={handleTimelineLayerPanelClose}
+                    />
+                  )}
+                </>
+              )
             }
             timelineFooter={
               captionEditMode ? (
@@ -1678,14 +3796,75 @@ export function StudioApp() {
               {captionEditMode ? (
                 <CaptionPropertyPanel iframeRef={previewIframeRef} />
               ) : (
-                <RenderQueue
-                  jobs={renderQueue.jobs}
-                  projectId={projectId}
-                  onDelete={renderQueue.deleteRender}
-                  onClearCompleted={renderQueue.clearCompleted}
-                  onStartRender={(format, quality) => renderQueue.startRender(30, quality, format)}
-                  isRendering={renderQueue.isRendering}
-                />
+                <>
+                  <div className="flex items-center gap-1 border-b border-neutral-800 px-3 py-2">
+                    <button
+                      type="button"
+                      data-right-panel-tab="design"
+                      onClick={() => setRightPanelTab("design")}
+                      className={`h-8 rounded-xl px-3 text-[11px] font-medium transition-colors ${
+                        rightPanelTab === "design"
+                          ? "bg-neutral-800 text-white"
+                          : "text-neutral-500 hover:bg-neutral-800/70 hover:text-neutral-200"
+                      }`}
+                    >
+                      Design
+                    </button>
+                    <button
+                      type="button"
+                      data-right-panel-tab="renders"
+                      onClick={() => setRightPanelTab("renders")}
+                      className={`h-8 rounded-xl px-3 text-[11px] font-medium transition-colors ${
+                        rightPanelTab === "renders"
+                          ? "bg-neutral-800 text-white"
+                          : "text-neutral-500 hover:bg-neutral-800/70 hover:text-neutral-200"
+                      }`}
+                    >
+                      {renderQueue.jobs.length > 0
+                        ? `Renders (${renderQueue.jobs.length})`
+                        : "Renders"}
+                    </button>
+                  </div>
+                  <div className="min-h-0 flex-1">
+                    {rightPanelTab === "renders" ? (
+                      <RenderQueue
+                        jobs={renderQueue.jobs}
+                        projectId={projectId}
+                        onDelete={renderQueue.deleteRender}
+                        onClearCompleted={renderQueue.clearCompleted}
+                        onStartRender={(format, quality) =>
+                          renderQueue.startRender(30, quality, format)
+                        }
+                        isRendering={renderQueue.isRendering}
+                      />
+                    ) : (
+                      <PropertyPanel
+                        mode="design"
+                        projectId={projectId}
+                        assets={assets}
+                        element={domEditSelection}
+                        motionMaxDuration={selectedMotionMaxDuration}
+                        copiedAgentPrompt={copiedAgentPrompt}
+                        copiedElementLocator={copiedElementLocator}
+                        onClearSelection={clearDomSelection}
+                        onSetStyle={handleDomStyleCommit}
+                        onSetMotion={handleDomMotionCommit}
+                        onSetText={handleDomTextCommit}
+                        onSetTextFieldStyle={handleDomTextFieldStyleCommit}
+                        onAddTextField={handleDomAddTextField}
+                        onRemoveTextField={handleDomRemoveTextField}
+                        onDetachFromLayout={handleDomDetachFromLayout}
+                        onAskAgent={handleAskAgent}
+                        onCopyElementLocator={handleCopyElementLocator}
+                        onCopyAgentInstruction={handleAgentModalSubmit}
+                        onImportAssets={handleImportFiles}
+                        fontAssets={fontAssets}
+                        onImportFonts={handleImportFonts}
+                        allowLayoutDetach={false}
+                      />
+                    )}
+                  </div>
+                </>
               )}
             </div>
           </>
@@ -1706,6 +3885,16 @@ export function StudioApp() {
         />
       )}
 
+      {/* Ask agent modal */}
+      {agentModalOpen && domEditSelection && (
+        <AskAgentModal
+          selectionLabel={domEditSelection.label}
+          motionContextIncluded={selectionHasMotionAgentContext(domEditSelection)}
+          onSubmit={handleAgentModalSubmit}
+          onClose={() => setAgentModalOpen(false)}
+        />
+      )}
+
       {/* Global drag-drop overlay */}
       {globalDragOver && (
         <div className="absolute inset-0 z-[90] flex items-center justify-center bg-black/50 backdrop-blur-sm pointer-events-none">
diff --git a/packages/studio/src/components/LintModal.tsx b/packages/studio/src/components/LintModal.tsx
index c71d5ed1b..5a7a34331 100644
--- a/packages/studio/src/components/LintModal.tsx
+++ b/packages/studio/src/components/LintModal.tsx
@@ -1,5 +1,6 @@
 import { useState } from "react";
 import { XIcon, WarningIcon, CheckCircleIcon, CaretRightIcon } from "@phosphor-icons/react";
+import { copyTextToClipboard } from "../utils/clipboard";
 
 export interface LintFinding {
   severity: "error" | "warning";
@@ -30,12 +31,10 @@ export function LintModal({
       return line;
     });
     const text = `Fix these HyperFrames lint issues for project "${projectId}":\n\nProject path: ${window.location.href}\n\n${lines.join("\n\n")}`;
-    try {
-      await navigator.clipboard.writeText(text);
+    const copiedText = await copyTextToClipboard(text);
+    if (copiedText) {
       setCopied(true);
       setTimeout(() => setCopied(false), 2000);
-    } catch {
-      // ignore
     }
   };
 
diff --git a/packages/studio/src/components/editor/DomEditOverlay.tsx b/packages/studio/src/components/editor/DomEditOverlay.tsx
new file mode 100644
index 000000000..bb9fbd666
--- /dev/null
+++ b/packages/studio/src/components/editor/DomEditOverlay.tsx
@@ -0,0 +1,454 @@
+import { memo, useMemo, useRef, useState, type RefObject } from "react";
+import { useMountEffect } from "../../hooks/useMountEffect";
+import { type DomEditSelection, findElementForSelection } from "./domEditing";
+
+interface OverlayRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  scaleX: number;
+  scaleY: number;
+}
+
+interface DomEditOverlayProps {
+  iframeRef: RefObject<HTMLIFrameElement | null>;
+  selection: DomEditSelection | null;
+  allowCanvasMovement?: boolean;
+  onCanvasMouseDown: (
+    event: React.MouseEvent<HTMLDivElement>,
+    options?: { preferClipAncestor?: boolean },
+  ) => void;
+  onCanvasDoubleClick: (event: React.MouseEvent<HTMLDivElement>) => void;
+  onSelectedDoubleClick: () => void;
+  onBlockedMove: (selection: DomEditSelection) => void;
+  onMoveCommit: (
+    selection: DomEditSelection,
+    next: { left: number; top: number },
+  ) => Promise<void> | void;
+  onResizeCommit: (
+    selection: DomEditSelection,
+    next: { width: number; height: number },
+  ) => Promise<void> | void;
+}
+
+function toOverlayRect(
+  overlayEl: HTMLDivElement,
+  iframe: HTMLIFrameElement,
+  element: HTMLElement,
+): OverlayRect | null {
+  const iframeRect = iframe.getBoundingClientRect();
+  const overlayRect = overlayEl.getBoundingClientRect();
+  const doc = iframe.contentDocument;
+  const root =
+    doc?.querySelector<HTMLElement>("[data-composition-id]") ?? doc?.documentElement ?? null;
+  const rootRect = root?.getBoundingClientRect();
+  const rootWidth = rootRect?.width;
+  const rootHeight = rootRect?.height;
+  if (!rootWidth || !rootHeight) return null;
+
+  const elementRect = element.getBoundingClientRect();
+  const scaleX = iframeRect.width / rootWidth;
+  const scaleY = iframeRect.height / rootHeight;
+
+  return {
+    left: iframeRect.left - overlayRect.left + elementRect.left * scaleX,
+    top: iframeRect.top - overlayRect.top + elementRect.top * scaleY,
+    width: elementRect.width * scaleX,
+    height: elementRect.height * scaleY,
+    scaleX,
+    scaleY,
+  };
+}
+
+type GestureKind = "drag" | "resize";
+const BLOCKED_MOVE_THRESHOLD_PX = 4;
+const OVERLAY_RECT_EPSILON_PX = 0.5;
+
+function rectsEqual(a: OverlayRect | null, b: OverlayRect | null): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return (
+    Math.abs(a.left - b.left) < OVERLAY_RECT_EPSILON_PX &&
+    Math.abs(a.top - b.top) < OVERLAY_RECT_EPSILON_PX &&
+    Math.abs(a.width - b.width) < OVERLAY_RECT_EPSILON_PX &&
+    Math.abs(a.height - b.height) < OVERLAY_RECT_EPSILON_PX &&
+    Math.abs(a.scaleX - b.scaleX) < 0.001 &&
+    Math.abs(a.scaleY - b.scaleY) < 0.001
+  );
+}
+
+function selectionCacheKey(
+  selection: Pick<DomEditSelection, "id" | "selector" | "selectorIndex" | "sourceFile">,
+): string {
+  return [
+    selection.sourceFile ?? "",
+    selection.id ?? "",
+    selection.selector ?? "",
+    selection.selectorIndex ?? "",
+  ].join("|");
+}
+
+function restoreInlineStyle(
+  element: HTMLElement,
+  property: "left" | "top" | "width" | "height",
+  value: string,
+) {
+  if (value) element.style.setProperty(property, value);
+  else element.style.removeProperty(property);
+}
+
+function trySetPointerCapture(element: HTMLElement, pointerId: number) {
+  try {
+    element.setPointerCapture(pointerId);
+  } catch {
+    // Synthetic pointer events used by tests/agent automation may not have an
+    // active pointer in the browser. The drag still works through overlay events.
+  }
+}
+
+interface GestureState {
+  kind: GestureKind;
+  startX: number;
+  startY: number;
+  initialStyleLeft: string;
+  initialStyleTop: string;
+  originLeft: number;
+  originTop: number;
+  originWidth: number;
+  originHeight: number;
+  actualLeft: number;
+  actualTop: number;
+  actualWidth: number;
+  actualHeight: number;
+  scaleX: number;
+  scaleY: number;
+}
+
+interface BlockedMoveState {
+  pointerId: number;
+  startX: number;
+  startY: number;
+  notified: boolean;
+}
+
+export const DomEditOverlay = memo(function DomEditOverlay({
+  iframeRef,
+  selection,
+  allowCanvasMovement = true,
+  onCanvasMouseDown,
+  onCanvasDoubleClick,
+  onSelectedDoubleClick,
+  onBlockedMove,
+  onMoveCommit,
+  onResizeCommit,
+}: DomEditOverlayProps) {
+  const overlayRef = useRef<HTMLDivElement | null>(null);
+  const boxRef = useRef<HTMLDivElement | null>(null);
+  const [overlayRect, setOverlayRect] = useState<OverlayRect | null>(null);
+  const gestureRef = useRef<GestureState | null>(null);
+  const blockedMoveRef = useRef<BlockedMoveState | null>(null);
+  const suppressNextBoxClickRef = useRef(false);
+  const rafPausedRef = useRef(false);
+  const resolvedElementRef = useRef<{ key: string; element: HTMLElement } | null>(null);
+
+  const selectionRef = useRef(selection);
+  selectionRef.current = selection;
+  const overlayRectRef = useRef(overlayRect);
+  overlayRectRef.current = overlayRect;
+  const onMoveCommitRef = useRef(onMoveCommit);
+  onMoveCommitRef.current = onMoveCommit;
+  const onResizeCommitRef = useRef(onResizeCommit);
+  onResizeCommitRef.current = onResizeCommit;
+  const onBlockedMoveRef = useRef(onBlockedMove);
+  onBlockedMoveRef.current = onBlockedMove;
+
+  useMountEffect(() => {
+    let frame = 0;
+    const clearOverlayRect = () => {
+      if (!overlayRectRef.current) return;
+      overlayRectRef.current = null;
+      setOverlayRect(null);
+    };
+    const setNextOverlayRect = (next: OverlayRect | null) => {
+      if (rectsEqual(overlayRectRef.current, next)) return;
+      overlayRectRef.current = next;
+      setOverlayRect(next);
+    };
+    const resolveElement = (doc: Document, sel: DomEditSelection) => {
+      const key = selectionCacheKey(sel);
+      const cached = resolvedElementRef.current;
+      if (
+        cached?.key === key &&
+        cached.element.isConnected &&
+        cached.element.ownerDocument === doc
+      ) {
+        return cached.element;
+      }
+
+      const next = findElementForSelection(doc, sel, sel.sourceFile);
+      resolvedElementRef.current = next ? { key, element: next } : null;
+      return next;
+    };
+
+    const update = () => {
+      frame = requestAnimationFrame(update);
+      if (rafPausedRef.current) return;
+
+      const sel = selectionRef.current;
+      const iframe = iframeRef.current;
+      const overlayEl = overlayRef.current;
+      if (!sel || !iframe || !overlayEl) {
+        resolvedElementRef.current = null;
+        clearOverlayRect();
+        return;
+      }
+
+      const doc = iframe.contentDocument;
+      if (!doc) return;
+
+      const el = resolveElement(doc, sel);
+      if (!el) {
+        clearOverlayRect();
+        return;
+      }
+
+      const next = toOverlayRect(overlayEl, iframe, el);
+      setNextOverlayRect(next);
+    };
+
+    frame = requestAnimationFrame(update);
+    return () => cancelAnimationFrame(frame);
+  });
+
+  const selectionKey = useMemo(() => {
+    if (!selection) return "none";
+    return `${selection.sourceFile}:${selection.id ?? selection.selector ?? selection.label}:${
+      selection.selectorIndex ?? 0
+    }`;
+  }, [selection]);
+
+  const startGesture = (kind: GestureKind, e: React.PointerEvent) => {
+    const sel = selectionRef.current;
+    const rect = overlayRectRef.current;
+    const box = boxRef.current;
+    if (!sel || !rect || !box) return;
+
+    const left = Number.parseFloat(sel.computedStyles.left ?? "");
+    const top = Number.parseFloat(sel.computedStyles.top ?? "");
+    const width = Number.parseFloat(sel.computedStyles.width ?? "");
+    const height = Number.parseFloat(sel.computedStyles.height ?? "");
+    if (!Number.isFinite(left) || !Number.isFinite(top)) return;
+    if (kind === "resize" && !Number.isFinite(width) && !Number.isFinite(height)) return;
+
+    e.preventDefault();
+    e.stopPropagation();
+    trySetPointerCapture(e.target as HTMLElement, e.pointerId);
+
+    rafPausedRef.current = true;
+
+    gestureRef.current = {
+      kind,
+      startX: e.clientX,
+      startY: e.clientY,
+      initialStyleLeft: sel.element.style.left,
+      initialStyleTop: sel.element.style.top,
+      originLeft: rect.left,
+      originTop: rect.top,
+      originWidth: rect.width,
+      originHeight: rect.height,
+      actualLeft: left,
+      actualTop: top,
+      actualWidth: Number.isFinite(width) ? width : 0,
+      actualHeight: Number.isFinite(height) ? height : 0,
+      scaleX: rect.scaleX,
+      scaleY: rect.scaleY,
+    };
+  };
+
+  const onPointerMove = (e: React.PointerEvent) => {
+    const g = gestureRef.current;
+    const sel = selectionRef.current;
+    const box = boxRef.current;
+    const blockedMove = blockedMoveRef.current;
+    if (blockedMove && sel) {
+      const dx = e.clientX - blockedMove.startX;
+      const dy = e.clientY - blockedMove.startY;
+      if (!blockedMove.notified && Math.hypot(dx, dy) >= BLOCKED_MOVE_THRESHOLD_PX) {
+        blockedMove.notified = true;
+        suppressNextBoxClickRef.current = true;
+        onBlockedMoveRef.current(sel);
+      }
+      return;
+    }
+
+    if (!g || !sel || !box) return;
+
+    const dx = e.clientX - g.startX;
+    const dy = e.clientY - g.startY;
+
+    if (g.kind === "drag") {
+      const nextBoxLeft = g.originLeft + dx;
+      const nextBoxTop = g.originTop + dy;
+      box.style.left = `${nextBoxLeft}px`;
+      box.style.top = `${nextBoxTop}px`;
+      sel.element.style.left = `${Math.round(g.actualLeft + dx / g.scaleX)}px`;
+      sel.element.style.top = `${Math.round(g.actualTop + dy / g.scaleY)}px`;
+    } else {
+      const newW = Math.max(20, g.originWidth + dx);
+      const newH = Math.max(20, g.originHeight + dy);
+      box.style.width = `${newW}px`;
+      box.style.height = `${newH}px`;
+      sel.element.style.width = `${Math.round(g.actualWidth + dx / g.scaleX)}px`;
+      sel.element.style.height = `${Math.round(g.actualHeight + dy / g.scaleY)}px`;
+    }
+  };
+
+  const onPointerUp = (e: React.PointerEvent<HTMLDivElement>) => {
+    const g = gestureRef.current;
+    const sel = selectionRef.current;
+    const box = boxRef.current;
+    blockedMoveRef.current = null;
+    if (!g || !sel) {
+      gestureRef.current = null;
+      rafPausedRef.current = false;
+      return;
+    }
+
+    gestureRef.current = null;
+    rafPausedRef.current = false;
+
+    const movedDistance = Math.hypot(e.clientX - g.startX, e.clientY - g.startY);
+    if (g.kind === "drag" && movedDistance < BLOCKED_MOVE_THRESHOLD_PX) {
+      restoreInlineStyle(sel.element, "left", g.initialStyleLeft);
+      restoreInlineStyle(sel.element, "top", g.initialStyleTop);
+      if (box) {
+        box.style.left = `${g.originLeft}px`;
+        box.style.top = `${g.originTop}px`;
+      }
+      suppressNextBoxClickRef.current = true;
+      onCanvasMouseDown(e as unknown as React.MouseEvent<HTMLDivElement>, {
+        preferClipAncestor: false,
+      });
+      return;
+    }
+
+    if (g.kind === "drag") {
+      const finalLeft = Number.parseFloat(sel.element.style.left) || g.actualLeft;
+      const finalTop = Number.parseFloat(sel.element.style.top) || g.actualTop;
+      void Promise.resolve(onMoveCommitRef.current(sel, { left: finalLeft, top: finalTop })).catch(
+        () => {
+          sel.element.style.left = `${Math.round(g.actualLeft)}px`;
+          sel.element.style.top = `${Math.round(g.actualTop)}px`;
+        },
+      );
+    } else {
+      const finalW = Number.parseFloat(sel.element.style.width) || g.actualWidth;
+      const finalH = Number.parseFloat(sel.element.style.height) || g.actualHeight;
+      void Promise.resolve(onResizeCommitRef.current(sel, { width: finalW, height: finalH })).catch(
+        () => {
+          if (g.actualWidth > 0) sel.element.style.width = `${Math.round(g.actualWidth)}px`;
+          else sel.element.style.removeProperty("width");
+          if (g.actualHeight > 0) sel.element.style.height = `${Math.round(g.actualHeight)}px`;
+          else sel.element.style.removeProperty("height");
+        },
+      );
+    }
+  };
+
+  // Click on overlay background → select whatever is under the pointer in the iframe.
+  // This handles clicking children inside an already-selected parent: the selection
+  // box stops propagation for drag gestures, but clicks on the transparent overlay
+  // area outside the box pass through to the iframe pick logic.
+  const handleOverlayMouseDown = (event: React.MouseEvent<HTMLDivElement>) => {
+    const target = event.target as HTMLElement | null;
+    if (target?.closest('[data-dom-edit-selection-box="true"]')) return;
+    onCanvasMouseDown(event, { preferClipAncestor: false });
+  };
+
+  const handleOverlayDoubleClick = (event: React.MouseEvent<HTMLDivElement>) => {
+    const target = event.target as HTMLElement | null;
+    if (target?.closest('[data-dom-edit-selection-box="true"]')) return;
+    onCanvasDoubleClick(event);
+  };
+
+  // Click on the selection box itself → re-pick the element under the pointer.
+  // This lets you click a child element even when a parent is selected, because
+  // the click coordinates are forwarded to the iframe's element picker.
+  const handleBoxClick = (event: React.MouseEvent<HTMLDivElement>) => {
+    if (gestureRef.current) return;
+    if (suppressNextBoxClickRef.current) {
+      suppressNextBoxClickRef.current = false;
+      event.stopPropagation();
+      return;
+    }
+    onCanvasMouseDown(event, { preferClipAncestor: false });
+  };
+
+  const clearPointerState = () => {
+    blockedMoveRef.current = null;
+    gestureRef.current = null;
+    rafPausedRef.current = false;
+  };
+
+  return (
+    <div
+      key={selectionKey}
+      ref={overlayRef}
+      className="absolute inset-0 z-10 pointer-events-auto"
+      onMouseDown={handleOverlayMouseDown}
+      onDoubleClick={handleOverlayDoubleClick}
+      onPointerMove={onPointerMove}
+      onPointerUp={onPointerUp}
+      onPointerCancel={clearPointerState}
+    >
+      {selection && overlayRect && (
+        <>
+          <div
+            key={selectionKey}
+            ref={boxRef}
+            data-dom-edit-selection-box="true"
+            className="pointer-events-auto absolute rounded-xl border border-studio-accent/80 bg-studio-accent/5 shadow-[0_0_0_1px_rgba(60,230,172,0.25)]"
+            style={{
+              left: overlayRect.left,
+              top: overlayRect.top,
+              width: overlayRect.width,
+              height: overlayRect.height,
+              cursor: allowCanvasMovement && selection.capabilities.canMove ? "move" : "default",
+            }}
+            onPointerDown={(e) => {
+              if (!allowCanvasMovement) return;
+              if (selection.capabilities.canMove) {
+                startGesture("drag", e);
+                return;
+              }
+              e.preventDefault();
+              e.stopPropagation();
+              trySetPointerCapture(e.currentTarget, e.pointerId);
+              blockedMoveRef.current = {
+                pointerId: e.pointerId,
+                startX: e.clientX,
+                startY: e.clientY,
+                notified: false,
+              };
+            }}
+            onClick={handleBoxClick}
+            onDoubleClick={onSelectedDoubleClick}
+          >
+            {/* Resize handle — bottom-right corner */}
+            {allowCanvasMovement && selection.capabilities.canResize && (
+              <div
+                className="absolute -right-1.5 -bottom-1.5 w-3 h-3 rounded-sm bg-studio-accent border border-studio-accent/60"
+                style={{ cursor: "se-resize", touchAction: "none" }}
+                onPointerDown={(e) => {
+                  e.stopPropagation();
+                  startGesture("resize", e);
+                }}
+              />
+            )}
+          </div>
+        </>
+      )}
+    </div>
+  );
+});
diff --git a/packages/studio/src/components/editor/PropertyPanel.tsx b/packages/studio/src/components/editor/PropertyPanel.tsx
index 1acb2aad0..ea13fb3a4 100644
--- a/packages/studio/src/components/editor/PropertyPanel.tsx
+++ b/packages/studio/src/components/editor/PropertyPanel.tsx
@@ -1,272 +1,3568 @@
-import { memo } from "react";
-import { X, MousePointer, Move, Type, Palette, Clock, Eye } from "../../icons/SystemIcons";
-import { Button, IconButton } from "../ui";
-import type { PickedElement } from "../../hooks/useElementPicker";
+import {
+  memo,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+  type WheelEvent as ReactWheelEvent,
+} from "react";
+import { createPortal } from "react-dom";
+import {
+  Eye,
+  ClipboardList,
+  Layers,
+  MessageSquare,
+  Move,
+  Palette,
+  Plus,
+  RotateCcw,
+  Settings,
+  Type,
+  X,
+  Zap,
+} from "../../icons/SystemIcons";
+import {
+  formatCssColor,
+  hsvToRgb,
+  parseCssColor,
+  rgbToHsv,
+  toColorPickerValue,
+  toHexColor,
+  type ParsedColor,
+} from "./colorValue";
+import {
+  buildDefaultGradientModel,
+  insertGradientStop,
+  parseGradient,
+  serializeGradient,
+  type GradientModel,
+} from "./gradientValue";
+import { isTextEditableSelection, type DomEditSelection } from "./domEditing";
+import {
+  COMMON_LOCAL_FONT_FAMILIES,
+  googleFontStylesheetUrl,
+  POPULAR_GOOGLE_FONT_FAMILIES,
+} from "./fontCatalog";
+import { fontFamilyFromAssetPath, importedFontFaceCss, type ImportedFontAsset } from "./fontAssets";
+import { resolveFloatingPanelPosition, type FloatingPosition } from "./floatingPanel";
+import { IMAGE_EXT } from "../../utils/mediaTypes";
+import {
+  buildDefaultMotionDraft,
+  buildMotionCurveModel,
+  clampMotionDraftToTimeline,
+  DEFAULT_CUSTOM_MOTION_BEZIER,
+  detectMotionOwnership,
+  formatMotionBezierEase,
+  getMotionEaseLabel,
+  isMotionBezierEase,
+  MOTION_EASE_OPTIONS,
+  normalizeMotionEase,
+  parseMotionBezierEase,
+  parseMotionDraft,
+  sampleMotionEase,
+  type MotionBezierEase,
+  type MotionCurveModel,
+  type MotionCurveTrack,
+  type MotionDirection,
+  type MotionDraft,
+  type MotionEase,
+  type MotionKeyframes,
+  type MotionKeyframeRange,
+  type MotionOwnershipReport,
+  type MotionOwnershipState,
+  type MotionPreset,
+} from "./motionEditing";
 
 interface PropertyPanelProps {
-  element: PickedElement | null;
-  isPickMode: boolean;
-  onEnablePick: () => void;
-  onDisablePick: () => void;
-  onClearPick: () => void;
+  mode?: "design" | "motion";
+  projectId: string;
+  assets: string[];
+  element: DomEditSelection | null;
+  motionMaxDuration?: number;
+  copiedAgentPrompt: boolean;
+  copiedElementLocator?: boolean;
+  onClearSelection: () => void;
   onSetStyle: (prop: string, value: string) => void;
-  onSetDataAttr: (attr: string, value: string) => void;
-  onSetText?: (text: string) => void;
+  onSetMotion: (motion: MotionDraft | null) => void;
+  onSetText: (value: string, fieldKey?: string) => void;
+  onSetTextFieldStyle: (fieldKey: string, property: string, value: string) => void;
+  onAddTextField: (afterFieldKey?: string) => string | Promise<string | null> | null;
+  onRemoveTextField: (fieldKey: string) => void;
+  onDetachFromLayout: () => void;
+  onAskAgent: () => void;
+  onCopyElementLocator: () => void | Promise<void>;
+  onCopyAgentInstruction: (instruction: string) => void | Promise<void>;
+  onImportAssets?: (files: FileList) => Promise<string[]>;
+  fontAssets?: ImportedFontAsset[];
+  onImportFonts?: (files: FileList | File[]) => Promise<ImportedFontAsset[]>;
+  allowLayoutDetach?: boolean;
 }
 
-function PropertyRow({
+const FIELD =
+  "min-w-0 rounded-xl border border-neutral-800 bg-neutral-900/95 px-3 py-2 text-neutral-100 shadow-[inset_0_1px_0_rgba(255,255,255,0.03)] transition-colors focus-within:border-neutral-600";
+const LABEL = "text-[11px] font-medium uppercase tracking-[0.18em] text-neutral-500";
+const RESPONSIVE_GRID = "grid grid-cols-[repeat(auto-fit,minmax(118px,1fr))] gap-3";
+const EMPTY_STYLES: Record<string, string> = {};
+const GENERIC_FONT_FAMILIES = new Set([
+  "inherit",
+  "initial",
+  "revert",
+  "revert-layer",
+  "serif",
+  "sans-serif",
+  "monospace",
+  "cursive",
+  "fantasy",
+  "system-ui",
+  "ui-sans-serif",
+  "ui-serif",
+  "ui-monospace",
+  "ui-rounded",
+  "emoji",
+  "math",
+  "fangsong",
+]);
+const DEFAULT_FONT_FAMILIES = [
+  ...COMMON_LOCAL_FONT_FAMILIES,
+  "Inter",
+  "system-ui",
+  "sans-serif",
+  "serif",
+  "monospace",
+];
+const MOTION_PRESET_OPTIONS: Array<{ label: string; value: MotionPreset }> = [
+  { label: "Fade Up", value: "fade-up" },
+  { label: "Slide", value: "slide" },
+  { label: "Pop", value: "pop" },
+];
+const MOTION_DIRECTION_OPTIONS: MotionDirection[] = ["up", "down", "left", "right"];
+const CUSTOM_EASE_VALUE = "__custom-bezier__";
+const CUSTOM_EASE_PRESETS: Array<{ label: string; value: MotionBezierEase }> = [
+  { label: "Soft", value: DEFAULT_CUSTOM_MOTION_BEZIER },
+  { label: "Snap", value: { x1: 0.2, y1: 0.9, x2: 0.24, y2: 1 } },
+  { label: "Overshoot", value: { x1: 0.2, y1: 1.35, x2: 0.34, y2: 1 } },
+];
+
+interface LocalFontData {
+  family: string;
+  fullName?: string;
+  postscriptName?: string;
+  style?: string;
+  blob?: () => Promise<Blob>;
+}
+
+type FontSource = "Current" | "Document" | "Imported" | "Local" | "Google" | "System";
+
+interface FontOption {
+  family: string;
+  source: FontSource;
+}
+
+const COLOR_PICKER_SIZE = { width: 292, height: 386 };
+
+function buildMakeMovableAgentInstruction(reason: string): string {
+  return [
+    "Make this selected HyperFrames element movable in Studio.",
+    `Studio blocked direct move/resize because: ${reason}`,
+    "Refactor only this element safely.",
+    "Preserve its current visual position, timing, and sibling layout intent where possible.",
+    "If it is transform-driven, replace transform-based positioning with absolute pixel geometry.",
+    "If layout flow owns it, detach conservatively with position: absolute, px left/top/width/height, and margin: 0.",
+  ].join(" ");
+}
+
+function colorFromCss(value: string): ParsedColor {
+  return parseCssColor(value) ?? { red: 0, green: 0, blue: 0, alpha: 1 };
+}
+
+declare global {
+  interface Window {
+    queryLocalFonts?: () => Promise<LocalFontData[]>;
+  }
+}
+
+function sanitizeFontFilePart(value: string): string {
+  return value
+    .replace(/[^\w .-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function localFontSortScore(font: LocalFontData): number {
+  const style = font.style?.toLowerCase() ?? "";
+  const fullName = font.fullName?.toLowerCase() ?? "";
+  if (style === "regular" || fullName.endsWith(" regular")) return 0;
+  if (style === "normal" || fullName.endsWith(" normal")) return 1;
+  if (style === "medium" || fullName.endsWith(" medium")) return 2;
+  return 3;
+}
+
+function parseNumericValue(value: string | undefined): number | null {
+  if (!value) return null;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function formatNumericValue(value: number): string {
+  const rounded = Math.round(value * 100) / 100;
+  return Number.isInteger(rounded)
+    ? `${rounded}`
+    : rounded.toFixed(2).replace(/0+$/, "").replace(/\.$/, "");
+}
+
+function roundPanelNumber(value: number): number {
+  const normalized = Math.abs(value) < 0.0001 ? 0 : value;
+  return Math.round(normalized * 1000) / 1000;
+}
+
+function trySetElementPointerCapture(element: Element, pointerId: number) {
+  if (!(element instanceof HTMLElement || element instanceof SVGElement)) return;
+  try {
+    element.setPointerCapture(pointerId);
+  } catch {
+    // Synthetic pointer events used in browser automation may not have an
+    // active browser pointer. Drag interactions still work through move events.
+  }
+}
+
+interface ParsedNumericToken {
+  value: number;
+  unit: string;
+}
+
+function parseNumericToken(value: string | undefined): ParsedNumericToken | null {
+  if (!value) return null;
+  const match = value.trim().match(/^(-?\d+(?:\.\d+)?)([a-z%]*)$/i);
+  if (!match) return null;
+  const parsed = Number.parseFloat(match[1]);
+  if (!Number.isFinite(parsed)) return null;
+  return {
+    value: parsed,
+    unit: match[2] ?? "",
+  };
+}
+
+function adjustNumericToken(
+  value: string,
+  direction: 1 | -1,
+  modifiers?: { shiftKey?: boolean; altKey?: boolean },
+): string | null {
+  const token = parseNumericToken(value);
+  if (!token) return null;
+
+  const baseStep = modifiers?.altKey ? 0.1 : modifiers?.shiftKey ? 10 : 1;
+  const nextValue = token.value + baseStep * direction;
+  return `${formatNumericValue(nextValue)}${token.unit}`;
+}
+
+function formatColorToken(value: string): string {
+  const parsed = parseCssColor(value);
+  if (!parsed) return value;
+  const hex = toColorPickerValue(value).replace(/^#/, "").toUpperCase();
+  return `${hex} / ${Math.round(parsed.alpha * 100)}%`;
+}
+
+function extractBackgroundImageUrl(value: string | undefined): string {
+  if (!value) return "";
+  const lowerValue = value.toLowerCase();
+  const urlStart = lowerValue.indexOf("url(");
+  if (urlStart < 0) return "";
+
+  let index = urlStart + 4;
+  while (
+    index < value.length &&
+    (value[index] === " " ||
+      value[index] === "\n" ||
+      value[index] === "\r" ||
+      value[index] === "\t" ||
+      value[index] === "\f")
+  ) {
+    index += 1;
+  }
+
+  const quote = value[index] === '"' || value[index] === "'" ? value[index] : null;
+  if (quote) {
+    index += 1;
+    const endQuote = value.indexOf(quote, index);
+    return endQuote >= index ? value.slice(index, endQuote) : "";
+  }
+
+  const endParen = value.indexOf(")", index);
+  if (endParen < index) return "";
+  return value.slice(index, endParen).trim();
+}
+
+function normalizeProjectPath(value: string): string {
+  const trimmed = value.trim();
+  const maybeUrl = /^[a-z]+:\/\//i.test(trimmed) ? new URL(trimmed).pathname : trimmed;
+  return decodeURIComponent(maybeUrl)
+    .replace(/\\/g, "/")
+    .replace(/^\.?\//, "");
+}
+
+function toRelativeProjectAssetPath(sourceFile: string, assetPath: string): string {
+  const fromParts = normalizeProjectPath(sourceFile).split("/").filter(Boolean);
+  const targetParts = normalizeProjectPath(assetPath).split("/").filter(Boolean);
+
+  fromParts.pop();
+
+  while (fromParts.length > 0 && targetParts.length > 0 && fromParts[0] === targetParts[0]) {
+    fromParts.shift();
+    targetParts.shift();
+  }
+
+  return [...fromParts.map(() => ".."), ...targetParts].join("/") || assetPath;
+}
+
+function toProjectRootAssetPath(assetPath: string): string {
+  return normalizeProjectPath(assetPath);
+}
+
+function resolveSelectedAsset(
+  imageUrl: string,
+  sourceFile: string,
+  assets: string[],
+): string | null {
+  const normalizedUrl = normalizeProjectPath(imageUrl);
+  if (!normalizedUrl) return null;
+
+  for (const asset of assets) {
+    const normalizedAsset = normalizeProjectPath(asset);
+    const relativeAsset = toRelativeProjectAssetPath(sourceFile, asset);
+    if (
+      normalizedUrl === normalizedAsset ||
+      normalizedUrl === relativeAsset ||
+      normalizedUrl.endsWith(`/${normalizedAsset}`) ||
+      normalizedUrl.endsWith(`/${relativeAsset}`)
+    ) {
+      return asset;
+    }
+  }
+
+  return null;
+}
+
+function collectSelectionColors(styles: Record<string, string>) {
+  const candidates = [
+    { source: "Fill", value: styles["background-color"] },
+    { source: "Text", value: styles.color },
+  ];
+
+  const deduped = new Map<string, { swatch: string; token: string; sources: string[] }>();
+
+  for (const candidate of candidates) {
+    if (!candidate.value) continue;
+    const parsed = parseCssColor(candidate.value);
+    if (!parsed || parsed.alpha <= 0) continue;
+
+    const key = `${toColorPickerValue(candidate.value)}-${Math.round(parsed.alpha * 100)}`;
+    const existing = deduped.get(key);
+    if (existing) {
+      existing.sources.push(candidate.source);
+      continue;
+    }
+
+    deduped.set(key, {
+      swatch: toColorPickerValue(candidate.value),
+      token: formatColorToken(candidate.value),
+      sources: [candidate.source],
+    });
+  }
+
+  return Array.from(deduped.values());
+}
+
+function CommitField({
+  value,
+  disabled,
+  liveCommit,
+  onCommit,
+}: {
+  value: string;
+  disabled?: boolean;
+  liveCommit?: boolean;
+  onCommit: (nextValue: string) => void;
+}) {
+  const [draft, setDraft] = useState(value);
+  const commitTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const valueRef = useRef(value);
+
+  valueRef.current = value;
+
+  useEffect(() => {
+    setDraft(value);
+  }, [value]);
+
+  useEffect(
+    () => () => {
+      if (commitTimerRef.current) clearTimeout(commitTimerRef.current);
+    },
+    [],
+  );
+
+  const commitDraft = (nextDraft: string) => {
+    if (commitTimerRef.current) clearTimeout(commitTimerRef.current);
+    if (nextDraft !== valueRef.current) {
+      onCommit(nextDraft);
+    }
+  };
+
+  const scheduleCommit = (nextDraft: string) => {
+    if (commitTimerRef.current) clearTimeout(commitTimerRef.current);
+    commitTimerRef.current = setTimeout(() => {
+      if (nextDraft !== valueRef.current) {
+        onCommit(nextDraft);
+      }
+    }, 120);
+  };
+
+  return (
+    <input
+      type="text"
+      value={draft}
+      disabled={disabled}
+      onChange={(e) => {
+        setDraft(e.target.value);
+        if (liveCommit) scheduleCommit(e.target.value);
+      }}
+      onBlur={() => commitDraft(draft)}
+      onWheel={(e) => {
+        if (disabled) return;
+        const delta = e.deltaY === 0 ? e.deltaX : e.deltaY;
+        if (delta === 0) return;
+        const nextDraft = adjustNumericToken(draft, delta < 0 ? 1 : -1, e);
+        if (!nextDraft) return;
+        e.preventDefault();
+        e.stopPropagation();
+        setDraft(nextDraft);
+        scheduleCommit(nextDraft);
+      }}
+      onKeyDown={(e) => {
+        if (e.key === "Enter") {
+          (e.target as HTMLInputElement).blur();
+          return;
+        }
+        if (e.key !== "ArrowUp" && e.key !== "ArrowDown") return;
+        const nextDraft = adjustNumericToken(draft, e.key === "ArrowUp" ? 1 : -1, e);
+        if (!nextDraft) return;
+        e.preventDefault();
+        setDraft(nextDraft);
+        scheduleCommit(nextDraft);
+      }}
+      title={parseNumericToken(value) ? "Scroll or use Arrow keys to adjust" : undefined}
+      className="min-w-0 w-full bg-transparent text-[11px] font-medium text-neutral-100 outline-none disabled:cursor-not-allowed disabled:text-neutral-600"
+    />
+  );
+}
+
+function MetricField({
+  label,
+  value,
+  disabled,
+  liveCommit,
+  onCommit,
+}: {
+  label: string;
+  value: string;
+  disabled?: boolean;
+  liveCommit?: boolean;
+  onCommit: (nextValue: string) => void;
+}) {
+  return (
+    <div
+      data-panel-wheel-lock="true"
+      className={FIELD}
+      onWheel={(e) => {
+        if (!disabled) return;
+        e.preventDefault();
+        e.stopPropagation();
+      }}
+    >
+      <div className="flex min-w-0 items-center gap-3">
+        <span className="flex-shrink-0 text-[11px] font-medium text-neutral-500">{label}</span>
+        <CommitField
+          value={value}
+          disabled={disabled}
+          liveCommit={liveCommit}
+          onCommit={onCommit}
+        />
+      </div>
+    </div>
+  );
+}
+
+function isPanelWheelLockedTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof Element)) return false;
+  return Boolean(target.closest("input, textarea, select, [data-panel-wheel-lock='true']"));
+}
+
+function preventPanelScrollFromControlWheel(event: ReactWheelEvent<HTMLDivElement>) {
+  if (!isPanelWheelLockedTarget(event.target)) return;
+  event.preventDefault();
+  event.stopPropagation();
+}
+
+function DetailField({
+  label,
+  value,
+  disabled,
+  onCommit,
+}: {
+  label: string;
+  value: string;
+  disabled?: boolean;
+  onCommit: (nextValue: string) => void;
+}) {
+  return (
+    <label className="grid min-w-0 gap-1.5">
+      <span className={LABEL}>{label}</span>
+      <div className={FIELD}>
+        <CommitField value={value} disabled={disabled} onCommit={onCommit} />
+      </div>
+    </label>
+  );
+}
+
+function TextAreaField({
+  label,
+  value,
+  disabled,
+  autoFocus,
+  onCommit,
+}: {
+  label: string;
+  value: string;
+  disabled?: boolean;
+  autoFocus?: boolean;
+  onCommit: (nextValue: string) => void;
+}) {
+  const [draft, setDraft] = useState(value);
+  const textareaRef = useRef<HTMLTextAreaElement | null>(null);
+  const commitTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const focusedRef = useRef(false);
+  const valueRef = useRef(value);
+
+  valueRef.current = value;
+
+  useEffect(() => {
+    if (focusedRef.current) return;
+    setDraft(value);
+  }, [value]);
+
+  useEffect(
+    () => () => {
+      if (commitTimerRef.current) clearTimeout(commitTimerRef.current);
+    },
+    [],
+  );
+
+  useEffect(() => {
+    if (!autoFocus) return;
+    textareaRef.current?.focus();
+  }, [autoFocus]);
+
+  const commitDraft = (nextDraft: string) => {
+    if (commitTimerRef.current) clearTimeout(commitTimerRef.current);
+    if (nextDraft !== valueRef.current) {
+      onCommit(nextDraft);
+    }
+  };
+
+  const scheduleCommit = (nextDraft: string) => {
+    if (commitTimerRef.current) clearTimeout(commitTimerRef.current);
+    commitTimerRef.current = setTimeout(() => {
+      if (nextDraft !== valueRef.current) {
+        onCommit(nextDraft);
+      }
+    }, 120);
+  };
+
+  return (
+    <label className="grid min-w-0 gap-1.5">
+      <span className={LABEL}>{label}</span>
+      <div className={FIELD}>
+        <textarea
+          ref={textareaRef}
+          value={draft}
+          disabled={disabled}
+          rows={4}
+          onFocus={() => {
+            focusedRef.current = true;
+          }}
+          onChange={(e) => {
+            setDraft(e.target.value);
+            scheduleCommit(e.target.value);
+          }}
+          onBlur={() => {
+            focusedRef.current = false;
+            commitDraft(draft);
+          }}
+          className="w-full resize-none bg-transparent text-[11px] font-medium text-neutral-100 outline-none disabled:cursor-not-allowed disabled:text-neutral-600"
+        />
+      </div>
+    </label>
+  );
+}
+
+function formatTextFieldPreview(value: string): string {
+  const collapsed = value.trim().replace(/\s+/g, " ");
+  if (collapsed.length <= 56) return collapsed;
+  return `${collapsed.slice(0, 55)}…`;
+}
+
+function getTextFieldColor(
+  field: { computedStyles: Record<string, string> },
+  inheritedStyles: Record<string, string>,
+): string {
+  return field.computedStyles.color || inheritedStyles.color || "rgb(0, 0, 0)";
+}
+
+function splitFontFamilies(value: string): string[] {
+  const families: string[] = [];
+  let current = "";
+  let quote: '"' | "'" | null = null;
+
+  for (const char of value) {
+    if ((char === '"' || char === "'") && !quote) {
+      quote = char;
+      continue;
+    }
+    if (char === quote) {
+      quote = null;
+      continue;
+    }
+    if (char === "," && !quote) {
+      if (current.trim()) families.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+
+  if (current.trim()) families.push(current.trim());
+  return families.map((family) => family.replace(/^["']|["']$/g, "").trim()).filter(Boolean);
+}
+
+function primaryFontFamily(value: string): string {
+  return splitFontFamilies(value)[0] ?? "inherit";
+}
+
+function quoteFontFamily(family: string): string {
+  const trimmed = family.trim();
+  if (GENERIC_FONT_FAMILIES.has(trimmed.toLowerCase())) return trimmed;
+  return `"${trimmed.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function buildFontFamilyValue(family: string): string {
+  const trimmed = family.trim();
+  if (!trimmed) return "inherit";
+  if (GENERIC_FONT_FAMILIES.has(trimmed.toLowerCase())) return trimmed;
+  return `${quoteFontFamily(trimmed)}, ui-sans-serif, system-ui, sans-serif`;
+}
+
+function collectDocumentFontFamilies(): string[] {
+  if (typeof document === "undefined") return [];
+  const fontSet = document.fonts;
+  if (!fontSet) return [];
+  return Array.from(fontSet, (fontFace) => fontFace.family.replace(/^["']|["']$/g, "").trim())
+    .filter(Boolean)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+function uniqueFontFamilies(values: string[]): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const value of values) {
+    const family = value.trim();
+    if (!family) continue;
+    const key = family.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(family);
+  }
+  return result;
+}
+
+function uniqueFontOptions(values: FontOption[]): FontOption[] {
+  const seen = new Set<string>();
+  const result: FontOption[] = [];
+  for (const value of values) {
+    const family = value.family.trim();
+    if (!family) continue;
+    const key = family.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push({ family, source: value.source });
+  }
+  return result;
+}
+
+function fontSourceRank(source: FontSource): number {
+  if (source === "Current") return 0;
+  if (source === "Document") return 1;
+  if (source === "Imported") return 2;
+  if (source === "Local") return 3;
+  if (source === "Google") return 4;
+  return 5;
+}
+
+function sortFontOptions(options: FontOption[]): FontOption[] {
+  return [...options].sort((a, b) => {
+    const rankDelta = fontSourceRank(a.source) - fontSourceRank(b.source);
+    if (rankDelta !== 0) return rankDelta;
+
+    const commonA = COMMON_LOCAL_FONT_FAMILIES.findIndex(
+      (family) => family.toLowerCase() === a.family.toLowerCase(),
+    );
+    const commonB = COMMON_LOCAL_FONT_FAMILIES.findIndex(
+      (family) => family.toLowerCase() === b.family.toLowerCase(),
+    );
+    const commonDelta =
+      (commonA === -1 ? Number.MAX_SAFE_INTEGER : commonA) -
+      (commonB === -1 ? Number.MAX_SAFE_INTEGER : commonB);
+
+    return commonDelta === 0 ? a.family.localeCompare(b.family) : commonDelta;
+  });
+}
+
+function fontSearchKey(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
+function fontMatchesQuery(family: string, query: string): boolean {
+  const normalizedQuery = query.trim().toLowerCase();
+  if (!normalizedQuery) return true;
+  const normalizedFamily = family.toLowerCase();
+  if (normalizedFamily.includes(normalizedQuery)) return true;
+  return fontSearchKey(family).includes(fontSearchKey(normalizedQuery));
+}
+
+function loadGoogleFontStylesheet(family: string): void {
+  if (typeof document === "undefined") return;
+  const trimmed = family.trim();
+  if (!trimmed) return;
+
+  const id = `studio-google-font-${trimmed.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
+  if (document.getElementById(id)) return;
+
+  const preconnect = document.querySelector('link[data-studio-google-font-preconnect="true"]');
+  if (!preconnect) {
+    const preconnectEl = document.createElement("link");
+    preconnectEl.setAttribute("data-studio-google-font-preconnect", "true");
+    preconnectEl.rel = "preconnect";
+    preconnectEl.href = "https://fonts.gstatic.com";
+    preconnectEl.crossOrigin = "anonymous";
+    document.head.appendChild(preconnectEl);
+  }
+
+  const link = document.createElement("link");
+  link.id = id;
+  link.rel = "stylesheet";
+  link.href = googleFontStylesheetUrl(trimmed);
+  document.head.appendChild(link);
+}
+
+function loadImportedFontStylesheet(asset: ImportedFontAsset): void {
+  if (typeof document === "undefined") return;
+  const id = `studio-imported-font-${asset.family.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
+  if (document.getElementById(id)) return;
+
+  const style = document.createElement("style");
+  style.id = id;
+  style.textContent = importedFontFaceCss(asset);
+  document.head.appendChild(style);
+}
+
+function FontWeightField({
+  value,
+  disabled,
+  onCommit,
+}: {
+  value: string;
+  disabled?: boolean;
+  onCommit: (nextValue: string) => void;
+}) {
+  const options = ["300", "400", "500", "600", "700", "800"];
+  return (
+    <div className={FIELD}>
+      <div className="flex min-w-0 items-center gap-3">
+        <span className="flex-shrink-0 text-[11px] font-medium text-neutral-500">Weight</span>
+        <select
+          value={value}
+          disabled={disabled}
+          onChange={(e) => onCommit(e.target.value)}
+          className="min-w-0 w-full appearance-none bg-transparent text-[11px] font-medium text-neutral-100 outline-none disabled:cursor-not-allowed disabled:text-neutral-600"
+        >
+          {options.map((option) => (
+            <option key={option} value={option}>
+              {option}
+            </option>
+          ))}
+        </select>
+      </div>
+    </div>
+  );
+}
+
+function FontFamilyField({
+  value,
+  disabled,
+  importedFonts,
+  onImportFonts,
+  onCommit,
+}: {
+  value: string;
+  disabled?: boolean;
+  importedFonts: ImportedFontAsset[];
+  onImportFonts?: (files: FileList | File[]) => Promise<ImportedFontAsset[]>;
+  onCommit: (nextValue: string) => void;
+}) {
+  const currentFamily = primaryFontFamily(value);
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const fontInputRef = useRef<HTMLInputElement | null>(null);
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const [localFonts, setLocalFonts] = useState<string[]>([]);
+  const [localFontData, setLocalFontData] = useState<LocalFontData[]>([]);
+  const [googleFonts, setGoogleFonts] = useState<string[]>(() => [...POPULAR_GOOGLE_FONT_FAMILIES]);
+  const [loadingLocalFonts, setLoadingLocalFonts] = useState(false);
+  const [loadingGoogleFonts, setLoadingGoogleFonts] = useState(false);
+  const [importingFonts, setImportingFonts] = useState(false);
+  const [fontNotice, setFontNotice] = useState<string | null>(null);
+  const canQueryLocalFonts =
+    typeof window !== "undefined" && typeof window.queryLocalFonts === "function";
+
+  useEffect(() => {
+    if (!open) return;
+    const handlePointerDown = (event: PointerEvent) => {
+      const target = event.target;
+      if (!(target instanceof Node)) return;
+      if (!containerRef.current?.contains(target)) setOpen(false);
+    };
+    document.addEventListener("pointerdown", handlePointerDown);
+    return () => {
+      document.removeEventListener("pointerdown", handlePointerDown);
+    };
+  }, [open]);
+
+  useEffect(() => {
+    if (!open) return;
+    requestAnimationFrame(() => inputRef.current?.focus());
+  }, [open]);
+
+  useEffect(() => {
+    let cancelled = false;
+    void fetch("/api/fonts")
+      .then((response) => (response.ok ? response.json() : null))
+      .then((data: { fonts?: string[] } | null) => {
+        const fonts = data?.fonts;
+        if (cancelled || !Array.isArray(fonts)) return;
+        setLocalFonts((current) => uniqueFontFamilies([...current, ...fonts]));
+      })
+      .catch(() => undefined);
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoadingGoogleFonts(true);
+    void fetch("/api/fonts/google")
+      .then((response) => (response.ok ? response.json() : null))
+      .then((data: { fonts?: string[] } | null) => {
+        const fonts = data?.fonts;
+        if (cancelled || !Array.isArray(fonts)) return;
+        setGoogleFonts(uniqueFontFamilies([...fonts, ...POPULAR_GOOGLE_FONT_FAMILIES]));
+      })
+      .catch(() => undefined)
+      .finally(() => {
+        if (!cancelled) setLoadingGoogleFonts(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  useEffect(() => {
+    if (googleFonts.some((family) => family.toLowerCase() === currentFamily.toLowerCase())) {
+      loadGoogleFontStylesheet(currentFamily);
+    }
+    const imported = importedFonts.find(
+      (font) => font.family.toLowerCase() === currentFamily.toLowerCase(),
+    );
+    if (imported) loadImportedFontStylesheet(imported);
+  }, [currentFamily, googleFonts, importedFonts]);
+
+  const loadBrowserLocalFonts = async () => {
+    if (!canQueryLocalFonts || !window.queryLocalFonts) {
+      setFontNotice("This browser does not expose installed fonts. Import a font file instead.");
+      return;
+    }
+    setLoadingLocalFonts(true);
+    setFontNotice(null);
+    try {
+      const fonts = await window.queryLocalFonts();
+      const sortedFonts = [...fonts].sort((a, b) => localFontSortScore(a) - localFontSortScore(b));
+      const families = sortedFonts
+        .map((font) => font.family)
+        .filter((name): name is string => Boolean(name))
+        .map((name) => fontFamilyFromAssetPath(`${name}.ttf`));
+      setLocalFontData(sortedFonts);
+      setLocalFonts((current) => uniqueFontFamilies([...current, ...families]));
+      setFontNotice(fonts.length === 0 ? "No browser-local fonts were returned." : null);
+    } catch (error) {
+      const name = error instanceof Error ? error.name : "";
+      setFontNotice(
+        name === "NotAllowedError"
+          ? "Local font access was denied. Import a font file instead."
+          : "Local font access is unavailable. Import a font file instead.",
+      );
+    } finally {
+      setLoadingLocalFonts(false);
+    }
+  };
+
+  const handleImportFonts = async (files: FileList | File[] | null) => {
+    if (!files?.length || !onImportFonts) return;
+    setImportingFonts(true);
+    setFontNotice(null);
+    try {
+      const imported = await onImportFonts(files);
+      for (const font of imported) loadImportedFontStylesheet(font);
+      const first = imported[0];
+      if (first) {
+        onCommit(buildFontFamilyValue(first.family));
+        setQuery("");
+        setOpen(false);
+      } else {
+        setFontNotice("No supported font files were imported.");
+      }
+    } finally {
+      setImportingFonts(false);
+    }
+  };
+
+  const projectFontAssets = useMemo(
+    () =>
+      uniqueFontOptions(
+        importedFonts.map((font): FontOption => ({ family: font.family, source: "Imported" })),
+      ),
+    [importedFonts],
+  );
+
+  const options = useMemo(() => {
+    const documentFonts = collectDocumentFontFamilies();
+    return sortFontOptions(
+      uniqueFontOptions([
+        { family: currentFamily, source: "Current" },
+        ...documentFonts.map((family): FontOption => ({ family, source: "Document" })),
+        ...projectFontAssets,
+        ...localFonts.map((family): FontOption => ({ family, source: "Local" })),
+        ...googleFonts.map((family): FontOption => ({ family, source: "Google" })),
+        ...DEFAULT_FONT_FAMILIES.map((family): FontOption => ({ family, source: "System" })),
+      ]),
+    );
+  }, [currentFamily, googleFonts, localFonts, projectFontAssets]);
+
+  const filteredOptions = useMemo(() => {
+    const matches = options.filter((option) => fontMatchesQuery(option.family, query));
+    return matches.slice(0, query.trim() ? 120 : 160);
+  }, [options, query]);
+
+  const importLocalFont = async (family: string): Promise<ImportedFontAsset | null> => {
+    if (!onImportFonts) return null;
+    const candidates = localFontData
+      .filter((font) => fontFamilyFromAssetPath(`${font.family}.ttf`) === family)
+      .sort((a, b) => localFontSortScore(a) - localFontSortScore(b));
+    const font = candidates.find((entry) => typeof entry.blob === "function");
+    if (!font?.blob) return null;
+
+    const blob = await font.blob();
+    const style = sanitizeFontFilePart(font.style ?? "Regular") || "Regular";
+    const name = sanitizeFontFilePart(`${family} ${style}`) || family;
+    const file = new File([blob], `${name}.ttf`, {
+      type: blob.type || "font/ttf",
+    });
+    const imported = await onImportFonts([file]);
+    return (
+      imported.find((asset) => asset.family.toLowerCase() === family.toLowerCase()) ??
+      imported[0] ??
+      null
+    );
+  };
+
+  const commitFamily = async (option: FontOption) => {
+    if (option.source === "Local") {
+      setImportingFonts(true);
+      setFontNotice(null);
+      try {
+        const imported = await importLocalFont(option.family);
+        if (imported) {
+          loadImportedFontStylesheet(imported);
+          onCommit(buildFontFamilyValue(imported.family));
+          setQuery("");
+          setOpen(false);
+          return;
+        }
+        onCommit(buildFontFamilyValue(option.family));
+        setQuery("");
+        setOpen(false);
+      } finally {
+        setImportingFonts(false);
+      }
+      return;
+    }
+
+    if (option.source === "Google") {
+      loadGoogleFontStylesheet(option.family);
+    }
+    const imported = importedFonts.find(
+      (font) => font.family.toLowerCase() === option.family.toLowerCase(),
+    );
+    if (imported) loadImportedFontStylesheet(imported);
+    onCommit(buildFontFamilyValue(option.family));
+    setQuery("");
+    setOpen(false);
+  };
+
+  return (
+    <div ref={containerRef} className="relative grid min-w-0 gap-1.5">
+      <span className={LABEL}>Font family</span>
+      <button
+        type="button"
+        disabled={disabled}
+        onClick={() => setOpen((next) => !next)}
+        className={`${FIELD} flex h-10 items-center justify-between gap-3 text-left hover:border-neutral-700 disabled:cursor-not-allowed`}
+      >
+        <span
+          className="min-w-0 flex-1 truncate text-[11px] font-medium text-neutral-100"
+          style={{ fontFamily: value }}
+        >
+          {currentFamily}
+        </span>
+        <span className="flex-shrink-0 text-[10px] uppercase tracking-[0.14em] text-neutral-600">
+          Font
+        </span>
+      </button>
+
+      {open && (
+        <div className="absolute left-0 right-0 top-[calc(100%+6px)] z-50 overflow-hidden rounded-xl border border-neutral-700 bg-neutral-950 shadow-2xl">
+          <div className="grid grid-cols-[minmax(0,1fr)_auto_auto] gap-2 border-b border-neutral-800 p-2">
+            <input
+              ref={inputRef}
+              type="text"
+              value={query}
+              disabled={disabled}
+              placeholder={loadingGoogleFonts ? "Loading Google Fonts..." : "Search fonts"}
+              onChange={(e) => setQuery(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === "Escape") {
+                  e.preventDefault();
+                  setOpen(false);
+                }
+                if (e.key === "Enter" && filteredOptions[0]) {
+                  e.preventDefault();
+                  commitFamily(filteredOptions[0]);
+                }
+              }}
+              className="min-w-0 rounded-lg border border-neutral-800 bg-neutral-900 px-2.5 py-2 text-[11px] font-medium text-neutral-100 outline-none placeholder:text-neutral-600 focus:border-neutral-600"
+            />
+            {canQueryLocalFonts && (
+              <button
+                type="button"
+                disabled={disabled || loadingLocalFonts}
+                onClick={loadBrowserLocalFonts}
+                className="rounded-lg border border-neutral-700 bg-neutral-900 px-2.5 text-[10px] font-medium text-neutral-400 transition-colors hover:border-neutral-600 hover:text-neutral-100 disabled:cursor-not-allowed disabled:text-neutral-700"
+              >
+                {loadingLocalFonts ? "..." : "Local"}
+              </button>
+            )}
+            <button
+              type="button"
+              disabled={disabled || importingFonts || !onImportFonts}
+              onClick={() => fontInputRef.current?.click()}
+              className="rounded-lg border border-neutral-700 bg-neutral-900 px-2.5 text-[10px] font-medium text-neutral-400 transition-colors hover:border-neutral-600 hover:text-neutral-100 disabled:cursor-not-allowed disabled:text-neutral-700"
+            >
+              {importingFonts ? "..." : "Import"}
+            </button>
+            <input
+              ref={fontInputRef}
+              type="file"
+              accept=".ttf,.otf,.ttc,.woff,.woff2,.eot,font/*"
+              multiple
+              aria-label="Import local font files"
+              disabled={disabled || importingFonts || !onImportFonts}
+              className="hidden"
+              onChange={async (event) => {
+                await handleImportFonts(event.target.files);
+                event.target.value = "";
+              }}
+            />
+          </div>
+          {fontNotice && (
+            <div className="border-b border-neutral-800 px-3 py-2 text-[10px] leading-4 text-neutral-500">
+              {fontNotice}
+            </div>
+          )}
+          <div className="max-h-64 overflow-y-auto p-1">
+            {filteredOptions.length === 0 ? (
+              <div className="px-2 py-3 text-[11px] text-neutral-500">No fonts found.</div>
+            ) : (
+              filteredOptions.map((option) => (
+                <button
+                  key={`${option.source}-${option.family}`}
+                  type="button"
+                  onClick={() => commitFamily(option)}
+                  className={`flex w-full min-w-0 items-center justify-between gap-3 rounded-lg px-2 py-2 text-left text-[11px] transition-colors ${
+                    option.family === currentFamily
+                      ? "bg-studio-accent/15 text-neutral-50"
+                      : "text-neutral-300 hover:bg-neutral-900 hover:text-neutral-100"
+                  }`}
+                >
+                  <span className="min-w-0 truncate font-medium">{option.family}</span>
+                  <span className="flex-shrink-0 text-[9px] uppercase tracking-[0.14em] text-neutral-600">
+                    {option.source}
+                  </span>
+                </button>
+              ))
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function ColorField({
+  label,
+  value,
+  disabled,
+  onCommit,
+}: {
+  label: string;
+  value: string;
+  disabled?: boolean;
+  onCommit: (nextValue: string) => void;
+}) {
+  const buttonRef = useRef<HTMLButtonElement | null>(null);
+  const panelRef = useRef<HTMLDivElement | null>(null);
+  const [open, setOpen] = useState(false);
+  const [panelPosition, setPanelPosition] = useState<FloatingPosition | null>(null);
+  const [draftColor, setDraftColor] = useState<ParsedColor>(() => colorFromCss(value));
+  const [hexDraft, setHexDraft] = useState(() => toHexColor(colorFromCss(value)).toUpperCase());
+  const hsv = rgbToHsv(draftColor);
+  const hueColor = formatCssColor({
+    ...hsvToRgb({ hue: hsv.hue, saturation: 1, value: 1 }),
+    alpha: 1,
+  });
+  const opaqueColor = formatCssColor({ ...draftColor, alpha: 1 });
+  const currentColor = formatCssColor(draftColor);
+  const saturationPercent = Math.round(hsv.saturation * 100);
+  const brightnessPercent = Math.round(hsv.value * 100);
+  const alphaPercent = Math.round(draftColor.alpha * 100);
+
+  useEffect(() => {
+    const nextColor = colorFromCss(value);
+    setDraftColor(nextColor);
+    setHexDraft(toHexColor(nextColor).toUpperCase());
+  }, [value]);
+
+  const updatePanelPosition = useCallback(() => {
+    const anchor = buttonRef.current?.getBoundingClientRect();
+    if (!anchor) return;
+    const measured = panelRef.current?.getBoundingClientRect();
+    setPanelPosition(
+      resolveFloatingPanelPosition(
+        anchor,
+        { width: window.innerWidth, height: window.innerHeight },
+        {
+          width: measured?.width || COLOR_PICKER_SIZE.width,
+          height: measured?.height || COLOR_PICKER_SIZE.height,
+        },
+      ),
+    );
+  }, []);
+
+  useLayoutEffect(() => {
+    if (!open) return;
+    updatePanelPosition();
+
+    const handlePositionInvalidated = () => updatePanelPosition();
+    window.addEventListener("resize", handlePositionInvalidated);
+    window.addEventListener("scroll", handlePositionInvalidated, true);
+    return () => {
+      window.removeEventListener("resize", handlePositionInvalidated);
+      window.removeEventListener("scroll", handlePositionInvalidated, true);
+    };
+  }, [open, updatePanelPosition]);
+
+  useEffect(() => {
+    if (!open) return;
+
+    const handlePointerDown = (event: PointerEvent) => {
+      const target = event.target as Node | null;
+      if (!target) return;
+      if (panelRef.current?.contains(target) || buttonRef.current?.contains(target)) return;
+      setOpen(false);
+    };
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") setOpen(false);
+    };
+
+    document.addEventListener("pointerdown", handlePointerDown);
+    document.addEventListener("keydown", handleKeyDown);
+    return () => {
+      document.removeEventListener("pointerdown", handlePointerDown);
+      document.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [open]);
+
+  const commitColor = (nextColor: ParsedColor) => {
+    setDraftColor(nextColor);
+    setHexDraft(toHexColor(nextColor).toUpperCase());
+    onCommit(formatCssColor(nextColor));
+  };
+
+  const commitHsv = (nextHsv: { hue?: number; saturation?: number; value?: number }) => {
+    const rgb = hsvToRgb({
+      hue: nextHsv.hue ?? hsv.hue,
+      saturation: nextHsv.saturation ?? hsv.saturation,
+      value: nextHsv.value ?? hsv.value,
+    });
+    commitColor({ ...rgb, alpha: draftColor.alpha });
+  };
+
+  const updateSaturationValue = (clientX: number, clientY: number, target: HTMLDivElement) => {
+    const rect = target.getBoundingClientRect();
+    const saturation = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width));
+    const nextValue = Math.max(0, Math.min(1, 1 - (clientY - rect.top) / rect.height));
+    commitHsv({ saturation, value: nextValue });
+  };
+
+  const handleHexCommit = (nextHex: string) => {
+    setHexDraft(nextHex);
+    const normalized = nextHex.trim().startsWith("#") ? nextHex.trim() : `#${nextHex.trim()}`;
+    const parsed = parseCssColor(normalized);
+    if (!parsed) return;
+    commitColor({ ...parsed, alpha: draftColor.alpha });
+  };
+
+  const picker = open
+    ? createPortal(
+        <div
+          ref={panelRef}
+          className="fixed z-[9999] w-[292px] overflow-hidden rounded-2xl border border-neutral-700 bg-neutral-950 shadow-2xl shadow-black/50"
+          style={{
+            left: panelPosition?.left ?? -9999,
+            top: panelPosition?.top ?? -9999,
+          }}
+        >
+          <div className="flex items-center justify-between border-b border-neutral-800 px-3 py-2">
+            <div className="min-w-0">
+              <div className="truncate text-[11px] font-medium text-neutral-100">{label}</div>
+              <div className="text-[9px] uppercase tracking-[0.16em] text-neutral-600">Color</div>
+            </div>
+            <button
+              type="button"
+              onClick={() => setOpen(false)}
+              className="flex h-7 w-7 items-center justify-center rounded-lg text-neutral-500 transition-colors hover:bg-neutral-900 hover:text-neutral-200"
+              aria-label="Close color picker"
+            >
+              <X size={13} />
+            </button>
+          </div>
+          <div className="space-y-3 p-3">
+            <div
+              className="relative h-36 cursor-crosshair overflow-hidden rounded-xl border border-neutral-700 shadow-[inset_0_0_0_1px_rgba(255,255,255,0.06)]"
+              style={{
+                backgroundColor: hueColor,
+                touchAction: "none",
+              }}
+              onPointerDown={(event) => {
+                event.preventDefault();
+                event.currentTarget.setPointerCapture(event.pointerId);
+                updateSaturationValue(event.clientX, event.clientY, event.currentTarget);
+              }}
+              onPointerMove={(event) => {
+                if (event.buttons !== 1) return;
+                updateSaturationValue(event.clientX, event.clientY, event.currentTarget);
+              }}
+            >
+              <div className="absolute inset-0 bg-gradient-to-r from-white to-transparent" />
+              <div className="absolute inset-0 bg-gradient-to-t from-black to-transparent" />
+              <div
+                className="pointer-events-none absolute top-0 h-full w-px -translate-x-1/2 bg-white/70 shadow-[0_0_0_1px_rgba(0,0,0,0.45)] mix-blend-difference"
+                style={{ left: `${hsv.saturation * 100}%` }}
+              />
+              <div
+                className="pointer-events-none absolute left-0 h-px w-full -translate-y-1/2 bg-white/70 shadow-[0_0_0_1px_rgba(0,0,0,0.45)] mix-blend-difference"
+                style={{ top: `${(1 - hsv.value) * 100}%` }}
+              />
+              <div
+                className="pointer-events-none absolute h-6 w-6 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white shadow-[0_0_0_1px_rgba(0,0,0,0.85),0_8px_18px_rgba(0,0,0,0.45)]"
+                style={{
+                  left: `${hsv.saturation * 100}%`,
+                  top: `${(1 - hsv.value) * 100}%`,
+                  backgroundColor: opaqueColor,
+                }}
+              />
+            </div>
+
+            <div className="flex min-w-0 items-center gap-3">
+              <div
+                className="h-9 w-9 flex-shrink-0 rounded-xl border border-neutral-600 shadow-[inset_0_1px_0_rgba(255,255,255,0.08)]"
+                style={{ backgroundColor: currentColor }}
+              />
+              <div className="min-w-0 flex-1">
+                <div className="truncate text-[11px] font-medium text-neutral-100">
+                  {currentColor}
+                </div>
+                <div className="mt-0.5 text-[9px] uppercase tracking-[0.12em] text-neutral-600">
+                  S {saturationPercent}% · B {brightnessPercent}% · A {alphaPercent}%
+                </div>
+              </div>
+            </div>
+
+            <ColorSlider
+              label="Hue"
+              value={hsv.hue}
+              min={0}
+              max={360}
+              step={1}
+              displayValue={`${Math.round(hsv.hue)}°`}
+              background="linear-gradient(90deg, #f00, #ff0, #0f0, #0ff, #00f, #f0f, #f00)"
+              thumbColor={hueColor}
+              disabled={disabled}
+              onCommit={(nextHue) => commitHsv({ hue: nextHue })}
+            />
+
+            <ColorSlider
+              label="Alpha"
+              value={draftColor.alpha}
+              min={0}
+              max={1}
+              step={0.01}
+              displayValue={`${alphaPercent}%`}
+              background={`linear-gradient(90deg, transparent, ${opaqueColor})`}
+              thumbColor={currentColor}
+              disabled={disabled}
+              onCommit={(nextAlpha) => commitColor({ ...draftColor, alpha: nextAlpha })}
+            />
+
+            <label className="grid gap-1.5">
+              <span className={LABEL}>Hex</span>
+              <input
+                value={hexDraft}
+                onChange={(event) => handleHexCommit(event.target.value)}
+                className={`${FIELD} h-10 w-full text-[11px] font-medium outline-none`}
+                spellCheck={false}
+              />
+            </label>
+          </div>
+        </div>,
+        document.body,
+      )
+    : null;
+
+  const openPicker = () => {
+    if (disabled) return;
+    setOpen((current) => !current);
+    if (!open) {
+      requestAnimationFrame(updatePanelPosition);
+    }
+  };
+
+  return (
+    <div className="grid min-w-0 gap-1.5">
+      <span className={LABEL}>{label}</span>
+      <button
+        type="button"
+        disabled={disabled}
+        aria-label={`Pick ${label.toLowerCase()} color`}
+        ref={buttonRef}
+        onClick={openPicker}
+        className={`${FIELD} flex items-center gap-3 text-left hover:border-neutral-700 disabled:cursor-not-allowed ${open ? "border-neutral-600" : ""}`}
+      >
+        <div
+          className="relative h-7 w-7 flex-shrink-0 overflow-hidden rounded-lg border border-neutral-700 bg-neutral-950 shadow-[inset_0_1px_0_rgba(255,255,255,0.04)]"
+          style={{ backgroundColor: value || "transparent" }}
+        />
+        <span className="min-w-0 flex-1 truncate text-[11px] font-medium text-neutral-100">
+          {value}
+        </span>
+      </button>
+      {picker}
+    </div>
+  );
+}
+
+function ColorSlider({
+  label,
+  value,
+  min,
+  max,
+  step,
+  displayValue,
+  background,
+  thumbColor,
+  disabled,
+  onCommit,
+}: {
+  label: string;
+  value: number;
+  min: number;
+  max: number;
+  step: number;
+  displayValue: string;
+  background: string;
+  thumbColor: string;
+  disabled?: boolean;
+  onCommit: (nextValue: number) => void;
+}) {
+  const trackRef = useRef<HTMLDivElement | null>(null);
+  const percent = ((value - min) / (max - min)) * 100;
+
+  const commitFromClientX = (clientX: number) => {
+    const rect = trackRef.current?.getBoundingClientRect();
+    if (!rect || rect.width <= 0) return;
+    const rawValue = min + ((clientX - rect.left) / rect.width) * (max - min);
+    const stepped = Math.round(rawValue / step) * step;
+    onCommit(Math.max(min, Math.min(max, stepped)));
+  };
+
+  const commitKeyboardValue = (nextValue: number) => {
+    onCommit(Math.max(min, Math.min(max, nextValue)));
+  };
+
+  return (
+    <div className="grid gap-1.5">
+      <div className="flex items-center justify-between">
+        <span className={LABEL}>{label}</span>
+        <span className="text-[10px] font-medium text-neutral-400">{displayValue}</span>
+      </div>
+      <div
+        role="slider"
+        tabIndex={disabled ? -1 : 0}
+        aria-label={label}
+        aria-valuemin={min}
+        aria-valuemax={max}
+        aria-valuenow={value}
+        aria-disabled={disabled}
+        className={`relative flex h-8 items-center rounded-lg outline-none focus-visible:ring-2 focus-visible:ring-[#f5a400]/40 ${
+          disabled ? "cursor-not-allowed opacity-50" : "cursor-ew-resize"
+        }`}
+        style={{ touchAction: "none" }}
+        onPointerDown={(event) => {
+          if (disabled) return;
+          event.preventDefault();
+          event.currentTarget.focus();
+          event.currentTarget.setPointerCapture(event.pointerId);
+          commitFromClientX(event.clientX);
+        }}
+        onPointerMove={(event) => {
+          if (disabled || event.buttons !== 1) return;
+          commitFromClientX(event.clientX);
+        }}
+        onKeyDown={(event) => {
+          if (disabled) return;
+          if (event.key === "ArrowRight" || event.key === "ArrowUp") {
+            event.preventDefault();
+            commitKeyboardValue(value + step);
+          } else if (event.key === "ArrowLeft" || event.key === "ArrowDown") {
+            event.preventDefault();
+            commitKeyboardValue(value - step);
+          } else if (event.key === "Home") {
+            event.preventDefault();
+            commitKeyboardValue(min);
+          } else if (event.key === "End") {
+            event.preventDefault();
+            commitKeyboardValue(max);
+          }
+        }}
+      >
+        <div
+          ref={trackRef}
+          className="h-4 w-full rounded-full border border-neutral-700 shadow-[inset_0_1px_2px_rgba(0,0,0,0.55)]"
+          style={{ background }}
+        />
+        <div
+          className="pointer-events-none absolute top-1/2 h-6 w-6 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white shadow-[0_0_0_1px_rgba(0,0,0,0.85),0_6px_14px_rgba(0,0,0,0.5)]"
+          style={{ left: `${Math.max(0, Math.min(100, percent))}%`, backgroundColor: thumbColor }}
+        />
+      </div>
+    </div>
+  );
+}
+
+function ImageFillField({
+  projectId,
+  sourceFile,
+  value,
+  assets,
+  disabled,
+  onCommit,
+  onImportAssets,
+}: {
+  projectId: string;
+  sourceFile: string;
+  value: string;
+  assets: string[];
+  disabled?: boolean;
+  onCommit: (nextValue: string) => void;
+  onImportAssets?: (files: FileList) => Promise<string[]>;
+}) {
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
+  const [uploading, setUploading] = useState(false);
+  const imageAssets = useMemo(() => assets.filter((asset) => IMAGE_EXT.test(asset)), [assets]);
+  const selectedAsset = useMemo(
+    () => resolveSelectedAsset(value, sourceFile, imageAssets),
+    [imageAssets, sourceFile, value],
+  );
+  const externalUrlValue = selectedAsset ? "" : value;
+
+  const handleUpload = async (files: FileList | null) => {
+    if (!files?.length || !onImportAssets) return;
+    setUploading(true);
+    try {
+      const uploaded = await onImportAssets(files);
+      const nextImage = uploaded.find((asset) => IMAGE_EXT.test(asset));
+      if (nextImage) {
+        onCommit(`url("${toProjectRootAssetPath(nextImage)}")`);
+      }
+    } finally {
+      setUploading(false);
+    }
+  };
+
+  return (
+    <div className="space-y-4">
+      <div className="grid min-w-0 gap-1.5">
+        <div className="flex min-w-0 flex-wrap items-center justify-between gap-2">
+          <span className={LABEL}>Project asset</span>
+          <button
+            type="button"
+            disabled={disabled || uploading}
+            onClick={() => fileInputRef.current?.click()}
+            className={`inline-flex h-7 max-w-full items-center gap-1.5 rounded-lg border border-neutral-700 bg-neutral-950 px-2.5 text-[11px] font-medium text-neutral-300 transition-colors ${
+              disabled || uploading
+                ? "cursor-not-allowed text-neutral-600"
+                : "cursor-pointer hover:border-neutral-600 hover:text-white"
+            }`}
+          >
+            <Plus size={12} className="flex-shrink-0" />
+            <span className="truncate">{uploading ? "Uploading…" : "Upload image"}</span>
+          </button>
+          <input
+            ref={fileInputRef}
+            type="file"
+            accept="image/*"
+            aria-label="Upload image asset"
+            disabled={disabled || uploading}
+            className="hidden"
+            onChange={async (event) => {
+              await handleUpload(event.target.files);
+              event.target.value = "";
+            }}
+          />
+        </div>
+        {imageAssets.length > 0 ? (
+          <div className="space-y-3">
+            {selectedAsset && (
+              <div className="overflow-hidden rounded-xl border border-neutral-800 bg-neutral-900/80">
+                <img
+                  src={`/api/projects/${projectId}/preview/${selectedAsset}`}
+                  alt={selectedAsset.split("/").pop() ?? selectedAsset}
+                  className="h-28 w-full object-contain bg-neutral-950/80"
+                />
+              </div>
+            )}
+            <div className={FIELD}>
+              <select
+                value={selectedAsset ?? ""}
+                disabled={disabled}
+                onChange={(e) => {
+                  const nextAsset = e.target.value;
+                  if (!nextAsset) {
+                    onCommit("none");
+                    return;
+                  }
+                  onCommit(`url("${toProjectRootAssetPath(nextAsset)}")`);
+                }}
+                className="min-w-0 w-full appearance-none bg-transparent text-[11px] font-medium text-neutral-100 outline-none disabled:cursor-not-allowed disabled:text-neutral-600"
+              >
+                <option value="">None</option>
+                {imageAssets.map((asset) => (
+                  <option key={asset} value={asset}>
+                    {asset}
+                  </option>
+                ))}
+              </select>
+            </div>
+          </div>
+        ) : (
+          <div className="rounded-xl border border-dashed border-neutral-800 bg-neutral-900/50 px-3 py-3 text-[11px] leading-5 text-neutral-500">
+            No image assets yet. Upload one here and Studio will also add it to the Assets tab.
+          </div>
+        )}
+      </div>
+
+      <DetailField
+        label="External URL"
+        value={externalUrlValue}
+        disabled={disabled}
+        onCommit={(next) => onCommit(next.trim() ? `url("${next.trim()}")` : "none")}
+      />
+    </div>
+  );
+}
+
+function MotionControls({
+  draft,
+  active,
+  ownership,
+  maxDuration,
+  disabled,
+  onChange,
+  onClear,
+}: {
+  draft: MotionDraft;
+  active: boolean;
+  ownership: MotionOwnershipReport;
+  maxDuration?: number;
+  disabled?: boolean;
+  onChange: (nextMotion: MotionDraft) => void;
+  onClear: () => void;
+}) {
+  const safeDraft = clampMotionDraftToTimeline(draft, maxDuration);
+  const commitDraft = (nextDraft: MotionDraft) => {
+    onChange(clampMotionDraftToTimeline(nextDraft, maxDuration));
+  };
+  const patchDraft = (partial: Partial<MotionDraft>) => {
+    commitDraft({ ...safeDraft, ...partial });
+  };
+  const patchPresetShape = (partial: Partial<MotionDraft>) => {
+    commitDraft({ ...safeDraft, ...partial, keyframes: undefined });
+  };
+  const changePreset = (preset: MotionPreset) => {
+    commitDraft(
+      buildDefaultMotionDraft(preset, {
+        start: safeDraft.start,
+        duration: safeDraft.duration,
+        ease: safeDraft.ease,
+      }),
+    );
+  };
+  const parseControlNumber = (value: string, fallback: number, min: number): number => {
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? Math.max(min, parsed) : fallback;
+  };
+  const distanceDisabled = disabled || safeDraft.preset === "pop";
+  const curveModel = buildMotionCurveModel(safeDraft);
+  const timelineLimitLabel =
+    maxDuration != null && Number.isFinite(maxDuration) && maxDuration > 0
+      ? `Motion window max ${formatMotionTime(maxDuration)}`
+      : null;
+  const patchTrack = (
+    key: keyof MotionKeyframes,
+    edge: keyof MotionKeyframeRange,
+    nextValue: number,
+  ) => {
+    const keyframes = keyframesFromCurveModel(curveModel);
+    commitDraft({
+      ...safeDraft,
+      keyframes: {
+        ...keyframes,
+        [key]: {
+          ...keyframes[key],
+          [edge]: clampMotionTrackValue(key, nextValue),
+        },
+      },
+    });
+  };
+
+  return (
+    <div className="space-y-4">
+      <MotionOwnershipBadges ownership={ownership} />
+      <SegmentedControl
+        disabled={disabled}
+        value={safeDraft.preset}
+        onChange={(next) => changePreset(next as MotionPreset)}
+        options={MOTION_PRESET_OPTIONS}
+      />
+      <MotionCurveView
+        model={curveModel}
+        disabled={disabled}
+        onTrackChange={(key, edge, value) => patchTrack(key, edge, value)}
+        onEaseChange={(nextEase) => patchDraft({ ease: nextEase })}
+      />
+      <div className={RESPONSIVE_GRID}>
+        <SelectField
+          label="Direction"
+          value={safeDraft.direction}
+          disabled={distanceDisabled}
+          onChange={(next) => patchPresetShape({ direction: next as MotionDirection })}
+          options={MOTION_DIRECTION_OPTIONS}
+        />
+        <DetailField
+          label="Start"
+          value={formatNumericValue(safeDraft.start)}
+          disabled={disabled}
+          onCommit={(next) => patchDraft({ start: parseControlNumber(next, safeDraft.start, 0) })}
+        />
+        <DetailField
+          label="Duration"
+          value={formatNumericValue(safeDraft.duration)}
+          disabled={disabled}
+          onCommit={(next) =>
+            patchDraft({ duration: parseControlNumber(next, safeDraft.duration, 0.05) })
+          }
+        />
+      </div>
+      <MotionEaseField
+        value={safeDraft.ease}
+        disabled={disabled}
+        onChange={(nextEase) => patchDraft({ ease: nextEase })}
+      />
+      {timelineLimitLabel && (
+        <div className="font-mono text-[10px] tabular-nums text-neutral-600">
+          {timelineLimitLabel}
+        </div>
+      )}
+      <div className="grid gap-1.5">
+        <span className={LABEL}>Distance</span>
+        <SliderControl
+          value={safeDraft.distance}
+          min={0}
+          max={160}
+          step={1}
+          disabled={distanceDisabled}
+          displayValue={`${Math.round(safeDraft.distance)}px`}
+          formatDisplayValue={(next) => `${Math.round(next)}px`}
+          onCommit={(next) => patchPresetShape({ distance: next })}
+        />
+      </div>
+      <button
+        type="button"
+        disabled={disabled || !active}
+        onClick={onClear}
+        className="inline-flex h-8 items-center gap-2 rounded-lg border border-neutral-700 bg-neutral-950 px-3 text-[11px] font-medium text-neutral-300 transition-colors hover:border-neutral-600 hover:text-white disabled:cursor-not-allowed disabled:text-neutral-600"
+      >
+        <X size={12} />
+        Clear motion
+      </button>
+    </div>
+  );
+}
+
+function MotionEaseField({
+  value,
+  disabled,
+  onChange,
+}: {
+  value: MotionEase;
+  disabled?: boolean;
+  onChange: (nextEase: MotionEase) => void;
+}) {
+  const isCustom = isMotionBezierEase(value);
+  const bezier = parseMotionBezierEase(value) ?? DEFAULT_CUSTOM_MOTION_BEZIER;
+  const selectOptions = [
+    ...MOTION_EASE_OPTIONS.map((option) => ({
+      label: `${option.group} / ${option.label}`,
+      value: option.value,
+    })),
+    { label: "Custom / Cubic Bezier", value: CUSTOM_EASE_VALUE },
+  ];
+
+  const patchBezier = (partial: Partial<MotionBezierEase>) => {
+    onChange(formatMotionBezierEase({ ...bezier, ...partial }));
+  };
+
+  return (
+    <div className="grid gap-3">
+      <SelectField
+        label="Ease"
+        value={isCustom ? CUSTOM_EASE_VALUE : value}
+        disabled={disabled}
+        onChange={(next) => {
+          if (next === CUSTOM_EASE_VALUE) {
+            onChange(formatMotionBezierEase(bezier));
+            return;
+          }
+          const normalized = normalizeMotionEase(next);
+          if (normalized) onChange(normalized);
+        }}
+        options={selectOptions}
+      />
+      {isCustom && (
+        <div className={`${FIELD} grid gap-3 p-3`}>
+          <div className="flex min-w-0 flex-wrap items-center justify-between gap-2">
+            <div className="min-w-0 truncate font-mono text-[10px] tabular-nums text-neutral-400">
+              {formatMotionBezierEase(bezier)}
+            </div>
+            <div className="flex flex-wrap gap-1.5">
+              {CUSTOM_EASE_PRESETS.map((preset) => (
+                <button
+                  key={preset.label}
+                  type="button"
+                  disabled={disabled}
+                  onClick={() => onChange(formatMotionBezierEase(preset.value))}
+                  className="rounded-md border border-neutral-800 bg-neutral-950 px-2 py-1 text-[10px] font-medium text-neutral-400 transition-colors hover:border-neutral-700 hover:text-neutral-100 disabled:cursor-not-allowed disabled:text-neutral-600"
+                >
+                  {preset.label}
+                </button>
+              ))}
+            </div>
+          </div>
+          <div className="grid gap-3">
+            <BezierSlider
+              label="P1 X"
+              value={bezier.x1}
+              min={0}
+              max={1}
+              disabled={disabled}
+              onCommit={(next) => patchBezier({ x1: next })}
+            />
+            <BezierSlider
+              label="P1 Y"
+              value={bezier.y1}
+              min={-2}
+              max={3}
+              disabled={disabled}
+              onCommit={(next) => patchBezier({ y1: next })}
+            />
+            <BezierSlider
+              label="P2 X"
+              value={bezier.x2}
+              min={0}
+              max={1}
+              disabled={disabled}
+              onCommit={(next) => patchBezier({ x2: next })}
+            />
+            <BezierSlider
+              label="P2 Y"
+              value={bezier.y2}
+              min={-2}
+              max={3}
+              disabled={disabled}
+              onCommit={(next) => patchBezier({ y2: next })}
+            />
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function BezierSlider({
+  label,
+  value,
+  min,
+  max,
+  disabled,
+  onCommit,
+}: {
+  label: string;
+  value: number;
+  min: number;
+  max: number;
+  disabled?: boolean;
+  onCommit: (nextValue: number) => void;
+}) {
+  return (
+    <div className="grid min-w-0 grid-cols-[44px_minmax(0,1fr)] items-center gap-3">
+      <span className="text-[10px] font-semibold uppercase tracking-[0.12em] text-neutral-500">
+        {label}
+      </span>
+      <SliderControl
+        value={value}
+        min={min}
+        max={max}
+        step={0.01}
+        disabled={disabled}
+        displayValue={formatNumericValue(value)}
+        formatDisplayValue={formatNumericValue}
+        onCommit={(next) => onCommit(roundPanelNumber(next))}
+      />
+    </div>
+  );
+}
+
+function keyframesFromCurveModel(model: MotionCurveModel): MotionKeyframes {
+  const entries = new Map(
+    model.tracks.map((track) => [track.key, { from: track.from, to: track.to }]),
+  );
+  return {
+    x: entries.get("x") ?? { from: 0, to: 0 },
+    y: entries.get("y") ?? { from: 0, to: 0 },
+    opacity: entries.get("opacity") ?? { from: 1, to: 1 },
+    scale: entries.get("scale") ?? { from: 1, to: 1 },
+  };
+}
+
+function clampMotionTrackValue(key: keyof MotionKeyframes, value: number): number {
+  const normalized = Number.isFinite(value) ? value : 0;
+  if (key === "opacity") return Math.min(1, Math.max(0, normalized));
+  if (key === "scale") return Math.max(0, normalized);
+  return normalized;
+}
+
+function MotionOwnershipBadges({ ownership }: { ownership: MotionOwnershipReport }) {
+  if (ownership.badges.length === 0) return null;
+  return (
+    <div className="flex min-w-0 flex-wrap gap-2" aria-label="Motion ownership">
+      {ownership.badges.map((badge) => (
+        <span
+          key={`${badge.kind}-${badge.state}`}
+          title={badge.description}
+          className={`inline-flex h-7 min-w-0 items-center gap-1.5 rounded-full border px-2.5 text-[10px] font-semibold uppercase tracking-[0.12em] ${getMotionBadgeClass(
+            badge.state,
+          )}`}
+        >
+          <span className="truncate">{badge.label}</span>
+          <span className="text-[9px] opacity-70">{badge.state}</span>
+        </span>
+      ))}
+    </div>
+  );
+}
+
+function getMotionBadgeClass(state: MotionOwnershipState): string {
+  switch (state) {
+    case "Editable":
+      return "border-[#3ce6ac]/35 bg-[#3ce6ac]/10 text-[#c4fff0]";
+    case "Mixed":
+      return "border-amber-400/35 bg-amber-400/10 text-amber-100";
+    case "Unsafe":
+      return "border-red-400/35 bg-red-400/10 text-red-100";
+    case "Detected":
+    default:
+      return "border-neutral-700 bg-neutral-950/70 text-neutral-300";
+  }
+}
+
+function MotionCurveView({
+  model,
+  disabled,
+  onTrackChange,
+  onEaseChange,
+}: {
+  model: MotionCurveModel;
+  disabled?: boolean;
+  onTrackChange: (
+    key: keyof MotionKeyframes,
+    edge: keyof MotionKeyframeRange,
+    value: number,
+  ) => void;
+  onEaseChange: (nextEase: MotionEase) => void;
+}) {
+  const primaryTrack = selectPrimaryMotionTrack(model);
+
+  return (
+    <div className={`${FIELD} space-y-4 p-4`} aria-label="Motion curve visualization">
+      <div className="flex min-w-0 items-center justify-between gap-3">
+        <div className="min-w-0 text-[10px] font-semibold uppercase tracking-[0.16em] text-neutral-500">
+          Curve
+        </div>
+        <div className="flex flex-shrink-0 items-center gap-2 font-mono text-[10px] tabular-nums text-neutral-500">
+          <span>{formatMotionTime(model.start)}</span>
+          <span className="text-neutral-700">/</span>
+          <span>{formatMotionTime(model.duration)}</span>
+          <span className="rounded-md border border-neutral-800 px-1.5 py-0.5 text-[9px] uppercase tracking-[0.08em] text-neutral-400">
+            {getMotionEaseLabel(model.ease)}
+          </span>
+        </div>
+      </div>
+
+      <MotionHeroCurve
+        model={model}
+        track={primaryTrack}
+        disabled={disabled}
+        onTrackChange={onTrackChange}
+        onEaseChange={onEaseChange}
+      />
+
+      <div className="grid gap-3 border-t border-neutral-800/70 pt-3">
+        {model.tracks.map((track) => (
+          <MotionTrackEditorRow
+            key={track.key}
+            track={track}
+            disabled={disabled}
+            onTrackChange={onTrackChange}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function selectPrimaryMotionTrack(model: MotionCurveModel): MotionCurveTrack {
+  const preferred: Array<MotionCurveTrack["key"]> = ["y", "x", "scale", "opacity"];
+  for (const key of preferred) {
+    const activeTrack = model.tracks.find((track) => track.key === key && track.active);
+    if (activeTrack) return activeTrack;
+  }
+  return (
+    model.tracks[0] ?? {
+      key: "opacity",
+      label: "Opacity",
+      from: 0,
+      to: 1,
+      unit: "",
+      active: true,
+      points: [],
+    }
+  );
+}
+
+function MotionHeroCurve({
+  model,
+  track,
+  disabled,
+  onTrackChange,
+  onEaseChange,
+}: {
+  model: MotionCurveModel;
+  track: MotionCurveTrack;
+  disabled?: boolean;
+  onTrackChange: (
+    key: keyof MotionKeyframes,
+    edge: keyof MotionKeyframeRange,
+    value: number,
+  ) => void;
+  onEaseChange: (nextEase: MotionEase) => void;
+}) {
+  const svgRef = useRef<SVGSVGElement | null>(null);
+  const draggingEdgeRef = useRef<keyof MotionKeyframeRange | null>(null);
+  const draggingBezierHandleRef = useRef<keyof MotionBezierEase | null>(null);
+  const [draggingEdge, setDraggingEdge] = useState<keyof MotionKeyframeRange | null>(null);
+  const [draggingBezierHandle, setDraggingBezierHandle] = useState<keyof MotionBezierEase | null>(
+    null,
+  );
+  const domain = buildHeroDomain(track, model.ease);
+  const bezier = parseMotionBezierEase(model.ease);
+  const ticks = buildHeroTicks(domain, track.unit);
+  const path = buildHeroCurvePath(model, track, domain);
+  const startX = getHeroX(model.markers[0]?.percent ?? 0);
+  const endX = getHeroX(100);
+  const xSpan = Math.max(1, endX - startX);
+  const startY = getHeroY(track.from, domain);
+  const endY = getHeroY(track.to, domain);
+  const commitFromPointer = useCallback(
+    (edge: keyof MotionKeyframeRange, clientY: number) => {
+      const svg = svgRef.current;
+      const rect = svg?.getBoundingClientRect();
+      if (!rect || rect.height <= 0) return;
+      const svgY = ((clientY - rect.top) / rect.height) * 170;
+      onTrackChange(track.key, edge, clampMotionTrackValue(track.key, getHeroValue(svgY, domain)));
+    },
+    [domain, onTrackChange, track.key],
+  );
+  const commitBezierFromPointer = useCallback(
+    (handle: keyof MotionBezierEase, clientX: number, clientY: number) => {
+      if (!bezier || Math.abs(track.to - track.from) < 0.0001) return;
+      const svg = svgRef.current;
+      const rect = svg?.getBoundingClientRect();
+      if (!rect || rect.width <= 0 || rect.height <= 0) return;
+      const svgX = ((clientX - rect.left) / rect.width) * 320;
+      const svgY = ((clientY - rect.top) / rect.height) * 170;
+      const nextX = Math.min(1, Math.max(0, (svgX - startX) / xSpan));
+      const nextValue = getHeroValue(svgY, domain);
+      const nextY = Math.min(3, Math.max(-2, (nextValue - track.from) / (track.to - track.from)));
+      const nextBezier =
+        handle === "x1" || handle === "y1"
+          ? { ...bezier, x1: roundPanelNumber(nextX), y1: roundPanelNumber(nextY) }
+          : { ...bezier, x2: roundPanelNumber(nextX), y2: roundPanelNumber(nextY) };
+      onEaseChange(formatMotionBezierEase(nextBezier));
+    },
+    [bezier, domain, onEaseChange, startX, track.from, track.to, xSpan],
+  );
+  const changeByStep = (edge: keyof MotionKeyframeRange, delta: number) => {
+    onTrackChange(track.key, edge, clampMotionTrackValue(track.key, track[edge] + delta));
+  };
+  const valueStep = track.unit === "px" ? 1 : 0.01;
+  const canEdit = !disabled && track.active;
+  const canEditBezier = canEdit && bezier != null && Math.abs(track.to - track.from) >= 0.0001;
+  const bezierP1 = bezier
+    ? {
+        x: startX + bezier.x1 * xSpan,
+        y: getHeroY(track.from + (track.to - track.from) * bezier.y1, domain),
+      }
+    : null;
+  const bezierP2 = bezier
+    ? {
+        x: startX + bezier.x2 * xSpan,
+        y: getHeroY(track.from + (track.to - track.from) * bezier.y2, domain),
+      }
+    : null;
+
+  const endpoint = (edge: keyof MotionKeyframeRange, x: number, y: number) => (
+    <g key={edge}>
+      <circle
+        cx={x}
+        cy={y}
+        r="10"
+        fill="transparent"
+        className={canEdit ? "cursor-ns-resize" : "cursor-default"}
+        onPointerDown={(event) => {
+          if (!canEdit) return;
+          event.preventDefault();
+          event.stopPropagation();
+          draggingEdgeRef.current = edge;
+          setDraggingEdge(edge);
+          trySetElementPointerCapture(event.currentTarget, event.pointerId);
+          commitFromPointer(edge, event.clientY);
+        }}
+      />
+      <circle
+        cx={x}
+        cy={y}
+        r="4.8"
+        fill="#f8d85c"
+        stroke={draggingEdge === edge ? "#fff3b0" : "transparent"}
+        strokeWidth="2"
+        className={canEdit ? "pointer-events-none" : "opacity-70"}
+      />
+      <circle
+        cx={x}
+        cy={y}
+        r="13"
+        fill="transparent"
+        stroke={draggingEdge === edge ? "rgba(248,216,92,0.26)" : "transparent"}
+        strokeWidth="2"
+        className="pointer-events-none"
+      />
+    </g>
+  );
+  const bezierHandle = (
+    handle: "x1" | "x2",
+    point: { x: number; y: number },
+    anchor: { x: number; y: number },
+  ) => (
+    <g key={handle}>
+      <line
+        x1={anchor.x}
+        y1={anchor.y}
+        x2={point.x}
+        y2={point.y}
+        stroke="rgba(248,216,92,0.25)"
+        strokeDasharray="3 5"
+      />
+      <circle
+        cx={point.x}
+        cy={point.y}
+        r="10"
+        fill="transparent"
+        className={canEditBezier ? "cursor-move" : "cursor-default"}
+        onPointerDown={(event) => {
+          if (!canEditBezier) return;
+          event.preventDefault();
+          event.stopPropagation();
+          draggingBezierHandleRef.current = handle;
+          setDraggingBezierHandle(handle);
+          trySetElementPointerCapture(event.currentTarget, event.pointerId);
+          commitBezierFromPointer(handle, event.clientX, event.clientY);
+        }}
+      />
+      <circle
+        cx={point.x}
+        cy={point.y}
+        r="4"
+        fill="#080808"
+        stroke={draggingBezierHandle === handle ? "#fff3b0" : "#f8d85c"}
+        strokeWidth="2"
+        className="pointer-events-none"
+      />
+    </g>
+  );
+
+  return (
+    <div className="overflow-hidden rounded-2xl border border-neutral-800 bg-neutral-950/80 px-2 py-3 shadow-[inset_0_1px_0_rgba(255,255,255,0.03)]">
+      <svg
+        ref={svgRef}
+        viewBox="0 0 320 170"
+        className="h-[170px] w-full outline-none"
+        role="group"
+        aria-label={`${track.label} curve. Drag endpoints to edit from and to values.`}
+        style={{ touchAction: "none" }}
+        onPointerMove={(event) => {
+          const edge = draggingEdgeRef.current;
+          const bezierHandleKey = draggingBezierHandleRef.current;
+          if (disabled || (!edge && !bezierHandleKey)) return;
+          event.preventDefault();
+          if (edge) commitFromPointer(edge, event.clientY);
+          if (bezierHandleKey)
+            commitBezierFromPointer(bezierHandleKey, event.clientX, event.clientY);
+        }}
+        onPointerUp={() => {
+          draggingEdgeRef.current = null;
+          draggingBezierHandleRef.current = null;
+          setDraggingEdge(null);
+          setDraggingBezierHandle(null);
+        }}
+        onPointerCancel={() => {
+          draggingEdgeRef.current = null;
+          draggingBezierHandleRef.current = null;
+          setDraggingEdge(null);
+          setDraggingBezierHandle(null);
+        }}
+      >
+        <rect x="0" y="0" width="320" height="170" rx="16" fill="#080808" />
+        {ticks.map((tick) => (
+          <g key={`${tick.value}-${tick.label}`}>
+            <line
+              x1="54"
+              x2="304"
+              y1={tick.y}
+              y2={tick.y}
+              stroke="rgba(255,255,255,0.13)"
+              strokeDasharray="4 6"
+            />
+            <text
+              x="46"
+              y={tick.y + 4}
+              fill="rgba(255,255,255,0.38)"
+              fontSize="10"
+              textAnchor="end"
+            >
+              {tick.label}
+            </text>
+          </g>
+        ))}
+        <line x1={startX} x2={startX} y1="18" y2="142" stroke="rgba(248,216,92,0.18)" />
+        <path
+          d={path}
+          fill="none"
+          stroke={track.active ? "#f8d85c" : "rgba(248,216,92,0.45)"}
+          strokeWidth="3"
+          strokeLinecap="round"
+        />
+        {bezierP1 && bezierHandle("x1", bezierP1, { x: startX, y: startY })}
+        {bezierP2 && bezierHandle("x2", bezierP2, { x: endX, y: endY })}
+        {endpoint("from", startX, startY)}
+        {endpoint("to", endX, endY)}
+        <text x="54" y="160" fill="rgba(255,255,255,0.4)" fontSize="10">
+          {formatMotionTime(0)}
+        </text>
+        <text x="304" y="160" fill="rgba(255,255,255,0.4)" fontSize="10" textAnchor="end">
+          {formatMotionTime(model.windowEnd)}
+        </text>
+        <text x="54" y="14" fill="rgba(255,255,255,0.55)" fontSize="10">
+          {track.label}
+        </text>
+      </svg>
+      <div className="mt-2 grid grid-cols-2 gap-2">
+        <button
+          type="button"
+          disabled={!canEdit}
+          onKeyDown={(event) => {
+            if (!canEdit) return;
+            if (event.key === "ArrowUp") {
+              event.preventDefault();
+              changeByStep("from", valueStep);
+            } else if (event.key === "ArrowDown") {
+              event.preventDefault();
+              changeByStep("from", -valueStep);
+            }
+          }}
+          className="rounded-lg border border-neutral-800 bg-neutral-950/70 px-2 py-1 text-left font-mono text-[9px] tabular-nums text-neutral-500 outline-none transition-colors focus-visible:border-[#f8d85c]/60 disabled:cursor-default disabled:opacity-60"
+        >
+          From {formatNumericValue(track.from)}
+          {track.unit}
+        </button>
+        <button
+          type="button"
+          disabled={!canEdit}
+          onKeyDown={(event) => {
+            if (!canEdit) return;
+            if (event.key === "ArrowUp") {
+              event.preventDefault();
+              changeByStep("to", valueStep);
+            } else if (event.key === "ArrowDown") {
+              event.preventDefault();
+              changeByStep("to", -valueStep);
+            }
+          }}
+          className="rounded-lg border border-neutral-800 bg-neutral-950/70 px-2 py-1 text-right font-mono text-[9px] tabular-nums text-neutral-500 outline-none transition-colors focus-visible:border-[#f8d85c]/60 disabled:cursor-default disabled:opacity-60"
+        >
+          To {formatNumericValue(track.to)}
+          {track.unit}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function MotionTrackEditorRow({
+  track,
+  disabled,
+  onTrackChange,
+}: {
+  track: MotionCurveTrack;
+  disabled?: boolean;
+  onTrackChange: (
+    key: keyof MotionKeyframes,
+    edge: keyof MotionKeyframeRange,
+    value: number,
+  ) => void;
+}) {
+  return (
+    <div
+      className={`grid grid-cols-[70px_minmax(0,1fr)] items-center gap-3 text-[10px] ${
+        track.active ? "text-neutral-200" : "text-neutral-600"
+      }`}
+    >
+      <div className="min-w-0">
+        <div className="truncate font-semibold uppercase tracking-[0.12em]">{track.label}</div>
+        <div className="mt-0.5 font-mono text-[9px] tabular-nums text-neutral-600">
+          {formatNumericValue(track.from)}
+          {track.unit} {"->"} {formatNumericValue(track.to)}
+          {track.unit}
+        </div>
+      </div>
+      <div className="grid min-w-0 grid-cols-2 gap-2">
+        <MotionKeyframeField
+          label={`${track.label} from`}
+          value={track.from}
+          unit={track.unit}
+          disabled={disabled}
+          onCommit={(next) => onTrackChange(track.key, "from", next)}
+        />
+        <MotionKeyframeField
+          label={`${track.label} to`}
+          value={track.to}
+          unit={track.unit}
+          disabled={disabled}
+          onCommit={(next) => onTrackChange(track.key, "to", next)}
+        />
+      </div>
+    </div>
+  );
+}
+
+function MotionKeyframeField({
   label,
   value,
-  onChange,
+  unit,
+  disabled,
+  onCommit,
 }: {
   label: string;
+  value: number;
+  unit: "px" | "";
+  disabled?: boolean;
+  onCommit: (nextValue: number) => void;
+}) {
+  const parseMotionInput = (next: string) => {
+    const parsed = Number.parseFloat(next);
+    onCommit(Number.isFinite(parsed) ? parsed : value);
+  };
+  return (
+    <label
+      className="flex h-7 min-w-0 items-center rounded-md border border-neutral-800 bg-neutral-950/70 px-1.5"
+      data-panel-wheel-lock="true"
+    >
+      <span className="sr-only">{label}</span>
+      <CommitField
+        value={formatNumericValue(value)}
+        disabled={disabled}
+        onCommit={parseMotionInput}
+      />
+      {unit && <span className="ml-0.5 flex-shrink-0 text-[9px] text-neutral-600">{unit}</span>}
+    </label>
+  );
+}
+
+interface HeroDomain {
+  min: number;
+  max: number;
+}
+
+function buildHeroDomain(track: MotionCurveTrack, ease: MotionEase): HeroDomain {
+  const sampledValues = [track.from, track.to];
+  for (let index = 0; index <= 40; index += 1) {
+    const progress = sampleMotionEase(ease, index / 40);
+    sampledValues.push(track.from + (track.to - track.from) * progress);
+  }
+
+  if (track.unit === "px") {
+    const minValue = Math.min(0, ...sampledValues);
+    const maxValue = Math.max(0, ...sampledValues);
+    const span = Math.max(1, maxValue - minValue);
+    const padding = Math.max(8, span * 0.12);
+    return {
+      min: roundMotionDisplayNumber(minValue - (minValue < 0 ? padding : 0)),
+      max: roundMotionDisplayNumber(maxValue + padding),
+    };
+  }
+
+  if (track.key === "opacity") return { min: 0, max: 1 };
+
+  const maxValue = Math.max(1.2, ...sampledValues);
+  return {
+    min: 0,
+    max: roundMotionDisplayNumber(maxValue),
+  };
+}
+
+function roundMotionDisplayNumber(value: number): number {
+  const normalized = Math.abs(value) < 0.0001 ? 0 : value;
+  return Math.round(normalized * 1000) / 1000;
+}
+
+function buildHeroTicks(domain: HeroDomain, unit: MotionCurveTrack["unit"]) {
+  return [domain.max, (domain.min + domain.max) / 2, domain.min].map((value) => ({
+    value,
+    y: getHeroY(value, domain),
+    label: `${formatNumericValue(value)}${unit}`,
+  }));
+}
+
+function buildHeroCurvePath(
+  model: MotionCurveModel,
+  track: MotionCurveTrack,
+  domain: HeroDomain,
+): string {
+  const startX = getHeroX(model.markers[0]?.percent ?? 0);
+  const endX = getHeroX(100);
+  const span = Math.max(1, endX - startX);
+  const fromY = getHeroY(track.from, domain);
+  const points = [`M 54 ${fromY}`, `L ${startX} ${fromY}`];
+  for (let index = 1; index <= 40; index += 1) {
+    const rawProgress = index / 40;
+    const easedProgress = sampleMotionEase(model.ease, rawProgress);
+    const value = track.from + (track.to - track.from) * easedProgress;
+    points.push(`L ${roundPanelNumber(startX + span * rawProgress)} ${getHeroY(value, domain)}`);
+  }
+  points.push(`L ${endX} ${getHeroY(track.to, domain)}`);
+  return points.join(" ");
+}
+
+function getHeroX(percent: number): number {
+  return 54 + (Math.min(100, Math.max(0, percent)) / 100) * 250;
+}
+
+function getHeroY(value: number, domain: HeroDomain): number {
+  if (Math.abs(domain.max - domain.min) < 0.0001) return 80;
+  const normalized = (value - domain.min) / (domain.max - domain.min);
+  return Math.round((142 - normalized * 112) * 100) / 100;
+}
+
+function getHeroValue(y: number, domain: HeroDomain): number {
+  const clampedY = Math.min(142, Math.max(30, y));
+  const normalized = (142 - clampedY) / 112;
+  return roundPanelNumber(domain.min + normalized * (domain.max - domain.min));
+}
+
+function formatMotionTime(value: number): string {
+  return `${formatNumericValue(value)}s`;
+}
+
+function GradientField({
+  value,
+  fallbackColor,
+  disabled,
+  onCommit,
+}: {
   value: string;
-  onChange: (v: string) => void;
+  fallbackColor: string | undefined;
+  disabled?: boolean;
+  onCommit: (nextValue: string) => void;
+}) {
+  const previewRef = useRef<HTMLDivElement | null>(null);
+  const parsed = parseGradient(value) ?? buildDefaultGradientModel(fallbackColor);
+
+  const commit = (next: GradientModel) => onCommit(serializeGradient(next));
+
+  const patch = (partial: Partial<GradientModel>) => commit({ ...parsed, ...partial });
+
+  const updateStop = (index: number, partial: Partial<GradientModel["stops"][number]>) => {
+    const stops = parsed.stops.map((stop, stopIndex) =>
+      stopIndex === index ? { ...stop, ...partial } : stop,
+    );
+    commit({ ...parsed, stops });
+  };
+
+  const addStop = (position?: number) => {
+    const nextGradient =
+      position != null
+        ? insertGradientStop(parsed, position)
+        : insertGradientStop(
+            parsed,
+            parsed.stops.at(-1)?.position != null
+              ? Math.min(100, (parsed.stops.at(-1)?.position ?? 90) + 10)
+              : 100,
+          );
+    commit(nextGradient);
+  };
+
+  const removeStop = (index: number) => {
+    if (parsed.stops.length <= 2) return;
+    commit({ ...parsed, stops: parsed.stops.filter((_, stopIndex) => stopIndex !== index) });
+  };
+
+  const previewStyle = {
+    backgroundImage: serializeGradient(parsed),
+  };
+
+  return (
+    <div className="space-y-4">
+      <div className={`${FIELD} space-y-3 p-3`}>
+        <div
+          ref={previewRef}
+          className="relative h-11 overflow-hidden rounded-lg border border-neutral-700"
+          style={previewStyle}
+          onClick={(event) => {
+            if (disabled) return;
+            const rect = previewRef.current?.getBoundingClientRect();
+            if (!rect || rect.width <= 0) return;
+            const position = ((event.clientX - rect.left) / rect.width) * 100;
+            addStop(position);
+          }}
+        >
+          {parsed.stops.map((stop, index) => (
+            <div
+              key={`stop-preview-${index}`}
+              className="absolute top-1/2 h-4 w-4 -translate-y-1/2 rounded-full border-2 border-white/90 shadow-[0_0_0_1px_rgba(0,0,0,0.35)]"
+              style={{
+                left: `calc(${stop.position}% - 8px)`,
+                backgroundColor: stop.color,
+              }}
+            />
+          ))}
+        </div>
+        <div className="flex min-w-0 flex-wrap items-center gap-2">
+          <SegmentedControl
+            disabled={disabled}
+            value={parsed.kind}
+            onChange={(next) => patch({ kind: next as GradientModel["kind"] })}
+            options={[
+              { label: "Linear", value: "linear" },
+              { label: "Radial", value: "radial" },
+              { label: "Conic", value: "conic" },
+            ]}
+          />
+          <label className="flex items-center gap-2 text-[11px] font-medium text-neutral-400">
+            <input
+              type="checkbox"
+              checked={parsed.repeating}
+              disabled={disabled}
+              onChange={(e) => patch({ repeating: e.target.checked })}
+              className="h-4 w-4 rounded border-neutral-700 bg-neutral-950 text-[#3ce6ac] focus:ring-[#3ce6ac]"
+            />
+            Repeat
+          </label>
+          <button
+            type="button"
+            disabled={disabled}
+            onClick={() =>
+              commit({
+                ...parsed,
+                stops: [...parsed.stops].reverse().map((stop) => ({
+                  ...stop,
+                  position: 100 - stop.position,
+                })),
+              })
+            }
+            className="inline-flex h-7 items-center gap-1.5 rounded-lg border border-neutral-700 bg-neutral-950 px-2.5 text-[11px] font-medium text-neutral-300 transition-colors hover:border-neutral-600 hover:text-white disabled:cursor-not-allowed disabled:text-neutral-600"
+          >
+            <RotateCcw size={12} />
+            Reverse
+          </button>
+        </div>
+      </div>
+
+      {(parsed.kind === "linear" || parsed.kind === "conic") && (
+        <div className="grid gap-1.5">
+          <span className={LABEL}>{parsed.kind === "linear" ? "Angle" : "Start angle"}</span>
+          <SliderControl
+            value={parsed.angle}
+            min={0}
+            max={360}
+            step={1}
+            disabled={disabled}
+            displayValue={`${Math.round(parsed.angle)}°`}
+            formatDisplayValue={(next) => `${Math.round(next)}°`}
+            onCommit={(next) => patch({ angle: next })}
+          />
+        </div>
+      )}
+
+      {parsed.kind === "radial" && (
+        <div className={RESPONSIVE_GRID}>
+          <SelectField
+            label="Shape"
+            value={parsed.shape}
+            disabled={disabled}
+            onChange={(next) => patch({ shape: next as GradientModel["shape"] })}
+            options={["ellipse", "circle"]}
+          />
+          <SelectField
+            label="Size"
+            value={parsed.radialSize}
+            disabled={disabled}
+            onChange={(next) => patch({ radialSize: next as GradientModel["radialSize"] })}
+            options={["closest-side", "closest-corner", "farthest-side", "farthest-corner"]}
+          />
+        </div>
+      )}
+
+      {(parsed.kind === "radial" || parsed.kind === "conic") && (
+        <div className={RESPONSIVE_GRID}>
+          <div className="grid min-w-0 gap-1.5">
+            <span className={LABEL}>Center X</span>
+            <SliderControl
+              value={parsed.centerX}
+              min={0}
+              max={100}
+              step={1}
+              disabled={disabled}
+              displayValue={`${Math.round(parsed.centerX)}%`}
+              formatDisplayValue={(next) => `${Math.round(next)}%`}
+              onCommit={(next) => patch({ centerX: next })}
+            />
+          </div>
+          <div className="grid min-w-0 gap-1.5">
+            <span className={LABEL}>Center Y</span>
+            <SliderControl
+              value={parsed.centerY}
+              min={0}
+              max={100}
+              step={1}
+              disabled={disabled}
+              displayValue={`${Math.round(parsed.centerY)}%`}
+              formatDisplayValue={(next) => `${Math.round(next)}%`}
+              onCommit={(next) => patch({ centerY: next })}
+            />
+          </div>
+        </div>
+      )}
+
+      <div className="space-y-3">
+        <div className="flex items-center justify-between">
+          <span className={LABEL}>Stops</span>
+          <button
+            type="button"
+            disabled={disabled || parsed.stops.length >= 6}
+            onClick={() => addStop()}
+            className="inline-flex h-7 items-center gap-1.5 rounded-lg border border-neutral-700 bg-neutral-950 px-2.5 text-[11px] font-medium text-neutral-300 transition-colors hover:border-neutral-600 hover:text-white disabled:cursor-not-allowed disabled:text-neutral-600"
+          >
+            <Plus size={12} />
+            Add stop
+          </button>
+        </div>
+        <div className="space-y-3">
+          {parsed.stops.map((stop, index) => (
+            <div
+              key={`stop-editor-${index}`}
+              className="grid min-w-0 grid-cols-[minmax(0,1fr)_68px_28px] gap-2"
+            >
+              <ColorField
+                label={`Stop ${index + 1}`}
+                value={stop.color}
+                disabled={disabled}
+                onCommit={(next) => updateStop(index, { color: next })}
+              />
+              <DetailField
+                label="Pos"
+                value={`${Math.round(stop.position)}%`}
+                disabled={disabled}
+                onCommit={(next) =>
+                  updateStop(index, {
+                    position: Number.parseFloat(next.replace("%", "")) || 0,
+                  })
+                }
+              />
+              <button
+                type="button"
+                disabled={disabled || parsed.stops.length <= 2}
+                onClick={() => removeStop(index)}
+                className="mt-[22px] flex h-10 items-center justify-center rounded-lg border border-neutral-700 bg-neutral-950 text-neutral-400 transition-colors hover:border-neutral-600 hover:text-white disabled:cursor-not-allowed disabled:text-neutral-700"
+                aria-label={`Remove stop ${index + 1}`}
+              >
+                <X size={12} />
+              </button>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function SliderControl({
+  value,
+  min,
+  max,
+  step,
+  displayValue,
+  formatDisplayValue,
+  disabled,
+  onCommit,
+}: {
+  value: number;
+  min: number;
+  max: number;
+  step: number;
+  displayValue: string;
+  formatDisplayValue?: (nextValue: number) => string;
+  disabled?: boolean;
+  onCommit: (nextValue: number) => void;
 }) {
+  const [draft, setDraft] = useState(value);
+  const commitTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const valueRef = useRef(value);
+
+  valueRef.current = value;
+
+  useEffect(() => {
+    setDraft(value);
+  }, [value]);
+
+  useEffect(
+    () => () => {
+      if (commitTimerRef.current) clearTimeout(commitTimerRef.current);
+    },
+    [],
+  );
+
+  const commitDraft = (nextDraft: number) => {
+    if (commitTimerRef.current) clearTimeout(commitTimerRef.current);
+    if (nextDraft !== valueRef.current) {
+      onCommit(nextDraft);
+    }
+  };
+
+  const scheduleCommit = (nextDraft: number) => {
+    if (commitTimerRef.current) clearTimeout(commitTimerRef.current);
+    commitTimerRef.current = setTimeout(() => {
+      if (nextDraft !== valueRef.current) {
+        onCommit(nextDraft);
+      }
+    }, 40);
+  };
+
+  const renderedDisplayValue = formatDisplayValue?.(draft) ?? displayValue;
+
   return (
-    <div className="flex items-center gap-2">
-      <span className="text-2xs text-neutral-600 w-16 flex-shrink-0 text-right">{label}</span>
+    <div className="grid min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-2">
       <input
-        type="text"
-        value={value}
-        onChange={(e) => onChange(e.target.value)}
-        className="flex-1 bg-neutral-900 border border-neutral-800 rounded px-1.5 py-0.5 text-2xs text-neutral-200 font-mono outline-none focus:border-neutral-600 min-w-0"
+        type="range"
+        min={min}
+        max={max}
+        step={step}
+        value={draft}
+        disabled={disabled}
+        onChange={(e) => {
+          const nextDraft = Number(e.target.value);
+          setDraft(nextDraft);
+          scheduleCommit(nextDraft);
+        }}
+        onMouseUp={() => commitDraft(draft)}
+        onTouchEnd={() => commitDraft(draft)}
+        onBlur={() => commitDraft(draft)}
+        className="h-2 min-w-0 w-full cursor-pointer appearance-none rounded-full bg-neutral-800 accent-[#3ce6ac] disabled:cursor-not-allowed"
       />
+      <div className="min-w-[52px] rounded-xl border border-neutral-800 bg-neutral-900 px-2 py-2 text-right text-[11px] font-medium text-neutral-100 shadow-[inset_0_1px_0_rgba(255,255,255,0.03)]">
+        {renderedDisplayValue}
+      </div>
     </div>
   );
 }
 
-function ColorRow({
+function SegmentedControl({
+  options,
+  value,
+  disabled,
+  onChange,
+}: {
+  options: Array<{ label: string; value: string }>;
+  value: string;
+  disabled?: boolean;
+  onChange: (nextValue: string) => void;
+}) {
+  return (
+    <div
+      className="grid min-w-0 gap-1 rounded-xl bg-neutral-900 p-1 shadow-[inset_0_1px_0_rgba(255,255,255,0.03)]"
+      style={{ gridTemplateColumns: `repeat(${options.length}, minmax(0, 1fr))` }}
+    >
+      {options.map((option) => {
+        const selected = option.value === value;
+        return (
+          <button
+            key={option.value}
+            type="button"
+            disabled={disabled}
+            onClick={() => onChange(option.value)}
+            className={`min-w-0 truncate rounded-lg px-2 py-1.5 text-[11px] font-medium transition-colors disabled:cursor-not-allowed ${
+              selected
+                ? "bg-neutral-800 text-white shadow-[0_1px_3px_rgba(0,0,0,0.28)]"
+                : "text-neutral-500 hover:text-neutral-200"
+            }`}
+          >
+            {option.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+function SelectField({
   label,
   value,
+  disabled,
+  options,
   onChange,
 }: {
   label: string;
   value: string;
-  onChange: (v: string) => void;
+  disabled?: boolean;
+  options: Array<string | { label: string; value: string }>;
+  onChange: (nextValue: string) => void;
 }) {
   return (
-    <div className="flex items-center gap-2">
-      <span className="text-2xs text-neutral-600 w-16 flex-shrink-0 text-right">{label}</span>
-      <div className="flex items-center gap-1 flex-1">
-        <div
-          className="w-5 h-5 rounded border border-neutral-700 flex-shrink-0"
-          style={{ backgroundColor: value }}
-        />
-        <input
-          type="text"
+    <label className="grid min-w-0 gap-1.5">
+      <span className={LABEL}>{label}</span>
+      <div className={FIELD}>
+        <select
           value={value}
+          disabled={disabled}
           onChange={(e) => onChange(e.target.value)}
-          className="flex-1 bg-neutral-900 border border-neutral-800 rounded px-1.5 py-0.5 text-2xs text-neutral-200 font-mono outline-none focus:border-neutral-600 min-w-0"
-        />
+          className="min-w-0 w-full appearance-none bg-transparent text-[11px] font-medium text-neutral-100 outline-none disabled:cursor-not-allowed disabled:text-neutral-600"
+        >
+          {options.map((option) => (
+            <option
+              key={typeof option === "string" ? option : option.value}
+              value={typeof option === "string" ? option : option.value}
+            >
+              {typeof option === "string" ? option : option.label}
+            </option>
+          ))}
+        </select>
       </div>
-    </div>
+    </label>
+  );
+}
+
+function Section({
+  title,
+  icon,
+  children,
+  accessory,
+}: {
+  title: string;
+  icon: ReactNode;
+  children: ReactNode;
+  accessory?: ReactNode;
+}) {
+  return (
+    <section className="min-w-0 border-t border-neutral-800/80 px-4 py-4">
+      <div className="mb-3 flex min-w-0 flex-wrap items-center justify-between gap-2">
+        <div className="flex min-w-0 items-center gap-2.5">
+          <span className="flex-shrink-0 text-neutral-500">{icon}</span>
+          <h3 className="text-[11px] font-semibold uppercase tracking-[0.12em] text-neutral-300">
+            {title}
+          </h3>
+        </div>
+        {accessory}
+      </div>
+      {children}
+    </section>
   );
 }
 
-function SectionHeader({ icon: Icon, label }: { icon: typeof Move; label: string }) {
+function SelectionColorRow({
+  swatch,
+  token,
+  sources,
+}: {
+  swatch: string;
+  token: string;
+  sources: string[];
+}) {
   return (
-    <div className="flex items-center gap-1.5 mt-2 mb-1">
-      <Icon size={10} className="text-neutral-600" />
-      <span className="text-2xs font-medium text-neutral-500 uppercase tracking-wider">
-        {label}
-      </span>
+    <div className={`${FIELD} flex min-w-0 items-center gap-3`}>
+      <div
+        className="h-7 w-7 flex-shrink-0 rounded-lg border border-neutral-700"
+        style={{ backgroundColor: swatch }}
+      />
+      <div className="min-w-0 flex-1">
+        <div className="truncate text-[11px] font-medium text-neutral-100">{token}</div>
+        <div className="truncate text-[11px] uppercase tracking-[0.18em] text-neutral-500">
+          {sources.join(" · ")}
+        </div>
+      </div>
     </div>
   );
 }
 
 export const PropertyPanel = memo(function PropertyPanel({
+  mode = "design",
+  projectId,
+  assets,
   element,
-  isPickMode,
-  onEnablePick,
-  onDisablePick,
-  onClearPick,
+  motionMaxDuration,
+  copiedAgentPrompt,
+  copiedElementLocator = false,
+  onClearSelection,
   onSetStyle,
-  onSetDataAttr,
+  onSetMotion,
   onSetText,
+  onSetTextFieldStyle,
+  onAddTextField,
+  onRemoveTextField,
+  onDetachFromLayout,
+  onAskAgent,
+  onCopyElementLocator,
+  onCopyAgentInstruction,
+  onImportAssets,
+  fontAssets = [],
+  onImportFonts,
+  allowLayoutDetach = true,
 }: PropertyPanelProps) {
+  const styles = element?.computedStyles ?? EMPTY_STYLES;
+  const selectionColors = useMemo(() => collectSelectionColors(styles), [styles]);
+  const backgroundImage = styles["background-image"] ?? "none";
+  const fillMode =
+    backgroundImage && backgroundImage !== "none"
+      ? backgroundImage.includes("gradient")
+        ? "Gradient"
+        : "Image"
+      : "Solid";
+  const [preferredFillMode, setPreferredFillMode] = useState(fillMode);
+  const imageUrl = extractBackgroundImageUrl(backgroundImage);
+  const [activeTextFieldKey, setActiveTextFieldKey] = useState<string | null>(
+    element?.textFields[0]?.key ?? null,
+  );
+  const hasTextControls = element != null && isTextEditableSelection(element);
+  const motionAttribute = element?.dataAttributes["hf-motion"];
+  const activeMotionDraft = useMemo(() => {
+    const parsed = parseMotionDraft(motionAttribute);
+    return parsed ? clampMotionDraftToTimeline(parsed, motionMaxDuration) : null;
+  }, [motionAttribute, motionMaxDuration]);
+  const motionDraft = useMemo(
+    () =>
+      clampMotionDraftToTimeline(activeMotionDraft ?? buildDefaultMotionDraft(), motionMaxDuration),
+    [activeMotionDraft, motionMaxDuration],
+  );
+  const motionOwnership = useMemo(
+    () =>
+      detectMotionOwnership({
+        element: element?.element ?? null,
+        dataAttributes: element?.dataAttributes,
+        computedStyles: element?.computedStyles,
+      }),
+    [element],
+  );
+  const panelScrollRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    setPreferredFillMode(fillMode);
+  }, [fillMode, element?.id, element?.selector, backgroundImage]);
+
+  useEffect(() => {
+    const panel = panelScrollRef.current;
+    if (!panel) return;
+
+    const handleWheel = (event: WheelEvent) => {
+      if (!isPanelWheelLockedTarget(event.target)) return;
+      event.preventDefault();
+    };
+
+    panel.addEventListener("wheel", handleWheel, { passive: false, capture: true });
+    return () => panel.removeEventListener("wheel", handleWheel, { capture: true });
+  }, [element?.id, element?.selector]);
+
+  useEffect(() => {
+    const nextFields = element?.textFields ?? [];
+    setActiveTextFieldKey((current) => {
+      if (current && nextFields.some((field) => field.key === current)) return current;
+      return nextFields[0]?.key ?? null;
+    });
+  }, [element?.id, element?.selector, element?.textFields]);
+
   if (!element) {
     return (
-      <div className="flex flex-col items-center justify-center h-full px-4 text-center">
-        <MousePointer size={20} className="text-neutral-700 mb-2" />
-        <p className="text-xs text-neutral-500">Click an element in the preview to inspect it</p>
-        <Button
-          variant="secondary"
-          size="sm"
-          onClick={isPickMode ? onDisablePick : onEnablePick}
-          className={`mt-3 ${isPickMode ? "bg-studio-accent/20 text-studio-accent border-studio-accent/30" : ""}`}
-        >
-          {isPickMode ? "Pick mode active..." : "Enable Pick Mode"}
-        </Button>
+      <div className="flex h-full flex-col items-center justify-center bg-neutral-900 px-6 text-center">
+        <Eye size={18} className="mb-3 text-neutral-600" />
+        <p className="text-sm font-medium text-neutral-200">Select an element in the preview.</p>
+        <p className="mt-2 max-w-[260px] text-xs leading-5 text-neutral-500">
+          The inspector is tuned for direct DOM edits with safer geometry controls, color picking,
+          and cleaner grouped layer controls.
+        </p>
       </div>
     );
   }
 
-  const s = element.computedStyles;
+  const styleEditingDisabled = !element.capabilities.canEditStyles;
+  const moveEditingDisabled = !element.capabilities.canMove;
+  const resizeEditingDisabled = !element.capabilities.canResize;
+  const isFlex = styles.display === "flex" || styles.display === "inline-flex";
+  const radiusValue = parseNumericValue(styles["border-radius"]) ?? 0;
+  const opacityValue = Math.round((parseNumericValue(styles.opacity) ?? 1) * 100);
+  const clipContent = ["hidden", "clip"].includes((styles.overflow ?? "").trim());
+  const sourceLabel = element.id ? `#${element.id}` : element.selector;
+  const showEditableSections = element.capabilities.canEditStyles;
+  const isMotionMode = mode === "motion";
+  const disabledMoveReason =
+    allowLayoutDetach &&
+    element.capabilities.reasonIfDisabled &&
+    !element.capabilities.canDetachFromLayout
+      ? element.capabilities.reasonIfDisabled
+      : null;
 
-  return (
-    <div className="flex flex-col h-full min-h-0">
-      {/* Header */}
-      <div className="flex items-center justify-between px-3 py-2 border-b border-neutral-800 flex-shrink-0">
-        <div className="flex items-center gap-1.5 min-w-0">
-          <span className="text-2xs font-mono text-studio-accent truncate">{element.selector}</span>
+  const handleFillModeChange = (nextMode: string) => {
+    setPreferredFillMode(nextMode);
+    if (nextMode === "Solid") {
+      onSetStyle("background-image", "none");
+      return;
+    }
+    if (nextMode === "Gradient" && !backgroundImage.includes("gradient")) {
+      onSetStyle(
+        "background-image",
+        serializeGradient(buildDefaultGradientModel(styles["background-color"])),
+      );
+    }
+  };
+
+  const motionSection = showEditableSections ? (
+    <Section
+      title="Motion"
+      icon={<Zap size={15} />}
+      accessory={
+        <div className="rounded-full border border-neutral-700 bg-neutral-900 px-2.5 py-1 text-[10px] font-medium uppercase tracking-[0.16em] text-neutral-400">
+          {activeMotionDraft ? "Active" : "Off"}
         </div>
-        <div className="flex items-center gap-1">
-          <IconButton
-            icon={<MousePointer size={11} />}
-            aria-label={isPickMode ? "Disable pick mode" : "Enable pick mode"}
-            size="sm"
-            onClick={isPickMode ? onDisablePick : onEnablePick}
-            className={isPickMode ? "text-studio-accent bg-studio-accent/10" : ""}
-          />
-          <IconButton
-            icon={<X size={11} />}
+      }
+    >
+      <MotionControls
+        draft={motionDraft}
+        active={activeMotionDraft != null}
+        ownership={motionOwnership}
+        maxDuration={motionMaxDuration}
+        disabled={styleEditingDisabled}
+        onChange={onSetMotion}
+        onClear={() => onSetMotion(null)}
+      />
+    </Section>
+  ) : (
+    <div className="border-t border-neutral-800 px-4 py-5 text-[11px] leading-5 text-neutral-500">
+      Motion controls require a style-editable DOM layer.
+    </div>
+  );
+
+  return (
+    <div className="flex h-full min-h-0 flex-col overflow-hidden bg-neutral-900 text-neutral-100">
+      <div className="border-b border-neutral-800 px-4 py-5">
+        <div className="flex items-start justify-between gap-4">
+          <div className="min-w-0">
+            <div className={LABEL}>Document</div>
+            <div className="mt-3 truncate text-[12px] font-semibold text-neutral-100">
+              {element.label}
+            </div>
+            <div className="mt-1 truncate text-[11px] text-neutral-500">{sourceLabel}</div>
+          </div>
+          <button
+            type="button"
             aria-label="Clear selection"
-            size="sm"
-            onClick={onClearPick}
-          />
+            onClick={onClearSelection}
+            className="flex h-9 w-9 items-center justify-center rounded-full border border-neutral-700 bg-neutral-950 text-neutral-500 shadow-[0_1px_2px_rgba(0,0,0,0.2)] transition-colors hover:border-neutral-600 hover:text-neutral-200"
+          >
+            <X size={13} />
+          </button>
+        </div>
+        <div className="mt-4 flex flex-wrap gap-2">
+          <button
+            type="button"
+            onClick={onAskAgent}
+            className="inline-flex h-8 items-center justify-center gap-2 rounded-xl border border-neutral-700 bg-neutral-950 px-3.5 text-[11px] font-medium text-neutral-100 transition-colors hover:border-studio-accent/40 hover:text-studio-accent"
+          >
+            <MessageSquare size={15} />
+            <span>{copiedAgentPrompt ? "Prompt copied" : "Ask agent"}</span>
+          </button>
+          <button
+            type="button"
+            onClick={() => {
+              void Promise.resolve(onCopyElementLocator());
+            }}
+            className="inline-flex h-8 items-center justify-center gap-2 rounded-xl border border-neutral-700 bg-neutral-950 px-3.5 text-[11px] font-medium text-neutral-100 transition-colors hover:border-neutral-500 hover:text-white"
+          >
+            <ClipboardList size={15} />
+            <span>{copiedElementLocator ? "LOC copied" : "Copy LOC"}</span>
+          </button>
         </div>
       </div>
 
-      {/* Properties */}
-      <div className="flex-1 overflow-y-auto px-3 py-2 space-y-1">
-        {/* Element info */}
-        <div className="flex items-center gap-2 mb-2">
-          <span className="text-2xs text-neutral-300 font-medium">{element.label}</span>
-          <span className="text-2xs text-neutral-600 font-mono">&lt;{element.tagName}&gt;</span>
-        </div>
+      <div
+        ref={panelScrollRef}
+        className="flex-1 overflow-y-auto"
+        onWheel={preventPanelScrollFromControlWheel}
+      >
+        {isMotionMode ? (
+          motionSection
+        ) : (
+          <>
+            <Section title="Layout" icon={<Move size={15} />}>
+              <div className={RESPONSIVE_GRID}>
+                <MetricField
+                  label="X"
+                  value={styles.left ?? "auto"}
+                  disabled={moveEditingDisabled}
+                  onCommit={(next) => onSetStyle("left", next)}
+                />
+                <MetricField
+                  label="Y"
+                  value={styles.top ?? "auto"}
+                  disabled={moveEditingDisabled}
+                  onCommit={(next) => onSetStyle("top", next)}
+                />
+                <MetricField
+                  label="W"
+                  value={styles.width ?? "auto"}
+                  disabled={resizeEditingDisabled}
+                  onCommit={(next) => onSetStyle("width", next)}
+                />
+                <MetricField
+                  label="H"
+                  value={styles.height ?? "auto"}
+                  disabled={resizeEditingDisabled}
+                  onCommit={(next) => onSetStyle("height", next)}
+                />
+              </div>
+              {disabledMoveReason && (
+                <div className="mt-4 flex min-w-0 flex-wrap items-center justify-between gap-3 border-l border-amber-500/40 pl-3">
+                  <div className="min-w-0 text-[11px] leading-5 text-neutral-400">
+                    <div className="font-medium text-amber-100">{disabledMoveReason}</div>
+                    <div>Copy a targeted prompt so an agent can refactor this layer safely.</div>
+                  </div>
+                  <button
+                    type="button"
+                    onClick={() => {
+                      void Promise.resolve(
+                        onCopyAgentInstruction(
+                          buildMakeMovableAgentInstruction(disabledMoveReason),
+                        ),
+                      );
+                    }}
+                    className="inline-flex h-8 flex-shrink-0 items-center rounded-lg border border-neutral-700 bg-neutral-950 px-3 text-[11px] font-medium text-neutral-100 transition-colors hover:border-amber-400/70 hover:text-amber-100"
+                  >
+                    {copiedAgentPrompt ? "Prompt copied" : "Ask agent to make movable"}
+                  </button>
+                </div>
+              )}
+              {allowLayoutDetach && element.capabilities.canDetachFromLayout && (
+                <div className="mt-4 flex min-w-0 flex-wrap items-center justify-between gap-3 border-l border-amber-500/40 pl-3">
+                  <div className="min-w-0 text-[11px] leading-5 text-neutral-400">
+                    <div className="font-medium text-neutral-200">
+                      This layer is controlled by layout.
+                    </div>
+                    <div>Detaches from flex/grid flow and preserves current visual position.</div>
+                  </div>
+                  <button
+                    type="button"
+                    onClick={onDetachFromLayout}
+                    className="inline-flex h-8 flex-shrink-0 items-center rounded-lg border border-neutral-700 bg-neutral-950 px-3 text-[11px] font-medium text-neutral-100 transition-colors hover:border-amber-400/70 hover:text-amber-100"
+                  >
+                    Make movable
+                  </button>
+                </div>
+              )}
+            </Section>
 
-        {/* Position & Size */}
-        <SectionHeader icon={Move} label="Position & Size" />
-        <div className="grid grid-cols-2 gap-1">
-          <PropertyRow
-            label="X"
-            value={s["left"] ?? "auto"}
-            onChange={(v) => onSetStyle("left", v)}
-          />
-          <PropertyRow
-            label="Y"
-            value={s["top"] ?? "auto"}
-            onChange={(v) => onSetStyle("top", v)}
-          />
-          <PropertyRow
-            label="W"
-            value={s["width"] ?? "auto"}
-            onChange={(v) => onSetStyle("width", v)}
-          />
-          <PropertyRow
-            label="H"
-            value={s["height"] ?? "auto"}
-            onChange={(v) => onSetStyle("height", v)}
-          />
-        </div>
+            {showEditableSections && isFlex && (
+              <Section title="Flex" icon={<Layers size={15} />}>
+                <div className="space-y-4">
+                  <SegmentedControl
+                    disabled={styleEditingDisabled}
+                    value={styles["flex-direction"] || "row"}
+                    onChange={(next) => onSetStyle("flex-direction", next)}
+                    options={[
+                      { label: "→ Row", value: "row" },
+                      { label: "↓ Column", value: "column" },
+                    ]}
+                  />
+                  <div className={RESPONSIVE_GRID}>
+                    <SelectField
+                      label="Justify"
+                      value={styles["justify-content"] || "flex-start"}
+                      disabled={styleEditingDisabled}
+                      onChange={(next) => onSetStyle("justify-content", next)}
+                      options={[
+                        "flex-start",
+                        "center",
+                        "space-between",
+                        "space-around",
+                        "space-evenly",
+                        "flex-end",
+                      ]}
+                    />
+                    <SelectField
+                      label="Align"
+                      value={styles["align-items"] || "stretch"}
+                      disabled={styleEditingDisabled}
+                      onChange={(next) => onSetStyle("align-items", next)}
+                      options={["stretch", "flex-start", "center", "flex-end", "baseline"]}
+                    />
+                  </div>
+                  <DetailField
+                    label="Gap"
+                    value={styles.gap ?? "0px"}
+                    disabled={styleEditingDisabled}
+                    onCommit={(next) => onSetStyle("gap", next.endsWith("px") ? next : `${next}px`)}
+                  />
+                  <label className="flex items-center gap-3 rounded-2xl border border-neutral-800 bg-neutral-900 px-3 py-3 text-[12px] text-neutral-300 shadow-[inset_0_1px_0_rgba(255,255,255,0.03)]">
+                    <input
+                      type="checkbox"
+                      checked={clipContent}
+                      disabled={styleEditingDisabled}
+                      onChange={(e) =>
+                        onSetStyle("overflow", e.target.checked ? "hidden" : "visible")
+                      }
+                      className="h-4 w-4 rounded border-neutral-700 bg-neutral-950 text-[#3ce6ac] focus:ring-[#3ce6ac]"
+                    />
+                    <span>Clip content</span>
+                  </label>
+                </div>
+              </Section>
+            )}
 
-        {/* Typography */}
-        {(element.tagName === "div" ||
-          element.tagName === "span" ||
-          element.tagName === "p" ||
-          element.tagName === "h1" ||
-          element.tagName === "h2") && (
-          <>
-            <SectionHeader icon={Type} label="Typography" />
-            <PropertyRow
-              label="Size"
-              value={s["font-size"] ?? ""}
-              onChange={(v) => onSetStyle("font-size", v)}
-            />
-            <PropertyRow
-              label="Weight"
-              value={s["font-weight"] ?? ""}
-              onChange={(v) => onSetStyle("font-weight", v)}
-            />
-            <PropertyRow
-              label="Family"
-              value={s["font-family"]?.split(",")[0] ?? ""}
-              onChange={(v) => onSetStyle("font-family", v)}
-            />
-          </>
-        )}
+            {showEditableSections && (
+              <>
+                <Section title="Radius" icon={<Settings size={15} />}>
+                  <SliderControl
+                    value={radiusValue}
+                    min={0}
+                    max={Math.max(240, Math.ceil(radiusValue))}
+                    step={1}
+                    disabled={styleEditingDisabled}
+                    displayValue={`${formatNumericValue(radiusValue)}px`}
+                    formatDisplayValue={(next) => `${formatNumericValue(next)}px`}
+                    onCommit={(next) =>
+                      onSetStyle("border-radius", `${formatNumericValue(next)}px`)
+                    }
+                  />
+                </Section>
 
-        {/* Colors */}
-        <SectionHeader icon={Palette} label="Colors" />
-        <ColorRow
-          label="Color"
-          value={s["color"] ?? "#fff"}
-          onChange={(v) => onSetStyle("color", v)}
-        />
-        <ColorRow
-          label="Background"
-          value={s["background-color"] ?? "transparent"}
-          onChange={(v) => onSetStyle("background-color", v)}
-        />
+                <Section title="Blending" icon={<Eye size={15} />}>
+                  <div className="space-y-4">
+                    <SliderControl
+                      value={opacityValue}
+                      min={0}
+                      max={100}
+                      step={1}
+                      disabled={styleEditingDisabled}
+                      displayValue={`${opacityValue}%`}
+                      formatDisplayValue={(next) => `${Math.round(next)}%`}
+                      onCommit={(next) => onSetStyle("opacity", formatNumericValue(next / 100))}
+                    />
+                    <SelectField
+                      label="Mode"
+                      value={styles["mix-blend-mode"] || "normal"}
+                      disabled={styleEditingDisabled}
+                      onChange={(next) => onSetStyle("mix-blend-mode", next)}
+                      options={["normal", "multiply", "screen", "overlay", "darken", "lighten"]}
+                    />
+                  </div>
+                </Section>
 
-        {/* Appearance */}
-        <SectionHeader icon={Eye} label="Appearance" />
-        <PropertyRow
-          label="Opacity"
-          value={s["opacity"] ?? "1"}
-          onChange={(v) => onSetStyle("opacity", v)}
-        />
-        <PropertyRow
-          label="Radius"
-          value={s["border-radius"] ?? "0"}
-          onChange={(v) => onSetStyle("border-radius", v)}
-        />
-        <PropertyRow
-          label="Z-index"
-          value={s["z-index"] ?? "auto"}
-          onChange={(v) => onSetStyle("z-index", v)}
-        />
-        <PropertyRow
-          label="Transform"
-          value={s["transform"] ?? "none"}
-          onChange={(v) => onSetStyle("transform", v)}
-        />
+                <Section
+                  title="Fill"
+                  icon={<Palette size={15} />}
+                  accessory={
+                    <div className="rounded-full border border-neutral-700 bg-neutral-900 px-2.5 py-1 text-[10px] font-medium uppercase tracking-[0.16em] text-neutral-400">
+                      {preferredFillMode}
+                    </div>
+                  }
+                >
+                  <div className="space-y-4">
+                    <SegmentedControl
+                      disabled={styleEditingDisabled}
+                      value={preferredFillMode}
+                      onChange={handleFillModeChange}
+                      options={[
+                        { label: "Solid", value: "Solid" },
+                        { label: "Gradient", value: "Gradient" },
+                        { label: "Image", value: "Image" },
+                      ]}
+                    />
+                    {preferredFillMode === "Solid" ? (
+                      <ColorField
+                        label="Fill color"
+                        value={styles["background-color"] ?? "transparent"}
+                        disabled={styleEditingDisabled}
+                        onCommit={(next) => onSetStyle("background-color", next)}
+                      />
+                    ) : preferredFillMode === "Gradient" ? (
+                      <GradientField
+                        value={
+                          backgroundImage !== "none"
+                            ? backgroundImage
+                            : serializeGradient(
+                                buildDefaultGradientModel(styles["background-color"]),
+                              )
+                        }
+                        fallbackColor={styles["background-color"]}
+                        disabled={styleEditingDisabled}
+                        onCommit={(next) => onSetStyle("background-image", next)}
+                      />
+                    ) : (
+                      <ImageFillField
+                        projectId={projectId}
+                        sourceFile={element.sourceFile}
+                        value={imageUrl}
+                        assets={assets}
+                        disabled={styleEditingDisabled}
+                        onCommit={(next) => onSetStyle("background-image", next)}
+                        onImportAssets={onImportAssets}
+                      />
+                    )}
+                    {!hasTextControls && (
+                      <ColorField
+                        label="Text color"
+                        value={styles.color ?? "rgb(0, 0, 0)"}
+                        disabled={styleEditingDisabled}
+                        onCommit={(next) => onSetStyle("color", next)}
+                      />
+                    )}
+                  </div>
+                </Section>
 
-        {/* Timing */}
-        {(element.dataAttributes["start"] || element.dataAttributes["duration"]) && (
-          <>
-            <SectionHeader icon={Clock} label="Timing" />
-            {element.dataAttributes["start"] != null && (
-              <PropertyRow
-                label="Start"
-                value={element.dataAttributes["start"]}
-                onChange={(v) => onSetDataAttr("start", v)}
-              />
-            )}
-            {element.dataAttributes["duration"] != null && (
-              <PropertyRow
-                label="Duration"
-                value={element.dataAttributes["duration"]}
-                onChange={(v) => onSetDataAttr("duration", v)}
-              />
-            )}
-            {element.dataAttributes["track-index"] != null && (
-              <PropertyRow
-                label="Track"
-                value={element.dataAttributes["track-index"]}
-                onChange={(v) => onSetDataAttr("track-index", v)}
-              />
-            )}
-          </>
-        )}
+                {hasTextControls && (
+                  <Section title="Text" icon={<Type size={15} />}>
+                    {(() => {
+                      const textFields = element.textFields;
+                      const activeField =
+                        textFields.find((field) => field.key === activeTextFieldKey) ??
+                        textFields[0];
+                      if (!activeField) return null;
 
-        {/* Editable text content */}
-        {element.textContent && (
-          <>
-            <SectionHeader icon={Type} label="Text Content" />
-            <textarea
-              defaultValue={element.textContent}
-              onBlur={(e) => onSetText?.(e.target.value)}
-              onKeyDown={(e) => {
-                if (e.key === "Enter" && e.metaKey) {
-                  (e.target as HTMLTextAreaElement).blur();
-                }
-              }}
-              rows={3}
-              className="w-full bg-neutral-900 border border-neutral-800 rounded px-2 py-1.5 text-xs text-neutral-200 outline-none focus:border-neutral-600 resize-y leading-relaxed"
-              placeholder="Edit text..."
-            />
+                      if (textFields.length === 1) {
+                        return (
+                          <div className="space-y-4 rounded-xl border border-neutral-800 bg-neutral-900/60 p-3">
+                            <div className="min-w-0">
+                              <div className="truncate text-[11px] font-medium text-neutral-100">
+                                {formatTextFieldPreview(activeField.value) || "Text"}
+                              </div>
+                              <div className="text-[10px] uppercase tracking-[0.12em] text-neutral-500">
+                                {activeField.tagName}
+                              </div>
+                            </div>
+
+                            <TextAreaField
+                              key={activeField.key}
+                              label="Content"
+                              value={activeField.value}
+                              disabled={false}
+                              onCommit={(next) => onSetText(next, activeField.key)}
+                            />
+
+                            <ColorField
+                              label="Text color"
+                              value={getTextFieldColor(activeField, styles)}
+                              disabled={false}
+                              onCommit={(next) =>
+                                onSetTextFieldStyle(activeField.key, "color", next)
+                              }
+                            />
+
+                            <div className={RESPONSIVE_GRID}>
+                              <MetricField
+                                label="Size"
+                                value={
+                                  activeField.computedStyles["font-size"] ||
+                                  styles["font-size"] ||
+                                  "16px"
+                                }
+                                disabled={false}
+                                liveCommit
+                                onCommit={(next) =>
+                                  onSetTextFieldStyle(activeField.key, "font-size", next)
+                                }
+                              />
+                              <FontWeightField
+                                value={
+                                  activeField.computedStyles["font-weight"] ||
+                                  styles["font-weight"] ||
+                                  "400"
+                                }
+                                disabled={false}
+                                onCommit={(next) =>
+                                  onSetTextFieldStyle(activeField.key, "font-weight", next)
+                                }
+                              />
+                            </div>
+
+                            <FontFamilyField
+                              value={
+                                activeField.computedStyles["font-family"] ||
+                                styles["font-family"] ||
+                                "inherit"
+                              }
+                              disabled={false}
+                              importedFonts={fontAssets}
+                              onImportFonts={onImportFonts}
+                              onCommit={(next) =>
+                                onSetTextFieldStyle(activeField.key, "font-family", next)
+                              }
+                            />
+                          </div>
+                        );
+                      }
+
+                      return (
+                        <div className="space-y-4">
+                          <div className="grid gap-1.5">
+                            <div className="flex min-w-0 flex-wrap items-center justify-between gap-2">
+                              <span className={LABEL}>Text layers</span>
+                              <button
+                                type="button"
+                                onClick={() => {
+                                  void Promise.resolve(onAddTextField(activeField.key)).then(
+                                    (nextKey) => {
+                                      if (nextKey) setActiveTextFieldKey(nextKey);
+                                    },
+                                  );
+                                }}
+                                className="inline-flex h-7 max-w-full items-center gap-1.5 rounded-lg border border-neutral-700 bg-neutral-950 px-2.5 text-[11px] font-medium text-neutral-300 transition-colors hover:border-neutral-600 hover:text-white"
+                              >
+                                <Plus size={12} className="flex-shrink-0" />
+                                <span className="truncate">Add text</span>
+                              </button>
+                            </div>
+                            <div className="grid gap-2">
+                              {textFields.map((field, index) => {
+                                const active = field.key === activeField.key;
+                                return (
+                                  <button
+                                    key={field.key}
+                                    type="button"
+                                    onClick={() => setActiveTextFieldKey(field.key)}
+                                    className={`min-w-0 w-full rounded-xl border px-3 py-2 text-left transition-colors ${
+                                      active
+                                        ? "border-studio-accent/50 bg-studio-accent/10"
+                                        : "border-neutral-800 bg-neutral-900/80 hover:border-neutral-700 hover:bg-neutral-900"
+                                    }`}
+                                  >
+                                    <div className="flex min-w-0 items-center justify-between gap-2">
+                                      <div className="flex min-w-0 items-center gap-2">
+                                        <span
+                                          className="h-4 w-4 flex-shrink-0 rounded border border-neutral-700 bg-neutral-950"
+                                          style={{
+                                            backgroundColor: getTextFieldColor(field, styles),
+                                          }}
+                                        />
+                                        <span className="min-w-0 truncate text-[11px] font-medium text-neutral-100">
+                                          {formatTextFieldPreview(field.value) ||
+                                            `Text ${index + 1}`}
+                                        </span>
+                                      </div>
+                                      <span className="flex-shrink-0 rounded-md border border-neutral-700 bg-neutral-950 px-1.5 py-0.5 text-[10px] uppercase tracking-[0.12em] text-neutral-500">
+                                        {field.tagName}
+                                      </span>
+                                    </div>
+                                  </button>
+                                );
+                              })}
+                            </div>
+                          </div>
+
+                          <div className="space-y-4 rounded-xl border border-neutral-800 bg-neutral-900/60 p-3">
+                            <div className="flex min-w-0 items-center justify-between gap-2">
+                              <div className="min-w-0">
+                                <div className="truncate text-[11px] font-medium text-neutral-100">
+                                  {formatTextFieldPreview(activeField.value) || "Text"}
+                                </div>
+                                <div className="text-[10px] uppercase tracking-[0.12em] text-neutral-500">
+                                  {activeField.tagName}
+                                </div>
+                              </div>
+                              <button
+                                type="button"
+                                onClick={() => onRemoveTextField(activeField.key)}
+                                className="inline-flex h-7 flex-shrink-0 items-center rounded-lg border border-neutral-700 bg-neutral-950 px-2.5 text-[11px] font-medium text-neutral-300 transition-colors hover:border-neutral-600 hover:text-white"
+                              >
+                                Remove
+                              </button>
+                            </div>
+
+                            <TextAreaField
+                              key={activeField.key}
+                              label="Content"
+                              value={activeField.value}
+                              disabled={false}
+                              autoFocus
+                              onCommit={(next) => onSetText(next, activeField.key)}
+                            />
+
+                            <ColorField
+                              label="Text color"
+                              value={getTextFieldColor(activeField, styles)}
+                              disabled={false}
+                              onCommit={(next) =>
+                                onSetTextFieldStyle(activeField.key, "color", next)
+                              }
+                            />
+
+                            <div className={RESPONSIVE_GRID}>
+                              <MetricField
+                                label="Size"
+                                value={activeField.computedStyles["font-size"] || "16px"}
+                                disabled={false}
+                                liveCommit
+                                onCommit={(next) =>
+                                  onSetTextFieldStyle(activeField.key, "font-size", next)
+                                }
+                              />
+                              <FontWeightField
+                                value={activeField.computedStyles["font-weight"] || "400"}
+                                disabled={false}
+                                onCommit={(next) =>
+                                  onSetTextFieldStyle(activeField.key, "font-weight", next)
+                                }
+                              />
+                            </div>
+
+                            <FontFamilyField
+                              value={
+                                activeField.computedStyles["font-family"] ||
+                                styles["font-family"] ||
+                                "inherit"
+                              }
+                              disabled={false}
+                              importedFonts={fontAssets}
+                              onImportFonts={onImportFonts}
+                              onCommit={(next) =>
+                                onSetTextFieldStyle(activeField.key, "font-family", next)
+                              }
+                            />
+                          </div>
+                        </div>
+                      );
+                    })()}
+                  </Section>
+                )}
+
+                {selectionColors.length > 0 && (
+                  <Section title="Selection colors" icon={<Palette size={15} />}>
+                    <div className="space-y-3">
+                      {selectionColors.map((entry) => (
+                        <SelectionColorRow
+                          key={`${entry.swatch}-${entry.token}`}
+                          swatch={entry.swatch}
+                          token={entry.token}
+                          sources={entry.sources}
+                        />
+                      ))}
+                    </div>
+                  </Section>
+                )}
+              </>
+            )}
           </>
         )}
       </div>
diff --git a/packages/studio/src/components/editor/TimelineLayerPanel.tsx b/packages/studio/src/components/editor/TimelineLayerPanel.tsx
new file mode 100644
index 000000000..323d30b54
--- /dev/null
+++ b/packages/studio/src/components/editor/TimelineLayerPanel.tsx
@@ -0,0 +1,192 @@
+import { memo, useCallback, useRef, useState, type PointerEvent as ReactPointerEvent } from "react";
+import type { DomEditLayerItem } from "./domEditing";
+
+interface TimelineLayerPanelProps {
+  clipLabel: string;
+  layers: DomEditLayerItem[];
+  selectedLayerKey: string | null;
+  onSelectLayer: (layer: DomEditLayerItem) => void;
+  onClose: () => void;
+}
+
+export const TimelineLayerPanel = memo(function TimelineLayerPanel({
+  clipLabel,
+  layers,
+  selectedLayerKey,
+  onSelectLayer,
+  onClose,
+}: TimelineLayerPanelProps) {
+  const childCount = Math.max(0, layers.length - 1);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const dragRef = useRef<{
+    pointerId: number;
+    startClientX: number;
+    startClientY: number;
+    startX: number;
+    startY: number;
+  } | null>(null);
+  const [position, setPosition] = useState({ x: 0, y: 0 });
+
+  const clampPosition = useCallback(
+    (nextX: number, nextY: number) => {
+      const panel = panelRef.current;
+      if (!panel) return { x: nextX, y: nextY };
+
+      const rect = panel.getBoundingClientRect();
+      const margin = 12;
+      const minX = margin - rect.left + position.x;
+      const minY = margin - rect.top + position.y;
+      const maxX = window.innerWidth - margin - rect.right + position.x;
+      const maxY = window.innerHeight - margin - rect.bottom + position.y;
+
+      return {
+        x: Math.min(maxX, Math.max(minX, nextX)),
+        y: Math.min(maxY, Math.max(minY, nextY)),
+      };
+    },
+    [position.x, position.y],
+  );
+
+  const handleDragStart = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      if (event.button !== 0) return;
+      event.preventDefault();
+      event.stopPropagation();
+      dragRef.current = {
+        pointerId: event.pointerId,
+        startClientX: event.clientX,
+        startClientY: event.clientY,
+        startX: position.x,
+        startY: position.y,
+      };
+      event.currentTarget.setPointerCapture(event.pointerId);
+    },
+    [position.x, position.y],
+  );
+
+  const handleDragMove = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      const drag = dragRef.current;
+      if (!drag || drag.pointerId !== event.pointerId) return;
+      event.preventDefault();
+      event.stopPropagation();
+      setPosition(
+        clampPosition(
+          drag.startX + event.clientX - drag.startClientX,
+          drag.startY + event.clientY - drag.startClientY,
+        ),
+      );
+    },
+    [clampPosition],
+  );
+
+  const handleDragEnd = useCallback((event: ReactPointerEvent<HTMLDivElement>) => {
+    const drag = dragRef.current;
+    if (!drag || drag.pointerId !== event.pointerId) return;
+    event.preventDefault();
+    event.stopPropagation();
+    dragRef.current = null;
+    if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+      event.currentTarget.releasePointerCapture(event.pointerId);
+    }
+  }, []);
+
+  return (
+    <div
+      ref={panelRef}
+      className="pointer-events-auto absolute left-3 top-3 z-[100] w-[280px] max-w-[calc(100%-24px)] overflow-hidden rounded-xl border border-white/10 bg-neutral-950/92 shadow-2xl shadow-black/40 backdrop-blur-md"
+      style={{ transform: `translate3d(${position.x}px, ${position.y}px, 0)` }}
+      onPointerDown={(event) => {
+        event.stopPropagation();
+      }}
+      onClick={(event) => {
+        event.stopPropagation();
+      }}
+    >
+      <div
+        className="flex cursor-grab touch-none select-none items-start justify-between gap-3 border-b border-white/10 px-3 py-3 active:cursor-grabbing"
+        onPointerDown={handleDragStart}
+        onPointerMove={handleDragMove}
+        onPointerUp={handleDragEnd}
+        onPointerCancel={handleDragEnd}
+      >
+        <div className="min-w-0">
+          <div className="text-[9px] font-semibold uppercase tracking-[0.18em] text-neutral-500">
+            Clip layers
+          </div>
+          <div className="mt-1 truncate text-sm font-semibold text-neutral-100">{clipLabel}</div>
+        </div>
+        <button
+          type="button"
+          onPointerDown={(event) => {
+            event.stopPropagation();
+          }}
+          onClick={onClose}
+          className="flex h-7 w-7 flex-shrink-0 items-center justify-center rounded-md border border-white/10 bg-black/20 text-neutral-500 transition-colors hover:border-white/20 hover:text-neutral-200"
+          aria-label="Close clip layers"
+        >
+          <svg
+            width="14"
+            height="14"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.8"
+            strokeLinecap="round"
+            aria-hidden="true"
+          >
+            <path d="M18 6 6 18" />
+            <path d="m6 6 12 12" />
+          </svg>
+        </button>
+      </div>
+      <div className="border-b border-white/10 px-3 py-2 text-[11px] text-neutral-500">
+        {childCount > 0
+          ? `${childCount} nested selectable layer${childCount === 1 ? "" : "s"}`
+          : "No nested layers"}
+      </div>
+      <div className="max-h-[320px] overflow-y-auto py-1">
+        {layers.map((layer) => {
+          const selected = layer.key === selectedLayerKey;
+          return (
+            <button
+              key={layer.key}
+              type="button"
+              data-timeline-layer-row={layer.key}
+              onPointerDown={(event) => {
+                event.stopPropagation();
+                onSelectLayer(layer);
+              }}
+              onClick={(event) => {
+                event.stopPropagation();
+                onSelectLayer(layer);
+              }}
+              className={`group flex w-full items-center gap-2 px-2.5 py-1.5 text-left transition-colors ${
+                selected
+                  ? "bg-studio-accent/14 text-studio-accent"
+                  : "text-neutral-300 hover:bg-white/[0.04] hover:text-neutral-100"
+              }`}
+              style={{ paddingLeft: 10 + layer.depth * 14 }}
+            >
+              <span
+                className={`flex h-5 w-5 flex-shrink-0 items-center justify-center rounded-md border text-[9px] font-bold uppercase ${
+                  selected
+                    ? "border-studio-accent/50 bg-studio-accent/18"
+                    : "border-white/10 bg-black/20 text-neutral-500 group-hover:text-neutral-300"
+                }`}
+              >
+                {layer.tagName.slice(0, 2)}
+              </span>
+              <span className="min-w-0 flex-1 truncate text-xs font-medium">{layer.label}</span>
+              {layer.childCount > 0 && (
+                <span className="rounded-full border border-white/10 bg-black/25 px-1.5 py-0.5 text-[9px] font-semibold tabular-nums text-neutral-500">
+                  {layer.childCount}
+                </span>
+              )}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+});
diff --git a/packages/studio/src/components/editor/colorValue.test.ts b/packages/studio/src/components/editor/colorValue.test.ts
new file mode 100644
index 000000000..fe0cb0b97
--- /dev/null
+++ b/packages/studio/src/components/editor/colorValue.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatCssColor,
+  hsvToRgb,
+  mergeColorWithExistingAlpha,
+  parseCssColor,
+  rgbToHsv,
+  toColorPickerValue,
+  toHexColor,
+} from "./colorValue";
+
+describe("parseCssColor", () => {
+  it("parses rgb values", () => {
+    expect(parseCssColor("rgb(12, 34, 56)")).toEqual({
+      red: 12,
+      green: 34,
+      blue: 56,
+      alpha: 1,
+    });
+  });
+
+  it("parses rgba values", () => {
+    expect(parseCssColor("rgba(15, 23, 42, 0.64)")).toEqual({
+      red: 15,
+      green: 23,
+      blue: 42,
+      alpha: 0.64,
+    });
+  });
+
+  it("parses transparent", () => {
+    expect(parseCssColor("transparent")).toEqual({
+      red: 0,
+      green: 0,
+      blue: 0,
+      alpha: 0,
+    });
+  });
+});
+
+describe("toColorPickerValue", () => {
+  it("converts css color to hex", () => {
+    expect(toColorPickerValue("rgba(15, 23, 42, 0.64)")).toBe("#0f172a");
+  });
+});
+
+describe("toHexColor", () => {
+  it("formats rgb channels as hex", () => {
+    expect(toHexColor({ red: 15, green: 23, blue: 42 })).toBe("#0f172a");
+  });
+});
+
+describe("formatCssColor", () => {
+  it("formats opaque colors as rgb", () => {
+    expect(formatCssColor({ red: 18, green: 52, blue: 86, alpha: 1 })).toBe("rgb(18, 52, 86)");
+  });
+
+  it("formats translucent colors as rgba", () => {
+    expect(formatCssColor({ red: 18, green: 52, blue: 86, alpha: 0.64 })).toBe(
+      "rgba(18, 52, 86, 0.64)",
+    );
+  });
+});
+
+describe("rgb hsv conversion", () => {
+  it("round-trips primary color values", () => {
+    const hsv = rgbToHsv({ red: 47, green: 198, blue: 127 });
+    expect(hsvToRgb(hsv)).toEqual({ red: 47, green: 198, blue: 127 });
+  });
+});
+
+describe("mergeColorWithExistingAlpha", () => {
+  it("preserves alpha when the previous color was translucent", () => {
+    expect(mergeColorWithExistingAlpha("#123456", "rgba(15, 23, 42, 0.64)")).toBe(
+      "rgba(18, 52, 86, 0.64)",
+    );
+  });
+
+  it("returns rgb when the previous color was opaque", () => {
+    expect(mergeColorWithExistingAlpha("#123456", "rgb(15, 23, 42)")).toBe("rgb(18, 52, 86)");
+  });
+});
diff --git a/packages/studio/src/components/editor/colorValue.ts b/packages/studio/src/components/editor/colorValue.ts
new file mode 100644
index 000000000..d1d04fb5a
--- /dev/null
+++ b/packages/studio/src/components/editor/colorValue.ts
@@ -0,0 +1,175 @@
+export interface ParsedColor {
+  red: number;
+  green: number;
+  blue: number;
+  alpha: number;
+}
+
+export interface HsvColor {
+  hue: number;
+  saturation: number;
+  value: number;
+}
+
+function clampChannel(value: number): number {
+  return Math.max(0, Math.min(255, Math.round(value)));
+}
+
+function clampAlpha(value: number): number {
+  return Math.max(0, Math.min(1, value));
+}
+
+function toHex(value: number): string {
+  return clampChannel(value).toString(16).padStart(2, "0");
+}
+
+function formatAlpha(value: number): string {
+  return `${Math.round(clampAlpha(value) * 100) / 100}`;
+}
+
+export function parseCssColor(value: string): ParsedColor | null {
+  const trimmed = value.trim().toLowerCase();
+  if (!trimmed) return null;
+  if (trimmed === "transparent") {
+    return { red: 0, green: 0, blue: 0, alpha: 0 };
+  }
+
+  const shortHex = trimmed.match(/^#([0-9a-f]{3})$/i);
+  if (shortHex) {
+    const [r, g, b] = shortHex[1].split("");
+    return {
+      red: Number.parseInt(r + r, 16),
+      green: Number.parseInt(g + g, 16),
+      blue: Number.parseInt(b + b, 16),
+      alpha: 1,
+    };
+  }
+
+  const hex = trimmed.match(/^#([0-9a-f]{6})$/i);
+  if (hex) {
+    return {
+      red: Number.parseInt(hex[1].slice(0, 2), 16),
+      green: Number.parseInt(hex[1].slice(2, 4), 16),
+      blue: Number.parseInt(hex[1].slice(4, 6), 16),
+      alpha: 1,
+    };
+  }
+
+  const rgba = trimmed.match(
+    /^rgba?\(\s*([0-9.]+)\s*,\s*([0-9.]+)\s*,\s*([0-9.]+)(?:\s*,\s*([0-9.]+))?\s*\)$/i,
+  );
+  if (rgba) {
+    return {
+      red: clampChannel(Number.parseFloat(rgba[1])),
+      green: clampChannel(Number.parseFloat(rgba[2])),
+      blue: clampChannel(Number.parseFloat(rgba[3])),
+      alpha: clampAlpha(rgba[4] != null ? Number.parseFloat(rgba[4]) : 1),
+    };
+  }
+
+  return null;
+}
+
+export function toColorPickerValue(value: string): string {
+  const parsed = parseCssColor(value);
+  if (!parsed) return "#000000";
+  return toHexColor(parsed);
+}
+
+export function toHexColor(color: Pick<ParsedColor, "red" | "green" | "blue">): string {
+  return `#${toHex(color.red)}${toHex(color.green)}${toHex(color.blue)}`;
+}
+
+export function formatCssColor(color: ParsedColor): string {
+  const red = clampChannel(color.red);
+  const green = clampChannel(color.green);
+  const blue = clampChannel(color.blue);
+  const alpha = clampAlpha(color.alpha);
+
+  if (alpha >= 1) {
+    return `rgb(${red}, ${green}, ${blue})`;
+  }
+
+  return `rgba(${red}, ${green}, ${blue}, ${formatAlpha(alpha)})`;
+}
+
+export function rgbToHsv(color: Pick<ParsedColor, "red" | "green" | "blue">): HsvColor {
+  const red = clampChannel(color.red) / 255;
+  const green = clampChannel(color.green) / 255;
+  const blue = clampChannel(color.blue) / 255;
+  const max = Math.max(red, green, blue);
+  const min = Math.min(red, green, blue);
+  const delta = max - min;
+
+  let hue = 0;
+  if (delta !== 0) {
+    if (max === red) {
+      hue = 60 * (((green - blue) / delta) % 6);
+    } else if (max === green) {
+      hue = 60 * ((blue - red) / delta + 2);
+    } else {
+      hue = 60 * ((red - green) / delta + 4);
+    }
+  }
+
+  if (hue < 0) hue += 360;
+
+  return {
+    hue,
+    saturation: max === 0 ? 0 : delta / max,
+    value: max,
+  };
+}
+
+export function hsvToRgb(color: HsvColor): Pick<ParsedColor, "red" | "green" | "blue"> {
+  const hue = (((color.hue % 360) + 360) % 360) / 60;
+  const saturation = Math.max(0, Math.min(1, color.saturation));
+  const value = Math.max(0, Math.min(1, color.value));
+  const chroma = value * saturation;
+  const x = chroma * (1 - Math.abs((hue % 2) - 1));
+  const m = value - chroma;
+
+  let red = 0;
+  let green = 0;
+  let blue = 0;
+
+  if (hue >= 0 && hue < 1) {
+    red = chroma;
+    green = x;
+  } else if (hue >= 1 && hue < 2) {
+    red = x;
+    green = chroma;
+  } else if (hue >= 2 && hue < 3) {
+    green = chroma;
+    blue = x;
+  } else if (hue >= 3 && hue < 4) {
+    green = x;
+    blue = chroma;
+  } else if (hue >= 4 && hue < 5) {
+    red = x;
+    blue = chroma;
+  } else {
+    red = chroma;
+    blue = x;
+  }
+
+  return {
+    red: clampChannel((red + m) * 255),
+    green: clampChannel((green + m) * 255),
+    blue: clampChannel((blue + m) * 255),
+  };
+}
+
+export function mergeColorWithExistingAlpha(nextHex: string, previousValue: string): string {
+  const hex = nextHex.trim();
+  const match = hex.match(/^#([0-9a-f]{6})$/i);
+  if (!match) return previousValue;
+
+  const previous = parseCssColor(previousValue);
+  const red = Number.parseInt(match[1].slice(0, 2), 16);
+  const green = Number.parseInt(match[1].slice(2, 4), 16);
+  const blue = Number.parseInt(match[1].slice(4, 6), 16);
+  const alpha = previous?.alpha ?? 1;
+
+  return formatCssColor({ red, green, blue, alpha });
+}
diff --git a/packages/studio/src/components/editor/domEditing.test.ts b/packages/studio/src/components/editor/domEditing.test.ts
new file mode 100644
index 000000000..6e1f9c075
--- /dev/null
+++ b/packages/studio/src/components/editor/domEditing.test.ts
@@ -0,0 +1,699 @@
+import { describe, expect, it } from "vitest";
+import { Window } from "happy-dom";
+import {
+  buildDomEditMovePatchOperations,
+  buildDomEditResizePatchOperations,
+  buildDomEditStylePatchOperation,
+  buildElementAgentPrompt,
+  collectDomEditLayerItems,
+  countDomEditChildLayers,
+  findElementForSelection,
+  getDomEditLayerKey,
+  isTextEditableSelection,
+  serializeDomEditTextFields,
+  type DomEditSelection,
+  resolveDomEditCapabilities,
+  resolveDomEditSelection,
+} from "./domEditing";
+
+function createDocument(markup: string): Document {
+  const window = new Window();
+  Object.assign(window, { SyntaxError });
+  window.document.body.innerHTML = markup;
+  return window.document;
+}
+
+describe("resolveDomEditCapabilities", () => {
+  it("marks absolute px-positioned layers as movable and resizable", () => {
+    expect(
+      resolveDomEditCapabilities({
+        selector: "#card",
+        inlineStyles: {
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+        },
+        computedStyles: {
+          position: "absolute",
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+          transform: "none",
+        },
+        isCompositionHost: false,
+        isMasterView: false,
+      }),
+    ).toEqual({
+      canSelect: true,
+      canEditStyles: true,
+      canMove: true,
+      canResize: true,
+      canDetachFromLayout: false,
+      reasonIfDisabled: undefined,
+    });
+  });
+
+  it("rejects flex/grid children for move and resize", () => {
+    expect(
+      resolveDomEditCapabilities({
+        selector: "#chip",
+        tagName: "div",
+        inlineStyles: {},
+        computedStyles: {
+          position: "static",
+          display: "block",
+          left: "auto",
+          top: "auto",
+          width: "180px",
+          height: "64px",
+          transform: "none",
+        },
+        isCompositionHost: false,
+        isMasterView: false,
+      }),
+    ).toMatchObject({
+      canSelect: true,
+      canEditStyles: true,
+      canMove: false,
+      canResize: false,
+      canDetachFromLayout: true,
+      reasonIfDisabled: "This layer is controlled by layout.",
+    });
+  });
+
+  it("rejects transform-driven geometry", () => {
+    expect(
+      resolveDomEditCapabilities({
+        selector: "#card",
+        inlineStyles: {
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+        },
+        computedStyles: {
+          position: "absolute",
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+          transform: "matrix(1, 0, 0, 1, 12, 0)",
+        },
+        isCompositionHost: false,
+        isMasterView: false,
+      }),
+    ).toMatchObject({
+      canMove: false,
+      canResize: false,
+      canDetachFromLayout: false,
+    });
+  });
+
+  it("allows moving Studio-owned motion layers even while their runtime transform is active", () => {
+    expect(
+      resolveDomEditCapabilities({
+        selector: "#headline",
+        inlineStyles: {
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+        },
+        computedStyles: {
+          position: "absolute",
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+          transform: "matrix(1, 0, 0, 1, 0, 32)",
+        },
+        hasStudioOwnedMotion: true,
+        isCompositionHost: false,
+        isMasterView: false,
+      }),
+    ).toMatchObject({
+      canMove: true,
+      canResize: true,
+      canDetachFromLayout: false,
+    });
+  });
+
+  it("treats identity transforms left behind by animation libraries as movable", () => {
+    expect(
+      resolveDomEditCapabilities({
+        selector: "#card",
+        inlineStyles: {
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+        },
+        computedStyles: {
+          position: "absolute",
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+          transform: "matrix(1, 0, 0, 1, 0, 0)",
+        },
+        isCompositionHost: false,
+        isMasterView: false,
+      }),
+    ).toMatchObject({
+      canMove: true,
+      canResize: true,
+      canDetachFromLayout: false,
+    });
+  });
+
+  it("treats identity matrix3d transforms as movable", () => {
+    expect(
+      resolveDomEditCapabilities({
+        selector: "#card",
+        inlineStyles: {
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+        },
+        computedStyles: {
+          position: "absolute",
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+          transform: "matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)",
+        },
+        isCompositionHost: false,
+        isMasterView: false,
+      }),
+    ).toMatchObject({
+      canMove: true,
+      canResize: true,
+    });
+  });
+
+  it("allows imported absolute media to resize from computed px geometry", () => {
+    expect(
+      resolveDomEditCapabilities({
+        selector: "#photo",
+        inlineStyles: {
+          inset: "0",
+          width: "100%",
+          height: "100%",
+        },
+        computedStyles: {
+          position: "absolute",
+          left: "0px",
+          top: "0px",
+          width: "330px",
+          height: "228px",
+          transform: "none",
+        },
+        isCompositionHost: false,
+        isMasterView: false,
+      }),
+    ).toMatchObject({
+      canMove: true,
+      canResize: true,
+    });
+  });
+});
+
+describe("resolveDomEditSelection", () => {
+  it("allows moving composition hosts in master view while keeping contents drill-down only", () => {
+    expect(
+      resolveDomEditCapabilities({
+        selector: "#detail-host",
+        inlineStyles: {
+          left: "80px",
+          top: "60px",
+          width: "320px",
+          height: "220px",
+        },
+        computedStyles: {
+          position: "absolute",
+          left: "80px",
+          top: "60px",
+          width: "320px",
+          height: "220px",
+          transform: "none",
+        },
+        isCompositionHost: true,
+        isMasterView: true,
+      }),
+    ).toEqual({
+      canSelect: true,
+      canEditStyles: false,
+      canMove: true,
+      canResize: true,
+      canDetachFromLayout: false,
+      reasonIfDisabled: undefined,
+    });
+  });
+
+  it("resolves child clicks inside a composition host back to the host in master view", () => {
+    const document = createDocument(`
+      <div data-composition-id="main">
+        <div id="detail-host" data-composition-src="compositions/detail-card.html">
+          <span id="inner-copy">Nested scene</span>
+        </div>
+      </div>
+    `);
+
+    const child = document.getElementById("inner-copy") as HTMLElement;
+    const selection = resolveDomEditSelection(child, {
+      activeCompositionPath: null,
+      isMasterView: true,
+    });
+
+    expect(selection?.id).toBe("detail-host");
+    expect(selection?.isCompositionHost).toBe(true);
+    expect(selection?.capabilities.canMove).toBe(false);
+    expect(selection?.capabilities.canEditStyles).toBe(false);
+  });
+
+  it("scopes class selector indexing to the same source file", () => {
+    const document = createDocument(`
+      <div data-composition-id="main">
+        <div class="chip">Root chip</div>
+        <div data-composition-id="nested" data-composition-file="compositions/nested.html">
+          <div class="chip">Nested chip</div>
+        </div>
+      </div>
+    `);
+
+    const rootChip = document.getElementsByClassName("chip")[0] as HTMLElement;
+    const selection = resolveDomEditSelection(rootChip, {
+      activeCompositionPath: null,
+      isMasterView: true,
+    });
+
+    expect(selection?.sourceFile).toBe("index.html");
+    expect(selection?.selector).toBe(".chip");
+    expect(selection?.selectorIndex).toBe(0);
+    expect(findElementForSelection(document, selection!, null)).toBe(rootChip);
+  });
+
+  it("prefers the nearest clip ancestor on single-click style selection", () => {
+    const document = createDocument(`
+      <section id="card" class="clip" style="left: 10px; top: 20px; width: 200px; height: 100px; position: absolute;">
+        <p id="copy">Hello</p>
+      </section>
+    `);
+
+    const child = document.getElementById("copy") as HTMLElement;
+    const selection = resolveDomEditSelection(child, {
+      activeCompositionPath: null,
+      isMasterView: false,
+      preferClipAncestor: true,
+    });
+
+    expect(selection?.id).toBe("card");
+    expect(selection?.selector).toBe("#card");
+  });
+
+  it("can resolve the exact child when clip-ancestor preference is disabled", () => {
+    const document = createDocument(`
+      <section id="card" class="clip" style="left: 10px; top: 20px; width: 200px; height: 100px; position: absolute;">
+        <p id="copy">Hello</p>
+      </section>
+    `);
+
+    const child = document.getElementById("copy") as HTMLElement;
+    const selection = resolveDomEditSelection(child, {
+      activeCompositionPath: null,
+      isMasterView: false,
+      preferClipAncestor: false,
+    });
+
+    expect(selection?.id).toBe("copy");
+    expect(selection?.selector).toBe("#copy");
+  });
+
+  it("collects simple child text blocks as separate editable fields", () => {
+    const document = createDocument(`
+      <section id="card" class="clip" style="left: 10px; top: 20px; width: 200px; height: 100px; position: absolute;">
+        <strong>Headline</strong>
+        <span>Supporting copy</span>
+      </section>
+    `);
+
+    const selection = resolveDomEditSelection(document.getElementById("card") as HTMLElement, {
+      activeCompositionPath: null,
+      isMasterView: false,
+    });
+
+    expect(selection?.textFields.map((field) => field.label)).toEqual(["Text 1", "Text 2"]);
+    expect(selection?.textFields.map((field) => field.value)).toEqual([
+      "Headline",
+      "Supporting copy",
+    ]);
+  });
+
+  it("preserves user-entered text spacing in editable text fields", () => {
+    const document = createDocument(`
+      <section id="card" class="clip" style="position: absolute;">
+        <strong>Headline with trailing space </strong>
+      </section>
+    `);
+
+    const selection = resolveDomEditSelection(document.getElementById("card") as HTMLElement, {
+      activeCompositionPath: null,
+      isMasterView: false,
+    });
+
+    expect(selection?.textFields[0]?.value).toBe("Headline with trailing space ");
+  });
+
+  it("keeps an emptied text layer editable so users can type into it again", () => {
+    const document = createDocument(`
+      <div id="card" class="clip" style="position: absolute;"></div>
+    `);
+
+    const selection = resolveDomEditSelection(document.getElementById("card") as HTMLElement, {
+      activeCompositionPath: null,
+      isMasterView: false,
+    });
+
+    expect(selection?.textFields).toMatchObject([
+      {
+        key: "self:0:div",
+        label: "Content",
+        value: "",
+        source: "self",
+      },
+    ]);
+    expect(selection ? isTextEditableSelection(selection) : false).toBe(true);
+  });
+
+  it("keeps emptied child text layers editable after their content is cleared", () => {
+    const document = createDocument(`
+      <div id="card" class="clip" style="position: absolute;">
+        <strong></strong>
+        <span></span>
+      </div>
+    `);
+
+    const selection = resolveDomEditSelection(document.getElementById("card") as HTMLElement, {
+      activeCompositionPath: null,
+      isMasterView: false,
+    });
+
+    expect(selection?.textFields.map((field) => field.tagName)).toEqual(["strong", "span"]);
+    expect(selection?.textFields.map((field) => field.value)).toEqual(["", ""]);
+  });
+
+  it("builds a stable selectable layer tree for timeline clip inspection", () => {
+    const document = createDocument(`
+      <section id="clip" class="clip" style="position: absolute;">
+        <div id="card">
+          <h1 class="title">Headline</h1>
+          <p class="copy">Copy</p>
+        </div>
+        <script>window.noop = true;</script>
+      </section>
+    `);
+
+    const root = document.getElementById("clip") as HTMLElement;
+    const layers = collectDomEditLayerItems(root, {
+      activeCompositionPath: "compositions/manual.html",
+      isMasterView: false,
+    });
+
+    expect(layers.map((layer) => [layer.label, layer.tagName, layer.depth])).toEqual([
+      ["Clip", "section", 0],
+      ["Card", "div", 1],
+      ["Title", "h1", 2],
+      ["Copy", "p", 2],
+    ]);
+    expect(layers[0]?.childCount).toBe(1);
+    expect(
+      countDomEditChildLayers(root, {
+        activeCompositionPath: "compositions/manual.html",
+        isMasterView: false,
+      }),
+    ).toBe(3);
+    expect(getDomEditLayerKey(layers[2]!)).toBe("compositions/manual.html:.title:0");
+  });
+
+  it("handles SVG className objects when counting nested timeline layers", () => {
+    const document = createDocument(`
+      <section id="clip" class="clip" style="position: absolute;">
+        <svg class="icon" viewBox="0 0 24 24">
+          <path class="spark" d="M4 12h16" />
+        </svg>
+      </section>
+    `);
+
+    const svg = document.querySelector("svg") as HTMLElement;
+    Object.defineProperty(svg, "className", {
+      configurable: true,
+      value: { baseVal: "icon" },
+    });
+
+    const root = document.getElementById("clip") as HTMLElement;
+
+    expect(() =>
+      countDomEditChildLayers(root, {
+        activeCompositionPath: "compositions/manual.html",
+        isMasterView: false,
+      }),
+    ).not.toThrow();
+
+    const layers = collectDomEditLayerItems(root, {
+      activeCompositionPath: "compositions/manual.html",
+      isMasterView: false,
+    });
+
+    expect(layers.map((layer) => layer.selector)).toContain(".icon");
+  });
+});
+
+describe("patch builders and prompt builder", () => {
+  it("builds move patch operations for left/top", () => {
+    expect(buildDomEditMovePatchOperations(140.4, 82.1)).toEqual([
+      { type: "inline-style", property: "left", value: "140px" },
+      { type: "inline-style", property: "top", value: "82px" },
+    ]);
+  });
+
+  it("builds resize patch operations for width/height", () => {
+    expect(buildDomEditResizePatchOperations(301.6, 210.1)).toEqual([
+      { type: "inline-style", property: "width", value: "302px" },
+      { type: "inline-style", property: "height", value: "210px" },
+    ]);
+  });
+
+  it("builds style patch operations", () => {
+    expect(buildDomEditStylePatchOperation("background-color", "rgb(15, 23, 42)")).toEqual({
+      type: "inline-style",
+      property: "background-color",
+      value: "rgb(15, 23, 42)",
+    });
+  });
+
+  it("builds an agent prompt with source and selector context", () => {
+    const selection = {
+      element: {} as HTMLElement,
+      id: "editable-card",
+      selector: "#editable-card",
+      selectorIndex: undefined,
+      sourceFile: "index.html",
+      compositionPath: "index.html",
+      compositionSrc: undefined,
+      isCompositionHost: false,
+      label: "Drag me first",
+      tagName: "div",
+      boundingBox: { x: 108, y: 112, width: 380, height: 196 },
+      textContent: "Drag me first",
+      dataAttributes: {},
+      inlineStyles: {
+        left: "108px",
+        top: "112px",
+        width: "380px",
+        height: "196px",
+      },
+      computedStyles: {
+        position: "absolute",
+        left: "108px",
+        top: "112px",
+        width: "380px",
+        height: "196px",
+        color: "rgb(248, 250, 252)",
+      },
+      textFields: [
+        {
+          key: "self:0:div",
+          label: "Content",
+          value: "Drag me first",
+          tagName: "div",
+          attributes: [],
+          inlineStyles: {},
+          computedStyles: {},
+          source: "self",
+        },
+      ],
+      capabilities: {
+        canSelect: true,
+        canEditStyles: true,
+        canMove: true,
+        canResize: true,
+      },
+    } satisfies DomEditSelection;
+
+    const prompt = buildElementAgentPrompt({
+      selection,
+      currentTime: 1.25,
+      tagSnippet: `<div id="editable-card" style="position:absolute; left: 108px; top: 112px; width: 380px; height: 196px; color: rgb(248, 250, 252)"`,
+    });
+
+    expect(prompt).toContain("## HyperFrames element edit request v1");
+    expect(prompt).toContain("Schema version: 1");
+    expect(prompt).toContain("Source file: index.html");
+    expect(prompt).toContain("Selector: #editable-card");
+    expect(prompt).toContain("Playback time:");
+    expect(prompt).toContain("Text fields:");
+    expect(prompt).toContain('key=self:0:div; tag=<div>; source=self; text="Drag me first"');
+    expect(prompt).toContain("Inline styles:");
+    expect(prompt).toContain("Computed styles (browser-resolved):");
+    expect(prompt).toContain("Target HTML:");
+    expect(prompt).toContain("Guardrails:");
+    expect(prompt).toContain("Do not modify other elements' data-* attributes or positioning.");
+  });
+
+  it("uses an absolute source path in copied agent prompts when provided", () => {
+    const selection = {
+      element: {} as HTMLElement,
+      id: "editable-card",
+      selector: "#editable-card",
+      selectorIndex: undefined,
+      sourceFile: "index.html",
+      compositionPath: "index.html",
+      compositionSrc: undefined,
+      isCompositionHost: false,
+      label: "Drag me first",
+      tagName: "div",
+      boundingBox: { x: 108, y: 112, width: 380, height: 196 },
+      textContent: "Drag me first",
+      dataAttributes: {},
+      inlineStyles: {},
+      computedStyles: {},
+      textFields: [],
+      capabilities: {
+        canSelect: true,
+        canEditStyles: true,
+        canMove: true,
+        canResize: true,
+        canDetachFromLayout: false,
+      },
+    } satisfies DomEditSelection;
+
+    const prompt = buildElementAgentPrompt({
+      selection,
+      currentTime: 1.25,
+      sourceFilePath: "/tmp/hf-studio-project/index.html",
+    });
+
+    expect(prompt).toContain("Source file: /tmp/hf-studio-project/index.html");
+    expect(prompt).not.toContain("Source file: index.html");
+  });
+
+  it("includes motion ownership and runtime guardrails in motion-aware agent prompts", () => {
+    const selection = {
+      element: {} as HTMLElement,
+      id: "headline",
+      selector: "#headline",
+      selectorIndex: undefined,
+      sourceFile: "index.html",
+      compositionPath: "index.html",
+      compositionSrc: undefined,
+      isCompositionHost: false,
+      label: "Headline",
+      tagName: "div",
+      boundingBox: { x: 100, y: 120, width: 500, height: 180 },
+      textContent: "Launch",
+      dataAttributes: {
+        "hf-motion":
+          "v=1;preset=fade-up;start=0;duration=0.6;ease=outCubic;x=0;y=32;opacity=0:1;scale=1:1",
+      },
+      inlineStyles: {},
+      computedStyles: {},
+      textFields: [],
+      capabilities: {
+        canSelect: true,
+        canEditStyles: true,
+        canMove: true,
+        canResize: true,
+        canDetachFromLayout: false,
+      },
+    } satisfies DomEditSelection;
+
+    const prompt = buildElementAgentPrompt({
+      selection,
+      currentTime: 0.35,
+      sourceFilePath: "/tmp/hf-studio-project/index.html",
+      motionContext: {
+        version: 1,
+        state: "mixed",
+        summary: "Multiple motion owners detected; external owners are read-only.",
+        hfMotionAttribute: selection.dataAttributes["hf-motion"],
+        owners: [
+          { label: "HF Motion", state: "Editable", editable: true },
+          { label: "GSAP", state: "Detected", editable: false },
+          { label: "Mixed", state: "Mixed", editable: false },
+        ],
+        curveTracks: [
+          { key: "y", label: "Y", from: 32, to: 0, unit: "px", active: true },
+          { key: "opacity", label: "Opacity", from: 0, to: 1, unit: "", active: true },
+        ],
+        instructions: [
+          "Patch the existing runtime library only when the target is static and element-specific.",
+          "Use an outer layout wrapper when transform ownership is mixed.",
+        ],
+      },
+    });
+
+    expect(prompt).toContain("## HyperFrames element edit request v2");
+    expect(prompt).toContain("Motion context:");
+    expect(prompt).toContain("Authored HF Motion:");
+    expect(prompt).toContain("- HF Motion: Editable");
+    expect(prompt).toContain("- GSAP: Detected");
+    expect(prompt).toContain("- Y: 32px -> 0px");
+    expect(prompt).toContain("Patch the existing runtime library only when");
+    expect(prompt).toContain("Use an outer layout wrapper");
+  });
+
+  it("serializes child text fields back into HTML", () => {
+    expect(
+      serializeDomEditTextFields([
+        {
+          key: "child:0:strong",
+          label: "Text 1",
+          value: "Headline <1>",
+          tagName: "strong",
+          attributes: [],
+          inlineStyles: {
+            "font-size": "22px",
+          },
+          computedStyles: {},
+          source: "child",
+        },
+        {
+          key: "child:1:span",
+          label: "Text 2",
+          value: "Details & more",
+          tagName: "span",
+          attributes: [],
+          inlineStyles: {},
+          computedStyles: {},
+          source: "child",
+        },
+      ]),
+    ).toBe(
+      '<strong data-hf-text-key="child:0:strong" style="font-size: 22px">Headline &lt;1&gt;</strong><span data-hf-text-key="child:1:span">Details &amp; more</span>',
+    );
+  });
+});
diff --git a/packages/studio/src/components/editor/domEditing.ts b/packages/studio/src/components/editor/domEditing.ts
new file mode 100644
index 000000000..77608d810
--- /dev/null
+++ b/packages/studio/src/components/editor/domEditing.ts
@@ -0,0 +1,962 @@
+import { formatTime } from "../../player/lib/time";
+import type { PatchOperation, PatchTarget } from "../../utils/sourcePatcher";
+import type { MotionAgentContext } from "./motionEditing";
+
+const CURATED_STYLE_PROPERTIES = [
+  "position",
+  "display",
+  "top",
+  "left",
+  "right",
+  "bottom",
+  "inset",
+  "width",
+  "height",
+  "gap",
+  "justify-content",
+  "align-items",
+  "flex-direction",
+  "font-size",
+  "font-weight",
+  "font-family",
+  "color",
+  "background-color",
+  "background-image",
+  "opacity",
+  "mix-blend-mode",
+  "border-radius",
+  "border-color",
+  "outline-color",
+  "overflow",
+  "box-shadow",
+  "z-index",
+  "transform",
+] as const;
+
+export interface DomEditCapabilities {
+  canSelect: boolean;
+  canEditStyles: boolean;
+  canMove: boolean;
+  canResize: boolean;
+  canDetachFromLayout: boolean;
+  reasonIfDisabled?: string;
+}
+
+export interface DomEditTextField {
+  key: string;
+  label: string;
+  value: string;
+  tagName: string;
+  attributes: Array<{ name: string; value: string }>;
+  inlineStyles: Record<string, string>;
+  computedStyles: Record<string, string>;
+  source: "self" | "child";
+}
+
+export interface DomEditSelection extends PatchTarget {
+  element: HTMLElement;
+  label: string;
+  tagName: string;
+  sourceFile: string;
+  compositionPath: string;
+  compositionSrc?: string;
+  isCompositionHost: boolean;
+  boundingBox: { x: number; y: number; width: number; height: number };
+  textContent: string | null;
+  dataAttributes: Record<string, string>;
+  inlineStyles: Record<string, string>;
+  computedStyles: Record<string, string>;
+  textFields: DomEditTextField[];
+  capabilities: DomEditCapabilities;
+}
+
+export interface DomEditLayerItem {
+  key: string;
+  element: HTMLElement;
+  label: string;
+  tagName: string;
+  depth: number;
+  childCount: number;
+  id?: string;
+  selector?: string;
+  selectorIndex?: number;
+  sourceFile: string;
+}
+
+export interface DomEditContextOptions {
+  activeCompositionPath: string | null;
+  isMasterView: boolean;
+  preferClipAncestor?: boolean;
+}
+
+function isHtmlElement(value: unknown): value is HTMLElement {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "nodeType" in value &&
+    typeof (value as { nodeType?: unknown }).nodeType === "number" &&
+    (value as { nodeType: number }).nodeType === 1
+  );
+}
+
+function parsePx(value: string | undefined): number | null {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (!trimmed.endsWith("px")) return null;
+  const parsed = parseFloat(trimmed);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function isIdentityTransform(value: string | undefined): boolean {
+  const transform = (value ?? "none").trim();
+  if (!transform || transform === "none") return true;
+
+  const matrix = transform.match(/^matrix\(([^)]+)\)$/i);
+  if (matrix) {
+    const values = matrix[1].split(",").map((part) => Number.parseFloat(part.trim()));
+    if (values.length !== 6 || values.some((part) => !Number.isFinite(part))) return false;
+    return (
+      Math.abs(values[0] - 1) < 0.0001 &&
+      Math.abs(values[1]) < 0.0001 &&
+      Math.abs(values[2]) < 0.0001 &&
+      Math.abs(values[3] - 1) < 0.0001 &&
+      Math.abs(values[4]) < 0.0001 &&
+      Math.abs(values[5]) < 0.0001
+    );
+  }
+
+  const matrix3d = transform.match(/^matrix3d\(([^)]+)\)$/i);
+  if (!matrix3d) return false;
+  const values = matrix3d[1].split(",").map((part) => Number.parseFloat(part.trim()));
+  if (values.length !== 16 || values.some((part) => !Number.isFinite(part))) return false;
+  const identity = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+  return values.every((part, index) => Math.abs(part - identity[index]) < 0.0001);
+}
+
+function isClipClassName(className: string | undefined): boolean {
+  return Boolean(className?.split(/\s+/).includes("clip"));
+}
+
+function isInlineTextTag(tagName: string | undefined): boolean {
+  return Boolean(
+    tagName &&
+    ["a", "b", "em", "i", "small", "span", "strong", "sub", "sup"].includes(tagName.toLowerCase()),
+  );
+}
+
+function isBlockishTag(tagName: string | undefined): boolean {
+  return Boolean(
+    tagName &&
+    [
+      "article",
+      "aside",
+      "canvas",
+      "div",
+      "figure",
+      "footer",
+      "header",
+      "img",
+      "main",
+      "section",
+      "svg",
+      "video",
+    ].includes(tagName.toLowerCase()),
+  );
+}
+
+function isBlockishDisplay(display: string | undefined): boolean {
+  return Boolean(
+    display &&
+    [
+      "block",
+      "flex",
+      "flow-root",
+      "grid",
+      "inline-block",
+      "inline-flex",
+      "inline-grid",
+      "list-item",
+      "table",
+    ].includes(display),
+  );
+}
+
+function isTextBearingTag(tagName: string): boolean {
+  return ["div", "span", "p", "strong", "h1", "h2", "h3", "h4", "h5", "h6"].includes(tagName);
+}
+
+function getCuratedComputedStyles(el: HTMLElement): Record<string, string> {
+  const styles: Record<string, string> = {};
+  const computed = el.ownerDocument.defaultView?.getComputedStyle(el);
+  if (!computed) return styles;
+
+  for (const prop of CURATED_STYLE_PROPERTIES) {
+    const value = computed.getPropertyValue(prop);
+    if (value) styles[prop] = value;
+  }
+
+  return styles;
+}
+
+function findClosestByAttribute(el: HTMLElement, attributeNames: string[]): HTMLElement | null {
+  let current: HTMLElement | null = el;
+  while (current) {
+    const candidate = current;
+    if (attributeNames.some((attribute) => candidate.hasAttribute(attribute))) {
+      return candidate;
+    }
+    current = current.parentElement;
+  }
+  return null;
+}
+
+function getCompositionHost(el: HTMLElement): HTMLElement | null {
+  return findClosestByAttribute(el, ["data-composition-src", "data-composition-file"]);
+}
+
+function getSourceFileForElement(
+  el: HTMLElement,
+  activeCompositionPath: string | null,
+): { sourceFile: string; compositionPath: string } {
+  const ownerRoot = findClosestByAttribute(el, ["data-composition-id"]);
+  const sourceFile =
+    ownerRoot?.getAttribute("data-composition-file") ??
+    ownerRoot?.getAttribute("data-composition-src") ??
+    activeCompositionPath ??
+    "index.html";
+
+  return {
+    sourceFile,
+    compositionPath: sourceFile,
+  };
+}
+
+function getSelectionCandidate(startEl: HTMLElement, options: DomEditContextOptions): HTMLElement {
+  if (options.preferClipAncestor) {
+    const clipAncestor = startEl.closest(".clip");
+    if (isHtmlElement(clipAncestor)) {
+      return clipAncestor;
+    }
+  }
+
+  if (!options.isMasterView) return startEl;
+
+  const compositionHost = getCompositionHost(startEl);
+  if (compositionHost && compositionHost !== startEl) {
+    return compositionHost;
+  }
+
+  return startEl;
+}
+
+function getPreferredClassSelector(el: HTMLElement): string | undefined {
+  const classes = getElementClassName(el)
+    .split(/\s+/)
+    .map((value) => value.trim())
+    .filter(Boolean);
+  if (classes.length === 0) return undefined;
+  const preferred =
+    classes.find((value) => value !== "clip" && !value.startsWith("__hf-")) ?? classes[0];
+  return preferred ? `.${preferred}` : undefined;
+}
+
+function getElementClassName(el: HTMLElement): string {
+  return typeof el.className === "string" ? el.className : (el.getAttribute("class") ?? "");
+}
+
+function humanizeIdentifier(value: string): string {
+  return (
+    value
+      .replace(/\.html$/i, "")
+      .replace(/^compositions\//i, "")
+      .split("/")
+      .at(-1)
+      ?.replace(/[-_]+/g, " ")
+      .replace(/\b\w/g, (char) => char.toUpperCase()) ?? value
+  );
+}
+
+function buildStableSelector(el: HTMLElement): string | undefined {
+  if (el.id) return `#${el.id}`;
+
+  const compositionId = el.getAttribute("data-composition-id");
+  if (compositionId) return `[data-composition-id="${compositionId}"]`;
+
+  return getPreferredClassSelector(el);
+}
+
+function getSelectorIndex(
+  doc: Document,
+  el: HTMLElement,
+  selector: string | undefined,
+  sourceFile: string,
+  activeCompositionPath: string | null,
+): number | undefined {
+  if (!selector?.startsWith(".")) return undefined;
+
+  const candidates = Array.from(doc.querySelectorAll(selector)).filter(
+    (candidate): candidate is HTMLElement =>
+      isHtmlElement(candidate) &&
+      getSourceFileForElement(candidate, activeCompositionPath).sourceFile === sourceFile,
+  );
+  const index = candidates.indexOf(el);
+  return index >= 0 ? index : undefined;
+}
+
+export function getDomEditLayerKey(
+  target: Pick<DomEditSelection, "id" | "selector" | "selectorIndex" | "sourceFile">,
+): string {
+  const selectorIndex = target.selectorIndex ?? 0;
+  return `${target.sourceFile}:${target.id ?? target.selector ?? "layer"}:${selectorIndex}`;
+}
+
+function buildElementLabel(el: HTMLElement): string {
+  const compositionId = el.getAttribute("data-composition-id");
+  if (compositionId && compositionId !== "main") {
+    return humanizeIdentifier(compositionId);
+  }
+
+  const compositionSrc =
+    el.getAttribute("data-composition-src") ?? el.getAttribute("data-composition-file");
+  if (compositionSrc) {
+    return humanizeIdentifier(compositionSrc);
+  }
+
+  if (el.id) return humanizeIdentifier(el.id);
+
+  const preferredClass = getPreferredClassSelector(el);
+  if (preferredClass) {
+    return humanizeIdentifier(preferredClass.replace(/^\./, ""));
+  }
+
+  const text = (el.textContent ?? "").trim().replace(/\s+/g, " ");
+  if (text) return text.length > 40 ? `${text.slice(0, 39)}…` : text;
+  return el.tagName.toLowerCase();
+}
+
+const DOM_LAYER_IGNORED_TAGS = new Set([
+  "base",
+  "br",
+  "link",
+  "meta",
+  "script",
+  "source",
+  "style",
+  "template",
+  "track",
+  "wbr",
+]);
+
+function isInspectableLayerElement(el: HTMLElement): boolean {
+  const tagName = el.tagName.toLowerCase();
+  if (DOM_LAYER_IGNORED_TAGS.has(tagName)) return false;
+
+  const computed = el.ownerDocument.defaultView?.getComputedStyle(el);
+  if (computed?.display === "none" || computed?.visibility === "hidden") return false;
+
+  return true;
+}
+
+function getDomLayerPatchTarget(
+  el: HTMLElement,
+  activeCompositionPath: string | null,
+): Pick<DomEditSelection, "id" | "selector" | "selectorIndex" | "sourceFile"> | null {
+  if (!isInspectableLayerElement(el)) return null;
+
+  const selector = buildStableSelector(el);
+  if (!selector) return null;
+
+  const { sourceFile } = getSourceFileForElement(el, activeCompositionPath);
+  return {
+    id: el.id || undefined,
+    selector,
+    selectorIndex: getSelectorIndex(
+      el.ownerDocument,
+      el,
+      selector,
+      sourceFile,
+      activeCompositionPath,
+    ),
+    sourceFile,
+  };
+}
+
+function getDirectLayerChildren(el: HTMLElement, options: DomEditContextOptions): HTMLElement[] {
+  return Array.from(el.children).filter(
+    (child): child is HTMLElement =>
+      isHtmlElement(child) && getDomLayerPatchTarget(child, options.activeCompositionPath) !== null,
+  );
+}
+
+export function countDomEditChildLayers(
+  root: HTMLElement | null | undefined,
+  options: DomEditContextOptions,
+  maxCount = 99,
+): number {
+  if (!root) return 0;
+
+  let count = 0;
+  const visit = (el: HTMLElement) => {
+    for (const child of Array.from(el.children)) {
+      if (!isHtmlElement(child)) continue;
+      if (getDomLayerPatchTarget(child, options.activeCompositionPath)) {
+        count += 1;
+        if (count >= maxCount) return;
+      }
+      visit(child);
+      if (count >= maxCount) return;
+    }
+  };
+
+  visit(root);
+  return count;
+}
+
+export function collectDomEditLayerItems(
+  root: HTMLElement | null | undefined,
+  options: DomEditContextOptions,
+  maxItems = 80,
+): DomEditLayerItem[] {
+  if (!root) return [];
+
+  const items: DomEditLayerItem[] = [];
+  const visit = (el: HTMLElement, depth: number) => {
+    if (items.length >= maxItems) return;
+
+    const target = getDomLayerPatchTarget(el, options.activeCompositionPath);
+    if (target) {
+      items.push({
+        key: getDomEditLayerKey(target),
+        element: el,
+        label: buildElementLabel(el),
+        tagName: el.tagName.toLowerCase(),
+        depth,
+        childCount: getDirectLayerChildren(el, options).length,
+        id: target.id ?? undefined,
+        selector: target.selector ?? undefined,
+        selectorIndex: target.selectorIndex,
+        sourceFile: target.sourceFile,
+      });
+    }
+
+    const nextDepth = target ? depth + 1 : depth;
+    for (const child of Array.from(el.children)) {
+      if (!isHtmlElement(child)) continue;
+      visit(child, nextDepth);
+      if (items.length >= maxItems) return;
+    }
+  };
+
+  visit(root, 0);
+  return items;
+}
+
+function getDataAttributes(el: HTMLElement): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  for (const attr of el.attributes) {
+    if (attr.name.startsWith("data-")) {
+      attrs[attr.name.slice(5)] = attr.value;
+    }
+  }
+  return attrs;
+}
+
+function getInlineStyles(el: HTMLElement): Record<string, string> {
+  const styles: Record<string, string> = {};
+  for (const property of CURATED_STYLE_PROPERTIES) {
+    const value = el.style.getPropertyValue(property);
+    if (value) styles[property] = value;
+  }
+  return styles;
+}
+
+function isEditableTextLeaf(el: HTMLElement): boolean {
+  return isTextBearingTag(el.tagName.toLowerCase()) && el.children.length === 0;
+}
+
+function getTextFieldLabel(
+  _tagName: string,
+  index: number,
+  total: number,
+  source: "self" | "child",
+): string {
+  if (source === "self" || total === 1) return "Content";
+  return `Text ${index + 1}`;
+}
+
+function buildTextField(
+  el: HTMLElement,
+  index: number,
+  total: number,
+  source: "self" | "child",
+): DomEditTextField {
+  const tagName = el.tagName.toLowerCase();
+  const key = el.getAttribute("data-hf-text-key") ?? `${source}:${index}:${tagName}`;
+  return {
+    key,
+    label: getTextFieldLabel(tagName, index, total, source),
+    value: el.textContent ?? "",
+    tagName,
+    attributes: Array.from(el.attributes)
+      .filter((attribute) => attribute.name !== "style")
+      .map((attribute) => ({
+        name: attribute.name,
+        value: attribute.value,
+      })),
+    inlineStyles: getInlineStyles(el),
+    computedStyles: getCuratedComputedStyles(el),
+    source,
+  };
+}
+
+function collectDomEditTextFields(el: HTMLElement): DomEditTextField[] {
+  const childFields = Array.from(el.children).filter(isHtmlElement).filter(isEditableTextLeaf);
+  if (childFields.length > 0) {
+    return childFields.map((child, index) =>
+      buildTextField(child, index, childFields.length, "child"),
+    );
+  }
+
+  if (isEditableTextLeaf(el)) {
+    return [buildTextField(el, 0, 1, "self")];
+  }
+
+  return [];
+}
+
+function escapeHtmlText(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function serializeTextFieldStyle(field: DomEditTextField): string {
+  const entries = Object.entries(field.inlineStyles).filter(([, value]) => Boolean(value));
+  if (entries.length === 0) return "";
+  return entries.map(([key, value]) => `${key}: ${value}`).join("; ");
+}
+
+export function serializeDomEditTextFields(fields: DomEditTextField[]): string {
+  return fields
+    .filter((field) => field.source === "child")
+    .map((field) => {
+      const attrs = [
+        ...field.attributes.filter((attribute) => attribute.name !== "data-hf-text-key"),
+        { name: "data-hf-text-key", value: field.key },
+      ]
+        .map((attribute) => ` ${attribute.name}="${attribute.value.replace(/"/g, "&quot;")}"`)
+        .join("");
+      const style = serializeTextFieldStyle(field);
+      const styleAttr = style ? ` style="${style.replace(/"/g, "&quot;")}"` : "";
+      return `<${field.tagName}${attrs}${styleAttr}>${escapeHtmlText(field.value)}</${field.tagName}>`;
+    })
+    .join("");
+}
+
+export function buildDefaultDomEditTextField(base?: Partial<DomEditTextField>): DomEditTextField {
+  return {
+    key: `child:new:${Date.now()}`,
+    label: "Text",
+    value: "New text",
+    tagName: "span",
+    attributes: [],
+    inlineStyles: {
+      "font-family": base?.computedStyles?.["font-family"] ?? "inherit",
+      "font-size": base?.computedStyles?.["font-size"] ?? "16px",
+      "font-weight": base?.computedStyles?.["font-weight"] ?? "400",
+      color: base?.computedStyles?.color ?? "inherit",
+    },
+    computedStyles: {},
+    source: "child",
+  };
+}
+
+export function resolveDomEditCapabilities(args: {
+  selector?: string;
+  tagName?: string;
+  className?: string;
+  inlineStyles: Record<string, string>;
+  computedStyles: Record<string, string>;
+  hasStudioOwnedMotion?: boolean;
+  isCompositionHost: boolean;
+  isMasterView: boolean;
+}): DomEditCapabilities {
+  if (!args.selector) {
+    return {
+      canSelect: false,
+      canEditStyles: false,
+      canMove: false,
+      canResize: false,
+      canDetachFromLayout: false,
+      reasonIfDisabled: "Studio could not resolve a stable patch target for this element.",
+    };
+  }
+
+  const position = args.computedStyles.position;
+  const left = parsePx(args.inlineStyles.left) ?? parsePx(args.computedStyles.left);
+  const top = parsePx(args.inlineStyles.top) ?? parsePx(args.computedStyles.top);
+  const width = parsePx(args.inlineStyles.width) ?? parsePx(args.computedStyles.width);
+  const height = parsePx(args.inlineStyles.height) ?? parsePx(args.computedStyles.height);
+  const hasTransformDrivenGeometry =
+    !args.hasStudioOwnedMotion && !isIdentityTransform(args.computedStyles.transform);
+
+  const canMove =
+    (position === "absolute" || position === "fixed") &&
+    left != null &&
+    top != null &&
+    !hasTransformDrivenGeometry;
+
+  const canResize = canMove && (width != null || height != null);
+  const isBlockishLayer =
+    args.isCompositionHost ||
+    isClipClassName(args.className) ||
+    isBlockishTag(args.tagName) ||
+    isBlockishDisplay(args.computedStyles.display);
+  const canDetachFromLayout =
+    !canMove &&
+    !hasTransformDrivenGeometry &&
+    isBlockishLayer &&
+    (!isInlineTextTag(args.tagName) || isClipClassName(args.className));
+  const reasonIfDisabled = !canMove
+    ? canDetachFromLayout
+      ? "This layer is controlled by layout."
+      : "Direct move/resize is limited to absolute or fixed elements with px geometry and no transform-driven layout."
+    : undefined;
+
+  if (args.isCompositionHost && args.isMasterView) {
+    return {
+      canSelect: true,
+      canEditStyles: false,
+      canMove,
+      canResize,
+      canDetachFromLayout,
+      reasonIfDisabled,
+    };
+  }
+
+  return {
+    canSelect: true,
+    canEditStyles: true,
+    canMove,
+    canResize,
+    canDetachFromLayout,
+    reasonIfDisabled,
+  };
+}
+
+export function resolveDomEditSelection(
+  startEl: HTMLElement | null,
+  options: DomEditContextOptions,
+): DomEditSelection | null {
+  if (!startEl) return null;
+  const doc = startEl.ownerDocument;
+
+  let current: HTMLElement | null = getSelectionCandidate(startEl, options);
+  while (current && current !== doc.body && current !== doc.documentElement) {
+    const selector = buildStableSelector(current);
+    if (!selector) {
+      current = current.parentElement;
+      continue;
+    }
+
+    const { sourceFile, compositionPath } = getSourceFileForElement(
+      current,
+      options.activeCompositionPath,
+    );
+    const selectorIndex = getSelectorIndex(
+      doc,
+      current,
+      selector,
+      sourceFile,
+      options.activeCompositionPath,
+    );
+    const compositionSrc =
+      current.getAttribute("data-composition-src") ??
+      current.getAttribute("data-composition-file") ??
+      undefined;
+    const inlineStyles = getInlineStyles(current);
+    const computedStyles = getCuratedComputedStyles(current);
+    const textFields = collectDomEditTextFields(current);
+    const capabilities = resolveDomEditCapabilities({
+      selector,
+      tagName: current.tagName.toLowerCase(),
+      className: getElementClassName(current),
+      inlineStyles,
+      computedStyles,
+      hasStudioOwnedMotion: current.hasAttribute("data-hf-motion"),
+      isCompositionHost: Boolean(compositionSrc),
+      isMasterView: options.isMasterView,
+    });
+    const rect = current.getBoundingClientRect();
+
+    return {
+      element: current,
+      id: current.id || undefined,
+      selector,
+      selectorIndex,
+      sourceFile,
+      compositionPath,
+      compositionSrc,
+      isCompositionHost: Boolean(compositionSrc),
+      label: buildElementLabel(current),
+      tagName: current.tagName.toLowerCase(),
+      boundingBox: {
+        x: rect.left,
+        y: rect.top,
+        width: rect.width,
+        height: rect.height,
+      },
+      textContent: current.textContent?.trim() || null,
+      dataAttributes: getDataAttributes(current),
+      inlineStyles,
+      computedStyles,
+      textFields,
+      capabilities,
+    };
+  }
+
+  return null;
+}
+
+export function refreshDomEditSelection(
+  selection: DomEditSelection,
+  activeCompositionPath: string | null,
+): DomEditSelection | null {
+  const doc = selection.element.ownerDocument;
+  const nextElement = findElementForSelection(doc, selection, activeCompositionPath);
+  return nextElement
+    ? resolveDomEditSelection(nextElement, {
+        activeCompositionPath,
+        isMasterView: !activeCompositionPath || activeCompositionPath === "index.html",
+      })
+    : null;
+}
+
+export function findElementForSelection(
+  doc: Document,
+  selection: Pick<DomEditSelection, "id" | "selector" | "selectorIndex" | "sourceFile">,
+  activeCompositionPath: string | null = null,
+): HTMLElement | null {
+  if (selection.id) {
+    const byId = doc.getElementById(selection.id);
+    if (
+      isHtmlElement(byId) &&
+      (!selection.sourceFile ||
+        getSourceFileForElement(byId, activeCompositionPath).sourceFile === selection.sourceFile)
+    ) {
+      return byId;
+    }
+  }
+
+  if (!selection.selector) return null;
+
+  if (selection.selector.startsWith(".") && selection.selectorIndex != null) {
+    const matches = Array.from(doc.querySelectorAll(selection.selector)).filter(
+      (candidate): candidate is HTMLElement =>
+        isHtmlElement(candidate) &&
+        (!selection.sourceFile ||
+          getSourceFileForElement(candidate, activeCompositionPath).sourceFile ===
+            selection.sourceFile),
+    );
+    return matches[selection.selectorIndex] ?? null;
+  }
+
+  const matches = Array.from(doc.querySelectorAll(selection.selector)).filter(
+    (candidate): candidate is HTMLElement =>
+      isHtmlElement(candidate) &&
+      (!selection.sourceFile ||
+        getSourceFileForElement(candidate, activeCompositionPath).sourceFile ===
+          selection.sourceFile),
+  );
+  return matches[0] ?? null;
+}
+
+export function buildDomEditMovePatchOperations(left: number, top: number): PatchOperation[] {
+  return [
+    { type: "inline-style", property: "left", value: `${Math.round(left)}px` },
+    { type: "inline-style", property: "top", value: `${Math.round(top)}px` },
+  ];
+}
+
+export function buildDomEditResizePatchOperations(width: number, height: number): PatchOperation[] {
+  return [
+    { type: "inline-style", property: "width", value: `${Math.round(width)}px` },
+    { type: "inline-style", property: "height", value: `${Math.round(height)}px` },
+  ];
+}
+
+export function buildDomEditDetachPatchOperations(rect: {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}): PatchOperation[] {
+  return [
+    { type: "inline-style", property: "position", value: "absolute" },
+    { type: "inline-style", property: "left", value: `${Math.round(rect.left)}px` },
+    { type: "inline-style", property: "top", value: `${Math.round(rect.top)}px` },
+    { type: "inline-style", property: "width", value: `${Math.round(rect.width)}px` },
+    { type: "inline-style", property: "height", value: `${Math.round(rect.height)}px` },
+    { type: "inline-style", property: "margin", value: "0" },
+    { type: "inline-style", property: "right", value: "auto" },
+    { type: "inline-style", property: "bottom", value: "auto" },
+  ];
+}
+
+export function buildDomEditStylePatchOperation(property: string, value: string): PatchOperation {
+  return {
+    type: "inline-style",
+    property,
+    value,
+  };
+}
+
+export function buildDomEditTextPatchOperation(value: string): PatchOperation {
+  return {
+    type: "text-content",
+    property: "text",
+    value,
+  };
+}
+
+function formatBoundingBox(bounds: DomEditSelection["boundingBox"]): string {
+  return `x=${Math.round(bounds.x)}, y=${Math.round(bounds.y)}, width=${Math.round(bounds.width)}, height=${Math.round(bounds.height)}`;
+}
+
+function formatStyleBlock(styles: Record<string, string>): string {
+  return Object.entries(styles)
+    .filter(([, value]) => value && value !== "initial")
+    .map(([key, value]) => `${key}: ${value}`)
+    .join("\n");
+}
+
+function formatTextFields(fields: DomEditTextField[]): string {
+  return fields
+    .map(
+      (field) =>
+        `- key=${field.key}; tag=<${field.tagName}>; source=${field.source}; text="${field.value.replace(/"/g, '\\"')}"`,
+    )
+    .join("\n");
+}
+
+function formatMotionNumber(value: number): string {
+  const normalized = Math.abs(value) < 0.0001 ? 0 : value;
+  const rounded = Math.round(normalized * 1000) / 1000;
+  return Number.isInteger(rounded)
+    ? `${rounded}`
+    : rounded.toFixed(3).replace(/0+$/, "").replace(/\.$/, "");
+}
+
+function formatMotionTrackValue(value: number, unit: string): string {
+  return `${formatMotionNumber(value)}${unit}`;
+}
+
+function formatMotionContext(context: MotionAgentContext): string[] {
+  const lines = ["Motion context:", `State: ${context.state}`, `Summary: ${context.summary}`];
+
+  if (context.hfMotionAttribute) {
+    lines.push(`Authored HF Motion: ${context.hfMotionAttribute}`);
+  }
+
+  if (context.owners.length > 0) {
+    lines.push("Runtime owners:");
+    for (const owner of context.owners) {
+      lines.push(`- ${owner.label}: ${owner.state}${owner.editable ? " (editable)" : ""}`);
+    }
+  }
+
+  if (context.curveTracks.length > 0) {
+    lines.push("Motion curve tracks:");
+    for (const track of context.curveTracks) {
+      lines.push(
+        `- ${track.label}: ${formatMotionTrackValue(track.from, track.unit)} -> ${formatMotionTrackValue(
+          track.to,
+          track.unit,
+        )}${track.active ? "" : " (constant)"}`,
+      );
+    }
+  }
+
+  if (context.instructions.length > 0) {
+    lines.push("Motion edit guidance:");
+    for (const instruction of context.instructions) {
+      lines.push(`- ${instruction}`);
+    }
+  }
+
+  return lines;
+}
+
+export function buildElementAgentPrompt({
+  selection,
+  currentTime,
+  tagSnippet,
+  userInstruction,
+  sourceFilePath,
+  motionContext,
+}: {
+  selection: DomEditSelection;
+  currentTime: number;
+  tagSnippet?: string;
+  userInstruction?: string;
+  sourceFilePath?: string;
+  motionContext?: MotionAgentContext;
+}): string {
+  const displayedSourceFile = sourceFilePath?.trim() || selection.sourceFile;
+  const schemaVersion = motionContext ? 2 : 1;
+  const lines = [
+    `## HyperFrames element edit request v${schemaVersion}`,
+    `Schema version: ${schemaVersion}`,
+    "",
+    userInstruction?.trim() || "Edit this selected HyperFrames element.",
+    "",
+    `Composition: ${selection.compositionPath}`,
+    `Playback time: ${formatTime(currentTime)}`,
+    `Source file: ${displayedSourceFile}`,
+    `DOM id: ${selection.id ?? "(none)"}`,
+    `Selector: ${selection.selector ?? "(none)"}`,
+    `Selector index: ${selection.selectorIndex ?? 0}`,
+    `Tag: <${selection.tagName}>`,
+    `Bounds: ${formatBoundingBox(selection.boundingBox)}`,
+  ];
+
+  if (selection.textContent) {
+    lines.push(`Text: ${selection.textContent}`);
+  }
+
+  const textFieldsBlock = formatTextFields(selection.textFields);
+  if (textFieldsBlock) {
+    lines.push("", "Text fields:", textFieldsBlock);
+  }
+
+  const inlineStyleBlock = formatStyleBlock(selection.inlineStyles);
+  if (inlineStyleBlock) {
+    lines.push("", "Inline styles:", inlineStyleBlock);
+  }
+
+  const computedStyleBlock = formatStyleBlock(selection.computedStyles);
+  if (computedStyleBlock) {
+    lines.push("", "Computed styles (browser-resolved):", computedStyleBlock);
+  }
+
+  if (tagSnippet) {
+    lines.push("", "Target HTML:", tagSnippet);
+  }
+
+  if (motionContext) {
+    lines.push("", ...formatMotionContext(motionContext));
+  }
+
+  lines.push(
+    "",
+    "Guardrails:",
+    "- Make a targeted change to this element only.",
+    "- Preserve the rest of the composition and its timing.",
+    "- Do not modify other elements' data-* attributes or positioning.",
+    "- Prefer existing inline styles or existing CSS rules for this element over adding unrelated selectors.",
+  );
+
+  return lines.join("\n");
+}
+
+export function isTextEditableSelection(selection: DomEditSelection): boolean {
+  return selection.textFields.length > 0 && !selection.isCompositionHost;
+}
diff --git a/packages/studio/src/components/editor/floatingPanel.test.ts b/packages/studio/src/components/editor/floatingPanel.test.ts
new file mode 100644
index 000000000..98145d693
--- /dev/null
+++ b/packages/studio/src/components/editor/floatingPanel.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { resolveFloatingPanelPosition } from "./floatingPanel";
+
+describe("resolveFloatingPanelPosition", () => {
+  it("places the panel below the anchor when there is space", () => {
+    expect(
+      resolveFloatingPanelPosition(
+        { left: 100, top: 100, right: 220, bottom: 140, width: 120, height: 40 },
+        { width: 800, height: 600 },
+        { width: 280, height: 220 },
+      ),
+    ).toMatchObject({ top: 148, placement: "bottom" });
+  });
+
+  it("places the panel above the anchor when the bottom would be clipped", () => {
+    expect(
+      resolveFloatingPanelPosition(
+        { left: 100, top: 500, right: 220, bottom: 540, width: 120, height: 40 },
+        { width: 800, height: 600 },
+        { width: 280, height: 220 },
+      ),
+    ).toMatchObject({ top: 272, placement: "top" });
+  });
+
+  it("clamps the panel horizontally inside the viewport", () => {
+    expect(
+      resolveFloatingPanelPosition(
+        { left: 760, top: 100, right: 800, bottom: 140, width: 40, height: 40 },
+        { width: 800, height: 600 },
+        { width: 280, height: 220 },
+      ).left,
+    ).toBe(508);
+  });
+});
diff --git a/packages/studio/src/components/editor/floatingPanel.ts b/packages/studio/src/components/editor/floatingPanel.ts
new file mode 100644
index 000000000..695d32274
--- /dev/null
+++ b/packages/studio/src/components/editor/floatingPanel.ts
@@ -0,0 +1,54 @@
+export interface FloatingRect {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+  width: number;
+  height: number;
+}
+
+export interface FloatingSize {
+  width: number;
+  height: number;
+}
+
+export interface FloatingPosition {
+  left: number;
+  top: number;
+  placement: "top" | "bottom";
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+export function resolveFloatingPanelPosition(
+  anchor: FloatingRect,
+  viewport: FloatingSize,
+  panel: FloatingSize,
+  options?: { offset?: number; margin?: number },
+): FloatingPosition {
+  const offset = options?.offset ?? 8;
+  const margin = options?.margin ?? 12;
+  const maxLeft = Math.max(margin, viewport.width - panel.width - margin);
+  const preferredLeft = anchor.left + anchor.width / 2 - panel.width / 2;
+  const left = clamp(preferredLeft, margin, maxLeft);
+  const belowTop = anchor.bottom + offset;
+  const aboveTop = anchor.top - panel.height - offset;
+  const fitsBelow = belowTop + panel.height <= viewport.height - margin;
+  const fitsAbove = aboveTop >= margin;
+
+  if (fitsBelow || !fitsAbove) {
+    return {
+      left,
+      top: clamp(belowTop, margin, Math.max(margin, viewport.height - panel.height - margin)),
+      placement: "bottom",
+    };
+  }
+
+  return {
+    left,
+    top: clamp(aboveTop, margin, Math.max(margin, viewport.height - panel.height - margin)),
+    placement: "top",
+  };
+}
diff --git a/packages/studio/src/components/editor/fontAssets.ts b/packages/studio/src/components/editor/fontAssets.ts
new file mode 100644
index 000000000..579a0f35a
--- /dev/null
+++ b/packages/studio/src/components/editor/fontAssets.ts
@@ -0,0 +1,32 @@
+export interface ImportedFontAsset {
+  family: string;
+  path: string;
+  url: string;
+}
+
+const FONT_EXT_RE = /\.(eot|otf|ttc|ttf|woff2?)$/i;
+const FONT_STYLE_SUFFIX_RE =
+  /\s+(thin|extralight|extra light|light|regular|roman|medium|semibold|semi bold|bold|extrabold|extra bold|black|italic|oblique|variable)$/i;
+
+export function cssString(value: string): string {
+  return JSON.stringify(value);
+}
+
+export function fontFamilyFromAssetPath(path: string): string {
+  const fileName = decodeURIComponent(path.split(/[\\/]/).pop() ?? path).replace(FONT_EXT_RE, "");
+  let family = fileName
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/\s+/g, " ")
+    .trim();
+
+  while (FONT_STYLE_SUFFIX_RE.test(family)) {
+    family = family.replace(FONT_STYLE_SUFFIX_RE, "").trim();
+  }
+
+  return family || fileName;
+}
+
+export function importedFontFaceCss(asset: ImportedFontAsset, url: string = asset.url): string {
+  return `@font-face { font-family: ${cssString(asset.family)}; src: url(${cssString(url)}); font-display: swap; }`;
+}
diff --git a/packages/studio/src/components/editor/fontCatalog.ts b/packages/studio/src/components/editor/fontCatalog.ts
new file mode 100644
index 000000000..c8691fc31
--- /dev/null
+++ b/packages/studio/src/components/editor/fontCatalog.ts
@@ -0,0 +1,126 @@
+export const POPULAR_GOOGLE_FONT_FAMILIES = [
+  "ABeeZee",
+  "Abel",
+  "Abril Fatface",
+  "Alegreya",
+  "Alegreya Sans",
+  "Anton",
+  "Archivo",
+  "Archivo Black",
+  "Arimo",
+  "Assistant",
+  "Barlow",
+  "Barlow Condensed",
+  "Bebas Neue",
+  "Bitter",
+  "Bricolage Grotesque",
+  "Cabin",
+  "Cardo",
+  "Catamaran",
+  "Caveat",
+  "Chivo",
+  "Cormorant Garamond",
+  "Crimson Text",
+  "Dancing Script",
+  "DM Sans",
+  "DM Serif Display",
+  "Domine",
+  "EB Garamond",
+  "Exo 2",
+  "Figtree",
+  "Fira Code",
+  "Fira Sans",
+  "Fraunces",
+  "Fredoka",
+  "IBM Plex Mono",
+  "IBM Plex Sans",
+  "IBM Plex Serif",
+  "Inconsolata",
+  "Instrument Sans",
+  "Instrument Serif",
+  "Inter",
+  "JetBrains Mono",
+  "Josefin Sans",
+  "Jost",
+  "Kanit",
+  "Karla",
+  "Lato",
+  "League Gothic",
+  "Lexend",
+  "Libre Baskerville",
+  "Libre Franklin",
+  "Lora",
+  "Manrope",
+  "Merriweather",
+  "Montserrat",
+  "Mukta",
+  "Mulish",
+  "Newsreader",
+  "Noto Sans",
+  "Noto Sans JP",
+  "Noto Serif",
+  "Nunito",
+  "Nunito Sans",
+  "Open Sans",
+  "Oswald",
+  "Outfit",
+  "Overpass",
+  "Pacifico",
+  "Pathway Extreme",
+  "Permanent Marker",
+  "Playfair Display",
+  "Plus Jakarta Sans",
+  "Poppins",
+  "Prata",
+  "PT Sans",
+  "PT Serif",
+  "Public Sans",
+  "Quicksand",
+  "Raleway",
+  "Red Hat Display",
+  "Roboto",
+  "Roboto Condensed",
+  "Roboto Mono",
+  "Roboto Serif",
+  "Rubik",
+  "Schibsted Grotesk",
+  "Signika",
+  "Source Code Pro",
+  "Source Sans 3",
+  "Source Serif 4",
+  "Space Grotesk",
+  "Space Mono",
+  "Spectral",
+  "Sora",
+  "Syne",
+  "Teko",
+  "Titillium Web",
+  "Ubuntu",
+  "Ubuntu Mono",
+  "Unbounded",
+  "Urbanist",
+  "Varela Round",
+  "Work Sans",
+  "Young Serif",
+  "Zilla Slab",
+] as const;
+
+export const COMMON_LOCAL_FONT_FAMILIES = [
+  "TT Norms Pro",
+  "SF Pro Display",
+  "SF Pro Text",
+  "Avenir",
+  "Avenir Next",
+  "Helvetica Neue",
+  "Arial",
+  "Georgia",
+  "Times New Roman",
+  "Menlo",
+  "Monaco",
+  "Courier New",
+] as const;
+
+export function googleFontStylesheetUrl(family: string): string {
+  const encodedFamily = encodeURIComponent(family.trim()).replace(/%20/g, "+");
+  return `https://fonts.googleapis.com/css2?family=${encodedFamily}:wght@300;400;500;600;700;800;900&display=swap`;
+}
diff --git a/packages/studio/src/components/editor/gradientValue.test.ts b/packages/studio/src/components/editor/gradientValue.test.ts
new file mode 100644
index 000000000..4a5dc6ca4
--- /dev/null
+++ b/packages/studio/src/components/editor/gradientValue.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildDefaultGradientModel,
+  insertGradientStop,
+  parseGradient,
+  serializeGradient,
+} from "./gradientValue";
+
+describe("parseGradient", () => {
+  it("parses linear gradients", () => {
+    expect(
+      parseGradient("linear-gradient(135deg, rgba(15, 23, 42, 0.58), rgba(255, 255, 255, 0.04))"),
+    ).toMatchObject({
+      kind: "linear",
+      repeating: false,
+      angle: 135,
+      stops: [
+        { color: "rgba(15, 23, 42, 0.58)", position: 0 },
+        { color: "rgba(255, 255, 255, 0.04)", position: 100 },
+      ],
+    });
+  });
+
+  it("parses radial gradients", () => {
+    expect(
+      parseGradient("radial-gradient(circle closest-side at 20% 35%, #ff0000 10%, #0000ff 90%)"),
+    ).toMatchObject({
+      kind: "radial",
+      shape: "circle",
+      radialSize: "closest-side",
+      centerX: 20,
+      centerY: 35,
+    });
+  });
+
+  it("parses conic gradients", () => {
+    expect(
+      parseGradient("conic-gradient(from 45deg at 40% 60%, #111111 0%, #ffffff 100%)"),
+    ).toMatchObject({
+      kind: "conic",
+      angle: 45,
+      centerX: 40,
+      centerY: 60,
+    });
+  });
+
+  it("parses repeating gradients", () => {
+    expect(
+      parseGradient("repeating-linear-gradient(90deg, #000000 0%, #ffffff 50%)"),
+    ).toMatchObject({
+      kind: "linear",
+      repeating: true,
+      angle: 90,
+    });
+  });
+});
+
+describe("serializeGradient", () => {
+  it("serializes default gradient models", () => {
+    expect(serializeGradient(buildDefaultGradientModel("rgba(60, 230, 172, 0.18)"))).toBe(
+      "linear-gradient(135deg, rgba(60, 230, 172, 0.18) 0%, rgba(255, 255, 255, 0.04) 100%)",
+    );
+  });
+
+  it("round-trips parsed gradients", () => {
+    const parsed = parseGradient(
+      "repeating-conic-gradient(from 90deg at 25% 75%, rgba(0, 0, 0, 0.5) 0%, rgba(255, 255, 255, 0.1) 100%)",
+    );
+    expect(parsed).not.toBeNull();
+    expect(serializeGradient(parsed!)).toBe(
+      "repeating-conic-gradient(from 90deg at 25% 75%, rgba(0, 0, 0, 0.5) 0%, rgba(255, 255, 255, 0.1) 100%)",
+    );
+  });
+});
+
+describe("insertGradientStop", () => {
+  it("inserts a stop at the clicked position with an interpolated color", () => {
+    const parsed = parseGradient("linear-gradient(90deg, #000000 0%, #ffffff 100%)");
+    expect(parsed).not.toBeNull();
+
+    expect(insertGradientStop(parsed!, 25)).toMatchObject({
+      stops: [
+        { color: "#000000", position: 0 },
+        { color: "#404040", position: 25 },
+        { color: "#ffffff", position: 100 },
+      ],
+    });
+  });
+});
diff --git a/packages/studio/src/components/editor/gradientValue.ts b/packages/studio/src/components/editor/gradientValue.ts
new file mode 100644
index 000000000..a8983f5f9
--- /dev/null
+++ b/packages/studio/src/components/editor/gradientValue.ts
@@ -0,0 +1,445 @@
+export type GradientKind = "linear" | "radial" | "conic";
+
+export type RadialSizeKeyword =
+  | "closest-side"
+  | "closest-corner"
+  | "farthest-side"
+  | "farthest-corner";
+
+export interface GradientStop {
+  color: string;
+  position: number;
+}
+
+export interface GradientModel {
+  kind: GradientKind;
+  repeating: boolean;
+  angle: number;
+  centerX: number;
+  centerY: number;
+  shape: "circle" | "ellipse";
+  radialSize: RadialSizeKeyword;
+  stops: GradientStop[];
+}
+
+const RADIAL_SIZE_KEYWORDS: RadialSizeKeyword[] = [
+  "closest-side",
+  "closest-corner",
+  "farthest-side",
+  "farthest-corner",
+];
+
+function isWhitespace(char: string | undefined): boolean {
+  return char === " " || char === "\n" || char === "\r" || char === "\t" || char === "\f";
+}
+
+function isDigit(char: string | undefined): boolean {
+  return char != null && char >= "0" && char <= "9";
+}
+
+function isSimpleNumber(value: string): boolean {
+  if (!value) return false;
+  let index = value[0] === "-" ? 1 : 0;
+  let digits = 0;
+
+  while (isDigit(value[index])) {
+    index += 1;
+    digits += 1;
+  }
+
+  if (value[index] === ".") {
+    index += 1;
+    while (isDigit(value[index])) {
+      index += 1;
+      digits += 1;
+    }
+  }
+
+  return digits > 0 && index === value.length;
+}
+
+function parseCssNumber(value: string | undefined): number | null {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (!isSimpleNumber(trimmed)) return null;
+  const parsed = Number(trimmed);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function splitCssWhitespace(value: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+
+  for (const char of value) {
+    if (isWhitespace(char)) {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += char;
+  }
+
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+function hasCssWord(value: string, word: string): boolean {
+  return splitCssWhitespace(value.toLowerCase()).includes(word);
+}
+
+function parsePercentToken(value: string | undefined, fallback: number): number {
+  if (!value?.endsWith("%")) return fallback;
+  const parsed = parseCssNumber(value.slice(0, -1));
+  return parsed == null ? fallback : clamp(parsed, 0, 100);
+}
+
+function parseAngleToken(value: string | undefined): number | null {
+  const trimmed = value?.trim().toLowerCase();
+  if (!trimmed?.endsWith("deg")) return null;
+  return parseCssNumber(trimmed.slice(0, -3));
+}
+
+function trailingPercentStart(value: string): number | null {
+  if (!value.endsWith("%")) return null;
+  const withoutUnit = value.slice(0, -1).trimEnd();
+  let start = withoutUnit.length;
+
+  while (start > 0 && (isDigit(withoutUnit[start - 1]) || withoutUnit[start - 1] === ".")) {
+    start -= 1;
+  }
+
+  if (start > 0 && withoutUnit[start - 1] === "-") {
+    start -= 1;
+  }
+
+  const token = withoutUnit.slice(start);
+  if (!isSimpleNumber(token)) return null;
+  if (start === 0 || !isWhitespace(withoutUnit[start - 1])) return null;
+  return start;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+function round(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+function parsePercent(value: string | undefined, fallback: number): number {
+  const parsed = parseCssNumber(value);
+  return parsed == null ? fallback : clamp(parsed, 0, 100);
+}
+
+function parseColorStop(raw: string): { color: string; position: number | null } {
+  const trimmed = raw.trim();
+  const percentStart = trailingPercentStart(trimmed);
+  if (percentStart == null) return { color: trimmed, position: null };
+
+  const withoutUnit = trimmed.slice(0, -1).trimEnd();
+  return {
+    color: withoutUnit.slice(0, percentStart).trim(),
+    position: parsePercent(withoutUnit.slice(percentStart), 0),
+  };
+}
+
+function normalizeStops(stops: Array<{ color: string; position: number | null }>): GradientStop[] {
+  if (stops.length === 0) {
+    return [
+      { color: "rgba(60, 230, 172, 0.18)", position: 0 },
+      { color: "rgba(255, 255, 255, 0.04)", position: 100 },
+    ];
+  }
+
+  if (stops.length === 1) {
+    return [
+      { color: stops[0].color, position: 0 },
+      { color: stops[0].color, position: 100 },
+    ];
+  }
+
+  const result = stops.map((stop, index) => ({
+    color: stop.color,
+    position: stop.position ?? (index / (stops.length - 1)) * 100,
+  }));
+
+  return result.map((stop) => ({
+    color: stop.color,
+    position: round(clamp(stop.position, 0, 100)),
+  }));
+}
+
+function splitGradientArgs(value: string): string[] {
+  const parts: string[] = [];
+  let current = "";
+  let depth = 0;
+
+  for (const char of value) {
+    if (char === "(") depth += 1;
+    if (char === ")") depth = Math.max(0, depth - 1);
+
+    if (char === "," && depth === 0) {
+      if (current.trim()) parts.push(current.trim());
+      current = "";
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (current.trim()) parts.push(current.trim());
+  return parts;
+}
+
+function directionToAngle(value: string): number | null {
+  const normalized = value.trim().toLowerCase();
+  const map: Record<string, number> = {
+    "to top": 0,
+    "to top right": 45,
+    "to right top": 45,
+    "to right": 90,
+    "to bottom right": 135,
+    "to right bottom": 135,
+    "to bottom": 180,
+    "to bottom left": 225,
+    "to left bottom": 225,
+    "to left": 270,
+    "to top left": 315,
+    "to left top": 315,
+  };
+  return normalized in map ? map[normalized] : null;
+}
+
+function parseLinearArgs(parts: string[]): GradientModel {
+  const first = parts[0] ?? "";
+  const angleFromDirection = directionToAngle(first);
+  const parsedAngle = parseAngleToken(first);
+  const firstIsAngle = parsedAngle != null;
+  const angle = parsedAngle ?? angleFromDirection ?? 180;
+  const stopParts = firstIsAngle || angleFromDirection != null ? parts.slice(1) : parts;
+
+  return {
+    kind: "linear",
+    repeating: false,
+    angle,
+    centerX: 50,
+    centerY: 50,
+    shape: "ellipse",
+    radialSize: "farthest-corner",
+    stops: normalizeStops(stopParts.map(parseColorStop)),
+  };
+}
+
+function parseRadialArgs(parts: string[]): GradientModel {
+  const first = parts[0] ?? "";
+  const firstLower = first.toLowerCase();
+  const hasConfig =
+    hasCssWord(firstLower, "at") ||
+    hasCssWord(firstLower, "circle") ||
+    hasCssWord(firstLower, "ellipse") ||
+    firstLower.includes("closest-") ||
+    firstLower.includes("farthest-");
+  const config = hasConfig ? first : "";
+  const stopParts = hasConfig ? parts.slice(1) : parts;
+  const configLower = config.toLowerCase();
+  const configTokens = splitCssWhitespace(configLower);
+  const atIndex = configTokens.indexOf("at");
+
+  const shape = hasCssWord(configLower, "circle") ? "circle" : "ellipse";
+  const radialSize =
+    RADIAL_SIZE_KEYWORDS.find((keyword) => configTokens.includes(keyword)) ?? "farthest-corner";
+
+  return {
+    kind: "radial",
+    repeating: false,
+    angle: 180,
+    centerX: parsePercentToken(configTokens[atIndex + 1], 50),
+    centerY: parsePercentToken(configTokens[atIndex + 2], 50),
+    shape,
+    radialSize,
+    stops: normalizeStops(stopParts.map(parseColorStop)),
+  };
+}
+
+function parseConicArgs(parts: string[]): GradientModel {
+  const first = parts[0] ?? "";
+  const firstLower = first.toLowerCase();
+  const hasConfig = hasCssWord(firstLower, "from") || hasCssWord(firstLower, "at");
+  const config = hasConfig ? first : "";
+  const stopParts = hasConfig ? parts.slice(1) : parts;
+  const configTokens = splitCssWhitespace(config.toLowerCase());
+  const fromIndex = configTokens.indexOf("from");
+  const atIndex = configTokens.indexOf("at");
+  const angle = parseAngleToken(configTokens[fromIndex + 1]);
+
+  return {
+    kind: "conic",
+    repeating: false,
+    angle: angle ?? 0,
+    centerX: parsePercentToken(configTokens[atIndex + 1], 50),
+    centerY: parsePercentToken(configTokens[atIndex + 2], 50),
+    shape: "ellipse",
+    radialSize: "farthest-corner",
+    stops: normalizeStops(stopParts.map(parseColorStop)),
+  };
+}
+
+export function buildDefaultGradientModel(fallbackColor?: string): GradientModel {
+  return {
+    kind: "linear",
+    repeating: false,
+    angle: 135,
+    centerX: 50,
+    centerY: 50,
+    shape: "ellipse",
+    radialSize: "farthest-corner",
+    stops: normalizeStops([
+      {
+        color:
+          fallbackColor && fallbackColor !== "transparent"
+            ? fallbackColor
+            : "rgba(60, 230, 172, 0.18)",
+        position: 0,
+      },
+      { color: "rgba(255, 255, 255, 0.04)", position: 100 },
+    ]),
+  };
+}
+
+export function parseGradient(value: string | undefined): GradientModel | null {
+  if (!value || value === "none") return null;
+  const trimmed = value.trim();
+  const openParenIndex = trimmed.indexOf("(");
+  if (openParenIndex <= 0 || !trimmed.endsWith(")")) return null;
+
+  const functionName = trimmed.slice(0, openParenIndex).toLowerCase();
+  const kindByFunctionName: Record<string, { kind: GradientKind; repeating: boolean }> = {
+    "linear-gradient": { kind: "linear", repeating: false },
+    "radial-gradient": { kind: "radial", repeating: false },
+    "conic-gradient": { kind: "conic", repeating: false },
+    "repeating-linear-gradient": { kind: "linear", repeating: true },
+    "repeating-radial-gradient": { kind: "radial", repeating: true },
+    "repeating-conic-gradient": { kind: "conic", repeating: true },
+  };
+  const parsedFunction = kindByFunctionName[functionName];
+  if (!parsedFunction) return null;
+
+  const { kind, repeating } = parsedFunction;
+  const parts = splitGradientArgs(trimmed.slice(openParenIndex + 1, -1));
+
+  const parsed =
+    kind === "linear"
+      ? parseLinearArgs(parts)
+      : kind === "radial"
+        ? parseRadialArgs(parts)
+        : parseConicArgs(parts);
+
+  return { ...parsed, repeating };
+}
+
+function formatStop(stop: GradientStop): string {
+  return `${stop.color} ${round(stop.position)}%`;
+}
+
+export function serializeGradient(model: GradientModel): string {
+  const fn = `${model.repeating ? "repeating-" : ""}${model.kind}-gradient`;
+  const stops = model.stops.map(formatStop).join(", ");
+
+  if (model.kind === "linear") {
+    return `${fn}(${round(model.angle)}deg, ${stops})`;
+  }
+
+  if (model.kind === "radial") {
+    return `${fn}(${model.shape} ${model.radialSize} at ${round(model.centerX)}% ${round(
+      model.centerY,
+    )}%, ${stops})`;
+  }
+
+  return `${fn}(from ${round(model.angle)}deg at ${round(model.centerX)}% ${round(
+    model.centerY,
+  )}%, ${stops})`;
+}
+
+function blendChannel(start: number, end: number, ratio: number): number {
+  return Math.round(start + (end - start) * ratio);
+}
+
+function formatHex(channel: number): string {
+  return channel.toString(16).padStart(2, "0");
+}
+
+export function interpolateGradientStopColor(model: GradientModel, position: number): string {
+  const clampedPosition = clamp(position, 0, 100);
+  const sortedStops = [...model.stops].sort((a, b) => a.position - b.position);
+  const exact = sortedStops.find((stop) => Math.abs(stop.position - clampedPosition) < 0.001);
+  if (exact) return exact.color;
+
+  const right = sortedStops.find((stop) => stop.position > clampedPosition) ?? sortedStops.at(-1);
+  const left =
+    [...sortedStops].reverse().find((stop) => stop.position < clampedPosition) ?? sortedStops[0];
+  if (!left || !right) return sortedStops[0]?.color ?? "rgba(255, 255, 255, 1)";
+  if (left === right) return left.color;
+
+  const leftColor = left.color;
+  const rightColor = right.color;
+  const leftParsed = leftColor ? parseColorString(leftColor) : null;
+  const rightParsed = rightColor ? parseColorString(rightColor) : null;
+  if (!leftParsed || !rightParsed) return left.color;
+
+  const ratio = (clampedPosition - left.position) / Math.max(1, right.position - left.position);
+  const red = blendChannel(leftParsed.red, rightParsed.red, ratio);
+  const green = blendChannel(leftParsed.green, rightParsed.green, ratio);
+  const blue = blendChannel(leftParsed.blue, rightParsed.blue, ratio);
+  const alpha = round(leftParsed.alpha + (rightParsed.alpha - leftParsed.alpha) * ratio);
+
+  if (alpha >= 1) {
+    return `#${formatHex(red)}${formatHex(green)}${formatHex(blue)}`.toUpperCase();
+  }
+
+  return `rgba(${red}, ${green}, ${blue}, ${alpha})`;
+}
+
+export function insertGradientStop(model: GradientModel, position: number): GradientModel {
+  const clampedPosition = round(clamp(position, 0, 100));
+  const color = interpolateGradientStopColor(model, clampedPosition);
+  const nextStops = [...model.stops, { color, position: clampedPosition }].sort(
+    (a, b) => a.position - b.position,
+  );
+  return {
+    ...model,
+    stops: nextStops,
+  };
+}
+
+function parseColorString(
+  value: string,
+): { red: number; green: number; blue: number; alpha: number } | null {
+  const trimmed = value.trim().toLowerCase();
+  if (trimmed === "transparent") {
+    return { red: 0, green: 0, blue: 0, alpha: 0 };
+  }
+
+  const hex = trimmed.match(/^#([0-9a-f]{6})$/i);
+  if (hex) {
+    return {
+      red: Number.parseInt(hex[1].slice(0, 2), 16),
+      green: Number.parseInt(hex[1].slice(2, 4), 16),
+      blue: Number.parseInt(hex[1].slice(4, 6), 16),
+      alpha: 1,
+    };
+  }
+
+  const rgba = trimmed.match(
+    /^rgba?\(\s*([0-9.]+)\s*,\s*([0-9.]+)\s*,\s*([0-9.]+)(?:\s*,\s*([0-9.]+))?\s*\)$/i,
+  );
+  if (!rgba) return null;
+
+  return {
+    red: Number.parseFloat(rgba[1]),
+    green: Number.parseFloat(rgba[2]),
+    blue: Number.parseFloat(rgba[3]),
+    alpha: rgba[4] != null ? Number.parseFloat(rgba[4]) : 1,
+  };
+}
diff --git a/packages/studio/src/components/editor/motionEditing.test.ts b/packages/studio/src/components/editor/motionEditing.test.ts
new file mode 100644
index 000000000..34129d39f
--- /dev/null
+++ b/packages/studio/src/components/editor/motionEditing.test.ts
@@ -0,0 +1,514 @@
+import { describe, expect, it } from "vitest";
+import { Window } from "happy-dom";
+import {
+  buildMotionAgentContext,
+  buildMotionCurveModel,
+  buildDomEditMotionPatchOperations,
+  buildDomEditMotionPatchOperation,
+  buildMotionVarsAttribute,
+  buildMotionVarsId,
+  clampMotionDraftToTimeline,
+  detectMotionOwnership,
+  formatMotionBezierEase,
+  MOTION_EASE_OPTIONS,
+  parseMotionDraft,
+  parseMotionBezierEase,
+  parseMotionVarsAttribute,
+  sampleMotionEase,
+  serializeMotionVarsAttribute,
+  serializeMotionDraft,
+  type MotionDraft,
+} from "./motionEditing";
+
+describe("motionEditing", () => {
+  it("serializes the default fade-up preset into the data-hf-motion contract", () => {
+    const draft: MotionDraft = {
+      preset: "fade-up",
+      direction: "up",
+      start: 0,
+      duration: 0.6,
+      ease: "outCubic",
+      distance: 32,
+    };
+
+    expect(serializeMotionDraft(draft)).toBe(
+      "v=1;preset=fade-up;start=0;duration=0.6;ease=outCubic;x=0;y=32;opacity=0:1;scale=1:1",
+    );
+  });
+
+  it("serializes custom two-keyframe tracks into the data-hf-motion contract", () => {
+    const draft: MotionDraft = {
+      preset: "fade-up",
+      direction: "up",
+      start: 0.1,
+      duration: 1.2,
+      ease: "inOutCubic",
+      distance: 32,
+      keyframes: {
+        x: { from: -24, to: 12 },
+        y: { from: 48, to: 4 },
+        opacity: { from: 0.25, to: 0.9 },
+        scale: { from: 0.8, to: 1.1 },
+      },
+    };
+
+    expect(serializeMotionDraft(draft)).toBe(
+      "v=1;preset=fade-up;start=0.1;duration=1.2;ease=inOutCubic;x=-24:12;y=48:4;opacity=0.25:0.9;scale=0.8:1.1",
+    );
+  });
+
+  it("serializes and parses custom cubic-bezier easing", () => {
+    const draft: MotionDraft = {
+      preset: "fade-up",
+      direction: "up",
+      start: 0,
+      duration: 0.6,
+      ease: "bezier(0.2,1.25,0.4,1)",
+      distance: 32,
+    };
+
+    expect(serializeMotionDraft(draft)).toContain("ease=bezier(0.2,1.25,0.4,1)");
+    expect(parseMotionDraft(serializeMotionDraft(draft))?.ease).toBe("bezier(0.2,1.25,0.4,1)");
+    expect(parseMotionBezierEase("cubic-bezier(0.2, 1.25, 0.4, 1)")).toEqual({
+      x1: 0.2,
+      y1: 1.25,
+      x2: 0.4,
+      y2: 1,
+    });
+  });
+
+  it("exposes a broad deterministic easing catalog", () => {
+    expect(MOTION_EASE_OPTIONS.map((option) => option.value)).toEqual(
+      expect.arrayContaining([
+        "linear",
+        "ease",
+        "outSine",
+        "inOutQuad",
+        "outCubic",
+        "inOutQuart",
+        "outExpo",
+        "inOutCirc",
+        "outBack",
+        "outBounce",
+        "outElastic",
+      ]),
+    );
+    expect(formatMotionBezierEase({ x1: 0.16, y1: 1, x2: 0.3, y2: 1 })).toBe(
+      "bezier(0.16,1,0.3,1)",
+    );
+    expect(sampleMotionEase("outBack", 0.5)).toBeGreaterThan(1);
+    expect(sampleMotionEase("bezier(0,0,1,1)", 0.5)).toBeCloseTo(0.5, 4);
+  });
+
+  it("serializes slide direction and distance into x/y offsets", () => {
+    const draft: MotionDraft = {
+      preset: "slide",
+      direction: "left",
+      start: 0.25,
+      duration: 0.75,
+      ease: "linear",
+      distance: 48,
+    };
+
+    expect(serializeMotionDraft(draft)).toBe(
+      "v=1;preset=slide;start=0.25;duration=0.75;ease=linear;x=48;y=0;opacity=1:1;scale=1:1",
+    );
+  });
+
+  it("serializes pop as opacity plus scale without travel", () => {
+    const draft: MotionDraft = {
+      preset: "pop",
+      direction: "up",
+      start: 0,
+      duration: 0.4,
+      ease: "outCubic",
+      distance: 32,
+    };
+
+    expect(serializeMotionDraft(draft)).toBe(
+      "v=1;preset=pop;start=0;duration=0.4;ease=outCubic;x=0;y=0;opacity=0:1;scale=0.92:1",
+    );
+  });
+
+  it("clamps motion timing to the timeline duration", () => {
+    const draft: MotionDraft = {
+      preset: "fade-up",
+      direction: "up",
+      start: 5,
+      duration: 16.05,
+      ease: "outCubic",
+      distance: 32,
+      keyframes: {
+        x: { from: 0, to: 0 },
+        y: { from: 44, to: 0 },
+        opacity: { from: 0, to: 1 },
+        scale: { from: 1, to: 1 },
+      },
+    };
+
+    expect(clampMotionDraftToTimeline(draft, 3)).toEqual({
+      ...draft,
+      start: 2.95,
+      duration: 0.05,
+    });
+  });
+
+  it("clamps duration against the remaining timeline window", () => {
+    expect(
+      clampMotionDraftToTimeline(
+        {
+          preset: "slide",
+          direction: "right",
+          start: 2.2,
+          duration: 2,
+          ease: "linear",
+          distance: 24,
+        },
+        3,
+      ),
+    ).toMatchObject({
+      start: 2.2,
+      duration: 0.8,
+    });
+  });
+
+  it("parses authored motion back into editable controls", () => {
+    expect(
+      parseMotionDraft(
+        "v=1;preset=fade-up;start=0.15;duration=0.8;ease=inOutCubic;x=0;y=40;opacity=0:1;scale=1:1",
+      ),
+    ).toEqual({
+      preset: "fade-up",
+      direction: "up",
+      start: 0.15,
+      duration: 0.8,
+      ease: "inOutCubic",
+      distance: 40,
+      keyframes: {
+        x: { from: 0, to: 0 },
+        y: { from: 40, to: 0 },
+        opacity: { from: 0, to: 1 },
+        scale: { from: 1, to: 1 },
+      },
+    });
+  });
+
+  it("parses custom two-keyframe tracks back into editable controls", () => {
+    expect(
+      parseMotionDraft(
+        "v=1;preset=slide;start=0.25;duration=0.75;ease=linear;x=-20:10;y=4:-4;opacity=0.2:1;scale=0.75:1.25",
+      ),
+    ).toEqual({
+      preset: "slide",
+      direction: "right",
+      start: 0.25,
+      duration: 0.75,
+      ease: "linear",
+      distance: 20,
+      keyframes: {
+        x: { from: -20, to: 10 },
+        y: { from: 4, to: -4 },
+        opacity: { from: 0.2, to: 1 },
+        scale: { from: 0.75, to: 1.25 },
+      },
+    });
+  });
+
+  it("builds set and clear patch operations", () => {
+    const draft: MotionDraft = {
+      preset: "fade-up",
+      direction: "up",
+      start: 0,
+      duration: 0.6,
+      ease: "outCubic",
+      distance: 32,
+    };
+
+    expect(buildDomEditMotionPatchOperation(draft)).toEqual({
+      type: "attribute",
+      property: "hf-motion",
+      value: "v=1;preset=fade-up;start=0;duration=0.6;ease=outCubic;x=0;y=32;opacity=0:1;scale=1:1",
+    });
+    expect(buildDomEditMotionPatchOperation(null)).toEqual({
+      type: "attribute",
+      property: "hf-motion",
+      value: null,
+    });
+    expect(buildDomEditMotionPatchOperations(draft, "headline")).toEqual([
+      {
+        type: "attribute",
+        property: "hf-motion",
+        value:
+          "v=1;preset=fade-up;start=0;duration=0.6;ease=outCubic;x=0;y=32;opacity=0:1;scale=1:1",
+      },
+      {
+        type: "attribute",
+        property: "hf-motion-vars",
+        value: "v=1;id=headline;lanes=x,y,scale,rotate,opacity;owner=hf;driver=hf",
+      },
+    ]);
+    expect(buildDomEditMotionPatchOperations(null, "headline")).toEqual([
+      { type: "attribute", property: "hf-motion", value: null },
+      { type: "attribute", property: "hf-motion-vars", value: null },
+    ]);
+  });
+
+  it("serializes and parses canonical motion variable lanes", () => {
+    expect(buildMotionVarsId("#Hero Title")).toBe("hero-title");
+    expect(buildMotionVarsAttribute("hero-title")).toBe(
+      "v=1;id=hero-title;lanes=x,y,scale,rotate,opacity;owner=hf;driver=hf",
+    );
+    expect(
+      parseMotionVarsAttribute(
+        "v=1;id=hero-title;lanes=x,y,scale,rotate,opacity;owner=hf;driver=hf",
+      ),
+    ).toEqual({
+      version: 1,
+      id: "hero-title",
+      lanes: ["x", "y", "scale", "rotate", "opacity"],
+      owner: "hf",
+      driver: "hf",
+    });
+    expect(parseMotionVarsAttribute("v=1;id=hero;lanes=x,bad;owner=hf;driver=hf")).toBeNull();
+  });
+
+  it("serializes external runtime variable lanes through the shared contract", () => {
+    const serialized = serializeMotionVarsAttribute({
+      version: 1,
+      id: "#Hero Title",
+      lanes: ["x", "opacity"],
+      owner: "gsap",
+      driver: "runtime",
+    });
+
+    expect(serialized).toBe("v=1;id=hero-title;lanes=x,opacity;owner=gsap;driver=runtime");
+    expect(parseMotionVarsAttribute(serialized)).toEqual({
+      version: 1,
+      id: "hero-title",
+      lanes: ["x", "opacity"],
+      owner: "gsap",
+      driver: "runtime",
+    });
+  });
+
+  it("maps fade-up into curve tracks with start and end markers", () => {
+    const model = buildMotionCurveModel({
+      preset: "fade-up",
+      direction: "up",
+      start: 0.25,
+      duration: 0.75,
+      ease: "outCubic",
+      distance: 40,
+    });
+
+    expect(model.windowEnd).toBe(1);
+    expect(model.markers).toEqual([
+      { label: "Start", time: 0.25, percent: 25 },
+      { label: "End", time: 1, percent: 100 },
+    ]);
+    expect(model.tracks).toMatchObject([
+      { key: "x", from: 0, to: 0, unit: "px", active: false },
+      { key: "y", from: 40, to: 0, unit: "px", active: true },
+      { key: "opacity", from: 0, to: 1, unit: "", active: true },
+      { key: "scale", from: 1, to: 1, unit: "", active: false },
+    ]);
+  });
+
+  it("maps pop into opacity and scale curve tracks", () => {
+    const model = buildMotionCurveModel({
+      preset: "pop",
+      direction: "left",
+      start: 0,
+      duration: 0.4,
+      ease: "outCubic",
+      distance: 80,
+    });
+
+    expect(model.tracks.map((track) => [track.key, track.from, track.to, track.active])).toEqual([
+      ["x", 0, 0, false],
+      ["y", 0, 0, false],
+      ["opacity", 0, 1, true],
+      ["scale", 0.92, 1, true],
+    ]);
+  });
+
+  it("maps custom keyframes into editable curve tracks", () => {
+    const model = buildMotionCurveModel({
+      preset: "fade-up",
+      direction: "up",
+      start: 0,
+      duration: 1,
+      ease: "linear",
+      distance: 32,
+      keyframes: {
+        x: { from: -8, to: 16 },
+        y: { from: 24, to: 0 },
+        opacity: { from: 0.25, to: 1 },
+        scale: { from: 0.9, to: 1.05 },
+      },
+    });
+
+    expect(model.tracks.map((track) => [track.key, track.from, track.to, track.active])).toEqual([
+      ["x", -8, 16, true],
+      ["y", 24, 0, true],
+      ["opacity", 0.25, 1, true],
+      ["scale", 0.9, 1.05, true],
+    ]);
+  });
+
+  it("detects editable HyperFrames motion ownership", () => {
+    const window = new Window();
+    const element = window.document.createElement("div");
+    element.setAttribute("data-hf-motion", "v=1;preset=fade-up");
+    window.document.body.appendChild(element);
+
+    expect(
+      detectMotionOwnership({
+        element: element as HTMLElement,
+        dataAttributes: { "hf-motion": "v=1;preset=fade-up" },
+        computedStyles: {},
+      }),
+    ).toMatchObject({
+      state: "editable",
+      badges: [{ kind: "hf-motion", label: "HF Motion", state: "Editable" }],
+    });
+  });
+
+  it("detects variable-owned HyperFrames motion as editable", () => {
+    const window = new Window();
+    const element = window.document.createElement("div");
+    element.setAttribute("data-hf-motion-vars", buildMotionVarsAttribute("headline"));
+    window.document.body.appendChild(element);
+
+    const report = detectMotionOwnership({
+      element: element as HTMLElement,
+      dataAttributes: { "hf-motion-vars": buildMotionVarsAttribute("headline") },
+      computedStyles: {},
+    });
+
+    expect(report.state).toBe("editable");
+    expect(report.badges).toContainEqual(
+      expect.objectContaining({
+        kind: "hf-motion",
+        label: "HF Motion Vars",
+        state: "Editable",
+      }),
+    );
+  });
+
+  it("detects external canonical variable lanes without exposing unsafe editing", () => {
+    const window = new Window();
+    const element = window.document.createElement("div");
+    element.setAttribute(
+      "data-hf-motion-vars",
+      "v=1;id=headline;lanes=x,y,scale,rotate,opacity;owner=gsap;driver=runtime",
+    );
+    window.document.body.appendChild(element);
+
+    const report = detectMotionOwnership({
+      element: element as HTMLElement,
+      dataAttributes: {
+        "hf-motion-vars":
+          "v=1;id=headline;lanes=x,y,scale,rotate,opacity;owner=gsap;driver=runtime",
+      },
+      computedStyles: {},
+    });
+
+    expect(report).toMatchObject({
+      state: "detected",
+      editable: false,
+      badges: [{ kind: "gsap", label: "GSAP Vars", state: "Detected", editable: false }],
+    });
+  });
+
+  it("detects read-only external runtime ownership and mixed ownership", () => {
+    const window = new Window();
+    const element = window.document.createElement("div") as HTMLElement;
+    window.document.body.appendChild(element);
+    Object.defineProperty(element, "getAnimations", {
+      value: () => [{ constructor: { name: "Animation" } }],
+    });
+    Object.assign(window, {
+      __timelines: {
+        main: {
+          getChildren: () => [{ targets: () => [element] }],
+        },
+      },
+      __hfAnime: [{ animatables: [{ target: element }] }],
+    });
+
+    const report = detectMotionOwnership({
+      element,
+      dataAttributes: {},
+      computedStyles: {
+        "animation-name": "pulse",
+        "animation-duration": "1s",
+      },
+    });
+
+    expect(report.state).toBe("mixed");
+    expect(report.badges.map((badge) => badge.label)).toEqual([
+      "CSS",
+      "WAAPI",
+      "GSAP",
+      "anime.js",
+      "Mixed",
+    ]);
+    expect(report.badges.filter((badge) => badge.state === "Editable")).toHaveLength(0);
+  });
+
+  it("detects Three ownership for time-driven canvases", () => {
+    const window = new Window();
+    const canvas = window.document.createElement("canvas") as HTMLElement;
+    window.document.body.appendChild(canvas);
+    Object.assign(window, { __hfThreeTime: 0 });
+
+    expect(
+      detectMotionOwnership({
+        element: canvas,
+        dataAttributes: {},
+        computedStyles: {},
+      }).badges,
+    ).toMatchObject([{ kind: "three", label: "Three", state: "Detected" }]);
+  });
+
+  it("builds motion-aware agent context with curve and runtime guardrails", () => {
+    const ownership = detectMotionOwnership({
+      dataAttributes: { "hf-motion": "v=1;preset=fade-up" },
+      computedStyles: {
+        "animation-name": "pulse",
+        "animation-duration": "1s",
+      },
+    });
+
+    const context = buildMotionAgentContext({
+      hfMotionAttribute:
+        "v=1;preset=fade-up;start=0;duration=0.6;ease=outCubic;x=0;y=32;opacity=0:1;scale=1:1",
+      draft: parseMotionDraft(
+        "v=1;preset=fade-up;start=0;duration=0.6;ease=outCubic;x=0;y=32;opacity=0:1;scale=1:1",
+      ),
+      ownership,
+    });
+
+    expect(context.version).toBe(1);
+    expect(context.owners.map((owner) => `${owner.label}:${owner.state}`)).toEqual([
+      "HF Motion:Editable",
+      "CSS:Detected",
+      "Mixed:Mixed",
+    ]);
+    expect(context.curveTracks).toContainEqual({
+      key: "y",
+      label: "Y",
+      from: 32,
+      to: 0,
+      unit: "px",
+      active: true,
+    });
+    expect(
+      context.instructions.some((item) => item.includes("Patch the existing runtime library")),
+    ).toBe(true);
+    expect(context.instructions.some((item) => item.includes("Use an outer layout wrapper"))).toBe(
+      true,
+    );
+  });
+});
diff --git a/packages/studio/src/components/editor/motionEditing.ts b/packages/studio/src/components/editor/motionEditing.ts
new file mode 100644
index 000000000..34f3950d2
--- /dev/null
+++ b/packages/studio/src/components/editor/motionEditing.ts
@@ -0,0 +1,1240 @@
+import type { PatchOperation } from "../../utils/sourcePatcher";
+
+export type MotionPreset = "fade-up" | "slide" | "pop";
+export type MotionDirection = "up" | "down" | "left" | "right";
+export type MotionEasePreset =
+  | "linear"
+  | "ease"
+  | "inSine"
+  | "outSine"
+  | "inOutSine"
+  | "inQuad"
+  | "outQuad"
+  | "inOutQuad"
+  | "inCubic"
+  | "outCubic"
+  | "inOutCubic"
+  | "inQuart"
+  | "outQuart"
+  | "inOutQuart"
+  | "inQuint"
+  | "outQuint"
+  | "inOutQuint"
+  | "inExpo"
+  | "outExpo"
+  | "inOutExpo"
+  | "inCirc"
+  | "outCirc"
+  | "inOutCirc"
+  | "inBack"
+  | "outBack"
+  | "inOutBack"
+  | "inBounce"
+  | "outBounce"
+  | "inOutBounce"
+  | "inElastic"
+  | "outElastic"
+  | "inOutElastic";
+export type MotionEase = MotionEasePreset | `bezier(${string})`;
+export type MotionCurveTrackKey = "x" | "y" | "opacity" | "scale";
+export type MotionVariableLane = "x" | "y" | "scale" | "rotate" | "opacity";
+export type MotionVariableOwner = "hf" | "gsap" | "anime" | "css" | "waapi";
+export type MotionVariableDriver = "hf" | "runtime";
+export type MotionOwnershipKind =
+  | "hf-motion"
+  | "css"
+  | "waapi"
+  | "gsap"
+  | "animejs"
+  | "three"
+  | "mixed"
+  | "unsafe";
+export type MotionOwnershipState = "Editable" | "Detected" | "Mixed" | "Unsafe";
+
+export interface MotionKeyframeRange {
+  from: number;
+  to: number;
+}
+
+export interface MotionKeyframes {
+  x: MotionKeyframeRange;
+  y: MotionKeyframeRange;
+  opacity: MotionKeyframeRange;
+  scale: MotionKeyframeRange;
+}
+
+export interface MotionDraft {
+  preset: MotionPreset;
+  direction: MotionDirection;
+  start: number;
+  duration: number;
+  ease: MotionEase;
+  distance: number;
+  keyframes?: MotionKeyframes;
+}
+
+export interface MotionCurveMarker {
+  label: string;
+  time: number;
+  percent: number;
+}
+
+export interface MotionCurveTrack {
+  key: MotionCurveTrackKey;
+  label: string;
+  from: number;
+  to: number;
+  unit: "px" | "";
+  active: boolean;
+  points: Array<{ percent: number; value: number }>;
+}
+
+export interface MotionCurveModel {
+  start: number;
+  duration: number;
+  end: number;
+  windowEnd: number;
+  ease: MotionEase;
+  markers: MotionCurveMarker[];
+  tracks: MotionCurveTrack[];
+}
+
+export interface MotionOwnershipBadge {
+  kind: MotionOwnershipKind;
+  label: string;
+  state: MotionOwnershipState;
+  editable: boolean;
+  description: string;
+}
+
+export interface MotionOwnershipReport {
+  state: "none" | "editable" | "detected" | "mixed" | "unsafe";
+  badges: MotionOwnershipBadge[];
+  editable: boolean;
+  summary: string;
+}
+
+export interface MotionOwnershipInput {
+  element?: HTMLElement | null;
+  dataAttributes?: Record<string, string>;
+  computedStyles?: Record<string, string>;
+}
+
+export interface MotionAgentOwner {
+  label: string;
+  state: MotionOwnershipState;
+  editable: boolean;
+}
+
+export interface MotionAgentCurveTrack {
+  key: MotionCurveTrackKey;
+  label: string;
+  from: number;
+  to: number;
+  unit: "px" | "";
+  active: boolean;
+}
+
+export interface MotionAgentContext {
+  version: 1;
+  state: MotionOwnershipReport["state"];
+  summary: string;
+  hfMotionAttribute?: string;
+  owners: MotionAgentOwner[];
+  curveTracks: MotionAgentCurveTrack[];
+  instructions: string[];
+}
+
+export interface MotionEaseOption {
+  label: string;
+  value: MotionEasePreset;
+  group: "Basic" | "Sine" | "Quad" | "Cubic" | "Quart" | "Quint" | "Expo" | "Circ" | "Back" | "FX";
+}
+
+export interface MotionBezierEase {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+}
+
+export interface MotionVarsConfig {
+  version: 1;
+  id: string;
+  lanes: MotionVariableLane[];
+  owner: MotionVariableOwner;
+  driver: MotionVariableDriver;
+}
+
+export type MotionEditConfidence = "safe" | "needs-import" | "read-only" | "unsafe";
+
+export interface MotionVariableLanePatch {
+  lane: MotionVariableLane;
+  keyframes: MotionKeyframeRange;
+}
+
+export interface MotionVariableSourcePatch {
+  confidence: "safe";
+  operations: PatchOperation[];
+}
+
+export interface MotionVariableAdapterEditContract<TTarget = unknown> {
+  detect: (target: TTarget) => MotionOwnershipReport;
+  canImport: (target: TTarget) => MotionEditConfidence;
+  importToVariableLanes: (target: TTarget) => MotionVariableSourcePatch | null;
+  canPatch: (target: TTarget) => MotionEditConfidence;
+  patchVariableLane: (
+    target: TTarget,
+    lane: MotionVariableLane,
+    keyframes: MotionKeyframeRange,
+  ) => MotionVariableSourcePatch | null;
+}
+
+const MOTION_VERSION = 1;
+const DEFAULT_START = 0;
+const DEFAULT_DISTANCE = 32;
+const DEFAULT_DURATION = 0.6;
+const MIN_MOTION_DURATION = 0.05;
+const POP_DURATION = 0.4;
+const POP_SCALE_FROM = 0.92;
+const SUPPORTED_PRESETS = new Set<MotionPreset>(["fade-up", "slide", "pop"]);
+const SUPPORTED_DIRECTIONS = new Set<MotionDirection>(["up", "down", "left", "right"]);
+const MOTION_VAR_LANES: MotionVariableLane[] = ["x", "y", "scale", "rotate", "opacity"];
+const SUPPORTED_MOTION_VAR_LANES = new Set<MotionVariableLane>(MOTION_VAR_LANES);
+const SUPPORTED_MOTION_VAR_OWNERS = new Set<MotionVariableOwner>([
+  "hf",
+  "gsap",
+  "anime",
+  "css",
+  "waapi",
+]);
+const SUPPORTED_MOTION_VAR_DRIVERS = new Set<MotionVariableDriver>(["hf", "runtime"]);
+export const DEFAULT_CUSTOM_MOTION_BEZIER: MotionBezierEase = {
+  x1: 0.16,
+  y1: 1,
+  x2: 0.3,
+  y2: 1,
+};
+export const MOTION_EASE_OPTIONS: MotionEaseOption[] = [
+  { label: "Linear", value: "linear", group: "Basic" },
+  { label: "CSS Ease", value: "ease", group: "Basic" },
+  { label: "In Sine", value: "inSine", group: "Sine" },
+  { label: "Out Sine", value: "outSine", group: "Sine" },
+  { label: "In Out Sine", value: "inOutSine", group: "Sine" },
+  { label: "In Quad", value: "inQuad", group: "Quad" },
+  { label: "Out Quad", value: "outQuad", group: "Quad" },
+  { label: "In Out Quad", value: "inOutQuad", group: "Quad" },
+  { label: "In Cubic", value: "inCubic", group: "Cubic" },
+  { label: "Out Cubic", value: "outCubic", group: "Cubic" },
+  { label: "In Out Cubic", value: "inOutCubic", group: "Cubic" },
+  { label: "In Quart", value: "inQuart", group: "Quart" },
+  { label: "Out Quart", value: "outQuart", group: "Quart" },
+  { label: "In Out Quart", value: "inOutQuart", group: "Quart" },
+  { label: "In Quint", value: "inQuint", group: "Quint" },
+  { label: "Out Quint", value: "outQuint", group: "Quint" },
+  { label: "In Out Quint", value: "inOutQuint", group: "Quint" },
+  { label: "In Expo", value: "inExpo", group: "Expo" },
+  { label: "Out Expo", value: "outExpo", group: "Expo" },
+  { label: "In Out Expo", value: "inOutExpo", group: "Expo" },
+  { label: "In Circ", value: "inCirc", group: "Circ" },
+  { label: "Out Circ", value: "outCirc", group: "Circ" },
+  { label: "In Out Circ", value: "inOutCirc", group: "Circ" },
+  { label: "In Back", value: "inBack", group: "Back" },
+  { label: "Out Back", value: "outBack", group: "Back" },
+  { label: "In Out Back", value: "inOutBack", group: "Back" },
+  { label: "In Bounce", value: "inBounce", group: "FX" },
+  { label: "Out Bounce", value: "outBounce", group: "FX" },
+  { label: "In Out Bounce", value: "inOutBounce", group: "FX" },
+  { label: "In Elastic", value: "inElastic", group: "FX" },
+  { label: "Out Elastic", value: "outElastic", group: "FX" },
+  { label: "In Out Elastic", value: "inOutElastic", group: "FX" },
+];
+const SUPPORTED_EASES = new Set<string>(MOTION_EASE_OPTIONS.map((option) => option.value));
+
+interface ParsedMotionAttribute {
+  preset: MotionPreset;
+  start: number;
+  duration: number;
+  ease: MotionEase;
+  keyframes: MotionKeyframes;
+}
+
+export function buildDefaultMotionDraft(
+  preset: MotionPreset = "fade-up",
+  base?: Partial<MotionDraft>,
+): MotionDraft {
+  const draft = {
+    preset,
+    direction: base?.direction && SUPPORTED_DIRECTIONS.has(base.direction) ? base.direction : "up",
+    start: normalizeFiniteNumber(base?.start, DEFAULT_START, 0),
+    duration:
+      preset === "pop"
+        ? normalizeFiniteNumber(base?.duration, POP_DURATION, MIN_MOTION_DURATION)
+        : normalizeFiniteNumber(base?.duration, DEFAULT_DURATION, MIN_MOTION_DURATION),
+    ease: base?.ease ? (normalizeMotionEase(base.ease) ?? "outCubic") : "outCubic",
+    distance: normalizeFiniteNumber(base?.distance, DEFAULT_DISTANCE, 0),
+  };
+
+  if (!base?.keyframes) return draft;
+  return {
+    ...draft,
+    keyframes: normalizeMotionKeyframes(base.keyframes, getPresetKeyframes(draft)),
+  };
+}
+
+export function clampMotionDraftToTimeline(
+  draft: MotionDraft,
+  timelineDuration: number | null | undefined,
+): MotionDraft {
+  const normalized = buildDefaultMotionDraft(draft.preset, draft);
+  if (timelineDuration == null || !Number.isFinite(timelineDuration) || timelineDuration <= 0) {
+    return normalized;
+  }
+
+  const maxTimelineTime = Math.max(MIN_MOTION_DURATION, timelineDuration);
+  const maxStart = Math.max(0, maxTimelineTime - MIN_MOTION_DURATION);
+  const start = roundMotionNumber(Math.min(maxStart, Math.max(0, normalized.start)));
+  const durationMax = Math.max(MIN_MOTION_DURATION, maxTimelineTime - start);
+  const duration = roundMotionNumber(
+    Math.min(durationMax, Math.max(MIN_MOTION_DURATION, normalized.duration)),
+  );
+
+  return {
+    ...normalized,
+    start,
+    duration,
+  };
+}
+
+export function serializeMotionDraft(draft: MotionDraft): string {
+  const normalized = buildDefaultMotionDraft(draft.preset, draft);
+  const keyframes = resolveMotionKeyframes(normalized);
+
+  return [
+    `v=${MOTION_VERSION}`,
+    `preset=${normalized.preset}`,
+    `start=${formatNumber(normalized.start)}`,
+    `duration=${formatNumber(normalized.duration)}`,
+    `ease=${normalized.ease}`,
+    `x=${formatPositionRange(keyframes.x)}`,
+    `y=${formatPositionRange(keyframes.y)}`,
+    `opacity=${formatRange(keyframes.opacity)}`,
+    `scale=${formatRange(keyframes.scale)}`,
+  ].join(";");
+}
+
+export function parseMotionDraft(value: string | null | undefined): MotionDraft | null {
+  const parsed = parseMotionAttribute(value);
+  if (!parsed) return null;
+  const { x, y } = parsed.keyframes;
+  const dominantOffset =
+    Math.max(Math.abs(x.from), Math.abs(x.to)) >= Math.max(Math.abs(y.from), Math.abs(y.to))
+      ? Math.abs(x.from) >= Math.abs(x.to)
+        ? x.from
+        : x.to
+      : Math.abs(y.from) >= Math.abs(y.to)
+        ? y.from
+        : y.to;
+  const direction = resolveDirection(x.from, y.from);
+
+  return buildDefaultMotionDraft(parsed.preset, {
+    direction,
+    start: parsed.start,
+    duration: parsed.duration,
+    ease: parsed.ease,
+    distance: Math.abs(dominantOffset),
+    keyframes: parsed.keyframes,
+  });
+}
+
+export function buildDomEditMotionPatchOperation(draft: MotionDraft | null): PatchOperation {
+  return {
+    type: "attribute",
+    property: "hf-motion",
+    value: draft ? serializeMotionDraft(draft) : null,
+  };
+}
+
+export function buildMotionVarsId(seed: string | null | undefined): string {
+  const normalized = (seed ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/^[.#]+/, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64);
+  return normalized || "layer";
+}
+
+export function buildMotionVarsAttribute(id: string): string {
+  return serializeMotionVarsAttribute({
+    version: 1,
+    id,
+    lanes: MOTION_VAR_LANES,
+    owner: "hf",
+    driver: "hf",
+  });
+}
+
+export function serializeMotionVarsAttribute(config: MotionVarsConfig): string {
+  const id = buildMotionVarsId(config.id);
+  const lanes: MotionVariableLane[] = [];
+  for (const lane of config.lanes) {
+    if (!SUPPORTED_MOTION_VAR_LANES.has(lane)) continue;
+    if (!lanes.includes(lane)) lanes.push(lane);
+  }
+  const owner = SUPPORTED_MOTION_VAR_OWNERS.has(config.owner) ? config.owner : "hf";
+  const driver = SUPPORTED_MOTION_VAR_DRIVERS.has(config.driver) ? config.driver : "hf";
+  return [
+    `v=${MOTION_VERSION}`,
+    `id=${id}`,
+    `lanes=${lanes.length > 0 ? lanes : MOTION_VAR_LANES}`,
+    `owner=${owner}`,
+    `driver=${driver}`,
+  ].join(";");
+}
+
+export function parseMotionVarsAttribute(
+  value: string | null | undefined,
+): MotionVarsConfig | null {
+  if (!value) return null;
+  const parts = new Map<string, string>();
+  for (const rawPart of value.split(";")) {
+    const part = rawPart.trim();
+    if (!part) continue;
+    const separatorIndex = part.indexOf("=");
+    if (separatorIndex <= 0) return null;
+    const key = part.slice(0, separatorIndex).trim();
+    const partValue = part.slice(separatorIndex + 1).trim();
+    if (!key || !partValue) return null;
+    parts.set(key, partValue);
+  }
+
+  if (parts.get("v") !== `${MOTION_VERSION}`) return null;
+  const id = parts.get("id");
+  if (!id || buildMotionVarsId(id) !== id) return null;
+  const lanes: MotionVariableLane[] = [];
+  for (const rawLane of parts.get("lanes")?.split(",") ?? []) {
+    const lane = rawLane.trim() as MotionVariableLane;
+    if (!SUPPORTED_MOTION_VAR_LANES.has(lane)) return null;
+    if (!lanes.includes(lane)) lanes.push(lane);
+  }
+  if (lanes.length === 0) return null;
+
+  const owner = parts.get("owner") as MotionVariableOwner | undefined;
+  if (!owner || !SUPPORTED_MOTION_VAR_OWNERS.has(owner)) return null;
+  const driver = parts.get("driver") as MotionVariableDriver | undefined;
+  if (!driver || !SUPPORTED_MOTION_VAR_DRIVERS.has(driver)) return null;
+
+  return {
+    version: 1,
+    id,
+    lanes,
+    owner,
+    driver,
+  };
+}
+
+export function buildDomEditMotionPatchOperations(
+  draft: MotionDraft | null,
+  motionVarsId: string,
+): PatchOperation[] {
+  return [
+    buildDomEditMotionPatchOperation(draft),
+    {
+      type: "attribute",
+      property: "hf-motion-vars",
+      value: draft ? buildMotionVarsAttribute(motionVarsId) : null,
+    },
+  ];
+}
+
+export function buildMotionCurveModel(draft: MotionDraft): MotionCurveModel {
+  const normalized = buildDefaultMotionDraft(draft.preset, draft);
+  const keyframes = resolveMotionKeyframes(normalized);
+  const start = roundMotionNumber(normalized.start);
+  const duration = roundMotionNumber(normalized.duration);
+  const end = roundMotionNumber(start + duration);
+  const windowEnd = Math.max(end, duration, 0.001);
+  const startPercent = roundMotionNumber((start / windowEnd) * 100);
+
+  const tracks: MotionCurveTrack[] = [
+    buildCurveTrack("x", "X", keyframes.x.from, keyframes.x.to, "px", startPercent),
+    buildCurveTrack("y", "Y", keyframes.y.from, keyframes.y.to, "px", startPercent),
+    buildCurveTrack(
+      "opacity",
+      "Opacity",
+      keyframes.opacity.from,
+      keyframes.opacity.to,
+      "",
+      startPercent,
+    ),
+    buildCurveTrack("scale", "Scale", keyframes.scale.from, keyframes.scale.to, "", startPercent),
+  ];
+
+  return {
+    start,
+    duration,
+    end,
+    windowEnd,
+    ease: normalized.ease,
+    markers: [
+      { label: "Start", time: start, percent: startPercent },
+      { label: "End", time: end, percent: 100 },
+    ],
+    tracks,
+  };
+}
+
+export function buildMotionAgentContext({
+  hfMotionAttribute,
+  draft,
+  ownership,
+}: {
+  hfMotionAttribute?: string;
+  draft: MotionDraft | null;
+  ownership: MotionOwnershipReport;
+}): MotionAgentContext {
+  const model = draft ? buildMotionCurveModel(draft) : null;
+  return {
+    version: 1,
+    state: ownership.state,
+    summary: ownership.summary,
+    hfMotionAttribute: hfMotionAttribute?.trim() || undefined,
+    owners: ownership.badges.map((badge) => ({
+      label: badge.label,
+      state: badge.state,
+      editable: badge.editable,
+    })),
+    curveTracks:
+      model?.tracks.map((track) => ({
+        key: track.key,
+        label: track.label,
+        from: track.from,
+        to: track.to,
+        unit: track.unit,
+        active: track.active,
+      })) ?? [],
+    instructions: [
+      "Patch the existing runtime library only when the target is static, element-specific, and not shared with unrelated layers.",
+      "Do not blindly rewrite dynamic selectors, unresolved variables, shared timelines, function-valued properties, or arbitrary Three.js scene graph mutations.",
+      "Use HF Motion when the requested result should become Studio-owned and deterministic.",
+      "Use an outer layout wrapper when transform ownership is mixed or layout positioning would be corrupted.",
+      "After editing, reload Studio, select this element, seek the preview, and confirm the animation persists in source.",
+    ],
+  };
+}
+
+export function detectMotionOwnership(input: MotionOwnershipInput): MotionOwnershipReport {
+  const element = input.element ?? null;
+  const badges: MotionOwnershipBadge[] = [];
+  const motionVars = parseMotionVarsAttribute(
+    input.dataAttributes?.["hf-motion-vars"] ?? element?.getAttribute("data-hf-motion-vars"),
+  );
+  const hasHfMotion = Boolean(
+    input.dataAttributes?.["hf-motion"] || element?.hasAttribute("data-hf-motion"),
+  );
+
+  if (hasHfMotion || motionVars?.owner === "hf") {
+    badges.push({
+      kind: "hf-motion",
+      label: motionVars ? "HF Motion Vars" : "HF Motion",
+      state: "Editable",
+      editable: true,
+      description: motionVars
+        ? "Studio-authored motion uses canonical CSS variable lanes."
+        : "Studio-authored deterministic motion.",
+    });
+  }
+
+  if (motionVars && motionVars.owner !== "hf") {
+    const variableOwner = getMotionVariableOwnerBadge(motionVars.owner);
+    badges.push({
+      kind: variableOwner.kind,
+      label: `${variableOwner.label} Vars`,
+      state: "Detected",
+      editable: false,
+      description:
+        "Canonical CSS variable lanes detected. Direct source patching still requires safe importer confidence.",
+    });
+  }
+
+  if (hasCssMotion(input)) {
+    badges.push({
+      kind: "css",
+      label: "CSS",
+      state: "Detected",
+      editable: false,
+      description: "CSS animation or transition detected. Read-only for now.",
+    });
+  }
+
+  if (hasWaapiMotion(element)) {
+    badges.push({
+      kind: "waapi",
+      label: "WAAPI",
+      state: "Detected",
+      editable: false,
+      description: "Web Animations API motion detected. Read-only for now.",
+    });
+  }
+
+  if (hasGsapMotion(element)) {
+    badges.push({
+      kind: "gsap",
+      label: "GSAP",
+      state: "Detected",
+      editable: false,
+      description: "Registered GSAP timeline targets this element. Read-only for now.",
+    });
+  }
+
+  if (hasAnimeMotion(element)) {
+    badges.push({
+      kind: "animejs",
+      label: "anime.js",
+      state: "Detected",
+      editable: false,
+      description: "Registered anime.js instance targets this element. Read-only for now.",
+    });
+  }
+
+  if (hasThreeMotion(element)) {
+    badges.push({
+      kind: "three",
+      label: "Three",
+      state: "Detected",
+      editable: false,
+      description: "Three.js time bridge detected. Read-only for now.",
+    });
+  }
+
+  const ownerCount = badges.length;
+  if (ownerCount > 1) {
+    badges.push({
+      kind: "mixed",
+      label: "Mixed",
+      state: "Mixed",
+      editable: false,
+      description: "Multiple motion owners touch this layer; Studio will not rewrite them.",
+    });
+  }
+
+  if (ownerCount === 0) {
+    return {
+      state: "none",
+      badges: [],
+      editable: false,
+      summary: "No runtime-owned motion detected.",
+    };
+  }
+
+  const hasEditableOwner = badges.some((badge) => badge.kind === "hf-motion");
+  const state = ownerCount > 1 ? "mixed" : hasEditableOwner ? "editable" : "detected";
+  return {
+    state,
+    badges,
+    editable: state === "editable",
+    summary:
+      state === "editable"
+        ? "Studio-authored motion is editable."
+        : state === "mixed"
+          ? "Multiple motion owners detected; external owners are read-only."
+          : "External runtime motion is detected and read-only.",
+  };
+}
+
+function getMotionVariableOwnerBadge(owner: MotionVariableOwner): {
+  kind: MotionOwnershipKind;
+  label: string;
+} {
+  switch (owner) {
+    case "gsap":
+      return { kind: "gsap", label: "GSAP" };
+    case "anime":
+      return { kind: "animejs", label: "anime.js" };
+    case "css":
+      return { kind: "css", label: "CSS" };
+    case "waapi":
+      return { kind: "waapi", label: "WAAPI" };
+    case "hf":
+    default:
+      return { kind: "hf-motion", label: "HF Motion" };
+  }
+}
+
+function parseMotionAttribute(value: string | null | undefined): ParsedMotionAttribute | null {
+  if (!value) return null;
+  const parts = new Map<string, string>();
+  for (const rawPart of value.split(";")) {
+    const part = rawPart.trim();
+    if (!part) continue;
+    const separatorIndex = part.indexOf("=");
+    if (separatorIndex <= 0) return null;
+    parts.set(part.slice(0, separatorIndex).trim(), part.slice(separatorIndex + 1).trim());
+  }
+
+  if (parts.get("v") !== `${MOTION_VERSION}`) return null;
+  const preset = parts.get("preset") as MotionPreset | undefined;
+  if (!preset || !SUPPORTED_PRESETS.has(preset)) return null;
+  const ease = normalizeMotionEase(parts.get("ease") ?? "outCubic");
+  if (!ease) return null;
+
+  const start = parseFiniteNumber(parts.get("start") ?? "0");
+  const duration = parseFiniteNumber(parts.get("duration"));
+  const x = parseRange(parts.get("x"), { from: 0, to: 0 }, 0);
+  const y = parseRange(parts.get("y"), { from: 0, to: 0 }, 0);
+  const opacity = parseRange(parts.get("opacity"), { from: 1, to: 1 });
+  const scale = parseRange(parts.get("scale"), { from: 1, to: 1 });
+  if (
+    start == null ||
+    start < 0 ||
+    duration == null ||
+    duration <= 0 ||
+    !x ||
+    !y ||
+    !opacity ||
+    !scale
+  ) {
+    return null;
+  }
+
+  return {
+    preset,
+    start,
+    duration,
+    ease,
+    keyframes: normalizeMotionKeyframes({ x, y, opacity, scale }, getPresetKeyframes({ preset })),
+  };
+}
+
+function getPresetOffsets(draft: MotionDraft): { x: number; y: number } {
+  if (draft.preset === "pop") return { x: 0, y: 0 };
+  switch (draft.direction) {
+    case "down":
+      return { x: 0, y: -draft.distance };
+    case "left":
+      return { x: draft.distance, y: 0 };
+    case "right":
+      return { x: -draft.distance, y: 0 };
+    case "up":
+    default:
+      return { x: 0, y: draft.distance };
+  }
+}
+
+function getPresetKeyframes(
+  draft: Pick<MotionDraft, "preset"> & Partial<MotionDraft>,
+): MotionKeyframes {
+  const presetDraft = {
+    preset: draft.preset,
+    direction:
+      draft.direction && SUPPORTED_DIRECTIONS.has(draft.direction) ? draft.direction : "up",
+    start: 0,
+    duration: draft.preset === "pop" ? POP_DURATION : DEFAULT_DURATION,
+    ease: "outCubic",
+    distance: normalizeFiniteNumber(draft.distance, DEFAULT_DISTANCE, 0),
+  } satisfies MotionDraft;
+  const offsets = getPresetOffsets(presetDraft);
+  return {
+    x: { from: offsets.x, to: 0 },
+    y: { from: offsets.y, to: 0 },
+    opacity: { from: draft.preset === "slide" ? 1 : 0, to: 1 },
+    scale: { from: draft.preset === "pop" ? POP_SCALE_FROM : 1, to: 1 },
+  };
+}
+
+function resolveMotionKeyframes(draft: MotionDraft): MotionKeyframes {
+  return normalizeMotionKeyframes(draft.keyframes, getPresetKeyframes(draft));
+}
+
+function normalizeMotionKeyframes(
+  keyframes: Partial<MotionKeyframes> | undefined,
+  fallback: MotionKeyframes,
+): MotionKeyframes {
+  return {
+    x: normalizeRange(keyframes?.x, fallback.x),
+    y: normalizeRange(keyframes?.y, fallback.y),
+    opacity: normalizeRange(keyframes?.opacity, fallback.opacity, 0, 1),
+    scale: normalizeRange(keyframes?.scale, fallback.scale, 0),
+  };
+}
+
+function normalizeRange(
+  range: Partial<MotionKeyframeRange> | undefined,
+  fallback: MotionKeyframeRange,
+  min = Number.NEGATIVE_INFINITY,
+  max = Number.POSITIVE_INFINITY,
+): MotionKeyframeRange {
+  return {
+    from: clampFiniteNumber(range?.from, fallback.from, min, max),
+    to: clampFiniteNumber(range?.to, fallback.to, min, max),
+  };
+}
+
+function buildCurveTrack(
+  key: MotionCurveTrackKey,
+  label: string,
+  from: number,
+  to: number,
+  unit: "px" | "",
+  startPercent: number,
+): MotionCurveTrack {
+  const roundedFrom = roundMotionNumber(from);
+  const roundedTo = roundMotionNumber(to);
+  return {
+    key,
+    label,
+    from: roundedFrom,
+    to: roundedTo,
+    unit,
+    active: Math.abs(roundedFrom - roundedTo) > 0.0001,
+    points: [
+      { percent: startPercent, value: roundedFrom },
+      { percent: 100, value: roundedTo },
+    ],
+  };
+}
+
+function resolveDirection(x: number, y: number): MotionDirection {
+  if (Math.abs(x) >= Math.abs(y) && Math.abs(x) > 0) {
+    return x > 0 ? "left" : "right";
+  }
+  if (Math.abs(y) > 0) {
+    return y > 0 ? "up" : "down";
+  }
+  return "up";
+}
+
+export function normalizeMotionEase(value: string): MotionEase | null {
+  const trimmed = value.trim();
+  if (isMotionEasePreset(trimmed)) return trimmed;
+  const bezier = parseMotionBezierEase(trimmed);
+  return bezier ? formatMotionBezierEase(bezier) : null;
+}
+
+function isMotionEasePreset(value: string): value is MotionEasePreset {
+  return SUPPORTED_EASES.has(value);
+}
+
+export function isMotionBezierEase(value: string): value is `bezier(${string})` {
+  return parseMotionBezierEase(value) != null;
+}
+
+export function parseMotionBezierEase(value: string): MotionBezierEase | null {
+  const trimmed = value.trim();
+  const bezierPrefix = "bezier(";
+  const cssPrefix = "cubic-bezier(";
+  const prefix = trimmed.startsWith(bezierPrefix)
+    ? bezierPrefix
+    : trimmed.startsWith(cssPrefix)
+      ? cssPrefix
+      : null;
+  if (!prefix || !trimmed.endsWith(")")) return null;
+
+  const body = trimmed.slice(prefix.length, -1);
+  const parts = body.split(",").map((part) => parseFiniteNumber(part));
+  if (parts.length !== 4 || parts.some((part) => part == null)) return null;
+  const [x1, y1, x2, y2] = parts;
+  if (x1 == null || y1 == null || x2 == null || y2 == null) return null;
+  if (x1 < 0 || x1 > 1 || x2 < 0 || x2 > 1) return null;
+  if (y1 < -4 || y1 > 4 || y2 < -4 || y2 > 4) return null;
+  return { x1, y1, x2, y2 };
+}
+
+export function formatMotionBezierEase(bezier: MotionBezierEase): MotionEase {
+  return `bezier(${formatNumber(bezier.x1)},${formatNumber(bezier.y1)},${formatNumber(
+    bezier.x2,
+  )},${formatNumber(bezier.y2)})`;
+}
+
+export function getMotionEaseLabel(ease: MotionEase): string {
+  const option = MOTION_EASE_OPTIONS.find((entry) => entry.value === ease);
+  if (option) return option.label;
+  const bezier = parseMotionBezierEase(ease);
+  return bezier ? `Custom ${formatMotionBezierEase(bezier).replace("bezier", "")}` : "Out Cubic";
+}
+
+export function sampleMotionEase(ease: MotionEase, progress: number): number {
+  const t = clampFiniteNumber(progress, 0, 0, 1);
+  const bezier = parseMotionBezierEase(ease);
+  if (bezier) return cubicBezierProgress(t, bezier);
+
+  const c1 = 1.70158;
+  const c2 = c1 * 1.525;
+  const c3 = c1 + 1;
+  const c4 = (2 * Math.PI) / 3;
+  const c5 = (2 * Math.PI) / 4.5;
+
+  switch (ease) {
+    case "ease":
+      return cubicBezierProgress(t, { x1: 0.25, y1: 0.1, x2: 0.25, y2: 1 });
+    case "inSine":
+      return 1 - Math.cos((t * Math.PI) / 2);
+    case "outSine":
+      return Math.sin((t * Math.PI) / 2);
+    case "inOutSine":
+      return -(Math.cos(Math.PI * t) - 1) / 2;
+    case "inQuad":
+      return t * t;
+    case "outQuad":
+      return 1 - (1 - t) * (1 - t);
+    case "inOutQuad":
+      return t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
+    case "inCubic":
+      return t * t * t;
+    case "outCubic":
+      return 1 - Math.pow(1 - t, 3);
+    case "inOutCubic":
+      return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+    case "inQuart":
+      return t * t * t * t;
+    case "outQuart":
+      return 1 - Math.pow(1 - t, 4);
+    case "inOutQuart":
+      return t < 0.5 ? 8 * Math.pow(t, 4) : 1 - Math.pow(-2 * t + 2, 4) / 2;
+    case "inQuint":
+      return Math.pow(t, 5);
+    case "outQuint":
+      return 1 - Math.pow(1 - t, 5);
+    case "inOutQuint":
+      return t < 0.5 ? 16 * Math.pow(t, 5) : 1 - Math.pow(-2 * t + 2, 5) / 2;
+    case "inExpo":
+      return t === 0 ? 0 : Math.pow(2, 10 * t - 10);
+    case "outExpo":
+      return t === 1 ? 1 : 1 - Math.pow(2, -10 * t);
+    case "inOutExpo":
+      return t === 0
+        ? 0
+        : t === 1
+          ? 1
+          : t < 0.5
+            ? Math.pow(2, 20 * t - 10) / 2
+            : (2 - Math.pow(2, -20 * t + 10)) / 2;
+    case "inCirc":
+      return 1 - Math.sqrt(1 - Math.pow(t, 2));
+    case "outCirc":
+      return Math.sqrt(1 - Math.pow(t - 1, 2));
+    case "inOutCirc":
+      return t < 0.5
+        ? (1 - Math.sqrt(1 - Math.pow(2 * t, 2))) / 2
+        : (Math.sqrt(1 - Math.pow(-2 * t + 2, 2)) + 1) / 2;
+    case "inBack":
+      return c3 * t * t * t - c1 * t * t;
+    case "outBack":
+      return 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2);
+    case "inOutBack":
+      return t < 0.5
+        ? (Math.pow(2 * t, 2) * ((c2 + 1) * 2 * t - c2)) / 2
+        : (Math.pow(2 * t - 2, 2) * ((c2 + 1) * (t * 2 - 2) + c2) + 2) / 2;
+    case "inBounce":
+      return 1 - sampleOutBounce(1 - t);
+    case "outBounce":
+      return sampleOutBounce(t);
+    case "inOutBounce":
+      return t < 0.5 ? (1 - sampleOutBounce(1 - 2 * t)) / 2 : (1 + sampleOutBounce(2 * t - 1)) / 2;
+    case "inElastic":
+      return t === 0
+        ? 0
+        : t === 1
+          ? 1
+          : -Math.pow(2, 10 * t - 10) * Math.sin((t * 10 - 10.75) * c4);
+    case "outElastic":
+      return t === 0 ? 0 : t === 1 ? 1 : Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * c4) + 1;
+    case "inOutElastic":
+      return t === 0
+        ? 0
+        : t === 1
+          ? 1
+          : t < 0.5
+            ? -(Math.pow(2, 20 * t - 10) * Math.sin((20 * t - 11.125) * c5)) / 2
+            : (Math.pow(2, -20 * t + 10) * Math.sin((20 * t - 11.125) * c5)) / 2 + 1;
+    case "linear":
+    default:
+      return t;
+  }
+}
+
+function cubicBezierProgress(progress: number, bezier: MotionBezierEase): number {
+  if (progress <= 0 || progress >= 1) return progress;
+
+  let t = progress;
+  for (let index = 0; index < 8; index += 1) {
+    const x = cubicBezierAxis(t, bezier.x1, bezier.x2) - progress;
+    const dx = cubicBezierAxisDerivative(t, bezier.x1, bezier.x2);
+    if (Math.abs(x) < 0.000001) break;
+    if (Math.abs(dx) < 0.000001) {
+      t = solveBezierTByBisection(progress, bezier);
+      break;
+    }
+    t = clampFiniteNumber(t - x / dx, t, 0, 1);
+  }
+
+  return cubicBezierAxis(t, bezier.y1, bezier.y2);
+}
+
+function solveBezierTByBisection(progress: number, bezier: MotionBezierEase): number {
+  let lower = 0;
+  let upper = 1;
+  let t = progress;
+  for (let index = 0; index < 16; index += 1) {
+    t = (lower + upper) / 2;
+    const x = cubicBezierAxis(t, bezier.x1, bezier.x2);
+    if (Math.abs(x - progress) < 0.000001) break;
+    if (x < progress) {
+      lower = t;
+    } else {
+      upper = t;
+    }
+  }
+  return t;
+}
+
+function cubicBezierAxis(t: number, p1: number, p2: number): number {
+  const inverseT = 1 - t;
+  return 3 * inverseT * inverseT * t * p1 + 3 * inverseT * t * t * p2 + t * t * t;
+}
+
+function cubicBezierAxisDerivative(t: number, p1: number, p2: number): number {
+  const inverseT = 1 - t;
+  return 3 * inverseT * inverseT * p1 + 6 * inverseT * t * (p2 - p1) + 3 * t * t * (1 - p2);
+}
+
+function sampleOutBounce(progress: number): number {
+  const n1 = 7.5625;
+  const d1 = 2.75;
+  if (progress < 1 / d1) return n1 * progress * progress;
+  if (progress < 2 / d1) {
+    const shifted = progress - 1.5 / d1;
+    return n1 * shifted * shifted + 0.75;
+  }
+  if (progress < 2.5 / d1) {
+    const shifted = progress - 2.25 / d1;
+    return n1 * shifted * shifted + 0.9375;
+  }
+  const shifted = progress - 2.625 / d1;
+  return n1 * shifted * shifted + 0.984375;
+}
+
+function parseFiniteNumber(value: string | undefined): number | null {
+  if (value == null || value.trim() === "") return null;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function parseRange(
+  value: string | undefined,
+  fallback: MotionKeyframeRange,
+  singleValueTo?: number,
+): MotionKeyframeRange | null {
+  if (value == null || value.trim() === "") return fallback;
+  const parts = value.split(":");
+  if (parts.length > 2) return null;
+  const from = parseFiniteNumber(parts[0]);
+  if (from == null) return null;
+  const to =
+    parts.length === 2 ? parseFiniteNumber(parts[1]) : singleValueTo != null ? singleValueTo : from;
+  if (to == null) return null;
+  return { from, to };
+}
+
+function normalizeFiniteNumber(value: number | undefined, fallback: number, min: number): number {
+  return value != null && Number.isFinite(value) ? Math.max(min, value) : fallback;
+}
+
+function clampFiniteNumber(value: number | undefined, fallback: number, min: number, max: number) {
+  if (value == null || !Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, value));
+}
+
+function formatPositionRange(range: MotionKeyframeRange): string {
+  return Math.abs(range.to) < 0.0001
+    ? formatNumber(range.from)
+    : `${formatNumber(range.from)}:${formatNumber(range.to)}`;
+}
+
+function formatRange(range: MotionKeyframeRange): string {
+  return `${formatNumber(range.from)}:${formatNumber(range.to)}`;
+}
+
+function formatNumber(value: number): string {
+  const normalized = Math.abs(value) < 0.0001 ? 0 : value;
+  const rounded = Math.round(normalized * 1000) / 1000;
+  return Number.isInteger(rounded)
+    ? `${rounded}`
+    : rounded.toFixed(3).replace(/0+$/, "").replace(/\.$/, "");
+}
+
+function roundMotionNumber(value: number): number {
+  const normalized = Math.abs(value) < 0.0001 ? 0 : value;
+  return Math.round(normalized * 1000) / 1000;
+}
+
+function hasCssMotion(input: MotionOwnershipInput): boolean {
+  const animationName = getMotionStyleValue(input, "animation-name");
+  if (animationName && animationName !== "none") return true;
+
+  const animationDuration = getMotionStyleValue(input, "animation-duration");
+  if (hasNonZeroCssTime(animationDuration)) return true;
+
+  const transitionProperty = getMotionStyleValue(input, "transition-property");
+  const transitionDuration = getMotionStyleValue(input, "transition-duration");
+  return Boolean(
+    transitionProperty && transitionProperty !== "none" && hasNonZeroCssTime(transitionDuration),
+  );
+}
+
+function getMotionStyleValue(input: MotionOwnershipInput, property: string): string | undefined {
+  const supplied = input.computedStyles?.[property];
+  if (supplied) return supplied.trim();
+  const element = input.element;
+  if (!element) return undefined;
+  try {
+    return element.ownerDocument.defaultView
+      ?.getComputedStyle(element)
+      .getPropertyValue(property)
+      .trim();
+  } catch {
+    return undefined;
+  }
+}
+
+function hasNonZeroCssTime(value: string | undefined): boolean {
+  if (!value) return false;
+  return value.split(",").some((part) => {
+    const trimmed = part.trim();
+    if (!trimmed) return false;
+    const parsed = Number.parseFloat(trimmed);
+    if (!Number.isFinite(parsed) || parsed <= 0) return false;
+    return trimmed.endsWith("ms") ? parsed > 0 : parsed > 0;
+  });
+}
+
+function hasWaapiMotion(element: HTMLElement | null): boolean {
+  const getAnimations = element?.getAnimations;
+  if (typeof getAnimations !== "function") return false;
+  try {
+    return getAnimations.call(element).some((animation: Animation) => {
+      const constructorName = animation.constructor?.name ?? "";
+      return constructorName !== "CSSAnimation" && constructorName !== "CSSTransition";
+    });
+  } catch {
+    return false;
+  }
+}
+
+function hasGsapMotion(element: HTMLElement | null): boolean {
+  const runtimeWindow = getOwnerWindow(element) as GsapMotionWindow | null;
+  const timelines = runtimeWindow?.__timelines;
+  if (!element || !timelines) return false;
+
+  for (const timeline of Object.values(timelines)) {
+    const children = getGsapChildren(timeline);
+    if (children.some((child) => targetMatchesElement(resolveGsapTargets(child), element))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function hasAnimeMotion(element: HTMLElement | null): boolean {
+  const runtimeWindow = getOwnerWindow(element) as AnimeMotionWindow | null;
+  if (!element || !Array.isArray(runtimeWindow?.__hfAnime)) return false;
+  return runtimeWindow.__hfAnime.some((instance) =>
+    targetMatchesElement(resolveAnimeTargets(instance), element),
+  );
+}
+
+function hasThreeMotion(element: HTMLElement | null): boolean {
+  const runtimeWindow = getOwnerWindow(element) as ThreeMotionWindow | null;
+  return Boolean(
+    element?.tagName.toLowerCase() === "canvas" &&
+    runtimeWindow &&
+    "__hfThreeTime" in runtimeWindow,
+  );
+}
+
+function getOwnerWindow(element: HTMLElement | null): Window | null {
+  return element?.ownerDocument.defaultView ?? (typeof window !== "undefined" ? window : null);
+}
+
+function getGsapChildren(timeline: unknown): unknown[] {
+  if (!timeline || typeof timeline !== "object") return [];
+  const getChildren = (timeline as { getChildren?: (...args: boolean[]) => unknown }).getChildren;
+  if (typeof getChildren !== "function") return [];
+  try {
+    const children = getChildren.call(timeline, true, true, true);
+    return Array.isArray(children) ? children : [];
+  } catch {
+    return [];
+  }
+}
+
+function resolveGsapTargets(child: unknown): unknown {
+  if (!child || typeof child !== "object") return null;
+  const targets = (child as { targets?: () => unknown }).targets;
+  if (typeof targets === "function") {
+    try {
+      return targets.call(child);
+    } catch {
+      return null;
+    }
+  }
+  return (
+    (child as { vars?: { targets?: unknown }; _targets?: unknown }).vars?.targets ??
+    (child as { _targets?: unknown })._targets ??
+    null
+  );
+}
+
+function resolveAnimeTargets(instance: unknown): unknown {
+  if (!instance || typeof instance !== "object") return null;
+  const typed = instance as {
+    animatables?: Array<{ target?: unknown }>;
+    animations?: Array<{ animatable?: { target?: unknown }; target?: unknown }>;
+    targets?: unknown;
+    _targets?: unknown;
+  };
+  if (Array.isArray(typed.animatables)) {
+    return typed.animatables.map((animatable) => animatable.target);
+  }
+  if (Array.isArray(typed.animations)) {
+    return typed.animations.map((animation) => animation.animatable?.target ?? animation.target);
+  }
+  return typed.targets ?? typed._targets ?? null;
+}
+
+function targetMatchesElement(targets: unknown, element: HTMLElement): boolean {
+  if (!targets) return false;
+  if (targets === element) return true;
+  if (typeof targets === "string") {
+    try {
+      return element.matches(targets);
+    } catch {
+      return false;
+    }
+  }
+  if (Array.isArray(targets)) {
+    return targets.some((target) => targetMatchesElement(target, element));
+  }
+  if (
+    typeof NodeList !== "undefined" &&
+    targets instanceof NodeList &&
+    Array.from(targets).includes(element)
+  ) {
+    return true;
+  }
+  return false;
+}
+
+interface GsapMotionWindow extends Window {
+  __timelines?: Record<string, unknown>;
+}
+
+interface AnimeMotionWindow extends Window {
+  __hfAnime?: unknown[];
+}
+
+interface ThreeMotionWindow extends Window {
+  __hfThreeTime?: number;
+}
diff --git a/packages/studio/src/components/nle/NLELayout.test.ts b/packages/studio/src/components/nle/NLELayout.test.ts
new file mode 100644
index 000000000..b7d142bd8
--- /dev/null
+++ b/packages/studio/src/components/nle/NLELayout.test.ts
@@ -0,0 +1,55 @@
+import { Window } from "happy-dom";
+import { beforeAll, describe, expect, it } from "vitest";
+
+let resolveTimelineCompositionSource: typeof import("./NLELayout").resolveTimelineCompositionSource;
+
+beforeAll(async () => {
+  const window = new Window();
+  Object.assign(globalThis, {
+    HTMLElement: window.HTMLElement,
+    HTMLDivElement: window.HTMLDivElement,
+    HTMLIFrameElement: window.HTMLIFrameElement,
+    HTMLImageElement: window.HTMLImageElement,
+    customElements: window.customElements,
+    document: window.document,
+    CSSStyleSheet: window.CSSStyleSheet,
+    ResizeObserver: class {
+      observe() {}
+      disconnect() {}
+    },
+  });
+  ({ resolveTimelineCompositionSource } = await import("./NLELayout"));
+});
+
+describe("resolveTimelineCompositionSource", () => {
+  const map = new Map([
+    ["hook", "compositions/hook.html"],
+    ["motion", "compositions/motion.html"],
+    ["closing", "compositions/closing.html"],
+  ]);
+
+  it("keeps an existing composition source", () => {
+    expect(
+      resolveTimelineCompositionSource(
+        { id: "scene-hook", compositionSrc: "compositions/custom.html" },
+        map,
+      ),
+    ).toBe("compositions/custom.html");
+  });
+
+  it("maps scene-prefixed timeline clip ids back to composition paths", () => {
+    expect(resolveTimelineCompositionSource({ id: "scene-motion" }, map)).toBe(
+      "compositions/motion.html",
+    );
+  });
+
+  it("maps suffixed host ids back to composition paths", () => {
+    expect(resolveTimelineCompositionSource({ id: "closing-host" }, map)).toBe(
+      "compositions/closing.html",
+    );
+  });
+
+  it("returns undefined for unrelated timeline elements", () => {
+    expect(resolveTimelineCompositionSource({ id: "avatar-video" }, map)).toBeUndefined();
+  });
+});
diff --git a/packages/studio/src/components/nle/NLELayout.tsx b/packages/studio/src/components/nle/NLELayout.tsx
index 79757b081..99bd223c8 100644
--- a/packages/studio/src/components/nle/NLELayout.tsx
+++ b/packages/studio/src/components/nle/NLELayout.tsx
@@ -1,5 +1,4 @@
 import { useState, useCallback, useRef, useEffect, memo, type ReactNode } from "react";
-import { useMountEffect } from "../../hooks/useMountEffect";
 import { useTimelinePlayer, PlayerControls, Timeline, usePlayerStore } from "../../player";
 import type { TimelineElement } from "../../player";
 import type { BlockedTimelineEditIntent } from "../../player/components/timelineEditing";
@@ -9,6 +8,11 @@ import {
   TIMELINE_TOGGLE_SHORTCUT_LABEL,
   getTimelineToggleTitle,
 } from "../../utils/timelineDiscovery";
+import {
+  getCompositionLabel,
+  getCompositionPreviewUrl,
+  parseCompositionSourceMap,
+} from "../../utils/compositionPaths";
 
 interface NLELayoutProps {
   projectId: string;
@@ -30,7 +34,7 @@ interface NLELayoutProps {
   /** Custom clip content renderer for timeline (thumbnails, waveforms, etc.) */
   renderClipContent?: (
     element: TimelineElement,
-    style: { clip: string; label: string },
+    style: { clip: string; label: string; accent?: string },
   ) => ReactNode;
   onFileDrop?: (
     files: File[],
@@ -51,6 +55,17 @@ interface NLELayoutProps {
     updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
   ) => Promise<void> | void;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
+  /** Mirror timeline clip selection into the parent editor selection model. */
+  onSelectTimelineElement?: (element: TimelineElement | null) => void;
+  /** Enable the preview inspector for an explicit timeline clip. */
+  onInspectTimelineElement?: (element: TimelineElement) => void;
+  inspectedTimelineElementId?: string | null;
+  /** Descendant layer counts for clips that can expose nested DOM layers. */
+  timelineLayerChildCounts?: ReadonlyMap<string, number>;
+  /** Timeline clips with custom thumbnail content enabled. */
+  thumbnailedTimelineElementIds?: Set<string>;
+  /** Toggle thumbnail content for an explicit timeline clip. */
+  onToggleTimelineElementThumbnail?: (element: TimelineElement) => void;
   /** Exposes the compIdToSrc map for parent components (e.g., useRenderClipContent) */
   onCompIdToSrcChange?: (map: Map<string, string>) => void;
   /** Whether the timeline panel is visible (default: true) */
@@ -63,6 +78,31 @@ const MIN_TIMELINE_H = 100;
 const DEFAULT_TIMELINE_H = 220;
 const MIN_PREVIEW_H = 120;
 
+export function resolveTimelineCompositionSource(
+  element: Pick<TimelineElement, "id" | "compositionSrc">,
+  compIdToSrc: ReadonlyMap<string, string>,
+): string | undefined {
+  if (element.compositionSrc) return element.compositionSrc;
+
+  const candidates = new Set<string>();
+  const addCandidate = (value: string) => {
+    if (value) candidates.add(value);
+  };
+  addCandidate(element.id);
+  addCandidate(element.id.replace(/^(scene|composition|comp)-/, ""));
+  addCandidate(element.id.replace(/-(host|comp|layer|mount)$/, ""));
+  addCandidate(
+    element.id.replace(/^(scene|composition|comp)-/, "").replace(/-(host|comp|layer|mount)$/, ""),
+  );
+
+  for (const candidate of candidates) {
+    const src = compIdToSrc.get(candidate);
+    if (src) return src;
+  }
+
+  return undefined;
+}
+
 export const NLELayout = memo(function NLELayout({
   projectId,
   portrait,
@@ -80,6 +120,12 @@ export const NLELayout = memo(function NLELayout({
   onMoveElement,
   onResizeElement,
   onBlockedEditAttempt,
+  onSelectTimelineElement,
+  onInspectTimelineElement,
+  inspectedTimelineElementId,
+  timelineLayerChildCounts,
+  thumbnailedTimelineElementIds,
+  onToggleTimelineElementThumbnail,
   onCompIdToSrcChange,
   timelineVisible,
   onToggleTimeline,
@@ -103,7 +149,9 @@ export const NLELayout = memo(function NLELayout({
     usePlayerStore.getState().reset();
   }
 
-  // Refresh the existing iframe in place when source files change.
+  // Refresh the current iframe in place after project file writes. Direct
+  // project/composition navigation still remounts through NLEPreview's stable
+  // project/directUrl key.
   const prevRefreshKeyRef = useRef(refreshKey);
   useEffect(() => {
     if (refreshKey === prevRefreshKeyRef.current) return;
@@ -119,25 +167,23 @@ export const NLELayout = memo(function NLELayout({
 
   // Composition ID → actual file path mapping, built from the raw index.html
   const [compIdToSrc, setCompIdToSrc] = useState<Map<string, string>>(new Map());
-  useMountEffect(() => {
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    let cancelled = false;
     fetch(`/api/projects/${projectId}/files/index.html`)
       .then((r) => r.json())
       .then((data: { content?: string }) => {
+        if (cancelled) return;
         const html = data.content || "";
-        const map = new Map<string, string>();
-        const re =
-          /data-composition-id=["']([^"']+)["'][^>]*data-composition-src=["']([^"']+)["']|data-composition-src=["']([^"']+)["'][^>]*data-composition-id=["']([^"']+)["']/g;
-        let match;
-        while ((match = re.exec(html)) !== null) {
-          const id = match[1] || match[4];
-          const src = match[2] || match[3];
-          if (id && src) map.set(id, src);
-        }
+        const map = parseCompositionSourceMap(html);
         setCompIdToSrc(map);
         onCompIdToSrcChange?.(map);
       })
       .catch(() => {});
-  });
+    return () => {
+      cancelled = true;
+    };
+  }, [projectId, onCompIdToSrcChange]);
 
   // Patch elements with compositionSrc whenever elements or compIdToSrc change.
   // The runtime strips data-composition-src from the DOM after loading, so elements
@@ -155,8 +201,7 @@ export const NLELayout = memo(function NLELayout({
       let patched = false;
       const updated = elements.map((el) => {
         if (el.compositionSrc) return el;
-        // Try exact match, then strip common suffixes (-host, -comp, -layer)
-        const src = map.get(el.id) ?? map.get(el.id.replace(/-(host|comp|layer)$/, ""));
+        const src = resolveTimelineCompositionSource(el, map);
         if (src) {
           patched = true;
           return { ...el, compositionSrc: src };
@@ -184,7 +229,7 @@ export const NLELayout = memo(function NLELayout({
 
   // Composition drill-down stack
   const [compositionStack, setCompositionStack] = useState<CompositionLevel[]>([
-    { id: "master", label: "Master", previewUrl: `/api/projects/${projectId}/preview` },
+    { id: "master", label: "Master", previewUrl: getCompositionPreviewUrl(projectId, null) },
   ]);
 
   // Wrap setCompositionStack to auto-notify parent on composition change
@@ -209,6 +254,10 @@ export const NLELayout = memo(function NLELayout({
   const currentLevel = compositionStack[compositionStack.length - 1];
   const directUrl = compositionStack.length > 1 ? currentLevel.previewUrl : undefined;
 
+  useEffect(() => {
+    onIframeRef?.(iframeRef.current);
+  }, [compositionStack.length, onIframeRef, refreshKey, iframeRef]);
+
   // Save master seek position before drilling down so we can restore it on back-navigation.
   // saveSeekPosition() sets pendingSeekRef in useTimelinePlayer which onIframeLoad reads.
   const masterSeekRef = useRef(0);
@@ -260,12 +309,8 @@ export const NLELayout = memo(function NLELayout({
           return prev.slice(0, -1);
         }
         // Extract a clean label from the path (strip directories and extension)
-        const label =
-          resolvedPath
-            .split("/")
-            .pop()
-            ?.replace(/\.html$/, "") || resolvedPath;
-        const previewUrl = `/api/projects/${projectId}/preview/comp/${resolvedPath}`;
+        const label = getCompositionLabel(resolvedPath);
+        const previewUrl = getCompositionPreviewUrl(projectId, resolvedPath);
         return [...prev, { id: resolvedPath, label, previewUrl }];
       });
     },
@@ -294,13 +339,13 @@ export const NLELayout = memo(function NLELayout({
       usePlayerStore.getState().setElements([]);
       updateCompositionStack((prev) => (prev.length > 1 ? [prev[0]] : prev));
     } else if (activeCompositionPath && activeCompositionPath.startsWith("compositions/")) {
-      const label = activeCompositionPath.replace(/^compositions\//, "").replace(/\.html$/, "");
-      const previewUrl = `/api/projects/${projectId}/preview/comp/${activeCompositionPath}`;
+      const label = getCompositionLabel(activeCompositionPath);
+      const previewUrl = getCompositionPreviewUrl(projectId, activeCompositionPath);
       usePlayerStore.getState().setElements([]);
       updateCompositionStack((prev) => {
         if (prev[prev.length - 1]?.id === activeCompositionPath) return prev;
         return [
-          { id: "master", label: "Master", previewUrl: `/api/projects/${projectId}/preview` },
+          { id: "master", label: "Master", previewUrl: getCompositionPreviewUrl(projectId, null) },
           { id: activeCompositionPath, label, previewUrl },
         ];
       });
@@ -359,7 +404,6 @@ export const NLELayout = memo(function NLELayout({
             onIframeLoad={onIframeLoad}
             portrait={portrait}
             directUrl={directUrl}
-            refreshKey={refreshKey}
           />
           {previewOverlay}
         </div>
@@ -405,6 +449,12 @@ export const NLELayout = memo(function NLELayout({
               <Timeline
                 onSeek={seek}
                 onDrillDown={handleDrillDown}
+                onSelectElement={onSelectTimelineElement}
+                onInspectElement={onInspectTimelineElement}
+                inspectedElementId={inspectedTimelineElementId}
+                layerChildCounts={timelineLayerChildCounts}
+                thumbnailedElementIds={thumbnailedTimelineElementIds}
+                onToggleElementThumbnail={onToggleTimelineElementThumbnail}
                 renderClipContent={renderClipContent}
                 onFileDrop={onFileDrop}
                 onDeleteElement={onDeleteElement}
diff --git a/packages/studio/src/components/nle/NLEPreview.test.ts b/packages/studio/src/components/nle/NLEPreview.test.ts
index 4451458ee..7c0e96334 100644
--- a/packages/studio/src/components/nle/NLEPreview.test.ts
+++ b/packages/studio/src/components/nle/NLEPreview.test.ts
@@ -1,19 +1,33 @@
-import { describe, expect, it } from "vitest";
-import { getPreviewPlayerKey } from "./NLEPreview";
+import { Window } from "happy-dom";
+import { beforeAll, describe, expect, it } from "vitest";
+
+let getPreviewPlayerKey: typeof import("./NLEPreview").getPreviewPlayerKey;
+
+beforeAll(async () => {
+  const window = new Window();
+  Object.assign(globalThis, {
+    HTMLElement: window.HTMLElement,
+    HTMLDivElement: window.HTMLDivElement,
+    HTMLIFrameElement: window.HTMLIFrameElement,
+    HTMLImageElement: window.HTMLImageElement,
+    customElements: window.customElements,
+    document: window.document,
+    CSSStyleSheet: window.CSSStyleSheet,
+    ResizeObserver: class {
+      observe() {}
+      disconnect() {}
+    },
+  });
+  ({ getPreviewPlayerKey } = await import("./NLEPreview"));
+});
 
 describe("getPreviewPlayerKey", () => {
-  it("keeps the same player identity when only refreshKey changes", () => {
+  it("uses the project id for master preview identity", () => {
     expect(
       getPreviewPlayerKey({
         projectId: "timeline-edit-playground",
-        refreshKey: 1,
       }),
-    ).toBe(
-      getPreviewPlayerKey({
-        projectId: "timeline-edit-playground",
-        refreshKey: 2,
-      }),
-    );
+    ).toBe("timeline-edit-playground");
   });
 
   it("switches identity when drilling into a different directUrl", () => {
diff --git a/packages/studio/src/components/nle/NLEPreview.tsx b/packages/studio/src/components/nle/NLEPreview.tsx
index dab649edc..b415c685f 100644
--- a/packages/studio/src/components/nle/NLEPreview.tsx
+++ b/packages/studio/src/components/nle/NLEPreview.tsx
@@ -7,7 +7,6 @@ interface NLEPreviewProps {
   onIframeLoad: () => void;
   portrait?: boolean;
   directUrl?: string;
-  refreshKey?: number;
 }
 
 export function getPreviewPlayerKey({
@@ -16,25 +15,29 @@ export function getPreviewPlayerKey({
 }: {
   projectId: string;
   directUrl?: string;
-  refreshKey?: number;
 }): string {
   return directUrl ?? projectId;
 }
 
+/**
+ * Manages the composition preview identity.
+ * Routine source refreshes happen inside the existing iframe via
+ * useTimelinePlayer.refreshPlayer(); this only remounts when the project or
+ * drilled-in composition URL changes.
+ */
 export const NLEPreview = memo(function NLEPreview({
   projectId,
   iframeRef,
   onIframeLoad,
   portrait,
   directUrl,
-  refreshKey,
 }: NLEPreviewProps) {
-  const playerKey = getPreviewPlayerKey({ projectId, directUrl, refreshKey });
+  const playerKey = getPreviewPlayerKey({ projectId, directUrl });
 
   return (
     <div className="flex flex-col h-full min-h-0">
       <div
-        className="flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0 outline-none focus:ring-1 focus:ring-studio-accent/40"
+        className="relative flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0 outline-none focus:ring-1 focus:ring-studio-accent/40"
         tabIndex={0}
         aria-label="Composition preview"
       >
diff --git a/packages/studio/src/components/renders/RenderQueue.tsx b/packages/studio/src/components/renders/RenderQueue.tsx
index 8a6e69909..097232e7a 100644
--- a/packages/studio/src/components/renders/RenderQueue.tsx
+++ b/packages/studio/src/components/renders/RenderQueue.tsx
@@ -41,31 +41,36 @@ function FormatInfoTooltip({ format }: { format: "mp4" | "webm" | "mov" }) {
 
   return (
     <div className="relative" onPointerEnter={show} onPointerLeave={hide}>
-      <svg
-        width="12"
-        height="12"
-        viewBox="0 0 24 24"
-        fill="none"
-        stroke="currentColor"
-        strokeWidth="2"
-        strokeLinecap="round"
-        strokeLinejoin="round"
-        className="text-neutral-600 hover:text-neutral-400 transition-colors cursor-help"
+      <button
+        type="button"
+        aria-label={`${info.label} export details`}
+        className="flex h-8 w-8 items-center justify-center rounded-full border border-neutral-800 bg-neutral-950 text-neutral-500 transition-colors hover:border-neutral-700 hover:text-neutral-200"
       >
-        <circle cx="12" cy="12" r="10" />
-        <path d="M9.09 9a3 3 0 015.83 1c0 2-3 3-3 3" />
-        <line x1="12" y1="17" x2="12.01" y2="17" />
-      </svg>
+        <svg
+          width="13"
+          height="13"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <circle cx="12" cy="12" r="10" />
+          <path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3" />
+          <line x1="12" y1="17" x2="12.01" y2="17" />
+        </svg>
+      </button>
       {open && (
-        <div className="absolute top-full right-0 mt-1.5 w-52 p-2 rounded bg-neutral-900 border border-neutral-700 shadow-lg z-50">
-          <p className="text-[10px] font-semibold text-neutral-200 mb-0.5">{info.label}</p>
-          <p className="text-[9px] text-neutral-400 leading-tight">{info.desc}</p>
-          <div className="mt-1.5 pt-1.5 border-t border-neutral-800">
+        <div className="absolute right-0 top-full z-50 mt-2 w-64 rounded-xl border border-neutral-700 bg-neutral-950 p-3 shadow-2xl">
+          <p className="mb-1 text-[11px] font-semibold text-neutral-100">{info.label}</p>
+          <p className="text-[10px] leading-4 text-neutral-400">{info.desc}</p>
+          <div className="mt-2 border-t border-neutral-800 pt-2">
             {(["mp4", "mov", "webm"] as const)
               .filter((f) => f !== format)
               .map((f) => (
-                <p key={f} className="text-[9px] text-neutral-500 leading-relaxed">
-                  <span className="text-neutral-400 font-medium">{FORMAT_INFO[f].label}</span>
+                <p key={f} className="text-[10px] leading-4 text-neutral-500">
+                  <span className="font-medium text-neutral-300">{FORMAT_INFO[f].label}</span>
                   {" — "}
                   {FORMAT_INFO[f].desc}
                 </p>
@@ -101,39 +106,72 @@ function FormatExportButton({
   const showQuality = format !== "mov";
 
   return (
-    <div className="flex items-center gap-1">
-      <FormatInfoTooltip format={format} />
+    <div className="border-b border-neutral-800 px-4 py-4">
+      <div className="mb-4 flex min-w-0 items-start justify-between gap-3">
+        <div className="min-w-0">
+          <div className="text-[11px] font-semibold uppercase tracking-[0.18em] text-neutral-500">
+            Export
+          </div>
+          <div className="mt-1 text-[11px] leading-5 text-neutral-400">
+            Render the current composition.
+          </div>
+        </div>
+        <FormatInfoTooltip format={format} />
+      </div>
       {showQuality && (
-        <select
-          value={quality}
-          onChange={(e) => setQuality(e.target.value as "draft" | "standard" | "high")}
-          disabled={isRendering}
-          title={QUALITY_OPTIONS.find((q) => q.value === quality)?.title}
-          className="h-5 px-1 text-[10px] rounded-l bg-neutral-800 border border-neutral-700 text-neutral-300 outline-none disabled:opacity-50"
-        >
-          {QUALITY_OPTIONS.map((q) => (
-            <option key={q.value} value={q.value} title={q.title}>
-              {q.label}
-            </option>
-          ))}
-        </select>
+        <div className="mb-4 grid gap-2">
+          <div className="text-[10px] font-semibold uppercase tracking-[0.16em] text-neutral-500">
+            Quality
+          </div>
+          <div className="grid grid-cols-3 rounded-xl border border-neutral-800 bg-neutral-950 p-1">
+            {QUALITY_OPTIONS.map((option) => (
+              <button
+                key={option.value}
+                type="button"
+                title={option.title}
+                disabled={isRendering}
+                onClick={() => setQuality(option.value)}
+                className={`h-8 min-w-0 rounded-lg px-2 text-[11px] font-medium transition-colors disabled:cursor-not-allowed disabled:opacity-50 ${
+                  quality === option.value
+                    ? "bg-neutral-800 text-white shadow-[0_1px_2px_rgba(0,0,0,0.25)]"
+                    : "text-neutral-500 hover:bg-neutral-900 hover:text-neutral-200"
+                }`}
+              >
+                <span className="block truncate">{option.label}</span>
+              </button>
+            ))}
+          </div>
+        </div>
       )}
-      <select
-        value={format}
-        onChange={(e) => setFormat(e.target.value as "mp4" | "webm" | "mov")}
-        disabled={isRendering}
-        className={`h-5 px-1 text-[10px] bg-neutral-800 border border-neutral-700 text-neutral-300 outline-none disabled:opacity-50 ${showQuality ? "" : "rounded-l"}`}
-      >
-        <option value="mp4">MP4</option>
-        <option value="mov">MOV</option>
-        <option value="webm">WebM</option>
-      </select>
+      <div className="mb-4 grid gap-2">
+        <div className="text-[10px] font-semibold uppercase tracking-[0.16em] text-neutral-500">
+          Format
+        </div>
+        <div className="grid grid-cols-3 rounded-xl border border-neutral-800 bg-neutral-950 p-1">
+          {(["mp4", "mov", "webm"] as const).map((option) => (
+            <button
+              key={option}
+              type="button"
+              disabled={isRendering}
+              onClick={() => setFormat(option)}
+              className={`h-8 min-w-0 rounded-lg px-2 text-[11px] font-medium transition-colors disabled:cursor-not-allowed disabled:opacity-50 ${
+                format === option
+                  ? "bg-neutral-800 text-white shadow-[0_1px_2px_rgba(0,0,0,0.25)]"
+                  : "text-neutral-500 hover:bg-neutral-900 hover:text-neutral-200"
+              }`}
+            >
+              {FORMAT_INFO[option].label.replace(" (ProRes 4444)", "").replace(" (VP9)", "")}
+            </button>
+          ))}
+        </div>
+      </div>
       <button
+        type="button"
         onClick={() => onStartRender(format, quality)}
         disabled={isRendering}
-        className="flex items-center gap-1 px-2 py-0.5 text-[10px] font-semibold rounded-r bg-studio-accent text-[#09090B] hover:brightness-110 transition-colors disabled:opacity-50"
+        className="flex h-10 w-full items-center justify-center rounded-xl bg-studio-accent px-4 text-[12px] font-semibold text-[#09090B] transition-colors hover:brightness-110 disabled:cursor-not-allowed disabled:opacity-50"
       >
-        {isRendering ? "Rendering..." : "Export"}
+        {isRendering ? "Rendering..." : `Export ${FORMAT_INFO[format].label.split(" ")[0]}`}
       </button>
     </div>
   );
@@ -160,26 +198,13 @@ export const RenderQueue = memo(function RenderQueue({
   const completedCount = jobs.filter((j) => j.status !== "rendering").length;
 
   return (
-    <div className="flex flex-col h-full">
-      {/* Header — no title, already shown in header button */}
-      <div className="flex items-center justify-end px-3 py-2 border-b border-neutral-800/50 flex-shrink-0">
-        <div className="flex items-center gap-1.5">
-          {completedCount > 0 && (
-            <button
-              onClick={onClearCompleted}
-              className="text-[10px] text-neutral-600 hover:text-neutral-400 transition-colors"
-            >
-              Clear
-            </button>
-          )}
-          <FormatExportButton onStartRender={onStartRender} isRendering={isRendering} />
-        </div>
-      </div>
+    <div className="flex h-full flex-col bg-neutral-900 text-neutral-100">
+      <FormatExportButton onStartRender={onStartRender} isRendering={isRendering} />
 
       {/* Job list */}
       <div ref={listRef} className="flex-1 overflow-y-auto">
         {jobs.length === 0 ? (
-          <div className="flex flex-col items-center justify-center h-full px-4 gap-2">
+          <div className="flex h-full flex-col items-center justify-center gap-3 px-6 text-center">
             <svg
               width="20"
               height="20"
@@ -205,17 +230,38 @@ export const RenderQueue = memo(function RenderQueue({
                 strokeLinejoin="round"
               />
             </svg>
-            <p className="text-[10px] text-neutral-600 text-center">No renders yet</p>
+            <div>
+              <p className="text-[12px] font-medium text-neutral-300">No renders yet</p>
+              <p className="mt-1 text-[11px] leading-5 text-neutral-600">
+                Exports will appear here with progress, downloads, and history.
+              </p>
+            </div>
           </div>
         ) : (
-          jobs.map((job) => (
-            <RenderQueueItem
-              key={job.id}
-              job={job}
-              projectId={projectId}
-              onDelete={() => onDelete(job.id)}
-            />
-          ))
+          <div>
+            <div className="flex items-center justify-between border-b border-neutral-800/70 px-4 py-3">
+              <div className="text-[10px] font-semibold uppercase tracking-[0.16em] text-neutral-500">
+                History
+              </div>
+              {completedCount > 0 && (
+                <button
+                  type="button"
+                  onClick={onClearCompleted}
+                  className="rounded-lg border border-neutral-800 bg-neutral-950 px-2.5 py-1 text-[10px] font-medium text-neutral-400 transition-colors hover:border-neutral-700 hover:text-neutral-100"
+                >
+                  Clear completed
+                </button>
+              )}
+            </div>
+            {jobs.map((job) => (
+              <RenderQueueItem
+                key={job.id}
+                job={job}
+                projectId={projectId}
+                onDelete={() => onDelete(job.id)}
+              />
+            ))}
+          </div>
         )}
       </div>
     </div>
diff --git a/packages/studio/src/components/sidebar/AssetsTab.tsx b/packages/studio/src/components/sidebar/AssetsTab.tsx
index eccbf9d88..4272c543d 100644
--- a/packages/studio/src/components/sidebar/AssetsTab.tsx
+++ b/packages/studio/src/components/sidebar/AssetsTab.tsx
@@ -2,6 +2,7 @@ import { memo, useState, useCallback, useRef } from "react";
 import { VideoFrameThumbnail } from "../ui/VideoFrameThumbnail";
 import { MEDIA_EXT, IMAGE_EXT, VIDEO_EXT, AUDIO_EXT } from "../../utils/mediaTypes";
 import { TIMELINE_ASSET_MIME } from "../../utils/timelineAssetDrop";
+import { copyTextToClipboard } from "../../utils/clipboard";
 
 interface AssetsTabProps {
   projectId: string;
@@ -298,12 +299,10 @@ export const AssetsTab = memo(function AssetsTab({
   );
 
   const handleCopyPath = useCallback(async (path: string) => {
-    try {
-      await navigator.clipboard.writeText(path);
+    const copied = await copyTextToClipboard(path);
+    if (copied) {
       setCopiedPath(path);
       setTimeout(() => setCopiedPath(null), 1500);
-    } catch {
-      // ignore
     }
   }, []);
 
diff --git a/packages/studio/src/components/sidebar/CompositionsTab.test.ts b/packages/studio/src/components/sidebar/CompositionsTab.test.ts
index 25549f1ea..ce2ef1fe3 100644
--- a/packages/studio/src/components/sidebar/CompositionsTab.test.ts
+++ b/packages/studio/src/components/sidebar/CompositionsTab.test.ts
@@ -1,37 +1,56 @@
 import { describe, expect, it } from "vitest";
-import { resolveCompositionPreviewScale } from "./CompositionsTab";
-
-describe("resolveCompositionPreviewScale", () => {
-  it("scales a 16:9 stage to fit the composition card", () => {
-    expect(
-      resolveCompositionPreviewScale({
-        cardWidth: 80,
-        cardHeight: 45,
-        stageWidth: 1920,
-        stageHeight: 1080,
-      }),
-    ).toBeCloseTo(80 / 1920);
-  });
-
-  it("scales non-16:9 stages against their actual dimensions", () => {
-    expect(
-      resolveCompositionPreviewScale({
-        cardWidth: 80,
-        cardHeight: 45,
-        stageWidth: 1280,
-        stageHeight: 720,
-      }),
-    ).toBeCloseTo(80 / 1280);
-  });
-
-  it("falls back to the default stage when dimensions are invalid", () => {
-    expect(
-      resolveCompositionPreviewScale({
-        cardWidth: 80,
-        cardHeight: 45,
-        stageWidth: 0,
-        stageHeight: Number.NaN,
-      }),
-    ).toBeCloseTo(80 / 1920);
+import {
+  DEFAULT_COMPOSITION_THUMBNAIL_MODE,
+  getCompositionDisplayName,
+  getCompositionThumbnailTimeSeconds,
+  parseCompositionDimensionsFromHtml,
+  parseCompositionDurationFromHtml,
+} from "./CompositionsTab";
+
+describe("getCompositionDisplayName", () => {
+  it("strips the composition directory and html extension", () => {
+    expect(getCompositionDisplayName("compositions/intro-card.html")).toBe("intro-card");
+  });
+
+  it("keeps bare composition names readable", () => {
+    expect(getCompositionDisplayName("index.html")).toBe("index");
+  });
+});
+
+describe("DEFAULT_COMPOSITION_THUMBNAIL_MODE", () => {
+  it("loads composition thumbnails by default", () => {
+    expect(DEFAULT_COMPOSITION_THUMBNAIL_MODE).toBe("visible");
+  });
+});
+
+describe("composition thumbnail timing", () => {
+  it("uses the 3s frame for compositions at least 3 seconds long", () => {
+    expect(getCompositionThumbnailTimeSeconds(4.3)).toBe(3);
+    expect(getCompositionThumbnailTimeSeconds(3)).toBe(3);
+  });
+
+  it("uses the midpoint for compositions shorter than 3 seconds", () => {
+    expect(getCompositionThumbnailTimeSeconds(2)).toBe(1);
+    expect(getCompositionThumbnailTimeSeconds(1.5)).toBe(0.75);
+  });
+
+  it("falls back to 3s when duration is unavailable", () => {
+    expect(getCompositionThumbnailTimeSeconds(null)).toBe(3);
+  });
+});
+
+describe("composition source metadata parsing", () => {
+  it("reads duration and dimensions from composition attributes", () => {
+    const html =
+      '<div data-composition-id="beat" data-width="960" data-height="540" data-duration="2.5">';
+    expect(parseCompositionDurationFromHtml(html)).toBe(2.5);
+    expect(parseCompositionDimensionsFromHtml(html)).toEqual({ width: 960, height: 540 });
+  });
+
+  it("falls back to 16:9 dimensions when omitted", () => {
+    expect(parseCompositionDimensionsFromHtml("<main></main>")).toEqual({
+      width: 1920,
+      height: 1080,
+    });
   });
 });
diff --git a/packages/studio/src/components/sidebar/CompositionsTab.tsx b/packages/studio/src/components/sidebar/CompositionsTab.tsx
index 12dc558da..bac00ef4e 100644
--- a/packages/studio/src/components/sidebar/CompositionsTab.tsx
+++ b/packages/studio/src/components/sidebar/CompositionsTab.tsx
@@ -1,136 +1,250 @@
-import { memo, useRef, useState } from "react";
+import { memo, useEffect, useRef, useState } from "react";
+import { buildCompositionThumbnailUrl } from "../../player/components/CompositionThumbnail";
+import { hashThumbnailSource } from "../../thumbnails/sourceHash";
+import { getStudioThumbnailService } from "../../thumbnails/studioThumbnailService";
+import { shouldRequestThumbnail, type ThumbnailMode } from "../../thumbnails/thumbnailMode";
+import { getCompositionPreviewUrl } from "../../utils/compositionPaths";
 
 interface CompositionsTabProps {
-  projectId: string;
   compositions: string[];
   activeComposition: string | null;
   onSelect: (comp: string) => void;
+  projectId?: string;
+  resolveSourceContent?: (path: string) => Promise<string>;
+}
+
+const COMPOSITION_THUMBNAIL_WIDTH = 160;
+const COMPOSITION_THUMBNAIL_HEIGHT = 90;
+const DEFAULT_COMPOSITION_THUMBNAIL_TIME_SECONDS = 3;
+const DEFAULT_COMPOSITION_WIDTH = 1920;
+const DEFAULT_COMPOSITION_HEIGHT = 1080;
+export const DEFAULT_COMPOSITION_THUMBNAIL_MODE: ThumbnailMode = "visible";
+
+interface CompositionSourceMetadata {
+  sourceHash: string;
+  duration: number | null;
+  width: number;
+  height: number;
+}
+
+interface MiniPlayerApi {
+  seek?: (timeSeconds: number) => void;
+  renderSeek?: (timeSeconds: number) => void;
+  play?: () => void;
+  pause?: () => void;
+  getTime?: () => number;
+  getDuration?: () => number;
+}
+
+interface HyperframesPlayerElement extends HTMLElement {
+  iframeElement: HTMLIFrameElement;
+}
+
+export function getCompositionDisplayName(comp: string): string {
+  const name = comp.replace(/^compositions\//, "").replace(/\.html$/, "");
+  return name || "index";
 }
 
-const DEFAULT_PREVIEW_STAGE = { width: 1920, height: 1080 };
-
-export function resolveCompositionPreviewScale(input: {
-  cardWidth: number;
-  cardHeight: number;
-  stageWidth: number;
-  stageHeight: number;
-}): number {
-  const safeStageWidth =
-    Number.isFinite(input.stageWidth) && input.stageWidth > 0
-      ? input.stageWidth
-      : DEFAULT_PREVIEW_STAGE.width;
-  const safeStageHeight =
-    Number.isFinite(input.stageHeight) && input.stageHeight > 0
-      ? input.stageHeight
-      : DEFAULT_PREVIEW_STAGE.height;
-  const scaleX = input.cardWidth / safeStageWidth;
-  const scaleY = input.cardHeight / safeStageHeight;
-  return Math.min(scaleX, scaleY);
+export function parseCompositionDurationFromHtml(html: string): number | null {
+  return parseNumericCompositionAttribute(html, "data-duration");
+}
+
+export function parseCompositionDimensionsFromHtml(html: string): {
+  width: number;
+  height: number;
+} {
+  return {
+    width: parseNumericCompositionAttribute(html, "data-width") ?? DEFAULT_COMPOSITION_WIDTH,
+    height: parseNumericCompositionAttribute(html, "data-height") ?? DEFAULT_COMPOSITION_HEIGHT,
+  };
+}
+
+export function getCompositionThumbnailTimeSeconds(duration: number | null | undefined): number {
+  if (!Number.isFinite(duration) || duration == null || duration <= 0) {
+    return DEFAULT_COMPOSITION_THUMBNAIL_TIME_SECONDS;
+  }
+  const time =
+    duration < DEFAULT_COMPOSITION_THUMBNAIL_TIME_SECONDS
+      ? duration / 2
+      : DEFAULT_COMPOSITION_THUMBNAIL_TIME_SECONDS;
+  return Math.round(time * 100) / 100;
 }
 
 function CompCard({
-  projectId,
   comp,
   isActive,
   onSelect,
+  projectId,
+  resolveSourceContent,
 }: {
-  projectId: string;
   comp: string;
   isActive: boolean;
   onSelect: () => void;
+  projectId?: string;
+  resolveSourceContent?: (path: string) => Promise<string>;
 }) {
+  const name = getCompositionDisplayName(comp);
+  const cardRef = useRef<HTMLButtonElement | null>(null);
   const [hovered, setHovered] = useState(false);
-  const [stageSize, setStageSize] = useState(DEFAULT_PREVIEW_STAGE);
-  const hoverTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const handleEnter = () => {
-    hoverTimer.current = setTimeout(() => setHovered(true), 300);
-  };
-  const handleLeave = () => {
-    if (hoverTimer.current) {
-      clearTimeout(hoverTimer.current);
-      hoverTimer.current = null;
-    }
-    setHovered(false);
-  };
-  const name = comp.replace(/^compositions\//, "").replace(/\.html$/, "");
-  const thumbnailUrl = `/api/projects/${projectId}/thumbnail/${comp}?t=2`;
-  const previewUrl = `/api/projects/${projectId}/preview/comp/${comp}`;
-  const previewScale = resolveCompositionPreviewScale({
-    cardWidth: 80,
-    cardHeight: 45,
-    stageWidth: stageSize.width,
-    stageHeight: stageSize.height,
+  const [isVisible, setIsVisible] = useState(false);
+  const [thumbnailUrl, setThumbnailUrl] = useState<string | null>(null);
+  const [thumbnailFailed, setThumbnailFailed] = useState(false);
+  const [sourceMetadata, setSourceMetadata] = useState<CompositionSourceMetadata | null>(null);
+  const shouldLoadThumbnail = shouldRequestThumbnail(DEFAULT_COMPOSITION_THUMBNAIL_MODE, {
+    hovered,
+    visible: isVisible,
   });
 
+  useEffect(() => {
+    const node = cardRef.current;
+    if (!node || typeof IntersectionObserver === "undefined") {
+      setIsVisible(true);
+      return;
+    }
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        setIsVisible(entry?.isIntersecting ?? false);
+      },
+      { rootMargin: "96px 0px" },
+    );
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, []);
+
+  useEffect(() => {
+    if (!shouldLoadThumbnail || !projectId) {
+      return;
+    }
+
+    const controller = new AbortController();
+    let cancelled = false;
+    setThumbnailFailed(false);
+
+    void (async () => {
+      const sourceContent = await readCompositionSourceContent({
+        projectId,
+        path: comp,
+        signal: controller.signal,
+        resolveSourceContent,
+      });
+      if (controller.signal.aborted || cancelled) return;
+
+      const dimensions = parseCompositionDimensionsFromHtml(sourceContent);
+      const metadata = {
+        sourceHash: hashThumbnailSource(sourceContent),
+        duration: parseCompositionDurationFromHtml(sourceContent),
+        width: dimensions.width,
+        height: dimensions.height,
+      };
+      setSourceMetadata(metadata);
+      if (controller.signal.aborted || cancelled) return;
+
+      const thumbnailTime = getCompositionThumbnailTimeSeconds(metadata.duration);
+      const previewUrl = getCompositionPreviewUrl(projectId, comp);
+      const thumbnailRequestUrl = buildCompositionThumbnailUrl({
+        previewUrl,
+        seekTime: thumbnailTime,
+        duration: 0,
+        origin: window.location.origin,
+      });
+      const objectUrl = await getStudioThumbnailService().getThumbnailUrl({
+        key: {
+          projectId,
+          sourcePath: comp,
+          sourceHash: metadata.sourceHash,
+          kind: "composition",
+          timeSeconds: thumbnailTime,
+          width: COMPOSITION_THUMBNAIL_WIDTH,
+          height: COMPOSITION_THUMBNAIL_HEIGHT,
+          devicePixelRatio: window.devicePixelRatio || 1,
+          version: 3,
+        },
+        url: thumbnailRequestUrl,
+        priority: hovered ? "hover" : "idle",
+        signal: controller.signal,
+      });
+      if (!cancelled && objectUrl) setThumbnailUrl(objectUrl);
+    })().catch((error: unknown) => {
+      if (!cancelled && !isAbortError(error)) setThumbnailFailed(true);
+    });
+
+    return () => {
+      cancelled = true;
+      controller.abort();
+    };
+  }, [comp, hovered, projectId, resolveSourceContent, shouldLoadThumbnail]);
+
   return (
-    <div
+    <button
+      type="button"
+      ref={cardRef}
+      data-composition-path={comp}
       onClick={onSelect}
-      onPointerEnter={handleEnter}
-      onPointerLeave={handleLeave}
+      onMouseEnter={() => setHovered(true)}
+      onMouseLeave={() => setHovered(false)}
+      onFocus={() => setHovered(true)}
+      onBlur={() => setHovered(false)}
       className={`w-full text-left px-2 py-1.5 flex items-center gap-2.5 transition-colors cursor-pointer ${
         isActive
           ? "bg-studio-accent/10 border-l-2 border-studio-accent"
           : "border-l-2 border-transparent hover:bg-neutral-800/50"
       }`}
     >
-      <div className="w-20 h-[45px] rounded overflow-hidden bg-neutral-900 flex-shrink-0 relative">
-        {/* Live iframe preview on hover */}
-        {hovered && (
-          <iframe
-            src={previewUrl}
-            sandbox="allow-scripts allow-same-origin"
-            className="absolute left-0 top-0 border-none pointer-events-none"
-            style={{
-              transformOrigin: "0 0",
-              width: stageSize.width,
-              height: stageSize.height,
-              transform: `scale(${previewScale})`,
-            }}
-            onLoad={(e) => {
-              try {
-                const iframe = e.currentTarget;
-                const root = iframe.contentDocument?.querySelector("[data-composition-id]");
-                const width =
-                  Number(root?.getAttribute("data-width")) || DEFAULT_PREVIEW_STAGE.width;
-                const height =
-                  Number(root?.getAttribute("data-height")) || DEFAULT_PREVIEW_STAGE.height;
-                setStageSize({ width, height });
-              } catch {
-                setStageSize(DEFAULT_PREVIEW_STAGE);
-              }
-            }}
-            tabIndex={-1}
-          />
-        )}
-        {/* Static thumbnail — hidden while hovering */}
-        <div
-          className="absolute inset-0 transition-opacity duration-150"
-          style={{ opacity: hovered ? 0 : 1 }}
-        >
+      <div className="relative h-[45px] w-20 flex-shrink-0 overflow-hidden rounded bg-neutral-900 ring-1 ring-white/5">
+        {thumbnailUrl && (
           <img
             src={thumbnailUrl}
-            alt={name}
-            loading="lazy"
-            className="w-full h-full object-contain"
-            onError={(e) => {
-              (e.target as HTMLImageElement).style.display = "none";
-            }}
+            alt=""
+            draggable={false}
+            className="absolute inset-0 h-full w-full object-cover opacity-80"
           />
-        </div>
+        )}
+        <HoverCompositionPreview
+          active={hovered}
+          compositionPath={comp}
+          duration={sourceMetadata?.duration ?? null}
+          height={sourceMetadata?.height ?? DEFAULT_COMPOSITION_HEIGHT}
+          projectId={projectId}
+          width={sourceMetadata?.width ?? DEFAULT_COMPOSITION_WIDTH}
+        />
+        {!thumbnailUrl && (
+          <>
+            <div
+              className="absolute inset-0 opacity-80"
+              style={{
+                backgroundImage:
+                  "linear-gradient(120deg, rgba(60,230,172,0.18), transparent 44%), linear-gradient(180deg, rgba(255,255,255,0.05), rgba(0,0,0,0.2))",
+              }}
+            />
+            <div
+              className="absolute inset-0 opacity-30"
+              style={{
+                backgroundSize: "12px 12px",
+                backgroundImage:
+                  "linear-gradient(rgba(255,255,255,0.08) 1px, transparent 1px), linear-gradient(90deg, rgba(255,255,255,0.08) 1px, transparent 1px)",
+              }}
+            />
+          </>
+        )}
+        {thumbnailFailed && (
+          <div className="absolute right-1 top-1 h-1.5 w-1.5 rounded-full bg-amber-300/70" />
+        )}
       </div>
       <div className="min-w-0 flex-1">
-        <span className="text-[11px] font-medium text-neutral-300 truncate block">{name}</span>
-        <span className="text-[9px] text-neutral-600 truncate block">{comp}</span>
+        <span className="block truncate text-[11px] font-medium text-neutral-300">{name}</span>
+        <span className="block truncate text-[9px] text-neutral-600">{comp}</span>
       </div>
-    </div>
+    </button>
   );
 }
 
 export const CompositionsTab = memo(function CompositionsTab({
-  projectId,
   compositions,
   activeComposition,
   onSelect,
+  projectId,
+  resolveSourceContent,
 }: CompositionsTabProps) {
   if (compositions.length === 0) {
     return (
@@ -145,12 +259,163 @@ export const CompositionsTab = memo(function CompositionsTab({
       {compositions.map((comp) => (
         <CompCard
           key={comp}
-          projectId={projectId}
           comp={comp}
           isActive={activeComposition === comp}
           onSelect={() => onSelect(comp)}
+          projectId={projectId}
+          resolveSourceContent={resolveSourceContent}
         />
       ))}
     </div>
   );
 });
+
+function HoverCompositionPreview({
+  active,
+  compositionPath,
+  duration,
+  height,
+  projectId,
+  width,
+}: {
+  active: boolean;
+  compositionPath: string;
+  duration: number | null;
+  height: number;
+  projectId?: string;
+  width: number;
+}) {
+  const hostRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    if (!active || !projectId) return;
+    const host = hostRef.current;
+    if (!host) return;
+
+    let cancelled = false;
+    let player: HyperframesPlayerElement | null = null;
+    let retryTimer: ReturnType<typeof window.setTimeout> | null = null;
+    let frameHandle = 0;
+
+    const cleanup = () => {
+      if (retryTimer != null) window.clearTimeout(retryTimer);
+      retryTimer = null;
+      if (frameHandle) window.cancelAnimationFrame(frameHandle);
+      frameHandle = 0;
+      const api = readMiniPlayer(player);
+      api?.pause?.();
+      player?.remove();
+      player = null;
+    };
+
+    void import("@hyperframes/player").then(() => {
+      if (cancelled) return;
+      player = document.createElement("hyperframes-player") as HyperframesPlayerElement;
+      player.setAttribute("src", getCompositionPreviewUrl(projectId, compositionPath));
+      player.setAttribute("width", String(width || DEFAULT_COMPOSITION_WIDTH));
+      player.setAttribute("height", String(height || DEFAULT_COMPOSITION_HEIGHT));
+      player.setAttribute("muted", "");
+      player.style.display = "block";
+      player.style.height = "100%";
+      player.style.pointerEvents = "none";
+      player.style.width = "100%";
+      host.replaceChildren(player);
+
+      const startPlayback = () => {
+        if (frameHandle) return;
+        if (retryTimer != null) {
+          window.clearTimeout(retryTimer);
+          retryTimer = null;
+        }
+        const api = readMiniPlayer(player);
+        if (!api) {
+          retryTimer = window.setTimeout(startPlayback, 50);
+          return;
+        }
+        api.pause?.();
+        const runtimeDuration = api.getDuration?.();
+        const loopDuration =
+          duration && duration > 0
+            ? duration
+            : runtimeDuration && runtimeDuration > 0
+              ? runtimeDuration
+              : 3;
+        const seek = api.renderSeek ?? api.seek;
+        if (!seek) return;
+        const startTimeMs = performance.now();
+
+        const tick = () => {
+          if (cancelled) return;
+          const elapsedSeconds = (performance.now() - startTimeMs) / 1000;
+          seek(Math.min(loopDuration, elapsedSeconds % loopDuration));
+          frameHandle = window.requestAnimationFrame(tick);
+        };
+
+        seek(0);
+        frameHandle = window.requestAnimationFrame(tick);
+      };
+
+      const iframe = player.iframeElement;
+      iframe.addEventListener("load", startPlayback, { once: true });
+      retryTimer = window.setTimeout(startPlayback, 80);
+    });
+
+    return () => {
+      cancelled = true;
+      cleanup();
+    };
+  }, [active, compositionPath, duration, height, projectId, width]);
+
+  return (
+    <div
+      aria-hidden="true"
+      className={`absolute inset-0 z-10 overflow-hidden bg-black transition-opacity duration-150 ${
+        active ? "opacity-100" : "pointer-events-none opacity-0"
+      }`}
+    >
+      <div ref={hostRef} className="h-full w-full" />
+    </div>
+  );
+}
+
+function readMiniPlayer(player: HyperframesPlayerElement | null): MiniPlayerApi | null {
+  const api = (player?.iframeElement.contentWindow as (Window & { __player?: unknown }) | null)
+    ?.__player;
+  if (!api || typeof api !== "object") return null;
+  return api as MiniPlayerApi;
+}
+
+async function readCompositionSourceContent({
+  path,
+  projectId,
+  resolveSourceContent,
+  signal,
+}: {
+  path: string;
+  projectId: string;
+  resolveSourceContent?: (path: string) => Promise<string>;
+  signal: AbortSignal;
+}): Promise<string> {
+  if (resolveSourceContent) return resolveSourceContent(path);
+  const response = await fetch(`/api/projects/${projectId}/files/${encodeURIComponent(path)}`, {
+    signal,
+  });
+  if (!response.ok) throw new Error(`Failed to read ${path}`);
+  const data = (await response.json()) as { content?: string };
+  return data.content ?? "";
+}
+
+function parseNumericCompositionAttribute(html: string, attribute: string): number | null {
+  const escaped = attribute.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = new RegExp(`${escaped}\\s*=\\s*["']([^"']+)["']`, "i").exec(html);
+  const value = match?.[1] == null ? Number.NaN : Number.parseFloat(match[1]);
+  return Number.isFinite(value) && value > 0 ? value : null;
+}
+
+function isAbortError(error: unknown): boolean {
+  return (
+    typeof DOMException !== "undefined" &&
+    error instanceof DOMException &&
+    error.name === "AbortError"
+  );
+}
diff --git a/packages/studio/src/components/sidebar/LeftSidebar.tsx b/packages/studio/src/components/sidebar/LeftSidebar.tsx
index a4172888c..cdd266df5 100644
--- a/packages/studio/src/components/sidebar/LeftSidebar.tsx
+++ b/packages/studio/src/components/sidebar/LeftSidebar.tsx
@@ -22,6 +22,7 @@ interface LeftSidebarProps {
   assets: string[];
   activeComposition: string | null;
   onSelectComposition: (comp: string) => void;
+  resolveCompositionSourceContent?: (path: string) => Promise<string>;
   onImportFiles?: (files: FileList, dir?: string) => void;
   fileTree?: string[];
   editingFile?: { path: string; content: string | null } | null;
@@ -45,6 +46,7 @@ export const LeftSidebar = memo(function LeftSidebar({
   assets,
   activeComposition,
   onSelectComposition,
+  resolveCompositionSourceContent,
   onImportFiles,
   fileTree: fileProp,
   editingFile,
@@ -90,73 +92,86 @@ export const LeftSidebar = memo(function LeftSidebar({
       style={{ width }}
     >
       {/* Tabs — Code first */}
-      <div className="flex border-b border-neutral-800/50 flex-shrink-0">
-        <button
-          type="button"
-          onClick={() => selectTab("code")}
-          className={`flex-1 py-2 text-[11px] font-medium transition-colors ${
-            tab === "code"
-              ? "text-neutral-200 border-b-2 border-studio-accent"
-              : "text-neutral-500 hover:text-neutral-400"
-          }`}
-        >
-          Code
-        </button>
-        <button
-          type="button"
-          onClick={() => selectTab("compositions")}
-          className={`flex-1 py-2 text-[11px] font-medium transition-colors ${
-            tab === "compositions"
-              ? "text-neutral-200 border-b-2 border-studio-accent"
-              : "text-neutral-500 hover:text-neutral-400"
-          }`}
-        >
-          Compositions
-        </button>
-        <button
-          type="button"
-          onClick={() => selectTab("assets")}
-          className={`flex-1 py-2 text-[11px] font-medium transition-colors ${
-            tab === "assets"
-              ? "text-neutral-200 border-b-2 border-studio-accent"
-              : "text-neutral-500 hover:text-neutral-400"
-          }`}
-        >
-          Assets
-        </button>
-        {onToggleCollapse && (
-          <button
-            type="button"
-            onClick={onToggleCollapse}
-            className="mx-1 my-1 flex h-7 w-7 flex-shrink-0 items-center justify-center rounded-md border border-transparent text-neutral-500 transition-colors hover:border-neutral-800 hover:bg-neutral-900 hover:text-neutral-300"
-            title="Hide sidebar"
-            aria-label="Hide sidebar"
+      <div className="border-b border-neutral-800/50 px-3 py-3 flex-shrink-0">
+        <div className="relative min-w-0">
+          <div
+            className={`grid min-w-0 gap-1 rounded-[18px] bg-neutral-900 p-1 shadow-[inset_0_1px_0_rgba(255,255,255,0.03)] ${
+              onToggleCollapse ? "pr-9" : ""
+            }`}
+            style={{ gridTemplateColumns: "0.9fr 1.25fr 0.9fr" }}
           >
-            <svg
-              width="14"
-              height="14"
-              viewBox="0 0 24 24"
-              fill="none"
-              stroke="currentColor"
-              strokeWidth="1.5"
-              strokeLinecap="round"
-              strokeLinejoin="round"
-              aria-hidden="true"
+            <button
+              type="button"
+              data-sidebar-tab="code"
+              onClick={() => selectTab("code")}
+              className={`min-w-0 truncate rounded-[14px] px-2 py-2 text-[10px] font-semibold transition-all ${
+                tab === "code"
+                  ? "bg-neutral-800 text-white"
+                  : "text-neutral-500 hover:text-neutral-200"
+              }`}
             >
-              <path d="m14 7-5 5 5 5" />
-              <path d="M19 4v16" />
-            </svg>
-          </button>
-        )}
+              Code
+            </button>
+            <button
+              type="button"
+              data-sidebar-tab="compositions"
+              onClick={() => selectTab("compositions")}
+              className={`min-w-0 truncate rounded-[14px] px-2 py-2 text-[10px] font-semibold transition-all ${
+                tab === "compositions"
+                  ? "bg-neutral-800 text-white"
+                  : "text-neutral-500 hover:text-neutral-200"
+              }`}
+            >
+              Compositions
+            </button>
+            <button
+              type="button"
+              data-sidebar-tab="assets"
+              onClick={() => selectTab("assets")}
+              className={`min-w-0 truncate rounded-[14px] px-2 py-2 text-[10px] font-semibold transition-all ${
+                tab === "assets"
+                  ? "bg-neutral-800 text-white"
+                  : "text-neutral-500 hover:text-neutral-200"
+              }`}
+            >
+              Assets
+            </button>
+          </div>
+          {onToggleCollapse && (
+            <button
+              type="button"
+              onClick={onToggleCollapse}
+              className="absolute right-1 top-1/2 flex h-7 w-7 -translate-y-1/2 items-center justify-center rounded-md border border-transparent text-neutral-500 transition-colors hover:border-neutral-800 hover:bg-neutral-950 hover:text-neutral-300"
+              title="Hide sidebar"
+              aria-label="Hide sidebar"
+            >
+              <svg
+                width="14"
+                height="14"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden="true"
+              >
+                <path d="m14 7-5 5 5 5" />
+                <path d="M19 4v16" />
+              </svg>
+            </button>
+          )}
+        </div>
       </div>
 
       {/* Tab content */}
       {tab === "compositions" && (
         <CompositionsTab
-          projectId={projectId}
           compositions={compositions}
           activeComposition={activeComposition}
           onSelect={onSelectComposition}
+          projectId={projectId}
+          resolveSourceContent={resolveCompositionSourceContent}
         />
       )}
       {tab === "assets" && (
diff --git a/packages/studio/src/hooks/usePersistentEditHistory.test.ts b/packages/studio/src/hooks/usePersistentEditHistory.test.ts
new file mode 100644
index 000000000..132f94af4
--- /dev/null
+++ b/packages/studio/src/hooks/usePersistentEditHistory.test.ts
@@ -0,0 +1,255 @@
+import { describe, expect, it } from "vitest";
+import { createEmptyEditHistory } from "../utils/editHistory";
+import type { EditHistoryStorageAdapter } from "../utils/editHistoryStorage";
+import { createMemoryEditHistoryStorage } from "../utils/editHistoryStorage";
+import {
+  createPersistentEditHistoryController,
+  createPersistentEditHistoryStore,
+} from "./usePersistentEditHistory";
+
+describe("createPersistentEditHistoryController", () => {
+  it("records history and reloads it for the same project", async () => {
+    const storage = createMemoryEditHistoryStorage();
+    const first = await createPersistentEditHistoryController({
+      projectId: "project-1",
+      storage,
+      now: () => 100,
+      onChange: () => {},
+    });
+
+    await first.recordEdit({
+      label: "Move layer",
+      kind: "manual",
+      files: { "index.html": { before: "a", after: "b" } },
+    });
+
+    const second = await createPersistentEditHistoryController({
+      projectId: "project-1",
+      storage,
+      now: () => 200,
+      onChange: () => {},
+    });
+
+    expect(second.snapshot().canUndo).toBe(true);
+    expect(second.snapshot().undoLabel).toBe("Move layer");
+    expect(second.snapshot().undoPaths).toEqual(["index.html"]);
+  });
+
+  it("undo applies files through the provided callback and persists redo state", async () => {
+    const storage = createMemoryEditHistoryStorage();
+    const controller = await createPersistentEditHistoryController({
+      projectId: "project-1",
+      storage,
+      now: () => 100,
+      onChange: () => {},
+    });
+    await controller.recordEdit({
+      label: "Move layer",
+      kind: "manual",
+      files: { "index.html": { before: "a", after: "b" } },
+    });
+
+    const result = await controller.undo({
+      readFile: async (path) => {
+        expect(path).toBe("index.html");
+        return "b";
+      },
+      writeFile: async (path, content) => {
+        expect(path).toBe("index.html");
+        expect(content).toBe("a");
+      },
+    });
+    expect(result.ok).toBe(true);
+
+    expect(controller.snapshot().canUndo).toBe(false);
+    expect(controller.snapshot().canRedo).toBe(true);
+    expect(controller.snapshot().redoPaths).toEqual(["index.html"]);
+  });
+
+  it("keeps in-memory history when storage saves fail", async () => {
+    const storage: EditHistoryStorageAdapter = {
+      async get() {
+        return null;
+      },
+      async set() {
+        throw new Error("IndexedDB unavailable");
+      },
+      async delete() {},
+    };
+    const controller = await createPersistentEditHistoryController({
+      projectId: "project-1",
+      storage,
+      now: () => 100,
+      onChange: () => {},
+    });
+
+    await expect(
+      controller.recordEdit({
+        label: "Move layer",
+        kind: "manual",
+        files: { "index.html": { before: "a", after: "b" } },
+      }),
+    ).resolves.toBeUndefined();
+
+    expect(controller.snapshot().canUndo).toBe(true);
+  });
+
+  it("serializes concurrent record edits against the latest state", async () => {
+    const storage = createMemoryEditHistoryStorage();
+    let timestamp = 100;
+    const store = createPersistentEditHistoryStore({
+      projectId: "project-1",
+      storage,
+      initialState: createEmptyEditHistory(),
+      now: () => timestamp++,
+      onChange: () => {},
+    });
+
+    await Promise.all([
+      store.recordEdit({
+        label: "Move layer",
+        kind: "manual",
+        files: { "index.html": { before: "a", after: "b" } },
+      }),
+      store.recordEdit({
+        label: "Resize layer",
+        kind: "manual",
+        files: { "index.html": { before: "b", after: "c" } },
+      }),
+    ]);
+
+    expect(store.snapshot().state.undo.map((entry) => entry.label)).toEqual([
+      "Move layer",
+      "Resize layer",
+    ]);
+  });
+
+  it("still coalesces concurrent source edits that share a coalesce key", async () => {
+    const storage = createMemoryEditHistoryStorage();
+    let timestamp = 100;
+    const store = createPersistentEditHistoryStore({
+      projectId: "project-1",
+      storage,
+      initialState: createEmptyEditHistory(),
+      now: () => timestamp++,
+      onChange: () => {},
+    });
+
+    await Promise.all([
+      store.recordEdit({
+        label: "Edit source",
+        kind: "source",
+        coalesceKey: "source:index.html",
+        files: { "index.html": { before: "a", after: "b" } },
+      }),
+      store.recordEdit({
+        label: "Edit source",
+        kind: "source",
+        coalesceKey: "source:index.html",
+        files: { "index.html": { before: "b", after: "c" } },
+      }),
+    ]);
+
+    expect(store.snapshot().state.undo).toHaveLength(1);
+    expect(store.snapshot().state.undo[0].files["index.html"].before).toBe("a");
+    expect(store.snapshot().state.undo[0].files["index.html"].after).toBe("c");
+  });
+
+  it("reads undo hashes from the live top entry during queued undo calls", async () => {
+    const storage = createMemoryEditHistoryStorage();
+    let timestamp = 100;
+    const store = createPersistentEditHistoryStore({
+      projectId: "project-1",
+      storage,
+      initialState: createEmptyEditHistory(),
+      now: () => timestamp++,
+      onChange: () => {},
+    });
+    await store.recordEdit({
+      label: "Edit first file",
+      kind: "manual",
+      files: { "first.html": { before: "first-before", after: "first-after" } },
+    });
+    await store.recordEdit({
+      label: "Edit second file",
+      kind: "manual",
+      files: { "second.html": { before: "second-before", after: "second-after" } },
+    });
+
+    const files: Record<string, string> = {
+      "first.html": "first-after",
+      "second.html": "second-after",
+    };
+    const readPaths: string[] = [];
+
+    await Promise.all([
+      store.undo({
+        readFile: async (path) => {
+          readPaths.push(path);
+          return files[path];
+        },
+        writeFile: async (path, content) => {
+          files[path] = content;
+        },
+      }),
+      store.undo({
+        readFile: async (path) => {
+          readPaths.push(path);
+          return files[path];
+        },
+        writeFile: async (path, content) => {
+          files[path] = content;
+        },
+      }),
+    ]);
+
+    expect(readPaths).toEqual(["second.html", "first.html"]);
+    expect(files).toEqual({
+      "first.html": "first-before",
+      "second.html": "second-before",
+    });
+    expect(store.snapshot().canUndo).toBe(false);
+    expect(store.snapshot().canRedo).toBe(true);
+  });
+
+  it("rolls back files when an undo write fails partway through", async () => {
+    const storage = createMemoryEditHistoryStorage();
+    const store = createPersistentEditHistoryStore({
+      projectId: "project-1",
+      storage,
+      initialState: createEmptyEditHistory(),
+      now: () => 100,
+      onChange: () => {},
+    });
+    await store.recordEdit({
+      label: "Edit files",
+      kind: "manual",
+      files: {
+        "first.html": { before: "first-before", after: "first-after" },
+        "second.html": { before: "second-before", after: "second-after" },
+      },
+    });
+
+    const files: Record<string, string> = {
+      "first.html": "first-after",
+      "second.html": "second-after",
+    };
+    const result = store.undo({
+      readFile: async (path) => files[path],
+      writeFile: async (path, content) => {
+        if (path === "second.html" && content === "second-before") {
+          throw new Error("write failed");
+        }
+        files[path] = content;
+      },
+    });
+
+    await expect(result).rejects.toThrow("write failed");
+    expect(files).toEqual({
+      "first.html": "first-after",
+      "second.html": "second-after",
+    });
+    expect(store.snapshot().undoLabel).toBe("Edit files");
+    expect(store.snapshot().canRedo).toBe(false);
+  });
+});
diff --git a/packages/studio/src/hooks/usePersistentEditHistory.ts b/packages/studio/src/hooks/usePersistentEditHistory.ts
new file mode 100644
index 000000000..b2f0a1cf2
--- /dev/null
+++ b/packages/studio/src/hooks/usePersistentEditHistory.ts
@@ -0,0 +1,336 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  buildEditHistoryEntry,
+  createEmptyEditHistory,
+  hashEditHistoryContent,
+  pushEditHistoryEntry,
+  redoEditHistory,
+  undoEditHistory,
+  type BuildEditHistoryEntryInput,
+  type EditHistoryKind,
+  type EditHistoryState,
+} from "../utils/editHistory";
+import {
+  createIndexedDbEditHistoryStorage,
+  loadEditHistoryState,
+  saveEditHistoryState,
+  type EditHistoryStorageAdapter,
+} from "../utils/editHistoryStorage";
+
+interface RecordEditInput {
+  label: string;
+  kind: EditHistoryKind;
+  coalesceKey?: string;
+  files: BuildEditHistoryEntryInput["files"];
+}
+
+interface ApplyCallbacks {
+  readFile: (path: string) => Promise<string>;
+  writeFile: (path: string, content: string) => Promise<void>;
+}
+
+interface UsePersistentEditHistoryOptions {
+  projectId: string | null;
+  storage?: EditHistoryStorageAdapter;
+  now?: () => number;
+}
+
+interface ApplyResult {
+  ok: boolean;
+  reason?: "empty" | "content-mismatch";
+  label?: string;
+}
+
+interface PersistentEditHistoryStoreOptions {
+  projectId: string;
+  storage: EditHistoryStorageAdapter;
+  initialState: EditHistoryState;
+  now?: () => number;
+  onChange: (state: EditHistoryState) => void;
+}
+
+type EditHistoryMutation<T> = (state: EditHistoryState) => Promise<{
+  state: EditHistoryState;
+  result: T;
+}>;
+
+function createEntryId(now: number): string {
+  return `edit-${now.toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function snapshotEditHistoryState(state: EditHistoryState) {
+  const undoEntry = state.undo[state.undo.length - 1] ?? null;
+  const redoEntry = state.redo[state.redo.length - 1] ?? null;
+  return {
+    canUndo: Boolean(undoEntry),
+    canRedo: Boolean(redoEntry),
+    undoLabel: undoEntry?.label ?? null,
+    redoLabel: redoEntry?.label ?? null,
+    undoPaths: undoEntry ? Object.keys(undoEntry.files) : [],
+    redoPaths: redoEntry ? Object.keys(redoEntry.files) : [],
+    state,
+  };
+}
+
+async function readCurrentFileHashes(
+  paths: string[],
+  readFile: (path: string) => Promise<string>,
+): Promise<{
+  currentFiles: Record<string, string>;
+  currentHashes: Record<string, string>;
+}> {
+  const currentFiles: Record<string, string> = {};
+  const currentHashes: Record<string, string> = {};
+  for (const path of paths) {
+    const content = await readFile(path);
+    currentFiles[path] = content;
+    currentHashes[path] = hashEditHistoryContent(content);
+  }
+  return { currentFiles, currentHashes };
+}
+
+async function writeFilesWithRollback({
+  files,
+  rollbackFiles,
+  writeFile,
+}: {
+  files: Record<string, string>;
+  rollbackFiles: Record<string, string>;
+  writeFile: (path: string, content: string) => Promise<void>;
+}): Promise<void> {
+  const writtenPaths: string[] = [];
+  try {
+    for (const [path, content] of Object.entries(files)) {
+      await writeFile(path, content);
+      writtenPaths.push(path);
+    }
+  } catch (error) {
+    try {
+      for (const path of writtenPaths.reverse()) {
+        await writeFile(path, rollbackFiles[path]);
+      }
+    } catch (rollbackError) {
+      throw new AggregateError(
+        [error, rollbackError],
+        "Failed to apply edit history and rollback did not complete",
+      );
+    }
+    throw error;
+  }
+}
+
+export function createPersistentEditHistoryStore({
+  projectId,
+  storage,
+  initialState,
+  now = Date.now,
+  onChange,
+}: PersistentEditHistoryStoreOptions) {
+  let state = initialState;
+  let queue = Promise.resolve();
+
+  const save = async (nextState: EditHistoryState) => {
+    state = nextState;
+    onChange(nextState);
+    try {
+      await saveEditHistoryState(storage, projectId, nextState);
+    } catch {
+      // Keep in-memory history usable when IndexedDB is unavailable.
+    }
+  };
+
+  const mutate = async <T>(mutation: EditHistoryMutation<T>): Promise<T> => {
+    const run = queue.then(async () => {
+      const { state: nextState, result } = await mutation(state);
+      if (nextState !== state) await save(nextState);
+      return result;
+    });
+    queue = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    return run;
+  };
+
+  return {
+    snapshot: () => snapshotEditHistoryState(state),
+    async recordEdit(input: RecordEditInput) {
+      await mutate<void>(async (currentState) => {
+        const timestamp = now();
+        const entry = buildEditHistoryEntry({
+          ...input,
+          id: createEntryId(timestamp),
+          projectId,
+          now: timestamp,
+        });
+        return {
+          state: pushEditHistoryEntry(currentState, entry),
+          result: undefined,
+        };
+      });
+    },
+    async undo(callbacks: ApplyCallbacks): Promise<ApplyResult> {
+      return mutate<ApplyResult>(async (currentState) => {
+        const entry = currentState.undo[currentState.undo.length - 1];
+        if (!entry) {
+          return {
+            state: currentState,
+            result: { ok: false, reason: "empty" },
+          };
+        }
+        const { currentFiles, currentHashes } = await readCurrentFileHashes(
+          Object.keys(entry.files),
+          callbacks.readFile,
+        );
+        const result = undoEditHistory(currentState, currentHashes, now());
+        if (!result.ok) {
+          return {
+            state: currentState,
+            result: { ok: false, reason: result.reason },
+          };
+        }
+        await writeFilesWithRollback({
+          files: result.filesToWrite,
+          rollbackFiles: currentFiles,
+          writeFile: callbacks.writeFile,
+        });
+        return {
+          state: result.state,
+          result: { ok: true, label: result.entry.label },
+        };
+      });
+    },
+    async redo(callbacks: ApplyCallbacks): Promise<ApplyResult> {
+      return mutate<ApplyResult>(async (currentState) => {
+        const entry = currentState.redo[currentState.redo.length - 1];
+        if (!entry) {
+          return {
+            state: currentState,
+            result: { ok: false, reason: "empty" },
+          };
+        }
+        const { currentFiles, currentHashes } = await readCurrentFileHashes(
+          Object.keys(entry.files),
+          callbacks.readFile,
+        );
+        const result = redoEditHistory(currentState, currentHashes, now());
+        if (!result.ok) {
+          return {
+            state: currentState,
+            result: { ok: false, reason: result.reason },
+          };
+        }
+        await writeFilesWithRollback({
+          files: result.filesToWrite,
+          rollbackFiles: currentFiles,
+          writeFile: callbacks.writeFile,
+        });
+        return {
+          state: result.state,
+          result: { ok: true, label: result.entry.label },
+        };
+      });
+    },
+  };
+}
+
+export async function createPersistentEditHistoryController({
+  projectId,
+  storage,
+  now = Date.now,
+  onChange,
+}: {
+  projectId: string;
+  storage: EditHistoryStorageAdapter;
+  now?: () => number;
+  onChange: (state: EditHistoryState) => void;
+}) {
+  let state = await loadEditHistoryState(storage, projectId);
+  const store = createPersistentEditHistoryStore({
+    projectId,
+    storage,
+    initialState: state,
+    now,
+    onChange: (nextState) => {
+      state = nextState;
+      onChange(nextState);
+    },
+  });
+
+  return store;
+}
+
+export function usePersistentEditHistory(options: UsePersistentEditHistoryOptions) {
+  const storage = useMemo(
+    () => options.storage ?? createIndexedDbEditHistoryStorage(),
+    [options.storage],
+  );
+  const now = options.now ?? Date.now;
+  const [state, setState] = useState<EditHistoryState>(() => createEmptyEditHistory());
+  const [loaded, setLoaded] = useState(false);
+  const projectId = options.projectId;
+  const storeRef = useRef<ReturnType<typeof createPersistentEditHistoryStore> | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    const emptyState = createEmptyEditHistory();
+    storeRef.current = null;
+    setState(emptyState);
+    setLoaded(false);
+    if (!projectId) {
+      setLoaded(true);
+      return;
+    }
+
+    loadEditHistoryState(storage, projectId)
+      .then((loadedState) => {
+        if (cancelled) return;
+        storeRef.current = createPersistentEditHistoryStore({
+          projectId,
+          storage,
+          initialState: loadedState,
+          now,
+          onChange: setState,
+        });
+        setState(loadedState);
+      })
+      .catch(() => {
+        if (cancelled) return;
+        storeRef.current = createPersistentEditHistoryStore({
+          projectId,
+          storage,
+          initialState: emptyState,
+          now,
+          onChange: setState,
+        });
+        setState(emptyState);
+      })
+      .finally(() => {
+        if (!cancelled) setLoaded(true);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [now, projectId, storage]);
+
+  const recordEdit = useCallback(async (input: RecordEditInput) => {
+    await storeRef.current?.recordEdit(input);
+  }, []);
+
+  const undo = useCallback(async (callbacks: ApplyCallbacks): Promise<ApplyResult> => {
+    return storeRef.current?.undo(callbacks) ?? { ok: false, reason: "empty" };
+  }, []);
+
+  const redo = useCallback(async (callbacks: ApplyCallbacks): Promise<ApplyResult> => {
+    return storeRef.current?.redo(callbacks) ?? { ok: false, reason: "empty" };
+  }, []);
+
+  return {
+    loaded,
+    ...snapshotEditHistoryState(state),
+    recordEdit,
+    undo,
+    redo,
+  };
+}
diff --git a/packages/studio/src/hooks/useSharedEditHistory.ts b/packages/studio/src/hooks/useSharedEditHistory.ts
new file mode 100644
index 000000000..94af48635
--- /dev/null
+++ b/packages/studio/src/hooks/useSharedEditHistory.ts
@@ -0,0 +1,203 @@
+import { useCallback, useEffect, useState } from "react";
+import type {
+  BuildEditHistoryEntryInput,
+  EditHistoryKind,
+  ProjectHistorySummary,
+} from "@hyperframes/core/studio-history";
+
+interface RecordEditInput {
+  label: string;
+  kind: EditHistoryKind;
+  coalesceKey?: string;
+  files: BuildEditHistoryEntryInput["files"];
+}
+
+interface ApplyCallbacks {
+  readFile: (path: string) => Promise<string>;
+  writeFile: (path: string, content: string) => Promise<void>;
+}
+
+interface UseSharedEditHistoryOptions {
+  projectId: string | null;
+}
+
+interface ApplyResult {
+  ok: boolean;
+  reason?: "empty" | "content-mismatch";
+  label?: string;
+}
+
+interface SharedHistorySnapshot {
+  loaded: boolean;
+  canUndo: boolean;
+  canRedo: boolean;
+  undoLabel: string | null;
+  redoLabel: string | null;
+  revision: number;
+}
+
+const EMPTY_HISTORY: SharedHistorySnapshot = {
+  loaded: false,
+  canUndo: false,
+  canRedo: false,
+  undoLabel: null,
+  redoLabel: null,
+  revision: 0,
+};
+
+function toSnapshot(summary: ProjectHistorySummary, loaded = true): SharedHistorySnapshot {
+  return {
+    loaded,
+    canUndo: summary.canUndo,
+    canRedo: summary.canRedo,
+    undoLabel: summary.undoLabel ?? null,
+    redoLabel: summary.redoLabel ?? null,
+    revision: summary.revision,
+  };
+}
+
+async function readJson(response: Response): Promise<unknown> {
+  return response.json().catch(() => null);
+}
+
+function readApplyResult(data: unknown, fallbackOk: boolean): ApplyResult {
+  if (typeof data !== "object" || data === null) return { ok: fallbackOk };
+  const result = data as { ok?: unknown; error?: unknown; reason?: unknown; label?: unknown };
+  if (result.ok === true) {
+    return {
+      ok: true,
+      label: typeof result.label === "string" ? result.label : undefined,
+    };
+  }
+  const reason = result.reason ?? result.error;
+  return {
+    ok: false,
+    reason: reason === "content-mismatch" || reason === "empty" ? reason : undefined,
+  };
+}
+
+function dispatchProjectHistoryEvent(data: unknown): void {
+  window.dispatchEvent(new CustomEvent("hf:project-history-event", { detail: data }));
+}
+
+function refreshPreviewFrames(): void {
+  for (const frame of document.querySelectorAll("iframe")) {
+    if (!(frame instanceof HTMLIFrameElement) || !frame.src.includes("/preview/")) continue;
+    const url = new URL(frame.src);
+    url.searchParams.set("hfRefresh", String(Date.now()));
+    frame.src = url.toString();
+  }
+}
+
+export function useSharedEditHistory(options: UseSharedEditHistoryOptions) {
+  const [snapshot, setSnapshot] = useState<SharedHistorySnapshot>(EMPTY_HISTORY);
+  const projectId = options.projectId;
+
+  useEffect(() => {
+    if (!projectId) {
+      setSnapshot({ ...EMPTY_HISTORY, loaded: true });
+      return;
+    }
+
+    let cancelled = false;
+    setSnapshot(EMPTY_HISTORY);
+
+    fetch(`/api/projects/${projectId}/history`)
+      .then(async (response) => {
+        if (!response.ok) throw new Error("Failed to load project history");
+        return (await response.json()) as ProjectHistorySummary;
+      })
+      .then((summary) => {
+        if (!cancelled) setSnapshot(toSnapshot(summary));
+      })
+      .catch(() => {
+        if (!cancelled) setSnapshot({ ...EMPTY_HISTORY, loaded: true });
+      });
+
+    const events = new EventSource(`/api/projects/${projectId}/events`);
+    events.addEventListener("project-edit", (event) => {
+      const data = JSON.parse(event.data) as { history?: ProjectHistorySummary };
+      dispatchProjectHistoryEvent(data);
+      refreshPreviewFrames();
+      if (!cancelled && data.history) setSnapshot(toSnapshot(data.history));
+    });
+    events.addEventListener("history-updated", (event) => {
+      const data = JSON.parse(event.data) as { history?: ProjectHistorySummary };
+      dispatchProjectHistoryEvent(data);
+      refreshPreviewFrames();
+      if (!cancelled && data.history) setSnapshot(toSnapshot(data.history));
+    });
+    events.addEventListener("file-change", (event) => {
+      dispatchProjectHistoryEvent(JSON.parse(event.data));
+      refreshPreviewFrames();
+    });
+
+    return () => {
+      cancelled = true;
+      events.close();
+    };
+  }, [projectId]);
+
+  const recordEdit = useCallback(
+    async (input: RecordEditInput) => {
+      if (!projectId) return;
+      const response = await fetch(`/api/projects/${projectId}/history/record-applied`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          ...input,
+          actor: { type: "user" },
+        }),
+      });
+      const data = await readJson(response);
+      if (!response.ok) throw new Error("Failed to record project edit");
+      if (typeof data === "object" && data !== null && "history" in data) {
+        const history = data.history;
+        if (typeof history === "object" && history !== null) {
+          dispatchProjectHistoryEvent(data);
+          refreshPreviewFrames();
+          setSnapshot(toSnapshot(history as ProjectHistorySummary));
+        }
+      }
+    },
+    [projectId],
+  );
+
+  const applyTransition = useCallback(
+    async (direction: "undo" | "redo"): Promise<ApplyResult> => {
+      if (!projectId) return { ok: false, reason: "empty" };
+      const response = await fetch(`/api/projects/${projectId}/history/${direction}`, {
+        method: "POST",
+      });
+      const data = await readJson(response);
+      if (typeof data === "object" && data !== null && "history" in data) {
+        const history = data.history;
+        if (typeof history === "object" && history !== null) {
+          dispatchProjectHistoryEvent(data);
+          refreshPreviewFrames();
+          setSnapshot(toSnapshot(history as ProjectHistorySummary));
+        }
+      }
+      if (!response.ok) return readApplyResult(data, false);
+      return readApplyResult(data, true);
+    },
+    [projectId],
+  );
+
+  const undo = useCallback(
+    async (_callbacks: ApplyCallbacks): Promise<ApplyResult> => applyTransition("undo"),
+    [applyTransition],
+  );
+
+  const redo = useCallback(
+    async (_callbacks: ApplyCallbacks): Promise<ApplyResult> => applyTransition("redo"),
+    [applyTransition],
+  );
+
+  return {
+    ...snapshot,
+    recordEdit,
+    undo,
+    redo,
+  };
+}
diff --git a/packages/studio/src/icons/SystemIcons.tsx b/packages/studio/src/icons/SystemIcons.tsx
index d63ad8cae..00b4456d3 100644
--- a/packages/studio/src/icons/SystemIcons.tsx
+++ b/packages/studio/src/icons/SystemIcons.tsx
@@ -54,6 +54,7 @@ import {
   ClipboardText,
   ArrowCounterClockwise,
   Camera as PhCamera,
+  ArrowClockwise,
   Gear,
 } from "@phosphor-icons/react";
 import type { Icon as PhosphorIcon, IconProps as PhosphorIconProps } from "@phosphor-icons/react";
@@ -129,4 +130,5 @@ export const ChevronRight = makeIcon(CaretRight);
 export const ClipboardList = makeIcon(ClipboardText);
 export const RotateCcw = makeIcon(ArrowCounterClockwise);
 export const Camera = makeIcon(PhCamera);
+export const RotateCw = makeIcon(ArrowClockwise);
 export const Settings = makeIcon(Gear);
diff --git a/packages/studio/src/player/components/AudioWaveform.tsx b/packages/studio/src/player/components/AudioWaveform.tsx
index 01082ed18..71f4b1850 100644
--- a/packages/studio/src/player/components/AudioWaveform.tsx
+++ b/packages/studio/src/player/components/AudioWaveform.tsx
@@ -157,7 +157,11 @@ export const AudioWaveform = memo(function AudioWaveform({
   );
 
   return (
-    <div ref={setContainerRef} className="absolute inset-0 overflow-hidden">
+    <div
+      ref={setContainerRef}
+      data-audio-waveform="true"
+      className="absolute inset-0 overflow-hidden"
+    >
       <div ref={barsRef} className="absolute left-0 right-0 bottom-0" style={{ top: 16 }} />
       {/* Shimmer while decoding */}
       {!peaks && (
diff --git a/packages/studio/src/player/components/CompositionThumbnail.test.ts b/packages/studio/src/player/components/CompositionThumbnail.test.ts
new file mode 100644
index 000000000..0c23d3d48
--- /dev/null
+++ b/packages/studio/src/player/components/CompositionThumbnail.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { buildCompositionThumbnailUrl } from "./CompositionThumbnail";
+
+describe("buildCompositionThumbnailUrl", () => {
+  it("includes selector and occurrence index for precise element thumbnails", () => {
+    expect(
+      buildCompositionThumbnailUrl({
+        previewUrl: "/api/projects/demo/preview",
+        seekTime: 1,
+        duration: 2,
+        selector: ".card",
+        selectorIndex: 2,
+        origin: "http://localhost:3000",
+      }),
+    ).toBe(
+      "http://localhost:3000/api/projects/demo/thumbnail/index.html?t=2.00&v=v2&selector=.card&selectorIndex=2",
+    );
+  });
+});
diff --git a/packages/studio/src/player/components/CompositionThumbnail.tsx b/packages/studio/src/player/components/CompositionThumbnail.tsx
index 6fdcecc30..a80e04aaf 100644
--- a/packages/studio/src/player/components/CompositionThumbnail.tsx
+++ b/packages/studio/src/player/components/CompositionThumbnail.tsx
@@ -7,6 +7,7 @@ interface CompositionThumbnailProps {
   labelColor: string;
   accentColor?: string;
   selector?: string;
+  selectorIndex?: number;
   seekTime?: number;
   duration?: number;
   width?: number;
@@ -16,12 +17,44 @@ interface CompositionThumbnailProps {
 const CLIP_HEIGHT = 66;
 const THUMBNAIL_URL_VERSION = "v2";
 
+export function buildCompositionThumbnailUrl({
+  previewUrl,
+  seekTime = 2,
+  duration = 5,
+  selector,
+  selectorIndex,
+  origin,
+}: {
+  previewUrl: string;
+  seekTime?: number;
+  duration?: number;
+  selector?: string;
+  selectorIndex?: number;
+  origin: string;
+}): string {
+  const thumbnailBase = previewUrl
+    .replace("/preview/comp/", "/thumbnail/")
+    .replace(/\/preview$/, "/thumbnail/index.html");
+  const midTime = seekTime + duration / 2;
+  const thumbnailUrl = new URL(thumbnailBase, origin);
+  thumbnailUrl.searchParams.set("t", midTime.toFixed(2));
+  thumbnailUrl.searchParams.set("v", THUMBNAIL_URL_VERSION);
+  if (selector) {
+    thumbnailUrl.searchParams.set("selector", selector);
+    if (selectorIndex != null && selectorIndex > 0) {
+      thumbnailUrl.searchParams.set("selectorIndex", String(selectorIndex));
+    }
+  }
+  return thumbnailUrl.toString();
+}
+
 export const CompositionThumbnail = memo(function CompositionThumbnail({
   previewUrl,
   label,
   labelColor,
   accentColor = "#6B7280",
   selector,
+  selectorIndex,
   seekTime = 2,
   duration = 5,
 }: CompositionThumbnailProps) {
@@ -48,15 +81,14 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
     roRef.current?.disconnect();
   });
 
-  const thumbnailBase = previewUrl
-    .replace("/preview/comp/", "/thumbnail/")
-    .replace(/\/preview$/, "/thumbnail/index.html");
-  const midTime = seekTime + duration / 2;
-  const thumbnailUrl = new URL(thumbnailBase, window.location.origin);
-  thumbnailUrl.searchParams.set("t", midTime.toFixed(2));
-  thumbnailUrl.searchParams.set("v", THUMBNAIL_URL_VERSION);
-  if (selector) thumbnailUrl.searchParams.set("selector", selector);
-  const url = thumbnailUrl.toString();
+  const url = buildCompositionThumbnailUrl({
+    previewUrl,
+    seekTime,
+    duration,
+    selector,
+    selectorIndex,
+    origin: window.location.origin,
+  });
   const frameW = Math.max(48, Math.round(CLIP_HEIGHT * aspect));
   const frameCount = containerWidth > 0 ? Math.max(1, Math.ceil(containerWidth / frameW)) : 1;
 
@@ -66,7 +98,7 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
         src={url}
         alt=""
         draggable={false}
-        loading="lazy"
+        loading="eager"
         onLoad={(e) => {
           const img = e.currentTarget;
           if (img.naturalWidth > 0 && img.naturalHeight > 0) {
diff --git a/packages/studio/src/player/components/EditModal.tsx b/packages/studio/src/player/components/EditModal.tsx
index 067426c08..dae44f2d2 100644
--- a/packages/studio/src/player/components/EditModal.tsx
+++ b/packages/studio/src/player/components/EditModal.tsx
@@ -3,6 +3,7 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import { usePlayerStore } from "../store/playerStore";
 import { formatTime } from "../lib/time";
 import { buildPromptCopyText, buildTimelineAgentPrompt } from "./timelineEditing";
+import { copyTextToClipboard } from "../../utils/clipboard";
 
 interface EditPopoverProps {
   rangeStart: number;
@@ -62,16 +63,8 @@ export function EditPopover({ rangeStart, rangeEnd, anchorX, anchorY, onClose }:
   }, [start, end, elementsInRange, prompt]);
 
   const handleCopy = useCallback(async () => {
-    try {
-      await navigator.clipboard.writeText(buildClipboardText());
-    } catch {
-      const ta = document.createElement("textarea");
-      ta.value = buildClipboardText();
-      document.body.appendChild(ta);
-      ta.select();
-      document.execCommand("copy");
-      document.body.removeChild(ta);
-    }
+    const copied = await copyTextToClipboard(buildClipboardText());
+    if (!copied) return;
     setCopiedAgentPrompt(true);
     setTimeout(() => {
       setCopiedAgentPrompt(false);
@@ -82,16 +75,8 @@ export function EditPopover({ rangeStart, rangeEnd, anchorX, anchorY, onClose }:
   const handleCopyPrompt = useCallback(async () => {
     const promptText = buildPromptCopyText(prompt);
     if (!promptText) return;
-    try {
-      await navigator.clipboard.writeText(promptText);
-    } catch {
-      const ta = document.createElement("textarea");
-      ta.value = promptText;
-      document.body.appendChild(ta);
-      ta.select();
-      document.execCommand("copy");
-      document.body.removeChild(ta);
-    }
+    const copied = await copyTextToClipboard(promptText);
+    if (!copied) return;
     setCopiedPromptOnly(true);
     setTimeout(() => {
       setCopiedPromptOnly(false);
diff --git a/packages/studio/src/player/components/Player.tsx b/packages/studio/src/player/components/Player.tsx
index cda592bdd..eb42a43a4 100644
--- a/packages/studio/src/player/components/Player.tsx
+++ b/packages/studio/src/player/components/Player.tsx
@@ -1,36 +1,29 @@
 import { forwardRef, useRef, useState } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
-// NOTE: importing "@hyperframes/player" registers a class extending HTMLElement
-// at module load, which throws under SSR. Defer the import to the mount effect
-// so it only runs in the browser.
 
 interface PlayerProps {
   projectId?: string;
   directUrl?: string;
   onLoad: () => void;
   portrait?: boolean;
+  style?: React.CSSProperties;
 }
 
 interface HyperframesPlayerElement extends HTMLElement {
   iframeElement: HTMLIFrameElement;
 }
 
-/**
- * Readiness check for a Lottie animation instance. Duck-types both supported
- * player shapes:
- *
- * - `lottie-web` exposes a boolean `isLoaded` on `AnimationItem`.
- * - `@dotlottie/player-component` doesn't; we infer readiness from
- *   `totalFrames > 0` since that value is only populated once the animation
- *   JSON has been parsed.
- *
- * Kept in sync with the runtime adapter's own checks in
- * `@hyperframes/core/runtime/adapters/lottie.ts` — that module would be a
- * more canonical home for the helper, but importing from the core package's
- * root index pulls Node-only submodules (path, url) into this browser bundle
- * and breaks Vite. If the helper grows, split a browser-safe submodule
- * export in core and switch this to import it.
- */
+function enableInteractiveIframe(player: HyperframesPlayerElement): void {
+  const root = player.shadowRoot;
+  if (!root) return;
+
+  const container = root.querySelector<HTMLElement>(".hfp-container");
+  const iframe = root.querySelector<HTMLIFrameElement>(".hfp-iframe");
+
+  container?.style.setProperty("pointer-events", "auto");
+  iframe?.style.setProperty("pointer-events", "auto");
+}
+
 function isLottieAnimationReady(anim: unknown): boolean {
   if (typeof anim !== "object" || anim === null) return true;
   const maybe = anim as { isLoaded?: boolean; totalFrames?: number };
@@ -39,14 +32,6 @@ function isLottieAnimationReady(anim: unknown): boolean {
   return false;
 }
 
-// Assets are considered ready when every `<video>`/`<audio>` has enough data
-// to play through without buffering, and every registered Lottie animation has
-// finished loading.
-//
-// Returns whichever value was returned last on cross-origin / transient DOM
-// races so a brief access failure (e.g. an iframe that just swapped src)
-// doesn't flicker the overlay state — we keep showing whatever was most
-// recently true.
 function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean): boolean {
   try {
     const win = iframe.contentWindow as unknown as (Window & { __hfLottie?: unknown[] }) | null;
@@ -72,18 +57,9 @@ function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean): bool
   }
 }
 
-/**
- * Renders a composition preview using the <hyperframes-player> web component.
- *
- * The web component handles iframe scaling, dimension detection, and
- * ResizeObserver internally. This wrapper bridges its inner iframe to the
- * forwarded ref so useTimelinePlayer can access it for clip manifest parsing,
- * timeline probing, and DOM inspection.
- */
 export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
-  ({ projectId, directUrl, onLoad, portrait }, ref) => {
+  ({ projectId, directUrl, onLoad, portrait, style }, ref) => {
     const containerRef = useRef<HTMLDivElement>(null);
-    const loadCountRef = useRef(0);
     const assetPollRef = useRef<ReturnType<typeof setInterval> | null>(null);
     const [assetsLoading, setAssetsLoading] = useState(false);
 
@@ -94,22 +70,19 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
       let canceled = false;
       let cleanup: (() => void) | undefined;
 
-      // Dynamic import registers the custom element in the browser only.
       import("@hyperframes/player").then(() => {
         if (canceled) return;
 
-        // Create the web component imperatively to avoid JSX custom-element typing.
+        let loadHandled = false;
+        let readyProbeInterval: ReturnType<typeof window.setInterval> | undefined;
         const player = document.createElement("hyperframes-player") as HyperframesPlayerElement;
         const src = directUrl || `/api/projects/${projectId}/preview`;
-        player.setAttribute("src", src);
         player.setAttribute("width", String(portrait ? 1080 : 1920));
         player.setAttribute("height", String(portrait ? 1920 : 1080));
         player.style.width = "100%";
         player.style.height = "100%";
         player.style.display = "block";
-        container.appendChild(player);
 
-        // Bridge the inner iframe to the forwarded ref for useTimelinePlayer.
         const iframe = player.iframeElement;
         if (typeof ref === "function") {
           ref(iframe);
@@ -117,35 +90,19 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           (ref as React.MutableRefObject<HTMLIFrameElement | null>).current = iframe;
         }
 
-        // Prevent the web component's built-in click-to-toggle behavior.
-        // The studio manages playback exclusively via useTimelinePlayer.
         const preventToggle = (e: Event) => e.stopImmediatePropagation();
         player.addEventListener("click", preventToggle, { capture: true });
 
-        // Forward the iframe's native load event to the studio's onIframeLoad.
         const handleLoad = () => {
-          loadCountRef.current++;
-          // Reveal animation on reload (hot-reload, composition switch)
-          if (loadCountRef.current > 1) {
-            container.classList.remove("preview-revealing");
-            void container.offsetWidth;
-            container.classList.add("preview-revealing");
-            const onEnd = () => container.classList.remove("preview-revealing");
-            container.addEventListener("animationend", onEnd, { once: true });
+          if (loadHandled) return;
+          loadHandled = true;
+          if (readyProbeInterval != null) {
+            window.clearInterval(readyProbeInterval);
+            readyProbeInterval = undefined;
           }
+
           onLoad();
 
-          // Show a loading overlay until every `<video>`/`<audio>` and Lottie
-          // asset is ready. Without this users can click play before audio has
-          // buffered — the runtime is resilient (queued play() resolves once
-          // data arrives), but the overlay communicates why the first frame
-          // or first audio beat may lag.
-          //
-          // Poll with a 10 s safety cap (100 ticks × 100 ms). If the cap
-          // trips we hide the overlay so the UI doesn't appear stuck forever,
-          // but we log a debug warning so the case is diagnosable — a long
-          // cold video or a broken asset can legitimately exceed 10 s on a
-          // slow network.
           if (assetPollRef.current) clearInterval(assetPollRef.current);
           let lastUnloaded = hasUnloadedAssets(iframe, false);
           if (lastUnloaded) {
@@ -158,11 +115,6 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
                 if (assetPollRef.current) clearInterval(assetPollRef.current);
                 assetPollRef.current = null;
                 setAssetsLoading(false);
-                if (lastUnloaded) {
-                  console.debug(
-                    "[Player] Asset-loading overlay timed out after 10s; hiding anyway. Check network or asset integrity.",
-                  );
-                }
               }
             }, 100);
           } else {
@@ -171,13 +123,40 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
         };
         iframe.addEventListener("load", handleLoad);
 
+        container.appendChild(player);
+        enableInteractiveIframe(player);
+        // Set src last so a warm browser/cache cannot complete the iframe load
+        // before Studio has attached the load listener that hydrates timeline state.
+        player.setAttribute("src", src);
+        let readyProbeAttempts = 0;
+        readyProbeInterval = window.setInterval(() => {
+          readyProbeAttempts += 1;
+          try {
+            const doc = iframe.contentDocument;
+            const href = iframe.contentWindow?.location.href;
+            if (
+              doc &&
+              href !== "about:blank" &&
+              (doc.readyState === "interactive" || doc.readyState === "complete")
+            ) {
+              handleLoad();
+              return;
+            }
+          } catch {
+            // The iframe is same-origin in Studio; if the browser briefly denies
+            // access during navigation, keep the normal load listener as authority.
+          }
+
+          if (readyProbeAttempts >= 50) handleLoad();
+        }, 100);
+
         cleanup = () => {
           iframe.removeEventListener("load", handleLoad);
           player.removeEventListener("click", preventToggle, { capture: true });
+          if (readyProbeInterval != null) window.clearInterval(readyProbeInterval);
           if (assetPollRef.current) clearInterval(assetPollRef.current);
           assetPollRef.current = null;
           container.removeChild(player);
-          // Clear the forwarded ref
           if (typeof ref === "function") {
             ref(null);
           } else if (ref) {
@@ -193,7 +172,10 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
     });
 
     return (
-      <div className="relative w-full h-full max-w-full max-h-full overflow-hidden bg-black flex items-center justify-center">
+      <div
+        className="relative w-full h-full max-w-full max-h-full overflow-hidden bg-black flex items-center justify-center"
+        style={style}
+      >
         <div ref={containerRef} className="w-full h-full" />
         {assetsLoading && (
           <div className="absolute inset-0 bg-black/80 flex flex-col items-center justify-center z-20 pointer-events-none">
diff --git a/packages/studio/src/player/components/Timeline.test.ts b/packages/studio/src/player/components/Timeline.test.ts
index 19041d5e0..606dbddc7 100644
--- a/packages/studio/src/player/components/Timeline.test.ts
+++ b/packages/studio/src/player/components/Timeline.test.ts
@@ -8,8 +8,12 @@ import {
   getTimelinePlayheadLeft,
   getTimelineScrollLeftForZoomAnchor,
   getTimelineScrollLeftForZoomTransition,
+  getTimelineVisibleTimeRange,
+  getTimelineVisibleTrackIndexRange,
+  shouldShowTimelineShortcutHint,
   shouldHandleTimelineDeleteKey,
   shouldAutoScrollTimeline,
+  shouldRenderTimelineElementInRange,
 } from "./Timeline";
 import { formatTime } from "../lib/time";
 
@@ -216,6 +220,107 @@ describe("getTimelineScrollLeftForZoomAnchor", () => {
   });
 });
 
+describe("getTimelineVisibleTimeRange", () => {
+  it("maps the scroll viewport into an overscanned time range", () => {
+    expect(
+      getTimelineVisibleTimeRange({
+        scrollLeft: 320,
+        viewportWidth: 640,
+        gutter: 32,
+        pixelsPerSecond: 100,
+        duration: 20,
+        overscanPx: 100,
+      }),
+    ).toEqual({ start: 1.88, end: 10.28 });
+  });
+
+  it("clamps invalid or out-of-bounds ranges to the composition duration", () => {
+    expect(
+      getTimelineVisibleTimeRange({
+        scrollLeft: 2000,
+        viewportWidth: 300,
+        gutter: 32,
+        pixelsPerSecond: 100,
+        duration: 5,
+        overscanPx: 100,
+      }),
+    ).toEqual({ start: 5, end: 5 });
+  });
+});
+
+describe("shouldRenderTimelineElementInRange", () => {
+  it("keeps clips that intersect the visible time range", () => {
+    expect(
+      shouldRenderTimelineElementInRange({ start: 3, duration: 2 }, { start: 4, end: 8 }),
+    ).toBe(true);
+    expect(
+      shouldRenderTimelineElementInRange({ start: 8, duration: 1 }, { start: 4, end: 8 }),
+    ).toBe(true);
+  });
+
+  it("skips clips outside the visible time range", () => {
+    expect(
+      shouldRenderTimelineElementInRange({ start: 0, duration: 1 }, { start: 4, end: 8 }),
+    ).toBe(false);
+    expect(
+      shouldRenderTimelineElementInRange({ start: 9, duration: 1 }, { start: 4, end: 8 }),
+    ).toBe(false);
+  });
+});
+
+describe("getTimelineVisibleTrackIndexRange", () => {
+  it("maps vertical scroll into an overscanned track index range", () => {
+    expect(
+      getTimelineVisibleTrackIndexRange({
+        scrollTop: 180,
+        viewportHeight: 220,
+        rulerHeight: 24,
+        trackHeight: 72,
+        trackCount: 20,
+        overscanRows: 1,
+      }),
+    ).toEqual({ startIndex: 1, endIndex: 7 });
+  });
+
+  it("renders all tracks before viewport measurement exists", () => {
+    expect(
+      getTimelineVisibleTrackIndexRange({
+        scrollTop: 0,
+        viewportHeight: 0,
+        rulerHeight: 24,
+        trackHeight: 72,
+        trackCount: 4,
+        overscanRows: 2,
+      }),
+    ).toEqual({ startIndex: 0, endIndex: 3 });
+  });
+
+  it("clamps the range to available tracks", () => {
+    expect(
+      getTimelineVisibleTrackIndexRange({
+        scrollTop: 2000,
+        viewportHeight: 220,
+        rulerHeight: 24,
+        trackHeight: 72,
+        trackCount: 5,
+        overscanRows: 2,
+      }),
+    ).toEqual({ startIndex: 4, endIndex: 4 });
+  });
+
+  it("returns an empty range when there are no tracks", () => {
+    expect(
+      getTimelineVisibleTrackIndexRange({
+        scrollTop: 0,
+        viewportHeight: 220,
+        rulerHeight: 24,
+        trackHeight: 72,
+        trackCount: 0,
+      }),
+    ).toEqual({ startIndex: 0, endIndex: -1 });
+  });
+});
+
 describe("getTimelinePlayheadLeft", () => {
   it("converts time to a pixel offset from the gutter", () => {
     expect(getTimelinePlayheadLeft(4, 20)).toBe(112);
@@ -237,6 +342,17 @@ describe("getTimelineCanvasHeight", () => {
   });
 });
 
+describe("shouldShowTimelineShortcutHint", () => {
+  it("shows the hint when the timeline does not vertically overflow", () => {
+    expect(shouldShowTimelineShortcutHint(220, 220)).toBe(true);
+    expect(shouldShowTimelineShortcutHint(220.5, 220)).toBe(true);
+  });
+
+  it("hides the hint when timeline tracks need vertical scrolling", () => {
+    expect(shouldShowTimelineShortcutHint(221.5, 220)).toBe(false);
+  });
+});
+
 describe("shouldHandleTimelineDeleteKey", () => {
   it("handles Delete and Backspace when focus is not in an editor", () => {
     expect(shouldHandleTimelineDeleteKey({ key: "Delete" })).toBe(true);
diff --git a/packages/studio/src/player/components/Timeline.tsx b/packages/studio/src/player/components/Timeline.tsx
index 4ed4319cc..4165642ed 100644
--- a/packages/studio/src/player/components/Timeline.tsx
+++ b/packages/studio/src/player/components/Timeline.tsx
@@ -28,6 +28,7 @@ import {
 } from "./timelineTheme";
 import { getPinchTimelineZoomPercent, getTimelinePixelsPerSecond } from "./timelineZoom";
 import { TIMELINE_ASSET_MIME } from "../../utils/timelineAssetDrop";
+import { canInspectTimelineElement, isAudioTimelineElement } from "../../utils/timelineInspector";
 
 /* ── Layout ─────────────────────────────────────────────────────── */
 const GUTTER = 32;
@@ -35,7 +36,10 @@ const TRACK_H = 72;
 const RULER_H = 24;
 const CLIP_Y = 3; // vertical inset inside track
 const CLIP_HANDLE_W = 18;
-const TIMELINE_SCROLL_BUFFER = 24;
+const TIMELINE_SCROLL_BUFFER = 20;
+const TIMELINE_CLIP_OVERSCAN_PX = 360;
+const TIMELINE_TRACK_OVERSCAN_ROWS = 2;
+const NOOP = () => {};
 
 interface TrackVisualStyle extends TimelineTrackStyle {
   icon: ReactNode;
@@ -173,6 +177,86 @@ export function shouldAutoScrollTimeline(
   return scrollWidth - clientWidth > 1;
 }
 
+export interface TimelineVisibleTimeRange {
+  start: number;
+  end: number;
+}
+
+export function getTimelineVisibleTimeRange(input: {
+  scrollLeft: number;
+  viewportWidth: number;
+  gutter: number;
+  pixelsPerSecond: number;
+  duration: number;
+  overscanPx?: number;
+}): TimelineVisibleTimeRange {
+  const duration = Number.isFinite(input.duration) ? Math.max(0, input.duration) : 0;
+  const pps = Number.isFinite(input.pixelsPerSecond) ? Math.max(0, input.pixelsPerSecond) : 0;
+  if (duration <= 0 || pps <= 0) return { start: 0, end: duration };
+
+  const overscanPx = Number.isFinite(input.overscanPx) ? Math.max(0, input.overscanPx ?? 0) : 0;
+  const viewportWidth = Number.isFinite(input.viewportWidth) ? Math.max(0, input.viewportWidth) : 0;
+  const scrollLeft = Number.isFinite(input.scrollLeft) ? Math.max(0, input.scrollLeft) : 0;
+  const gutter = Number.isFinite(input.gutter) ? Math.max(0, input.gutter) : 0;
+
+  const startPx = Math.max(0, scrollLeft - gutter - overscanPx);
+  const endPx = Math.max(startPx, scrollLeft + viewportWidth - gutter + overscanPx);
+  return {
+    start: Math.max(0, Math.min(duration, startPx / pps)),
+    end: Math.max(0, Math.min(duration, endPx / pps)),
+  };
+}
+
+export function shouldRenderTimelineElementInRange(
+  element: Pick<TimelineElement, "start" | "duration">,
+  range: TimelineVisibleTimeRange,
+): boolean {
+  const start = Number.isFinite(element.start) ? element.start : 0;
+  const duration = Number.isFinite(element.duration) ? Math.max(0, element.duration) : 0;
+  const end = start + duration;
+  return end >= range.start && start <= range.end;
+}
+
+export interface TimelineVisibleTrackIndexRange {
+  startIndex: number;
+  endIndex: number;
+}
+
+export function getTimelineVisibleTrackIndexRange(input: {
+  scrollTop: number;
+  viewportHeight: number;
+  rulerHeight: number;
+  trackHeight: number;
+  trackCount: number;
+  overscanRows?: number;
+}): TimelineVisibleTrackIndexRange {
+  const trackCount = Number.isFinite(input.trackCount)
+    ? Math.max(0, Math.floor(input.trackCount))
+    : 0;
+  if (trackCount === 0) return { startIndex: 0, endIndex: -1 };
+
+  const viewportHeight = Number.isFinite(input.viewportHeight)
+    ? Math.max(0, input.viewportHeight)
+    : 0;
+  const trackHeight = Number.isFinite(input.trackHeight) ? Math.max(0, input.trackHeight) : 0;
+  if (viewportHeight <= 0 || trackHeight <= 0) return { startIndex: 0, endIndex: trackCount - 1 };
+
+  const scrollTop = Number.isFinite(input.scrollTop) ? Math.max(0, input.scrollTop) : 0;
+  const rulerHeight = Number.isFinite(input.rulerHeight) ? Math.max(0, input.rulerHeight) : 0;
+  const overscanRows = Number.isFinite(input.overscanRows)
+    ? Math.max(0, Math.floor(input.overscanRows ?? 0))
+    : 0;
+
+  const visibleTop = Math.max(0, scrollTop - rulerHeight);
+  const visibleBottom = Math.max(visibleTop, scrollTop + viewportHeight - rulerHeight);
+  const startIndex = Math.min(
+    trackCount - 1,
+    Math.max(0, Math.floor(visibleTop / trackHeight) - overscanRows),
+  );
+  const endIndex = Math.min(trackCount - 1, Math.ceil(visibleBottom / trackHeight) + overscanRows);
+  return { startIndex, endIndex };
+}
+
 export function getTimelineScrollLeftForZoomTransition(
   previousZoomMode: ZoomMode | null,
   nextZoomMode: ZoomMode,
@@ -216,6 +300,14 @@ export function getTimelineCanvasHeight(trackCount: number): number {
   return RULER_H + Math.max(0, trackCount) * TRACK_H + TIMELINE_SCROLL_BUFFER;
 }
 
+export function shouldShowTimelineShortcutHint(
+  scrollHeight: number,
+  clientHeight: number,
+): boolean {
+  if (!Number.isFinite(scrollHeight) || !Number.isFinite(clientHeight)) return true;
+  return scrollHeight - clientHeight <= 1;
+}
+
 export function shouldHandleTimelineDeleteKey(input: {
   key: string;
   metaKey?: boolean;
@@ -279,17 +371,27 @@ export function resolveTimelineAssetDrop(
     track: getDefaultDroppedTrack(input.trackOrder, rowIndex),
   };
 }
-
 /* ── Component ──────────────────────────────────────────────────── */
 interface TimelineProps {
   /** Called when user seeks via ruler/track click or playhead drag */
   onSeek?: (time: number) => void;
   /** Called when user double-clicks a composition clip to drill into it */
   onDrillDown?: (element: import("../store/playerStore").TimelineElement) => void;
+  /** Called when user selects a timeline clip */
+  onSelectElement?: (element: import("../store/playerStore").TimelineElement | null) => void;
+  /** Called when user explicitly enables the preview inspector for a clip */
+  onInspectElement?: (element: import("../store/playerStore").TimelineElement) => void;
+  inspectedElementId?: string | null;
+  /** Descendant layer counts for timeline clips that contain selectable DOM children. */
+  layerChildCounts?: ReadonlyMap<string, number>;
+  /** Timeline clips whose thumbnail content should be rendered. */
+  thumbnailedElementIds?: Set<string>;
+  /** Called when user toggles a clip thumbnail from the timeline. */
+  onToggleElementThumbnail?: (element: import("../store/playerStore").TimelineElement) => void;
   /** Optional custom content renderer for clips (thumbnails, waveforms, etc.) */
   renderClipContent?: (
     element: import("../store/playerStore").TimelineElement,
-    style: { clip: string; label: string },
+    style: { clip: string; label: string; accent?: string },
   ) => ReactNode;
   /** Optional overlay renderer for clips (e.g. badges, cursors) */
   renderClipOverlay?: (element: import("../store/playerStore").TimelineElement) => ReactNode;
@@ -361,6 +463,12 @@ interface BlockedClipState {
 export const Timeline = memo(function Timeline({
   onSeek,
   onDrillDown,
+  onSelectElement,
+  onInspectElement,
+  inspectedElementId,
+  layerChildCounts,
+  thumbnailedElementIds,
+  onToggleElementThumbnail,
   renderClipContent,
   renderClipOverlay,
   onFileDrop,
@@ -378,7 +486,6 @@ export const Timeline = memo(function Timeline({
   const selectedElementId = usePlayerStore((s) => s.selectedElementId);
   const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
   const updateElement = usePlayerStore((s) => s.updateElement);
-  const currentTime = usePlayerStore((s) => s.currentTime);
   const zoomMode = usePlayerStore((s) => s.zoomMode);
   const manualZoomPercent = usePlayerStore((s) => s.manualZoomPercent);
   const setZoomMode = usePlayerStore((s) => s.setZoomMode);
@@ -386,7 +493,12 @@ export const Timeline = memo(function Timeline({
   const playheadRef = useRef<HTMLDivElement>(null);
   const containerRef = useRef<HTMLDivElement>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
-  const [hoveredClip, setHoveredClip] = useState<string | null>(null);
+  const [timelineViewport, setTimelineViewport] = useState({
+    scrollLeft: 0,
+    scrollTop: 0,
+    width: 0,
+    height: 0,
+  });
   const isDragging = useRef(false);
   const shiftClickClipRef = useRef<{
     element: TimelineElement;
@@ -427,30 +539,80 @@ export const Timeline = memo(function Timeline({
   onDeleteElementRef.current = onDeleteElement;
   const suppressClickRef = useRef(false);
   const [showPopover, setShowPopover] = useState(false);
+  const [showShortcutHint, setShowShortcutHint] = useState(true);
   const [viewportWidth, setViewportWidth] = useState(0);
   const roRef = useRef<ResizeObserver | null>(null);
+  const shortcutHintRafRef = useRef(0);
+  const viewportRafRef = useRef(0);
+  const syncTimelineViewport = useCallback(() => {
+    const scroll = scrollRef.current;
+    if (!scroll) return;
+    const next = {
+      scrollLeft: scroll.scrollLeft,
+      scrollTop: scroll.scrollTop,
+      width: scroll.clientWidth,
+      height: scroll.clientHeight,
+    };
+    setTimelineViewport((prev) =>
+      Math.abs(prev.scrollLeft - next.scrollLeft) < 0.5 &&
+      Math.abs(prev.scrollTop - next.scrollTop) < 0.5 &&
+      Math.abs(prev.width - next.width) < 0.5 &&
+      Math.abs(prev.height - next.height) < 0.5
+        ? prev
+        : next,
+    );
+  }, []);
+  const scheduleTimelineViewportSync = useCallback(() => {
+    if (viewportRafRef.current) return;
+    viewportRafRef.current = requestAnimationFrame(() => {
+      viewportRafRef.current = 0;
+      syncTimelineViewport();
+    });
+  }, [syncTimelineViewport]);
+  const syncShortcutHintVisibility = useCallback(() => {
+    const scroll = scrollRef.current;
+    setShowShortcutHint(
+      scroll ? shouldShowTimelineShortcutHint(scroll.scrollHeight, scroll.clientHeight) : true,
+    );
+  }, []);
+  const scheduleShortcutHintVisibilitySync = useCallback(() => {
+    if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
+    shortcutHintRafRef.current = requestAnimationFrame(() => {
+      shortcutHintRafRef.current = 0;
+      syncShortcutHintVisibility();
+    });
+  }, [syncShortcutHintVisibility]);
 
   // Callback ref: sets up ResizeObserver when the DOM element actually mounts.
   // useMountEffect can't work here because the component returns null on first
   // render (timelineReady=false), so containerRef.current is null when the
   // effect fires and the ResizeObserver is never created.
-  const setContainerRef = useCallback((el: HTMLDivElement | null) => {
-    if (roRef.current) {
-      roRef.current.disconnect();
-      roRef.current = null;
-    }
-    containerRef.current = el;
-    if (!el) return;
-    setViewportWidth(el.clientWidth);
-    roRef.current = new ResizeObserver(([entry]) => {
-      setViewportWidth(entry.contentRect.width);
-    });
-    roRef.current.observe(el);
-  }, []);
+  const setContainerRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      if (roRef.current) {
+        roRef.current.disconnect();
+        roRef.current = null;
+      }
+      containerRef.current = el;
+      if (!el) return;
+      setViewportWidth(el.clientWidth);
+      scheduleTimelineViewportSync();
+      scheduleShortcutHintVisibilitySync();
+      roRef.current = new ResizeObserver(([entry]) => {
+        setViewportWidth(entry.contentRect.width);
+        scheduleTimelineViewportSync();
+        scheduleShortcutHintVisibilitySync();
+      });
+      roRef.current.observe(el);
+    },
+    [scheduleShortcutHintVisibilitySync, scheduleTimelineViewportSync],
+  );
 
   // Clean up ResizeObserver on unmount
   useMountEffect(() => () => {
     roRef.current?.disconnect();
+    if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
+    if (viewportRafRef.current) cancelAnimationFrame(viewportRafRef.current);
   });
 
   // Effective duration: max of store duration and the furthest element end.
@@ -495,6 +657,7 @@ export const Timeline = memo(function Timeline({
     }
     return [...trackOrder, draggedClip.previewTrack].sort((a, b) => a - b);
   }, [draggedClip, trackOrder]);
+  const totalH = getTimelineCanvasHeight(displayTrackOrder.length);
   const selectedElement = useMemo(
     () => elements.find((element) => (element.key ?? element.id) === selectedElementId) ?? null,
     [elements, selectedElementId],
@@ -522,14 +685,38 @@ export const Timeline = memo(function Timeline({
   durationRef.current = effectiveDuration;
   const ppsRef = useRef(pps);
   ppsRef.current = pps;
+  const visibleTimeRange = useMemo(
+    () =>
+      getTimelineVisibleTimeRange({
+        scrollLeft: timelineViewport.scrollLeft,
+        viewportWidth: timelineViewport.width || viewportWidth,
+        gutter: GUTTER,
+        pixelsPerSecond: pps,
+        duration: effectiveDuration,
+        overscanPx: TIMELINE_CLIP_OVERSCAN_PX,
+      }),
+    [effectiveDuration, pps, timelineViewport.scrollLeft, timelineViewport.width, viewportWidth],
+  );
+  const visibleTrackIndexRange = useMemo(
+    () =>
+      getTimelineVisibleTrackIndexRange({
+        scrollTop: timelineViewport.scrollTop,
+        viewportHeight: timelineViewport.height,
+        rulerHeight: RULER_H,
+        trackHeight: TRACK_H,
+        trackCount: displayTrackOrder.length,
+        overscanRows: TIMELINE_TRACK_OVERSCAN_ROWS,
+      }),
+    [displayTrackOrder.length, timelineViewport.height, timelineViewport.scrollTop],
+  );
   const syncPlayheadPosition = useCallback((time: number) => {
     if (!playheadRef.current || durationRef.current <= 0) return;
     playheadRef.current.style.left = `${getTimelinePlayheadLeft(time, ppsRef.current)}px`;
   }, []);
 
   useEffect(() => {
-    syncPlayheadPosition(currentTime);
-  }, [currentTime, pps, syncPlayheadPosition]);
+    syncPlayheadPosition(usePlayerStore.getState().currentTime);
+  }, [pps, syncPlayheadPosition]);
 
   useEffect(() => {
     const scroll = scrollRef.current;
@@ -544,7 +731,6 @@ export const Timeline = memo(function Timeline({
     );
     previousZoomModeRef.current = zoomMode;
   }, [zoomMode]);
-
   useMountEffect(() => {
     const unsub = liveTime.subscribe((t) => {
       const dur = durationRef.current;
@@ -1012,6 +1198,10 @@ export const Timeline = memo(function Timeline({
   );
   const majorTickInterval =
     major.length >= 2 ? Math.max(0.25, major[1] - major[0]) : effectiveDuration;
+  useEffect(() => {
+    syncShortcutHintVisibility();
+  }, [syncShortcutHintVisibility, timelineReady, elements.length, totalH]);
+
   const getPreviewElement = useCallback(
     (element: TimelineElement): TimelineElement => {
       if (
@@ -1239,7 +1429,6 @@ export const Timeline = memo(function Timeline({
     );
   }
 
-  const totalH = getTimelineCanvasHeight(displayTrackOrder.length);
   const draggedElement = draggedClip?.element ?? null;
   const activeDraggedElement =
     draggedClip?.started === true && draggedElement
@@ -1265,18 +1454,24 @@ export const Timeline = memo(function Timeline({
             draggedClip.pointerOffsetY,
         }
       : null;
-  const renderClipChildren = (element: TimelineElement, clipStyle: TrackVisualStyle) => {
+  const renderClipChildren = (
+    element: TimelineElement,
+    clipStyle: TrackVisualStyle,
+    showCustomContent: boolean,
+  ) => {
     return (
       <>
         {renderClipOverlay?.(element)}
         <div
           className={
-            renderClipContent
+            showCustomContent && renderClipContent
               ? "absolute inset-0 overflow-hidden"
               : "flex flex-col justify-center overflow-hidden flex-1 min-w-0 px-6"
           }
         >
-          {renderClipContent?.(element, clipStyle) ?? (
+          {showCustomContent && renderClipContent ? (
+            renderClipContent(element, clipStyle)
+          ) : (
             <div className="flex h-full min-h-0 flex-col justify-between py-3">
               <div className="flex items-start">
                 <span
@@ -1287,7 +1482,7 @@ export const Timeline = memo(function Timeline({
                     boxShadow: `inset 0 0 0 1px ${clipStyle.accent}33`,
                   }}
                 >
-                  {element.tag}
+                  {element.label || element.id || element.tag}
                 </span>
               </div>
               <div className="flex items-center">
@@ -1313,7 +1508,7 @@ export const Timeline = memo(function Timeline({
     <div
       ref={setContainerRef}
       aria-label="Timeline"
-      className={`border-t select-none h-full overflow-hidden ${shiftHeld ? "cursor-crosshair" : "cursor-default"}`}
+      className={`relative border-t select-none h-full overflow-hidden ${shiftHeld ? "cursor-crosshair" : "cursor-default"}`}
       style={{
         touchAction: "pan-x pan-y",
         background: theme.shellBackground,
@@ -1323,6 +1518,7 @@ export const Timeline = memo(function Timeline({
       <div
         ref={scrollRef}
         className={`${zoomMode === "fit" ? "overflow-x-hidden" : "overflow-x-auto"} overflow-y-auto h-full`}
+        data-studio-timeline-scroll="true"
         onDragOver={handleAssetDragOver}
         onDragLeave={() => setIsDragOver(false)}
         onDrop={handleAssetDrop}
@@ -1330,6 +1526,7 @@ export const Timeline = memo(function Timeline({
         onPointerMove={handlePointerMove}
         onPointerUp={handlePointerUp}
         onLostPointerCapture={handlePointerUp}
+        onScroll={scheduleTimelineViewportSync}
       >
         <div className="relative" style={{ height: totalH, width: GUTTER + trackContentWidth }}>
           {/* Grid lines */}
@@ -1390,9 +1587,12 @@ export const Timeline = memo(function Timeline({
           </div>
 
           {/* Tracks */}
-          {displayTrackOrder.map((trackNum) => {
+          {displayTrackOrder.map((trackNum, trackIndex) => {
             const els = tracks.find(([currentTrack]) => currentTrack === trackNum)?.[1] ?? [];
             const ts = trackStyles.get(trackNum) ?? getStyle("");
+            const isVisibleTrack =
+              trackIndex >= visibleTrackIndexRange.startIndex &&
+              trackIndex <= visibleTrackIndexRange.endIndex;
             const isPendingTrack =
               draggedClip?.started === true && !trackOrder.includes(trackNum) && els.length === 0;
             return (
@@ -1413,24 +1613,26 @@ export const Timeline = memo(function Timeline({
                     borderRight: `1px solid ${theme.gutterBorder}`,
                   }}
                 >
-                  <div
-                    className="flex items-center justify-center"
-                    style={{
-                      width: 18,
-                      height: 18,
-                      borderRadius: 6,
-                      backgroundColor: ts.iconBackground,
-                      border: `1px solid ${theme.gutterBorder}`,
-                      color: "#fff",
-                    }}
-                  >
-                    {ts.icon}
-                  </div>
+                  {isVisibleTrack && (
+                    <div
+                      className="flex items-center justify-center"
+                      style={{
+                        width: 18,
+                        height: 18,
+                        borderRadius: 6,
+                        backgroundColor: ts.iconBackground,
+                        border: `1px solid ${theme.gutterBorder}`,
+                        color: "#fff",
+                      }}
+                    >
+                      {ts.icon}
+                    </div>
+                  )}
                 </div>
 
                 {/* Clips */}
                 <div style={{ width: trackContentWidth }} className="relative">
-                  {isPendingTrack && (
+                  {isVisibleTrack && isPendingTrack && (
                     <div
                       className="absolute inset-0 flex items-center"
                       style={{
@@ -1446,120 +1648,161 @@ export const Timeline = memo(function Timeline({
                       New track
                     </div>
                   )}
-                  {els.map((el, i) => {
-                    const clipStyle = getStyle(el.tag);
-                    const elementKey = el.key ?? el.id;
-                    const capabilities = getTimelineEditCapabilities(el);
-                    const isSelected = selectedElementId === elementKey;
-                    const isComposition = !!el.compositionSrc;
-                    const clipKey = `${elementKey}-${i}`;
-                    const isHovered = hoveredClip === clipKey;
-                    const hasCustomContent = !!renderClipContent;
-                    const isDragging =
-                      draggedClip?.started === true &&
-                      (draggedElement?.key ?? draggedElement?.id) === elementKey;
-                    if (isDragging) return null;
-                    const previewElement = getPreviewElement(el);
-
-                    return (
-                      <TimelineClip
-                        key={clipKey}
-                        el={previewElement}
-                        pps={pps}
-                        clipY={CLIP_Y}
-                        isSelected={isSelected}
-                        isHovered={isHovered}
-                        isDragging={false}
-                        hasCustomContent={hasCustomContent}
-                        theme={theme}
-                        trackStyle={clipStyle}
-                        isComposition={isComposition}
-                        onHoverStart={() => setHoveredClip(clipKey)}
-                        onHoverEnd={() => setHoveredClip(null)}
-                        onResizeStart={(edge, e) => {
-                          if (e.button !== 0 || e.shiftKey || !onResizeElement) return;
-                          if (edge === "start" && !capabilities.canTrimStart) return;
-                          if (edge === "end" && !capabilities.canTrimEnd) return;
-                          e.stopPropagation();
-                          blockedClipRef.current = null;
-                          setShowPopover(false);
-                          setRangeSelection(null);
-                          setResizingClip({
-                            element: el,
-                            edge,
-                            originClientX: e.clientX,
-                            previewStart: el.start,
-                            previewDuration: el.duration,
-                            previewPlaybackStart: el.playbackStart,
-                            started: false,
-                          });
-                        }}
-                        onPointerDown={(e) => {
-                          if (e.button !== 0) return;
-                          if (e.shiftKey) {
-                            shiftClickClipRef.current = {
+                  {isVisibleTrack &&
+                    els.map((el, i) => {
+                      const clipStyle = getStyle(el.tag);
+                      const elementKey = el.key ?? el.id;
+                      const capabilities = getTimelineEditCapabilities(el);
+                      const isSelected = selectedElementId === elementKey;
+                      const canInspect = canInspectTimelineElement(el);
+                      const thumbnailLabel = isAudioTimelineElement(el) ? "waveform" : "thumbnail";
+                      const isInspectorActive = canInspect && inspectedElementId === elementKey;
+                      const isThumbnailActive = thumbnailedElementIds?.has(elementKey) ?? false;
+                      const isComposition = !!el.compositionSrc;
+                      const clipKey = `${elementKey}-${i}`;
+                      const childCount = layerChildCounts?.get(elementKey) ?? 0;
+                      const hasCustomContent = isThumbnailActive && !!renderClipContent;
+                      const isDragging =
+                        draggedClip?.started === true &&
+                        (draggedElement?.key ?? draggedElement?.id) === elementKey;
+                      if (isDragging) return null;
+                      const isResizing = resizingClip
+                        ? resizingClip.element.key === el.key ||
+                          (resizingClip.element.key == null &&
+                            resizingClip.element.id === el.id &&
+                            resizingClip.element.track === el.track)
+                        : false;
+                      const forceRender = isSelected || isResizing;
+                      if (
+                        !forceRender &&
+                        !shouldRenderTimelineElementInRange(el, visibleTimeRange)
+                      ) {
+                        return null;
+                      }
+                      const previewElement = getPreviewElement(el);
+
+                      return (
+                        <TimelineClip
+                          key={clipKey}
+                          el={previewElement}
+                          pps={pps}
+                          clipY={CLIP_Y}
+                          isSelected={isSelected}
+                          isHovered={false}
+                          isDragging={false}
+                          hasCustomContent={hasCustomContent}
+                          theme={theme}
+                          trackStyle={clipStyle}
+                          isComposition={isComposition}
+                          isInspectorActive={isInspectorActive}
+                          isThumbnailActive={isThumbnailActive}
+                          thumbnailLabel={thumbnailLabel}
+                          childCount={childCount}
+                          onHoverStart={NOOP}
+                          onHoverEnd={NOOP}
+                          onResizeStart={(edge, e) => {
+                            if (e.button !== 0 || e.shiftKey || !onResizeElement) return;
+                            if (edge === "start" && !capabilities.canTrimStart) return;
+                            if (edge === "end" && !capabilities.canTrimEnd) return;
+                            e.stopPropagation();
+                            blockedClipRef.current = null;
+                            setShowPopover(false);
+                            setRangeSelection(null);
+                            setResizingClip({
                               element: el,
-                              anchorX: e.clientX,
-                              anchorY: e.clientY,
-                            };
-                            return;
-                          }
-                          const target = e.currentTarget as HTMLElement;
-                          const rect = target.getBoundingClientRect();
-                          const blockedIntent = resolveBlockedTimelineEditIntent({
-                            width: rect.width,
-                            offsetX: e.clientX - rect.left,
-                            handleWidth: CLIP_HANDLE_W,
-                            capabilities,
-                          });
-                          if (
-                            blockedIntent &&
-                            ((blockedIntent === "move" && onMoveElement) ||
-                              (blockedIntent !== "move" && onResizeElement))
-                          ) {
-                            blockedClipRef.current = {
+                              edge,
+                              originClientX: e.clientX,
+                              previewStart: el.start,
+                              previewDuration: el.duration,
+                              previewPlaybackStart: el.playbackStart,
+                              started: false,
+                            });
+                          }}
+                          onPointerDown={(e) => {
+                            if (e.button !== 0) return;
+                            if (e.shiftKey) {
+                              shiftClickClipRef.current = {
+                                element: el,
+                                anchorX: e.clientX,
+                                anchorY: e.clientY,
+                              };
+                              return;
+                            }
+                            const target = e.currentTarget as HTMLElement;
+                            const rect = target.getBoundingClientRect();
+                            const blockedIntent = resolveBlockedTimelineEditIntent({
+                              width: rect.width,
+                              offsetX: e.clientX - rect.left,
+                              handleWidth: CLIP_HANDLE_W,
+                              capabilities,
+                            });
+                            if (
+                              blockedIntent &&
+                              ((blockedIntent === "move" && onMoveElement) ||
+                                (blockedIntent !== "move" && onResizeElement))
+                            ) {
+                              blockedClipRef.current = {
+                                element: el,
+                                intent: blockedIntent,
+                                originClientX: e.clientX,
+                                originClientY: e.clientY,
+                                started: false,
+                              };
+                              return;
+                            }
+                            if (!onMoveElement || !capabilities.canMove) return;
+                            blockedClipRef.current = null;
+                            setShowPopover(false);
+                            setRangeSelection(null);
+                            setDraggedClip({
                               element: el,
-                              intent: blockedIntent,
                               originClientX: e.clientX,
                               originClientY: e.clientY,
+                              originScrollLeft: scrollRef.current?.scrollLeft ?? 0,
+                              originScrollTop: scrollRef.current?.scrollTop ?? 0,
+                              pointerClientX: e.clientX,
+                              pointerClientY: e.clientY,
+                              pointerOffsetX: e.clientX - rect.left,
+                              pointerOffsetY: e.clientY - rect.top,
+                              previewStart: el.start,
+                              previewTrack: el.track,
                               started: false,
-                            };
-                            return;
+                            });
+                          }}
+                          onClick={(e) => {
+                            e.stopPropagation();
+                            if (suppressClickRef.current) return;
+                            const nextElement = isSelected ? null : el;
+                            setSelectedElementId(nextElement ? elementKey : null);
+                            onSelectElement?.(nextElement);
+                          }}
+                          onInspectorClick={
+                            canInspect
+                              ? () => {
+                                  if (suppressClickRef.current) return;
+                                  setSelectedElementId(elementKey);
+                                  onInspectElement?.(el);
+                                }
+                              : undefined
                           }
-                          if (!onMoveElement || !capabilities.canMove) return;
-                          blockedClipRef.current = null;
-                          setShowPopover(false);
-                          setRangeSelection(null);
-                          setDraggedClip({
-                            element: el,
-                            originClientX: e.clientX,
-                            originClientY: e.clientY,
-                            originScrollLeft: scrollRef.current?.scrollLeft ?? 0,
-                            originScrollTop: scrollRef.current?.scrollTop ?? 0,
-                            pointerClientX: e.clientX,
-                            pointerClientY: e.clientY,
-                            pointerOffsetX: e.clientX - rect.left,
-                            pointerOffsetY: e.clientY - rect.top,
-                            previewStart: el.start,
-                            previewTrack: el.track,
-                            started: false,
-                          });
-                        }}
-                        onClick={(e) => {
-                          e.stopPropagation();
-                          if (suppressClickRef.current) return;
-                          setSelectedElementId(isSelected ? null : elementKey);
-                        }}
-                        onDoubleClick={(e) => {
-                          e.stopPropagation();
-                          if (suppressClickRef.current) return;
-                          if (isComposition && onDrillDown) onDrillDown(el);
-                        }}
-                      >
-                        {renderClipChildren(previewElement, clipStyle)}
-                      </TimelineClip>
-                    );
-                  })}
+                          onThumbnailClick={
+                            onToggleElementThumbnail
+                              ? () => {
+                                  if (suppressClickRef.current) return;
+                                  onToggleElementThumbnail(el);
+                                }
+                              : undefined
+                          }
+                          onDoubleClick={(e) => {
+                            e.stopPropagation();
+                            if (suppressClickRef.current) return;
+                            if (isComposition && onDrillDown) onDrillDown(el);
+                          }}
+                        >
+                          {renderClipChildren(previewElement, clipStyle, hasCustomContent)}
+                        </TimelineClip>
+                      );
+                    })}
                 </div>
               </div>
             );
@@ -1585,17 +1828,27 @@ export const Timeline = memo(function Timeline({
                 }
                 isHovered={false}
                 isDragging={true}
-                hasCustomContent={!!renderClipContent}
+                hasCustomContent={false}
                 theme={theme}
                 trackStyle={getStyle(activeDraggedElement.tag)}
                 isComposition={!!activeDraggedElement.compositionSrc}
+                isInspectorActive={
+                  inspectedElementId === (activeDraggedElement.key ?? activeDraggedElement.id)
+                }
+                childCount={
+                  layerChildCounts?.get(activeDraggedElement.key ?? activeDraggedElement.id) ?? 0
+                }
                 onHoverStart={() => {}}
                 onHoverEnd={() => {}}
                 onResizeStart={() => {}}
                 onClick={() => {}}
                 onDoubleClick={() => {}}
               >
-                {renderClipChildren(activeDraggedElement, getStyle(activeDraggedElement.tag))}
+                {renderClipChildren(
+                  activeDraggedElement,
+                  getStyle(activeDraggedElement.tag),
+                  false,
+                )}
               </TimelineClip>
             </div>
           )}
@@ -1652,8 +1905,8 @@ export const Timeline = memo(function Timeline({
         </div>
       </div>
 
-      {/* Keyboard shortcut hint — always visible */}
-      {!showPopover && !rangeSelection && (
+      {/* Keyboard shortcut hint */}
+      {showShortcutHint && !showPopover && !rangeSelection && (
         <div className="absolute bottom-2 right-3 pointer-events-none z-20">
           <div
             className="flex items-center gap-1.5 px-2 py-1 rounded-md border"
diff --git a/packages/studio/src/player/components/TimelineClip.tsx b/packages/studio/src/player/components/TimelineClip.tsx
index 0bd3b3086..28ba52dd0 100644
--- a/packages/studio/src/player/components/TimelineClip.tsx
+++ b/packages/studio/src/player/components/TimelineClip.tsx
@@ -1,7 +1,7 @@
 import type { TimelineTrackStyle } from "./timelineTheme";
 // TimelineClip — Visual clip component for the NLE timeline.
 
-import { memo, type ReactNode } from "react";
+import { memo, useState, type ReactNode } from "react";
 import type { TimelineElement } from "../store/playerStore";
 import { defaultTimelineTheme, getClipHandleOpacity, type TimelineTheme } from "./timelineTheme";
 import { getTimelineEditCapabilities } from "./timelineEditing";
@@ -17,10 +17,16 @@ interface TimelineClipProps {
   theme?: TimelineTheme;
   trackStyle: TimelineTrackStyle;
   isComposition: boolean;
+  isInspectorActive?: boolean;
+  isThumbnailActive?: boolean;
+  thumbnailLabel?: string;
+  childCount?: number;
   onHoverStart: () => void;
   onHoverEnd: () => void;
   onPointerDown?: (e: React.PointerEvent) => void;
   onResizeStart?: (edge: "start" | "end", e: React.PointerEvent) => void;
+  onInspectorClick?: (e: React.MouseEvent) => void;
+  onThumbnailClick?: (e: React.MouseEvent) => void;
   onClick: (e: React.MouseEvent) => void;
   onDoubleClick: (e: React.MouseEvent) => void;
   children?: ReactNode;
@@ -37,32 +43,63 @@ export const TimelineClip = memo(function TimelineClip({
   theme = defaultTimelineTheme,
   trackStyle,
   isComposition,
+  isInspectorActive = false,
+  isThumbnailActive = false,
+  thumbnailLabel = "thumbnail",
+  childCount = 0,
   onHoverStart,
   onHoverEnd,
   onPointerDown,
   onResizeStart,
+  onInspectorClick,
+  onThumbnailClick,
   onClick,
   onDoubleClick,
   children,
 }: TimelineClipProps) {
+  const [localHovered, setLocalHovered] = useState(false);
+  const effectiveHovered = isHovered || localHovered;
   const leftPx = el.start * pps;
   const widthPx = Math.max(el.duration * pps, 4);
-  const handleOpacity = getClipHandleOpacity({ isHovered, isSelected, isDragging });
+  const handleOpacity = getClipHandleOpacity({
+    isHovered: effectiveHovered,
+    isSelected,
+    isDragging,
+  });
   const borderColor = isSelected
     ? theme.clipBorderActive
-    : isHovered
+    : effectiveHovered
       ? theme.clipBorderHover
       : theme.clipBorder;
   const boxShadow = isDragging
     ? theme.clipShadowDragging
     : isSelected
       ? theme.clipShadowActive
-      : isHovered
+      : effectiveHovered
         ? theme.clipShadowHover
         : theme.clipShadow;
   const capabilities = getTimelineEditCapabilities(el);
   const displayLabel = el.label || el.id || el.tag;
   const showHandles = handleOpacity > 0.01;
+  const baseBackgroundImage = isSelected ? theme.clipBackgroundActive : theme.clipBackground;
+  const glossBackgroundImage = isSelected
+    ? "linear-gradient(180deg, rgba(255,255,255,0.03), rgba(255,255,255,0))"
+    : "linear-gradient(180deg, rgba(255,255,255,0.02), rgba(255,255,255,0))";
+  const accentBackgroundImage = `linear-gradient(120deg, ${trackStyle.accent}${
+    isSelected ? "22" : "1e"
+  }, transparent 28%)`;
+  const compositionStripeBackgroundImage =
+    isComposition && !hasCustomContent
+      ? "repeating-linear-gradient(135deg, transparent, transparent 3px, rgba(255,255,255,0.05) 3px, rgba(255,255,255,0.05) 6px)"
+      : undefined;
+  const clipBackgroundImage = [
+    compositionStripeBackgroundImage,
+    glossBackgroundImage,
+    accentBackgroundImage,
+    baseBackgroundImage,
+  ]
+    .filter(Boolean)
+    .join(", ");
 
   return (
     <div
@@ -76,32 +113,71 @@ export const TimelineClip = memo(function TimelineClip({
         top: clipY,
         bottom: clipY,
         borderRadius: theme.clipRadius,
-        background: isSelected
-          ? `linear-gradient(180deg, rgba(255,255,255,0.03), rgba(255,255,255,0)), linear-gradient(120deg, ${trackStyle.accent}22, transparent 28%), ${theme.clipBackgroundActive}`
-          : `linear-gradient(180deg, rgba(255,255,255,0.02), rgba(255,255,255,0)), linear-gradient(120deg, ${trackStyle.accent}1e, transparent 28%), ${theme.clipBackground}`,
-        backgroundImage:
-          isComposition && !hasCustomContent
-            ? `repeating-linear-gradient(135deg, transparent, transparent 3px, rgba(255,255,255,0.05) 3px, rgba(255,255,255,0.05) 6px)`
-            : undefined,
+        backgroundImage: clipBackgroundImage,
         border: `1px solid ${borderColor}`,
         boxShadow,
         transition:
           "border-color 120ms ease-out, box-shadow 140ms ease-out, background 140ms ease-out",
-        zIndex: isDragging ? 20 : isSelected ? 10 : isHovered ? 5 : 1,
+        zIndex: isDragging ? 20 : isSelected ? 10 : effectiveHovered ? 5 : 1,
         cursor: capabilities.canMove ? "grab" : "default",
         transform: isDragging ? "translateY(-1px)" : undefined,
+        contain: "layout paint style",
       }}
       title={
         isComposition
           ? `${el.compositionSrc} \u2022 Double-click to open`
           : `${displayLabel} \u2022 ${el.start.toFixed(1)}s \u2013 ${(el.start + el.duration).toFixed(1)}s`
       }
-      onPointerEnter={onHoverStart}
-      onPointerLeave={onHoverEnd}
+      onPointerEnter={() => {
+        setLocalHovered(true);
+        onHoverStart();
+      }}
+      onPointerLeave={() => {
+        setLocalHovered(false);
+        onHoverEnd();
+      }}
       onPointerDown={onPointerDown}
       onClick={onClick}
       onDoubleClick={onDoubleClick}
     >
+      {childCount > 0 && !isDragging && (
+        <button
+          type="button"
+          className={`absolute left-1.5 top-1.5 z-20 flex h-5 items-center gap-1 rounded-md border px-1.5 text-[9px] font-semibold tabular-nums transition-colors ${
+            isInspectorActive
+              ? "border-studio-accent/70 bg-studio-accent/20 text-studio-accent"
+              : "border-white/10 bg-black/40 text-neutral-300 hover:border-studio-accent/50 hover:bg-studio-accent/10 hover:text-studio-accent"
+          }`}
+          data-timeline-layer-count={childCount}
+          aria-label={`Show ${childCount} nested selectable layer${childCount === 1 ? "" : "s"} for ${el.label || el.id || el.tag}`}
+          aria-pressed={isInspectorActive}
+          title={`Show ${childCount} nested selectable layer${childCount === 1 ? "" : "s"}`}
+          onPointerDown={(event) => {
+            event.stopPropagation();
+          }}
+          onClick={(event) => {
+            event.stopPropagation();
+            onInspectorClick?.(event);
+          }}
+        >
+          <svg
+            width="10"
+            height="10"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.8"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            aria-hidden="true"
+          >
+            <path d="M4 7h16" />
+            <path d="M7 12h13" />
+            <path d="M10 17h10" />
+          </svg>
+          {childCount}
+        </button>
+      )}
       <div
         aria-hidden="true"
         role="presentation"
@@ -174,6 +250,85 @@ export const TimelineClip = memo(function TimelineClip({
           }}
         />
       </div>
+      {(onThumbnailClick || onInspectorClick) && !isDragging && (
+        <div className="absolute right-1.5 top-1.5 z-20 flex items-center gap-1">
+          {onThumbnailClick && (
+            <button
+              type="button"
+              data-timeline-thumbnail-button="true"
+              aria-label={`${isThumbnailActive ? "Hide" : "Show"} ${thumbnailLabel} for ${el.label || el.id || el.tag}`}
+              aria-pressed={isThumbnailActive}
+              title={
+                isThumbnailActive ? `Hide clip ${thumbnailLabel}` : `Show clip ${thumbnailLabel}`
+              }
+              className={`flex h-5 w-5 items-center justify-center rounded-md border text-[10px] transition-colors ${
+                isThumbnailActive
+                  ? "border-studio-accent/70 bg-studio-accent/20 text-studio-accent"
+                  : "border-white/10 bg-black/35 text-neutral-400 hover:border-studio-accent/50 hover:bg-studio-accent/10 hover:text-studio-accent"
+              }`}
+              onPointerDown={(event) => {
+                event.stopPropagation();
+              }}
+              onClick={(event) => {
+                event.stopPropagation();
+                onThumbnailClick(event);
+              }}
+            >
+              <svg
+                width="12"
+                height="12"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.8"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden="true"
+              >
+                <rect x="3" y="5" width="18" height="14" rx="2" />
+                <circle cx="8" cy="10" r="1.5" />
+                <path d="m21 16-5-5L5 19" />
+              </svg>
+            </button>
+          )}
+          {onInspectorClick && (
+            <button
+              type="button"
+              data-timeline-inspector-button="true"
+              aria-label={`Inspect ${el.label || el.id || el.tag}`}
+              aria-pressed={isInspectorActive}
+              title={isInspectorActive ? "Disable clip inspector" : "Inspect clip in preview"}
+              className={`flex h-5 w-5 items-center justify-center rounded-md border text-[10px] transition-colors ${
+                isInspectorActive
+                  ? "border-studio-accent/70 bg-studio-accent/20 text-studio-accent"
+                  : "border-white/10 bg-black/35 text-neutral-400 hover:border-studio-accent/50 hover:bg-studio-accent/10 hover:text-studio-accent"
+              }`}
+              onPointerDown={(event) => {
+                event.stopPropagation();
+              }}
+              onClick={(event) => {
+                event.stopPropagation();
+                onInspectorClick(event);
+              }}
+            >
+              <svg
+                width="12"
+                height="12"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.8"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden="true"
+              >
+                <path d="M2 12s3.5-6 10-6 10 6 10 6-3.5 6-10 6S2 12 2 12Z" />
+                <circle cx="12" cy="12" r="2.5" />
+              </svg>
+            </button>
+          )}
+        </div>
+      )}
       {children}
     </div>
   );
diff --git a/packages/studio/src/player/components/TimelineThumbnailContent.test.ts b/packages/studio/src/player/components/TimelineThumbnailContent.test.ts
new file mode 100644
index 000000000..04bef20cc
--- /dev/null
+++ b/packages/studio/src/player/components/TimelineThumbnailContent.test.ts
@@ -0,0 +1,210 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import {
+  getTimelineThumbnailCaptureTimeSeconds,
+  getTimelineThumbnailTimeSeconds,
+  resolveTimelineElementThumbnailSourcePath,
+  resolveTimelineThumbnailSource,
+  resolveTimelineThumbnailSourcePath,
+  resolveTimelineVideoThumbnailSourcePath,
+} from "./TimelineThumbnailContent";
+
+const baseElement: TimelineElement = {
+  id: "clip",
+  tag: "div",
+  start: 10,
+  duration: 4,
+  track: 0,
+};
+
+describe("resolveTimelineThumbnailSourcePath", () => {
+  it("uses source composition paths directly", () => {
+    expect(
+      resolveTimelineThumbnailSourcePath({
+        ...baseElement,
+        compositionSrc: "compositions/manual.html",
+      }),
+    ).toBe("compositions/manual.html");
+  });
+
+  it("extracts composition paths from preview URLs", () => {
+    expect(
+      resolveTimelineThumbnailSourcePath({
+        ...baseElement,
+        compositionSrc:
+          "http://127.0.0.1:5196/api/projects/demo/preview/comp/compositions%2Fmanual.html",
+      }),
+    ).toBe("compositions/manual.html");
+  });
+
+  it("falls back to sourceFile and rejects non-composition sources", () => {
+    expect(resolveTimelineThumbnailSourcePath({ ...baseElement, sourceFile: "index.html" })).toBe(
+      "index.html",
+    );
+    expect(resolveTimelineThumbnailSourcePath({ ...baseElement, src: "assets/video.mp4" })).toBe(
+      null,
+    );
+  });
+});
+
+describe("resolveTimelineVideoThumbnailSourcePath", () => {
+  it("resolves root-relative project video assets", () => {
+    expect(
+      resolveTimelineVideoThumbnailSourcePath({
+        ...baseElement,
+        tag: "video",
+        src: "assets/avatar-visual.mp4",
+      }),
+    ).toBe("assets/avatar-visual.mp4");
+  });
+
+  it("resolves video assets relative to nested composition files", () => {
+    expect(
+      resolveTimelineVideoThumbnailSourcePath({
+        ...baseElement,
+        tag: "video",
+        sourceFile: "compositions/manual.html",
+        src: "../assets/demo.webm?cache=1",
+      }),
+    ).toBe("assets/demo.webm");
+  });
+
+  it("extracts project preview asset URLs", () => {
+    expect(
+      resolveTimelineVideoThumbnailSourcePath({
+        ...baseElement,
+        tag: "video",
+        src: "http://127.0.0.1:5196/api/projects/demo/preview/assets/avatar-visual.mp4",
+      }),
+    ).toBe("assets/avatar-visual.mp4");
+  });
+
+  it("rejects non-video and external media sources", () => {
+    expect(
+      resolveTimelineVideoThumbnailSourcePath({
+        ...baseElement,
+        tag: "img",
+        src: "assets/poster.png",
+      }),
+    ).toBe(null);
+    expect(
+      resolveTimelineVideoThumbnailSourcePath({
+        ...baseElement,
+        tag: "video",
+        src: "https://cdn.example.com/video.mp4",
+      }),
+    ).toBe(null);
+  });
+});
+
+describe("resolveTimelineElementThumbnailSourcePath", () => {
+  it("uses the explicit source file for DOM element thumbnails", () => {
+    expect(
+      resolveTimelineElementThumbnailSourcePath({
+        ...baseElement,
+        sourceFile: "compositions/manual.html",
+        selector: "#card",
+      }),
+    ).toBe("compositions/manual.html");
+  });
+
+  it("extracts the source file from stable timeline keys", () => {
+    expect(
+      resolveTimelineElementThumbnailSourcePath({
+        ...baseElement,
+        key: "index.html#beat-1",
+        selector: "#beat-1",
+      }),
+    ).toBe("index.html");
+    expect(
+      resolveTimelineElementThumbnailSourcePath({
+        ...baseElement,
+        key: "compositions/manual.html:.card:0",
+        selector: ".card",
+      }),
+    ).toBe("compositions/manual.html");
+  });
+});
+
+describe("resolveTimelineThumbnailSource", () => {
+  it("prefers composition thumbnails over nested media thumbnails", () => {
+    expect(
+      resolveTimelineThumbnailSource({
+        ...baseElement,
+        tag: "video",
+        compositionSrc: "compositions/hook.html",
+        src: "assets/avatar-visual.mp4",
+      }),
+    ).toEqual({ kind: "composition", sourcePath: "compositions/hook.html" });
+  });
+
+  it("falls back to visible video thumbnails for raw media clips", () => {
+    expect(
+      resolveTimelineThumbnailSource({
+        ...baseElement,
+        tag: "video",
+        src: "assets/avatar-visual.mp4",
+      }),
+    ).toEqual({ kind: "video", sourcePath: "assets/avatar-visual.mp4" });
+  });
+
+  it("falls back to selector captures for normal DOM timeline elements", () => {
+    expect(
+      resolveTimelineThumbnailSource({
+        ...baseElement,
+        key: "index.html#beat-1",
+        selector: "#beat-1",
+      }),
+    ).toEqual({
+      kind: "element",
+      sourcePath: "index.html",
+      selector: "#beat-1",
+      selectorIndex: undefined,
+    });
+  });
+
+  it("uses source-file selector captures for DOM elements before whole-composition captures", () => {
+    expect(
+      resolveTimelineThumbnailSource({
+        ...baseElement,
+        sourceFile: "index.html",
+        selector: "#beat-2",
+      }),
+    ).toEqual({
+      kind: "element",
+      sourcePath: "index.html",
+      selector: "#beat-2",
+      selectorIndex: undefined,
+    });
+  });
+});
+
+describe("getTimelineThumbnailTimeSeconds", () => {
+  it("uses the clip midpoint by default", () => {
+    expect(getTimelineThumbnailTimeSeconds(baseElement)).toBe(2);
+  });
+
+  it("adds playbackStart when present", () => {
+    expect(getTimelineThumbnailTimeSeconds({ ...baseElement, playbackStart: 5 })).toBe(7);
+  });
+});
+
+describe("getTimelineThumbnailCaptureTimeSeconds", () => {
+  it("uses source timeline time for selector captures", () => {
+    expect(
+      getTimelineThumbnailCaptureTimeSeconds(
+        { ...baseElement, start: 4.3, duration: 5.5, playbackStart: 20 },
+        { kind: "element", sourcePath: "index.html", selector: "#beat-2" },
+      ),
+    ).toBe(7.05);
+  });
+
+  it("keeps video captures on media time", () => {
+    expect(
+      getTimelineThumbnailCaptureTimeSeconds(
+        { ...baseElement, start: 4.3, duration: 5.5, playbackStart: 20 },
+        { kind: "video", sourcePath: "assets/demo.mp4" },
+      ),
+    ).toBe(22.75);
+  });
+});
diff --git a/packages/studio/src/player/components/TimelineThumbnailContent.tsx b/packages/studio/src/player/components/TimelineThumbnailContent.tsx
new file mode 100644
index 000000000..191b3be6c
--- /dev/null
+++ b/packages/studio/src/player/components/TimelineThumbnailContent.tsx
@@ -0,0 +1,407 @@
+import { memo, useEffect, useState } from "react";
+import type { TimelineElement } from "../store/playerStore";
+import { buildCompositionThumbnailUrl } from "./CompositionThumbnail";
+import { getStudioThumbnailService } from "../../thumbnails/studioThumbnailService";
+import { getCompositionPreviewUrl, isSourceCompositionPath } from "../../utils/compositionPaths";
+import { formatTime } from "../lib/time";
+
+export interface TimelineThumbnailContentProps {
+  element: TimelineElement;
+  projectId: string;
+  style: { clip: string; label: string; accent?: string };
+  resolveSourceHash: (path: string) => Promise<string>;
+}
+
+const TIMELINE_THUMBNAIL_WIDTH = 220;
+const TIMELINE_THUMBNAIL_HEIGHT = 72;
+const VIDEO_THUMBNAIL_IDLE_DELAY_MS = 1200;
+const VIDEO_SOURCE_EXT = /\.(mp4|m4v|mov|webm|ogv)(?:$|[?#])/i;
+
+export interface TimelineThumbnailSource {
+  kind: "composition" | "element" | "video";
+  sourcePath: string;
+  selector?: string;
+  selectorIndex?: number;
+}
+
+export function resolveTimelineThumbnailSource(
+  element: TimelineElement,
+): TimelineThumbnailSource | null {
+  const compositionPath = resolveTimelineThumbnailSourcePath(element);
+  if (compositionPath && element.compositionSrc) {
+    return { kind: "composition", sourcePath: compositionPath };
+  }
+
+  const videoPath = resolveTimelineVideoThumbnailSourcePath(element);
+  if (videoPath) return { kind: "video", sourcePath: videoPath };
+
+  const elementPath = resolveTimelineElementThumbnailSourcePath(element);
+  if (elementPath && element.selector) {
+    return {
+      kind: "element",
+      sourcePath: elementPath,
+      selector: element.selector,
+      selectorIndex: element.selectorIndex,
+    };
+  }
+
+  if (compositionPath) return { kind: "composition", sourcePath: compositionPath };
+
+  return null;
+}
+
+export function resolveTimelineThumbnailSourcePath(element: TimelineElement): string | null {
+  const candidates = [element.compositionSrc, element.sourceFile];
+  for (const candidate of candidates) {
+    const normalized = normalizeCompositionPath(candidate);
+    if (normalized) return normalized;
+  }
+  return null;
+}
+
+export function resolveTimelineVideoThumbnailSourcePath(element: TimelineElement): string | null {
+  const src = element.src;
+  if (!src || !isVideoTimelineSource(element, src)) return null;
+  return normalizeProjectAssetPath(src, element.sourceFile);
+}
+
+export function resolveTimelineElementThumbnailSourcePath(element: TimelineElement): string | null {
+  const direct = normalizeCompositionPath(element.sourceFile);
+  if (direct) return direct;
+
+  const keyed = normalizeCompositionPath(extractSourcePathFromTimelineKey(element.key));
+  if (keyed) return keyed;
+
+  return element.selector ? "index.html" : null;
+}
+
+export function getTimelineThumbnailTimeSeconds(element: TimelineElement): number {
+  const start = Number.isFinite(element.playbackStart)
+    ? Math.max(0, element.playbackStart ?? 0)
+    : 0;
+  const duration = Number.isFinite(element.duration) ? Math.max(0, element.duration) : 0;
+  return Math.round((start + duration / 2) * 100) / 100;
+}
+
+export function getTimelineThumbnailCaptureTimeSeconds(
+  element: TimelineElement,
+  source: TimelineThumbnailSource | null,
+): number {
+  if (source?.kind !== "element") return getTimelineThumbnailTimeSeconds(element);
+  const start = Number.isFinite(element.start) ? Math.max(0, element.start) : 0;
+  const duration = Number.isFinite(element.duration) ? Math.max(0, element.duration) : 0;
+  return Math.round((start + duration / 2) * 100) / 100;
+}
+
+export const TimelineThumbnailContent = memo(function TimelineThumbnailContent({
+  element,
+  projectId,
+  style,
+  resolveSourceHash,
+}: TimelineThumbnailContentProps) {
+  const [thumbnailUrl, setThumbnailUrl] = useState<string | null>(null);
+  const thumbnailSource = resolveTimelineThumbnailSource(element);
+  const sourceKind = thumbnailSource?.kind ?? null;
+  const sourcePath = thumbnailSource?.sourcePath ?? null;
+  const selector = thumbnailSource?.selector;
+  const selectorIndex = thumbnailSource?.selectorIndex;
+  const timeSeconds = getTimelineThumbnailCaptureTimeSeconds(element, thumbnailSource);
+
+  useEffect(() => {
+    const onCleared = (event: Event) => {
+      const detail = (event as CustomEvent<{ projectId?: string }>).detail;
+      if (!detail?.projectId || detail.projectId === projectId) setThumbnailUrl(null);
+    };
+    window.addEventListener("hf:thumbnail-cache-cleared", onCleared);
+    return () => window.removeEventListener("hf:thumbnail-cache-cleared", onCleared);
+  }, [projectId]);
+
+  useEffect(() => {
+    if (!sourceKind || !sourcePath) {
+      setThumbnailUrl(null);
+      return;
+    }
+
+    const controller = new AbortController();
+    let cancelled = false;
+
+    const requestThumbnail = () => {
+      void (async () => {
+        const objectUrl =
+          sourceKind === "composition"
+            ? await requestCompositionThumbnailUrl({
+                projectId,
+                sourcePath,
+                timeSeconds,
+                signal: controller.signal,
+                resolveSourceHash,
+              })
+            : sourceKind === "element"
+              ? await requestCompositionThumbnailUrl({
+                  projectId,
+                  sourcePath,
+                  timeSeconds,
+                  signal: controller.signal,
+                  resolveSourceHash,
+                  selector,
+                  selectorIndex,
+                })
+              : await requestVideoThumbnailUrl({
+                  projectId,
+                  sourcePath,
+                  timeSeconds,
+                  signal: controller.signal,
+                });
+        if (!cancelled && objectUrl) setThumbnailUrl(objectUrl);
+      })().catch((error: unknown) => {
+        if (!isAbortError(error)) setThumbnailUrl(null);
+      });
+    };
+
+    const delay =
+      sourceKind === "video"
+        ? window.setTimeout(requestThumbnail, VIDEO_THUMBNAIL_IDLE_DELAY_MS)
+        : null;
+    if (delay == null) requestThumbnail();
+
+    return () => {
+      cancelled = true;
+      if (delay != null) window.clearTimeout(delay);
+      controller.abort();
+    };
+  }, [
+    element.id,
+    projectId,
+    resolveSourceHash,
+    selector,
+    selectorIndex,
+    sourceKind,
+    sourcePath,
+    timeSeconds,
+  ]);
+
+  return (
+    <div className="absolute inset-0 overflow-hidden">
+      {thumbnailUrl && (sourceKind === "composition" || sourceKind === "element") && (
+        <img
+          src={thumbnailUrl}
+          alt=""
+          draggable={false}
+          className="absolute inset-0 h-full w-full object-cover opacity-55"
+        />
+      )}
+      {thumbnailUrl && sourceKind === "video" && (
+        <div
+          aria-hidden="true"
+          className="absolute inset-0 opacity-60"
+          style={{
+            backgroundImage: `url(${thumbnailUrl})`,
+            backgroundSize: `${TIMELINE_THUMBNAIL_WIDTH}px 100%`,
+            backgroundRepeat: "repeat-x",
+            backgroundPosition: "left center",
+          }}
+        />
+      )}
+      <div
+        className="absolute inset-0"
+        style={{
+          background: thumbnailUrl
+            ? "linear-gradient(90deg, rgba(0,0,0,0.72), rgba(0,0,0,0.2) 48%, rgba(0,0,0,0.65))"
+            : `linear-gradient(120deg, ${style.clip}22, transparent 34%), linear-gradient(180deg, rgba(255,255,255,0.03), rgba(0,0,0,0.18))`,
+        }}
+      />
+      <div className="absolute inset-0 flex h-full min-h-0 items-end px-6 py-3">
+        <div className="flex items-center">
+          <span className="max-w-full truncate rounded-md bg-black/45 px-1.5 py-0.5 text-[10px] font-medium tabular-nums leading-none text-white/70">
+            {formatTime(element.start)} {"\u2192"} {formatTime(element.start + element.duration)}
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+});
+
+async function requestCompositionThumbnailUrl({
+  projectId,
+  sourcePath,
+  timeSeconds,
+  signal,
+  resolveSourceHash,
+  selector,
+  selectorIndex,
+}: {
+  projectId: string;
+  sourcePath: string;
+  timeSeconds: number;
+  signal: AbortSignal;
+  resolveSourceHash: (path: string) => Promise<string>;
+  selector?: string;
+  selectorIndex?: number;
+}): Promise<string | null> {
+  const sourceHash = await resolveSourceHash(sourcePath);
+  if (signal.aborted) return null;
+  const previewUrl = getCompositionPreviewUrl(projectId, sourcePath);
+  const thumbnailRequestUrl = buildCompositionThumbnailUrl({
+    previewUrl,
+    seekTime: timeSeconds,
+    duration: 0,
+    selector,
+    selectorIndex,
+    origin: window.location.origin,
+  });
+  return getStudioThumbnailService().getThumbnailUrl({
+    key: {
+      projectId,
+      sourcePath,
+      sourceHash,
+      kind: "composition",
+      timeSeconds,
+      width: TIMELINE_THUMBNAIL_WIDTH,
+      height: TIMELINE_THUMBNAIL_HEIGHT,
+      devicePixelRatio: window.devicePixelRatio || 1,
+      version: selector ? 4 : 3,
+    },
+    url: thumbnailRequestUrl,
+    priority: "visible",
+    signal,
+  });
+}
+
+async function requestVideoThumbnailUrl({
+  projectId,
+  sourcePath,
+  timeSeconds,
+  signal,
+}: {
+  projectId: string;
+  sourcePath: string;
+  timeSeconds: number;
+  signal: AbortSignal;
+}): Promise<string | null> {
+  return getStudioThumbnailService().getVideoThumbnailUrl({
+    key: {
+      projectId,
+      sourcePath,
+      sourceHash: `media:${sourcePath}`,
+      kind: "video",
+      timeSeconds,
+      width: TIMELINE_THUMBNAIL_WIDTH,
+      height: TIMELINE_THUMBNAIL_HEIGHT,
+      devicePixelRatio: window.devicePixelRatio || 1,
+      version: 1,
+    },
+    loadBlob: (nextSignal) => fetchProjectAssetBlob(projectId, sourcePath, nextSignal),
+    priority: "visible",
+    signal,
+    fit: "cover",
+  });
+}
+
+function normalizeCompositionPath(value: string | undefined): string | null {
+  if (!value) return null;
+  try {
+    const parsed = value.startsWith("http") ? new URL(value) : null;
+    if (parsed) {
+      const marker = "/preview/comp/";
+      const markerIndex = parsed.pathname.indexOf(marker);
+      if (markerIndex >= 0) {
+        const encodedPath = parsed.pathname.slice(markerIndex + marker.length);
+        const path = decodeURIComponent(encodedPath);
+        return isSourceCompositionPath(path) ? path : null;
+      }
+      return null;
+    }
+  } catch {
+    return null;
+  }
+  const cleanPath = value.split("?")[0] ?? value;
+  return isSourceCompositionPath(cleanPath) ? cleanPath : null;
+}
+
+function extractSourcePathFromTimelineKey(key: string | undefined): string | undefined {
+  if (!key) return undefined;
+  const hashIndex = key.indexOf("#");
+  const selectorIndex = key.indexOf(":");
+  const splitIndex =
+    hashIndex >= 0 && selectorIndex >= 0
+      ? Math.min(hashIndex, selectorIndex)
+      : Math.max(hashIndex, selectorIndex);
+  return splitIndex > 0 ? key.slice(0, splitIndex) : undefined;
+}
+
+function isVideoTimelineSource(element: TimelineElement, src: string): boolean {
+  return element.tag.toLowerCase() === "video" || VIDEO_SOURCE_EXT.test(src);
+}
+
+function normalizeProjectAssetPath(value: string, sourceFile: string | undefined): string | null {
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.startsWith("data:") || trimmed.startsWith("blob:")) return null;
+
+  const previewPath = extractPreviewAssetPath(trimmed);
+  if (previewPath) return previewPath;
+
+  if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) return null;
+
+  const cleanPath = trimmed.split(/[?#]/)[0] ?? trimmed;
+  const baseDir = sourceFile?.includes("/") ? sourceFile.slice(0, sourceFile.lastIndexOf("/")) : "";
+  const normalized = normalizeRelativePath(baseDir ? `${baseDir}/${cleanPath}` : cleanPath);
+  return normalized && VIDEO_SOURCE_EXT.test(normalized) ? normalized : null;
+}
+
+function extractPreviewAssetPath(value: string): string | null {
+  try {
+    const parsed = value.startsWith("http") ? new URL(value) : null;
+    const path = parsed?.pathname ?? value;
+    const marker = "/preview/";
+    const markerIndex = path.indexOf(marker);
+    if (markerIndex < 0) return null;
+    const encodedPath = path.slice(markerIndex + marker.length);
+    if (!encodedPath || encodedPath.startsWith("comp/")) return null;
+    const decoded = decodeURIComponent(encodedPath);
+    return VIDEO_SOURCE_EXT.test(decoded) ? decoded : null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeRelativePath(path: string): string | null {
+  const parts: string[] = [];
+  for (const part of path.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === "..") {
+      if (parts.length === 0) return null;
+      parts.pop();
+      continue;
+    }
+    parts.push(part);
+  }
+  return parts.join("/");
+}
+
+async function fetchProjectAssetBlob(
+  projectId: string,
+  sourcePath: string,
+  signal: AbortSignal,
+): Promise<Blob | null> {
+  const response = await fetch(
+    `/api/projects/${encodeURIComponent(projectId)}/preview/${encodeRoutePath(sourcePath)}`,
+    { signal },
+  );
+  if (!response.ok) return null;
+  return response.blob();
+}
+
+function encodeRoutePath(path: string): string {
+  return path
+    .split("/")
+    .map((part) => encodeURIComponent(part))
+    .join("/");
+}
+
+function isAbortError(error: unknown): boolean {
+  return (
+    typeof DOMException !== "undefined" &&
+    error instanceof DOMException &&
+    error.name === "AbortError"
+  );
+}
diff --git a/packages/studio/src/player/components/timelineEditing.test.ts b/packages/studio/src/player/components/timelineEditing.test.ts
index 2ca13fe59..5282e621c 100644
--- a/packages/studio/src/player/components/timelineEditing.test.ts
+++ b/packages/studio/src/player/components/timelineEditing.test.ts
@@ -248,7 +248,7 @@ describe("getTimelineEditCapabilities", () => {
     });
   });
 
-  it("disables move and trims for generic motion clips even when patchable", () => {
+  it("allows moving generic motion clips while keeping trims blocked", () => {
     expect(
       getTimelineEditCapabilities({
         tag: "section",
@@ -256,7 +256,7 @@ describe("getTimelineEditCapabilities", () => {
         selector: ".feature-card",
       }),
     ).toEqual({
-      canMove: false,
+      canMove: true,
       canTrimStart: false,
       canTrimEnd: false,
     });
@@ -428,7 +428,6 @@ describe("buildClipRangeSelection", () => {
     });
   });
 });
-
 describe("resolveTimelineAutoScroll", () => {
   it("does not scroll when the pointer stays away from the edges", () => {
     expect(
@@ -512,7 +511,6 @@ describe("buildTimelineElementAgentPrompt", () => {
     ).toContain("If this clip is animated with GSAP");
   });
 });
-
 describe("resolveTimelineResize", () => {
   it("shrinks clip duration from the right edge", () => {
     expect(
diff --git a/packages/studio/src/player/components/timelineEditing.ts b/packages/studio/src/player/components/timelineEditing.ts
index 9f8ffc8ae..4016c0cd4 100644
--- a/packages/studio/src/player/components/timelineEditing.ts
+++ b/packages/studio/src/player/components/timelineEditing.ts
@@ -233,7 +233,7 @@ export function getTimelineEditCapabilities(input: {
   const hasFiniteDuration = Number.isFinite(input.duration) && input.duration > 0;
   const hasDeterministicWindow = isDeterministicTimelineWindow(input);
   return {
-    canMove: canPatch && hasDeterministicWindow,
+    canMove: canPatch && (hasDeterministicWindow || hasFiniteDuration),
     canTrimEnd: canPatch && hasFiniteDuration && hasDeterministicWindow,
     canTrimStart: canPatch && hasFiniteDuration && canOffsetTrimClipStart(input),
   };
@@ -273,7 +273,6 @@ export function buildClipRangeSelection(
     anchorY: anchor.anchorY,
   };
 }
-
 export function buildTimelineAgentPrompt({
   rangeStart,
   rangeEnd,
@@ -347,7 +346,6 @@ export function buildTimelineElementAgentPrompt(element: {
 
   return lines.join("\n");
 }
-
 export function formatTimelineAttributeNumber(value: number): string {
   return Number(roundToCentiseconds(value).toFixed(2)).toString();
 }
diff --git a/packages/studio/src/player/hooks/useTimelinePlayer.test.ts b/packages/studio/src/player/hooks/useTimelinePlayer.test.ts
index 2c89583f2..e18730a19 100644
--- a/packages/studio/src/player/hooks/useTimelinePlayer.test.ts
+++ b/packages/studio/src/player/hooks/useTimelinePlayer.test.ts
@@ -13,26 +13,6 @@ import {
   shouldIgnorePlaybackShortcutTarget,
 } from "./useTimelinePlayer";
 
-function mockTargetMatching(selectorNeedle: string): EventTarget {
-  return {
-    closest: (selector: string) => (selector.includes(selectorNeedle) ? ({} as Element) : null),
-  } as unknown as EventTarget;
-}
-
-function mockKeyboardEvent(
-  code: string,
-  overrides: Partial<Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey" | "target">> = {},
-): Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey" | "code" | "target"> {
-  return {
-    altKey: false,
-    ctrlKey: false,
-    metaKey: false,
-    code,
-    target: mockTargetMatching("[data-missing]"),
-    ...overrides,
-  };
-}
-
 function createDocument(markup: string): Document {
   const window = new Window();
   window.document.body.innerHTML = markup;
@@ -42,7 +22,7 @@ function createDocument(markup: string): Document {
 function createClip(overrides: Partial<ClipManifestClip>): ClipManifestClip {
   return {
     id: null,
-    label: "Element",
+    label: "",
     start: 0,
     duration: 4,
     track: 0,
@@ -56,6 +36,26 @@ function createClip(overrides: Partial<ClipManifestClip>): ClipManifestClip {
   };
 }
 
+function mockTargetMatching(selectorNeedle: string): EventTarget {
+  return {
+    closest: (selector: string) => (selector.includes(selectorNeedle) ? ({} as Element) : null),
+  } as unknown as EventTarget;
+}
+
+function mockKeyboardEvent(
+  code: string,
+  overrides: Partial<Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey" | "target">> = {},
+): Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey" | "code" | "target"> {
+  return {
+    altKey: false,
+    ctrlKey: false,
+    metaKey: false,
+    code,
+    target: mockTargetMatching("[data-missing]"),
+    ...overrides,
+  };
+}
+
 describe("buildStandaloneRootTimelineElement", () => {
   it("includes selector and source metadata for standalone composition fallback clips", () => {
     expect(
diff --git a/packages/studio/src/player/hooks/useTimelinePlayer.ts b/packages/studio/src/player/hooks/useTimelinePlayer.ts
index aa4f0ea25..017a4b7cf 100644
--- a/packages/studio/src/player/hooks/useTimelinePlayer.ts
+++ b/packages/studio/src/player/hooks/useTimelinePlayer.ts
@@ -22,9 +22,10 @@ interface TimelineLike {
   isActive: () => boolean;
 }
 
-interface ClipManifestClip {
+export interface ClipManifestClip {
   id: string | null;
   label: string;
+  timelineLabel?: string | null;
   start: number;
   duration: number;
   track: number;
@@ -220,7 +221,10 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
     const selectorIndex = getTimelineElementSelectorIndex(doc, el, selector);
     const label = getTimelineElementDisplayLabel({
       id: el.id || compId || null,
-      label: el.getAttribute("data-timeline-label") ?? el.getAttribute("data-label"),
+      label:
+        el.getAttribute("data-timeline-label") ??
+        el.getAttribute("data-label") ??
+        el.getAttribute("aria-label"),
       tag: tagLower,
     });
     const identity = buildTimelineElementIdentity({
@@ -335,7 +339,6 @@ function buildTimelineElementKey(params: {
   if (params.selector) return `${scope}:${params.selector}:${params.selectorIndex ?? 0}`;
   return `${scope}:${params.id}:${params.fallbackIndex}`;
 }
-
 function buildTimelineElementIdentity(params: {
   preferredId?: string | null;
   label: string;
@@ -557,7 +560,6 @@ export function buildStandaloneRootTimelineElement(params: {
     sourceFile: compositionSrc,
   };
 }
-
 function normalizePreviewViewport(doc: Document, win: Window): void {
   if (doc.documentElement) {
     doc.documentElement.style.overflow = "hidden";
@@ -1351,6 +1353,9 @@ export function useTimelinePlayer() {
     setIsPlaying(false);
   }, [getAdapter, stopRAFLoop, setIsPlaying, stopReverseLoop]);
 
+  const togglePlayRef = useRef(togglePlay);
+  togglePlayRef.current = togglePlay;
+
   const refreshPlayer = useCallback(() => {
     const iframe = iframeRef.current;
     if (!iframe) return;
@@ -1459,8 +1464,6 @@ export function useTimelinePlayer() {
       stopRAFLoop();
       stopReverseLoop();
       if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
-      // Don't reset() on cleanup — preserve timeline elements across iframe refreshes
-      // to prevent blink. New data will replace old when the iframe reloads.
     };
   });
 
diff --git a/packages/studio/src/styles/studio.css b/packages/studio/src/styles/studio.css
index aa2c6c1de..1299db4bc 100644
--- a/packages/studio/src/styles/studio.css
+++ b/packages/studio/src/styles/studio.css
@@ -9,6 +9,34 @@
  */
 :root {
   color-scheme: dark;
+  scrollbar-color: #737373 transparent;
+  scrollbar-width: thin;
+}
+
+* {
+  scrollbar-color: #737373 transparent;
+  scrollbar-width: thin;
+}
+
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: #737373;
+  border: 2px solid transparent;
+  border-radius: 999px;
+  background-clip: content-box;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: #8a8a8a;
+  background-clip: content-box;
 }
 
 body {
diff --git a/packages/studio/src/thumbnails/browserVideoThumbnail.ts b/packages/studio/src/thumbnails/browserVideoThumbnail.ts
new file mode 100644
index 000000000..806351c9f
--- /dev/null
+++ b/packages/studio/src/thumbnails/browserVideoThumbnail.ts
@@ -0,0 +1,139 @@
+import type { MediabunnyVideoThumbnailRequest } from "./mediabunnyVideoThumbnail";
+
+export async function createBrowserVideoThumbnail({
+  blob,
+  timeSeconds,
+  width,
+  height,
+  fit = "cover",
+  type = "image/webp",
+  quality = 0.82,
+  signal,
+}: MediabunnyVideoThumbnailRequest): Promise<Blob | null> {
+  throwIfAborted(signal);
+  if (typeof document === "undefined") return null;
+
+  const objectUrl = URL.createObjectURL(blob);
+  const video = document.createElement("video");
+  video.muted = true;
+  video.playsInline = true;
+  video.preload = "metadata";
+  video.src = objectUrl;
+
+  try {
+    await waitForVideoEvent(video, "loadedmetadata", signal);
+    throwIfAborted(signal);
+
+    const duration = Number.isFinite(video.duration) ? video.duration : 0;
+    video.currentTime = clamp(timeSeconds, 0, Math.max(0, duration));
+    await waitForVideoEvent(video, "seeked", signal);
+    throwIfAborted(signal);
+
+    const canvas = document.createElement("canvas");
+    canvas.width = Math.max(1, Math.round(width));
+    canvas.height = Math.max(1, Math.round(height));
+    const context = canvas.getContext("2d", { alpha: true });
+    if (!context) return null;
+
+    drawVideoFrame(context, video, canvas.width, canvas.height, fit);
+    return await canvasToBlob(canvas, type, quality);
+  } finally {
+    video.removeAttribute("src");
+    video.load();
+    URL.revokeObjectURL(objectUrl);
+  }
+}
+
+function drawVideoFrame(
+  context: CanvasRenderingContext2D,
+  video: HTMLVideoElement,
+  width: number,
+  height: number,
+  fit: "fill" | "contain" | "cover",
+): void {
+  const videoWidth = Math.max(1, video.videoWidth);
+  const videoHeight = Math.max(1, video.videoHeight);
+
+  if (fit === "fill") {
+    context.drawImage(video, 0, 0, width, height);
+    return;
+  }
+
+  const scale =
+    fit === "contain"
+      ? Math.min(width / videoWidth, height / videoHeight)
+      : Math.max(width / videoWidth, height / videoHeight);
+  const drawWidth = videoWidth * scale;
+  const drawHeight = videoHeight * scale;
+  const x = (width - drawWidth) / 2;
+  const y = (height - drawHeight) / 2;
+
+  context.clearRect(0, 0, width, height);
+  context.drawImage(video, x, y, drawWidth, drawHeight);
+}
+
+function waitForVideoEvent(
+  video: HTMLVideoElement,
+  eventName: "loadedmetadata" | "seeked",
+  signal: AbortSignal | undefined,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      video.removeEventListener(eventName, onEvent);
+      video.removeEventListener("error", onError);
+      signal?.removeEventListener("abort", onAbort);
+    };
+    const onEvent = () => {
+      cleanup();
+      resolve();
+    };
+    const onError = () => {
+      cleanup();
+      reject(new Error("Failed to decode video thumbnail."));
+    };
+    const onAbort = () => {
+      cleanup();
+      reject(createAbortError(signal?.reason));
+    };
+
+    if (signal?.aborted) {
+      reject(createAbortError(signal.reason));
+      return;
+    }
+
+    video.addEventListener(eventName, onEvent, { once: true });
+    video.addEventListener("error", onError, { once: true });
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function canvasToBlob(canvas: HTMLCanvasElement, type: string, quality: number): Promise<Blob> {
+  return new Promise((resolve, reject) => {
+    canvas.toBlob(
+      (blob) => {
+        if (blob) resolve(blob);
+        else reject(new Error("Failed to encode browser video thumbnail canvas."));
+      },
+      type,
+      quality,
+    );
+  });
+}
+
+function clamp(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min;
+  return Math.min(max, Math.max(min, value));
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (!signal?.aborted) return;
+  throw createAbortError(signal.reason);
+}
+
+function createAbortError(reason: unknown): Error {
+  if (reason instanceof Error) return reason;
+  if (typeof DOMException === "function") {
+    return new DOMException("Browser video thumbnail request aborted.", "AbortError");
+  }
+  return new Error("Browser video thumbnail request aborted.");
+}
diff --git a/packages/studio/src/thumbnails/indexedDbThumbnailCache.test.ts b/packages/studio/src/thumbnails/indexedDbThumbnailCache.test.ts
new file mode 100644
index 000000000..3402fc2e9
--- /dev/null
+++ b/packages/studio/src/thumbnails/indexedDbThumbnailCache.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import { selectThumbnailEvictions } from "./indexedDbThumbnailCache";
+
+describe("selectThumbnailEvictions", () => {
+  it("evicts oldest records until the byte budget fits", () => {
+    expect(
+      selectThumbnailEvictions(
+        [
+          { key: "new", byteSize: 8, updatedAt: 30 },
+          { key: "old", byteSize: 8, updatedAt: 10 },
+          { key: "middle", byteSize: 8, updatedAt: 20 },
+        ],
+        { maxBytes: 16, maxEntries: 10 },
+      ),
+    ).toEqual(["old"]);
+  });
+
+  it("evicts oldest records until the entry budget fits", () => {
+    expect(
+      selectThumbnailEvictions(
+        [
+          { key: "a", byteSize: 1, updatedAt: 10 },
+          { key: "b", byteSize: 1, updatedAt: 20 },
+          { key: "c", byteSize: 1, updatedAt: 30 },
+        ],
+        { maxBytes: 10, maxEntries: 1 },
+      ),
+    ).toEqual(["a", "b"]);
+  });
+
+  it("keeps records when both budgets fit", () => {
+    expect(
+      selectThumbnailEvictions(
+        [
+          { key: "a", byteSize: 1, updatedAt: 10 },
+          { key: "b", byteSize: 1, updatedAt: 20 },
+        ],
+        { maxBytes: 10, maxEntries: 10 },
+      ),
+    ).toEqual([]);
+  });
+});
diff --git a/packages/studio/src/thumbnails/indexedDbThumbnailCache.ts b/packages/studio/src/thumbnails/indexedDbThumbnailCache.ts
new file mode 100644
index 000000000..abe14b8e9
--- /dev/null
+++ b/packages/studio/src/thumbnails/indexedDbThumbnailCache.ts
@@ -0,0 +1,212 @@
+import type { ThumbnailKey } from "./thumbnailKey";
+
+export interface PersistentThumbnailRecord {
+  key: string;
+  projectId: string;
+  sourcePath: string;
+  sourceHash: string;
+  kind: ThumbnailKey["kind"];
+  blob: Blob;
+  byteSize: number;
+  updatedAt: number;
+}
+
+export interface IndexedDbThumbnailCacheOptions {
+  dbName?: string;
+  storeName?: string;
+  maxBytes?: number;
+  maxEntries?: number;
+  now?: () => number;
+}
+
+export interface ThumbnailEvictionRecord {
+  key: string;
+  byteSize: number;
+  updatedAt: number;
+}
+
+const DEFAULT_DB_NAME = "hyperframes-studio-thumbnails";
+const DEFAULT_STORE_NAME = "thumbnails";
+const DEFAULT_MAX_BYTES = 96 * 1024 * 1024;
+const DEFAULT_MAX_ENTRIES = 600;
+const DB_VERSION = 1;
+
+export function selectThumbnailEvictions(
+  records: ThumbnailEvictionRecord[],
+  options: { maxBytes: number; maxEntries: number },
+): string[] {
+  const maxBytes = Math.max(0, options.maxBytes);
+  const maxEntries = Math.max(0, options.maxEntries);
+  let totalBytes = records.reduce((total, record) => total + Math.max(0, record.byteSize), 0);
+  let totalEntries = records.length;
+  const evictions: string[] = [];
+
+  const oldestFirst = [...records].sort((a, b) => a.updatedAt - b.updatedAt);
+  for (const record of oldestFirst) {
+    if (totalEntries <= maxEntries && totalBytes <= maxBytes) break;
+    evictions.push(record.key);
+    totalEntries -= 1;
+    totalBytes -= Math.max(0, record.byteSize);
+  }
+
+  return evictions;
+}
+
+export class IndexedDbThumbnailCache {
+  private dbPromise: Promise<IDBDatabase> | null = null;
+  private readonly dbName: string;
+  private readonly storeName: string;
+  private readonly maxBytes: number;
+  private readonly maxEntries: number;
+  private readonly now: () => number;
+
+  constructor(options: IndexedDbThumbnailCacheOptions = {}) {
+    this.dbName = options.dbName ?? DEFAULT_DB_NAME;
+    this.storeName = options.storeName ?? DEFAULT_STORE_NAME;
+    this.maxBytes = Math.max(0, options.maxBytes ?? DEFAULT_MAX_BYTES);
+    this.maxEntries = Math.max(0, options.maxEntries ?? DEFAULT_MAX_ENTRIES);
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  get supported(): boolean {
+    return typeof indexedDB !== "undefined";
+  }
+
+  async get(key: string): Promise<PersistentThumbnailRecord | null> {
+    const record = await this.withStore("readwrite", (store) => requestToPromise(store.get(key)));
+    if (!isThumbnailRecord(record)) return null;
+    record.updatedAt = this.now();
+    await this.withStore("readwrite", (store) => requestToPromise(store.put(record)));
+    return record;
+  }
+
+  async set(record: Omit<PersistentThumbnailRecord, "updatedAt">): Promise<void> {
+    const stored: PersistentThumbnailRecord = {
+      ...record,
+      byteSize: Math.max(0, Math.ceil(record.byteSize)),
+      updatedAt: this.now(),
+    };
+    await this.withStore("readwrite", (store) => requestToPromise(store.put(stored)));
+    await this.prune();
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.withStore("readwrite", (store) => requestToPromise(store.delete(key)));
+  }
+
+  async clearProject(projectId: string): Promise<void> {
+    const records = await this.listRecords();
+    const keys = records
+      .filter((record) => record.projectId === projectId)
+      .map((record) => record.key);
+    await this.deleteMany(keys);
+  }
+
+  async clear(): Promise<void> {
+    await this.withStore("readwrite", (store) => requestToPromise(store.clear()));
+  }
+
+  async prune(): Promise<string[]> {
+    const records = await this.listRecords();
+    const evictions = selectThumbnailEvictions(records, {
+      maxBytes: this.maxBytes,
+      maxEntries: this.maxEntries,
+    });
+    await this.deleteMany(evictions);
+    return evictions;
+  }
+
+  private async deleteMany(keys: string[]): Promise<void> {
+    if (keys.length === 0) return;
+    await this.withStore("readwrite", async (store) => {
+      await Promise.all(keys.map((key) => requestToPromise(store.delete(key))));
+    });
+  }
+
+  private async listRecords(): Promise<PersistentThumbnailRecord[]> {
+    const records = await this.withStore("readonly", (store) =>
+      requestToPromise(store.getAll() as IDBRequest<unknown[]>),
+    );
+    return records.filter(isThumbnailRecord);
+  }
+
+  private async withStore<T>(
+    mode: IDBTransactionMode,
+    action: (store: IDBObjectStore) => Promise<T>,
+  ): Promise<T> {
+    if (!this.supported) throw new Error("IndexedDB is not available for thumbnail caching.");
+    const db = await this.openDb();
+    return new Promise<T>((resolve, reject) => {
+      const transaction = db.transaction(this.storeName, mode);
+      const store = transaction.objectStore(this.storeName);
+      let actionSettled = false;
+      let actionValue: T | undefined;
+
+      void action(store)
+        .then((value) => {
+          actionSettled = true;
+          actionValue = value;
+        })
+        .catch((error: unknown) => {
+          actionSettled = true;
+          reject(error);
+          transaction.abort();
+        });
+
+      transaction.oncomplete = () => {
+        if (!actionSettled) {
+          reject(new Error("IndexedDB transaction completed before thumbnail action settled."));
+          return;
+        }
+        resolve(actionValue as T);
+      };
+      transaction.onerror = () => reject(transaction.error ?? new Error("IndexedDB failed."));
+      transaction.onabort = () => reject(transaction.error ?? new Error("IndexedDB aborted."));
+    });
+  }
+
+  private openDb(): Promise<IDBDatabase> {
+    if (this.dbPromise) return this.dbPromise;
+    this.dbPromise = new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.dbName, DB_VERSION);
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        const store = db.objectStoreNames.contains(this.storeName)
+          ? request.transaction?.objectStore(this.storeName)
+          : db.createObjectStore(this.storeName, { keyPath: "key" });
+        if (store && !store.indexNames.contains("projectId")) {
+          store.createIndex("projectId", "projectId", { unique: false });
+        }
+        if (store && !store.indexNames.contains("updatedAt")) {
+          store.createIndex("updatedAt", "updatedAt", { unique: false });
+        }
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error ?? new Error("Failed to open IndexedDB."));
+    });
+    return this.dbPromise;
+  }
+}
+
+function requestToPromise<T>(request: IDBRequest<T>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error("IndexedDB request failed."));
+  });
+}
+
+function isThumbnailRecord(value: unknown): value is PersistentThumbnailRecord {
+  if (!value || typeof value !== "object") return false;
+  const record = value as Partial<PersistentThumbnailRecord>;
+  return (
+    typeof record.key === "string" &&
+    typeof record.projectId === "string" &&
+    typeof record.sourcePath === "string" &&
+    typeof record.sourceHash === "string" &&
+    typeof record.kind === "string" &&
+    typeof record.byteSize === "number" &&
+    typeof record.updatedAt === "number" &&
+    typeof Blob !== "undefined" &&
+    record.blob instanceof Blob
+  );
+}
diff --git a/packages/studio/src/thumbnails/mediabunnyVideoThumbnail.ts b/packages/studio/src/thumbnails/mediabunnyVideoThumbnail.ts
new file mode 100644
index 000000000..a0022d8de
--- /dev/null
+++ b/packages/studio/src/thumbnails/mediabunnyVideoThumbnail.ts
@@ -0,0 +1,111 @@
+export interface MediabunnyVideoThumbnailRequest {
+  blob: Blob;
+  timeSeconds: number;
+  width: number;
+  height: number;
+  fit?: "fill" | "contain" | "cover";
+  type?: "image/png" | "image/webp";
+  quality?: number;
+  signal?: AbortSignal;
+}
+
+export interface MediabunnyVideoThumbnailResult {
+  blob: Blob;
+  timestamp: number;
+  duration: number;
+}
+
+type ThumbnailCanvas = HTMLCanvasElement | OffscreenCanvas;
+
+export function canUseMediabunnyVideoThumbnails(): boolean {
+  return typeof Blob !== "undefined" && typeof VideoDecoder !== "undefined";
+}
+
+export async function createMediabunnyVideoThumbnail({
+  blob,
+  timeSeconds,
+  width,
+  height,
+  fit = "cover",
+  type = "image/webp",
+  quality = 0.82,
+  signal,
+}: MediabunnyVideoThumbnailRequest): Promise<MediabunnyVideoThumbnailResult | null> {
+  throwIfAborted(signal);
+
+  const { ALL_FORMATS, BlobSource, CanvasSink, Input } = await import("mediabunny");
+  const input = new Input({
+    source: new BlobSource(blob, { maxCacheSize: 8 * 1024 * 1024 }),
+    formats: ALL_FORMATS,
+  });
+
+  const abort = () => input.dispose();
+  signal?.addEventListener("abort", abort, { once: true });
+
+  try {
+    throwIfAborted(signal);
+    const videoTrack = await input.getPrimaryVideoTrack();
+    if (!videoTrack) return null;
+
+    throwIfAborted(signal);
+    const sink = new CanvasSink(videoTrack, {
+      width: Math.max(1, Math.round(width)),
+      height: Math.max(1, Math.round(height)),
+      fit,
+      poolSize: 1,
+    });
+    const frame = await sink.getCanvas(Math.max(0, timeSeconds), {
+      skipLiveWait: true,
+      verifyKeyPackets: false,
+    });
+
+    throwIfAborted(signal);
+    if (!frame) return null;
+
+    return {
+      blob: await canvasToBlob(frame.canvas, type, quality),
+      timestamp: frame.timestamp,
+      duration: frame.duration,
+    };
+  } finally {
+    signal?.removeEventListener("abort", abort);
+    input.dispose();
+  }
+}
+
+async function canvasToBlob(canvas: ThumbnailCanvas, type: string, quality: number): Promise<Blob> {
+  if (hasConvertToBlob(canvas)) {
+    return canvas.convertToBlob({ type, quality });
+  }
+
+  return new Promise((resolve, reject) => {
+    canvas.toBlob(
+      (blob) => {
+        if (blob) {
+          resolve(blob);
+        } else {
+          reject(new Error("Failed to encode Mediabunny thumbnail canvas."));
+        }
+      },
+      type,
+      quality,
+    );
+  });
+}
+
+function hasConvertToBlob(canvas: ThumbnailCanvas): canvas is OffscreenCanvas {
+  return "convertToBlob" in canvas;
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (!signal?.aborted) return;
+  throw createAbortError(signal.reason);
+}
+
+function createAbortError(reason: unknown): Error {
+  if (reason instanceof Error) return reason;
+  if (typeof DOMException === "function") {
+    return new DOMException("Mediabunny thumbnail request aborted.", "AbortError");
+  }
+  return new Error("Mediabunny thumbnail request aborted.");
+}
diff --git a/packages/studio/src/thumbnails/memoryThumbnailCache.test.ts b/packages/studio/src/thumbnails/memoryThumbnailCache.test.ts
new file mode 100644
index 000000000..5931a2cfb
--- /dev/null
+++ b/packages/studio/src/thumbnails/memoryThumbnailCache.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { MemoryThumbnailCache } from "./memoryThumbnailCache";
+
+describe("MemoryThumbnailCache", () => {
+  it("evicts the least recently used entry when the byte budget is exceeded", () => {
+    const disposed: string[] = [];
+    const cache = new MemoryThumbnailCache<string>({ maxBytes: 10, maxEntries: 10 });
+
+    cache.set("a", { value: "a", byteSize: 4, dispose: (value) => disposed.push(value) });
+    cache.set("b", { value: "b", byteSize: 4, dispose: (value) => disposed.push(value) });
+    expect(cache.get("a")).toBe("a");
+
+    cache.set("c", { value: "c", byteSize: 4, dispose: (value) => disposed.push(value) });
+
+    expect(cache.has("a")).toBe(true);
+    expect(cache.has("b")).toBe(false);
+    expect(cache.has("c")).toBe(true);
+    expect(disposed).toEqual(["b"]);
+    expect(cache.stats()).toMatchObject({ entries: 2, bytes: 8 });
+  });
+
+  it("evicts by entry count and disposes replaced values", () => {
+    const disposed: string[] = [];
+    const cache = new MemoryThumbnailCache<string>({ maxBytes: 100, maxEntries: 1 });
+
+    cache.set("a", { value: "old", byteSize: 4, dispose: (value) => disposed.push(value) });
+    cache.set("a", { value: "new", byteSize: 4, dispose: (value) => disposed.push(value) });
+    cache.set("b", { value: "b", byteSize: 4, dispose: (value) => disposed.push(value) });
+
+    expect(cache.get("a")).toBeUndefined();
+    expect(cache.get("b")).toBe("b");
+    expect(disposed).toEqual(["old", "new"]);
+  });
+
+  it("clears every cached value", () => {
+    const disposed: string[] = [];
+    const cache = new MemoryThumbnailCache<string>();
+
+    cache.set("a", { value: "a", byteSize: 4, dispose: (value) => disposed.push(value) });
+    cache.set("b", { value: "b", byteSize: 4, dispose: (value) => disposed.push(value) });
+    cache.clear();
+
+    expect(cache.stats()).toMatchObject({ entries: 0, bytes: 0 });
+    expect(disposed).toEqual(["a", "b"]);
+  });
+});
diff --git a/packages/studio/src/thumbnails/memoryThumbnailCache.ts b/packages/studio/src/thumbnails/memoryThumbnailCache.ts
new file mode 100644
index 000000000..af7690da6
--- /dev/null
+++ b/packages/studio/src/thumbnails/memoryThumbnailCache.ts
@@ -0,0 +1,106 @@
+export interface MemoryThumbnailCacheOptions {
+  maxBytes?: number;
+  maxEntries?: number;
+}
+
+export interface MemoryThumbnailCacheEntry<T> {
+  value: T;
+  byteSize: number;
+  dispose?: (value: T) => void;
+}
+
+export interface MemoryThumbnailCacheStats {
+  entries: number;
+  bytes: number;
+  maxBytes: number;
+  maxEntries: number;
+}
+
+interface StoredEntry<T> extends MemoryThumbnailCacheEntry<T> {
+  key: string;
+}
+
+const DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
+const DEFAULT_MAX_ENTRIES = 64;
+
+export class MemoryThumbnailCache<T> {
+  readonly maxBytes: number;
+  readonly maxEntries: number;
+
+  private entries = new Map<string, StoredEntry<T>>();
+  private totalBytes = 0;
+
+  constructor(options: MemoryThumbnailCacheOptions = {}) {
+    this.maxBytes = Math.max(0, options.maxBytes ?? DEFAULT_MAX_BYTES);
+    this.maxEntries = Math.max(0, options.maxEntries ?? DEFAULT_MAX_ENTRIES);
+  }
+
+  get(key: string): T | undefined {
+    const entry = this.entries.get(key);
+    if (!entry) return undefined;
+
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    return entry.value;
+  }
+
+  has(key: string): boolean {
+    return this.entries.has(key);
+  }
+
+  set(key: string, entry: MemoryThumbnailCacheEntry<T>): void {
+    this.delete(key);
+
+    const byteSize = Math.max(0, Math.ceil(entry.byteSize));
+    this.entries.set(key, {
+      key,
+      value: entry.value,
+      byteSize,
+      dispose: entry.dispose,
+    });
+    this.totalBytes += byteSize;
+    this.prune();
+  }
+
+  delete(key: string): boolean {
+    const entry = this.entries.get(key);
+    if (!entry) return false;
+
+    this.entries.delete(key);
+    this.totalBytes -= entry.byteSize;
+    disposeEntry(entry);
+    return true;
+  }
+
+  clear(): void {
+    for (const entry of this.entries.values()) {
+      disposeEntry(entry);
+    }
+    this.entries.clear();
+    this.totalBytes = 0;
+  }
+
+  stats(): MemoryThumbnailCacheStats {
+    return {
+      entries: this.entries.size,
+      bytes: this.totalBytes,
+      maxBytes: this.maxBytes,
+      maxEntries: this.maxEntries,
+    };
+  }
+
+  private prune(): void {
+    while (
+      this.entries.size > 0 &&
+      (this.entries.size > this.maxEntries || this.totalBytes > this.maxBytes)
+    ) {
+      const oldestKey = this.entries.keys().next().value;
+      if (typeof oldestKey !== "string") return;
+      this.delete(oldestKey);
+    }
+  }
+}
+
+function disposeEntry<T>(entry: StoredEntry<T>): void {
+  entry.dispose?.(entry.value);
+}
diff --git a/packages/studio/src/thumbnails/sourceHash.test.ts b/packages/studio/src/thumbnails/sourceHash.test.ts
new file mode 100644
index 000000000..3a4177d45
--- /dev/null
+++ b/packages/studio/src/thumbnails/sourceHash.test.ts
@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { hashThumbnailSource } from "./sourceHash";
+
+describe("hashThumbnailSource", () => {
+  it("is stable for identical content", () => {
+    expect(hashThumbnailSource("<div>Hello</div>")).toBe(hashThumbnailSource("<div>Hello</div>"));
+  });
+
+  it("changes when source changes", () => {
+    expect(hashThumbnailSource("<div>Hello</div>")).not.toBe(
+      hashThumbnailSource("<div>Hello!</div>"),
+    );
+  });
+});
diff --git a/packages/studio/src/thumbnails/sourceHash.ts b/packages/studio/src/thumbnails/sourceHash.ts
new file mode 100644
index 000000000..ef36b28ad
--- /dev/null
+++ b/packages/studio/src/thumbnails/sourceHash.ts
@@ -0,0 +1,8 @@
+export function hashThumbnailSource(content: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < content.length; i += 1) {
+    hash ^= content.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(36);
+}
diff --git a/packages/studio/src/thumbnails/studioThumbnailService.test.ts b/packages/studio/src/thumbnails/studioThumbnailService.test.ts
new file mode 100644
index 000000000..9eb60b107
--- /dev/null
+++ b/packages/studio/src/thumbnails/studioThumbnailService.test.ts
@@ -0,0 +1,186 @@
+import { describe, expect, it, vi } from "vitest";
+import { StudioThumbnailService } from "./studioThumbnailService";
+import type { ThumbnailKey } from "./thumbnailKey";
+
+const key: ThumbnailKey = {
+  projectId: "demo",
+  sourcePath: "index.html",
+  sourceHash: "abc",
+  kind: "composition",
+  timeSeconds: 1,
+  width: 120,
+  height: 68,
+  devicePixelRatio: 1,
+  version: 1,
+};
+
+function createPersistentCache() {
+  const records = new Map<string, { blob: Blob; byteSize: number }>();
+  return {
+    records,
+    cache: {
+      async get(cacheKey: string) {
+        const record = records.get(cacheKey);
+        if (!record) return null;
+        return {
+          key: cacheKey,
+          projectId: key.projectId,
+          sourcePath: key.sourcePath,
+          sourceHash: key.sourceHash,
+          kind: key.kind,
+          blob: record.blob,
+          byteSize: record.byteSize,
+          updatedAt: 1,
+        };
+      },
+      async set(record: { key: string; blob: Blob; byteSize: number }) {
+        records.set(record.key, { blob: record.blob, byteSize: record.byteSize });
+      },
+      async clearProject() {
+        records.clear();
+      },
+    },
+  };
+}
+
+describe("StudioThumbnailService", () => {
+  it("dedupes in-flight thumbnail requests and reuses memory cache", async () => {
+    const persistent = createPersistentCache();
+    const fetchBlob = vi.fn(async () => new Blob(["thumb"], { type: "image/jpeg" }));
+    const service = new StudioThumbnailService({
+      persistentCache: persistent.cache,
+      fetchBlob,
+      createObjectUrl: () => "blob:thumb",
+      revokeObjectUrl: vi.fn(),
+    });
+
+    const [first, second] = await Promise.all([
+      service.getThumbnailUrl({ key, url: "/thumb", priority: "hover" }),
+      service.getThumbnailUrl({ key, url: "/thumb", priority: "hover" }),
+    ]);
+    const third = await service.getThumbnailUrl({ key, url: "/thumb", priority: "hover" });
+
+    expect(first).toBe("blob:thumb");
+    expect(second).toBe("blob:thumb");
+    expect(third).toBe("blob:thumb");
+    expect(fetchBlob).toHaveBeenCalledTimes(1);
+  });
+
+  it("falls back to persistent cache before fetching", async () => {
+    const persistent = createPersistentCache();
+    const cacheKey = [
+      "v=1",
+      "project=demo",
+      "source=index.html",
+      "hash=abc",
+      "kind=composition",
+      "time=1",
+      "w=120",
+      "h=68",
+      "dpr=1",
+    ].join(";");
+    persistent.records.set(cacheKey, {
+      blob: new Blob(["cached"], { type: "image/jpeg" }),
+      byteSize: 128,
+    });
+    const fetchBlob = vi.fn(async () => new Blob(["fresh"], { type: "image/jpeg" }));
+    const service = new StudioThumbnailService({
+      persistentCache: persistent.cache,
+      fetchBlob,
+      createObjectUrl: () => "blob:cached",
+      revokeObjectUrl: vi.fn(),
+    });
+
+    await expect(service.getThumbnailUrl({ key, url: "/thumb", priority: "hover" })).resolves.toBe(
+      "blob:cached",
+    );
+    expect(fetchBlob).not.toHaveBeenCalled();
+  });
+
+  it("generates video thumbnails through the injected decoder lane", async () => {
+    const persistent = createPersistentCache();
+    const createVideoThumbnailBlob = vi.fn(
+      async () => new Blob(["video-thumb"], { type: "image/webp" }),
+    );
+    const service = new StudioThumbnailService({
+      persistentCache: persistent.cache,
+      createVideoThumbnailBlob,
+      createObjectUrl: () => "blob:video-thumb",
+      revokeObjectUrl: vi.fn(),
+    });
+    const videoKey: ThumbnailKey = {
+      ...key,
+      sourcePath: "assets/demo.mp4",
+      sourceHash: "video-hash",
+      kind: "video",
+      timeSeconds: 3.2,
+    };
+
+    await expect(
+      service.getVideoThumbnailUrl({
+        key: videoKey,
+        blob: new Blob(["video"], { type: "video/mp4" }),
+        priority: "hover",
+        fit: "contain",
+      }),
+    ).resolves.toBe("blob:video-thumb");
+
+    expect(createVideoThumbnailBlob).toHaveBeenCalledWith(
+      expect.objectContaining({
+        blob: expect.any(Blob),
+        timeSeconds: 3.2,
+        width: 120,
+        height: 68,
+        fit: "contain",
+      }),
+    );
+  });
+
+  it("reuses persistent video thumbnails before loading source media", async () => {
+    const persistent = createPersistentCache();
+    const videoKey: ThumbnailKey = {
+      ...key,
+      sourcePath: "assets/demo.mp4",
+      sourceHash: "video-hash",
+      kind: "video",
+      timeSeconds: 3.2,
+    };
+    const cacheKey = [
+      "v=1",
+      "project=demo",
+      "source=assets%2Fdemo.mp4",
+      "hash=video-hash",
+      "kind=video",
+      "time=3.2",
+      "w=120",
+      "h=68",
+      "dpr=1",
+    ].join(";");
+    persistent.records.set(cacheKey, {
+      blob: new Blob(["cached-video-thumb"], { type: "image/webp" }),
+      byteSize: 128,
+    });
+    const createVideoThumbnailBlob = vi.fn(
+      async () => new Blob(["video-thumb"], { type: "image/webp" }),
+    );
+    const loadBlob = vi.fn(async () => new Blob(["video"], { type: "video/mp4" }));
+    const service = new StudioThumbnailService({
+      persistentCache: persistent.cache,
+      createVideoThumbnailBlob,
+      createObjectUrl: () => "blob:cached-video-thumb",
+      revokeObjectUrl: vi.fn(),
+    });
+
+    await expect(
+      service.getVideoThumbnailUrl({
+        key: videoKey,
+        loadBlob,
+        priority: "hover",
+        fit: "contain",
+      }),
+    ).resolves.toBe("blob:cached-video-thumb");
+
+    expect(loadBlob).not.toHaveBeenCalled();
+    expect(createVideoThumbnailBlob).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/studio/src/thumbnails/studioThumbnailService.ts b/packages/studio/src/thumbnails/studioThumbnailService.ts
new file mode 100644
index 000000000..bdaef006d
--- /dev/null
+++ b/packages/studio/src/thumbnails/studioThumbnailService.ts
@@ -0,0 +1,214 @@
+import { IndexedDbThumbnailCache, type PersistentThumbnailRecord } from "./indexedDbThumbnailCache";
+import { MemoryThumbnailCache } from "./memoryThumbnailCache";
+import { estimateThumbnailBytes, serializeThumbnailKey, type ThumbnailKey } from "./thumbnailKey";
+import { ThumbnailScheduler, type ThumbnailPriority } from "./thumbnailScheduler";
+import type { VideoThumbnailRequest } from "./videoThumbnail";
+
+export interface StudioThumbnailRequest {
+  key: ThumbnailKey;
+  url: string;
+  priority: ThumbnailPriority;
+  signal?: AbortSignal;
+}
+
+export interface StudioVideoThumbnailRequest {
+  key: ThumbnailKey;
+  priority: ThumbnailPriority;
+  blob?: Blob;
+  loadBlob?: (signal: AbortSignal) => Promise<Blob | null>;
+  signal?: AbortSignal;
+  fit?: VideoThumbnailRequest["fit"];
+  type?: VideoThumbnailRequest["type"];
+  quality?: number;
+}
+
+export interface StudioThumbnailServiceStats {
+  memory: ReturnType<MemoryThumbnailCache<string>["stats"]>;
+  scheduler: ReturnType<ThumbnailScheduler["stats"]>;
+}
+
+export interface StudioThumbnailServiceOptions {
+  memoryCache?: MemoryThumbnailCache<string>;
+  persistentCache?: Pick<IndexedDbThumbnailCache, "get" | "set" | "clearProject">;
+  scheduler?: ThumbnailScheduler;
+  fetchBlob?: (url: string, signal: AbortSignal) => Promise<Blob | null>;
+  createVideoThumbnailBlob?: (request: VideoThumbnailRequest) => Promise<Blob | null>;
+  createObjectUrl?: (blob: Blob) => string;
+  revokeObjectUrl?: (url: string) => void;
+}
+
+export class StudioThumbnailService {
+  private readonly memoryCache: MemoryThumbnailCache<string>;
+  private readonly persistentCache: Pick<IndexedDbThumbnailCache, "get" | "set" | "clearProject">;
+  private readonly scheduler: ThumbnailScheduler;
+  private readonly fetchBlob: (url: string, signal: AbortSignal) => Promise<Blob | null>;
+  private readonly createVideoThumbnailBlob: (
+    request: VideoThumbnailRequest,
+  ) => Promise<Blob | null>;
+  private readonly createObjectUrl: (blob: Blob) => string;
+  private readonly revokeObjectUrl: (url: string) => void;
+
+  constructor(options: StudioThumbnailServiceOptions = {}) {
+    this.memoryCache = options.memoryCache ?? new MemoryThumbnailCache<string>();
+    this.persistentCache = options.persistentCache ?? new IndexedDbThumbnailCache();
+    this.scheduler = options.scheduler ?? new ThumbnailScheduler();
+    this.fetchBlob = options.fetchBlob ?? fetchThumbnailBlob;
+    this.createVideoThumbnailBlob = options.createVideoThumbnailBlob ?? createDefaultVideoThumbnail;
+    this.createObjectUrl = options.createObjectUrl ?? createBrowserObjectUrl;
+    this.revokeObjectUrl = options.revokeObjectUrl ?? revokeBrowserObjectUrl;
+  }
+
+  async getThumbnailUrl(request: StudioThumbnailRequest): Promise<string | null> {
+    const cacheKey = serializeThumbnailKey(request.key);
+    const cachedUrl = this.memoryCache.get(cacheKey);
+    if (cachedUrl) return cachedUrl;
+
+    const result = await this.scheduler.schedule({
+      key: cacheKey,
+      priority: request.priority,
+      signal: request.signal,
+      task: async (signal) => {
+        const persistent = await this.getPersistent(cacheKey);
+        if (persistent) return this.storeObjectUrl(cacheKey, persistent.blob, persistent.byteSize);
+
+        const blob = await this.fetchBlob(request.url, signal);
+        if (!blob) return null;
+
+        const byteSize = estimateThumbnailBytes(
+          request.key.width,
+          request.key.height,
+          request.key.devicePixelRatio,
+        );
+        await this.setPersistent({
+          key: cacheKey,
+          projectId: request.key.projectId,
+          sourcePath: request.key.sourcePath,
+          sourceHash: request.key.sourceHash,
+          kind: request.key.kind,
+          blob,
+          byteSize,
+          updatedAt: 0,
+        });
+        return this.storeObjectUrl(cacheKey, blob, byteSize);
+      },
+    });
+
+    return typeof result === "string" ? result : null;
+  }
+
+  async getVideoThumbnailUrl(request: StudioVideoThumbnailRequest): Promise<string | null> {
+    const cacheKey = serializeThumbnailKey(request.key);
+    const cachedUrl = this.memoryCache.get(cacheKey);
+    if (cachedUrl) return cachedUrl;
+
+    const result = await this.scheduler.schedule({
+      key: cacheKey,
+      priority: request.priority,
+      signal: request.signal,
+      task: async (signal) => {
+        const persistent = await this.getPersistent(cacheKey);
+        if (persistent) return this.storeObjectUrl(cacheKey, persistent.blob, persistent.byteSize);
+
+        const sourceBlob = request.blob ?? (await request.loadBlob?.(signal));
+        if (!sourceBlob) return null;
+
+        const blob = await this.createVideoThumbnailBlob({
+          blob: sourceBlob,
+          timeSeconds: request.key.timeSeconds,
+          width: request.key.width,
+          height: request.key.height,
+          fit: request.fit,
+          type: request.type,
+          quality: request.quality,
+          signal,
+        });
+        if (!blob) return null;
+
+        const byteSize = estimateThumbnailBytes(
+          request.key.width,
+          request.key.height,
+          request.key.devicePixelRatio,
+        );
+        await this.setPersistent({
+          key: cacheKey,
+          projectId: request.key.projectId,
+          sourcePath: request.key.sourcePath,
+          sourceHash: request.key.sourceHash,
+          kind: request.key.kind,
+          blob,
+          byteSize,
+          updatedAt: 0,
+        });
+        return this.storeObjectUrl(cacheKey, blob, byteSize);
+      },
+    });
+
+    return typeof result === "string" ? result : null;
+  }
+
+  async clearProject(projectId: string): Promise<void> {
+    this.memoryCache.clear();
+    await this.persistentCache.clearProject(projectId).catch(() => {});
+    dispatchThumbnailCacheCleared(projectId);
+  }
+
+  stats(): StudioThumbnailServiceStats {
+    return {
+      memory: this.memoryCache.stats(),
+      scheduler: this.scheduler.stats(),
+    };
+  }
+
+  dispose(): void {
+    this.memoryCache.clear();
+  }
+
+  private storeObjectUrl(cacheKey: string, blob: Blob, byteSize: number): string {
+    const objectUrl = this.createObjectUrl(blob);
+    this.memoryCache.set(cacheKey, {
+      value: objectUrl,
+      byteSize,
+      dispose: this.revokeObjectUrl,
+    });
+    return objectUrl;
+  }
+
+  private async getPersistent(cacheKey: string): Promise<PersistentThumbnailRecord | null> {
+    return this.persistentCache.get(cacheKey).catch(() => null);
+  }
+
+  private async setPersistent(record: PersistentThumbnailRecord): Promise<void> {
+    await this.persistentCache.set(record).catch(() => {});
+  }
+}
+
+let singleton: StudioThumbnailService | null = null;
+
+export function getStudioThumbnailService(): StudioThumbnailService {
+  if (!singleton) singleton = new StudioThumbnailService();
+  return singleton;
+}
+
+async function fetchThumbnailBlob(url: string, signal: AbortSignal): Promise<Blob | null> {
+  const response = await fetch(url, { signal });
+  if (!response.ok) return null;
+  return response.blob();
+}
+
+async function createDefaultVideoThumbnail(request: VideoThumbnailRequest): Promise<Blob | null> {
+  const { createVideoThumbnail } = await import("./videoThumbnail");
+  return createVideoThumbnail(request);
+}
+
+function createBrowserObjectUrl(blob: Blob): string {
+  return URL.createObjectURL(blob);
+}
+
+function revokeBrowserObjectUrl(url: string): void {
+  URL.revokeObjectURL(url);
+}
+
+function dispatchThumbnailCacheCleared(projectId: string): void {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent("hf:thumbnail-cache-cleared", { detail: { projectId } }));
+}
diff --git a/packages/studio/src/thumbnails/thumbnailKey.test.ts b/packages/studio/src/thumbnails/thumbnailKey.test.ts
new file mode 100644
index 000000000..e183d58eb
--- /dev/null
+++ b/packages/studio/src/thumbnails/thumbnailKey.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { estimateThumbnailBytes, serializeThumbnailKey } from "./thumbnailKey";
+
+describe("thumbnail keys", () => {
+  it("serializes fields in a stable order", () => {
+    expect(
+      serializeThumbnailKey({
+        projectId: "demo project",
+        sourcePath: "compositions/intro.html",
+        sourceHash: "abc123",
+        kind: "html-element",
+        selector: ".hero h1",
+        selectorIndex: 2,
+        timeSeconds: 1.23456,
+        width: 160.4,
+        height: 90.4,
+        devicePixelRatio: 1.9999,
+        version: 1,
+      }),
+    ).toBe(
+      "v=1;project=demo%20project;source=compositions%2Fintro.html;hash=abc123;kind=html-element;time=1.235;w=160;h=90;dpr=2;selector=.hero%20h1;selectorIndex=2",
+    );
+  });
+
+  it("estimates decoded thumbnail memory by pixel count", () => {
+    expect(estimateThumbnailBytes(100, 50, 2)).toBe(80_000);
+  });
+});
diff --git a/packages/studio/src/thumbnails/thumbnailKey.ts b/packages/studio/src/thumbnails/thumbnailKey.ts
new file mode 100644
index 000000000..014c4a5a3
--- /dev/null
+++ b/packages/studio/src/thumbnails/thumbnailKey.ts
@@ -0,0 +1,55 @@
+export type ThumbnailKind = "composition" | "html-element" | "image" | "video" | "audio";
+
+export interface ThumbnailKey {
+  projectId: string;
+  sourcePath: string;
+  sourceHash: string;
+  kind: ThumbnailKind;
+  selector?: string;
+  selectorIndex?: number;
+  timeSeconds: number;
+  width: number;
+  height: number;
+  devicePixelRatio: number;
+  version: number;
+}
+
+export function serializeThumbnailKey(key: ThumbnailKey): string {
+  const parts = [
+    ["v", formatInteger(key.version)],
+    ["project", key.projectId],
+    ["source", key.sourcePath],
+    ["hash", key.sourceHash],
+    ["kind", key.kind],
+    ["time", formatNumber(key.timeSeconds)],
+    ["w", formatInteger(key.width)],
+    ["h", formatInteger(key.height)],
+    ["dpr", formatNumber(key.devicePixelRatio)],
+  ];
+
+  if (key.selector) parts.push(["selector", key.selector]);
+  if (key.selectorIndex != null) parts.push(["selectorIndex", formatInteger(key.selectorIndex)]);
+
+  return parts.map(([name, value]) => `${name}=${encodeURIComponent(value)}`).join(";");
+}
+
+export function estimateThumbnailBytes(
+  width: number,
+  height: number,
+  devicePixelRatio = 1,
+): number {
+  const pixelRatio = Math.max(1, devicePixelRatio);
+  return (
+    Math.max(1, Math.ceil(width * pixelRatio)) * Math.max(1, Math.ceil(height * pixelRatio)) * 4
+  );
+}
+
+function formatInteger(value: number): string {
+  return String(Math.max(0, Math.round(value)));
+}
+
+function formatNumber(value: number): string {
+  if (!Number.isFinite(value)) return "0";
+  const rounded = Math.round(value * 1000) / 1000;
+  return Object.is(rounded, -0) ? "0" : String(rounded);
+}
diff --git a/packages/studio/src/thumbnails/thumbnailMode.test.ts b/packages/studio/src/thumbnails/thumbnailMode.test.ts
new file mode 100644
index 000000000..32ceea93c
--- /dev/null
+++ b/packages/studio/src/thumbnails/thumbnailMode.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { normalizeThumbnailMode, shouldRequestThumbnail } from "./thumbnailMode";
+
+describe("normalizeThumbnailMode", () => {
+  it("accepts known modes", () => {
+    expect(normalizeThumbnailMode("off")).toBe("off");
+    expect(normalizeThumbnailMode("hover")).toBe("visible");
+    expect(normalizeThumbnailMode("visible")).toBe("visible");
+    expect(normalizeThumbnailMode("always")).toBe("always");
+  });
+
+  it("defaults unknown values to disabled thumbnails", () => {
+    expect(normalizeThumbnailMode("fast")).toBe("off");
+    expect(normalizeThumbnailMode(null)).toBe("off");
+  });
+});
+
+describe("shouldRequestThumbnail", () => {
+  it("keeps off mode cold", () => {
+    expect(shouldRequestThumbnail("off", { hovered: true, visible: true })).toBe(false);
+  });
+
+  it("only requests hover mode while hovered", () => {
+    expect(shouldRequestThumbnail("hover", { hovered: false })).toBe(false);
+    expect(shouldRequestThumbnail("hover", { hovered: true })).toBe(true);
+  });
+
+  it("requests visible and always modes deterministically", () => {
+    expect(shouldRequestThumbnail("visible", { visible: true })).toBe(true);
+    expect(shouldRequestThumbnail("visible", { visible: false })).toBe(false);
+    expect(shouldRequestThumbnail("always", { visible: false })).toBe(true);
+  });
+});
diff --git a/packages/studio/src/thumbnails/thumbnailMode.ts b/packages/studio/src/thumbnails/thumbnailMode.ts
new file mode 100644
index 000000000..84e1ec852
--- /dev/null
+++ b/packages/studio/src/thumbnails/thumbnailMode.ts
@@ -0,0 +1,39 @@
+export type ThumbnailMode = "off" | "hover" | "visible" | "always";
+
+export const THUMBNAIL_MODE_STORAGE_KEY = "hf-studio-thumbnail-mode-v2";
+export const DEFAULT_THUMBNAIL_MODE: ThumbnailMode = "off";
+
+export function normalizeThumbnailMode(value: unknown): ThumbnailMode {
+  if (value === "visible" || value === "always" || value === "off") return value;
+  if (value === "hover") return "visible";
+  return DEFAULT_THUMBNAIL_MODE;
+}
+
+export function shouldRequestThumbnail(
+  mode: ThumbnailMode,
+  state: { hovered?: boolean; visible?: boolean } = {},
+): boolean {
+  if (mode === "always") return true;
+  if (mode === "visible") return state.visible !== false;
+  if (mode === "hover") return state.hovered === true;
+  return false;
+}
+
+export function readStoredThumbnailMode(
+  storage: Storage | undefined = getLocalStorage(),
+): ThumbnailMode {
+  if (!storage) return DEFAULT_THUMBNAIL_MODE;
+  return normalizeThumbnailMode(storage.getItem(THUMBNAIL_MODE_STORAGE_KEY));
+}
+
+export function writeStoredThumbnailMode(
+  mode: ThumbnailMode,
+  storage: Storage | undefined = getLocalStorage(),
+): void {
+  storage?.setItem(THUMBNAIL_MODE_STORAGE_KEY, mode);
+}
+
+function getLocalStorage(): Storage | undefined {
+  if (typeof localStorage === "undefined") return undefined;
+  return localStorage;
+}
diff --git a/packages/studio/src/thumbnails/thumbnailScheduler.test.ts b/packages/studio/src/thumbnails/thumbnailScheduler.test.ts
new file mode 100644
index 000000000..2a5ea8671
--- /dev/null
+++ b/packages/studio/src/thumbnails/thumbnailScheduler.test.ts
@@ -0,0 +1,162 @@
+import { describe, expect, it } from "vitest";
+import { ThumbnailScheduler, type ThumbnailJobResult } from "./thumbnailScheduler";
+
+describe("ThumbnailScheduler", () => {
+  it("dedupes jobs by key", async () => {
+    const scheduler = new ThumbnailScheduler();
+    let runs = 0;
+    const task = async () => {
+      runs += 1;
+      return "thumbnail";
+    };
+
+    const first = scheduler.schedule({ key: "same", priority: "visible", task });
+    const second = scheduler.schedule({ key: "same", priority: "visible", task });
+
+    expect(await Promise.all([first, second])).toEqual(["thumbnail", "thumbnail"]);
+    expect(runs).toBe(1);
+  });
+
+  it("runs higher priority queued work first", async () => {
+    const scheduler = new ThumbnailScheduler({ maxActiveJobs: 1 });
+    const blocker = deferred<ThumbnailJobResult>();
+    const order: string[] = [];
+
+    const first = scheduler.schedule({
+      key: "first",
+      priority: "visible",
+      task: async () => {
+        order.push("first");
+        return blocker.promise;
+      },
+    });
+    const idle = scheduler.schedule({
+      key: "idle",
+      priority: "idle",
+      task: async () => {
+        order.push("idle");
+        return "idle";
+      },
+    });
+    const visible = scheduler.schedule({
+      key: "visible",
+      priority: "visible",
+      task: async () => {
+        order.push("visible");
+        return "visible";
+      },
+    });
+
+    expect(order).toEqual(["first"]);
+    blocker.resolve("first");
+
+    expect(await first).toBe("first");
+    expect(await visible).toBe("visible");
+    expect(await idle).toBe("idle");
+    expect(order).toEqual(["first", "visible", "idle"]);
+  });
+
+  it("aborts queued work when all consumers cancel", async () => {
+    const scheduler = new ThumbnailScheduler({ maxActiveJobs: 1 });
+    const blocker = deferred<ThumbnailJobResult>();
+    let queuedRan = false;
+
+    const first = scheduler.schedule({
+      key: "first",
+      priority: "visible",
+      task: async () => blocker.promise,
+    });
+    const controller = new AbortController();
+    const queued = scheduler.schedule({
+      key: "queued",
+      priority: "visible",
+      signal: controller.signal,
+      task: async () => {
+        queuedRan = true;
+        return "queued";
+      },
+    });
+
+    controller.abort();
+    await expect(queued).rejects.toThrow(/aborted/i);
+    blocker.resolve("first");
+    await expect(first).resolves.toBe("first");
+
+    expect(queuedRan).toBe(false);
+    expect(scheduler.stats()).toMatchObject({ queued: 0, active: 0, trackedJobs: 0 });
+  });
+
+  it("does not cancel shared work when only one duplicate consumer aborts", async () => {
+    const scheduler = new ThumbnailScheduler({ maxActiveJobs: 1 });
+    const blocker = deferred<ThumbnailJobResult>();
+    const controller = new AbortController();
+
+    const first = scheduler.schedule({
+      key: "shared",
+      priority: "visible",
+      signal: controller.signal,
+      task: async () => blocker.promise,
+    });
+    const second = scheduler.schedule({
+      key: "shared",
+      priority: "visible",
+      task: async () => "should dedupe",
+    });
+
+    controller.abort();
+    await expect(first).rejects.toThrow(/aborted/i);
+    blocker.resolve("shared");
+    await expect(second).resolves.toBe("shared");
+  });
+
+  it("respects headless concurrency while keeping default work moving", async () => {
+    const scheduler = new ThumbnailScheduler({ maxActiveJobs: 2, maxActiveHeadlessJobs: 1 });
+    const firstHeadless = deferred<ThumbnailJobResult>();
+    const order: string[] = [];
+
+    const h1 = scheduler.schedule({
+      key: "h1",
+      priority: "visible",
+      lane: "headless",
+      task: async () => {
+        order.push("h1");
+        return firstHeadless.promise;
+      },
+    });
+    const h2 = scheduler.schedule({
+      key: "h2",
+      priority: "visible",
+      lane: "headless",
+      task: async () => {
+        order.push("h2");
+        return "h2";
+      },
+    });
+    const d1 = scheduler.schedule({
+      key: "d1",
+      priority: "visible",
+      task: async () => {
+        order.push("d1");
+        return "d1";
+      },
+    });
+
+    expect(order).toEqual(["h1", "d1"]);
+    await expect(d1).resolves.toBe("d1");
+    firstHeadless.resolve("h1");
+    await expect(h1).resolves.toBe("h1");
+    await expect(h2).resolves.toBe("h2");
+    expect(order).toEqual(["h1", "d1", "h2"]);
+  });
+});
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+
+  return { promise, resolve, reject };
+}
diff --git a/packages/studio/src/thumbnails/thumbnailScheduler.ts b/packages/studio/src/thumbnails/thumbnailScheduler.ts
new file mode 100644
index 000000000..0dd60bcb6
--- /dev/null
+++ b/packages/studio/src/thumbnails/thumbnailScheduler.ts
@@ -0,0 +1,231 @@
+export type ThumbnailPriority = "visible" | "hover" | "idle";
+export type ThumbnailLane = "default" | "headless";
+export type ThumbnailJobResult = Blob | ImageBitmap | string | null;
+
+export interface ThumbnailSchedulerOptions {
+  maxActiveJobs?: number;
+  maxActiveHeadlessJobs?: number;
+}
+
+export interface ScheduleThumbnailOptions {
+  key: string;
+  priority: ThumbnailPriority;
+  lane?: ThumbnailLane;
+  signal?: AbortSignal;
+  task: (signal: AbortSignal) => Promise<ThumbnailJobResult>;
+}
+
+export interface ThumbnailSchedulerStats {
+  queued: number;
+  active: number;
+  activeHeadless: number;
+  trackedJobs: number;
+}
+
+interface ScheduledJob {
+  key: string;
+  priority: ThumbnailPriority;
+  lane: ThumbnailLane;
+  task: (signal: AbortSignal) => Promise<ThumbnailJobResult>;
+  controller: AbortController;
+  promise: Promise<ThumbnailJobResult>;
+  resolve: (value: ThumbnailJobResult) => void;
+  reject: (reason: unknown) => void;
+  consumers: Set<symbol>;
+  state: "queued" | "running" | "settled";
+}
+
+const PRIORITIES: ThumbnailPriority[] = ["visible", "hover", "idle"];
+
+export class ThumbnailScheduler {
+  readonly maxActiveJobs: number;
+  readonly maxActiveHeadlessJobs: number;
+
+  private queues = new Map<ThumbnailPriority, ScheduledJob[]>(
+    PRIORITIES.map((priority) => [priority, []]),
+  );
+  private jobsByKey = new Map<string, ScheduledJob>();
+  private activeJobs = new Set<ScheduledJob>();
+  private activeHeadlessJobs = 0;
+
+  constructor(options: ThumbnailSchedulerOptions = {}) {
+    this.maxActiveJobs = Math.max(1, options.maxActiveJobs ?? 2);
+    this.maxActiveHeadlessJobs = Math.max(0, options.maxActiveHeadlessJobs ?? 1);
+  }
+
+  schedule(options: ScheduleThumbnailOptions): Promise<ThumbnailJobResult> {
+    const existing = this.jobsByKey.get(options.key);
+    if (existing) return this.attachConsumer(existing, options.signal);
+
+    let resolveJob: (value: ThumbnailJobResult) => void = () => {};
+    let rejectJob: (reason: unknown) => void = () => {};
+    const promise = new Promise<ThumbnailJobResult>((resolve, reject) => {
+      resolveJob = resolve;
+      rejectJob = reject;
+    });
+    const job: ScheduledJob = {
+      key: options.key,
+      priority: options.priority,
+      lane: options.lane ?? "default",
+      task: options.task,
+      controller: new AbortController(),
+      promise,
+      resolve: resolveJob,
+      reject: rejectJob,
+      consumers: new Set(),
+      state: "queued",
+    };
+
+    this.jobsByKey.set(job.key, job);
+    this.getQueue(job.priority).push(job);
+    const consumerPromise = this.attachConsumer(job, options.signal);
+    this.pump();
+    return consumerPromise;
+  }
+
+  stats(): ThumbnailSchedulerStats {
+    return {
+      queued: Array.from(this.queues.values()).reduce((total, queue) => total + queue.length, 0),
+      active: this.activeJobs.size,
+      activeHeadless: this.activeHeadlessJobs,
+      trackedJobs: this.jobsByKey.size,
+    };
+  }
+
+  private attachConsumer(
+    job: ScheduledJob,
+    signal: AbortSignal | undefined,
+  ): Promise<ThumbnailJobResult> {
+    if (signal?.aborted) return Promise.reject(createAbortError(signal.reason));
+
+    const token = Symbol(job.key);
+    job.consumers.add(token);
+
+    let abortReject: (reason: unknown) => void = () => {};
+    const abortPromise = new Promise<never>((_resolve, reject) => {
+      abortReject = reject;
+    });
+    const onAbort = () => {
+      this.detachConsumer(job, token);
+      abortReject(createAbortError(signal?.reason));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+
+    return Promise.race([job.promise, abortPromise]).finally(() => {
+      signal?.removeEventListener("abort", onAbort);
+      job.consumers.delete(token);
+    });
+  }
+
+  private detachConsumer(job: ScheduledJob, token: symbol): void {
+    job.consumers.delete(token);
+    if (job.state === "settled" || job.consumers.size > 0) return;
+
+    const abortError = createAbortError();
+    job.controller.abort(abortError);
+    if (job.state === "queued") {
+      this.removeQueuedJob(job);
+      this.settleJob(job, "reject", abortError);
+    }
+  }
+
+  private pump(): void {
+    while (this.activeJobs.size < this.maxActiveJobs) {
+      const next = this.takeNextRunnableJob();
+      if (!next) return;
+      this.runJob(next);
+    }
+  }
+
+  private takeNextRunnableJob(): ScheduledJob | null {
+    for (const priority of PRIORITIES) {
+      const queue = this.getQueue(priority);
+      const index = queue.findIndex((job) => this.canRun(job));
+      if (index >= 0) {
+        const [job] = queue.splice(index, 1);
+        return job ?? null;
+      }
+    }
+    return null;
+  }
+
+  private canRun(job: ScheduledJob): boolean {
+    return job.lane !== "headless" || this.activeHeadlessJobs < this.maxActiveHeadlessJobs;
+  }
+
+  private async runJob(job: ScheduledJob): Promise<void> {
+    if (job.controller.signal.aborted) {
+      this.settleJob(job, "reject", createAbortError(job.controller.signal.reason));
+      this.pump();
+      return;
+    }
+
+    job.state = "running";
+    this.activeJobs.add(job);
+    if (job.lane === "headless") this.activeHeadlessJobs += 1;
+
+    try {
+      this.settleJob(job, "resolve", await job.task(job.controller.signal));
+    } catch (error) {
+      this.settleJob(job, "reject", error);
+    } finally {
+      this.activeJobs.delete(job);
+      if (job.lane === "headless") {
+        this.activeHeadlessJobs = Math.max(0, this.activeHeadlessJobs - 1);
+      }
+      this.pump();
+    }
+  }
+
+  private settleJob(
+    job: ScheduledJob,
+    mode: "resolve" | "reject",
+    value: ThumbnailJobResult | unknown,
+  ): void {
+    if (job.state === "settled") return;
+
+    job.state = "settled";
+    this.jobsByKey.delete(job.key);
+    this.removeQueuedJob(job);
+
+    if (mode === "resolve") {
+      job.resolve(isThumbnailJobResult(value) ? value : null);
+    } else {
+      job.reject(value);
+    }
+  }
+
+  private removeQueuedJob(job: ScheduledJob): void {
+    for (const queue of this.queues.values()) {
+      const index = queue.indexOf(job);
+      if (index >= 0) {
+        queue.splice(index, 1);
+        return;
+      }
+    }
+  }
+
+  private getQueue(priority: ThumbnailPriority): ScheduledJob[] {
+    const queue = this.queues.get(priority);
+    if (queue) return queue;
+    throw new Error(`Unknown thumbnail priority: ${priority}`);
+  }
+}
+
+function isThumbnailJobResult(value: unknown): value is ThumbnailJobResult {
+  return (
+    value == null || typeof value === "string" || value instanceof Blob || isImageBitmap(value)
+  );
+}
+
+function isImageBitmap(value: unknown): value is ImageBitmap {
+  return typeof ImageBitmap !== "undefined" && value instanceof ImageBitmap;
+}
+
+function createAbortError(reason?: unknown): Error {
+  if (reason instanceof Error) return reason;
+  if (typeof DOMException === "function") {
+    return new DOMException("Thumbnail request aborted.", "AbortError");
+  }
+  return new Error("Thumbnail request aborted.");
+}
diff --git a/packages/studio/src/thumbnails/videoThumbnail.ts b/packages/studio/src/thumbnails/videoThumbnail.ts
new file mode 100644
index 000000000..4b219c80d
--- /dev/null
+++ b/packages/studio/src/thumbnails/videoThumbnail.ts
@@ -0,0 +1,40 @@
+import type {
+  MediabunnyVideoThumbnailRequest,
+  MediabunnyVideoThumbnailResult,
+} from "./mediabunnyVideoThumbnail";
+
+export type VideoThumbnailRequest = MediabunnyVideoThumbnailRequest;
+
+export async function createVideoThumbnail(request: VideoThumbnailRequest): Promise<Blob | null> {
+  if (canTryMediabunny()) {
+    const mediabunnyResult = await tryCreateMediabunnyThumbnail(request);
+    if (mediabunnyResult) return mediabunnyResult.blob;
+  }
+
+  const { createBrowserVideoThumbnail } = await import("./browserVideoThumbnail");
+  return createBrowserVideoThumbnail(request);
+}
+
+function canTryMediabunny(): boolean {
+  return typeof Blob !== "undefined" && typeof VideoDecoder !== "undefined";
+}
+
+async function tryCreateMediabunnyThumbnail(
+  request: VideoThumbnailRequest,
+): Promise<MediabunnyVideoThumbnailResult | null> {
+  try {
+    const { createMediabunnyVideoThumbnail } = await import("./mediabunnyVideoThumbnail");
+    return createMediabunnyVideoThumbnail(request);
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+    return null;
+  }
+}
+
+function isAbortError(error: unknown): boolean {
+  return (
+    typeof DOMException !== "undefined" &&
+    error instanceof DOMException &&
+    error.name === "AbortError"
+  );
+}
diff --git a/packages/studio/src/utils/clipboard.test.ts b/packages/studio/src/utils/clipboard.test.ts
new file mode 100644
index 000000000..6a319bbfb
--- /dev/null
+++ b/packages/studio/src/utils/clipboard.test.ts
@@ -0,0 +1,88 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Window } from "happy-dom";
+import { copyTextToClipboard } from "./clipboard";
+
+function installDocument(execCommand: (command: string) => boolean): void {
+  const window = new Window();
+  Object.defineProperty(window.document, "execCommand", {
+    configurable: true,
+    value: execCommand,
+  });
+  vi.stubGlobal("document", window.document);
+}
+
+function installNavigator(
+  writeText: (text: string) => Promise<void>,
+  userAgent = "Mozilla/5.0 Chrome/120.0.0.0 Safari/537.36",
+): void {
+  vi.stubGlobal("navigator", {
+    clipboard: { writeText },
+    userAgent,
+  });
+}
+
+describe("copyTextToClipboard", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("uses the synchronous selection copy path first in Safari", async () => {
+    const execCommand = vi.fn((command: string) => command === "copy");
+    const writeText = vi.fn((_text: string) => Promise.resolve());
+
+    installDocument(execCommand);
+    installNavigator(
+      writeText,
+      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Safari/605.1.15",
+    );
+
+    await expect(copyTextToClipboard("copy me")).resolves.toBe(true);
+
+    expect(execCommand).toHaveBeenCalledWith("copy");
+    expect(writeText).not.toHaveBeenCalled();
+    expect(document.querySelector("textarea")).toBeNull();
+  });
+
+  it("uses navigator.clipboard first outside Safari", async () => {
+    const execCommand = vi.fn((command: string) => command === "copy");
+    const writeText = vi.fn((_text: string) => Promise.resolve());
+
+    installDocument(execCommand);
+    installNavigator(writeText);
+
+    await expect(copyTextToClipboard("copy me")).resolves.toBe(true);
+
+    expect(writeText).toHaveBeenCalledWith("copy me");
+    expect(execCommand).not.toHaveBeenCalled();
+  });
+
+  it("falls back to selection copy outside Safari when navigator.clipboard fails", async () => {
+    const execCommand = vi.fn((command: string) => command === "copy");
+    const writeText = vi.fn((_text: string) => Promise.reject(new Error("blocked")));
+
+    installDocument(execCommand);
+    installNavigator(writeText);
+
+    await expect(copyTextToClipboard("copy me")).resolves.toBe(true);
+
+    expect(writeText).toHaveBeenCalledWith("copy me");
+    expect(execCommand).toHaveBeenCalledWith("copy");
+  });
+
+  it("reports failure when both copy paths fail", async () => {
+    const execCommand = vi.fn(() => false);
+    const writeText = vi.fn((_text: string) => Promise.reject(new Error("blocked")));
+
+    installDocument(execCommand);
+    installNavigator(
+      writeText,
+      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Safari/605.1.15",
+    );
+
+    await expect(copyTextToClipboard("copy me")).resolves.toBe(false);
+
+    expect(execCommand).toHaveBeenCalledWith("copy");
+    expect(writeText).toHaveBeenCalledWith("copy me");
+    expect(document.querySelector("textarea")).toBeNull();
+  });
+});
diff --git a/packages/studio/src/utils/clipboard.ts b/packages/studio/src/utils/clipboard.ts
new file mode 100644
index 000000000..449603fd0
--- /dev/null
+++ b/packages/studio/src/utils/clipboard.ts
@@ -0,0 +1,57 @@
+function copyWithSelection(text: string): boolean {
+  if (typeof document === "undefined" || !document.body || !document.execCommand) {
+    return false;
+  }
+
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.setAttribute("readonly", "true");
+  textarea.style.position = "fixed";
+  textarea.style.top = "0";
+  textarea.style.left = "0";
+  textarea.style.width = "1px";
+  textarea.style.height = "1px";
+  textarea.style.padding = "0";
+  textarea.style.border = "0";
+  textarea.style.opacity = "0";
+  textarea.style.pointerEvents = "none";
+
+  document.body.appendChild(textarea);
+  textarea.focus({ preventScroll: true });
+  textarea.select();
+  textarea.setSelectionRange(0, text.length);
+
+  try {
+    return document.execCommand("copy");
+  } catch {
+    return false;
+  } finally {
+    document.body.removeChild(textarea);
+  }
+}
+
+function shouldCopyWithSelectionFirst(): boolean {
+  if (typeof navigator === "undefined") return false;
+
+  const userAgent = navigator.userAgent;
+  return /Safari/i.test(userAgent) && !/Chrome|Chromium|CriOS|FxiOS|Edg|OPR/i.test(userAgent);
+}
+
+export async function copyTextToClipboard(text: string): Promise<boolean> {
+  const useSelectionFirst = shouldCopyWithSelectionFirst();
+  if (useSelectionFirst && copyWithSelection(text)) {
+    return true;
+  }
+
+  const clipboard = typeof navigator !== "undefined" ? navigator.clipboard : undefined;
+  if (clipboard?.writeText) {
+    try {
+      await clipboard.writeText(text);
+      return true;
+    } catch {
+      // Fall back below when the browser still allows synchronous copy.
+    }
+  }
+
+  return !useSelectionFirst && copyWithSelection(text);
+}
diff --git a/packages/studio/src/utils/compositionPaths.test.ts b/packages/studio/src/utils/compositionPaths.test.ts
new file mode 100644
index 000000000..6deddbf93
--- /dev/null
+++ b/packages/studio/src/utils/compositionPaths.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import {
+  getCompositionLabel,
+  getCompositionPreviewUrl,
+  isSourceCompositionPath,
+  parseCompositionSourceMap,
+} from "./compositionPaths";
+
+describe("composition paths", () => {
+  it("recognizes source composition paths", () => {
+    expect(isSourceCompositionPath("index.html")).toBe(true);
+    expect(isSourceCompositionPath("compositions/intro.html")).toBe(true);
+    expect(isSourceCompositionPath("assets/poster.png")).toBe(false);
+  });
+
+  it("builds stable preview URLs with encoded path segments", () => {
+    expect(getCompositionPreviewUrl("demo project", "index.html")).toBe(
+      "/api/projects/demo%20project/preview",
+    );
+    expect(getCompositionPreviewUrl("demo", "compositions/intro card.html")).toBe(
+      "/api/projects/demo/preview/comp/compositions/intro%20card.html",
+    );
+  });
+
+  it("labels composition paths for breadcrumbs", () => {
+    expect(getCompositionLabel("index.html")).toBe("Master");
+    expect(getCompositionLabel("compositions/manual-editing.html")).toBe("manual-editing");
+  });
+
+  it("parses composition id to source mappings from source HTML", () => {
+    const map = parseCompositionSourceMap(`
+      <section id="hero-host" data-composition-id="hero" data-composition-src="compositions/hero.html"></section>
+      <section data-composition-file='compositions/cards.html' data-composition-id='cards'></section>
+    `);
+
+    expect(map.get("hero")).toBe("compositions/hero.html");
+    expect(map.get("hero-host")).toBe("compositions/hero.html");
+    expect(map.get("cards")).toBe("compositions/cards.html");
+  });
+});
diff --git a/packages/studio/src/utils/compositionPaths.ts b/packages/studio/src/utils/compositionPaths.ts
new file mode 100644
index 000000000..00e708ff2
--- /dev/null
+++ b/packages/studio/src/utils/compositionPaths.ts
@@ -0,0 +1,57 @@
+export function isMasterCompositionPath(path: string | null | undefined): boolean {
+  return path == null || path === "index.html";
+}
+
+export function isSourceCompositionPath(path: string | null | undefined): path is string {
+  return path === "index.html" || Boolean(path?.startsWith("compositions/"));
+}
+
+export function getCompositionLabel(path: string): string {
+  if (path === "index.html") return "Master";
+  return (
+    path
+      .split("/")
+      .pop()
+      ?.replace(/\.html$/, "") || path
+  );
+}
+
+export function getCompositionPreviewUrl(projectId: string, path: string | null | undefined) {
+  const base = `/api/projects/${encodeURIComponent(projectId)}/preview`;
+  if (isMasterCompositionPath(path)) return base;
+  return `${base}/comp/${encodeRoutePath(path ?? "")}`;
+}
+
+export function parseCompositionSourceMap(html: string): Map<string, string> {
+  const result = new Map<string, string>();
+  const tagRe = /<[^>]+>/g;
+  let tagMatch: RegExpExecArray | null;
+  while ((tagMatch = tagRe.exec(html)) !== null) {
+    const attrs = parseHtmlAttributes(tagMatch[0] ?? "");
+    const id = attrs.get("data-composition-id");
+    const hostId = attrs.get("id");
+    const src = attrs.get("data-composition-src") ?? attrs.get("data-composition-file");
+    if (id && src) result.set(id, src);
+    if (hostId && src) result.set(hostId, src);
+  }
+  return result;
+}
+
+function encodeRoutePath(path: string): string {
+  return path
+    .split("/")
+    .map((part) => encodeURIComponent(part))
+    .join("/");
+}
+
+function parseHtmlAttributes(tag: string): Map<string, string> {
+  const attrs = new Map<string, string>();
+  const attrRe = /\s([^\s"'=<>`]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+  let match: RegExpExecArray | null;
+  while ((match = attrRe.exec(tag)) !== null) {
+    const name = match[1]?.toLowerCase();
+    if (!name) continue;
+    attrs.set(name, match[2] ?? match[3] ?? match[4] ?? "");
+  }
+  return attrs;
+}
diff --git a/packages/studio/src/utils/editHistory.test.ts b/packages/studio/src/utils/editHistory.test.ts
new file mode 100644
index 000000000..06be8a390
--- /dev/null
+++ b/packages/studio/src/utils/editHistory.test.ts
@@ -0,0 +1,280 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildEditHistoryEntry,
+  canApplyEditHistoryEntry,
+  createEmptyEditHistory,
+  hashEditHistoryContent,
+  pushEditHistoryEntry,
+  redoEditHistory,
+  undoEditHistory,
+} from "./editHistory";
+
+describe("edit history", () => {
+  it("pushes changed file snapshots onto undo and clears redo", () => {
+    const state = createEmptyEditHistory();
+    const entry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move layer",
+      files: {
+        "index.html": {
+          before: '<div style="left: 0px"></div>',
+          after: '<div style="left: 20px"></div>',
+        },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+
+    const withUndo = pushEditHistoryEntry(state, entry);
+    const redoEntry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Redoable edit",
+      files: {
+        "index.html": {
+          before: '<div style="left: 20px"></div>',
+          after: '<div style="left: 40px"></div>',
+        },
+      },
+      now: 200,
+      id: "redo-entry",
+    });
+
+    const next = pushEditHistoryEntry(
+      {
+        ...withUndo,
+        redo: [redoEntry],
+      },
+      {
+        ...entry,
+        id: "entry-2",
+        label: "Resize layer",
+        createdAt: 300,
+      },
+    );
+
+    expect(withUndo.undo).toHaveLength(1);
+    expect(withUndo.redo).toHaveLength(0);
+    expect(next.undo.map((item) => item.label)).toEqual(["Move layer", "Resize layer"]);
+    expect(next.redo).toHaveLength(0);
+  });
+
+  it("undo returns before contents and moves entry to redo", () => {
+    const entry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move layer",
+      files: {
+        "index.html": { before: "before", after: "after" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+    const state = pushEditHistoryEntry(createEmptyEditHistory(), entry);
+
+    const result = undoEditHistory(state, { "index.html": hashEditHistoryContent("after") }, 200);
+
+    expect(result.ok).toBe(true);
+    expect(result.filesToWrite).toEqual({ "index.html": "before" });
+    expect(result.state.undo).toHaveLength(0);
+    expect(result.state.redo.map((item) => item.id)).toEqual(["entry-1"]);
+  });
+
+  it("redo returns after contents and moves entry to undo", () => {
+    const entry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move layer",
+      files: {
+        "index.html": { before: "before", after: "after" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+    const undone = undoEditHistory(
+      pushEditHistoryEntry(createEmptyEditHistory(), entry),
+      { "index.html": hashEditHistoryContent("after") },
+      200,
+    ).state;
+
+    const result = redoEditHistory(undone, { "index.html": hashEditHistoryContent("before") }, 300);
+
+    expect(result.ok).toBe(true);
+    expect(result.filesToWrite).toEqual({ "index.html": "after" });
+    expect(result.state.undo.map((item) => item.id)).toEqual(["entry-1"]);
+    expect(result.state.redo).toHaveLength(0);
+  });
+
+  it("blocks undo when current content hash does not match the recorded after hash", () => {
+    const entry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move layer",
+      files: {
+        "index.html": { before: "before", after: "after" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+    const state = pushEditHistoryEntry(createEmptyEditHistory(), entry);
+
+    const result = undoEditHistory(
+      state,
+      { "index.html": hashEditHistoryContent("external") },
+      200,
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.reason).toBe("content-mismatch");
+    expect(result.state).toBe(state);
+    expect(result.filesToWrite).toEqual({});
+  });
+
+  it("can validate all files in a multi-file entry before applying", () => {
+    const entry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Update files",
+      files: {
+        "index.html": { before: "a", after: "b" },
+        "compositions/title.html": { before: "c", after: "d" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+
+    expect(
+      canApplyEditHistoryEntry(entry, "undo", {
+        "index.html": hashEditHistoryContent("b"),
+        "compositions/title.html": hashEditHistoryContent("d"),
+      }),
+    ).toEqual({ ok: true });
+    expect(
+      canApplyEditHistoryEntry(entry, "undo", {
+        "index.html": hashEditHistoryContent("b"),
+        "compositions/title.html": hashEditHistoryContent("external"),
+      }),
+    ).toEqual({ ok: false, reason: "content-mismatch", path: "compositions/title.html" });
+  });
+
+  it("prunes oldest undo entries when the limit is exceeded", () => {
+    let state = createEmptyEditHistory({ maxEntries: 2 });
+    for (let index = 1; index <= 3; index += 1) {
+      state = pushEditHistoryEntry(
+        state,
+        buildEditHistoryEntry({
+          projectId: "project-1",
+          label: `Edit ${index}`,
+          files: {
+            "index.html": { before: `${index - 1}`, after: `${index}` },
+          },
+          now: index,
+          id: `entry-${index}`,
+        }),
+        { maxEntries: 2 },
+      );
+    }
+
+    expect(state.undo.map((entry) => entry.id)).toEqual(["entry-2", "entry-3"]);
+  });
+
+  it("coalesces source editor edits for the same file inside the coalesce window", () => {
+    const first = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Edit source",
+      kind: "source",
+      coalesceKey: "source:index.html",
+      files: {
+        "index.html": { before: "a", after: "b" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+    const second = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Edit source",
+      kind: "source",
+      coalesceKey: "source:index.html",
+      files: {
+        "index.html": { before: "b", after: "c" },
+      },
+      now: 300,
+      id: "entry-2",
+    });
+
+    const state = pushEditHistoryEntry(
+      pushEditHistoryEntry(createEmptyEditHistory(), first),
+      second,
+      { coalesceMs: 1000 },
+    );
+
+    expect(state.undo).toHaveLength(1);
+    expect(state.undo[0].id).toBe("entry-2");
+    expect(state.undo[0].files["index.html"].before).toBe("a");
+    expect(state.undo[0].files["index.html"].after).toBe("c");
+  });
+
+  it("coalesces motion edits for the same layer inside the coalesce window", () => {
+    const first = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Edit layer motion",
+      kind: "motion",
+      coalesceKey: "motion:index.html:#headline",
+      files: {
+        "index.html": { before: "before", after: "motion-a" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+    const second = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Edit layer motion",
+      kind: "motion",
+      coalesceKey: "motion:index.html:#headline",
+      files: {
+        "index.html": { before: "motion-a", after: "motion-b" },
+      },
+      now: 300,
+      id: "entry-2",
+    });
+
+    const state = pushEditHistoryEntry(
+      pushEditHistoryEntry(createEmptyEditHistory(), first),
+      second,
+      { coalesceMs: 1000 },
+    );
+
+    expect(state.undo).toHaveLength(1);
+    expect(state.undo[0].kind).toBe("motion");
+    expect(state.undo[0].files["index.html"].before).toBe("before");
+    expect(state.undo[0].files["index.html"].after).toBe("motion-b");
+  });
+
+  it("does not coalesce source editor edits outside the coalesce window", () => {
+    const first = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Edit source",
+      kind: "source",
+      coalesceKey: "source:index.html",
+      files: {
+        "index.html": { before: "a", after: "b" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+    const second = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Edit source",
+      kind: "source",
+      coalesceKey: "source:index.html",
+      files: {
+        "index.html": { before: "b", after: "c" },
+      },
+      now: 5000,
+      id: "entry-2",
+    });
+
+    const state = pushEditHistoryEntry(
+      pushEditHistoryEntry(createEmptyEditHistory(), first),
+      second,
+      { coalesceMs: 1000 },
+    );
+
+    expect(state.undo.map((entry) => entry.id)).toEqual(["entry-1", "entry-2"]);
+  });
+});
diff --git a/packages/studio/src/utils/editHistory.ts b/packages/studio/src/utils/editHistory.ts
new file mode 100644
index 000000000..b899f8da7
--- /dev/null
+++ b/packages/studio/src/utils/editHistory.ts
@@ -0,0 +1 @@
+export * from "@hyperframes/core/studio-history";
diff --git a/packages/studio/src/utils/editHistoryStorage.test.ts b/packages/studio/src/utils/editHistoryStorage.test.ts
new file mode 100644
index 000000000..be5e3a6f9
--- /dev/null
+++ b/packages/studio/src/utils/editHistoryStorage.test.ts
@@ -0,0 +1,37 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { buildEditHistoryEntry, createEmptyEditHistory, pushEditHistoryEntry } from "./editHistory";
+import {
+  createMemoryEditHistoryStorage,
+  loadEditHistoryState,
+  saveEditHistoryState,
+} from "./editHistoryStorage";
+
+describe("edit history storage", () => {
+  let storage: ReturnType<typeof createMemoryEditHistoryStorage>;
+
+  beforeEach(() => {
+    storage = createMemoryEditHistoryStorage();
+  });
+
+  it("returns empty history for projects without persisted state", async () => {
+    const state = await loadEditHistoryState(storage, "project-1");
+
+    expect(state).toEqual(createEmptyEditHistory());
+  });
+
+  it("saves and loads history per project", async () => {
+    const entry = buildEditHistoryEntry({
+      id: "entry-1",
+      projectId: "project-1",
+      label: "Move layer",
+      files: { "index.html": { before: "a", after: "b" } },
+      now: 100,
+    });
+    const state = pushEditHistoryEntry(createEmptyEditHistory(), entry);
+
+    await saveEditHistoryState(storage, "project-1", state);
+
+    expect(await loadEditHistoryState(storage, "project-1")).toEqual(state);
+    expect(await loadEditHistoryState(storage, "project-2")).toEqual(createEmptyEditHistory());
+  });
+});
diff --git a/packages/studio/src/utils/editHistoryStorage.ts b/packages/studio/src/utils/editHistoryStorage.ts
new file mode 100644
index 000000000..1266c9a8d
--- /dev/null
+++ b/packages/studio/src/utils/editHistoryStorage.ts
@@ -0,0 +1,99 @@
+import { createEmptyEditHistory, type EditHistoryState } from "./editHistory";
+
+export interface EditHistoryStorageAdapter {
+  get(projectId: string): Promise<EditHistoryState | null>;
+  set(projectId: string, state: EditHistoryState): Promise<void>;
+  delete(projectId: string): Promise<void>;
+}
+
+const DB_NAME = "hyperframes-studio-edit-history";
+const DB_VERSION = 1;
+const STORE_NAME = "project-history";
+
+export function createMemoryEditHistoryStorage(): EditHistoryStorageAdapter {
+  const states = new Map<string, EditHistoryState>();
+  return {
+    async get(projectId) {
+      return states.get(projectId) ?? null;
+    },
+    async set(projectId, state) {
+      states.set(projectId, structuredClone(state));
+    },
+    async delete(projectId) {
+      states.delete(projectId);
+    },
+  };
+}
+
+function openEditHistoryDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    if (!globalThis.indexedDB) {
+      reject(new Error("IndexedDB is not available"));
+      return;
+    }
+
+    const request = globalThis.indexedDB.open(DB_NAME, DB_VERSION);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        db.createObjectStore(STORE_NAME);
+      }
+    };
+    request.onerror = () => reject(request.error ?? new Error("Failed to open edit history db"));
+    request.onsuccess = () => resolve(request.result);
+  });
+}
+
+function withStore<T>(
+  mode: IDBTransactionMode,
+  callback: (store: IDBObjectStore) => IDBRequest<T>,
+): Promise<T> {
+  return openEditHistoryDb().then(
+    (db) =>
+      new Promise<T>((resolve, reject) => {
+        const tx = db.transaction(STORE_NAME, mode);
+        const request = callback(tx.objectStore(STORE_NAME));
+        request.onerror = () => reject(request.error ?? new Error("IndexedDB request failed"));
+        request.onsuccess = () => resolve(request.result);
+        tx.oncomplete = () => db.close();
+        tx.onerror = () => {
+          db.close();
+          reject(tx.error ?? new Error("IndexedDB transaction failed"));
+        };
+      }),
+  );
+}
+
+export function createIndexedDbEditHistoryStorage(): EditHistoryStorageAdapter {
+  return {
+    async get(projectId) {
+      return (
+        (await withStore<EditHistoryState | undefined>("readonly", (store) =>
+          store.get(projectId),
+        )) ?? null
+      );
+    },
+    async set(projectId, state) {
+      await withStore<IDBValidKey>("readwrite", (store) => store.put(state, projectId));
+    },
+    async delete(projectId) {
+      await withStore<undefined>("readwrite", (store) => store.delete(projectId));
+    },
+  };
+}
+
+export async function loadEditHistoryState(
+  storage: EditHistoryStorageAdapter,
+  projectId: string,
+): Promise<EditHistoryState> {
+  const state = await storage.get(projectId);
+  return state ?? createEmptyEditHistory();
+}
+
+export async function saveEditHistoryState(
+  storage: EditHistoryStorageAdapter,
+  projectId: string,
+  state: EditHistoryState,
+): Promise<void> {
+  await storage.set(projectId, state);
+}
diff --git a/packages/studio/src/utils/mediaTypes.ts b/packages/studio/src/utils/mediaTypes.ts
index ebc41540d..844fe88ed 100644
--- a/packages/studio/src/utils/mediaTypes.ts
+++ b/packages/studio/src/utils/mediaTypes.ts
@@ -1,7 +1,7 @@
 export const IMAGE_EXT = /\.(jpg|jpeg|png|gif|webp|svg|ico)$/i;
 export const VIDEO_EXT = /\.(mp4|webm|mov)$/i;
 export const AUDIO_EXT = /\.(mp3|wav|ogg|m4a|aac)$/i;
-export const FONT_EXT = /\.(woff|woff2|ttf|otf|eot)$/i;
+export const FONT_EXT = /\.(woff|woff2|ttf|ttc|otf|eot)$/i;
 export const MEDIA_EXT = /\.(mp4|webm|mov|mp3|wav|ogg|m4a|aac|jpg|jpeg|png|gif|webp|svg|ico)$/i;
 
 export function isMediaFile(path: string): boolean {
diff --git a/packages/studio/src/utils/sourcePatcher.test.ts b/packages/studio/src/utils/sourcePatcher.test.ts
index 9f5c25f57..b6ef3e953 100644
--- a/packages/studio/src/utils/sourcePatcher.test.ts
+++ b/packages/studio/src/utils/sourcePatcher.test.ts
@@ -1,5 +1,12 @@
 import { describe, expect, it } from "vitest";
-import { applyPatchByTarget, readAttributeByTarget, type PatchOperation } from "./sourcePatcher";
+import {
+  applyPatch,
+  applyPatchByTarget,
+  findSourceLocationByTarget,
+  readAttributeByTarget,
+  readTagSnippetByTarget,
+  type PatchOperation,
+} from "./sourcePatcher";
 
 describe("applyPatchByTarget", () => {
   it("updates a composition host by data-composition-id selector", () => {
@@ -29,6 +36,64 @@ describe("applyPatchByTarget", () => {
     );
   });
 
+  it("patches inline move styles by target", () => {
+    const html = `<div id="card" style="position: absolute; left: 108px; top: 112px"></div>`;
+
+    const withLeft = applyPatchByTarget(
+      html,
+      { id: "card" },
+      { type: "inline-style", property: "left", value: "160px" },
+    );
+    const withTop = applyPatchByTarget(
+      withLeft,
+      { id: "card" },
+      { type: "inline-style", property: "top", value: "140px" },
+    );
+
+    expect(withTop).toContain('style="position: absolute; left: 160px; top: 140px"');
+  });
+
+  it("patches inline resize styles by target", () => {
+    const html = `<div id="card" style="position: absolute; width: 380px; height: 196px"></div>`;
+
+    const withWidth = applyPatchByTarget(
+      html,
+      { id: "card" },
+      { type: "inline-style", property: "width", value: "420px" },
+    );
+    const withHeight = applyPatchByTarget(
+      withWidth,
+      { id: "card" },
+      { type: "inline-style", property: "height", value: "220px" },
+    );
+
+    expect(withHeight).toContain('style="position: absolute; width: 420px; height: 220px"');
+  });
+
+  it("escapes quoted CSS urls inside double-quoted style attributes", () => {
+    const html = `<div id="card" style="position: absolute; opacity: 1"></div>`;
+
+    const withBackground = applyPatchByTarget(
+      html,
+      { id: "card" },
+      {
+        type: "inline-style",
+        property: "background-image",
+        value: `url("../ChatGPT Image Apr 22, 2026.png")`,
+      },
+    );
+    const withRadius = applyPatchByTarget(
+      withBackground,
+      { id: "card" },
+      { type: "inline-style", property: "border-radius", value: "12px" },
+    );
+
+    expect(withRadius).toContain(
+      "background-image: url(&quot;../ChatGPT Image Apr 22, 2026.png&quot;)",
+    );
+    expect(withRadius).toContain("border-radius: 12px");
+  });
+
   it("updates media timing attributes by selector", () => {
     const html = `<video class="hero clip" data-start="0.2" data-duration="1.4" data-media-start="0.4"></video>`;
 
@@ -55,6 +120,22 @@ describe("applyPatchByTarget", () => {
     expect(withMediaStart).toContain('data-media-start="0.7"');
   });
 
+  it("removes attributes by target when the patch value is null", () => {
+    const html = `<div id="headline" data-hf-motion="v=1;preset=fade-up" data-start="0"></div>`;
+
+    const patched = applyPatchByTarget(
+      html,
+      { id: "headline" },
+      {
+        type: "attribute",
+        property: "hf-motion",
+        value: null,
+      },
+    );
+
+    expect(patched).toBe(`<div id="headline" data-start="0"></div>`);
+  });
+
   it("reads media timing attributes by selector", () => {
     const html = `<div class="hero clip" data-start="0.2" data-duration="1.4" data-media-start="0.4"></div>`;
 
@@ -62,6 +143,69 @@ describe("applyPatchByTarget", () => {
     expect(readAttributeByTarget(html, { selector: ".hero" }, "duration")).toBe("1.4");
   });
 
+  it("reads the matched tag snippet by target", () => {
+    const html = `<section id="hero" class="card clip" style="left: 120px; top: 180px"></section>`;
+
+    expect(readTagSnippetByTarget(html, { id: "hero" })).toBe(
+      `<section id="hero" class="card clip" style="left: 120px; top: 180px"`,
+    );
+  });
+
+  it("patches and reads single-quoted attributes and styles", () => {
+    const html =
+      "<section id='hero' class='card clip' data-start='0.2' style='left: 120px; top: 180px'></section>";
+
+    const moved = applyPatchByTarget(
+      html,
+      { id: "hero" },
+      { type: "inline-style", property: "left", value: "160px" },
+    );
+    const updated = applyPatchByTarget(
+      moved,
+      { id: "hero" },
+      { type: "attribute", property: "start", value: "0.4" },
+    );
+
+    expect(updated).toContain(`style='left: 160px; top: 180px'`);
+    expect(updated).toContain(`data-start="0.4"`);
+    expect(readAttributeByTarget(updated, { id: "hero" }, "start")).toBe("0.4");
+  });
+
+  it("replaces the full text body of a nested element by id", () => {
+    const html =
+      '<div id="panel"><strong>Headline</strong><span>Supporting copy</span></div><p>Outside</p>';
+
+    const patched = applyPatch(html, "panel", {
+      type: "text-content",
+      property: "text",
+      value: "<strong>New headline</strong><span>New supporting copy</span>",
+    });
+
+    expect(patched).toContain(
+      '<div id="panel"><strong>New headline</strong><span>New supporting copy</span></div>',
+    );
+    expect(patched).toContain("<p>Outside</p>");
+  });
+
+  it("does not stop at the first child closing tag when patching nested text", () => {
+    const html =
+      '<section id="card"><div><strong>Headline</strong></div><div>Copy</div></section><p>Outside</p>';
+
+    const patched = applyPatchByTarget(
+      html,
+      { id: "card" },
+      {
+        type: "text-content",
+        property: "text",
+        value: "<strong>New headline</strong>",
+      },
+    );
+
+    expect(patched).toBe(
+      '<section id="card"><strong>New headline</strong></section><p>Outside</p>',
+    );
+  });
+
   it("patches the correct duplicate selector occurrence", () => {
     const html = [
       `<div class="headline clip" data-start="0"></div>`,
@@ -81,4 +225,22 @@ describe("applyPatchByTarget", () => {
     expect(patched).toContain(`<div class="headline clip" data-start="0"></div>`);
     expect(patched).toContain(`<div class="headline clip" data-start="2.5"></div>`);
   });
+
+  it("finds the source line and column for a targeted element", () => {
+    const html = [
+      "<main>",
+      '  <section class="headline clip" data-start="0"></section>',
+      '  <section class="headline clip" data-start="1"></section>',
+      "</main>",
+    ].join("\n");
+
+    const location = findSourceLocationByTarget(html, {
+      selector: ".headline",
+      selectorIndex: 1,
+    });
+
+    expect(location?.line).toBe(3);
+    expect(location?.column).toBe(3);
+    expect(location?.tag).toBe('<section class="headline clip" data-start="1"');
+  });
 });
diff --git a/packages/studio/src/utils/sourcePatcher.ts b/packages/studio/src/utils/sourcePatcher.ts
index 921cb5b64..4416585ba 100644
--- a/packages/studio/src/utils/sourcePatcher.ts
+++ b/packages/studio/src/utils/sourcePatcher.ts
@@ -7,10 +7,71 @@ function escapeRegex(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+function escapeStyleAttributeValue(value: string, quote: string): string {
+  return quote === '"' ? value.replace(/"/g, "&quot;") : value.replace(/'/g, "&#39;");
+}
+
+function splitInlineStyleDeclarations(style: string): string[] {
+  const declarations: string[] = [];
+  let current = "";
+  let quote: string | null = null;
+  let entity = false;
+  let parenDepth = 0;
+
+  for (const char of style) {
+    if (entity) {
+      current += char;
+      if (char === ";") entity = false;
+      continue;
+    }
+
+    if (char === "&") {
+      entity = true;
+      current += char;
+      continue;
+    }
+
+    if (quote) {
+      current += char;
+      if (char === quote) quote = null;
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      quote = char;
+      current += char;
+      continue;
+    }
+
+    if (char === "(") {
+      parenDepth += 1;
+      current += char;
+      continue;
+    }
+
+    if (char === ")") {
+      parenDepth = Math.max(0, parenDepth - 1);
+      current += char;
+      continue;
+    }
+
+    if (char === ";" && parenDepth === 0) {
+      declarations.push(current);
+      current = "";
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (current) declarations.push(current);
+  return declarations;
+}
+
 export interface PatchOperation {
   type: "inline-style" | "attribute" | "text-content";
   property: string;
-  value: string;
+  value: string | null;
 }
 
 export interface PatchTarget {
@@ -74,7 +135,7 @@ export function resolveSourceFile(
  */
 function patchInlineStyle(html: string, elementId: string, prop: string, value: string): string {
   // Find the element tag with this id
-  const idPattern = new RegExp(`(<[^>]*\\bid="${escapeRegex(elementId)}"[^>]*)>`, "i");
+  const idPattern = new RegExp(`(<[^>]*\\bid=(["'])${escapeRegex(elementId)}\\2[^>]*)>`, "i");
   const match = idPattern.exec(html);
   if (!match) return html;
 
@@ -86,12 +147,13 @@ function patchInlineStyleInTag(html: string, tag: string, prop: string, value: s
   if (!tag) return html;
 
   // Check if there's an existing style attribute
-  const styleMatch = /\bstyle="([^"]*)"/.exec(tag);
+  const styleMatch = /\bstyle=(["'])([\s\S]*?)\1/.exec(tag);
   if (styleMatch) {
-    const existingStyle = styleMatch[1];
+    const existingStyle = styleMatch[2];
+    const quote = styleMatch[1];
     // Parse existing properties
     const props = new Map<string, string>();
-    for (const part of existingStyle.split(";")) {
+    for (const part of splitInlineStyleDeclarations(existingStyle)) {
       const colon = part.indexOf(":");
       if (colon < 0) continue;
       const key = part.slice(0, colon).trim();
@@ -102,13 +164,14 @@ function patchInlineStyleInTag(html: string, tag: string, prop: string, value: s
     props.set(prop, value);
     // Rebuild style string
     const newStyle = Array.from(props.entries())
-      .map(([k, v]) => `${k}: ${v}`)
+      .map(([k, v]) => `${k}: ${escapeStyleAttributeValue(v, quote)}`)
       .join("; ");
-    const newTag = tag.replace(/\bstyle="[^"]*"/, `style="${newStyle}"`);
+    const newTag = tag.replace(styleMatch[0], `style=${quote}${newStyle}${quote}`);
     return html.replace(tag, newTag);
   } else {
     // No existing style — add one
-    const newTag = tag.replace(/>$/, "") + ` style="${prop}: ${value}"`;
+    const newTag =
+      tag.replace(/>$/, "") + ` style="${prop}: ${escapeStyleAttributeValue(value, '"')}"`;
     return html.replace(tag, newTag);
   }
 }
@@ -131,13 +194,55 @@ interface TagMatch {
   end: number;
 }
 
+export interface SourceLocation {
+  line: number;
+  column: number;
+  offset: number;
+  tag: string;
+}
+
+function getLineColumnAtOffset(
+  source: string,
+  offset: number,
+): Pick<SourceLocation, "line" | "column"> {
+  const safeOffset = Math.max(0, Math.min(source.length, offset));
+  let line = 1;
+  let columnStart = 0;
+
+  for (let index = 0; index < safeOffset; index += 1) {
+    const char = source[index];
+    if (char === "\n") {
+      line += 1;
+      columnStart = index + 1;
+    }
+  }
+
+  return {
+    line,
+    column: safeOffset - columnStart + 1,
+  };
+}
+
+export function findSourceLocationByTarget(
+  html: string,
+  target: PatchTarget,
+): SourceLocation | null {
+  const match = findTagByTarget(html, target);
+  if (!match) return null;
+  return {
+    ...getLineColumnAtOffset(html, match.start),
+    offset: match.start,
+    tag: match.tag,
+  };
+}
+
 function replaceTagAtMatch(html: string, match: TagMatch, newTag: string): string {
   return `${html.slice(0, match.start)}${newTag}${html.slice(match.end)}`;
 }
 
 function findTagByTarget(html: string, target: PatchTarget): TagMatch | null {
   if (target.id) {
-    const idPattern = new RegExp(`(<[^>]*\\bid="${escapeRegex(target.id)}"[^>]*)>`, "i");
+    const idPattern = new RegExp(`(<[^>]*\\bid=(["'])${escapeRegex(target.id)}\\2[^>]*)>`, "i");
     const match = idPattern.exec(html);
     if (match?.index != null) {
       return {
@@ -154,7 +259,7 @@ function findTagByTarget(html: string, target: PatchTarget): TagMatch | null {
   if (compositionIdMatch) {
     const compId = compositionIdMatch[1];
     const pattern = new RegExp(
-      `(<[^>]*\\bdata-composition-id="${escapeRegex(compId)}"[^>]*)>`,
+      `(<[^>]*\\bdata-composition-id=(["'])${escapeRegex(compId)}\\2[^>]*)>`,
       "i",
     );
     const match = pattern.exec(html);
@@ -201,23 +306,34 @@ export function readAttributeByTarget(
   if (!match) return undefined;
 
   const fullAttr = attr.startsWith("data-") ? attr : `data-${attr}`;
-  const valueMatch = new RegExp(`\\b${fullAttr}="([^"]*)"`).exec(match.tag);
-  return valueMatch?.[1];
+  const valueMatch = new RegExp(`\\b${fullAttr}=(["'])([^"']*)\\1`).exec(match.tag);
+  return valueMatch?.[2];
+}
+
+export function readTagSnippetByTarget(html: string, target: PatchTarget): string | undefined {
+  const match = findTagByTarget(html, target);
+  return match?.tag;
 }
 
 function patchAttributeByTarget(
   html: string,
   target: PatchTarget,
   attr: string,
-  value: string,
+  value: string | null,
 ): string {
   const match = findTagByTarget(html, target);
   if (!match) return html;
 
   const fullAttr = attr.startsWith("data-") ? attr : `data-${attr}`;
-  const attrPattern = new RegExp(`\\b${fullAttr}="[^"]*"`);
+  const attrPattern = new RegExp(`\\b${fullAttr}=(["'])([^"']*)\\1`);
+  const removableAttrPattern = new RegExp(`\\s+\\b${fullAttr}=(["'])([^"']*)\\1`);
   const tag = match.tag;
 
+  if (value == null) {
+    if (!attrPattern.test(tag)) return html;
+    return replaceTagAtMatch(html, match, tag.replace(removableAttrPattern, ""));
+  }
+
   if (attrPattern.test(tag)) {
     const newTag = tag.replace(attrPattern, `${fullAttr}="${value}"`);
     return replaceTagAtMatch(html, match, newTag);
@@ -230,14 +346,25 @@ function patchAttributeByTarget(
 /**
  * Apply an attribute change to an element in the HTML source.
  */
-function patchAttribute(html: string, elementId: string, attr: string, value: string): string {
-  const idPattern = new RegExp(`(<[^>]*\\bid="${escapeRegex(elementId)}"[^>]*)>`, "i");
+function patchAttribute(
+  html: string,
+  elementId: string,
+  attr: string,
+  value: string | null,
+): string {
+  const idPattern = new RegExp(`(<[^>]*\\bid=(["'])${escapeRegex(elementId)}\\2[^>]*)>`, "i");
   const match = idPattern.exec(html);
   if (!match) return html;
 
   const tag = match[1];
   const fullAttr = attr.startsWith("data-") ? attr : `data-${attr}`;
-  const attrPattern = new RegExp(`\\b${fullAttr}="[^"]*"`);
+  const attrPattern = new RegExp(`\\b${fullAttr}=(["'])([^"']*)\\1`);
+  const removableAttrPattern = new RegExp(`\\s+\\b${fullAttr}=(["'])([^"']*)\\1`);
+
+  if (value == null) {
+    if (!attrPattern.test(tag)) return html;
+    return html.replace(tag, tag.replace(removableAttrPattern, ""));
+  }
 
   if (attrPattern.test(tag)) {
     // Update existing attribute
@@ -254,11 +381,53 @@ function patchAttribute(html: string, elementId: string, attr: string, value: st
  * Apply a text content change to an element.
  */
 function patchTextContent(html: string, elementId: string, value: string): string {
-  // Match the element and its content: <tagname id="elementId"...>content</tagname>
-  const pattern = new RegExp(`(<[^>]*\\bid="${elementId}"[^>]*>)([\\s\\S]*?)(<\\/[a-z]+>)`, "i");
-  const match = pattern.exec(html);
+  const openTagPattern = new RegExp(
+    `(<([a-z0-9-]+)[^>]*\\bid=(["'])${escapeRegex(elementId)}\\3[^>]*>)`,
+    "i",
+  );
+  const match = openTagPattern.exec(html);
+  if (!match || match.index == null) return html;
+
+  const openingTag = match[1];
+  const tagName = match[2];
+  const contentStart = match.index + openingTag.length;
+  const closingIndex = findMatchingClosingTagIndex(html, tagName, contentStart);
+  if (closingIndex < 0) return html;
+
+  return `${html.slice(0, contentStart)}${value}${html.slice(closingIndex)}`;
+}
+
+function findMatchingClosingTagIndex(html: string, tagName: string, contentStart: number): number {
+  const tagPattern = new RegExp(`</?${escapeRegex(tagName)}\\b[^>]*>`, "gi");
+  tagPattern.lastIndex = contentStart;
+  let depth = 1;
+  let match: RegExpExecArray | null;
+
+  while ((match = tagPattern.exec(html)) !== null) {
+    const tag = match[0];
+    if (tag.startsWith("</")) {
+      depth -= 1;
+      if (depth === 0) return match.index;
+      continue;
+    }
+    if (!tag.endsWith("/>")) depth += 1;
+  }
+
+  return -1;
+}
+
+function patchTextContentByTarget(html: string, target: PatchTarget, value: string): string {
+  const match = findTagByTarget(html, target);
   if (!match) return html;
-  return html.replace(pattern, `${match[1]}${value}${match[3]}`);
+
+  const tagNameMatch = /^<([a-z0-9-]+)/i.exec(match.tag);
+  const tagName = tagNameMatch?.[1];
+  if (!tagName) return html;
+
+  const closingIndex = findMatchingClosingTagIndex(html, tagName, match.end + 1);
+  if (closingIndex < 0) return html;
+
+  return `${html.slice(0, match.end + 1)}${value}${html.slice(closingIndex)}`;
 }
 
 /**
@@ -267,11 +436,11 @@ function patchTextContent(html: string, elementId: string, value: string): strin
 export function applyPatch(html: string, elementId: string, op: PatchOperation): string {
   switch (op.type) {
     case "inline-style":
-      return patchInlineStyle(html, elementId, op.property, op.value);
+      return patchInlineStyle(html, elementId, op.property, op.value ?? "");
     case "attribute":
       return patchAttribute(html, elementId, op.property, op.value);
     case "text-content":
-      return patchTextContent(html, elementId, op.value);
+      return patchTextContent(html, elementId, op.value ?? "");
     default:
       return html;
   }
@@ -287,9 +456,11 @@ export function applyPatchByTarget(html: string, target: PatchTarget, op: PatchO
 
   switch (op.type) {
     case "inline-style":
-      return patchInlineStyleByTarget(html, target, op.property, op.value);
+      return patchInlineStyleByTarget(html, target, op.property, op.value ?? "");
     case "attribute":
       return patchAttributeByTarget(html, target, op.property, op.value);
+    case "text-content":
+      return patchTextContentByTarget(html, target, op.value ?? "");
     default:
       return html;
   }
diff --git a/packages/studio/src/utils/studioFileHistory.test.ts b/packages/studio/src/utils/studioFileHistory.test.ts
new file mode 100644
index 000000000..375843e80
--- /dev/null
+++ b/packages/studio/src/utils/studioFileHistory.test.ts
@@ -0,0 +1,156 @@
+import { describe, expect, it, vi } from "vitest";
+import { saveProjectFilesWithHistory } from "./studioFileHistory";
+
+describe("saveProjectFilesWithHistory", () => {
+  it("reads before content, writes after content, and records a history entry", async () => {
+    const reads: Record<string, string> = { "index.html": "before" };
+    const writes: Record<string, string> = {};
+    const recordEdit = vi.fn();
+
+    await saveProjectFilesWithHistory({
+      projectId: "project-1",
+      label: "Move layer",
+      kind: "manual",
+      files: { "index.html": "after" },
+      readFile: async (path) => reads[path],
+      writeFile: async (path, content) => {
+        writes[path] = content;
+      },
+      recordEdit,
+    });
+
+    expect(writes).toEqual({ "index.html": "after" });
+    expect(recordEdit).toHaveBeenCalledWith({
+      label: "Move layer",
+      kind: "manual",
+      coalesceKey: undefined,
+      files: { "index.html": { before: "before", after: "after" } },
+    });
+  });
+
+  it("skips writes and history for unchanged content", async () => {
+    const writeFile = vi.fn();
+    const recordEdit = vi.fn();
+
+    const changedPaths = await saveProjectFilesWithHistory({
+      projectId: "project-1",
+      label: "Edit layer",
+      kind: "manual",
+      files: { "index.html": "same" },
+      readFile: async () => "same",
+      writeFile,
+      recordEdit,
+    });
+
+    expect(changedPaths).toEqual([]);
+    expect(writeFile).not.toHaveBeenCalled();
+    expect(recordEdit).not.toHaveBeenCalled();
+  });
+
+  it("rolls back files already written when a later file write fails", async () => {
+    const reads: Record<string, string> = {
+      "index.html": "index-before",
+      "scene.html": "scene-before",
+    };
+    const writes: Array<[string, string]> = [];
+    const recordEdit = vi.fn();
+
+    await expect(
+      saveProjectFilesWithHistory({
+        projectId: "project-1",
+        label: "Move layer",
+        kind: "manual",
+        files: {
+          "index.html": "index-after",
+          "scene.html": "scene-after",
+        },
+        readFile: async (path) => reads[path],
+        writeFile: async (path, content) => {
+          writes.push([path, content]);
+          if (path === "scene.html") {
+            throw new Error("disk full");
+          }
+        },
+        recordEdit,
+      }),
+    ).rejects.toThrow("disk full");
+
+    expect(writes).toEqual([
+      ["index.html", "index-after"],
+      ["scene.html", "scene-after"],
+      ["index.html", "index-before"],
+    ]);
+    expect(recordEdit).not.toHaveBeenCalled();
+  });
+
+  it("rolls back written files when the injected history recorder throws", async () => {
+    const reads: Record<string, string> = {
+      "index.html": "index-before",
+      "scene.html": "scene-before",
+    };
+    const writes: Array<[string, string]> = [];
+
+    await expect(
+      saveProjectFilesWithHistory({
+        projectId: "project-1",
+        label: "Move layer",
+        kind: "manual",
+        files: {
+          "index.html": "index-after",
+          "scene.html": "scene-after",
+        },
+        readFile: async (path) => reads[path],
+        writeFile: async (path, content) => {
+          writes.push([path, content]);
+        },
+        recordEdit: async () => {
+          throw new Error("history unavailable");
+        },
+      }),
+    ).rejects.toThrow("history unavailable");
+
+    expect(writes).toEqual([
+      ["index.html", "index-after"],
+      ["scene.html", "scene-after"],
+      ["scene.html", "scene-before"],
+      ["index.html", "index-before"],
+    ]);
+  });
+
+  it("reports rollback failure with the original write failure", async () => {
+    const reads: Record<string, string> = {
+      "index.html": "index-before",
+      "scene.html": "scene-before",
+    };
+    const writes: Array<[string, string]> = [];
+
+    await expect(
+      saveProjectFilesWithHistory({
+        projectId: "project-1",
+        label: "Move layer",
+        kind: "manual",
+        files: {
+          "index.html": "index-after",
+          "scene.html": "scene-after",
+        },
+        readFile: async (path) => reads[path],
+        writeFile: async (path, content) => {
+          writes.push([path, content]);
+          if (path === "scene.html" && content === "scene-after") {
+            throw new Error("write denied");
+          }
+          if (path === "index.html" && content === "index-before") {
+            throw new Error("rollback denied");
+          }
+        },
+        recordEdit: vi.fn(),
+      }),
+    ).rejects.toThrow("rollback did not complete");
+
+    expect(writes).toEqual([
+      ["index.html", "index-after"],
+      ["scene.html", "scene-after"],
+      ["index.html", "index-before"],
+    ]);
+  });
+});
diff --git a/packages/studio/src/utils/studioFileHistory.ts b/packages/studio/src/utils/studioFileHistory.ts
new file mode 100644
index 000000000..95e0a2a39
--- /dev/null
+++ b/packages/studio/src/utils/studioFileHistory.ts
@@ -0,0 +1,61 @@
+import type { EditHistoryKind } from "./editHistory";
+
+interface SaveProjectFilesWithHistoryInput {
+  projectId: string;
+  label: string;
+  kind: EditHistoryKind;
+  coalesceKey?: string;
+  files: Record<string, string>;
+  readFile: (path: string) => Promise<string>;
+  writeFile: (path: string, content: string) => Promise<void>;
+  recordEdit: (entry: {
+    label: string;
+    kind: EditHistoryKind;
+    coalesceKey?: string;
+    files: Record<string, { before: string; after: string }>;
+  }) => Promise<void>;
+}
+
+export async function saveProjectFilesWithHistory({
+  label,
+  kind,
+  coalesceKey,
+  files,
+  readFile,
+  writeFile,
+  recordEdit,
+}: SaveProjectFilesWithHistoryInput): Promise<string[]> {
+  const snapshots: Record<string, { before: string; after: string }> = {};
+  for (const [path, after] of Object.entries(files)) {
+    const before = await readFile(path);
+    if (before !== after) {
+      snapshots[path] = { before, after };
+    }
+  }
+
+  const changedPaths = Object.keys(snapshots);
+  if (changedPaths.length === 0) return [];
+
+  const writtenPaths: string[] = [];
+  try {
+    for (const path of changedPaths) {
+      await writeFile(path, snapshots[path].after);
+      writtenPaths.push(path);
+    }
+
+    await recordEdit({ label, kind, coalesceKey, files: snapshots });
+  } catch (error) {
+    try {
+      for (const path of writtenPaths.reverse()) {
+        await writeFile(path, snapshots[path].before);
+      }
+    } catch (rollbackError) {
+      throw new AggregateError(
+        [error, rollbackError],
+        "Failed to save project files and rollback did not complete",
+      );
+    }
+    throw error;
+  }
+  return changedPaths;
+}
diff --git a/packages/studio/src/utils/timelineAssetDrop.test.ts b/packages/studio/src/utils/timelineAssetDrop.test.ts
index 2284091b4..80ff8dcf3 100644
--- a/packages/studio/src/utils/timelineAssetDrop.test.ts
+++ b/packages/studio/src/utils/timelineAssetDrop.test.ts
@@ -4,6 +4,7 @@ import {
   buildTimelineAssetInsertHtml,
   getTimelineAssetKind,
   insertTimelineAssetIntoSource,
+  resolveTimelineAssetInitialGeometry,
   resolveTimelineAssetSrc,
 } from "./timelineAssetDrop";
 
@@ -19,17 +20,21 @@ describe("getTimelineAssetKind", () => {
 
 describe("buildTimelineAssetInsertHtml", () => {
   it("builds an image clip with explicit timing and track", () => {
-    expect(
-      buildTimelineAssetInsertHtml({
-        id: "photo_asset",
-        assetPath: "assets/photo.png",
-        kind: "image",
-        start: 1.25,
-        duration: 3,
-        track: 2,
-        zIndex: 4,
-      }),
-    ).toContain('img id="photo_asset"');
+    const html = buildTimelineAssetInsertHtml({
+      id: "photo_asset",
+      assetPath: "assets/photo.png",
+      kind: "image",
+      start: 1.25,
+      duration: 3,
+      track: 2,
+      zIndex: 4,
+      geometry: { left: 0, top: 0, width: 1280, height: 720 },
+    });
+
+    expect(html).toContain('img id="photo_asset"');
+    expect(html).toContain("left: 0px");
+    expect(html).toContain("width: 1280px");
+    expect(html).not.toContain("inset:");
   });
 
   it("builds an audio clip without visual layout styles", () => {
@@ -47,6 +52,21 @@ describe("buildTimelineAssetInsertHtml", () => {
   });
 });
 
+describe("resolveTimelineAssetInitialGeometry", () => {
+  it("uses the target composition dimensions for visual media", () => {
+    expect(
+      resolveTimelineAssetInitialGeometry(
+        `<div data-composition-id="main" data-width="330" data-height="228"></div>`,
+      ),
+    ).toEqual({
+      left: 0,
+      top: 0,
+      width: 330,
+      height: 228,
+    });
+  });
+});
+
 describe("resolveTimelineAssetSrc", () => {
   it("keeps project-root asset paths for index.html", () => {
     expect(resolveTimelineAssetSrc("index.html", "assets/photo.png")).toBe("assets/photo.png");
diff --git a/packages/studio/src/utils/timelineAssetDrop.ts b/packages/studio/src/utils/timelineAssetDrop.ts
index c8ee11a55..9a431b4c5 100644
--- a/packages/studio/src/utils/timelineAssetDrop.ts
+++ b/packages/studio/src/utils/timelineAssetDrop.ts
@@ -76,6 +76,23 @@ export function buildTimelineFileDropPlacements(
   });
 }
 
+export function resolveTimelineAssetInitialGeometry(source: string): {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+} {
+  const width = Number.parseFloat(source.match(/\bdata-width=(["'])([^"']+)\1/i)?.[2] ?? "");
+  const height = Number.parseFloat(source.match(/\bdata-height=(["'])([^"']+)\1/i)?.[2] ?? "");
+
+  return {
+    left: 0,
+    top: 0,
+    width: Number.isFinite(width) && width > 0 ? Math.round(width) : 640,
+    height: Number.isFinite(height) && height > 0 ? Math.round(height) : 360,
+  };
+}
+
 export function buildTimelineAssetInsertHtml(input: {
   id: string;
   assetPath: string;
@@ -84,15 +101,18 @@ export function buildTimelineAssetInsertHtml(input: {
   duration: number;
   track: number;
   zIndex: number;
+  geometry?: { left: number; top: number; width: number; height: number };
 }): string {
   const sharedAttrs = `id="${input.id}" class="clip" src="${input.assetPath}" data-start="${input.start}" data-duration="${input.duration}" data-track-index="${input.track}"`;
+  const geometry = input.geometry ?? { left: 0, top: 0, width: 640, height: 360 };
+  const visualStyles = `position: absolute; left: ${geometry.left}px; top: ${geometry.top}px; width: ${geometry.width}px; height: ${geometry.height}px; object-fit: contain; z-index: ${input.zIndex}`;
 
   if (input.kind === "image") {
-    return `<img ${sharedAttrs} style="position: absolute; inset: 0; width: 100%; height: 100%; object-fit: contain; z-index: ${input.zIndex}" />`;
+    return `<img ${sharedAttrs} style="${visualStyles}" />`;
   }
 
   if (input.kind === "video") {
-    return `<video ${sharedAttrs} muted playsinline style="position: absolute; inset: 0; width: 100%; height: 100%; object-fit: contain; z-index: ${input.zIndex}"></video>`;
+    return `<video ${sharedAttrs} muted playsinline style="${visualStyles}"></video>`;
   }
 
   return `<audio ${sharedAttrs} style="z-index: ${input.zIndex}"></audio>`;
diff --git a/packages/studio/src/utils/timelineInspector.test.ts b/packages/studio/src/utils/timelineInspector.test.ts
new file mode 100644
index 000000000..e36945cfc
--- /dev/null
+++ b/packages/studio/src/utils/timelineInspector.test.ts
@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import { Window } from "happy-dom";
+import {
+  canInspectTimelineElement,
+  getTimelineElementKey,
+  isTimelineLayerVisibleInPreview,
+  isAudioTimelineElement,
+  shouldShowTimelineInspectorBounds,
+} from "./timelineInspector";
+
+function attachVisibleBox(
+  element: HTMLElement,
+  rect = { left: 10, top: 10, width: 80, height: 24 },
+) {
+  Object.defineProperty(element, "getBoundingClientRect", {
+    configurable: true,
+    value: () => ({
+      ...rect,
+      right: rect.left + rect.width,
+      bottom: rect.top + rect.height,
+      x: rect.left,
+      y: rect.top,
+      toJSON: () => ({}),
+    }),
+  });
+}
+
+function createDocument(markup: string): Document {
+  const window = new Window();
+  window.document.body.innerHTML = markup;
+  return window.document;
+}
+
+describe("getTimelineElementKey", () => {
+  it("prefers stable timeline keys over DOM ids", () => {
+    expect(getTimelineElementKey({ id: "card", key: "index.html#card" })).toBe("index.html#card");
+    expect(getTimelineElementKey({ id: "card" })).toBe("card");
+  });
+});
+
+describe("canInspectTimelineElement", () => {
+  it("allows visual timeline clips to opt into preview inspection", () => {
+    expect(canInspectTimelineElement({ tag: "section" })).toBe(true);
+    expect(canInspectTimelineElement({ tag: "video", src: "assets/demo.mp4" })).toBe(true);
+  });
+
+  it("blocks audio-only clips from opening the visual inspector", () => {
+    expect(canInspectTimelineElement({ tag: "audio" })).toBe(false);
+    expect(canInspectTimelineElement({ tag: "music" })).toBe(false);
+    expect(canInspectTimelineElement({ tag: "sfx" })).toBe(false);
+    expect(canInspectTimelineElement({ tag: "div", src: "assets/narration.mp3" })).toBe(false);
+  });
+});
+
+describe("isAudioTimelineElement", () => {
+  it("identifies audio-only clips by tag or source extension", () => {
+    expect(isAudioTimelineElement({ tag: "audio" })).toBe(true);
+    expect(isAudioTimelineElement({ tag: "sfx" })).toBe(true);
+    expect(isAudioTimelineElement({ tag: "div", src: "assets/narration.wav" })).toBe(true);
+    expect(isAudioTimelineElement({ tag: "video", src: "assets/demo.mp4" })).toBe(false);
+  });
+});
+
+describe("shouldShowTimelineInspectorBounds", () => {
+  const element = { start: 2, duration: 4 };
+
+  it("shows bounds at the clip start and end only", () => {
+    expect(shouldShowTimelineInspectorBounds(2, element)).toBe(true);
+    expect(shouldShowTimelineInspectorBounds(6, element)).toBe(true);
+    expect(shouldShowTimelineInspectorBounds(4, element)).toBe(false);
+  });
+
+  it("allows a small boundary tolerance", () => {
+    expect(shouldShowTimelineInspectorBounds(2.04, element, 0.05)).toBe(true);
+    expect(shouldShowTimelineInspectorBounds(2.08, element, 0.05)).toBe(false);
+  });
+
+  it("rejects missing and invalid timing", () => {
+    expect(shouldShowTimelineInspectorBounds(0, null)).toBe(false);
+    expect(shouldShowTimelineInspectorBounds(Number.NaN, element)).toBe(false);
+    expect(shouldShowTimelineInspectorBounds(0, { start: Number.NaN, duration: 1 })).toBe(false);
+  });
+});
+
+describe("isTimelineLayerVisibleInPreview", () => {
+  it("treats ancestor opacity as hidden for nested clip layers", () => {
+    const doc = createDocument(`
+      <div id="clip" style="opacity: 0">
+        <span id="label" style="opacity: 1">Label</span>
+      </div>
+    `);
+    const label = doc.getElementById("label");
+    expect(label).not.toBeNull();
+    attachVisibleBox(label as HTMLElement);
+
+    expect(isTimelineLayerVisibleInPreview(label as HTMLElement)).toBe(false);
+  });
+
+  it("accepts a boxed layer when ancestors are visible", () => {
+    const doc = createDocument(`
+      <div id="clip" style="opacity: 1">
+        <span id="label" style="opacity: 1">Label</span>
+      </div>
+    `);
+    const label = doc.getElementById("label");
+    expect(label).not.toBeNull();
+    attachVisibleBox(label as HTMLElement);
+
+    expect(isTimelineLayerVisibleInPreview(label as HTMLElement)).toBe(true);
+  });
+});
diff --git a/packages/studio/src/utils/timelineInspector.ts b/packages/studio/src/utils/timelineInspector.ts
new file mode 100644
index 000000000..aa76efd04
--- /dev/null
+++ b/packages/studio/src/utils/timelineInspector.ts
@@ -0,0 +1,89 @@
+import type { TimelineElement } from "../player";
+
+export const TIMELINE_INSPECTOR_BOUNDARY_EPSILON_SECONDS = 0.08;
+const AUDIO_TIMELINE_TAGS = new Set(["audio", "music", "sfx", "sound", "narration"]);
+const AUDIO_SOURCE_EXT_RE = /\.(aac|flac|m4a|mp3|ogg|opus|wav)(?:[?#].*)?$/i;
+
+export function getTimelineElementKey(
+  element: Pick<TimelineElement, "id" | "key"> | null | undefined,
+): string | null {
+  if (!element) return null;
+  return element.key ?? element.id;
+}
+
+export function canInspectTimelineElement(
+  element: Pick<TimelineElement, "tag" | "src"> | null | undefined,
+): boolean {
+  return !isAudioTimelineElement(element);
+}
+
+export function isAudioTimelineElement(
+  element: Pick<TimelineElement, "tag" | "src"> | null | undefined,
+): boolean {
+  if (!element) return false;
+  const tag = element.tag.trim().toLowerCase();
+  if (AUDIO_TIMELINE_TAGS.has(tag)) return true;
+  return Boolean(element.src && AUDIO_SOURCE_EXT_RE.test(element.src));
+}
+
+export function shouldShowTimelineInspectorBounds(
+  currentTime: number,
+  element: Pick<TimelineElement, "start" | "duration"> | null | undefined,
+  epsilonSeconds = TIMELINE_INSPECTOR_BOUNDARY_EPSILON_SECONDS,
+): boolean {
+  if (!element) return false;
+  if (!Number.isFinite(currentTime)) return false;
+  if (!Number.isFinite(element.start) || !Number.isFinite(element.duration)) return false;
+  const start = Math.max(0, element.start);
+  const end = Math.max(start, start + Math.max(0, element.duration));
+  const epsilon = Math.max(0, epsilonSeconds);
+  return Math.abs(currentTime - start) <= epsilon || Math.abs(currentTime - end) <= epsilon;
+}
+
+export interface TimelineLayerVisibility {
+  visible: boolean;
+  compositeOpacity: number;
+}
+
+export function getTimelineLayerVisibilityInPreview(
+  element: HTMLElement,
+  options: { minCompositeOpacity?: number } = {},
+): TimelineLayerVisibility {
+  if (!element.isConnected) return { visible: false, compositeOpacity: 0 };
+  const doc = element.ownerDocument;
+  const win = doc.defaultView;
+  if (!win) return { visible: false, compositeOpacity: 0 };
+
+  const minCompositeOpacity = options.minCompositeOpacity ?? 0.01;
+  let compositeOpacity = 1;
+  let current: HTMLElement | null = element;
+  while (current && current !== doc.body && current !== doc.documentElement) {
+    const style = win.getComputedStyle(current);
+    if (style.display === "none" || style.visibility === "hidden") {
+      return { visible: false, compositeOpacity };
+    }
+    compositeOpacity *= Number.parseFloat(style.opacity || "1");
+    if (compositeOpacity <= minCompositeOpacity) return { visible: false, compositeOpacity };
+    current = current.parentElement;
+  }
+
+  const rect = element.getBoundingClientRect();
+  if (rect.width <= 0.5 || rect.height <= 0.5) {
+    return { visible: false, compositeOpacity };
+  }
+
+  const viewportWidth = win.innerWidth || doc.documentElement.clientWidth;
+  const viewportHeight = win.innerHeight || doc.documentElement.clientHeight;
+  return {
+    compositeOpacity,
+    visible:
+      rect.right > 0 && rect.bottom > 0 && rect.left < viewportWidth && rect.top < viewportHeight,
+  };
+}
+
+export function isTimelineLayerVisibleInPreview(
+  element: HTMLElement,
+  options: { minCompositeOpacity?: number } = {},
+): boolean {
+  return getTimelineLayerVisibilityInPreview(element, options).visible;
+}
diff --git a/packages/studio/vite.config.ts b/packages/studio/vite.config.ts
index 6d99b3a36..493124c35 100644
--- a/packages/studio/vite.config.ts
+++ b/packages/studio/vite.config.ts
@@ -8,7 +8,7 @@ import {
   lstatSync,
   realpathSync,
 } from "node:fs";
-import { join, resolve } from "node:path";
+import { join, relative, resolve } from "node:path";
 import type {
   StudioApiAdapter,
   ResolvedProject,
@@ -53,7 +53,7 @@ const THUMBNAIL_CACHE_VERSION = "v2";
 function createViteAdapter(dataDir: string, server: ViteDevServer): StudioApiAdapter {
   // Lazy-load the bundler via Vite's SSR module loader
   let _bundler: ((dir: string) => Promise<string>) | null = null;
-  let _producerModulePromise: Promise<{
+  type ProducerModule = {
     createRenderJob: (config: {
       fps: 24 | 30 | 60;
       quality: "draft" | "standard" | "high";
@@ -65,7 +65,8 @@ function createViteAdapter(dataDir: string, server: ViteDevServer): StudioApiAda
       outputPath: string,
       onProgress?: (job: { progress: number; currentStage?: string }) => void,
     ) => Promise<void>;
-  }> | null = null;
+  };
+  let _producerModuleLoader: (() => Promise<ProducerModule>) | null = null;
   const getBundler = async () => {
     if (!_bundler) {
       try {
@@ -80,8 +81,8 @@ function createViteAdapter(dataDir: string, server: ViteDevServer): StudioApiAda
   };
 
   const getProducerModule = async () => {
-    if (!_producerModulePromise) {
-      _producerModulePromise = createRetryingModuleLoader(async () => {
+    if (!_producerModuleLoader) {
+      _producerModuleLoader = createRetryingModuleLoader(async () => {
         const { built } = ensureProducerDist({
           studioDir: __dirname,
           env: process.env,
@@ -93,9 +94,9 @@ function createViteAdapter(dataDir: string, server: ViteDevServer): StudioApiAda
         }
         const producerPkg = "@hyperframes/producer";
         return await import(/* @vite-ignore */ producerPkg);
-      })();
+      });
     }
-    return _producerModulePromise();
+    return _producerModuleLoader();
   };
 
   return {
@@ -237,7 +238,7 @@ function createViteAdapter(dataDir: string, server: ViteDevServer): StudioApiAda
 
     async generateThumbnail(opts) {
       const selectorKey = opts.selector
-        ? `_${opts.selector.replace(/[^a-zA-Z0-9_-]+/g, "_").slice(0, 80)}`
+        ? `_${opts.selector.replace(/[^a-zA-Z0-9_-]+/g, "_").slice(0, 80)}_${opts.selectorIndex ?? 0}`
         : "";
       const cacheKey = `${THUMBNAIL_CACHE_VERSION}_${opts.compPath.replace(/\//g, "_")}_${opts.seekTime.toFixed(2)}${selectorKey}.jpg`;
 
@@ -289,23 +290,34 @@ function createViteAdapter(dataDir: string, server: ViteDevServer): StudioApiAda
           await new Promise((r) => setTimeout(r, 200));
           let clip: { x: number; y: number; width: number; height: number } | undefined;
           if (opts.selector) {
-            clip = await page.evaluate((selector: string) => {
-              const el = document.querySelector(selector);
-              if (!(el instanceof HTMLElement)) return undefined;
-              const rect = el.getBoundingClientRect();
-              if (rect.width < 4 || rect.height < 4) return undefined;
-              const pad = 8;
-              const x = Math.max(0, rect.left - pad);
-              const y = Math.max(0, rect.top - pad);
-              const maxWidth = window.innerWidth - x;
-              const maxHeight = window.innerHeight - y;
-              return {
-                x,
-                y,
-                width: Math.max(1, Math.min(rect.width + pad * 2, maxWidth)),
-                height: Math.max(1, Math.min(rect.height + pad * 2, maxHeight)),
-              };
-            }, opts.selector);
+            clip = await page.evaluate(
+              (selector: string, selectorIndex: number | 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;
+                const pad = 8;
+                const x = Math.max(0, rect.left - pad);
+                const y = Math.max(0, rect.top - pad);
+                const maxWidth = window.innerWidth - x;
+                const maxHeight = window.innerHeight - y;
+                return {
+                  x,
+                  y,
+                  width: Math.max(1, Math.min(rect.width + pad * 2, maxWidth)),
+                  height: Math.max(1, Math.min(rect.height + pad * 2, maxHeight)),
+                };
+              },
+              opts.selector,
+              opts.selectorIndex,
+            );
           }
           const buf = await page.screenshot(
             opts.format === "png"
@@ -398,6 +410,7 @@ function devProjectApi(): Plugin {
     configureServer(server): void {
       // Load the shared module lazily via SSR (resolves hono + TypeScript)
       let _api: { fetch: (req: Request) => Promise<Response> } | null = null;
+      const recentApiWriteProjects = new Map<string, number>();
       const getApi = async () => {
         if (!_api) {
           const mod = await server.ssrLoadModule("@hyperframes/core/studio-api");
@@ -452,6 +465,7 @@ function devProjectApi(): Plugin {
           const url = new URL(req.url, `http://${req.headers.host}`);
           // Strip /api prefix — shared module routes are relative
           url.pathname = url.pathname.slice(4);
+          const apiPath = url.pathname;
 
           // Read body for non-GET/HEAD
           let body: Buffer | undefined;
@@ -472,6 +486,11 @@ function devProjectApi(): Plugin {
           });
 
           const response = await api.fetch(fetchReq);
+          const writeMatch =
+            /^\/projects\/([^/]+)\/(?:edits|history\/(?:undo|redo|record-applied))/.exec(apiPath);
+          if (writeMatch?.[1]) {
+            recentApiWriteProjects.set(decodeURIComponent(writeMatch[1]), Date.now());
+          }
           await bridgeHonoResponse(response, res);
         } catch (err) {
           console.error("[Studio API] Error:", err);
@@ -483,13 +502,13 @@ function devProjectApi(): Plugin {
       });
 
       // Watch project directories for file changes → HMR
-      const realProjectPaths: string[] = [];
+      const realProjectPaths: Array<{ id: string; dir: string }> = [];
       try {
         for (const entry of readdirSync(dataDir, { withFileTypes: true })) {
           const full = join(dataDir, entry.name);
           try {
             const real = lstatSync(full).isSymbolicLink() ? realpathSync(full) : full;
-            realProjectPaths.push(real);
+            realProjectPaths.push({ id: entry.name, dir: real });
             server.watcher.add(real);
           } catch {
             /* skip broken symlinks */
@@ -500,13 +519,44 @@ function devProjectApi(): Plugin {
       }
 
       server.watcher.on("change", (filePath: string) => {
-        const isProjectFile = realProjectPaths.some((p) => filePath.startsWith(p));
+        const project = realProjectPaths.find((p) => filePath.startsWith(p.dir));
+        const isProjectFile = Boolean(project);
         if (
           isProjectFile &&
           (filePath.endsWith(".html") || filePath.endsWith(".css") || filePath.endsWith(".js"))
         ) {
+          const relativePath = project ? relative(project.dir, filePath).split("\\").join("/") : "";
+          if (project && relativePath) {
+            const recentApiWrite = recentApiWriteProjects.get(project.id);
+            const shouldAdopt = !recentApiWrite || Date.now() - recentApiWrite > 3000;
+            if (shouldAdopt) {
+              void getApi()
+                .then((api) =>
+                  api.fetch(
+                    new Request(
+                      `http://studio/projects/${encodeURIComponent(project.id)}/history/adopt-external`,
+                      {
+                        method: "POST",
+                        headers: { "Content-Type": "application/json" },
+                        body: JSON.stringify({
+                          paths: [relativePath],
+                          actor: { type: "external" },
+                        }),
+                      },
+                    ),
+                  ),
+                )
+                .catch((error) => {
+                  console.warn("[Studio] Failed to adopt external file edit:", error);
+                });
+            }
+          }
           console.log(`[Studio] File changed: ${filePath}`);
-          server.ws.send({ type: "custom", event: "hf:file-change", data: {} });
+          server.ws.send({
+            type: "custom",
+            event: "hf:file-change",
+            data: { projectId: project?.id, paths: relativePath ? [relativePath] : [] },
+          });
         }
       });
     },