Invert the product.
HTML Docs is currently excellent at preserving an HTML artifact and increasingly capable at editing around it. The next version should instead make editing the canonical activity and treat HTML as one compiled output.
Imported pages retain their own styles, layout, scripts, and web-native richness.
The shell, region strings, live DOM, database, history, and agent edits must be reconciled.
A dependable editor, controllable agents, and rich output all operate on the same structure.
The wager is that users do not need to choose between “Google Docs familiarity” and “the expressive range of HTML.” They need a stable document model, a visible design system, and rich blocks that expose direct manipulation rather than raw implementation details.
Paper’s lesson is shared language.
Paper is useful inspiration because its human canvas and its agents speak the same web-native language. The transferable idea is not an infinite canvas; it is eliminating the translation layer between what a person edits and what an agent changes.
- 01 Direct manipulation and AI are complements.The canvas lets a person explore and judge; the agent removes repetition and carries changes across variants. Paper explicitly describes these as two sides of the same workflow. PAPER-08
- 02 The design system is an editable product surface.Tokens and reusable styles make “beautiful” reproducible. They also constrain the agent enough to preserve intent. PAPER-05
- 03 Agent context should come from selection.Paper’s build log describes teammate and agent presence and selection-aware context. HTML Docs should apply the same principle to document sections and blocks. PAPER-06
- 04 The human remains the editor.Paper’s own framing is that the agent saves clicks while the person retains style and intention. That is the correct control model for HTML Docs. PAPER-07
The product already contains half the answer.
The repository has block insertion, movement, conversion, slash commands, a Google Docs-like toolbar, structural undo, collaborative region syncing, and agent proposal cards. The problem is not a lack of features. It is that those features operate across multiple competing representations.
What is strong
- The Shadow DOM renderer preserves imported-page fidelity and isolates styles. LOCAL-01
- The mutation engine already expresses useful block commands: insert, move, split, merge, convert, indent, and delete. LOCAL-03
- Docsmith proposals are explicitly accepted or rejected; user control is already a product value. LOCAL-05
- The desktop app already includes a Codex adapter and streams externally authored file changes into the editor. LOCAL-07 LOCAL-09
What creates drag
- A character edit lives in native contenteditable history, while a structural edit lives in a separate snapshot history.
- Shell edits can rebuild the Shadow DOM, so caret and selection must be captured and restored.
- Remote patches need active-region, recent-edit, selection, and IME guards to avoid overwriting local intent.
- Formatting and focus depend on DOM selection timing and legacy browser commands; the existing editor-options investigation documents recurring failure modes. LOCAL-11
Root cause: imported HTML is both the thing being preserved and the substrate being edited. This makes every direct-editing affordance a negotiation with arbitrary DOM, CSS, and script behavior. The current implementation handles that complexity thoughtfully; the volume of defensive logic is itself evidence that the abstraction boundary is wrong for an editing-first product.
Familiar in ten seconds. Powerful on demand.
A blank document should require no explanation: click, type, select, format, paste, undo, comment, and share. The superpower appears only when the user asks for structure, design, data, or an agent.
A typed metric block: editable as content, styled as a component, exportable as semantic HTML.
Paragraphs, headings, lists, links, comments, tables, images, keyboard shortcuts, paste, and unified undo.
Slash menu, block handles, outline, drag/reorder, columns, callouts, cards, sections, and reusable patterns.
Document themes, tokens, style presets, responsive preview, and a contextual inspector for selected rich blocks.
Selection-aware Codex actions, inspectable diffs, scoped acceptance, agent history, and reusable document skills.
Rich HTML without raw-HTML anxiety
D3 and other web libraries belong behind typed blocks, not inside the text flow. A chart block should store a dataset, visualization specification, theme references, and accessibility text. D3 may render it, while the editor exposes a data table and contextual controls. The same principle applies to diagrams, tab groups, metric grids, embeds, and interactive explainers.
Separate content, design, rendering, and action.
The structured document should be small enough to reason about and rich enough to compile. It should never require an agent—or a toolbar button—to patch arbitrary DOM as its primary operation.
| Layer | Owns | Does not own |
|---|---|---|
| DocumentGraph | Stable node IDs, block hierarchy, text, marks, semantic attributes, references | Browser DOM, transient selection UI, generated CSS |
| DesignSystem | Color, typography, spacing, radius, breakpoints, component recipes, theme variants | One-off inline styling hidden from the user |
| Transaction engine | Validated commands, preconditions, inverse operations, attribution, version boundaries | Special “AI edit” code paths |
| Renderers | Editing DOM, published HTML/CSS/JS, responsive previews, export formats | Canonical document state |
| Rich-block plugins | Typed props, editor node view, output renderer, migrations, accessibility contract | Unbounded access to the editor runtime |
A rawHtml block remains essential as an isolated escape hatch for advanced imports and bespoke elements. It should have source/preview modes, explicit security boundaries, and limited interaction with surrounding rich text. It is a feature—not the foundation.
Codex should propose transactions, not rewrite pages.
The user controls scope and judgment. The agent receives structured context, uses the document’s design system by default, and returns small, attributable operations that can be previewed and reversed.
"baseVersion": "doc_v184",
"scope": { "sectionId": "sec_launch" },
"operations": [
{ "type": "replaceText", "nodeId": "p_42", "from": 18, "to": 41, "text": "time to first publish" },
{ "type": "insertNode", "after": "p_42", "node": { "type": "sourceNote" } }
],
"explanation": "Narrows the metric and attaches its cohort source."
} // illustrative API, not a committed schema
- 01 Scope is explicit.Default to the selection, current block, or current section. Expanding to the whole document requires a visible user choice.
- 02 Diffs render on the document.Text changes appear inline; block and design changes show before/after previews. Raw HTML is not the primary review surface.
- 03 Acceptance is granular.Accept one operation, one block, one section, or all. Reject and “revise this” stay beside the proposal.
- 04 Everything is reversible and attributable.Agent operations participate in the same undo and version history as human edits, with author, prompt, and rationale metadata.
- 05 Skills target the model.A “launch brief” skill produces structured nodes and design tokens. It does not emit an opaque page that the editor must reverse-engineer.
Docsmith’s existing accept/reject cards are the right control primitive, while the desktop Codex adapter is the right transport primitive. The missing layer is a common transaction protocol between them. Today, web proposals replace region HTML or insert blocks, while desktop agents can edit the backing HTML file. Both should converge on model commands. LOCAL-06 LOCAL-08
Time-box the editor engine; commit to the transaction boundary.
The strategic decision is the structured, transactional model—not a library logo. Run a two-week spike comparing ProseMirror and Lexical against HTML Docs’ hardest requirements, with a provisional lean toward ProseMirror.
Why ProseMirror leads
Its official model centers on schemas, immutable editor state, transactions, selection state, transforms, history, collaboration, and custom node views. Those primitives map directly to HTML Docs’ need for one write path and typed rich blocks. ARCH-01
Why Lexical stays in the spike
Lexical also offers immutable state, command-driven updates, React integration, history, and Yjs collaboration support. Its ergonomics and performance may be attractive, so it should be tested rather than dismissed. ARCH-03
Spike acceptance tests
- IME composition, multi-block selection, paste from Google Docs/Word/web, tables, mobile selection, and screen-reader semantics.
- Unified undo across text, structure, token, and agent transactions.
- Custom node views for chart, columns, callout, image, raw HTML, and interactive embeds.
- Concurrent edits and offline recovery with a Yjs-backed prototype; Yjs provides shared CRDT types, provider separation, awareness, and editor bindings. ARCH-02
- Deterministic standalone HTML export and round-trip stability for the structured schema.
Compatibility strategy
Add an explicit document mode: legacy_html or structured. Existing public documents remain on the current renderer. New documents default to structured. Import conversion produces a preview and confidence report; unsupported structures become typed raw blocks rather than silently degrading. No dual-write bridge should become permanent.
Prove the inversion with new documents.
Do not begin by migrating every page HTML Docs has ever imported. Begin with a coherent authoring loop that demonstrates writing quality, design richness, and agent control in one surface.
| Include | Concrete boundary | Defer |
|---|---|---|
| Core writing | Paragraph, H1–H3, lists, todo, quote, code, divider, link, comment, table, image | Arbitrary nested DOM conversion |
| Rich blocks | Callout, columns, metric grid, chart, diagram, embed | General-purpose page builder |
| Design | Document theme, semantic tokens, presets, responsive preview | Every CSS property |
| Agent | Selection/section scope, transaction diff, accept/reject/revise, undo | Silent autonomous full-doc rewrite |
| Output | Deterministic, semantic, responsive standalone HTML | Lossless import/export of every third-party script |
This wedge uses assets HTML Docs already has: the block command vocabulary, familiar toolbar work, Docsmith review model, export/presentation capability, shared editor package, and desktop agent transports. The investment goes into unifying them, not recreating them.
Build the foundation in visible slices.
Measure and spike
Instrument current text-loss, caret-jump, undo, paste, and collaboration failures. Compare ProseMirror and Lexical using the acceptance matrix. Draft DocumentGraph, transaction, and plugin contracts.
Structured writing alpha
New-document mode, core blocks, reliable paste, one history, comments, basic collaboration, themes/tokens, and deterministic HTML export. Keep it behind a workspace flag.
Shared agent protocol
Define MCP/desktop tools around transactions. Connect Docsmith and Claude/Codex adapters. Ship selection scope, on-canvas diffs, partial acceptance, attribution, and undo.
Rich-document system
Columns, metric grids, chart, diagram, responsive inspector, component recipes, workspace design systems, and skills that emit model-native structures.
Import and migration
Conversion audit, side-by-side preview, raw-block fallback, opt-in legacy migration, and lifecycle policy for the old editor. Preserve existing published URLs throughout.
Judge the editor before judging the magic.
The targets below are proposed product gates, not measured current performance. Baselines should be captured during Phase 0.
Automated matrix covers typing, IME, paste, format, undo, remote edits, and reconnect. Track lost-character and caret-jump telemetry separately.
Measure local keypress-to-paint for representative 100-, 1,000-, and 5,000-block documents.
First-time users create, format, comment, and publish without AI assistance or facilitator instruction.
Every agent mutation names its scope, exposes a review state, records attribution, and supplies an inverse operation.
Rich-block styling uses named document/workspace tokens rather than unique values. Track overrides as visible exceptions.
Published HTML matches approved responsive snapshots and meets accessibility checks for all first-party blocks.
The danger is building three products at once.
Approve the boundary, then prove it.
- D1 Approve a second document mode.New structured documents can evolve without destabilizing legacy HTML documents.
- D2 Approve one transaction path for humans and agents.This is the non-negotiable architectural seam.
- D3 Fund the two-week editor-engine spike.Use the same hard acceptance matrix for ProseMirror and Lexical; choose on evidence.
- D4 Choose the wedge narrative.“Write normally → add a rich block → delegate a selected change → publish beautiful HTML.”
- D5 Protect existing documents.No forced migration until structured mode proves editing integrity, export fidelity, and collaborative reliability.
HTML Docs should feel like the document editor people already know—until they ask it to become something ordinary document editors cannot make.