---
date: 2026-03-03
topic: dom-json-wysiwyg-sync
---

# DOM to JSON + WYSIWYG Sync

## What We're Building
A content workflow for this static site that starts with DOM-to-JSON extraction and then enables inline visual editing. The immediate goal is a JSON file generated from the current HTML snapshot that captures:
- visible page text
- page metadata (`title`, description, Open Graph/Twitter meta)
- image content (`img src` and `alt`)

The JSON should preserve subtopics and be structured by DOM context so it maps cleanly to the existing page. The follow-up goal is a lightweight WYSIWYG editor that lets humans change text directly in the page and update image `src`/`alt`, with synchronization between HTML and JSON.

## Why This Approach
The chosen direction prioritizes low-friction adoption in an existing static snapshot where editors still work directly in HTML. A DOM-to-JSON first pass minimizes upfront modeling effort and captures the current content state quickly. Then, a WYSIWYG layer provides direct manipulation while preserving visual context.

YAGNI rationale: avoid building a full CMS or strict schema-first localization system now. Start with extraction and practical editing primitives, then evolve only if editorial complexity requires it.

## Key Decisions
- Output format: Nested JSON with subtopics.
- Extraction scope: Visible page text plus metadata (title/description/Open Graph/Twitter).
- Key organization: DOM-first grouping with section-based top-level subtopics.
- Duplicate handling: Hybrid strategy. Keep section-local duplicates; dedupe only global/common content.
- Product scope: Include both stages in feature intent, but implement DOM-to-JSON extraction first.
- Sync model (future WYSIWYG): Bidirectional HTML ↔ JSON sync.
- Image editing v1 (future WYSIWYG): Edit `img src` and `alt` only (exclude `srcset`/`picture` initially).
- WYSIWYG editing scope v1 (future): Content updates only (text and image properties), no styling/layout editing.
- Content identity: Hybrid identification. Reuse existing selectors/IDs where possible and add `data-*` IDs only where needed.

## Resolved Questions
- JSON shape should include subtopics rather than flat keys.
- Metadata must be part of extraction.
- Human editors will still work against the HTML site, so DOM-oriented extraction is preferred.
- Full responsive image source editing is deferred to avoid layout breakage risk.

## Open Questions
- None currently.

## Next Steps
1. Proceed to planning (`/prompts:workflows-plan`) focused only on step 1: extraction pipeline and JSON structure contract.
2. Follow with a second planning pass for step 2: WYSIWYG editing and robust bi-directional sync rules.