@stesura/react-wordgard 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+## 0.1.0 (2026-11-03)
+
+### New features
+
+First release: React draws Wordgard's documents inside Wordgard's own update, in the app's React tree, and Wordgard keeps handling input, selection, composition and decorations.
+
+Requires `wordgard` ~0.6.2 and React 18 or 19.
+
+`WordgardEditor` creates an editor and provides it to its children; `WordgardDoc` puts it in the page and renders its document through a portal, so the app's contexts reach what it draws.
+
+`createShape` makes a node's shape (`Decoration.Tag.shape`) a React component that renders the node's content as `children` and may change the elements around it on its own; its root is the node type's own outer element, and `shape.of(element, { atom? })` gives one for `Decoration.Point.shape` or another root.
+
+A React shape can draw an atom (an image, a mention, a plot drawn as one), its component getting the node and its attributes, everything it draws chrome.
+
+`createWrapper` does the same for `Decoration.Tag.wrapper` and `Decoration.Point.wrapper`, and `createMarkShape` for a mark's shape (`Decoration.Mark.shape`, or a mark type's own), each taking the component and an `element` for its root.
+
+`createWidgetType` defines a Wordgard widget type drawn by a React component, usable wherever Wordgard takes a widget, its value and element types inferred from the component.
+
+`DecorationRoot` draws the root of a React shape, wrapper, mark or widget: the tag its decoration says, Wordgard's attributes and the root's ref, merged with the component's own props, with no `forwardRef` needed on React 18.
+
+A component can draw its root by hand instead, from the ref and Wordgard's attributes it gets as props, its style as an object to merge with its own.
+
+`createShape`, `createWrapper` and `createMarkShape` give the same value for the same component (and `element`).
+
+A component keeps its state through a mark change on its node, a retag of the node's opening token, and a move within its parent (the same node object deleted and inserted in one transaction); replacing the node, changing its type or moving it to another parent remounts it.
+
+`useWordgard`, `useEditorState` and `useEditorStateSelector` read the editor and its state as of its last update.
+
+`useEditorEffect` runs after the editor's update; `useEditorLayoutEffect` reads and writes within it, on the same paint as the document, a read returning `undefined` skipping its write; `useEditorEventCallback` gives a stable callback getting the editor.
+
+`useEditorEventListener` handles the editor's DOM events before Wordgard's own handlers and keymaps.
+
+`useNodePos`, `useStopEvent`, `useIgnoreMutation`, `useIsNodeSelected`, `useSelectNode` and `useMergedDOMRefs` give React decorations what react-prosemirror's node views had; `useStopEvent` is asked for events in a decoration's chrome, on its own elements and in React widgets, never in its content.
+
+The package ships a skill for AI coding agents, `skills/react-wordgard/SKILL.md`, on building editors with Wordgard and react-wordgard, with a reference on Wordgard's model for ProseMirror developers.

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edoardo Caratti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,451 @@
-# Temporary Holding Version
+# react-wordgard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Under construction.** react-wordgard isn't ready for production yet, and its API may still
+> change.
+
+react-wordgard stays on 0.x for as long as Wordgard does: it follows Wordgard's API and reaches
+into its internals, so it can't be more stable than Wordgard. Its 1.0 comes after Wordgard's.
+
+A React view for [Wordgard](https://www.npmjs.com/package/wordgard): React draws Wordgard's
+document, inside Wordgard's own update, and Wordgard keeps doing what it does (input, selection,
+composition, decorations). The API is Wordgard's; react-wordgard adds what React needs to draw it.
+
+This repository is derived from
+[react-prosemirror](https://github.com/handlewithcarecollective/react-prosemirror),
+by [Handle with Care Collective](https://github.com/handlewithcarecollective)
+and originally The New York Times Company. Thanks to them for the design this
+builds on.
+
+## Install
+
+```sh
+npm install @stesura/react-wordgard wordgard react react-dom
+```
+
+Peer dependencies: `wordgard` 0.6 (`~0.6.2`: react-wordgard reaches into Wordgard's internals, so
+only its patches), `react` and `react-dom` 18 or 19. An app must have one copy of `wordgard`, the
+one react-wordgard uses. With TypeScript, Wordgard's own typings need `skipLibCheck`.
+
+With an AI coding agent: the package ships a skill for building editors with Wordgard and
+react-wordgard, `skills/react-wordgard/SKILL.md` (in `node_modules/@stesura/react-wordgard/`). Point your
+agent to it, or copy the `react-wordgard` folder into your project's `.claude/skills/` for Claude
+Code.
+
+## Usage
+
+```tsx
+import { useState } from "react";
+import { Decoration, Wordgard } from "wordgard/editor";
+// `image()` adds images to the schema; `Image` is their node type, which decorations name.
+import { basicSchema, image } from "wordgard/schema";
+import { Image } from "wordgard/types";
+import {
+  DecorationRoot,
+  WordgardDoc,
+  WordgardEditor,
+  createShape,
+  useEditorStateSelector,
+} from "@stesura/react-wordgard";
+
+// An image's shape, drawn by a React component with state of its own: hovering outlines it.
+// DecorationRoot is its root: the node type's element, an <img>, with the node's attributes (its
+// `src` and `alt`, the selected node's class) and the component's own props.
+const ImageShape = createShape(function ImageShape() {
+  const [hover, setHover] = useState(false);
+  return (
+    <DecorationRoot
+      style={hover ? { outline: "2px solid" } : undefined}
+      onMouseEnter={() => setHover(true)}
+      onMouseLeave={() => setHover(false)}
+    />
+  );
+});
+
+function WordCount() {
+  const words = useEditorStateSelector((state) => state.doc.textContent().split(/\s+/).length);
+  return <output>{words} words</output>;
+}
+
+export function Editor() {
+  return (
+    <WordgardEditor
+      doc='<p>Hello <strong>world</strong> <img src="/cat.png" alt="A cat"></p>'
+      config={[
+        basicSchema(),
+        image(),
+        Decoration.Tag.shape(Image, ImageShape),
+        Wordgard.contentAttributes.of({ "aria-label": "Document" }),
+      ]}
+    >
+      <WordCount />
+      <WordgardDoc className="editor" />
+    </WordgardEditor>
+  );
+}
+```
+
+- `<WordgardEditor>` creates the editor from a `Wordgard.Spec` and provides it to what it holds.
+  The spec is read once, when it mounts: changing `doc` or `config` afterwards does nothing. The
+  editor owns its state: change it with `dispatch`, and its configuration with Wordgard's
+  compartments or `GardState.appendConfig`. `<WordgardDoc>` puts the editor in the page and
+  renders the document through a portal, in your React tree: your contexts reach React
+  decorations. One `<WordgardDoc>` per editor; a second one throws.
+- `createShape`, `createWrapper`, `createMarkShape` and `createWidgetType` make React components
+  Wordgard decorations: below. Call them at module level, with components defined there.
+  `createShape`, `createWrapper` and `createMarkShape` give the same value for the same component
+  (and `element`), so a config built again is the same; a component defined inside a render is a
+  new one each time, and remounts everything it draws. The components don't need
+  memoizing: React draws a node again only when it changed (its content, its shape, its
+  attributes, its widget's value), or from the component's own state, contexts and hooks.
+- Hooks, from inside `<WordgardEditor>`:
+  - `useWordgard()`: the editor.
+  - `useEditorState()`, `useEditorStateSelector(selector, isEqual?)`: the state as of the
+    editor's last flush, rendered in the same React commit as the document. The selector's result
+    re-renders when it changes, by `Object.is` or by `isEqual`.
+  - `useEditorEffect(effect, deps)`: an effect run once the editor's DOM is up to date, where it
+    may read layout (`coordsAtPos`) and dispatch.
+  - `useEditorEventCallback(callback)`: a stable callback getting the editor.
+  - `useEditorLayoutEffect({ read, write })`: reads in every update's read phase, writes in its write
+    phase, on the same paint as the document, for what must move with the text (markers in the
+    margin, pagination). It can't dispatch: Wordgard throws during its update. A `read` returning
+    `undefined` skips its write; when none asks for one, no write is scheduled, which spares
+    Wordgard measuring again. Reads run in the order the effects were registered: an engine whose
+    parts must run in another order registers one effect and drives them.
+  - `useEditorEventListener(type, (wg, event) => handled)`: the editor's DOM events of `type`
+    before Wordgard's handlers and keymaps; returning true handles the event. Key events during
+    a composition don't come; handling `input`, `beforeinput` or composition events skips
+    Wordgard's own handling of them.
+- In React's StrictMode (development only), `<WordgardEditor>` creates its editor twice and
+  drops one, which is never put in the page.
+- Don't read the editor's layout from a plain React effect: it runs inside Wordgard's update,
+  before the editor's view of the new DOM exists. Use `useEditorEffect` or `useEditorLayoutEffect`.
+
+### React decorations
+
+A node's shape, a wrapper, a mark's shape and a widget can each be a React component. Shapes,
+wrappers and marks render what they hold as `children`; each can change the DOM around it (its
+"chrome") on its own: from its state, a context or a store. Each factory returns Wordgard's own
+value (a shape, a wrapper, a mark's shape, a widget type), registered as drawn by the component,
+which you pass to Wordgard's decorations:
+
+```tsx
+import { Decoration } from "wordgard/editor";
+import { Blockquote, Link } from "wordgard/types";
+import { DecorationRoot, createMarkShape, createShape } from "@stesura/react-wordgard";
+
+// A blockquote drawn as a callout: a decorative icon, then the content.
+const CalloutShape = createShape(function Callout({ nodeProps: { contentDOMRef }, children }) {
+  return (
+    <DecorationRoot>
+      <span aria-hidden="true">💡</span>
+      <div className="body" ref={contentDOMRef}>
+        {children}
+      </div>
+    </DecorationRoot>
+  );
+});
+
+// A link, its target the mark's value.
+const LinkMark = createMarkShape(
+  function LinkMark({ markProps: { mark, contentDOMRef }, children }) {
+    return (
+      <DecorationRoot href={String(mark.value)}>
+        <span ref={contentDOMRef}>{children}</span>
+      </DecorationRoot>
+    );
+  },
+  { element: "a" }
+);
+
+const config = [
+  Decoration.Tag.shape(Blockquote, CalloutShape),
+  Decoration.Mark.shape(Link, LinkMark),
+];
+```
+
+- `createShape(component)` returns a node's shape for `Decoration.Tag.shape`, a function of the
+  node's tag (a form `Decoration.Tag.shape` takes): the type's nodes are drawn by the component.
+- Its root is the node type's own outer element, with its tag for each node (a heading's level
+  gives `h1` to `h6`) and its attributes.
+- The component gets `nodeProps` (`node`, `getPos`, `contentDOMRef`) and `children` (the
+  content), which goes in the `contentDOMRef` element, else in the root. Define the component
+  inline, as a named function, and its props are typed for you.
+- Only the outer element comes from the node type: the elements inside a structure shape (a
+  figure's `img`, a table's `tbody`) are the component's to draw, from `nodeProps.node`. Attributes
+  aimed at them land on the root, as a `target` that matches nothing picks the root (see "A shape,
+  a wrapper, or both").
+- Where the node type draws an atom (a leaf: an image, a mention; a plot whose shape has no
+  hole), so does its React shape: `children` is empty, everything the component draws is chrome,
+  and a `contentDOMRef` throws.
+- `shape.of(element, { atom? })` is the shape with `element` for its root, for
+  `Decoration.Point.shape` (which applies to whatever node follows, so no type says the element)
+  or a root other than the type's: `Decoration.Tag.shape(Blockquote, CalloutShape.of("aside"))`.
+  With `atom: true`, it has no hole: a leaf needs it (Wordgard refuses a hole in a leaf's shape),
+  and it draws a plot as an atom.
+- `createWrapper(component, { element? })`, for `Decoration.Tag.wrapper` and
+  `Decoration.Point.wrapper`: the same props without `contentDOMRef`; `children` is what it
+  wraps (the node's shape, or the element its `target` picks). `element` is its root, `div` by
+  default: a wrapper is an element the node type doesn't have.
+- `createMarkShape(component, { element? })`, for `Decoration.Mark.shape` or a mark type's own
+  `shape`: `markProps` (`mark`, the document's, `getPos`, `contentDOMRef`) and `children`. One
+  component draws each run of an equal mark. `element` is its root (`span` by default): a mark
+  shape is a static spec, so the element can't be read from the mark type. A React mark replacing
+  an attribute-shaped mark makes it element-shaped.
+- The root is the element the decoration says, and stays that element. Wordgard applies
+  decorations to a shape before anything is drawn (`target` selectors match its tag, attributes
+  merge onto its elements), so the tag has to be known up front.
+- `<DecorationRoot>` draws it, in a shape's, wrapper's or mark's component: 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. The component's own props win, except `className`, joined with Wordgard's, and `style`,
+  merged with it (the component's keys winning). Its `ref` gets the root too. Without a
+  `contentDOMRef`, the content goes in it. One per component, at its root.
+- Or the component draws its root by hand, for more control over the decoration's attributes:
+  below.
+- A root with another tag than the decoration's logs an error, once per tag.
+- The chrome is made uneditable unless it sets `contentEditable` itself.
+
+#### A root drawn by hand
+
+`DecorationRoot` applies all of Wordgard's attributes. To decide what reaches the root (drop one,
+change one, join Wordgard's classes your way) or to type the root as its element, the component
+draws the root itself. It gets Wordgard's attributes as props and a `ref` for the root:
+
+```tsx
+import { forwardRef } from "react";
+import { type ShapeComponentProps, createShape } from "@stesura/react-wordgard";
+
+// An image whose root drops the `title` a decoration gives it and adds a class of its own.
+const ImageShape = createShape(
+  forwardRef<HTMLImageElement, ShapeComponentProps<HTMLImageElement>>(function ImageShape(
+    { nodeProps, children, className, title, ...props },
+    ref
+  ) {
+    return <img {...props} ref={ref} className={["picture", className].join(" ").trim()} />;
+  })
+);
+```
+
+- Draw the element the decoration says (the node type's for a shape, `element` for a wrapper or
+  mark), spread the props, and put `ref` on it. On React 19 `ref` is a prop too, so `forwardRef`
+  isn't needed: `createShape<HTMLImageElement>(function ImageShape({ ref, ...props }) {…})`.
+- `className` holds Wordgard's classes (the selection's among them): join yours with them, or
+  they're lost.
+- `style` holds Wordgard's style as an object: spread yours over it,
+  `style={{ ...style, color: "red" }}`, or it replaces Wordgard's.
+- One way or the other: props spread onto `DecorationRoot` would apply twice.
+- `createWrapper` and `createMarkShape` components work the same way (`WrapperComponentProps`,
+  `MarkComponentProps`).
+
+#### React widgets
+
+```tsx
+import { Decoration } from "wordgard/editor";
+import { Paragraph } from "wordgard/types";
+import {
+  DecorationRoot,
+  type WidgetComponentProps,
+  createWidgetType,
+} from "@stesura/react-wordgard";
+
+// A pilcrow at the start of every paragraph.
+const Pilcrow = createWidgetType({
+  component: function Pilcrow({ value }: WidgetComponentProps<string>) {
+    return <DecorationRoot aria-hidden="true">{value}</DecorationRoot>;
+  },
+});
+
+const config = [Decoration.Tag.widget(Paragraph, "start", Pilcrow.of("¶"))];
+```
+
+- `createWidgetType(spec)`, for a widget: at a position (`Decoration.Point.widget`), beside a node
+  (`Decoration.Tag.widget`), inside an `Elt` shape. It takes `Widget.define`'s spec, `component`
+  in place of `render` (`eq`, `editable`, `inFlow`, `propagateEvent`, `connect`, `disconnect` keep
+  their meaning), and returns a real `Widget.Type`: its widgets are `type.of(value)`.
+- The component gets the `value`. Its root is a `DecorationRoot`, a `span` unless the spec gives
+  another `element` (`createWidgetType({ component, element: "div" })`): Wordgard doesn't look at
+  a widget's element, so it's the widget's choice. Or the component draws its root by hand, with
+  the `ref` it gets (`forwardRef` on React 18), as a shape's can.
+- Widgets are uneditable unless their spec sets `editable`, as in Wordgard.
+- A widget can also draw a node, as Wordgard allows:
+  `Decoration.Tag.shape(nodeType, (tag) => type.of(tag.param))`. `DecorationRoot` puts the node's
+  attributes on its root (a root drawn by hand gets them as props). A React shape is the usual
+  way.
+
+#### Hooks inside React decorations
+
+From a React shape's, wrapper's, mark's or widget's component:
+
+- `useNodePos()`: a function returning the position of what it draws, to call in handlers and
+  effects.
+- `useStopEvent((wg, event) => stop)`: asked for events in the decoration's chrome, on its own
+  elements (its root and the elements around its content element, unless the root is the content
+  element) and in React widgets; never for those in its content. 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`).
+- `useIsNodeSelected()`, `useSelectNode(select, deselect?)`: the node selection.
+- `useMergedDOMRefs(...refs)`: one ref setting several, as for a root that's also the content
+  element.
+
+### A shape, a wrapper, or both
+
+- A node type's shape decides where attributes go: a mark's or an attribute decoration's `target`
+  or `preferTarget` picks an element in it. `ImageAlt` and `ImageSize` go on a figure's `img`
+  because the figure's shape has one. A React shape for the figure draws its `img` itself, so they
+  land on its root instead: to keep them on the `img`, keep the type's shape and add React around
+  it with a wrapper.
+- React chrome around a node, or around an element in its shape, is a React wrapper:
+  `Decoration.Tag.wrapper(Figure, createWrapper(Frame), { target: "img" })` puts `Frame` around
+  the figure's `img`, which keeps its `src`, `alt` and width.
+- A shape and wrappers register on the same node type and apply to all its nodes.
+- For example: an image is the type's `img`, with a React frame around it for a resize handle. A
+  table is a React shape drawing `table > tbody > {children}`, with a wrapper for what goes outside
+  the table (a scroll container, column handles). A node taller than a page is clipped by a wrapper
+  whose component reads a store.
+
+That's a step more than a react-prosemirror node view, which draws all of its node's DOM. Wordgard
+applies decorations to the node type's shape before React draws, so an element decorations aim at
+must be in that shape. A wrapper adds React around it without taking it over.
+
+### Node data that changes
+
+A component keeps its state while its node changes in place or moves within its parent, and
+remounts, with everything inside it, when its node is replaced. So how an editing action changes a
+node matters:
+
+- Data an action changes on a node (an image's size, a block's alignment, a callout's kind, a
+  table's column widths) is a mark on its tag: a type made with `Mark.Type.define(name, { target })`,
+  read with `node.tag.mark(Type)`, changed with `{ from: pos, add: Type.of(value) }` and
+  `{ from: pos, remove: Type.of(value) }`. That's Wordgard's model: a mark change merges in
+  collaboration and inverts in history, and the component re-renders. Wordgard's `ImageSize` is
+  one; the demo's callout keeps its kind and title so (`demo/schema.ts`).
+- What identifies the node (an image's `src`, a heading's level) is its parameter. Change it by
+  retagging, replacing the node's opening token by one of the same type, as Wordgard's commands
+  do: `{ from: pos, to: pos + 1, insert: [Heading.of(2)] }`. The component re-renders, and its
+  content keeps its components.
+- Replacing the node whole (`{ from, to, insert: [node] }`) or changing its type remounts it.
+- A move keeps the component, and the components inside, when the node stays in its parent: in one
+  transaction, it's deleted and the same node object is inserted elsewhere in that parent. A copy
+  (a new node, or the same one inserted while the original stays) mounts anew, and so does a node
+  moved to another parent. React point widgets inside a moved node are drawn anew, as Wordgard
+  redraws them. React moves the node's DOM, and a browser reloads an `<iframe>` on any
+  DOM move. Wordgard's drag-and-drop rebuilds what it drops from HTML, so its moves remount.
+
+ProseMirror's `setNodeAttribute` and `setNodeMarkup` port to one of the first two.
+
+### Accessibility
+
+- Wordgard gives the editable element `role="textbox"` and `aria-multiline`. Name it with
+  `Wordgard.contentAttributes.of({ "aria-label": "…" })`: in Wordgard 0.6.2, `Wordgard.label`
+  puts the label on the editor's outer element, which leaves the textbox without a name.
+- A React decoration's chrome is read inline, with the document's text. Hide what's decorative
+  (`aria-hidden` on icons and counters), and give every control a name (its text or
+  `aria-label`).
+- Chrome is uneditable: a control in it needs to be focusable to be reached by keyboard, and
+  `useStopEvent` for its events, so that Wordgard leaves its keys alone.
+- `DecorationRoot` puts the node's attributes on its root, an image's `alt` among them, in a React
+  shape or a widget drawing a node. A root drawn by hand gets them as props: spread them onto it.
+- The tests run axe-core over editors with React shapes, marks and widgets
+  (`src/__tests__/accessibility.browser.test.tsx`): nothing breaks a rule plain Wordgard keeps.
+
+### Limits
+
+- A React decoration must keep its root element. Moving `{children}` under another element
+  remounts the content: the browser loses a selection or an IME composition in it.
+- In a textblock or a mark, the content element holds only the content: chrome there would be text
+  that can't be told from the content's. Chrome next to a textblock's text (line numbers, a
+  marker) is a tag widget at `"start"` or `"end"`, a React widget that may read the shape's
+  context: `Decoration.Tag.widget(Paragraph, "start", LineNumber.of(null))`. Wordgard places the
+  caret around it. In a node holding blocks, chrome may sit before or after
+  the content in the same element, not between its nodes.
+- A React wrapper can't wrap a node a native widget draws (draw it with a React shape or widget),
+  nor text.
+- An attribute code sets by hand (a resize observer's, a layout engine's) on a React decoration's
+  root or structure stays through Wordgard's updates and the component's renders, until React sets
+  that attribute itself: a `classList.add` goes when React sets `className` again (the node gets
+  selected, a mark adds a class). On an element Wordgard draws, Wordgard's next update undoes it.
+  Draw such state from decorations or the component's state instead; in a decoration's content,
+  `useIgnoreMutation` keeps Wordgard from undoing a change it claims, until Wordgard redraws there.
+- `useEditorEventListener` takes these event types: keyboard (`keydown`, `keyup`, `keypress`),
+  input (`beforeinput`, `input`, composition events), mouse (`mousedown`, `mouseup`, `mouseover`,
+  `mouseout`, `click`, `dblclick`, `contextmenu`), `focus`, `blur`, clipboard (`copy`, `cut`,
+  `paste`) and drag-and-drop events. Wordgard adds a handler per type when the editor is created;
+  scroll-blocking and the most frequent events (touch, wheel, `mousemove`, pointer events) are left
+  out.
+- A node drawn by a React widget has no element around it for its attributes, unlike plain
+  Wordgard's: its component gets them as props, so a selection doesn't remount it.
+- Typing with marks before there's text draws a mark from its own type, not a
+  `Decoration.Mark.shape` override; plain Wordgard does the same.
+- Wordgard 0.6.2's own typings need `skipLibCheck`.
+
+## Migrating from react-prosemirror
+
+react-wordgard isn't a compatibility layer: it follows Wordgard's API, and most of a migration is
+moving from ProseMirror's concepts to Wordgard's (see Wordgard's
+[ProseMirror migration guide](https://wordgard.net/docs/prosemirror/)). What changes on the React
+side:
+
+| react-prosemirror                                 | react-wordgard                                                                                                                                        |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<ProseMirror state={…} dispatchTransaction={…}>` | `<WordgardEditor doc={…} config={…}>`, uncontrolled: the editor owns its state, changes go through `wg.dispatch`                                      |
+| `<ProseMirrorDoc />`                              | `<WordgardDoc />`                                                                                                                                     |
+| `plugins` prop                                    | Wordgard extensions in `config`; to change them later, compartments or `GardState.appendConfig`                                                       |
+| `nodeViews` prop and node view components         | Tag decorations: `Decoration.Tag.shape(NodeType, createShape(component))` for any node, atoms included; `createWrapper` with `Decoration.Tag.wrapper` |
+| `markViews` prop and mark view components         | `createMarkShape` with `Decoration.Mark.shape`                                                                                                        |
+| `widget()` decorations with a component           | `Decoration.Point.widget(MyReactWidget.of(value))`                                                                                                    |
+| `getPos` prop, `useNodePos`                       | `nodeProps.getPos`, `useNodePos()` (a function, not the position)                                                                                     |
+| `useStopEvent`                                    | the same name, for events in a React decoration's chrome, on its own elements or in a React widget, not in its content                                |
+| `useIgnoreMutation`                               | the same name; chrome's and React widgets' mutations never reach Wordgard anyway                                                                      |
+| `useEditorState`, `useEditorStateSelector`        | the same names, with the state of the last flush                                                                                                      |
+| `useEditorEffect`                                 | the same name: runs after the editor's update; what it sets shows a frame later (below)                                                               |
+| `useIsNodeSelected`, `useSelectNode`              | the same names                                                                                                                                        |
+| `useMergedDOMRefs`                                | the same name                                                                                                                                         |
+| `useEditorEventCallback`                          | the same name, getting the editor                                                                                                                     |
+| `useEditorEventListener`                          | the same name, before Wordgard's handlers and keymaps, for a fixed set of event types                                                                 |
+| `useLayoutGroupEffect`                            | `useEditorEffect`; `useEditorLayoutEffect` to measure, then write on the same paint                                                                   |
+| `reactKeys()` plugin                              | not needed: keys come from the changes Wordgard gives the view                                                                                        |
+
+Not offered: `useIsComposingIn`, `useIsEditorStatic`.
+
+### Migrating a node view
+
+A react-prosemirror node view keeps its body: the props keep their names (`nodeProps`,
+`contentDOMRef`, `children`, `ref`, the attributes). What changes:
+
+- The props type: `ShapeComponentProps` (any node, atoms included), `WrapperComponentProps`,
+  `MarkComponentProps`.
+- The root's tag isn't the component's choice: it's the node type's own element, what `toDOM`'s
+  outer element was (see "React decorations" for why).
+- The root element, with its `{...props}` and `ref`, becomes `<DecorationRoot>`.
+- `node.attrs` becomes the node's parameter (`node.tag.param`, `node.param` for a leaf) for what
+  identifies it, and marks on its tag (`node.tag.mark(Type)`) for data changed in place: see "Node
+  data that changes". `view` becomes `wg`, Wordgard's editor.
+- Registration: `Decoration.Tag.shape(NodeType, createShape(component))` in the editor's `config`
+  instead of `nodeViews`.
+- Class names: `ProseMirror-selectednode` is `wg-selected-node`, a selected cell's class
+  `wg-selected-cell`.
+- `useNodePos()` returns a function giving the position, not the position.
+- `innerDecorations` has no equivalent.
+
+### Effects and timing
+
+In react-prosemirror React drives: `useEditorEffect` is a React layout effect that runs after the
+view's update, inside React's commit, so it can read layout, dispatch, and what it sets shows on the
+same paint. In react-wordgard Wordgard drives: React commits inside Wordgard's update, and those
+properties split between two hooks.
+
+|                                           | react-prosemirror `useEditorEffect` | `useEditorEffect`                  | `useEditorLayoutEffect`                              |
+| ----------------------------------------- | ----------------------------------- | ---------------------------------- | ---------------------------------------------------- |
+| Reads layout after the update             | yes                                 | yes                                | yes, in Wordgard's read phase                        |
+| May dispatch                              | yes                                 | yes                                | no                                                   |
+| What it sets shows on the same paint      | yes                                 | no, a frame later                  | yes                                                  |
+| Runs on every update without re-rendering | no                                  | no                                 | yes                                                  |
+| For                                       | everything                          | menus, focus, follow-up dispatches | what moves with the text: margin markers, pagination |
+
+## Licence
+
+MIT, © 2026 Edoardo Caratti, see [LICENSE.txt](LICENSE.txt).
+
+Includes code from react-prosemirror (© Handle with Care Collective and The New
+York Times Company) and Wordgard (© Marijn Haverbeke); their notices are in [THIRD_PARTY_LICENSES.txt](THIRD_PARTY_LICENSES.txt).

package/THIRD_PARTY_LICENSES.txt

@@ -0,0 +1,93 @@
+react-wordgard includes code from the projects below. Their copyright and
+license notices are reproduced here, as their licenses require.
+
+
+================================================================================
+react-prosemirror
+https://github.com/handlewithcarecollective/react-prosemirror
+================================================================================
+
+react-wordgard is derived from react-prosemirror, maintained by Handle with
+Care Collective and originally created at The New York Times Company. Files
+that came from it keep their "Copyright (c) The New York Times Company"
+headers.
+
+react-prosemirror was released under the Apache License 2.0 until 2026-10-02
+(commit 1827d3a) and under the MIT License since then. Both notices follow.
+
+--- MIT License (since 2026-10-02) ---------------------------------------------
+
+MIT License
+
+Copyright (c) 2026 Handle with Care Collective
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--- Apache License 2.0 (until 2026-10-02) --------------------------------------
+
+Copyright (c) 2022 The New York Times Company
+Copyright (c) 2025 Handle with Care Collective
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this library except in compliance with the License. You may obtain a copy of the
+License at
+
+www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+
+
+================================================================================
+Wordgard
+https://wordgard.net
+================================================================================
+
+test/wordgard/ holds copies of Wordgard's browser tests and their helpers;
+demo/main.tsx is adapted from Wordgard's demo (demo/demo.ts), and the
+IME emulation in src/__tests__/tile.browser.test.ts from its `compose` test
+helper (test/webtest-composition.ts). src/decorations/DecoIterator.ts copies
+Wordgard's decoration walker (src/editor/decoration.ts), with changes noted in
+the file. src/tile.ts copies `setUneditable` from Wordgard's tile tree
+(src/editor/tile.ts) and follows its tile builder there.
+
+MIT License
+
+Copyright (C) 2026 by Marijn Haverbeke <marijn@haverbeke.berlin>.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/ReactWordgard.d.ts

@@ -0,0 +1,13 @@
+import { Wordgard } from "wordgard/editor";
+import { ReactDocTile } from "./tile.js";
+import { type DOMObserver, DocTile } from "./wordgardInternals.js";
+export declare class ReactWordgard extends Wordgard {
+    docTile: DocTile;
+    observer: DOMObserver;
+    scheduleFlush: () => void;
+    static create: (spec: Wordgard.Spec) => ReactWordgard;
+    static host: (spec: Wordgard.Spec) => ReactWordgard;
+    static DocTile: typeof ReactDocTile;
+    constructor(spec: Wordgard.Spec, hosted?: boolean);
+    flush(): void;
+}