@thomasfosterau/prosekit-svelte 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Foster
+
+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,256 @@
-# Temporary Holding Version
+# `@thomasfosterau/prosekit-svelte`
 
-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.
+Svelte 5 rich-text editing on [ProseKit](https://prosekit.dev): `Editor`, `BlockEditor`, `InlineEditor`, a declarative `BlockToolbar` with an insert menu, and the link and image dialogs — all built on [bits-ui](https://bits-ui.com), all styled with daisyUI's semantic classes, every user-facing string a prop with an English default.
+
+Requires Tailwind 4 + daisyUI in the consuming app (see [Peer requirements](#peer-requirements)). Accessible-name props end in `Label`. Every component spreads the native attributes you pass (`id`, `data-*`, `aria-*`, …) on the element it renders — `SlashMenu` on its `role="menu"` element, `LinkDialog` and `ImageDialog` on their `role="dialog"` element — with the dialogs' `role`, `aria-modal` and title wiring winning. `Editor`, `BlockEditor`, `InlineEditor`, `BlockToolbar` and `SlashMenu` own their accessible name through `label` / `menuLabel`, or `labelledBy` to name it by a visible heading: give `labelledBy` the heading's `id` (or space-separated `id`s) and the component renders `aria-labelledby`, which wins over the label. `label` / `menuLabel` (or its default) stays on as `aria-label`, the fallback name if no element has that `id`; an empty `labelledBy` counts as unset. `aria-label` and `aria-labelledby` are not among their props, and passed anyway (from untyped code) the component's own attributes override the first and drop the second. Every component merges the caller's `class` last.
+
+## Installation
+
+```sh
+pnpm add @thomasfosterau/prosekit-svelte prosekit @prosekit/pm
+```
+
+### Peer requirements
+
+| Package | Range | Why |
+| --- | --- | --- |
+| `svelte` | `^5.30.1` | A declared peer. The components are compiled by your build, not pre-compiled. |
+| `prosekit` | `^0.22.2` | A declared peer. The editor runtime, and the two stylesheets `Editor.svelte` imports. |
+| `@prosekit/pm` | `^0.1.19` | A declared peer. ProseMirror's model and view, at the version ProseKit expects. |
+| `tailwindcss` | `^4.0.0` | Not a declared peer, but **required**: the components emit Tailwind classes and ship none. |
+| `daisyui` | `^5.0.0` | Same — the class vocabulary is daisyUI's (`btn`, `menu`, `modal-box`, `input`, `bg-base-100`). |
+
+Tailwind 4 has no `tailwind.config.js`, so wire it up from your CSS entry. The `@source` line is what makes Tailwind scan this package's `dist/` and emit the classes it asks for; without it the editor renders unstyled.
+
+```css
+@import 'tailwindcss';
+@source '../node_modules/@thomasfosterau/prosekit-svelte/dist';
+@plugin "daisyui" {
+  themes:
+    light --default,
+    dark --prefersdark;
+}
+```
+
+ProseKit's own stylesheets arrive through `Editor.svelte`'s bare imports — you do not import them yourself.
+
+`@thomasfosterau/prosekit-utilities` and `bits-ui` are ordinary dependencies of this package, at the same release line, and come along automatically when you install it — you do not add either yourself.
+
+## App integration
+
+**Import by path, never re-export from a shared component barrel.** `Editor.svelte` imports `prosekit/basic/style.css` and `prosekit/basic/typography.css` at the top level, and through `createEditor` it pulls the ProseKit runtime behind them — the largest client chunk in the applications this package was extracted from. Whatever module imports this package carries all of that in its chunk, so a route that genuinely edits a document imports a component directly:
+
+```svelte
+<!-- A route that genuinely edits a document -->
+<script lang="ts">
+  import { BlockEditor } from '@thomasfosterau/prosekit-svelte';
+</script>
+```
+
+and a route that only sometimes edits one reaches it behind a dynamic `import()`:
+
+```svelte
+{#await import('@thomasfosterau/prosekit-svelte') then { BlockEditor }}
+  <BlockEditor name="body" {defaultContent} />
+{/await}
+```
+
+Never re-export a component from an **application-wide** component barrel (`$lib/components/index.ts` or similar) and never wire the messages context from a root layout — both put the editor's CSS and runtime into every page's shared chunk. `"sideEffects": false` lets a bundler tree-shake the rest of this package's exports away from a route that only imports one component, but only if nothing else in the bundle reaches this package through a barrel that is itself always loaded.
+
+### The messages context
+
+Every string is already a prop, so a single call site needs nothing here. `setEditorMessages(partial)` is for an application that mounts the editor from several places and would rather not thread twenty props through each: it changes the _defaults_ for one subtree, merged over the English ones, and a caller's own prop still wins.
+
+Call it **per render site** — from the component that mounts the editor, for the reason above — never from a root layout.
+
+```svelte
+<!-- PostBodyField.svelte -->
+<script lang="ts">
+  import { BlockEditor, setEditorMessages } from '@thomasfosterau/prosekit-svelte';
+  import * as m from '$lib/paraglide/messages';
+
+  setEditorMessages({
+    toolbarLabel: m.editor_toolbar(),
+    bold: m.editor_bold(),
+    slashParagraph: m.editor_slash_paragraph(),
+  });
+</script>
+
+<BlockEditor name="body" label={m.post_body()} />
+```
+
+With no provider mounted — Storybook, a test, an application that never wires it — every string is its English default. That is the documented normal case, not an error.
+
+### Forms
+
+Given a `name`, `BlockEditor` and `InlineEditor` emit a hidden input carrying the current document as JSON, in the **application's** envelope shape (`{"type":"blockDocument",…}`), so the field posts with the form and decodes with the shape your document schema declares. `documentType` names the envelope; the components remap to and from ProseMirror's `doc` shape at the boundary in both directions.
+
+A worked example: a form field that composes an app extension and an app toolbar item, and the server action that reads the field back.
+
+```svelte
+<!-- BlockEditorField.svelte -->
+<script lang="ts">
+  import { BlockEditor, createDefaultToolbarItems, type ToolbarItem } from '@thomasfosterau/prosekit-svelte';
+  import type { NodeJSON } from '@thomasfosterau/prosekit-utilities';
+  import { blockExtension } from '$lib/server/document-schema.ts';
+
+  interface Props {
+    defaultContent?: NodeJSON | undefined;
+  }
+  let { defaultContent }: Props = $props();
+
+  const myItem: ToolbarItem = {
+    id: 'sidenote',
+    label: 'Sidenote',
+    kind: 'toggle',
+    isActive: (editor) => editor.nodes['sidenote']?.isActive() ?? false,
+    run: ({ editor }) => void editor.commands['insertNode']?.({ type: 'sidenote' }),
+  };
+</script>
+
+<form method="post" action="?/save">
+  <BlockEditor
+    name="content"
+    extension={blockExtension}
+    {defaultContent}
+    items={[...createDefaultToolbarItems(), myItem]}
+  />
+  <button type="submit">Save</button>
+</form>
+```
+
+```ts
+// +page.server.ts — reading the hidden input's JSON back with the core's DocumentSchema.decode
+import * as Effect from 'effect/Effect';
+import { blockDocumentSchema } from '$lib/server/document-schema.ts';
+
+export const actions = {
+  save: async ({ request }) => {
+    const form = await request.formData();
+    const raw: unknown = JSON.parse(String(form.get('content')));
+
+    // decode: (v: unknown) => Effect.Effect<DocumentJSON<'blockDocument'>, DocumentDecodeError>
+    const body = await Effect.runPromise(
+      blockDocumentSchema
+        .decode(raw)
+        .pipe(Effect.catchTag('DocumentDecodeError', (error) => Effect.die(error))),
+    );
+
+    // … persist `body`.
+  },
+};
+```
+
+`blockDocumentSchema` here is the `DocumentSchema` a server module builds with `@thomasfosterau/prosekit-utilities/prosekit`'s `defineDocumentSchema` — see that package's README for `decode`'s full signature and its `DocumentDecodeError` channel. Feeding the stored envelope straight into ProseKit instead of through this boundary throws `RangeError: Unknown node type`.
+
+# Editors
+
+| Component | Purpose | Props | Snippets | ARIA |
+| --- | --- | --- | --- | --- |
+| `Editor<E extends Extension>` | The bare ProseKit mount; everything else in this package is built on it | `extension: E`, `content?: NodeJSON` (bindable), `defaultContent?: NodeJSON`, `label?`, `labelledBy?` (a visible element's `id`; wins over `label`, which stays the fallback), `class?` + `HTMLAttributes<HTMLDivElement>` without `aria-label` / `aria-labelledby` (`label` / `labelledBy` own the name) | `children?` — rendered inside `<ProseKit>`, **before** the mount node, which is where a toolbar goes | wrapper `role="group"` only when named: `aria-labelledby` given `labelledBy`, `aria-label` given `label` (the name when `labelledBy` resolves to no element); the content is ProseMirror's `.ProseMirror[contenteditable]` node, whose keyboard model is the extension's |
+| `BlockEditor` | `Editor` on the block-document grammar, with the default toolbar, the envelope remap and a hidden form input | `extension?` (default `defineBlockDocumentExtension()`, built lazily), `documentType? = 'blockDocument'`, `content?` (bindable), `defaultContent?` (either shape), `name?`, `items?: ReadonlyArray<ToolbarItem \| ToolbarSeparator>`, `slashCommands?: ReadonlyArray<SlashCommand>`, `toolbar? = true` (`false` renders none, a snippet replaces the default), `label?`, `labelledBy?` (both forwarded to `Editor`), `class?` + `HTMLAttributes<HTMLDivElement>` without `aria-label` / `aria-labelledby` (forwarded to `Editor`'s wrapper; `label` / `labelledBy` own the name) | `toolbar?` — replaces the default `BlockToolbar`; `children?` — rendered after it | as `Editor`. Feeding a stored (`blockDocument`-typed) document straight into ProseKit throws `RangeError: Unknown node type`; this component is the boundary that stops that |
+| `InlineEditor` | One line of rich text: marks but no blocks | `extension?` (default `defineInlineDocumentExtension()` plus the Enter binding), `documentType? = 'inlineDocument'`, `content?` (bindable), `defaultContent?` (either shape), `name?`, `label?`, `labelledBy?` (both forwarded to `Editor`), `class?` + `HTMLAttributes<HTMLDivElement>` without `aria-label` / `aria-labelledby` (forwarded to `Editor`'s wrapper; `label` / `labelledBy` own the name) | `children?` — rendered inside the provider, before the mount node | as `Editor`; **Enter is a no-op** — an inline document's top node is `inline*`, so there is no second block for it to make. The binding lives in the default extension; supply your own `extension` and you own the single-line semantics too |
+
+```svelte
+<script lang="ts">
+  import { BlockEditor } from '@thomasfosterau/prosekit-svelte';
+  let content = $state();
+</script>
+
+<BlockEditor label="Post body" bind:content />
+```
+
+# Toolbar
+
+| Component | Purpose | Props | Snippets | ARIA |
+| --- | --- | --- | --- | --- |
+| `BlockToolbar` | The default toolbar, rendered from a list of items | `items? = createDefaultToolbarItems(messages)`, `slashCommands? = createDefaultSlashCommands(messages)`, `label? = 'Editor toolbar'`, `labelledBy?` (a visible element's `id`; wins over `label`, which stays the fallback), `insertLabel? = 'Insert'`, `insertMenuLabel? = 'Insert block'`, `linkDialog?: Partial<LinkDialogLabels>` (forwarded to `LinkDialog`), `imageDialog?: Partial<ImageDialogLabels>` (forwarded to `ImageDialog`), `class?` + `HTMLAttributes<HTMLDivElement>` without `aria-label` / `aria-labelledby` (on the `role="toolbar"` element; `label` / `labelledBy` own the name) | — (must be rendered inside an `Editor`; it reads the editor from ProseKit's context) | bits-ui `Toolbar.Root`: `role="toolbar"` named by `labelledBy` or else `label`, one tab stop, arrow keys move and wrap, Home/End to the ends, disabled items skipped; `kind: 'toggle'` items carry `aria-pressed` from `isActive` on every editor update; separators are `role="separator"` + `aria-orientation="vertical"` and not a keyboard stop; after a run, focus returns to the document unless the run opened a dialog |
+| `SlashMenu` | The insert menu, exported for a toolbar of your own | `commands: ReadonlyArray<SlashCommand>`, `open?` (bindable, default `false`), `label? = 'Insert'`, `menuLabel? = 'Insert block'`, `labelledBy?` (a visible element's `id`, naming the menu; wins over `menuLabel`, which stays the fallback), `dialogs?: ToolbarRunContext['dialogs']` (omitted, `dialogs.link()` / `dialogs.image()` do nothing), `class?` (on the daisyUI `menu` list inside the content) + `HTMLAttributes<HTMLDivElement>` without `dir`, `aria-label` or `aria-labelledby` (on the `role="menu"` content element, while open; `menuLabel` / `labelledBy` own the name, and an `id` becomes the trigger's `aria-controls`) | `trigger?({ props })` — your own opening control, spreading `props`; omitted, a daisyUI `btn` labelled `label` | bits-ui `DropdownMenu`: `aria-haspopup="menu"` + `aria-expanded` on the trigger, `role="menu"` on the content (named by `labelledBy` or else `menuLabel`), `role="menuitem"` per entry, arrow keys, typeahead, Escape closes and returns focus to the trigger — or to the document after a choice, unless the command opened a dialog |
+| `LinkDialog` | The link prompt, as a modal | `open?` (bindable), `href? = ''` (re-read on every open), `title? = ''`, `onSubmit: (attrs: { href: string; title: string \| null }) => void` (required), `onRemove?` (omitted, no remove button), `titleLabel? = 'Link'`, `hrefLabel? = 'URL'`, `linkTitleLabel? = 'Title (optional)'`, `submitLabel? = 'Apply'`, `removeLabel? = 'Remove link'`, `cancelLabel? = 'Cancel'`, `closeLabel? = 'Close'`, `invalidHrefMessage? = 'Enter an http, https or mailto URL.'`, `class?` + `HTMLAttributes<HTMLDivElement>` without `title` (on the `role="dialog"` element, while open; `role`, `aria-modal` and `aria-labelledby` are bits-ui's, and an `aria-describedby` of yours is kept) | — | bits-ui `Dialog`: `role="dialog"`, `aria-modal="true"`, `aria-labelledby` wired to the title, focus trap, Escape, scroll lock, focus return; a URL that fails `isSafeHref` is refused in a `role="alert"` with `aria-invalid` + `aria-describedby` on the field; the fields are in a `<form>`, so Enter submits |
+| `ImageDialog` | The image prompt, as a modal | `open?` (bindable), `src? = ''`, `onSubmit: (attrs: { src: string }) => void` (required), `titleLabel? = 'Image'`, `srcLabel? = 'Image URL'`, `submitLabel? = 'Insert'`, `cancelLabel? = 'Cancel'`, `closeLabel? = 'Close'`, `invalidSrcMessage? = 'Enter an http, https or mailto URL.'`, `class?` + `HTMLAttributes<HTMLDivElement>` (as `LinkDialog`'s, `title` included) | — | as `LinkDialog` |
+
+`BlockToolbar` renders `LinkDialog` and `ImageDialog` itself and opens them through `ToolbarRunContext.dialogs`; the link dialog is seeded from the selection's own link mark, so its button edits an existing link rather than replacing it, and its remove button runs `removeLink`.
+
+## The toolbar's data model
+
+`BlockToolbar` renders a list rather than a hard-coded row of buttons — an application appends its own item, reorders, drops one, or passes a list of its own making.
+
+```ts
+/** The editor as an item sees it: any grammar, `commands` / `nodes` / `marks` read by name. */
+type ToolbarEditor = Omit<Editor<any>, 'commands' | 'marks' | 'nodes'> & {
+  readonly commands: Record<string, CommandAction>;
+  readonly marks: Record<string, MarkAction>;
+  readonly nodes: Record<string, NodeAction>;
+};
+
+interface ToolbarRunContext {
+  readonly editor: ToolbarEditor;
+  readonly dialogs: { readonly link: () => void; readonly image: () => void };
+}
+
+interface ToolbarItem {
+  readonly id: string;
+  readonly label: string;
+  readonly kind?: ('toggle' | 'action') | undefined; // 'toggle' => aria-pressed from isActive
+  readonly isActive?: ((editor: ToolbarEditor) => boolean) | undefined;
+  readonly isEnabled?: ((editor: ToolbarEditor) => boolean) | undefined; // false => disabled button
+  readonly run: (context: ToolbarRunContext) => void;
+}
+
+interface ToolbarSeparator {
+  readonly id: string;
+  readonly separator: true;
+}
+
+interface SlashCommand {
+  readonly id: string;
+  readonly label: string;
+  readonly run: (context: ToolbarRunContext) => void;
+}
+```
+
+`ToolbarEditor` is not `Editor<any>` because it cannot be: ProseKit derives `commands`, `nodes` and `marks` from the extension's own typing, and the derivation collapses to `never` for `any`, so `editor.commands.toggleBold()` in an item of your own would not compile. A real `Editor<E>` is assignable to `ToolbarEditor`, and naming a command the grammar lacks gets `undefined` rather than a type error.
+
+| Export | Signature | Notes |
+| --- | --- | --- |
+| `isToolbarSeparator` | `(entry: ToolbarItem \| ToolbarSeparator) => entry is ToolbarSeparator` | Narrows an `items` entry to the separator arm. |
+| `createDefaultToolbarItems` | `(messages?: Partial<EditorMessages>) => ReadonlyArray<ToolbarItem \| ToolbarSeparator>` | Nineteen items and two separators, in order: **bold, italic, underline, strike, highlight, subscript, superscript, link** \| **paragraph, heading 2, quote, bullets, numbered, code block, rule, table (3×3), image** \| **undo, redo**. |
+| `createDefaultSlashCommands` | `(messages?: Partial<EditorMessages>) => ReadonlyArray<SlashCommand>` | Ten entries, in order: **paragraph, heading 2, blockquote, bullet list, ordered list, todo list, code block, table, image, horizontal rule**. |
+
+Every default `run` goes through the editor's own `commands`, `marks` and `nodes`, so the set works against any extension registering those node and mark types and quietly does nothing against one that does not — the default item set covers exactly `defineBlockDocumentExtension()`'s grammar; an application composing extra nodes adds their items itself. Extending is appending:
+
+```ts
+import { createDefaultToolbarItems, type ToolbarItem } from '@thomasfosterau/prosekit-svelte';
+
+const sidenote: ToolbarItem = {
+  id: 'sidenote',
+  label: 'Sidenote',
+  kind: 'toggle',
+  isActive: (editor) => editor.nodes['sidenote']?.isActive() ?? false,
+  run: ({ editor }) => void editor.commands['insertNode']?.({ type: 'sidenote' }),
+};
+
+const items = [...createDefaultToolbarItems(), { id: 'app', separator: true }, sidenote];
+```
+
+# Messages
+
+`EditorMessages` is one flat interface of plain strings, grouped here by what they name:
+
+- **Component labels** — `toolbarLabel`, `insertLabel`, `insertMenuLabel`; `linkDialogTitle`, `linkHrefLabel`, `linkTitleLabel`, `linkSubmitLabel`, `linkRemoveLabel`, `linkCancelLabel`, `linkCloseLabel`, `linkInvalidHrefMessage`; `imageDialogTitle`, `imageSrcLabel`, `imageSubmitLabel`, `imageCancelLabel`, `imageCloseLabel`, `imageInvalidSrcMessage`.
+- **Default toolbar item labels** — `bold`, `italic`, `underline`, `strike`, `highlight`, `subscript`, `superscript`, `link`, `paragraph`, `heading2`, `quote`, `bullets`, `numbered`, `codeBlock`, `rule`, `table`, `image`, `undo`, `redo`.
+- **Default insert-menu labels** — `slashParagraph`, `slashHeading2`, `slashBlockquote`, `slashBulletList`, `slashOrderedList`, `slashTodoList`, `slashCodeBlock`, `slashTable`, `slashImage`, `slashHorizontalRule`.
+
+| Export | Signature | Notes |
+| --- | --- | --- |
+| `EditorMessages` | One flat interface of plain `string`s | Every component label prop, plus one key per default item and insert-menu entry. |
+| `defaultEditorMessages` | `EditorMessages` | The English copy every prop falls back to — the applications this package was extracted from shipped these exact item labels, abbreviations included (`P`, `H2`, `Sub`, `Sup`). The default toolbar draws no icons, so an item's label is both its visible text and its accessible name. |
+| `setEditorMessages` | `(messages: Partial<EditorMessages>) => void` | Provides copy for this subtree, merged over the defaults. Per render site, never from a root layout — see [App integration](#app-integration). |
+| `getEditorMessages` | `() => EditorMessages` | Reads it, or `defaultEditorMessages` when no provider is mounted. |
+
+The context key is `Symbol.for('@thomasfosterau/prosekit-svelte/messages')` — a registry symbol, so two copies of the module in one bundle still agree.
+
+## Known limits
+
+- ProseKit's stock `link` mark declares `href`, `target` and `rel` only — no `title`. `LinkDialog`'s `title` field reaches `addLink` and survives only for a grammar whose own `link` mark declares one; against the stock mark, ProseMirror's `computeAttrs` silently drops it.
+- ProseKit's stock `image` node declares `src`, `width` and `height` only, which is why `ImageDialog` asks for one field, deliberately. The applications this package was extracted from also prompted for alt text, a title and a caption, and `computeAttrs` dropped all three — three prompts collecting text that went nowhere. An application whose image node declares more passes its own toolbar item.

package/dist/editor/BlockEditor.svelte

@@ -0,0 +1,66 @@
+<!-- @component An `Editor` on the block-document grammar with the default toolbar (`toolbar`, default `true`), the envelope remap (`documentType`, default `'blockDocument'`, ⇄ `doc`) and, given `name`, a hidden form input carrying the document JSON. -->
+
+<!--
+  BlockEditor — an `Editor` on the block-document grammar, with the default
+  toolbar and a hidden form input.
+
+  Two things it adds over `Editor`.
+
+  The envelope remap. A stored document's root `type` is the application's
+  own name for the surface (`blockDocument` by default); a compiled
+  ProseMirror schema's top node is always `doc`. This component is that
+  boundary, so it remaps in both directions: `defaultContent` is rewritten to
+  `doc` on the way in, and the hidden input always carries the application
+  shape. Feeding the stored shape straight into ProseKit throws
+  `RangeError: Unknown node type: blockDocument` and takes the hosting page
+  down with it — the bug both applications this package was extracted from
+  hit (#459).
+
+  The hidden input. Given a `name`, the editor is a progressive-enhancement
+  form field: the JSON of the current document, in the application's shape,
+  posts with the form.
+
+  `toolbar` is one prop carrying both halves of the design: `true` (the
+  default) renders `BlockToolbar`, `false` renders none, and a snippet —
+  which is what `{#snippet toolbar()}` on the call site passes — replaces it.
+-->
+<script lang="ts">import { fromEditorDocument, toEditorDocument } from "@thomasfosterau/prosekit-utilities";
+import { defineBlockDocumentExtension } from "@thomasfosterau/prosekit-utilities/prosekit";
+import BlockToolbar from "../toolbar/BlockToolbar.svelte";
+import EditorMount from "./Editor.svelte";
+let { extension, documentType = "blockDocument", content = $bindable(), defaultContent, name, items, slashCommands, toolbar = true, label, labelledBy, class: className, children, ...rest } = $props();
+// Built here rather than in the prop default so an application that passes
+// its own extension never constructs the stock one, and so the grammar is
+// captured once — `Editor` creates its editor once for the same reason.
+// svelte-ignore state_referenced_locally
+const resolvedExtension = extension ?? defineBlockDocumentExtension();
+const toStored = $derived(fromEditorDocument(documentType));
+const editorDefaultContent = $derived(defaultContent === undefined ? undefined : toEditorDocument(defaultContent));
+const serialised = $derived.by(() => {
+	const current = content ?? defaultContent;
+	return current === undefined ? undefined : JSON.stringify(toStored(current));
+});
+</script>
+
+<EditorMount
+  {...rest}
+  bind:content
+  extension={resolvedExtension}
+  defaultContent={editorDefaultContent}
+  {label}
+  {labelledBy}
+  class={className}
+>
+  {#if toolbar === true}
+    <BlockToolbar {items} {slashCommands} />
+  {:else if typeof toolbar === 'function'}
+    {@render toolbar()}
+  {/if}
+  {#if children}
+    {@render children()}
+  {/if}
+</EditorMount>
+
+{#if name !== undefined && serialised !== undefined}
+  <input type="hidden" {name} value={serialised} />
+{/if}

package/dist/editor/BlockEditor.svelte.d.ts

@@ -0,0 +1,42 @@
+import { type NodeJSON } from '@thomasfosterau/prosekit-utilities';
+import type { Extension } from 'prosekit/core';
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { SlashCommand, ToolbarItem, ToolbarSeparator } from '../toolbar/items.ts';
+interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'aria-label' | 'aria-labelledby'> {
+    /**
+     * The grammar. Omitted, `defineBlockDocumentExtension()` — built lazily,
+     * so an application passing its own never constructs the default.
+     */
+    extension?: Extension | undefined;
+    /** The envelope `type` of the stored document. */
+    documentType?: string | undefined;
+    /** Two-way bound current content, in editor (`doc`) shape. */
+    content?: NodeJSON | undefined;
+    /** Content the editor is created with, in either shape. */
+    defaultContent?: NodeJSON | undefined;
+    /** Form field name. Given one, a hidden input carries the document's JSON. */
+    name?: string | undefined;
+    /** The toolbar's items. Passed to the default `BlockToolbar`. */
+    items?: ReadonlyArray<ToolbarItem | ToolbarSeparator> | undefined;
+    /** The insert menu's entries. Passed to the default `BlockToolbar`. */
+    slashCommands?: ReadonlyArray<SlashCommand> | undefined;
+    /** `true` for the default toolbar, `false` for none, a snippet to replace it. */
+    toolbar?: boolean | Snippet<[]> | undefined;
+    /** Accessible name of the wrapper. */
+    label?: string | undefined;
+    /**
+     * The `id` (or space-separated `id`s) of the visible element that names
+     * the wrapper, rendered as `aria-labelledby`. Wins over `label`, which
+     * stays the fallback name if no element has the id.
+     */
+    labelledBy?: string | undefined;
+    /** Extra classes on the wrapper. */
+    class?: string | undefined;
+    /** Rendered after the toolbar, inside the editor's provider. */
+    children?: Snippet<[]> | undefined;
+}
+/** An `Editor` on the block-document grammar with the default toolbar (`toolbar`, default `true`), the envelope remap (`documentType`, default `'blockDocument'`, ⇄ `doc`) and, given `name`, a hidden form input carrying the document JSON. */
+declare const BlockEditor: import("svelte").Component<Props, {}, "content">;
+type BlockEditor = ReturnType<typeof BlockEditor>;
+export default BlockEditor;

package/dist/editor/Editor.svelte

@@ -0,0 +1,60 @@
+<!-- @component The ProseKit editor mount: `content` binds two-way, `defaultContent` seeds once, and `children` (a toolbar) renders inside the editor context. Importing it pulls in ProseKit's runtime and stylesheets. -->
+
+<!--
+  Editor — the ProseKit mount, and this package's only side-effecting
+  imports.
+
+  `prosekit/basic/style.css` and `prosekit/basic/typography.css` are bare
+  imports in another package's module graph, so the `"sideEffects": false`
+  this package declares about its own emitted modules still holds. What they
+  do mean is that anything importing this component pulls ProseKit's
+  stylesheets — and, through `createEditor`, the ProseKit runtime — into its
+  chunk. Import it by path from a route that genuinely edits a document, or
+  through a dynamic `import()` from one that only sometimes does, and never
+  re-export it from a barrel an application loads on every page.
+
+  The wrapper is a `role="group"` only when it is named, by `label` or
+  `labelledBy`: a group with no accessible name is noise in the
+  accessibility tree, and the thing that
+  matters — the `contenteditable` textbox ProseMirror builds — is named by
+  the application either way. `children` renders inside `<ProseKit>`, after
+  the mount node, which is where a toolbar goes: it needs the editor context
+  the provider sets.
+-->
+<script lang="ts" generics="E extends import('prosekit/core').Extension">import "prosekit/basic/style.css";
+import "prosekit/basic/typography.css";
+import { createEditor } from "prosekit/core";
+import { ProseKit, useDocChange } from "prosekit/svelte";
+let { extension, content = $bindable(), defaultContent, label, labelledBy, class: className, children, ...rest } = $props();
+// The editor is created once. `extension` and the initial content are
+// captured by value on purpose — reacting to later prop changes would
+// recreate the editor as the user types (see `defaultContent` above).
+// svelte-ignore state_referenced_locally
+const initialContent = defaultContent ?? content;
+// svelte-ignore state_referenced_locally
+const editor = createEditor({
+	extension,
+	// The library's `NodeJSON` is the deeply-readonly twin of ProseKit's; the
+	// value is the same object either way, and `createEditor` only reads it.
+	...initialContent !== undefined && { defaultContent: initialContent }
+});
+// `useDocChange` returns its dispose function, which `$effect` re-uses as
+// the cleanup — ProseKit's hooks are not Svelte-aware, so this is the
+// wiring that unsubscribes the document listener on unmount.
+$effect(() => useDocChange(() => content = editor.getDocJSON(), { editor }));
+</script>
+
+<div
+  {...rest}
+  role={label === undefined && !labelledBy ? undefined : 'group'}
+  aria-label={label}
+  aria-labelledby={labelledBy || undefined}
+  class={['flex flex-col gap-2', className]}
+>
+  <ProseKit {editor}>
+    {#if children}
+      {@render children()}
+    {/if}
+    <div {@attach editor.mount} class="outline-solid p-4"></div>
+  </ProseKit>
+</div>

package/dist/editor/Editor.svelte.d.ts

@@ -0,0 +1,57 @@
+import 'prosekit/basic/style.css';
+import 'prosekit/basic/typography.css';
+import type { NodeJSON } from '@thomasfosterau/prosekit-utilities';
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+declare function $$render<E extends import('prosekit/core').Extension>(): {
+    props: Omit<HTMLAttributes<HTMLDivElement>, "children" | "aria-label" | "aria-labelledby"> & {
+        /** The grammar and behaviour this editor is built from. */
+        extension: E;
+        /** Two-way bound current content; reflects user edits. */
+        content?: NodeJSON | undefined;
+        /**
+         * Content the editor is created with. Decoupled from `content` so an
+         * update form can pre-populate without retriggering editor recreation as
+         * the user types.
+         */
+        defaultContent?: NodeJSON | undefined;
+        /**
+         * Accessible name of the wrapper, and the fallback name when `labelledBy`
+         * names no element. With neither this nor `labelledBy`, the wrapper has
+         * no role.
+         */
+        label?: string | undefined;
+        /**
+         * The `id` (or space-separated `id`s) of the visible element that names
+         * the wrapper, rendered as `aria-labelledby`. Wins over `label`, which
+         * stays the fallback name if no element has the id.
+         */
+        labelledBy?: string | undefined;
+        /** Extra classes on the wrapper. */
+        class?: string | undefined;
+        /** Rendered inside the provider, before the mount node — the toolbar's place. */
+        children?: Snippet<[]> | undefined;
+    };
+    exports: {};
+    bindings: "content";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<E extends import('prosekit/core').Extension> {
+    props(): ReturnType<typeof $$render<E>>['props'];
+    events(): ReturnType<typeof $$render<E>>['events'];
+    slots(): ReturnType<typeof $$render<E>>['slots'];
+    bindings(): "content";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <E extends import('prosekit/core').Extension>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<E>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<E>['props']>, ReturnType<__sveltets_Render<E>['events']>, ReturnType<__sveltets_Render<E>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<E>['bindings']>;
+    } & ReturnType<__sveltets_Render<E>['exports']>;
+    <E extends import('prosekit/core').Extension>(internal: unknown, props: ReturnType<__sveltets_Render<E>['props']> & {}): ReturnType<__sveltets_Render<E>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+/** The ProseKit editor mount: `content` binds two-way, `defaultContent` seeds once, and `children` (a toolbar) renders inside the editor context. Importing it pulls in ProseKit's runtime and stylesheets. */
+declare const Editor: $$IsomorphicComponent;
+type Editor<E extends import('prosekit/core').Extension> = InstanceType<typeof Editor<E>>;
+export default Editor;

package/dist/editor/InlineEditor.svelte

@@ -0,0 +1,55 @@
+<!-- @component A single-line `Editor` on the inline-document grammar (Enter is a no-op), with the same envelope remap and hidden form input as `BlockEditor`. -->
+
+<!--
+  InlineEditor — an `Editor` on the inline-document grammar: one line of
+  rich text, marks but no blocks.
+
+  It carries the same envelope remap and hidden form input as `BlockEditor`
+  (the applications this package was extracted from had the remap on the
+  block editor only, and a separate `InlineEditorInput` wrapper for the
+  field; both are folded in here), and one thing of its own: **Enter is a
+  no-op**. An inline document's top node is `inline*`, so there is no second
+  block for Enter to make; without the binding the base keymap's Enter runs
+  against a document that cannot hold its result, and a field that looks like
+  a single-line input behaves like a textarea.
+
+  That binding lives in the DEFAULT extension. An application passing its own
+  `extension` owns the single-line semantics too — union
+  `defineKeymap({ Enter: () => true })` into it, or accept the base keymap's
+  behaviour.
+-->
+<script lang="ts">import { fromEditorDocument, toEditorDocument } from "@thomasfosterau/prosekit-utilities";
+import { defineInlineDocumentExtension } from "@thomasfosterau/prosekit-utilities/prosekit";
+import { defineKeymap, union } from "prosekit/core";
+import EditorMount from "./Editor.svelte";
+let { extension, documentType = "inlineDocument", content = $bindable(), defaultContent, name, label, labelledBy, class: className, children, ...rest } = $props();
+// Returning `true` claims the key: ProseKit runs the most recently added
+// keymap first, so this shadows the base keymap's Enter rather than racing
+// it.
+// svelte-ignore state_referenced_locally
+const resolvedExtension = extension ?? union(defineInlineDocumentExtension(), defineKeymap({ Enter: () => true }));
+const toStored = $derived(fromEditorDocument(documentType));
+const editorDefaultContent = $derived(defaultContent === undefined ? undefined : toEditorDocument(defaultContent));
+const serialised = $derived.by(() => {
+	const current = content ?? defaultContent;
+	return current === undefined ? undefined : JSON.stringify(toStored(current));
+});
+</script>
+
+<EditorMount
+  {...rest}
+  bind:content
+  extension={resolvedExtension}
+  defaultContent={editorDefaultContent}
+  {label}
+  {labelledBy}
+  class={className}
+>
+  {#if children}
+    {@render children()}
+  {/if}
+</EditorMount>
+
+{#if name !== undefined && serialised !== undefined}
+  <input type="hidden" {name} value={serialised} />
+{/if}

package/dist/editor/InlineEditor.svelte.d.ts

@@ -0,0 +1,36 @@
+import { type NodeJSON } from '@thomasfosterau/prosekit-utilities';
+import { type Extension } from 'prosekit/core';
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'aria-label' | 'aria-labelledby'> {
+    /**
+     * The grammar. Omitted, `defineInlineDocumentExtension()` plus the
+     * Enter binding — built lazily, so an application passing its own never
+     * constructs the default.
+     */
+    extension?: Extension | undefined;
+    /** The envelope `type` of the stored document. */
+    documentType?: string | undefined;
+    /** Two-way bound current content, in editor (`doc`) shape. */
+    content?: NodeJSON | undefined;
+    /** Content the editor is created with, in either shape. */
+    defaultContent?: NodeJSON | undefined;
+    /** Form field name. Given one, a hidden input carries the document's JSON. */
+    name?: string | undefined;
+    /** Accessible name of the wrapper. */
+    label?: string | undefined;
+    /**
+     * The `id` (or space-separated `id`s) of the visible element that names
+     * the wrapper, rendered as `aria-labelledby`. Wins over `label`, which
+     * stays the fallback name if no element has the id.
+     */
+    labelledBy?: string | undefined;
+    /** Extra classes on the wrapper. */
+    class?: string | undefined;
+    /** Rendered inside the editor's provider, after the mount node. */
+    children?: Snippet<[]> | undefined;
+}
+/** A single-line `Editor` on the inline-document grammar (Enter is a no-op), with the same envelope remap and hidden form input as `BlockEditor`. */
+declare const InlineEditor: import("svelte").Component<Props, {}, "content">;
+type InlineEditor = ReturnType<typeof InlineEditor>;
+export default InlineEditor;

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@thomasfosterau/prosekit-svelte` — Svelte 5 editor components on ProseKit.
+ *
+ * `Editor.svelte` carries this package's only side-effecting imports, the
+ * ProseKit basic stylesheets, and through `createEditor` it pulls the
+ * ProseKit runtime behind them. Import a component from here by path from a
+ * route that genuinely edits a document, or through a dynamic `import()`
+ * from one that only sometimes does; never re-export one from a barrel an
+ * application loads on every page.
+ *
+ * @module
+ */
+export { default as BlockEditor } from './editor/BlockEditor.svelte';
+export { default as Editor } from './editor/Editor.svelte';
+export { default as InlineEditor } from './editor/InlineEditor.svelte';
+export { defaultEditorMessages, getEditorMessages, setEditorMessages, type EditorMessages, } from './messages.svelte.ts';
+export { default as BlockToolbar } from './toolbar/BlockToolbar.svelte';
+export { default as ImageDialog } from './toolbar/ImageDialog.svelte';
+export { createDefaultSlashCommands, createDefaultToolbarItems, isToolbarSeparator, type SlashCommand, type ToolbarEditor, type ToolbarItem, type ToolbarRunContext, type ToolbarSeparator, } from './toolbar/items.ts';
+export { default as LinkDialog } from './toolbar/LinkDialog.svelte';
+export { default as SlashMenu } from './toolbar/SlashMenu.svelte';