Skip to main content
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
  • edit style properties from the right-side Design inspector
  • edit text content for safe text-bearing selections
  • edit solid fills, gradients, image fills, opacity, radius, flex properties, 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 current selection
The important rule is still 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
  • move handle behavior for supported elements
  • a resize handle when width and height are safely patchable
  • a small floating toolbar with Move, Styles, and Ask agent
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
  • Flex
    • direction, justify, align, gap, clip content
  • Radius
    • slider + readout
  • Blending
    • opacity slider + blend mode
  • Fill
    • solid color
    • multi-stop gradient editing
    • image URL fill
    • text color
  • Text
    • direct text content editing when the selection is safe to patch
  • 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.

​
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 inline left and top values that parse as 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.

​
Text editing support

Text editing is allowed only for safe text-bearing selections:
  • supported text-bearing tags such as div, span, p, and headings
  • non-empty text content
  • not a composition host

​
Unsupported examples

Studio intentionally withholds direct geometry editing for:
  • flex/grid children whose position is emergent from layout
  • transform-driven geometry
  • nested composition internals while the user is still in master view
  • nodes without a stable patch target
When geometry is blocked but style edits are still safe, the inspector shows the selection and the reason direct geometry editing is unavailable.

​
Nested Composition Rules

Nested compositions are handled explicitly.

​
In master view

  • clicking content inside a nested composition maps back to the composition host
  • 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
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
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.

​
Numeric Scrubbing

Numeric layout/detail inputs now 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
  • packages/studio/src/components/editor/DomEditOverlay.tsx
    • overlay box, toolbar, drag, resize
  • packages/studio/src/components/editor/PropertyPanel.tsx
    • right-side inspector UI
  • packages/studio/src/components/editor/domEditing.ts
    • selection resolution
    • capability gating
    • prompt generation
  • packages/studio/src/components/editor/colorValue.ts
    • color parsing and alpha-preserving color picker behavior
  • 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/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

​
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

​
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.