chore: merge next into main

.gitignore

@@ -62,7 +62,8 @@ tmp/
 packages/core/src/generated/
 packages/producer/src/services/fontData.generated.ts
 
-# Test artifacts
+# Local proof / test artifacts
+qa-artifacts/
 my-video/
 examples/
 packages/studio/data/
@@ -99,3 +100,5 @@ ab-test/
 compositions/
 video-6-2-patched/
 claude-design-hyperframes-video/
+.claude/worktrees/
+.claude/

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>

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.

docs/docs.json

@@ -222,7 +222,8 @@
               "contributing",
               "contributing/catalog",
               "contributing/release-channels",
-              "contributing/testing-local-changes"
+              "contributing/testing-local-changes",
+              "contributing/studio-manual-dom-editing"
             ]
           },
           {