@stesura/react-wordgard 0.0.0-stage → 0.1.0

package/skills/react-wordgard/SKILL.md

@@ -0,0 +1,397 @@
+---
+name: react-wordgard
+description: Build rich text editors with Wordgard and react-wordgard in a React app. Use when creating or changing a Wordgard editor drawn by React - hosting it, drawing nodes, marks, wrappers or widgets as React components, reading the editor's state in components, positioning menus and popovers, handling the editor's events, or migrating react-prosemirror node views.
+---
+
+# Building editors with Wordgard and react-wordgard
+
+react-wordgard is a React view for [Wordgard](https://wordgard.net/docs/), a rich text editor.
+Wordgard runs the editor (document, state, input, selection, IME composition, decorations,
+commands); react-wordgard has React draw its document, inside Wordgard's own update, in the app's
+React tree, so the app's contexts reach what it draws. **The API is Wordgard's**: a customisation
+is a Wordgard extension or decoration, and react-wordgard adds functions that let a React
+component be the decoration.
+
+Wordgard's own API: its docs (https://wordgard.net/docs/) and its typings in
+`node_modules/wordgard/dist/*.d.ts` (`wordgard/editor`, `wordgard/state`, `wordgard/doc`,
+`wordgard/schema`, `wordgard/types`, `wordgard/command`). react-wordgard's: its README and
+`node_modules/@stesura/react-wordgard/dist/index.d.ts`. Read them rather than guessing a signature.
+
+**New to Wordgard, or porting ProseMirror code?** Read `references/wordgard.md`, next to this file:
+Wordgard's model (plots, leaves, tags, marks on tags), changes, configuration, commands and the
+editor, each against its ProseMirror counterpart, with the traps.
+
+## Setup
+
+```sh
+npm install @stesura/react-wordgard wordgard react react-dom
+```
+
+- Peers: `wordgard` `~0.6.2` (react-wordgard uses its internals: only its patches), React 18 or 19.
+  The app must have **one copy** of `wordgard`, or Wordgard's `instanceof` checks fail.
+- TypeScript: Wordgard's typings need `skipLibCheck: true`.
+- Name the editor for screen readers with `Wordgard.contentAttributes.of({ "aria-label": "…" })`
+  in the config (`Wordgard.label` names the wrong element in 0.6.2).
+
+## Hosting the editor
+
+```tsx
+import { WordgardDoc, WordgardEditor } from "@stesura/react-wordgard";
+import { basicSchema } from "wordgard/schema";
+
+export const Editor = () => (
+  <WordgardEditor doc="<p>Hello</p>" config={[basicSchema()]}>
+    <WordgardDoc className="editor" />
+  </WordgardEditor>
+);
+```
+
+- `WordgardEditor` takes a `Wordgard.Spec` (`doc` as HTML, `config` as extensions, or a `state`),
+  **read once**: the editor is uncontrolled and owns its state. Change the document through
+  `wg.dispatch(…)`, the configuration through Wordgard's compartments or
+  `GardState.appendConfig`, never by re-rendering with new props.
+- `WordgardDoc` puts the editor in the page; one per editor. Components inside `WordgardEditor`
+  (toolbars, menus, sidebars, next to `WordgardDoc`) can use the hooks: below.
+- Don't create editors with `Wordgard.create` for a React app: react-wordgard's editor is made by
+  `WordgardEditor`. In StrictMode (development) it creates the editor twice and drops one, which is
+  never put in the page.
+
+## Reading and changing the editor from components
+
+```tsx
+import { Command, toggleStrong } from "wordgard/command";
+import { useEditorEventCallback, useEditorStateSelector } from "@stesura/react-wordgard";
+
+const Toolbar = () => {
+  const empty = useEditorStateSelector((state) => state.selection.empty);
+  const bold = useEditorEventCallback((wg) => Command.dispatch(wg, toggleStrong));
+  return (
+    <button
+      onMouseDown={(e) => {
+        e.preventDefault();
+        bold();
+      }}
+    >
+      Bold
+    </button>
+  );
+};
+```
+
+- `useWordgard()`: the editor (`wg`).
+- `useEditorState()`, `useEditorStateSelector(selector, isEqual?)`: the state as of the editor's
+  last update (the one the DOM shows). Prefer the selector: the component re-renders only when its
+  result changes (`Object.is`, or `isEqual`).
+- `useEditorEventCallback((wg, ...args) => …)`: a stable callback getting the editor, for event
+  handlers. Commands run through `Command.dispatch(wg, command, param?)`; plain changes through
+  `wg.dispatch({ changes: { from, to, insert }, selection })`.
+- `useEditorEventListener(type, (wg, event) => handled)`: the editor's DOM events of `type`, before
+  Wordgard's handlers and keymaps; return `true` to handle the event (Wordgard then calls
+  `preventDefault`). Types: `keydown`, `keyup`, `keypress`, `beforeinput`, `input`, composition
+  events, `mousedown`, `mouseup`, `mouseover`, `mouseout`, `click`, `dblclick`, `contextmenu`,
+  `focus`, `blur`, `copy`, `cut`, `paste`, drag-and-drop events. Key events during an IME
+  composition don't come. Handling `input`, `beforeinput` or a composition event skips Wordgard's
+  own handling of it: leave typing to Wordgard.
+
+### Effects and layout
+
+Wordgard drives the update and React draws inside it, so there are two effect hooks:
+
+| Hook                                                                      | Runs                                                                             | May dispatch             | What it sets shows | For                                                  |
+| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------ | ------------------ | ---------------------------------------------------- |
+| `useEditorEffect((wg) => cleanup?, deps)`                                 | after the editor's update                                                        | yes                      | a frame later      | focusing, follow-up dispatches, menus                |
+| `useEditorLayoutEffect({ read: (wg) => value, write: (value, wg) => … })` | inside every update: `read` in Wordgard's read phase, `write` in its write phase | **no** (Wordgard throws) | on the same paint  | what moves with the text: margin markers, pagination |
+
+- **Never read the editor's layout (`coordsAtPos`, `posAtCoords`) in a plain React `useEffect` or
+  `useLayoutEffect`**: it runs inside Wordgard's update, before the view of the new DOM exists, and
+  react-wordgard refuses the update. Use one of the two hooks above.
+- `useEditorLayoutEffect`'s `read` runs on every update: return `undefined` when nothing changed,
+  which skips the write and, when no read asks for one, Wordgard's second measure. Reads run in
+  registration order; an engine with ordered parts (pagination) registers one effect and drives
+  them.
+- Menus and popovers: position them with your popover library (Floating UI, Radix, Base UI) from a
+  virtual anchor built from `wg.coordsAtPos(pos)` in `useEditorEffect`; show or hide them from
+  `useEditorStateSelector`. Wordgard's own tooltips and panels also work, as plain DOM.
+
+## Drawing parts of the document with React
+
+Prefer Wordgard's declarative shapes (`Elt` shapes, `Decoration.Tag.attribute`, mark shapes) for
+anything that needs no code: React draws them all already. Use a React component where a part needs
+state, interaction or the app's contexts. Each factory below is **called at module level**, with a
+component defined there, and returns a Wordgard value you pass in `config`. `createShape`,
+`createWrapper` and `createMarkShape` return the same value for the same component, so composing
+the config again (per editor) is safe; a component created inside a render is new each time. The
+components need no memoizing: React draws a node again only when it changed, or from the
+component's own state, contexts and hooks.
+
+| Need                                                         | Factory                                   | Passed to                                                                             |
+| ------------------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------- |
+| A node, with content or an atom (callout, image, mention)    | `createShape(component)`                  | `Decoration.Tag.shape(Type, shape)`; `shape.of(element, { atom? })` for `Point.shape` |
+| An element around a node or part of its shape                | `createWrapper(component, { element })`   | `Decoration.Tag.wrapper(Type, wrapper, { target? })`, `Decoration.Point.wrapper`      |
+| A mark's element (link, comment highlight)                   | `createMarkShape(component, { element })` | `Decoration.Mark.shape(MarkType, shape)`                                              |
+| A widget at a position or beside a node (placeholder, badge) | `createWidgetType({ component, … })`      | `Decoration.Point.widget(MyType.of(value), { side })`, `Decoration.Tag.widget`        |
+
+```tsx
+import { Decoration } from "wordgard/editor";
+import { basicSchema, blockquote, image } from "wordgard/schema";
+import { Blockquote, Image, Link } from "wordgard/types";
+import { DecorationRoot, createMarkShape, createShape } from "@stesura/react-wordgard";
+
+const CalloutShape = createShape(function Callout({ nodeProps: { contentDOMRef }, children }) {
+  return (
+    <DecorationRoot>
+      <span aria-hidden="true">!</span>
+      <div ref={contentDOMRef}>{children}</div>
+    </DecorationRoot>
+  );
+});
+
+const LinkMark = createMarkShape(
+  function LinkMark({ markProps: { mark, contentDOMRef }, children }) {
+    return (
+      <DecorationRoot href={String(mark.value)}>
+        <span ref={contentDOMRef}>{children}</span>
+      </DecorationRoot>
+    );
+  },
+  { element: "a" }
+);
+
+// An atom: no content, everything it draws is chrome.
+const PictureShape = createShape(function Picture() {
+  return <DecorationRoot />;
+});
+
+export const config = [
+  basicSchema(),
+  blockquote(),
+  image(),
+  Decoration.Tag.shape(Blockquote, CalloutShape),
+  Decoration.Mark.shape(Link, LinkMark),
+  Decoration.Tag.shape(Image, PictureShape),
+];
+```
+
+An image's `src` is its type's own attribute and its `alt` the `ImageAlt` mark's: `DecorationRoot`
+puts both on the `<img>`. Check the parameter types of the node and mark types you use in
+`wordgard/types`.
+
+### The component's contract
+
+- **The root is the element the decoration says, and stays that element.** For a shape, that's
+  the node type's own outer element, per node (`h1` to `h6` for a heading); for `.of`,
+  `createWrapper` and `createMarkShape`, their `element` (`div` for wrappers, `span` for marks, by
+  default). Wordgard applies decorations to the shape before React draws (`target` selectors
+  match its tag), so the tag can't come from the component. Re-render freely, but don't swap the
+  root for another element.
+- **Draw it with `<DecorationRoot>`**, once, at the component's root. It renders that tag with
+  Wordgard's attributes (the node type's own, the selection classes `wg-selected-node` and
+  `wg-selected-cell`, tag, point and mark attributes, `contenteditable` on an atom) and the root's
+  ref. Its own props win, except `className`, joined with Wordgard's, and `style`, merged (its
+  keys winning); its `ref` gets the root too. It works on React 18 and 19 without `forwardRef`.
+  Widgets use it too (see "React widgets").
+- **Or draw the root by hand**, for more control over the decoration's attributes (drop or change
+  one, type the root as its element): the element the decoration says, `{...props}` (Wordgard's
+  attributes) and `ref` (`forwardRef` on React 18), never both ways at once. Join your classes with
+  `className` (Wordgard's, the selection's among them), and spread your style over `style`
+  (Wordgard's, as an object):
+
+  ```tsx
+  const ImageShape = createShape(
+    forwardRef<HTMLImageElement, ShapeComponentProps<HTMLImageElement>>(function ImageShape(
+      { nodeProps, children, className, style, ...props },
+      ref
+    ) {
+      return (
+        <img
+          {...props}
+          ref={ref}
+          className={["picture", className].join(" ").trim()}
+          style={{ ...style, outline: "1px solid" }}
+        />
+      );
+    })
+  );
+  ```
+
+- **Only the outer element comes from the node type.** The elements inside a structure shape (a
+  figure's `img`) are the component's to draw, from `nodeProps.node`; attributes aimed at them
+  arrive on the root (see "A shape, a wrapper, or both").
+- **Content goes where `contentDOMRef` points**, else in the root. `children` is the content (a
+  wrapper's `children` is what it wraps; no `contentDOMRef` there).
+- **An atom** (a leaf, or a plot whose shape has no hole) has no content: `children` is empty,
+  and a `contentDOMRef` throws. `.of(element, { atom: true })` has no hole: a leaf needs it (for
+  `Decoration.Point.shape` before a leaf), and it draws a plot as an atom.
+- Everything else the component draws is **chrome**: made uneditable, never read as document
+  content, free to change from the component's state, a context or a store.
+  - In a textblock (a paragraph-like node) or a mark, the content element holds only the content.
+    Chrome beside a textblock's text (line numbers) is a React widget at its `"start"` or `"end"`:
+    `Decoration.Tag.widget(Paragraph, "start", LineNumber.of(null))` (see "React widgets").
+  - In a node holding blocks, chrome may sit before or after the content in its element, not
+    between the content's nodes.
+  - Moving `{children}` under another element remounts the content (a selection or IME
+    composition in it ends).
+- Node parameters: `nodeProps.node.tag.param` for a node with content, `node.param` for a leaf;
+  `markProps.mark` is the document's mark (`mark.value`).
+- `createWrapper` can't wrap a node a native widget draws (draw it with a React shape or widget), nor text.
+- **Don't write attributes on document elements by hand.** On a React decoration's root they
+  survive only until React sets that attribute (a `classList.add` is lost when the selection
+  changes `className`); on elements Wordgard draws they're undone at the next update. Put the
+  state in the component (`data-resizing={resizing}`), or in a decoration from a state field.
+
+### React widgets
+
+```tsx
+import { Decoration } from "wordgard/editor";
+import { Paragraph } from "wordgard/types";
+import {
+  DecorationRoot,
+  type WidgetComponentProps,
+  createWidgetType,
+} from "@stesura/react-wordgard";
+
+// The root is a DecorationRoot, a <span> unless the spec gives an `element`.
+const Badge = createWidgetType({
+  component: function Badge({ value }: WidgetComponentProps<string>) {
+    return (
+      <DecorationRoot className="badge" aria-hidden="true">
+        {value}
+      </DecorationRoot>
+    );
+  },
+});
+
+export const badges = [
+  Decoration.Tag.widget(Paragraph, "start", Badge.of("¶")),
+  Decoration.Point.source.of(() =>
+    Decoration.Point.set([[Decoration.Point.widget(Badge.of("!")), 1]])
+  ),
+];
+```
+
+- `createWidgetType({ component, element?, eq?, editable?, inFlow?, propagateEvent?, connect?,
+disconnect? })` returns a real `Widget.Type`: its widgets are `Type.of(value)`. The component
+  gets `value`.
+- **Draw its root with `<DecorationRoot>`**: `element` (`span` by default), the ref, and the
+  node's attributes for a widget drawing a node. Or by hand: any element, with the `ref` the
+  component gets (`forwardRef` on React 18), which it **must** put on its root.
+- Widgets are uneditable unless their spec sets `editable`, as in Wordgard. A React widget
+  re-renders freely while it keeps its root element.
+- A widget drawing a node (`Decoration.Tag.shape(Type, (tag) => W.of(tag.param))`):
+  `DecorationRoot` puts the node's attributes on its root; a root drawn by hand gets them as
+  props, to spread. A React shape is the usual way to draw a node.
+- A widget's component may read a context a React shape around it provides (line numbers beside a
+  paragraph's text, from the paragraph's shape).
+
+### A shape, a wrapper, or both
+
+- The node type's shape decides where attributes go (`target`, `preferTarget`: `ImageAlt` and
+  `ImageSize` land on a figure's `img`). Don't replace a shape just to add chrome.
+- React chrome around a node, or an element in its shape, is a **wrapper**:
+  `Decoration.Tag.wrapper(Figure, createWrapper(Frame), { target: "img" })`. The `img` keeps its
+  `src`, `alt` and width; `Frame` draws a resize handle beside `{children}`.
+- A shape and wrappers on the same type apply to all its nodes. A table: a React shape drawing
+  `table > tbody > {children}`, plus a wrapper for a scroll container around it.
+- **One `Decoration.Tag.shape` per node type** draws it: where several features draw the same type
+  (react-prosemirror apps merging node views), fold their components into one in the app's code
+  and register that, or give each feature a wrapper or a tag widget of its own.
+- Porting a react-prosemirror node view that draws chrome around the node's own element: keep the
+  type's shape (or a React shape for the element), and move the chrome into a wrapper.
+
+### Changing a node without remounting it
+
+A component keeps its state while its node changes in place or moves within its parent; it
+remounts, with everything inside, when the node is replaced whole, changes type or moves to another
+parent.
+
+- **Data an action changes in place** (size, alignment, a callout's kind, a table's widths): a mark
+  on the tag, `Mark.Type.define(name, { target: NodeType, … })`, read with
+  `node.tag.mark(Type)`, changed with `wg.dispatch({ changes: { from: pos, add: Type.of(v) } })`
+  or `{ from: pos, remove: Type.of(v) }`. It merges in collaboration and inverts in history.
+- **What identifies the node** (an image's `src`, a heading's level): its parameter, changed by
+  retagging the opening token, `{ from: pos, to: pos + 1, insert: [Heading.of(2)] }`.
+- **Never** replace the whole node (`{ from, to, insert: [node] }`) to change its data: that
+  remounts the component.
+- ProseMirror's `setNodeAttribute` / `setNodeMarkup` port to one of the first two.
+- **Moving a node**: delete it and insert the same node object elsewhere in the same parent, in one
+  transaction (`changes: [{ from, to: from + node.length }, { from: target, insert: [node] }]`).
+  A copy (a new object, or one inserted while the original stays) mounts anew. React moves the
+  DOM, so an `<iframe>` in a moved node reloads. Wordgard's drag-and-drop rebuilds what it drops
+  from HTML: those moves remount.
+
+### Hooks inside React decorations
+
+- `useNodePos()`: a function returning the position of what the decoration draws (call it in
+  handlers and effects, not during render).
+- `useIsNodeSelected()`, `useSelectNode(select, deselect?)`: the node selection.
+- `useStopEvent((wg, event) => stop)`: asked for events in the decoration's chrome (inputs,
+  buttons in a title bar), on its own elements (its root and the elements around its content
+  element: an atom's root, a frame's padding; not a root that is itself the content element) and
+  in React widgets. Never for events in the content, unlike react-prosemirror. For an event it
+  stops, Wordgard's handlers and keymaps are skipped and the browser's default goes ahead.
+- `useIgnoreMutation((wg, record) => ignore)`: Wordgard doesn't read the DOM mutations it claims
+  (typing aside: Wordgard takes it from `beforeinput`).
+- `useMergedDOMRefs(...refs)`: one ref setting several (the forwarded `ref` and `contentDOMRef`
+  on one element, a measuring ref).
+
+## Accessibility
+
+- The editable element has `role="textbox"` and `aria-multiline`; give it a name (Setup).
+- Chrome is read inline with the document's text: `aria-hidden` on decorative parts, a name on
+  every control, controls focusable and wrapped in `useStopEvent` so Wordgard leaves their keys.
+
+## Migrating react-prosemirror node views
+
+| react-prosemirror                                                              | react-wordgard                                                                   |
+| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| `<ProseMirror state dispatchTransaction>`                                      | `<WordgardEditor doc config>`, uncontrolled; changes via `wg.dispatch`           |
+| `<ProseMirrorDoc />`                                                           | `<WordgardDoc />`                                                                |
+| `nodeViews`                                                                    | `Decoration.Tag.shape(Type, createShape(component))` in `config`, atoms included |
+| `markViews`                                                                    | `createMarkShape` with `Decoration.Mark.shape`                                   |
+| `NodeViewComponentProps`                                                       | `ShapeComponentProps` (same `nodeProps`, `contentDOMRef`, `children`, `ref`)     |
+| `node.attrs`                                                                   | `node.tag.param` for identity, `node.tag.mark(Type)` for data changed in place   |
+| `view` in callbacks                                                            | `wg`                                                                             |
+| `ProseMirror-selectednode`, `selectedCell`                                     | `wg-selected-node`, `wg-selected-cell`                                           |
+| `useNodePos()` returning a number                                              | `useNodePos()` returning a function                                              |
+| `useEditorEffect` for same-paint layout                                        | `useEditorLayoutEffect`                                                          |
+| `useStopEvent`, `useIgnoreMutation`, `useSelectNode`, `useEditorEventListener` | the same names, the editor first in callbacks                                    |
+| `useIsNodeSelected`, `useMergedDOMRefs`                                        | the same                                                                         |
+| `innerDecorations`, `useIsComposingIn`, `useIsEditorStatic`                    | none                                                                             |
+
+ProseMirror's model maps to Wordgard's in its migration guide:
+https://wordgard.net/docs/prosemirror/
+
+## When something fails
+
+- "…must draw a DecorationRoot, or forward its ref to its root element": the component's root is
+  neither a `DecorationRoot` nor given `ref` (on React 18, a hand-written root needs `forwardRef`).
+- "…drew <x> where its shape says <y>": draw the element the shape says (the node type's, or
+  `element`), or pass the drawn one to the shape's `of`.
+- "React's DOM has extra nodes" or "…chrome is between its content's nodes": chrome sits in a
+  content element where it can't (see the contract).
+- "A React widget's component must forward its ref to its root element": a widget drawing its
+  root by hand needs `forwardRef` (React 18) and `ref` on its root; or use `DecorationRoot`.
+- "DecorationRoot is the root of a React shape, wrapper, mark or widget: use it in their
+  component": a `DecorationRoot` outside those components (in a toolbar, say).
+- "A React wrapper's component must draw its children": a wrapper drew nothing where it wraps.
+- "A React shape drawing an atom has no content: drop its contentDOMRef": the node type draws an
+  atom (a leaf, a plot without a hole), so its React shape has no content element.
+- "A React shape can't wrap: use createWrapper", "A React wrapper isn't a shape: use createShape":
+  a factory's value went to the other decoration.
+- "…is called outside a React shape, wrapper, mark or widget": a decoration hook (`useNodePos`,
+  `useStopEvent`, `useIgnoreMutation`, `useSelectNode`, `useIsNodeSelected`) used elsewhere.
+  "Used outside a Wordgard editor": an editor hook outside `WordgardEditor`.
+- "This React shape or wrapper isn't drawn" (or widget, or mark): `useNodePos()`'s function called
+  during render or after unmount; call it in handlers and effects.
+- "Leaf nodes shapes shouldn't have a content hole": a React shape's `.of(element)` given to a
+  leaf; use `.of(element, { atom: true })`.
+- "A React wrapper can't wrap a native widget: draw … with a React widget", "A React wrapper
+  can't wrap text": a wrapper around a node a native widget draws, or around text.
+- "This editor is already rendered by another WordgardDoc": one `WordgardDoc` per editor.
+- "react-wordgard can't render part of …", "…can't render the shape of … yet": a shape or
+  decoration react-wordgard doesn't draw yet; the message names the node type.
+- "ReactWordgard can't update while React renders or commits": layout was read from a plain React
+  effect; use `useEditorEffect` or `useEditorLayoutEffect`.
+- "Cannot dispatch new updates during the editor flush phase": a dispatch from
+  `useEditorLayoutEffect` or a render; dispatch from an event handler or `useEditorEffect`.
+- Two copies of `wordgard` (`npm ls wordgard`) break `instanceof` checks in odd places.

package/skills/react-wordgard/references/wordgard.md

@@ -0,0 +1,189 @@
+# Wordgard, for ProseMirror developers
+
+Read this when you're new to Wordgard or porting ProseMirror code (react-prosemirror apps
+included). It covers the model and the traps; for exact signatures, read the typings in
+`node_modules/wordgard/dist/*.d.ts`, whose doc comments are Wordgard's reference manual. Wordgard's
+own guides: https://wordgard.net/docs/guide/ and, for ProseMirror users,
+https://wordgard.net/docs/prosemirror/. Written for Wordgard 0.6.
+
+## Modules
+
+One package, `wordgard`, in submodules:
+
+| Wordgard           | Replaces                                                                            |
+| ------------------ | ----------------------------------------------------------------------------------- |
+| `wordgard/doc`     | `prosemirror-model`, `prosemirror-transform`                                        |
+| `wordgard/state`   | `prosemirror-state`                                                                 |
+| `wordgard/editor`  | `prosemirror-view`, `prosemirror-keymap`, `prosemirror-menu`, input rules           |
+| `wordgard/command` | `prosemirror-commands`                                                              |
+| `wordgard/history` | `prosemirror-history`                                                               |
+| `wordgard/collab`  | `prosemirror-collab`                                                                |
+| `wordgard/types`   | `prosemirror-schema-basic`, `prosemirror-schema-list`: the node and mark types      |
+| `wordgard/schema`  | extensions adding those types with their commands, keys and menus (`basicSchema()`) |
+
+## The document
+
+- **A node is a plot or a leaf.** A `Plot` has content (`plot.content`, an array); a `Leaf` has
+  none. Text is a leaf (`Leaf.Text`, its parameter the string), and so is a line break.
+- **A tag is a node's type, parameter and marks.** A leaf is its own tag; a plot has one
+  (`plot.tag`). Read a parameter as `plot.tag.param` or `leaf.param`, a mark as
+  `node.tag.mark(Type)` (the value, or `undefined`).
+- **One parameter, no `attrs`.** What identifies a node (a heading's level, an image's `src`) is
+  its parameter. Anything else (alignment, size, a callout's kind) is a mark on its tag: a mark
+  type with a `target`, added or removed without touching the node.
+- **Marks live on tags**, a plot's as a leaf's, and a mark type says which nodes it may go on
+  (`target`), not the parent which content it allows.
+- **No content expressions.** A plot type says what it holds (`blockContent: Node.Group.Content`,
+  or `inlineContent: true`); finer rules go above the document (corrections, `wordgard/state`).
+- **Positions count as in ProseMirror**: a character or leaf is 1, a plot 2 plus its content.
+  `node.length` is ProseMirror's `nodeSize`; the document's excludes its own tokens.
+- **Walking it:** `doc.iterate(from, to, (node, pos, parent, index) => …)` for `descendants` and
+  `nodesBetween` (return `false` to skip a node's content), `doc.nodeAt(pos)`, `doc.plotAt(pos)`,
+  `doc.resolve(pos)` (a `Pos`, ProseMirror's `ResolvedPos`), `plot.textContent({ blockSeparator })`.
+- **Types are objects, not names.** Import them (`Heading`, `Paragraph` from `wordgard/types`) and
+  compare with `node.type == Heading` or `node.is(Heading)`; names are for JSON and debugging.
+
+### Defining types
+
+```ts
+import { Leaf, Mark, Node, Plot } from "wordgard/doc";
+import { GardState } from "wordgard/state";
+
+// A plot without a parameter: `define` gives its tag.
+export const Callout = Plot.define("Callout", {
+  blockContent: Node.Group.Content,
+  group: Node.Group.Content,
+  shape: { element: "aside", selector: "aside.callout", attributes: { class: "callout" } },
+});
+
+// Data an editing action changes is a mark on the tag, not a parameter.
+export const CalloutKind = Mark.Type.define<string>("CalloutKind", {
+  target: Callout,
+  validate: "string",
+  shape: { attribute: "data-kind", value: 0 },
+});
+
+// A leaf with a parameter: `Type.define`, and nodes are `Mention.of(param)`.
+export const Mention = Leaf.Type.define<string>("Mention", {
+  inline: true,
+  validate: "string",
+  shape: {
+    element: "span",
+    selector: "span[data-mention]",
+    attributes: (id) => ({ "data-mention": id }),
+    readElement: (elt) => elt.getAttribute("data-mention") ?? "",
+  },
+});
+
+// The schema is assembled from the configuration.
+export const schemaPart = GardState.schemaElement.of([Callout, CalloutKind, Mention]);
+```
+
+- `Plot.define` / `Leaf.define` / `Mark.define` for types without a parameter;
+  `Plot.Type.define<P>` / `Leaf.Type.define<P>` / `Mark.Type.define<P>` with one (`Heading.of(2)`).
+- `shape` is both `toDOM` and `parseDOM`: an element (with `selector` and `readElement` for
+  parsing) or, for a mark, an attribute merged onto its node's element. A `structure` shape draws
+  inner elements; `0` marks where the content goes.
+
+## Changes
+
+ProseMirror's steps are gone. A transaction is a spec, every position in it counts in the
+document before it, and its changes are one `ChangeSet`, which also maps positions.
+
+```ts
+import type { Node } from "wordgard/doc";
+import type { Wordgard } from "wordgard/editor";
+import { Heading, Strong } from "wordgard/types";
+
+export const examples = (wg: Wordgard, pos: number, node: Node, target: number) => {
+  // Insert, mark a range, delete: all in the original document's positions.
+  wg.dispatch({
+    changes: [
+      { from: 1, insert: [node] },
+      { from: 8, to: 10, add: Strong },
+      { from: 20, to: 30 },
+    ],
+    selection: { anchor: 2 },
+  });
+  // A parameter change: replace the node's opening token by one of the same type.
+  wg.dispatch({ changes: { from: pos, to: pos + 1, insert: [Heading.of(2)] } });
+  // A move: delete the node and insert the same object elsewhere.
+  wg.dispatch({
+    changes: [
+      { from: pos, to: pos + node.length },
+      { from: target, insert: [node] },
+    ],
+  });
+};
+```
+
+| ProseMirror                                | Wordgard                                                                                                                     |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| `tr.insert`, `tr.replaceWith`, `tr.delete` | `changes: { from, to?, insert? }`; `insert` is an array of tokens                                                            |
+| `tr.addMark`, `tr.removeMark`              | `{ from, to, add: Mark }`, `{ from, to, remove: Mark }`                                                                      |
+| `tr.setNodeMarkup`, `tr.setNodeAttribute`  | a retag (`{ from: pos, to: pos + 1, insert: [Type.of(param)] }`) or a mark on the tag (`{ from: pos, add: Type.of(value) }`) |
+| `tr.mapping.map(pos)`                      | `tr.changes.mapPos(pos, assoc?)`                                                                                             |
+| `tr.setMeta`                               | `Transaction.Annotation` (about the transaction), `Transaction.Effect` (a change to state, mapped through changes)           |
+| `tr.steps`, `tr.docChanged`                | `tr.changes`, `tr.docChanged`                                                                                                |
+| `state.apply(tr)`                          | `tr.state` (`state.update(spec)` builds the transaction)                                                                     |
+| `Slice` with open depths                   | `Slice`, a flat run of tokens: nodes, `Plot.Tag` (an opening token), `Plot.End`                                              |
+
+## Configuration
+
+- **Extensions, not plugins.** The configuration is a tree of extensions (CodeMirror 6's system):
+  facets (`GardState.Facet`), state fields, precedence (`GardState.prec.highest(…)`), and
+  compartments (`new GardState.Compartment()`, `.of(…)`, `.reconfigure(…)` in an effect) or
+  `GardState.appendConfig` to change it later.
+- **Plugin state** is a field: `GardState.Field.define({ create, update: (value, tr) => …, provide })`.
+- **Plugin views** are `Wordgard.Plugin.define((wg) => ({ update(update) {}, docUpdate(wg) {} }))`.
+- **Props** are facets: `Wordgard.domEventHandler(type, (event, wg) => handled)`,
+  `Wordgard.contentAttributes.of({…})`, `Wordgard.updateListener.of((update) => …)`, decorations.
+- **Keymaps:** `KeyBinding.of({ key: "Mod-b", run: command })`, each binding an extension.
+- **Commands** are `(wg, param) => boolean | Transaction.Spec`, run with
+  `Command.dispatch(wg, command, param?)`. `Command.Pure` takes `{ state }` and returns a spec or
+  `false`; `Command.bind(command, param)` fixes the parameter for menus and keys;
+  `Command.handler(command, other)` lets an extension change what a command does.
+- **History:** `history()` from `wordgard/history`, with the `undo` and `redo` commands.
+- **HTML and JSON:** `parse(schema, element)` and `serialize(doc).toHTML()` from `wordgard/doc`;
+  `node.toJSON()` and `state.schema.nodeFromJSON(json)`. A spec's `doc` may be an HTML string.
+
+## Selection
+
+- `state.selection` (`GardSelection`) holds raw positions (`anchor`, `head`, `from`, `to`,
+  `empty`); `state.sel` the resolved ones (`sel.head.parent.node`).
+- Set it in a spec, `selection: { anchor, head? }`, or with `GardSelection.node(pos, node)` for a
+  node selection.
+
+## The editor
+
+- **`Wordgard`** is the view. It updates the DOM asynchronously, on the next frame (its _flush_):
+  read layout with `coordsAtPos` and the like, which flush first, or after `wg.flush()`. A
+  dispatch during the flush throws.
+- **It draws its own cursor** and handles selection keys itself; bind commands to them.
+- **Decorations** come as point decorations (`Decoration.Point`: widgets, attributes, a node's
+  shape or wrapper, at a position), range decorations (`Decoration.Range`: wrappers and attributes
+  over a range) and tag decorations (`Decoration.Tag`: for every node of a type, in place of node
+  views). Point and range sources are functions of the state called on every update: keep large
+  sets in a state field and map them (`set.map(tr.changes)`). `decoratePlots` decorates each plot
+  of a type from its own content.
+- **No node views.** A node's DOM is its shape; interactive parts are widgets in it, beside its
+  content. With react-wordgard, a React component can be the shape: see `SKILL.md`.
+
+## Traps
+
+- **Don't replace a node to change its data.** `{ from, to, insert: [newNode] }` makes a new node:
+  views remount, and history and collaboration see a replacement. Retag or change a mark.
+- **Don't carry ProseMirror's `attrs` over as one object parameter.** Split identity (the
+  parameter) from data that changes (marks with a `target`).
+- **Positions in one spec all count in the original document**: don't adjust the later ones for
+  the earlier changes, as with ProseMirror's step-by-step mapping.
+- **Refer to types by object.** `node.type.name == "heading"` breaks when the name differs and
+  can't tell two types with one name apart.
+- **Don't read layout right after `dispatch`** without letting the editor flush; and never
+  dispatch from inside an update (a plugin's `update`, a field's `update`).
+- **Point and range sources run on every update**: computing a big set there costs every
+  keystroke.
+- **Drag-and-drop inside the editor rebuilds what it moves from HTML** (Wordgard 0.6): moved nodes
+  are new objects, and whatever their HTML doesn't carry is lost.
+- **`Wordgard.label` names the outer element in 0.6.2**, not the textbox: use
+  `Wordgard.contentAttributes.of({ "aria-label": … })`.