@stesura/svelte-wordgard 0.0.0-stage → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/LICENSE.txt +21 -0
  3. package/README.md +403 -2
  4. package/THIRD_PARTY_LICENSES.txt +55 -0
  5. package/dist/SvelteDocTile.d.ts +15 -0
  6. package/dist/SvelteDocTile.js +227 -0
  7. package/dist/SvelteWordgard.d.ts +9 -0
  8. package/dist/SvelteWordgard.js +13 -0
  9. package/dist/components/ChildNodeViews.d.ts +57 -0
  10. package/dist/components/ChildNodeViews.js +159 -0
  11. package/dist/components/Decoration.svelte +20 -0
  12. package/dist/components/Decoration.svelte.d.ts +12 -0
  13. package/dist/components/DecorationRoot.svelte +35 -0
  14. package/dist/components/DecorationRoot.svelte.d.ts +10 -0
  15. package/dist/components/DecorationView.d.ts +16 -0
  16. package/dist/components/DecorationView.js +51 -0
  17. package/dist/components/NodeWrapperView.d.ts +15 -0
  18. package/dist/components/NodeWrapperView.js +103 -0
  19. package/dist/components/SeparatorHackView.d.ts +2 -0
  20. package/dist/components/SeparatorHackView.js +6 -0
  21. package/dist/components/ShapeView.d.ts +17 -0
  22. package/dist/components/ShapeView.js +94 -0
  23. package/dist/components/TextNodeView.d.ts +2 -0
  24. package/dist/components/TextNodeView.js +8 -0
  25. package/dist/components/TrailingHackView.d.ts +2 -0
  26. package/dist/components/TrailingHackView.js +4 -0
  27. package/dist/components/WidgetView.d.ts +9 -0
  28. package/dist/components/WidgetView.js +56 -0
  29. package/dist/components/WordgardDoc.svelte +40 -0
  30. package/dist/components/WordgardDoc.svelte.d.ts +3 -0
  31. package/dist/components/WordgardEditor.svelte +33 -0
  32. package/dist/components/WordgardEditor.svelte.d.ts +8 -0
  33. package/dist/components/WrappedNode.svelte +18 -0
  34. package/dist/components/WrappedNode.svelte.d.ts +3 -0
  35. package/dist/components/WrapperView.d.ts +12 -0
  36. package/dist/components/WrapperView.js +80 -0
  37. package/dist/components/marks/MarkView.d.ts +7 -0
  38. package/dist/components/marks/MarkView.js +16 -0
  39. package/dist/components/marks/SvelteMarkView.d.ts +4 -0
  40. package/dist/components/marks/SvelteMarkView.js +72 -0
  41. package/dist/components/nodes/DefaultNodeView.d.ts +24 -0
  42. package/dist/components/nodes/DefaultNodeView.js +201 -0
  43. package/dist/components/nodes/DocNodeView.d.ts +3 -0
  44. package/dist/components/nodes/DocNodeView.js +6 -0
  45. package/dist/contexts/DecorationContext.d.ts +13 -0
  46. package/dist/contexts/DecorationContext.js +12 -0
  47. package/dist/contexts/EditorContext.d.ts +5 -0
  48. package/dist/contexts/EditorContext.js +15 -0
  49. package/dist/contexts/WrappedContext.d.ts +6 -0
  50. package/dist/contexts/WrappedContext.js +10 -0
  51. package/dist/decorations/SvelteMarkType.d.ts +28 -0
  52. package/dist/decorations/SvelteMarkType.js +19 -0
  53. package/dist/decorations/SvelteNodeWrapper.d.ts +26 -0
  54. package/dist/decorations/SvelteNodeWrapper.js +12 -0
  55. package/dist/decorations/SvelteShapeType.d.ts +30 -0
  56. package/dist/decorations/SvelteShapeType.js +24 -0
  57. package/dist/decorations/SvelteWidgetType.d.ts +24 -0
  58. package/dist/decorations/SvelteWidgetType.js +20 -0
  59. package/dist/decorations/SvelteWrapperType.d.ts +27 -0
  60. package/dist/decorations/SvelteWrapperType.js +19 -0
  61. package/dist/helpers/box.svelte.d.ts +4 -0
  62. package/dist/helpers/box.svelte.js +11 -0
  63. package/dist/helpers/dom.d.ts +4 -0
  64. package/dist/helpers/dom.js +68 -0
  65. package/dist/helpers/mountRoot.d.ts +28 -0
  66. package/dist/helpers/mountRoot.js +156 -0
  67. package/dist/helpers/publish.d.ts +3 -0
  68. package/dist/helpers/publish.js +12 -0
  69. package/dist/helpers/slot.d.ts +11 -0
  70. package/dist/helpers/slot.js +67 -0
  71. package/dist/hooks/useEditorEffect.svelte.d.ts +10 -0
  72. package/dist/hooks/useEditorEffect.svelte.js +30 -0
  73. package/dist/hooks/useEditorEventListener.d.ts +10 -0
  74. package/dist/hooks/useEditorEventListener.js +24 -0
  75. package/dist/hooks/useEditorField.svelte.d.ts +20 -0
  76. package/dist/hooks/useEditorField.svelte.js +51 -0
  77. package/dist/hooks/useEditorLayoutEffect.d.ts +15 -0
  78. package/dist/hooks/useEditorLayoutEffect.js +24 -0
  79. package/dist/hooks/useEditorState.svelte.d.ts +5 -0
  80. package/dist/hooks/useEditorState.svelte.js +20 -0
  81. package/dist/hooks/useIgnoreMutation.d.ts +6 -0
  82. package/dist/hooks/useIgnoreMutation.js +18 -0
  83. package/dist/hooks/useIsNodeSelected.d.ts +4 -0
  84. package/dist/hooks/useIsNodeSelected.js +5 -0
  85. package/dist/hooks/useNodePos.d.ts +5 -0
  86. package/dist/hooks/useNodePos.js +7 -0
  87. package/dist/hooks/useSelectNode.svelte.d.ts +6 -0
  88. package/dist/hooks/useSelectNode.svelte.js +28 -0
  89. package/dist/hooks/useStopEvent.d.ts +8 -0
  90. package/dist/hooks/useStopEvent.js +21 -0
  91. package/dist/hooks/useWordgard.d.ts +2 -0
  92. package/dist/hooks/useWordgard.js +4 -0
  93. package/dist/index.d.ts +21 -0
  94. package/dist/index.js +21 -0
  95. package/dist/words.d.ts +2 -0
  96. package/dist/words.js +10 -0
  97. package/package.json +60 -4
  98. package/skills/svelte-wordgard/SKILL.md +437 -0
  99. package/skills/svelte-wordgard/references/wordgard.md +192 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,11 @@
1
+ ## 0.4.0 (2026-11-19)
2
+
3
+ ### New features
4
+
5
+ First release: svelte-wordgard draws Wordgard's document with its own DOM renderer, and any decoration that takes a shape, a wrapper or a widget, or a mark's shape, can be a Svelte 5 component.
6
+
7
+ `WordgardEditor` and `WordgardDoc` host the editor in a Svelte app, and unmounting `WordgardDoc` unmounts the document's components; the hooks (`useWordgard`, `useEditorState`, `useEditorField`, `useEditorFieldEntry`, `useEditorEffect`, `useEditorLayoutEffect`, `useEditorEventListener`) read and change it from components, those outside the document getting the state once the editor's update is done.
8
+
9
+ On the server (SvelteKit's first render), `WordgardEditor` creates no editor and draws nothing: its children are drawn in the browser, as the page hydrates.
10
+
11
+ `createShape`, `createWrapper`, `createMarkShape`, `createWidgetType` and `nodeWrapper` make Svelte components decorations, mounted with the contexts of the component whose `contentDOMRef` or `wrappedDOMRef` element holds them; `DecorationRoot` draws a root of the decoration's own tag, `WrappedNode` is a node wrapper's root, its attributes going on the node's root element, and `useNodePos`, `useIsNodeSelected`, `useSelectNode`, `useStopEvent` and `useIgnoreMutation` work inside them.
package/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Edoardo Caratti
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,404 @@
1
- # Temporary Holding Version
1
+ # svelte-wordgard
2
2
 
3
- 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.
3
+ > **Under construction.** svelte-wordgard isn't ready for production yet, and its API may still
4
+ > change.
5
+
6
+ svelte-wordgard stays on 0.x for as long as Wordgard does: it reaches into Wordgard's internals, and
7
+ relies on Svelte's behaviour where no contract covers it, so it can't be more stable than either.
8
+
9
+ A Svelte view for [Wordgard](https://www.wordgard.net): any decoration that takes a shape, a wrapper
10
+ or a widget can be a Svelte 5 component, mounted with your app's contexts. Wordgard keeps doing the
11
+ rest (input, selection, composition), and the API stays Wordgard's.
12
+
13
+ A Svelte decoration marks its content element with an attachment, reads your app's contexts and
14
+ stores, and can re-render on its own without breaking the editor.
15
+
16
+ It is [react-wordgard](https://github.com/stesura/react-wordgard/tree/master/packages/react) for
17
+ Svelte, over the same core. Its README goes deeper into Wordgard's side (shapes or wrappers, sharing
18
+ the model with a server, changing a node without remounting it); all of that holds here.
19
+
20
+ ## Contents
21
+
22
+ - [Install](#install)
23
+ - [Usage](#usage)
24
+ - [Reading and changing the editor](#reading-and-changing-the-editor)
25
+ - [Svelte decorations](#svelte-decorations)
26
+ - [The component's contract](#the-components-contract)
27
+ - [Timing](#timing)
28
+ - [Server rendering](#server-rendering)
29
+ - [Limits](#limits)
30
+ - [API](#api)
31
+ - [Coming from react-wordgard](#coming-from-react-wordgard)
32
+ - [AI coding agents](#ai-coding-agents)
33
+ - [Licence](#licence)
34
+
35
+ ## Install
36
+
37
+ ```sh
38
+ npm install @stesura/svelte-wordgard wordgard svelte
39
+ ```
40
+
41
+ - `wordgard` 0.7.0 exactly: svelte-wordgard uses Wordgard's internals, which any release can change.
42
+ - `svelte` 5.57, from 5.57.3: svelte-wordgard relies on how Svelte places its anchors, flushes and
43
+ mounts, which no contract covers and even a patch release can change.
44
+ - Only one copy of `wordgard` in your app: `npm ls wordgard` should list one version. With two, the
45
+ editor won't work.
46
+ - svelte-wordgard brings its core, `@stesura/wordgard-view`, at the same version: don't install or
47
+ import it yourself.
48
+ - It ships `.svelte` files, compiled by your app's Svelte: a SvelteKit or Vite app with
49
+ `@sveltejs/vite-plugin-svelte` takes them as they are.
50
+ - With TypeScript, `"skipLibCheck": true` in your `tsconfig.json`: Wordgard's own typings don't
51
+ type-check ([#120](https://code.haverbeke.berlin/wordgard/wordgard/issues/120)).
52
+
53
+ ## Usage
54
+
55
+ ```svelte
56
+ <!-- Editor.svelte -->
57
+ <script lang="ts">
58
+ import { Decoration, Wordgard } from "wordgard/editor";
59
+ import { basicSchema, image } from "wordgard/schema";
60
+ import { Image } from "wordgard/types";
61
+ import { WordgardDoc, WordgardEditor, createShape } from "@stesura/svelte-wordgard";
62
+
63
+ import ImageView from "./ImageView.svelte";
64
+ import WordCount from "./WordCount.svelte";
65
+
66
+ const config = [
67
+ basicSchema(),
68
+ image(),
69
+ Decoration.Tag.shape(Image, createShape(ImageView)),
70
+ Wordgard.label("Document"),
71
+ ];
72
+ </script>
73
+
74
+ <WordgardEditor
75
+ doc={'<p>Hello <strong>world</strong> <img src="/cat.png" alt="A cat"></p>'}
76
+ {config}
77
+ >
78
+ <WordCount />
79
+ <WordgardDoc class="editor" />
80
+ </WordgardEditor>
81
+ ```
82
+
83
+ ```svelte
84
+ <!-- ImageView.svelte: the node type's element, an <img>. Wordgard's attributes (`src`, `alt`, the
85
+ selected node's class) come as props, spread on the root. -->
86
+ <script lang="ts">
87
+ import type { ShapeComponentProps } from "@stesura/svelte-wordgard";
88
+
89
+ let { nodeProps, contentDOMRef, ...rest }: ShapeComponentProps = $props();
90
+ let hover = $state(false);
91
+ </script>
92
+
93
+ <img
94
+ {...rest}
95
+ style:outline={hover ? "2px solid" : undefined}
96
+ onmouseenter={() => (hover = true)}
97
+ onmouseleave={() => (hover = false)}
98
+ />
99
+ ```
100
+
101
+ ```svelte
102
+ <!-- WordCount.svelte -->
103
+ <script lang="ts">
104
+ import { useEditorState } from "@stesura/svelte-wordgard";
105
+
106
+ const editorState = useEditorState();
107
+ const words = $derived(editorState.current.doc.textContent().split(/\s+/).filter(Boolean).length);
108
+ </script>
109
+
110
+ <output>{words} words</output>
111
+ ```
112
+
113
+ `<WordgardEditor>` creates the editor from its props (`doc`, `config`, `selection`, `state`), **read
114
+ once**: the editor owns its state, and you change it with `wg.dispatch(…)`, its configuration with
115
+ Wordgard's compartments. `<WordgardDoc>` puts it in the page, in a `div` taking its attributes; one
116
+ per editor. `WordgardEditor` draws no element: wrap as much of the page in it as needs the editor.
117
+
118
+ Svelte refuses a variable named `state` beside the `$state` rune: name the editor's state otherwise
119
+ (`editorState`).
120
+
121
+ ### Reading and changing the editor
122
+
123
+ Under `WordgardEditor`, inside the document or beside it:
124
+
125
+ - `useWordgard()`: the editor. Commands run through `Command.dispatch(wg, command)`, changes
126
+ through `wg.dispatch({ changes, selection })`; `wg.state` is the latest state, dispatches not yet
127
+ drawn included.
128
+ - `useEditorState()`: the state as of the editor's last update (the one the DOM shows), in
129
+ `current`. Derive from it with `$derived`.
130
+ - `useEditorField(field, select?, isEqual?)`: a state field's value, or a part of it, in `current`;
131
+ nothing runs on an update that leaves the field unchanged. `useEditorFieldEntry(field, key)`: one
132
+ entry of a field holding a `Map`.
133
+ - `useEditorEffect((wg) => cleanup?, source?)`: runs once the editor's DOM is up to date, after it
134
+ mounts and again when what `source` (a function) reads changes. What the effect itself reads isn't
135
+ tracked. It may read layout and dispatch: for focus, menus, follow-up dispatches.
136
+ - `useEditorLayoutEffect({ read, write })`: inside every update, `read` in Wordgard's read phase and
137
+ `write` in its write phase, on the same paint, without rendering; it can't dispatch. For what
138
+ moves with the text (margin markers, pagination).
139
+ - `useEditorEventListener(type, (wg, event) => handled)`: the editor's DOM events, before
140
+ Wordgard's handlers and keymaps; returning `true` handles the event. Keyboard, input, mouse
141
+ (not `mousemove`), focus, clipboard and drag-and-drop events.
142
+
143
+ ```svelte
144
+ <!-- BoldButton.svelte -->
145
+ <script lang="ts">
146
+ import { Command, toggleStrong } from "wordgard/command";
147
+ import { useEditorState, useWordgard } from "@stesura/svelte-wordgard";
148
+
149
+ const wg = useWordgard();
150
+ const editorState = useEditorState();
151
+ const empty = $derived(editorState.current.selection.empty);
152
+ </script>
153
+
154
+ <button
155
+ disabled={empty}
156
+ onmousedown={(event) => {
157
+ event.preventDefault();
158
+ Command.dispatch(wg, toggleStrong);
159
+ }}
160
+ >
161
+ Bold
162
+ </button>
163
+ ```
164
+
165
+ Menus and popovers: position them with your library (Floating UI) from `wg.coordsAtPos(pos)` in
166
+ `useEditorEffect`, shown or hidden from a `$derived` over the state. To react to changes without
167
+ rendering (autosave), add a `Wordgard.updateListener.of((update) => …)` to `config`. Components
168
+ outside `WordgardEditor` can't use the hooks: lift `WordgardEditor`, or share the editor through a
169
+ store from `useEditorEffect` and use it directly.
170
+
171
+ ### Svelte decorations
172
+
173
+ Each factory takes a component, is **called at module level**, and returns a Wordgard value for
174
+ `config`:
175
+
176
+ | Need | Factory | Passed to |
177
+ | --------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------- |
178
+ | A node, with content or an atom (callout, image, mention) | `createShape(component)` | `Decoration.Tag.shape(Type, shape)`; `shape.of(element, { atom? })` for `Point.shape` |
179
+ | An element around a node or part of its shape | `createWrapper(component, { element })` | `Decoration.Tag.wrapper(Type, wrapper, { target? })`, `Decoration.Point.wrapper` |
180
+ | A mark's element (link, comment highlight) | `createMarkShape(component, { element })` | `Decoration.Mark.shape(MarkType, shape)` |
181
+ | A widget at a position or beside a node (badge, mention) | `createWidgetType({ component, … })` | `Decoration.Point.widget(Type.of(value))`, `Decoration.Tag.widget`, `Tag.shape` |
182
+ | Data for a node's shape, with no element | `nodeWrapper(Type, component)` | `config` directly: it is an extension |
183
+
184
+ ```svelte
185
+ <!-- Callout.svelte: a shape holding blocks, chrome before its content. DecorationRoot draws the
186
+ node type's element. -->
187
+ <script lang="ts">
188
+ import { DecorationRoot, type ShapeComponentProps } from "@stesura/svelte-wordgard";
189
+
190
+ let { nodeProps, contentDOMRef, ...rest }: ShapeComponentProps = $props();
191
+ </script>
192
+
193
+ <DecorationRoot {...rest}>
194
+ <span aria-hidden="true">!</span>
195
+ <div {@attach contentDOMRef}></div>
196
+ </DecorationRoot>
197
+ ```
198
+
199
+ ```svelte
200
+ <!-- LinkMark.svelte: a mark, its root the content element. -->
201
+ <script lang="ts">
202
+ import { DecorationRoot, type MarkComponentProps } from "@stesura/svelte-wordgard";
203
+
204
+ let { markProps, contentDOMRef, ...rest }: MarkComponentProps = $props();
205
+ </script>
206
+
207
+ <DecorationRoot {...rest} content={contentDOMRef} href={String(markProps.mark.value)} />
208
+ ```
209
+
210
+ ```svelte
211
+ <!-- Resizer.svelte: a wrapper, with a handle beside what it wraps. What it wraps goes first in
212
+ the element wrappedDOMRef marks. -->
213
+ <script lang="ts">
214
+ import { type WrapperComponentProps, useStopEvent } from "@stesura/svelte-wordgard";
215
+
216
+ let { nodeProps, wrappedDOMRef, class: className, ...rest }: WrapperComponentProps = $props();
217
+ useStopEvent(() => true);
218
+ </script>
219
+
220
+ <span
221
+ {...rest}
222
+ class={[typeof className == "string" && className, "resizer"]}
223
+ {@attach wrappedDOMRef}
224
+ >
225
+ <span class="resize-handle" aria-hidden="true"></span>
226
+ </span>
227
+ ```
228
+
229
+ ```svelte
230
+ <!-- Badge.svelte: a widget. -->
231
+ <script lang="ts">
232
+ import type { WidgetComponentProps } from "@stesura/svelte-wordgard";
233
+
234
+ let { value, ...rest }: WidgetComponentProps<string> = $props();
235
+ </script>
236
+
237
+ <span {...rest} class="badge" aria-hidden="true">{value}</span>
238
+ ```
239
+
240
+ ```ts
241
+ // view.ts
242
+ import { Decoration } from "wordgard/editor";
243
+ import { Blockquote, Image, Link, Paragraph } from "wordgard/types";
244
+ import {
245
+ createMarkShape,
246
+ createShape,
247
+ createWidgetType,
248
+ createWrapper,
249
+ } from "@stesura/svelte-wordgard";
250
+
251
+ import Badge from "./Badge.svelte";
252
+ import Callout from "./Callout.svelte";
253
+ import LinkMark from "./LinkMark.svelte";
254
+ import Resizer from "./Resizer.svelte";
255
+
256
+ const BadgeWidget = createWidgetType<string>({ component: Badge });
257
+
258
+ export const view = [
259
+ Decoration.Tag.shape(Blockquote, createShape(Callout)),
260
+ Decoration.Mark.shape(Link, createMarkShape(LinkMark, { element: "a" })),
261
+ // An image is inline: a span around it.
262
+ Decoration.Tag.wrapper(Image, createWrapper(Resizer, { element: "span" })),
263
+ Decoration.Tag.widget(Paragraph, "start", BadgeWidget.of("¶")),
264
+ ];
265
+ ```
266
+
267
+ Keep the model (node and mark types, schema elements, fields, commands) in a module without Svelte,
268
+ which a server can import, and the Svelte decorations in a client module adding decorations only.
269
+
270
+ `nodeWrapper(Type, component)` puts a component around every node of a type, drawing no element:
271
+ its root is `<WrappedNode />`, standing for the node's drawing, and the attributes you give it go
272
+ on the node's root element (`class` joined, Svelte's class arrays and objects read, handlers
273
+ dropped). It hands the node's Svelte shape data through `setContext`, and re-renders from its own
274
+ state without drawing the node again. Changing the wrappers in the configuration draws the whole
275
+ document again.
276
+
277
+ Inside a decoration's component: `useNodePos()` (a function giving its position, for handlers and
278
+ effects), `useIsNodeSelected()` (in `current`), `useSelectNode(select, deselect?)`,
279
+ `useStopEvent((wg, event) => stop)` for events in its chrome (its controls), and
280
+ `useIgnoreMutation((wg, record) => ignore)`.
281
+
282
+ ### The component's contract
283
+
284
+ Each Svelte decoration is a root of its own (`mount`), placed in the document by svelte-wordgard,
285
+ which draws everything else itself: nothing Svelte puts beside a root (its anchors, a block's
286
+ comment) may land among the document's nodes.
287
+
288
+ - **One root, the element the decoration says, and its props spread on it.** For a shape, the node
289
+ type's own outer element, per node (`h1` to `h6` for a heading); for `createWrapper`,
290
+ `createMarkShape` and `.of(element)`, their `element` (`div` for wrappers, `span` for marks); for
291
+ a widget, any element. Wordgard applies decorations to that element before Svelte draws, so the
292
+ component can't choose it. Spread the props it doesn't use on the root (`{...rest}`): they are
293
+ Wordgard's attributes (the node type's, the selection's `wg-selected-node`, tag and mark
294
+ attributes). Nothing falls through by itself: a `class` of your own joins theirs
295
+ (`class={[typeof className == "string" && className, "mine"]}`), or replaces it.
296
+ - **`<DecorationRoot {...rest}>`** draws that root, its tag the decoration's (a heading's level,
297
+ per node), and follows when it changes.
298
+ - **At the top, one element, or one block (`{#if}`, `{#key}`) around one
299
+ element, with nothing beside it in that block.** A root sharing a block with a sibling
300
+ (`<p></p>{#if open}…{/if}`, or inside one `{#key}`) breaks the editor when the block draws it
301
+ again: Svelte then removes the document's nodes after the root. A component may replace its root
302
+ from its own state (an `{#if}` switching between two elements).
303
+ - **The content goes in an empty element marked `{@attach contentDOMRef}`**, which holds only the
304
+ content; without one, the root holds it, and what's drawn there gets the decoration's contexts,
305
+ not the component's. `<DecorationRoot content={contentDOMRef}>` makes the
306
+ root the content element. Never `{@render children()}` or text there: Svelte's anchors would
307
+ land among the content's nodes.
308
+ - **What a wrapper wraps goes first in the element marked `{@attach wrappedDOMRef}`.**
309
+ - Everything else the component draws is **chrome**: made uneditable, never read as content, free
310
+ to change. In a textblock or a mark, the content element holds only the content; chrome beside a
311
+ paragraph's text is a widget at its `"start"` or `"end"`. In a node holding blocks, chrome sits
312
+ around the content element, in elements of its own.
313
+ - Chrome inherits the editor's `white-space: pre-wrap`, which draws the space Svelte keeps between
314
+ elements on separate lines: a blank line between a title bar and the content element. Give the
315
+ root `white-space: normal` and the content element `white-space: pre-wrap`.
316
+ - A component may move its content element (`contentDOMRef` on another element, from its own
317
+ state): the content's DOM moves into it.
318
+ - Node parameters: `nodeProps.node.tag.param` for a node with content, `node.param` for a leaf;
319
+ data an action changes in place is a mark on the tag (`node.tag.mark(Type)`), changed with
320
+ `wg.dispatch({ changes: { from: pos, add: Type.of(value) } })`, which keeps the component mounted.
321
+
322
+ ### Timing
323
+
324
+ Wordgard updates the DOM in its flush, on the next frame, and svelte-wordgard draws the document
325
+ inside it, committing Svelte's pending work there (`flushSync`).
326
+
327
+ - **Don't read the editor's layout (`coordsAtPos`) or force its update from a component's script,
328
+ template, `$derived`, `$effect` or attachment**: the update is refused there and drawn on the
329
+ next frame. Use `useEditorEffect`, `useEditorLayoutEffect` or an event handler.
330
+ - `useNodePos()`'s function throws before the decoration's tiles exist: call it from handlers and
331
+ `useEditorEffect`.
332
+ - Components outside the document get a new state once the editor's update is done, their effects
333
+ outside Wordgard's flush, where they may dispatch.
334
+ - An error a component in the document throws, in its setup or in a later update of its own, is
335
+ logged; the next update draws the document again.
336
+ - Svelte's async mode (`experimental.async`) is supported (tested in Svelte's development build).
337
+ A component suspending (`await`) in the document isn't.
338
+
339
+ ### Server rendering
340
+
341
+ For a SvelteKit page that is only the editor, turn server rendering off for its route
342
+ (`export const ssr = false` in `+page.ts`): nothing then runs on the server.
343
+
344
+ A page that keeps server rendering (an editor under an article, a comment box) needs nothing either:
345
+ on the server, `WordgardEditor` creates no editor and draws nothing, since Wordgard needs the DOM,
346
+ to read its document's HTML too. Its children are drawn in the browser, as the page hydrates. Its
347
+ props are still built on the server: give the document as `doc` (HTML), or load it with
348
+ `schema.docFromJSON`; a `GardState.create({ doc: html })` in the page's script throws there. To keep
349
+ the editor's place meanwhile, draw a placeholder beside it with `{#if !browser}` (from
350
+ `$app/environment`).
351
+
352
+ ### Limits
353
+
354
+ - A Svelte wrapper can't wrap text, or a node a native widget draws (draw it with a Svelte widget).
355
+ - A root leaving with an outro transition is still in the document when its replacement comes:
356
+ the editor reports the component as drawing two roots.
357
+ - Each Svelte decoration is a root of its own: mounting thousands at once (bolding a long document
358
+ with a Svelte mark shape) costs about 30 µs each.
359
+
360
+ ## API
361
+
362
+ Everything is exported from `@stesura/svelte-wordgard`.
363
+
364
+ - Components: `WordgardEditor`, `WordgardDoc`, `DecorationRoot`, `WrappedNode`.
365
+ - Factories: `createShape`, `createWrapper`, `createMarkShape`, `createWidgetType`, `nodeWrapper`.
366
+ - Editor hooks, under `WordgardEditor`: `useWordgard`, `useEditorState`, `useEditorField`,
367
+ `useEditorFieldEntry`, `useEditorEffect`, `useEditorLayoutEffect`, `useEditorEventListener`.
368
+ - Decoration hooks, in a decoration's component: `useNodePos`, `useIsNodeSelected`,
369
+ `useSelectNode`, `useStopEvent`, `useIgnoreMutation`.
370
+ - Props types: `ShapeComponentProps`, `WrapperComponentProps`, `MarkComponentProps`,
371
+ `WidgetComponentProps`, `NodeWrapperComponentProps`.
372
+ - `SvelteWordgard.create(spec)`: an editor drawn by svelte-wordgard outside a component tree
373
+ (tests, benchmarks). In a Svelte app, use `WordgardEditor`.
374
+
375
+ The hooks' and components' signatures and details are in their typings (`dist/index.d.ts`).
376
+
377
+ ## Coming from react-wordgard
378
+
379
+ | react-wordgard | svelte-wordgard |
380
+ | -------------------------------------------------------------------- | --------------------------------------------------------------------- |
381
+ | `{children}` in `contentDOMRef`'s element | an empty element with `{@attach contentDOMRef}` |
382
+ | A wrapper's `{children}` | an element with `{@attach wrappedDOMRef}`, what's wrapped first in it |
383
+ | `{...props}` and `ref` on a root drawn by hand | `{...rest}` on the root: no ref, the root is found |
384
+ | `useEditorStateSelector(selector)` | `$derived(selector(useEditorState().current))` |
385
+ | `useEditorEventCallback(callback)` | a plain function using `useWordgard()` |
386
+ | `useEditorEffect(effect, deps)` | `useEditorEffect(effect, source)`, `source` a function |
387
+ | `NodeRootProps` in a node wrapper | attributes on its `<WrappedNode />` |
388
+ | `useIsNodeSelected()` returning a boolean | `useIsNodeSelected()` returning an object with `current` |
389
+ | `WordgardScope`, `useMergedDOMRefs`, `staticCopy`, `isTrailingBreak` | none |
390
+
391
+ ## AI coding agents
392
+
393
+ The package ships a skill for building editors with svelte-wordgard: `skills/svelte-wordgard/` (in
394
+ `node_modules/@stesura/svelte-wordgard/`). Copy that folder into your project's `.claude/skills/`,
395
+ or point your agent to its `SKILL.md`.
396
+
397
+ ## Licence
398
+
399
+ MIT, © 2026 Edoardo Caratti, see [LICENSE.txt](LICENSE.txt).
400
+
401
+ Includes code from react-prosemirror (© Handle with Care Collective and The New York Times
402
+ Company), through react-wordgard; its notices are in
403
+ [THIRD_PARTY_LICENSES.txt](THIRD_PARTY_LICENSES.txt). Its core, `@stesura/wordgard-view`, also
404
+ includes code from Wordgard (© Marijn Haverbeke).
@@ -0,0 +1,55 @@
1
+ svelte-wordgard includes code from the projects below. Their copyright and
2
+ license notices are reproduced here, as their licenses require.
3
+
4
+
5
+ ================================================================================
6
+ react-prosemirror
7
+ https://github.com/handlewithcarecollective/react-prosemirror
8
+ ================================================================================
9
+
10
+ svelte-wordgard is adapted from react-wordgard, which is derived from
11
+ react-prosemirror, maintained by Handle with Care Collective and originally
12
+ created at The New York Times Company.
13
+
14
+ react-prosemirror was released under the Apache License 2.0 until 2026-10-02
15
+ (commit 1827d3a) and under the MIT License since then. Both notices follow.
16
+
17
+ --- MIT License (since 2026-10-02) ---------------------------------------------
18
+
19
+ MIT License
20
+
21
+ Copyright (c) 2026 Handle with Care Collective
22
+
23
+ Permission is hereby granted, free of charge, to any person obtaining a copy
24
+ of this software and associated documentation files (the "Software"), to deal
25
+ in the Software without restriction, including without limitation the rights
26
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
27
+ copies of the Software, and to permit persons to whom the Software is
28
+ furnished to do so, subject to the following conditions:
29
+
30
+ The above copyright notice and this permission notice shall be included in all
31
+ copies or substantial portions of the Software.
32
+
33
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
34
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
35
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
36
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
37
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
38
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
39
+ SOFTWARE.
40
+
41
+ --- Apache License 2.0 (until 2026-10-02) --------------------------------------
42
+
43
+ Copyright (c) 2022 The New York Times Company
44
+ Copyright (c) 2025 Handle with Care Collective
45
+
46
+ Licensed under the Apache License, Version 2.0 (the "License"); you may not use
47
+ this library except in compliance with the License. You may obtain a copy of the
48
+ License at
49
+
50
+ www.apache.org/licenses/LICENSE-2.0
51
+
52
+ Unless required by applicable law or agreed to in writing, software distributed
53
+ under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
54
+ CONDITIONS OF ANY KIND, either express or implied. See the License for the
55
+ specific language governing permissions and limitations under the License.
@@ -0,0 +1,15 @@
1
+ import type { Wordgard } from "wordgard/editor";
2
+ import type { GardState } from "wordgard/state";
3
+ import { RenderedDocTile } from "@stesura/wordgard-view";
4
+ import { type DrawContext } from "./components/ChildNodeViews.js";
5
+ type HostedDoc = {
6
+ readonly claim: () => () => void;
7
+ readonly attach: (contexts: Map<unknown, unknown>, place: () => void) => () => void;
8
+ };
9
+ export declare const svelteDoc: (dom: Element) => HostedDoc;
10
+ export declare const drawings: WeakMap<Element, () => DrawContext>;
11
+ export declare class SvelteDocTile extends RenderedDocTile {
12
+ static create: (state: GardState, dom: Element, wg: Wordgard) => RenderedDocTile;
13
+ static host: (state: GardState, dom: Element, wg: Wordgard, mount: () => void) => RenderedDocTile;
14
+ }
15
+ export {};