Wordgard

Wordgard

Wordgard (https://wordgard.net, by Marijn Haverbeke) is a semantic rich text editor system — spiritually ProseMirror v2 with CodeMirror 6's extension architecture. It was released in 2026-07 and is not in model training data: never guess its API from ProseMirror or CodeMirror memory.

Before writing any Wordgard code

1. Read references/guide.md (the system guide — the authoritative mental model).
2. Coming from a ProseMirror mindset, read references/migrating-from-prosemirror.md.
3. For exact signatures, read the installed typings: node_modules/wordgard/dist/*.d.ts (doc, types, schema, table, state, editor, command, history, collab, phrases). These have full doc comments and are the API reference. Grep them; do not invent methods.
4. references/examples/*.md show working end-to-end code (schema definition, transactions, dynamic config, styling, translations).

See references/ATTRIBUTION.md for provenance; refresh copies on version bumps and read references/CHANGELOG.md when upgrading — Wordgard is 0.x and breaks compatibility deliberately.

Concept model (30 seconds)

• Document = immutable tree of plots (nodes with content) and leaves (no content; text is a leaf whose param is the string). A node's markup = its tag: {type, param, marks}. One param value replaces PM's attrs; optional/extra attributes are modeled as marks (e.g. image src is the leaf param, alt text is a mark).
• Nodes are value objects: no parent pointers, no identity, no mutation. Refer to positions by document offset; resolve with doc.resolve(pos) (Pos), map across changes with ChangeSet.mapPos.
• Changes are ChangeSets (delta over the old doc). Multiple changes in one spec are all addressed in original coordinates — no offset compensation. Insertions are token arrays (nodes, plot tags to open, Plot.End to close). Use fit/{correct: ...} when validity is unsure.
• Transactions are immutable, created from a spec object ({changes, selection, userEvent, scrollIntoView, effects}); metadata is annotations, state-directed payloads are effects (mappable). wg.dispatch(spec); new state at tr.state.
• Configuration is a tree of extensions with precedence (prec). Extension points are facets; persistent extension state lives in state fields (reducer over transactions); DOM-integrated behavior is a Wordgard.Plugin; runtime feature toggling uses compartments.
• Schemas compose from reusable elements (Plot.define, Plot.Type.define<P>, Leaf.Type.define<P>, Mark.define, Mark.Type.define<P>, Schema.Override). Content rules are deliberately loose (allowed-set + may-be-empty); richer invariants belong in corrections (Correction.onChildList/onContent/onMarks), not the schema.
• Commands are (editor, param?) => boolean | TransactionSpec, and act as identities that extensions can override via Command.handler by precedence. Key bindings and input rules are extension values themselves.
• Rendering: DOM shapes via Elt; decorations are tag-level (all nodes of a type — this replaces NodeViews), point (widget/attributes/shape override/wrapper at a position), or range (attributes/wrapper over a span), sourced from facets, stored in PointSet/RangeSet and mapped in state fields. Styling via Wordgard.styles/Wordgard.theme (CSS-in-JS, &dark/&light).
• DOM updates flush on requestAnimationFrame. Dispatch one coherent transaction, not a loop of small ones. In plugins, use scheduleDOMRead/scheduleDOMWrite.