---
date: 2026-03-04
topic: wysiwyg-inline-editor-sync
---

# WYSIWYG Inline Editor + HTML/JSON Sync

## What We're Building
A local-first WYSIWYG editing mode for the static HTML snapshot where creators can edit page content directly on the rendered page. Text becomes editable on double-click using inline `contenteditable` behavior. Images open a small overlay for editing `src` and `alt` only.

Edits must update both representations: the HTML content and the extracted content JSON. Persistence is local file write (not browser-only), so creators can save directly to project files during offline editing.

This phase is content-only. It explicitly excludes CSS/layout editing.

## Why This Approach
Approach A (in-page edit mode + local save service) was selected because it matches the intended user behavior: fast direct edits where content lives visually. It minimizes training and friction for non-technical editors who already think in terms of “change this heading here.”

YAGNI rationale: keep the first editor narrow and reliable. Only text and image content are editable, and image validation is warning-based (not blocking) to avoid blocking workflows while still reducing accidental visual breakage.

## Key Decisions
- Interaction model: Double-click inline editing for text.
- Save behavior: Auto-save on blur/enter plus manual save/undo controls.
- Image editing v1: Overlay for `src` + `alt` only.
- Ratio validation: Warning (non-blocking), threshold set to 15% difference between current and replacement image aspect ratios.
- Persistence model: Direct local file writes to `.html` and `.json` through a local helper service.
- Sync model: Bidirectional HTML ↔ JSON.
- Conflict default: HTML wins when both sides changed for the same mapped key.
- Scope guard: No CSS/layout editing in this phase.

## Resolved Questions
- Inline editing is preferred over panel-based editing.
- Save UX should support both auto-save and explicit controls.
- Image editing should remain limited to `src`/`alt` in v1.
- Ratio checks are advisory to preserve editor flow.
- Local file write capability is required for practical offline usage.

## Open Questions
- None currently.

## Next Steps
1. Move to planning for step 2 (`/prompts:workflows-plan`) with focus on editor UX rules, content identity mapping, and local save contract.
2. Keep implementation split into phases: text editing first, then image overlay and ratio warning behavior.