Visual Editor

VoxelSite includes a visual editor that lets you click on any element in your page and edit it directly — text, images, styles, new sections, and AI-powered rewrites — without writing code.

Activating the editor

Click the Edit button in the preview toolbar (above the live preview). The preview iframe enters editing mode:

• Hovering over any editable element shows a blue highlight
• Clicking an element selects it and opens a context toolbar
• The page is live — scroll, resize, and interact normally

Click Edit again to deactivate.

While the editor is active, all controls outside the preview are disabled and dimmed — the top navigation, status bar, and conversation panel. Only the Edit toggle stays interactive, preventing accidental navigation or state changes while you're editing.

What you can do

Edit text inline

Select any text element (heading, paragraph, button label, link) and click the Edit action in the toolbar. The text becomes editable right where it is, and a formatting toolbar appears above the element.

Type your changes, use Enter for line breaks, and format text with the toolbar or keyboard shortcuts. When you're done, click Apply (or press ⌘↵) to save your changes — a brief saving animation confirms the write. Click Cancel (or press Esc) to revert the element to its original content.

Formatting text

The formatting toolbar offers three controls:

The toolbar tracks the element — if it grows taller as you type, the toolbar follows. Formatting buttons highlight when the cursor is inside formatted text.

When inserting or editing a link, a dedicated modal appears with the URL field, an optional Link Style dropdown (populated from existing link classes on the page), and an Open in new window checkbox. The modal is draggable and shows contextual titles — "Insert Link" for new links, "Edit Link" when the cursor is inside an existing link.

If an element contains PHP template syntax (<?php, <?=), the toolbar shows a "PHP detected" hint instead of formatting buttons. Use the Code Editor for those elements.

Swap images

Select an image and click the Image action. VoxelSite opens the asset picker so you can choose a replacement from your uploaded images. The toolbar hides while the picker is open and reappears if you cancel. After selecting an image, the element deselects for a clean state.

Edit styles

Select any element and click the Style action to open the style editor panel. The panel uses icon-based navigation to organize style controls into tabs:

Every style change previews instantly on the page — no page reload or server round-trip needed. This is powered by the JIT CSS engine (see below).

Edit with AI

Select any element and click the AI button in the toolbar. A prompt panel appears centered above the element where you can describe changes in plain language:

• "Make this section warmer with earth tones"
• "Add a third testimonial card"
• "Change this to a two-column layout"
• "Rewrite the heading to be more compelling"

The panel title shows the element you're editing (e.g., "Edit Section" or "Edit Heading"). Type your instructions — press Enter for new lines, ⌘↵ (Ctrl+Enter) to submit. The textarea auto-grows as you type.

When you submit, the panel closes and the entire Studio enters a generating state — the same full-page overlay used by the code editor's inline AI:

• A centred status card appears over a backdrop, blocking all Studio interaction
• The card shows a live timer, current step, token count, and a Stop button
• Inside the preview, the selected element dims with a gentle opacity pulse and animated amber hatch lines

Press Escape or click Stop to cancel the generation. The AI rewrites the section in the source file, and the preview reloads automatically with the result.

The panel is draggable — grab the grip icon in the header to reposition it. If you select a different element or deselect, the panel closes automatically.

Delete elements

Select any element and click the Delete action. A confirmation dialog appears before the element is permanently removed from the source.

Edit source code

Select any element and click the Source (<>) button in the toolbar. An inline Monaco editor appears directly over the element, showing the raw HTML source — including any PHP code (<?php, <?=).

This is useful when you need precise control over attributes, structure, or embedded PHP expressions that the visual controls don't cover.

How it works

1. VoxelSite fetches the actual source file and extracts the exact fragment for this element using the internal address system
2. The source text appears in a syntax-highlighted editor with line numbers
3. Edit the HTML directly — add attributes, restructure nested elements, modify PHP expressions
4. Click Apply (or press ⌘S) to save, or Cancel (or press Esc) to discard

Validation

The editor validates your HTML as you type:

• Tag balance — every opening tag must have a matching closing tag in the correct order. Misnested tags like <div><span></div></span> are caught immediately
• Missing closing brackets — a <div class="foo" without a closing > is flagged
• Dangerous content — <script>, <iframe>, and inline on*= event handlers are blocked
• Root element — the element must remain a single top-level tag of the same type

When validation detects a problem, the Apply button is disabled, a warning message appears with the specific error and line number, and a red squiggly marker highlights the problem line in the editor.

Pessimistic save

The source editor saves defensively:

1. Your change is written to the source file first
2. Only after the file save succeeds does the live preview update
3. If the save fails (file changed externally, ambiguous match), the editor stays open with a clear error — the preview is never left in an inconsistent state

Both text edits and source edits save defensively: the file is written first, and the preview updates only after the write succeeds.

Add sections

Between every section on your page, a small + button appears at the section boundary. Click it to open the section picker.

Choosing a section type

The picker presents a grid of section types, each with an icon and a brief description:

Adding instructions

After selecting a section type, an optional instruction field appears. You can leave it empty (the AI will generate appropriate content for your business), or provide specific direction:

• "3 team members with short bios"
• "5 questions about shipping and returns"
• "pricing for Basic, Pro, and Enterprise plans"

Click Generate to start. The AI creates the section to match your site's existing design language — same fonts, colors, spacing rhythm, and Tailwind patterns.

What happens during generation

A full-page overlay appears — the same design used by the code editor's inline AI and the visual editor's AI edit — with live progress:

1. Preparing — the AI reads your site context
2. Generating — the status card shows elapsed time, token count, and a Stop button (e.g., "Generating FAQ… 12s · 1,250 tokens")
3. Done — the page reloads, scrolls to the new section, and highlights it with a brief blue outline

Press Escape or click Stop to cancel generation at any time.

Typical generation takes 20–30 seconds.

Where sections are inserted

The section is inserted exactly where you clicked the + button:

• Click the + at the very top → the new section appears before your first section
• Click the + between the hero and content sections → the new section appears between them
• Click the + after the last section → the new section appears at the end

Move sections

Each section divider also shows ▲ and ▼ chevron buttons for reordering sections. These buttons appear when you hover a divider and control the section directly above that divider.

The move is instant — no AI generation, no waiting. The section swaps position in the page immediately, and the change is saved to the source file in the background.

After a move, the page scrolls to follow the section to its new position. The divider below the moved section shows the appropriate buttons to undo the move or continue in either direction.

Visual feedback

When you hover a section divider, a diagonal-hatching overlay appears over the section that divider controls. This makes it immediately clear which section the ▲ and ▼ buttons refer to.

The first divider at the very top of the page is labeled top and has no chevrons — it only contains the + button for inserting a new section before the first one.

The Style Panel

Icon-based navigation

The style panel uses a row of small SVG icons instead of text tabs. This keeps the panel compact and lets you jump between categories quickly. The active tab is highlighted.

Color picker

The color picker displays all Tailwind colors in a compact scrollable grid:

1. Choose the property — Switch between Text, Background, and Border using the segmented control at the top
2. Special colors — White, black, and transparent appear above the matrix
3. Pick a color — The scrollable matrix shows all 17 color families × 11 shades (50–950). Four rows are visible at a time; scroll to see more. The active color cell is highlighted with a white border indicator

When reopening the color tab, the matrix auto-scrolls to reveal the currently active color. Scroll position is preserved when clicking colors, so the matrix stays in place.

Live preview

Every change you make in the style panel previews instantly on the page. The original classes are preserved until you explicitly click Apply & Compile. If you close the panel without applying or click Reset, all preview changes are reverted.

Responsive breakpoints

Your website looks different on a phone than it does on a desktop monitor. The style panel lets you control exactly how each element looks at every screen size using the breakpoint bar — a row of buttons between the tab icons and the style controls:

[ Base ] [ sm ] [ md ] [ lg ] [ xl ] [ 2xl ]

Each button represents a screen-size range:

How it works

1. Select a breakpoint — Click a button in the bar. All controls in the style panel now show and edit styles only for that screen size.

2. Make your change — For example, set the font size to 4xl while lg is selected. This means "on large screens and up, use size 4xl" — smaller screens are not affected.

3. Check other breakpoints — Click Base to see what mobile visitors get, then click lg to see the desktop version. Each breakpoint is independent.

The dot indicator

When a breakpoint button shows a small amber dot (●), it means the selected element already has styles set specifically for that screen size. This makes it easy to see at a glance which breakpoints have been customized.

How styles cascade

Styles work from small to large — a style set at Base applies to all screen sizes unless a larger breakpoint overrides it. For example:

• Base = text-lg → all screens show large text
• md = text-2xl → tablets and larger show extra-large text instead
• xl = text-4xl → desktops show even bigger text

You don't need to set every breakpoint. Only set the ones where you want the style to change.

Practical tips

• Start with Base — Design for mobile first, then add overrides at larger breakpoints
• Watch the dot — If a heading looks wrong on desktop but fine on mobile, check which breakpoints have dots — the override is there
• Use the Classes tab — Switch to the Classes tab to see the raw class names (like md:text-2xl). This can help you understand exactly what is applied at each breakpoint

Apply & Compile

When you click Apply & Compile, VoxelSite:

1. Updates the element's class attribute in the source PHP file
2. Triggers a Tailwind CSS recompile to include any new utility classes
3. Reloads the preview CSS so the compiled styles take effect

This ensures your changes are persisted and the compiled stylesheet stays in sync.

JIT CSS Preview

VoxelSite includes a Just-In-Time CSS engine that runs entirely in the browser. When you toggle a Tailwind class in the style panel, the JIT engine generates the corresponding CSS rule instantly and injects it into the page — no server call required.

The JIT engine supports:

• Typography — font sizes, weights, tracking, leading, transforms, decorations
• Colors — all 22 Tailwind color families × 11 shades for text, background, and border
• Spacing — padding and margin for all sides, using the full Tailwind spacing scale
• Layout — width, max-width, display, flex direction, alignment, gap
• Borders — border width, radius, style
• Effects — box shadows, opacity
• Responsive prefixes — all of the above work with breakpoint prefixes (sm:, md:, lg:, xl:, 2xl:)

When you apply your changes, VoxelSite compiles the final Tailwind CSS on the server to replace the JIT preview with production-quality styles.

The draggable panel

The style panel can be dragged anywhere on screen using the grip icon (⋮⋮) in the header. This lets you position it wherever is most convenient while editing.

Keyboard shortcuts

How edits are saved

All visual editor changes follow the same save pipeline as AI-generated changes:

1. VoxelSite identifies the element using an internal address system that tracks every element back to its exact position in the source file
2. It locates the matching content in the PHP source file (page or partial) using a deterministic index-based locator
3. If the element is found, the file is updated. If the locator fails, the save falls back to content matching and rejects with a clear error if zero or multiple matches are found
4. The change is tracked in the revision system — you can undo it
5. Tailwind CSS is recompiled if needed, and the preview refreshes

For source editor changes, the save uses the literal source text as the match needle — guaranteeing an exact match even when the source contains PHP expressions, multi-line attributes, or whitespace that differs from the browser's rendering. For text edits, the save uses the same index-based locator to precisely replace the element's inner content.

This means visual editor changes integrate fully with undo/redo and snapshots.

Related

• How Prompting Works — What happens under the hood when AI generates or edits your site
• Chat — The AI conversation panel for describing changes in natural language
• Code Editor — Edit source files directly with syntax highlighting and inline AI
• Undo & Snapshots — Roll back any change