---
title: "feat: Inline WYSIWYG editor with HTML-JSON sync"
type: feat
status: completed
date: 2026-03-04
---

# feat: Inline WYSIWYG editor with HTML-JSON sync

## Overview
Build step 2 of the content workflow: a local-first WYSIWYG editor for the existing static page where creators can directly edit content on the rendered page and persist changes to both HTML and JSON.

This plan is limited to content editing and synchronization behavior. It explicitly excludes style/layout editing.

## Problem Statement / Motivation
The repository now has extractable structured content (`content/site-content.de.json`) but no practical editing surface for creators. Editors need direct, low-friction page editing (double-click text, click image) while keeping HTML and JSON in sync.

## Proposed Solution
Add an in-page edit mode with inline `contenteditable` text editing and an image overlay editor for `src` and `alt`. Implement autosave (blur/enter) plus manual save/undo controls. Persist edits via a local helper service that writes both `ikfreunde.com.html` and `content/site-content.de.json`.

Synchronization is bidirectional in model intent, with conflict default set to HTML wins when the same mapped key diverges.

## Scope
In scope:
- Text editing on double-click for editable content nodes
- Image editing overlay for `src` and `alt`
- Aspect-ratio warning (non-blocking) at 15% threshold
- Autosave + manual save/undo controls
- Local persistence endpoint to write HTML + JSON
- Content identity mapping between DOM elements and JSON keys
- Conflict handling policy: HTML wins

Out of scope:
- CSS/layout editing
- `srcset`/`picture` editing
- Multi-user collaboration or remote persistence
- Authentication/authorization layer

## Technical Considerations
- Current site scripts are bundled/minified, so editor behavior should be isolated in a dedicated script layer.
- Content identity mapping must be stable enough for repeat edits and sync.
- Editing rules should avoid hidden/system nodes (cookie mechanics/scripts/non-content regions unless explicitly intended).
- Local persistence requires a trusted local helper process and clear file write boundaries.
- Undo scope must be defined (session-level content undo, not full VCS-like history).

## SpecFlow Analysis
Primary flow:
1. Editor enters edit mode.
2. User double-clicks text node and edits inline.
3. User blur/enter triggers autosave path.
4. Mapping resolves edited node to JSON key.
5. HTML and JSON are both updated and persisted via local helper.

Image flow:
1. User selects editable image.
2. Overlay opens with current `src` and `alt`.
3. New source is validated; ratio warning shown if aspect ratio differs by >15%.
4. User can still save despite warning.
5. HTML and JSON are updated and persisted.

Conflict flow:
1. Divergent values detected for same mapped key.
2. Default resolution applies: HTML value wins.
3. JSON is reconciled to HTML on save.

## Acceptance Criteria
- [x] Double-click enables inline text editing on intended content elements.
- [x] Text autosaves on blur/enter and also supports explicit save/undo controls.
- [x] Clicking editable images opens an overlay with `src` and `alt` fields.
- [x] Image ratio check warns (non-blocking) when replacement differs by >15% aspect ratio.
- [x] Save operation persists both `ikfreunde.com.html` and `content/site-content.de.json`.
- [x] Sync mapping updates the correct JSON key for edited text/image values.
- [x] Conflict resolution follows HTML-wins default.
- [x] No CSS/layout properties are modified by editor actions.

## Success Metrics
- Editors can modify headings/body text/images directly on page without manual JSON editing.
- Saved output remains consistent between HTML and JSON for edited items.
- Editing interactions feel immediate and require minimal training.
- No unintended style/layout changes caused by the editor.

## Dependencies & Risks
Dependencies:
- Defined DOM↔JSON mapping contract for editable nodes
- Local helper service runtime available in the editor environment

Risks:
- Incorrect key mapping leading to wrong JSON updates
- Over-editability (allowing non-content nodes)
- Unexpected side effects from integrating with existing bundled scripts
- File write race conditions during rapid autosave

Mitigations:
- Explicit editable-node allowlist and mapping tests
- Isolated editor namespace/events
- Debounced autosave + write serialization
- Dry-run/preview diagnostics for mapping during development

## References & Research
- Brainstorm input: `docs/brainstorms/2026-03-04-wysiwyg-inline-editor-sync-brainstorm.md`
- Prior extraction plan: `docs/plans/2026-03-04-feat-dom-to-json-content-extraction-plan.md`
- Extractor/source contract: `scripts/extract_dom_content.php`, `content/site-content.de.json`
- Target HTML: `ikfreunde.com.html`
