Studio Manual DOM Editing

Documentation Index

Fetch the complete documentation index at: https://hyperframes.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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.