@thomasfosterau/prosekit-flowchart 0.0.0 → 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,181 @@
 # @thomasfosterau/prosekit-flowchart
 
-Placeholder reserved for npm trusted publishing; the first real release is 0.1.0, from https://github.com/thomasfosterau/prosekit-utilities.
+A flowchart block for [ProseKit](https://prosekit.dev) documents, in two entry points. `./node` is the canvas-free half — the ProseMirror node spec and its `updateFlowchartData` command, the [Effect Schema](https://effect.website) payload, a server-renderable SVG, the attribute-override entry, and the HTML / Markdown serialiser hooks — and imports neither Svelte nor `@xyflow/svelte`, so it is safe on a server and in any bundle that never renders the interactive canvas. The root is the `@xyflow/svelte` canvas (`Flowchart`), the edit dialog, the editable node, the ProseKit Svelte node view, and the toolbar / insert-menu entries.
+
+**Why it is its own package.** A component whose behaviour needs a specific third-party dependency lives in its own package adjacent to the editor package, so the editor package stays free of it. Here that dependency is `@xyflow/svelte` — installing this package is the decision to render a flowchart, it is this package's **required** peer, and `@thomasfosterau/prosekit-svelte` never mentions it.
+
+## Installation
+
+```sh
+pnpm add @thomasfosterau/prosekit-flowchart @xyflow/svelte
+```
+
+### Peer requirements
+
+| Package | Range | Why |
+| --- | --- | --- |
+| `@xyflow/svelte` | `^1.6.6`, **required** | The canvas engine, and this package's reason to exist as a package. Reached from exactly one module (`Flowchart.svelte`), which `FlowchartEditDialog` loads through a dynamic `import()` the first time it opens. |
+| `svelte` | `^5.30.1` | The components are compiled by your build, not pre-compiled. |
+| `prosekit` | `^0.22.2` | `defineFlowchart()` registers a node spec on a ProseKit extension; `defineFlowchartNodeView()` is one. |
+| `@prosekit/pm` | `^0.1.19` | The node view's `Node` / `Attrs` types. |
+| `effect` | `^4.0.0` | The payload schemas under `./node`. The root entry imports no Effect itself. |
+
+`@thomasfosterau/prosekit-utilities` and `@thomasfosterau/prosekit-svelte` are not peers — they are ordinary dependencies of this package, at the same release line, and come along automatically when you install it. `bits-ui` does too, for `FlowchartEditDialog`'s `Dialog`.
+
+Tailwind and daisyUI are not declared peers, but they are **required**: every component here emits daisyUI classes (`btn`, `modal-box`, `input`, `text-error`) and ships no CSS of its own. Add this package's `dist/` to Tailwind's sources, or its classes are never emitted:
+
+```css
+@import 'tailwindcss';
+@source '../node_modules/@thomasfosterau/prosekit-svelte/dist';
+@source '../node_modules/@thomasfosterau/prosekit-flowchart/dist';
+@plugin "daisyui";
+```
+
+`@xyflow/svelte/dist/style.css` is imported by `Flowchart.svelte` for its side effect — you do not import it yourself, and it does not arrive on a page that never opens the edit dialog.
+
+## Wiring the block into an editor
+
+`./node` gives an application the grammar; the root gives it the UI. A worked example, threading both through one `blockDocument` surface:
+
+```ts
+// document-schema.ts — server-only: the grammar, and the derived wire schema
+import {
+  defineBlockDocumentExtension,
+  defineDocumentSchema,
+  mergeAttributeOverrides,
+  STANDARD_ATTRIBUTE_OVERRIDES,
+} from '@thomasfosterau/prosekit-utilities/prosekit';
+import {
+  defineFlowchart,
+  FLOWCHART_ATTRIBUTE_OVERRIDES,
+} from '@thomasfosterau/prosekit-flowchart/node';
+import { blockDocument } from './document-shapes.ts';
+
+export const blockDocumentSchema = defineDocumentSchema(blockDocument, {
+  extension: () => defineBlockDocumentExtension(defineFlowchart()),
+  attributes: mergeAttributeOverrides(STANDARD_ATTRIBUTE_OVERRIDES, FLOWCHART_ATTRIBUTE_OVERRIDES),
+});
+```
+
+```ts
+// posts.server.ts — HTML rendering, with the flowchart placeholder filled in
+import { createHtmlRenderer } from '@thomasfosterau/prosekit-utilities/prosekit';
+import { postProcessFlowcharts } from '@thomasfosterau/prosekit-flowchart/node';
+import { blockDocumentSchema } from './document-schema.ts';
+
+export const blockRenderer = createHtmlRenderer({
+  schema: blockDocumentSchema.schema,
+  postProcess: postProcessFlowcharts,
+});
+```
+
+```ts
+// markdown.ts — the Markdown serialiser, with the flowchart placeholder text
+import { createMarkdownSerialiser } from '@thomasfosterau/prosekit-utilities';
+import { flowchartMarkdown } from '@thomasfosterau/prosekit-flowchart/node';
+
+export const toMarkdown = createMarkdownSerialiser({
+  blocks: { flowchart: flowchartMarkdown() },
+});
+```
+
+```svelte
+<!-- Editor.svelte — the editor route: schema half + UI half, composed once -->
+<script lang="ts">
+  import {
+    BlockEditor,
+    createDefaultSlashCommands,
+    createDefaultToolbarItems,
+  } from '@thomasfosterau/prosekit-svelte';
+  import { defineBlockDocumentExtension } from '@thomasfosterau/prosekit-utilities/prosekit';
+  import { defineFlowchart } from '@thomasfosterau/prosekit-flowchart/node';
+  import {
+    defineFlowchartNodeView,
+    flowchartSlashCommand,
+    flowchartToolbarItem,
+  } from '@thomasfosterau/prosekit-flowchart';
+  import { union } from 'prosekit/core';
+
+  const appExtension = defineBlockDocumentExtension(defineFlowchart());
+
+  // The schema half and the view half, composed once.
+  const extension = union(appExtension, defineFlowchartNodeView());
+
+  const items = [...createDefaultToolbarItems(), flowchartToolbarItem()];
+  const slashCommands = [...createDefaultSlashCommands(), flowchartSlashCommand()];
+
+  let content = $state();
+</script>
+
+<BlockEditor {extension} {items} {slashCommands} bind:content />
+```
+
+Server-side, an application keeps only `./node`: `defineFlowchart()` in the extension its document schema derives from, `FLOWCHART_ATTRIBUTE_OVERRIDES` in its attribute overlay, `postProcessFlowcharts` in its HTML renderer, and `flowchartMarkdown()` in its Markdown serialiser. Nothing on that path imports Svelte or `@xyflow/svelte`.
+
+---
+
+# `./node`
+
+The flowchart block without a canvas. Imports no Svelte and no `@xyflow/svelte`, so it is safe on a server, in a Worker, and in any bundle that never renders the interactive canvas; the root entry is what pulls those in.
+
+```ts
+import { defineFlowchart } from '@thomasfosterau/prosekit-flowchart/node';
+```
+
+| Export | Signature | Notes |
+| --- | --- | --- |
+| `FlowchartNode`, `FlowchartEdge`, `FlowchartData` | Effect Schemas (each also the decoded type of the same name): `Schema.Struct({ id, position: { x, y }, data: { label } })`, `Schema.Struct({ id, source, target })`, `Schema.Struct({ nodes: Schema.Array(FlowchartNode), edges: Schema.Array(FlowchartEdge) })` | The persisted shape — a strict subset of what the canvas's own dependency (Svelte Flow) accepts, so its internal fields (selection, measured dimensions) never round-trip. |
+| `FlowchartPosition` | `type FlowchartPosition = FlowchartNode['position']` | Derived, not a separate schema. |
+| `EMPTY_FLOWCHART` | `FlowchartData` (`{ nodes: [], edges: [] }`) | The node spec's attribute default and `parseFlowchartData`'s failure value. |
+| `parseFlowchartData` | `(input: string) => FlowchartData` | Total, never throws. Invalid JSON or a non-object JSON value both yield a fresh `{ ...EMPTY_FLOWCHART }`; missing or non-array `nodes` / `edges` default to `[]`; each node and edge is decoded **individually**, so one malformed entry is dropped rather than failing the whole array. |
+| `generateFlowchartSvg`, `FlowchartSvgLabels` | `(data: FlowchartData, labels?: FlowchartSvgLabels) => string`; `interface FlowchartSvgLabels { emptyLabel?: string \| undefined; diagramLabel?: ((nodeCount: number) => string) \| undefined; untitledLabel?: string \| undefined }` | The three hard-coded strings ("Empty flowchart", `Flowchart diagram with ${n} node(s)`, "Untitled") are individually overridable through `labels`, and each still defaults to that exact copy. Uses `currentColor` strokes and text, `width="100%"`, a viewBox derived from persisted positions plus 20px padding; a label's XML-sensitive characters are escaped. |
+| `defineFlowchart` | `() => Extension` | Registers the `flowchart` node spec (`group: 'block'`, `atom: true`, `isolating: true`, `draggable: true`, `selectable: true`) and the `updateFlowchartData(pos, data)` command. `toDOM` emits `<div data-flowchart data-payload="…">` with the JSON unicode-escaped (`<`, `>`, `&`, `'` → `\uXXXX`) so a label can never break out of the attribute; `parseDOM` prefers `data-payload`, falling back to the element's `textContent` for older documents, then to `parseFlowchartData`'s empty-payload default for anything unparseable. `updateFlowchartData` is a no-op (returns `false`, no dispatch) when the target position is not a `flowchart` node. |
+| `FLOWCHART_ATTRIBUTE_OVERRIDES` | `Readonly<Record<string, Readonly<Record<string, Schema.Top \| RequiredAttribute>>>>` — `{ flowchart: { data: required(FlowchartData) } }` | The overlay entry a consuming app merges into its own attribute overlay (see [Wiring the block into an editor](#wiring-the-block-into-an-editor)). Wrapped in `required(...)`: a live editor's `flowchart` node always serialises `data` (`Node.toJSON()` includes every attribute, defaulted or not), so a machine-authored document must supply it too. |
+| `postProcessFlowcharts` | `(html: string, document: Document) => string` | The `createHtmlRenderer({ postProcess })` hook: replaces every `[data-flowchart]` placeholder's inner HTML with `generateFlowchartSvg`'s output, keeping `data-payload` so the editor can still round-trip the diagram. Short-circuits (returns `html` unchanged) when the string contains no `data-flowchart` at all. Takes the caller's `Document` implementation rather than constructing one, so it works from both a browser bundle and a server-side DOM (linkedom, …). |
+| `flowchartMarkdown` | `(label?: string) => BlockSerialiser` | Default label `'_[flowchart diagram]_'`. A **factory**, unlike this workspace's other opt-in serialisers (`mentionMarkdown`, `figureMarkdown`, `sidenoteMarkdown`), so a consuming app can override the placeholder text without reimplementing the `BlockSerialiser`. Ignores the node's own content — nothing in a `FlowchartData` payload has a faithful Markdown form. |
+
+---
+
+# root
+
+The `@xyflow/svelte` canvas, the edit dialog, the editable node, the ProseKit node view and the toolbar / insert-menu entries. Everything is exported from the package root:
+
+```ts
+import {
+  EditableNode,
+  Flowchart,
+  FlowchartEditDialog,
+  FlowchartNodeView,
+  defineFlowchartNodeView,
+  flowchartSlashCommand,
+  flowchartToolbarItem,
+} from '@thomasfosterau/prosekit-flowchart';
+```
+
+| Component | Purpose | Props | Snippets | ARIA |
+| --- | --- | --- | --- | --- |
+| `Flowchart` | The canvas itself. `interactive={false}` (the default) is a read-only render — no panning, no connecting, nodes immovable, no `Controls`; `interactive={true}` is the full WYSIWYG surface. There is deliberately no `onchange`: the parent pulls the diagram with `getSnapshot()` on save, which keeps the data flow one-way. | `data: FlowchartData` (seeds the canvas once — use `resetTo()` to replace it), `interactive?: boolean \| undefined` (default `false`), `class?: string \| undefined` (default `'h-96'`, merged after `flowchart-canvas`), `summaryLabel?: ((nodes: number, edges: number) => string) \| undefined`, `newNodeLabel?: string \| undefined` (default `'New'`), `nodeLabelLabel?: string \| undefined` (default `'Node label'`), `untitledLabel?: string \| undefined` (default `'Untitled'`), plus native `<div>` attributes (`class` excepted, spread on the container) | — | Server render (`typeof window === 'undefined'`) emits a `<p>` naming `summaryLabel(nodeCount, edgeCount)` in place of the canvas, which hydration replaces; once hydrated, `@xyflow/svelte`'s own accessibility surface applies. |
+| `EditableNode` | The Svelte Flow node type `Flowchart` registers as `editable`. Double-click, or Enter while the node has focus, opens the label field; Enter commits, Escape discards, and a blank label commits as `untitledLabel`. | `NodeProps` narrowed to `id`, `data: EditableNodeData`, `selected` — Svelte Flow instantiates it from the `nodeTypes` map, so there is no call site to pass a prop at. Its copy rides in `data.labels.nodeLabelLabel` / `data.labels.untitledLabel` instead, which `Flowchart` fills from its own same-named props (`EditableNodeData` / `EditableNodeLabels` are this `.svelte` file's own module exports, not re-exported from the package root). | — | `role="button"`; in the tab order (`tabindex="0"`) only while editable (`data.readOnly !== true`) — a reader tabbing through a published diagram is not stopped at every box. The edit field is named by `nodeLabelLabel`. |
+| `FlowchartEditDialog` | The modal that hosts the full WYSIWYG canvas, on bits-ui's `Dialog`. The one behaviour that is this component's own: while `onSave` is in flight, both buttons are disabled and Escape is refused, so a save is never abandoned halfway. | `open?: boolean \| undefined` (bindable, default `false`), `initialData?: FlowchartData \| undefined` (default `EMPTY_FLOWCHART`), `onSave: (data: FlowchartData) => void \| Promise<void>` (may reject), `titleLabel?: string \| undefined` (default `'Edit flowchart'`), `addNodeLabel?: string \| undefined` (default `'Add node'`), `helpText?: string \| undefined`, `saveLabel?` / `savingLabel?: string \| undefined` (default `'Save'` / `'Saving…'`), `cancelLabel?: string \| undefined` (default `'Cancel'`), `closeLabel?: string \| undefined` (default `'Close'`), `failureMessage?: string \| undefined` (shown when `onSave` rejects with something that is not an `Error`), `newNodeLabel?`, `nodeLabelLabel?`, `untitledLabel?: string \| undefined` (forwarded to the hosted `Flowchart`), `class?: string \| undefined` (merged onto the `modal-box`), plus native `<div>` attributes (spread on the `role="dialog"` element, while open; `role`, `aria-modal`, `aria-labelledby` and `aria-describedby` stay bits-ui's) | — | bits-ui's `Dialog` owns the focus trap, `aria-modal`, the `aria-labelledby` / `aria-describedby` wiring to `Dialog.Title` / `Dialog.Description`, the scroll lock and the focus return. The failure message renders in a `role="alert"`. |
+| `FlowchartNodeView` | What ProseKit mounts in place of a `flowchart` node. Its preview is the **same** server-renderable SVG a reader page gets (`generateFlowchartSvg`, from `./node`), so the editor and the published article cannot drift — and so the `@xyflow/svelte` bundle only arrives once the author presses Edit. | `node: Writable<ProseMirrorNode>` (ProseKit's node store), `selected: Writable<boolean>` (ProseKit's selection store), `setAttrs: (attrs: Attrs) => void` (the save channel — Save writes `{ data }` back through it), `editLabel?: string \| undefined` (default `'Edit'`) | — | The wrapper is `contenteditable="false"` and carries `data-prosemirror-node-name="flowchart"`; its border reflects `$selected`. The Edit button is named by `editLabel`. |
+
+Instance methods on `Flowchart`, reached through `bind:this`:
+
+| Method | Signature | What it does |
+| --- | --- | --- |
+| `resetTo` | `(payload: FlowchartData) => void` | Replaces the canvas state. Call it once the canvas has a layout box, so `fitView` has something to fit — `FlowchartEditDialog` calls it inside a `queueMicrotask` after the dialog's content mounts. |
+| `getSnapshot` | `() => FlowchartData` | The persisted shape, with `@xyflow/svelte`'s internal fields (selection, measured dimensions) stripped. |
+| `addNode` | `(label?: string) => void` | Appends a node at a staggered position (diagonally offset by 30px per existing node), so repeated presses do not pile up. Defaults to `newNodeLabel`. |
+
+`FlowchartEditDialog` also exposes an imperative `open(data?: FlowchartData): void`, reached the same way — the entry point `FlowchartNodeView` uses, since it has an instance to reach through `bind:this` but no place to thread a bound prop.
+
+`defineFlowchartNodeView(): Extension` registers `FlowchartNodeView` under the node name `flowchart`, hosted in a `div`, with `ignoreMutation` and `stopEvent` both returning `true` — the diagram rewrites its own DOM (the SVG preview, and the canvas while the dialog is open), and without those guards ProseMirror would read the rewrites as document edits.
+
+The toolbar and insert-menu entries:
+
+| Export | Signature | Notes |
+| --- | --- | --- |
+| `flowchartToolbarItem` | `(label?: string) => ToolbarItem` | A toolbar button (`kind: 'action'` — inserting a block has no pressed state) that inserts a `flowchart` node and returns focus to the document. Default label `'Flowchart'`. |
+| `flowchartSlashCommand` | `(label?: string) => SlashCommand` | The same insertion, as an insert-menu entry. Default label `'Flowchart'`. |
+
+Both insert the starter diagram — one node labelled `'Start'` at `(120, 80)` — rather than an empty payload, because an empty canvas gives an author nothing to double-click and no anchor to drag a connection from. Each insertion builds its own diagram object, so two blocks never share one payload. The insertion is reached by name through the editor's own `commands`, so an entry added to a toolbar whose extension never registered `defineFlowchart()` is inert rather than throwing.

package/dist/EditableNode.svelte

@@ -0,0 +1,111 @@
+<!-- @component The Svelte Flow node type `Flowchart` renders, with an inline-editable label. Svelte Flow instantiates it, so its copy arrives through `data.labels`. -->
+
+<!--
+  EditableNode — the Svelte Flow node type this package's canvas renders, with
+  an inline-editable label.
+
+  Double-click, or Enter while the node has focus, switches to edit mode; Enter
+  or blur commits the new label through `useSvelteFlow().updateNodeData(id, {
+  label })`; Escape restores the label the node had. In read-only mode every
+  edit handler is a no-op and the label renders as static text.
+
+  ## Why its strings arrive through `data`
+
+  Every other component in this workspace takes its user-facing copy as props
+  with English defaults. This one cannot: Svelte Flow instantiates a node
+  component itself, from the `nodeTypes` map, and passes it exactly the
+  `NodeProps` it constructs — a caller has no call site to pass a prop at. So
+  the two strings ride in the node's own `data` (`data.labels`), which
+  `Flowchart` fills from ITS props, and the defaults are applied here. The
+  contract is the same (every string overridable, English default); only the
+  channel differs.
+
+  ## ARIA contract
+
+  The node is `role="button"` — its whole purpose is "activate me to edit" —
+  and is in the tab order only when it is editable (`tabindex=-1` when
+  read-only, so a reader tabbing through a published diagram is not stopped at
+  every box). The edit field is named by `nodeLabelLabel`, because a bare
+  `<input>` inside a node would otherwise be announced as nothing at all.
+-->
+<script module lang="ts">export {};
+</script>
+
+<script lang="ts">import { Handle, Position, useSvelteFlow } from "@xyflow/svelte";
+let { id, data, selected } = $props();
+const flow = useSvelteFlow();
+const nodeLabelLabel = $derived(data.labels?.nodeLabelLabel ?? "Node label");
+const untitledLabel = $derived(data.labels?.untitledLabel ?? "Untitled");
+let editing = $state(false);
+// `draft` only matters while `editing` is true; `startEdit` seeds it from the
+// current `data.label` at that moment.
+let draft = $state("");
+// A `bind:this` target, so the declared type must literally be `T |
+// undefined`: Svelte's compiler assigns the element itself into the variable,
+// and `undefined` before mount and after unmount.
+let inputRef = $state();
+function startEdit() {
+	if (data.readOnly === true) return;
+	draft = data.label;
+	editing = true;
+	queueMicrotask(() => inputRef?.focus());
+}
+function commit() {
+	const trimmed = draft.trim() || untitledLabel;
+	flow.updateNodeData(id, { label: trimmed });
+	editing = false;
+}
+function cancel() {
+	draft = data.label;
+	editing = false;
+}
+function handleKeyDown(event) {
+	if (event.key !== "Enter" && event.key !== "Escape") return;
+	event.preventDefault();
+	// `stopPropagation` is load-bearing, not tidiness. Both handlers close edit
+	// mode synchronously, so without it the same Enter keystroke bubbles to the
+	// node wrapper below, finds `editing` already false, and immediately
+	// reopens the field the user just committed. The browser suite catches it;
+	// no type would.
+	event.stopPropagation();
+	if (event.key === "Enter") commit();
+	else cancel();
+}
+function handleNodeKeyDown(event) {
+	if (data.readOnly !== true && event.key === "Enter" && !editing) {
+		event.preventDefault();
+		startEdit();
+	}
+}
+</script>
+
+<div
+  class="flowchart-node bg-base-100 border-base-300 min-w-32 rounded border px-3 py-2 text-sm shadow-sm"
+  class:border-primary={selected}
+  class:cursor-text={data.readOnly !== true}
+  ondblclick={startEdit}
+  onkeydown={handleNodeKeyDown}
+  role="button"
+  tabindex={data.readOnly === true ? -1 : 0}
+>
+  <Handle type="target" position={Position.Top} isConnectable={data.readOnly !== true} />
+  {#if editing}
+    <input
+      bind:this={inputRef}
+      bind:value={draft}
+      onkeydown={handleKeyDown}
+      onblur={commit}
+      class="input input-xs w-full"
+      aria-label={nodeLabelLabel}
+    />
+  {:else}
+    <span>{data.label || untitledLabel}</span>
+  {/if}
+  <Handle type="source" position={Position.Bottom} isConnectable={data.readOnly !== true} />
+</div>
+
+<style>
+  .flowchart-node {
+    box-sizing: border-box;
+  }
+</style>

package/dist/EditableNode.svelte.d.ts

@@ -0,0 +1,35 @@
+/** Overridable copy for {@link EditableNode}, carried in the node's `data`. */
+export interface EditableNodeLabels {
+    /** Accessible name of the label edit field. Default: `'Node label'`. */
+    readonly nodeLabelLabel?: string | undefined;
+    /** Shown, and committed, when a label is blank. Default: `'Untitled'`. */
+    readonly untitledLabel?: string | undefined;
+}
+/**
+ * The `data` payload {@link EditableNode} expects — the persisted label plus
+ * the two canvas-local fields `Flowchart` derives from its own props.
+ *
+ * A `type` rather than an `interface`, deliberately: Svelte Flow's `Node`
+ * constrains its data to `Record<string, unknown>`, and only a type alias
+ * gets the implicit index signature that satisfies it.
+ */
+export type EditableNodeData = {
+    /** The node's label, as persisted in the flowchart payload. */
+    label: string;
+    /** Set by `Flowchart` from its `interactive` prop; suppresses every edit affordance. */
+    readOnly?: boolean | undefined;
+    /** Copy overrides, passed down from `Flowchart`'s props. */
+    labels?: EditableNodeLabels | undefined;
+};
+import { type NodeProps } from '@xyflow/svelte';
+/**
+ * Svelte Flow's own node props, narrowed to the `data` shape this node type
+ * reads. `id`, `selected` and `data` are the only three it uses.
+ */
+type Props = NodeProps & {
+    data: EditableNodeData;
+};
+/** The Svelte Flow node type `Flowchart` renders, with an inline-editable label. Svelte Flow instantiates it, so its copy arrives through `data.labels`. */
+declare const EditableNode: import("svelte").Component<Props, {}, "">;
+type EditableNode = ReturnType<typeof EditableNode>;
+export default EditableNode;

package/dist/Flowchart.svelte

@@ -0,0 +1,170 @@
+<!-- @component The `@xyflow/svelte` canvas for a `FlowchartData` payload: read-only by default, editable with `interactive`; pull the result with `getSnapshot()`. -->
+
+<!--
+  Flowchart — the `@xyflow/svelte` canvas that renders a `FlowchartData`
+  payload.
+
+  This is the ONE module in the package that imports `@xyflow/svelte`, and with
+  it the package's only side-effecting import,
+  `@xyflow/svelte/dist/style.css`. Everything else — the node spec, the
+  payload schema, the server-renderable SVG the node view previews with —
+  lives under `./node`, which imports neither Svelte nor xyflow. That split is
+  what keeps the canvas bundle off every page that merely displays a diagram.
+
+  Two modes:
+  - `interactive={false}` (the default): a read-only render. No panning, no
+    connecting, nodes immovable, no `Controls`.
+  - `interactive={true}`: the full WYSIWYG canvas. `addNode(label)` appends a
+    node; drag from a node's bottom handle to another's top to connect;
+    double-click a node to edit its label; Delete removes the selection.
+
+  ## Why there is no `onchange`
+
+  The parent reads the current diagram with `getSnapshot()` rather than
+  receiving reactive change events. That keeps the data flow strictly one-way
+  — payload in as a prop, snapshot pulled out on save — and avoids a reactive
+  bounce between the parent's draft state and xyflow's per-frame internal
+  mutations. `resetTo(payload)` is the other direction, and the dialog calls it
+  once the canvas has a real layout box for `fitView` to work against.
+
+  Svelte Flow depends on DOM measurement, so the canvas is gated on a `window`
+  check; a server render emits the `summaryLabel` paragraph instead, which
+  hydration replaces.
+-->
+<script lang="ts">import { Background, Controls, SvelteFlow } from "@xyflow/svelte";
+import "@xyflow/svelte/dist/style.css";
+import { untrack } from "svelte";
+import EditableNode from "./EditableNode.svelte";
+// A library package cannot import SvelteKit's `$app/environment`; this is its
+// portable equivalent (Node SSR and Cloudflare Workers never define `window`,
+// browsers always do).
+const browser = typeof window !== "undefined";
+let { data, interactive = false, class: className = "h-96", summaryLabel = (nodeCount, edgeCount) => `Flowchart with ${nodeCount} node(s) and ${edgeCount} edge(s)`, newNodeLabel = "New", nodeLabelLabel = "Node label", untitledLabel = "Untitled", ...rest } = $props();
+/**
+* The copy `EditableNode` reads out of each node's `data`. Svelte Flow
+* instantiates that component itself, so this is the only channel its two
+* strings can travel down — see its header comment.
+*/
+const labels = $derived({
+	nodeLabelLabel,
+	untitledLabel
+});
+function nodeData(label) {
+	return {
+		label,
+		readOnly: !interactive,
+		labels
+	};
+}
+function toFlowNodes(payload) {
+	return payload.nodes.map((node) => ({
+		id: node.id,
+		type: "editable",
+		position: {
+			x: node.position.x,
+			y: node.position.y
+		},
+		data: nodeData(node.data.label)
+	}));
+}
+function toFlowEdges(payload) {
+	return payload.edges.map((edge) => ({
+		id: edge.id,
+		source: edge.source,
+		target: edge.target
+	}));
+}
+// Local state is seeded from the `data` prop ONCE, inside `untrack` so it
+// deliberately does not subscribe to later changes — `resetTo()` is how a
+// parent replaces the diagram. Subscribing here would loop xyflow's
+// per-frame mutations against the parent's draft.
+let nodes = $state(untrack(() => toFlowNodes(data)));
+let edges = $state(untrack(() => toFlowEdges(data)));
+/** Replace the canvas state with the given payload. */
+export function resetTo(payload) {
+	nodes = toFlowNodes(payload);
+	edges = toFlowEdges(payload);
+}
+/** Strip xyflow's internal state and return the persisted shape. */
+export function getSnapshot() {
+	return {
+		nodes: nodes.map((node) => ({
+			id: node.id,
+			position: {
+				x: node.position.x,
+				y: node.position.y
+			},
+			data: { label: node.data.label ?? "" }
+		})),
+		edges: edges.map((edge) => ({
+			id: edge.id,
+			source: edge.source,
+			target: edge.target
+		}))
+	};
+}
+/** Append a node with the given label at a staggered default position. */
+export function addNode(label = newNodeLabel) {
+	// Stagger new nodes diagonally so repeated "Add node" presses do not pile
+	// them on top of each other.
+	const offset = nodes.length * 30;
+	nodes = [...nodes, {
+		id: newId("n"),
+		type: "editable",
+		position: {
+			x: 60 + offset,
+			y: 60 + offset
+		},
+		data: nodeData(label)
+	}];
+}
+const nodeTypes = { editable: EditableNode };
+function newId(prefix) {
+	return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function handleConnect(connection) {
+	if (!interactive) return;
+	edges = [...edges, {
+		id: newId("e"),
+		source: connection.source,
+		target: connection.target
+	}];
+}
+</script>
+
+<div {...rest} class={['flowchart-canvas', className]}>
+  {#if browser}
+    <SvelteFlow
+      bind:nodes
+      bind:edges
+      {nodeTypes}
+      nodesDraggable={interactive}
+      nodesConnectable={interactive}
+      elementsSelectable={interactive}
+      edgesFocusable={interactive}
+      panOnDrag={interactive}
+      zoomOnScroll={interactive}
+      zoomOnPinch={interactive}
+      zoomOnDoubleClick={false}
+      panOnScroll={false}
+      onconnect={handleConnect}
+      fitView
+    >
+      <Background />
+      {#if interactive}
+        <Controls />
+      {/if}
+    </SvelteFlow>
+  {:else}
+    <p class="text-base-content/60 p-4 text-sm">
+      {summaryLabel(data.nodes.length, data.edges.length)}
+    </p>
+  {/if}
+</div>
+
+<style>
+  .flowchart-canvas {
+    width: 100%;
+    position: relative;
+  }
+</style>

package/dist/Flowchart.svelte.d.ts

@@ -0,0 +1,27 @@
+import '@xyflow/svelte/dist/style.css';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { FlowchartData } from './node/schema.ts';
+interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'class'> {
+    /** Persisted flowchart payload — used to initialise the canvas. */
+    data: FlowchartData;
+    /** Enable the add / move / connect / edit / delete affordances. */
+    interactive?: boolean | undefined;
+    /** Classes on the canvas container; merged last, so they win. */
+    class?: string | undefined;
+    /** The server-render fallback sentence, given the node and edge counts. */
+    summaryLabel?: ((nodes: number, edges: number) => string) | undefined;
+    /** Default label for a node added by {@link addNode}. */
+    newNodeLabel?: string | undefined;
+    /** Accessible name of the label edit field inside a node. */
+    nodeLabelLabel?: string | undefined;
+    /** Shown, and committed, when a node's label is blank. */
+    untitledLabel?: string | undefined;
+}
+/** The `@xyflow/svelte` canvas for a `FlowchartData` payload: read-only by default, editable with `interactive`; pull the result with `getSnapshot()`. */
+declare const Flowchart: import("svelte").Component<Props, {
+    resetTo: (payload: FlowchartData) => void;
+    getSnapshot: () => FlowchartData;
+    addNode: (label?: string) => void;
+}, "">;
+type Flowchart = ReturnType<typeof Flowchart>;
+export default Flowchart;