@thomasfosterau/prosekit-utilities 0.0.0 → 0.1.0

package/dist/prosekit.js

@@ -0,0 +1,827 @@
+import { i as isSafeHref, n as toEditorDocument } from "./envelope-DQS7tt8f.js";
+import { d as attributeOverlay, o as Registry, p as required, s as createRegistryCache } from "./derive-BtbsOqS7.js";
+import * as Array from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as Record from "effect/Record";
+import { createEditor, defineBaseCommands, defineBaseKeymap, defineHistory, defineMarkSpec, defineNodeSpec, htmlFromJSON, union } from "prosekit/core";
+import { defineBold, defineBold as defineBold$1 } from "prosekit/extensions/bold";
+import { defineCode, defineCode as defineCode$1 } from "prosekit/extensions/code";
+import { defineItalic, defineItalic as defineItalic$1 } from "prosekit/extensions/italic";
+import { defineLink, defineLink as defineLink$1 } from "prosekit/extensions/link";
+import { defineStrike, defineStrike as defineStrike$1 } from "prosekit/extensions/strike";
+import { defineUnderline, defineUnderline as defineUnderline$1 } from "prosekit/extensions/underline";
+import { defineDoc } from "prosekit/extensions/doc";
+import { defineText } from "prosekit/extensions/text";
+import { defineParagraph } from "prosekit/extensions/paragraph";
+import { defineHeading } from "prosekit/extensions/heading";
+import { defineList } from "prosekit/extensions/list";
+import { defineBlockquote } from "prosekit/extensions/blockquote";
+import { defineImage } from "prosekit/extensions/image";
+import { defineHorizontalRule } from "prosekit/extensions/horizontal-rule";
+import { defineHardBreak } from "prosekit/extensions/hard-break";
+import { defineTable } from "prosekit/extensions/table";
+import { defineCodeBlock } from "prosekit/extensions/code-block";
+import { defineGapCursor } from "prosekit/extensions/gap-cursor";
+import { defineModClickPrevention } from "prosekit/extensions/mod-click-prevention";
+import { defineVirtualSelection } from "prosekit/extensions/virtual-selection";
+// src/prosekit/attribute-overrides.ts
+/**
+* The attribute overlay this library ships, and how to extend it.
+*
+* ProseMirror exposes a schema's *structure* at runtime but not its attribute
+* *value types*: an `AttributeSpec` carries a `default` and an optional
+* `validate` hint, nothing more. The derivation in
+* `@thomasfosterau/prosekit-utilities/derive` recovers what it can from those
+* and leaves a seam — the attribute overlay — for the rest. This module is
+* that seam pre-filled for ProseKit's stock nodes, plus the merge helper an
+* application uses to add its own entries.
+*
+* @module
+*/
+/** The value schema both table cell types' `colwidth` attribute carries. */
+const TABLE_CELL_COLWIDTH = /* @__PURE__ */ Schema.NullOr(/* @__PURE__ */ Schema.Array(Schema.Finite));
+/**
+* The overlay for ProseKit's stock nodes — the default when
+* `defineDocumentSchema` is given no `attributes`.
+*
+* Every entry here is either a value type ProseMirror cannot express or a
+* required-ness correction, and nothing else needs one: `link`'s
+* `href`/`target`/`rel`, `list`'s `checked`/`collapsed` and the table cells'
+* `colspan`/`rowspan` all derive correctly from ProseMirror's own `validate`
+* string or default value.
+*
+* **Why `required(…)`.** ProseMirror's rule is that *any* attribute with a
+* `default` — even one this overlay supplies a value type for — becomes an
+* omissible key. But `heading.level`, `list.kind`, `image.src`/`width`/`height`
+* and `codeBlock.language` are attributes a live editor always serialises:
+* `Node.toJSON()` includes every attr, defaulted or not, so an
+* editor-produced document always carries them. Leaving them omissible would
+* let a machine-authored document skip the very value it was supposed to
+* specify — a heading with no level, an image with no source — and still
+* validate. `required(…)` closes that gap. `colwidth` is deliberately *not*
+* wrapped: a cell that has never been resized genuinely has none.
+*/
+const STANDARD_ATTRIBUTE_OVERRIDES = {
+	heading: { level: /* @__PURE__ */ required(/* @__PURE__ */ Schema.Literals([
+		1,
+		2,
+		3,
+		4,
+		5,
+		6
+	])) },
+	list: {
+		kind: /* @__PURE__ */ required(/* @__PURE__ */ Schema.Literals([
+			"bullet",
+			"ordered",
+			"task",
+			"toggle"
+		])),
+		order: /* @__PURE__ */ Schema.NullOr(Schema.Finite)
+	},
+	image: {
+		src: /* @__PURE__ */ required(/* @__PURE__ */ Schema.NullOr(Schema.String)),
+		width: /* @__PURE__ */ required(/* @__PURE__ */ Schema.NullOr(Schema.Finite)),
+		height: /* @__PURE__ */ required(/* @__PURE__ */ Schema.NullOr(Schema.Finite))
+	},
+	codeBlock: { language: /* @__PURE__ */ required(Schema.String) },
+	tableCell: { colwidth: TABLE_CELL_COLWIDTH },
+	tableHeaderCell: { colwidth: TABLE_CELL_COLWIDTH }
+};
+/**
+* The overlay entry for `defineMention()`, to merge over
+* {@link STANDARD_ATTRIBUTE_OVERRIDES} when a grammar includes the mention
+* node.
+*
+* Both attributes are `required(…)` for the reason above: a mention the editor
+* produced always carries an id and a label, and a mention without an id
+* resolves to nothing.
+*/
+const MENTION_ATTRIBUTE_OVERRIDES = { mention: {
+	id: /* @__PURE__ */ required(Schema.String),
+	label: /* @__PURE__ */ required(Schema.String)
+} };
+/**
+* Merges overlays left to right, per node and then per attribute; a later
+* entry wins.
+*
+* ```ts
+* const attributes = mergeAttributeOverrides(
+*   STANDARD_ATTRIBUTE_OVERRIDES,
+*   MENTION_ATTRIBUTE_OVERRIDES,
+* );
+* ```
+*
+* The merge is shallow *per node*: two overlays that both name `image` end up
+* with the union of their attribute entries rather than one replacing the
+* other, so an application can override `image.src` alone without restating
+* `width` and `height`. Nothing is mutated — every call returns a new record.
+*/
+const mergeAttributeOverrides = (...overrides) => {
+	return Array.reduce(overrides, {}, (merged, current) => Record.union(merged, current, (left, right) => ({
+		...left,
+		...right
+	})));
+};
+// src/prosekit/lazy-schema.ts
+/**
+* Compile a ProseMirror schema once per isolate, on first use.
+*
+* @module
+*/
+/**
+* Wraps an extension factory in a compile-once, cache-forever thunk.
+*
+* ```ts
+* const schema = lazySchema(() => defineBlockDocumentExtension(defineMention()));
+* schema() === schema(); // the same compiled instance, for the life of the isolate
+* ```
+*
+* **Why lazy.** Compiling a ProseMirror schema builds the whole node and mark
+* registry and the content-match automata for every content expression in it.
+* It is expensive, and the result never changes at runtime. Doing it at module
+* scope would charge that cost to every bundle that so much as names a
+* document type; doing it per call charges it per use.
+*
+* **Why this matters more than it sounds (PERF-CPU-001 in the source
+* applications).** Before this cache existed there, schema validation called
+* `createEditor(...)` on every call — once per jsonb document column on every
+* database row read, and once per server-side document render. An O(1) cost
+* had become O(rows). Anything on a per-row or per-render path must go
+* through a thunk like this one, never `createEditor` directly.
+*
+* The cache is an `Option` rather than a nullable so a schema is never
+* recompiled because a falsy-looking value was cached, and the thunk is a
+* closure rather than a module-scope slot so two grammars never share one.
+*/
+function lazySchema(define) {
+	let compiled = Option.none();
+	return () => {
+		if (Option.isNone(compiled)) {
+			const schema = createEditor({ extension: define() }).schema;
+			compiled = Option.some(schema);
+			return schema;
+		}
+		return compiled.value;
+	};
+}
+// src/prosekit/document-schema.ts
+/**
+* The document wire schema, derived from the editor's own ProseMirror schema.
+*
+* ## What a document schema is for
+*
+* One `DocumentSchema` is a single Effect Schema doing both jobs a document
+* contract has to do:
+*
+* - The persistence and `{@html}`-render **trust boundary**. A jsonb document
+*   column (`@thomasfosterau/prosekit-utilities/drizzle`) decodes and encodes
+*   through `Document` on every read and write, and that is the first half of
+*   the SEC-XSS-001 defence in the source applications — the HTML serialiser's
+*   attribute escaping and link allow-list (`./html.ts`) is the second.
+* - The **generative contract** for whole-document machine emission (agentic
+*   editing, a re-validation guard around a translation service), and the
+*   source for a JSON Schema via `Schema.toJsonSchemaDocument`.
+*
+* ## Where the grammar comes from
+*
+* Node and mark names, groups, the content model — including each node's
+* `+`/`*` non-emptiness and any by-name content restriction, such as the
+* sidenote's `(text | hardBreak)*` — and the admissible marks are read
+* straight off the compiled ProseMirror schema by the `Registry` in
+* `@thomasfosterau/prosekit-utilities/derive`, which walks the compiled
+* `ContentMatch` automaton. There is no hand-transcribed grammar to drift out
+* of sync with the live editor. Attribute value types, which ProseMirror
+* cannot expose, come from the attribute overlay — see
+* `./attribute-overrides.ts`.
+*
+* ## The two halves
+*
+* A `DocumentShape` (the root entry) is the browser-cheap half: it names the
+* surface and checks the envelope structurally, with no ProseKit import.
+* `defineDocumentSchema(shape, …)` is the server half, and `install()` is what
+* joins them — from then on the shape rejects exactly what the derived schema
+* rejects, for the life of the isolate.
+*
+* @module
+*/
+/**
+* A decode that failed, as a tagged error rather than a thrown
+* `SchemaError` — for a caller that wants the failure in an `Effect` channel
+* it can catch by tag.
+*
+* `document` is the shape's name, so one handler can tell a rejected title
+* from a rejected body. `issue` is the underlying `SchemaError` carried
+* through `Schema.Defect()`, which is JSON-encodable, so the error survives a
+* wire hop to a client or a log sink.
+*/
+var DocumentDecodeError = class extends (/* @__PURE__ */ Schema.TaggedError()("DocumentDecodeError", {
+	document: Schema.String,
+	issue: /* @__PURE__ */ Schema.Defect()
+})) {};
+/**
+* Declares the ProseKit half of a document surface.
+*
+* ```ts
+* const blockDocument = defineDocumentShape({ name: 'blockDocument' });   // root entry
+* const cache = createRegistryCache();                                    // ./derive
+*
+* export const blockDocumentSchema = defineDocumentSchema(blockDocument, {
+*   extension: () => defineBlockDocumentExtension(defineMention()),
+*   attributes: mergeAttributeOverrides(STANDARD_ATTRIBUTE_OVERRIDES, MENTION_ATTRIBUTE_OVERRIDES),
+*   registryCache: cache,
+* });
+* ```
+*
+* ## Lazy, all the way down
+*
+* Nothing here compiles or derives anything at declaration time.
+* {@link DocumentSchema.schema} is a `lazySchema` thunk, and `Document` is
+* wrapped in `Schema.suspend`, which defers its body until the schema is first
+* used and memoises it thereafter. So importing the module that declares a
+* document surface — as a model layer or a route module does — never pays for
+* a ProseMirror compile or for building the derived Effect Schema graph unless
+* a document is actually validated (PERF-CPU-001 in the source applications).
+*
+* ## Sharing derivation without coupling
+*
+* Two document schemas built from overlapping extensions — a block grammar and
+* an inline grammar both composing `defineStandardMarks()` and `defineText()` —
+* derive the same mark schemas and the same `text` node schema. Passing both
+* the same `registryCache` means whichever is forced *first* builds that shared
+* structure and the other reuses it.
+*
+* They nonetheless stay **independently lazy and independent failure
+* domains**: validating one never forces compiling or deriving the other, and
+* a defect in one's derivation cannot break the other. That is why this is not
+* `deriveDocumentSchemas`, which batches N schemas in one eager call — it would
+* force compiling every grammar up front and couple their failure domains, for
+* exactly the same sharing benefit this gets without either cost.
+*
+* ## When two grammars may share a cache
+*
+* Only when their **mark sets match** and every node or mark type they both
+* name is defined identically (the same spec and the same attribute overlay).
+* The cache memoises derived schemas by type *name*, and an inline node's
+* derived `marks` field is the union of every mark its grammar's textblocks
+* admit. So two grammars that compose the same `text` node but different marks
+* do not derive the same `text` schema, and whichever is forced first decides
+* it for both.
+*
+* Concretely: a block grammar that adds `defineCitation()` and an inline
+* grammar that does not must not share a cache. If they do, forcing the block
+* schema first makes the inline schema accept a `citation` mark it never
+* declared, and forcing the inline schema first makes the block schema reject
+* its own `citation` marks. Neither order raises an error. Give such grammars
+* separate caches (or none: the default is a private cache).
+*/
+function defineDocumentSchema(shape, options) {
+	const schema = lazySchema(options.extension);
+	const overlay = attributeOverlay(options.attributes ?? STANDARD_ATTRIBUTE_OVERRIDES);
+	const shared = options.registryCache;
+	let own = Option.none();
+	const cacheFor = () => {
+		if (shared !== void 0) return shared;
+		if (Option.isSome(own)) return own.value;
+		const created = createRegistryCache();
+		own = Option.some(created);
+		return created;
+	};
+	const Document = Schema.suspend(() => {
+		const compiled = schema();
+		return new Registry(compiled, { attributes: overlay }, cacheFor()).nodeAs(compiled.topNodeType, shape.name);
+	});
+	const guard = Schema.is(Document);
+	const decodeUnknown = Schema.decodeUnknownEffect(Document);
+	return {
+		shape,
+		extension: options.extension,
+		schema,
+		Document,
+		is: (value) => Result.getOrElse(Result.try(() => guard(value)), () => false),
+		decode: (value) => Effect.mapError(decodeUnknown(value), (issue) => new DocumentDecodeError({
+			document: shape.name,
+			issue
+		})),
+		install: () => {
+			shape.install((value) => guard(value));
+		}
+	};
+}
+/**
+* Installs every schema's grammar guard onto its shape — the persistence
+* layer's one call.
+*
+* ```ts
+* installDocumentGrammars(blockDocumentSchema, inlineDocumentSchema);
+* ```
+*
+* Put it at module scope in the module a server runtime loads before handling
+* a request and no browser bundle can reach (the one that declares the
+* document columns). Installing is cheap — it stores a function reference and
+* forces nothing — and every shape stays permissive until it happens, so a
+* runtime that never installs under-checks rather than wrongly rejects.
+*/
+const installDocumentGrammars = (...schemas) => {
+	Array.forEach(schemas, (schema) => schema.install());
+};
+// src/prosekit/html.ts
+/**
+* HTML generation for editor documents, through ProseKit and a DOM.
+*
+* ProseKit's `htmlFromJSON` serialises through real DOM nodes, so the renderer
+* needs a `Document`. In a browser that is the global one; on a server it is
+* whatever the runtime can provide. See {@link createHtmlRenderer} for how one
+* is chosen and why it must be linkedom rather than happy-dom.
+*
+* Security: {@link sanitiseDocument} runs first on every render, dropping
+* `link` marks and `image` nodes whose URL is not in the safe-URL allow-list.
+* Together with the derived wire schema's decode (`./document-schema.ts`) that
+* is the SEC-XSS-001 defence in the source applications: the schema decides
+* what a document may contain, this decides what a URL may be.
+*
+* @module
+*/
+/**
+* A render that failed.
+*
+* `dom-unavailable` means no `Document` could be obtained: there is no global
+* one and `linkedom` could not be imported (or a caller-supplied `document`
+* thunk rejected). `serialise` means the document itself could not be turned
+* into HTML — most often a node or mark the compiled schema does not know,
+* which is what `htmlFromJSON` throws on. `cause` carries the original through
+* `Schema.Defect()`, so the error is JSON-encodable and survives a log sink.
+*/
+var HtmlRenderError = class extends (/* @__PURE__ */ Schema.TaggedError()("HtmlRenderError", {
+	reason: /* @__PURE__ */ Schema.Literals(["dom-unavailable", "serialise"]),
+	cause: /* @__PURE__ */ Schema.Defect()
+})) {};
+/**
+* A copy of a document tree with every unsafe URL removed: `link` marks whose
+* `href` fails {@link isSafeHref} are dropped from the node that carries them,
+* and `image` children whose `src` fails it are dropped from their parent's
+* content. Recursive, and non-mutating.
+*
+* Dropping the mark rather than the text keeps the prose — an unsafe link
+* renders as plain words — while dropping the whole `image` node is the only
+* option for a leaf whose entire content is its URL.
+*
+* Exported because the same pass belongs at any boundary that hands a document
+* to something which will render it, not only to {@link createHtmlRenderer}.
+*/
+function sanitiseDocument(node) {
+	const copy = { ...node };
+	const marked = Array.isArray(node.marks) ? {
+		...copy,
+		marks: node.marks.filter((mark) => mark.type !== "link" || isSafeHref(mark.attrs?.href))
+	} : copy;
+	return Array.isArray(node.content) ? {
+		...marked,
+		content: node.content.filter((child) => child.type !== "image" || isSafeHref(child.attrs?.src)).map(sanitiseDocument)
+	} : marked;
+}
+/**
+* The default `Document` source, resolved once per isolate.
+*
+* **Capability detection, not an environment flag.** A browser — and vitest's
+* happy-dom environment — provides a global `document`; every server runtime
+* (Node, workerd) does not. `import.meta.env.SSR` is `false` under vitest's
+* *node* environment, so flag-based branching picks the browser path exactly
+* where it must not.
+*
+* **On the server this must be linkedom, not happy-dom.** happy-dom pulls in
+* `node:child_process` and `node:vm`, which workerd does not provide: the
+* import fails at request time and takes down every page that renders prose.
+* linkedom is pure JavaScript and runs anywhere. It is an optional peer for
+* exactly this reason — a browser-only consumer never installs it, and the
+* import below is never reached.
+*
+* The promise, not the document, is cached: concurrent first renders share one
+* import rather than racing several.
+*/
+let defaultDocument = /* @__PURE__ */ Option.none();
+const resolveDefaultDocument = () => {
+	if (Option.isNone(defaultDocument)) {
+		const loading = (async () => {
+			if (!Predicate.isUndefined(globalThis.document)) return globalThis.document;
+			const { parseHTML } = await import("linkedom");
+			return parseHTML("<!doctype html><html><body></body></html>").document;
+		})();
+		defaultDocument = Option.some(loading);
+		return loading;
+	}
+	return defaultDocument.value;
+};
+/**
+* Builds a renderer bound to one compiled schema.
+*
+* ```ts
+* const renderer = createHtmlRenderer({ schema: blockDocumentSchema.schema });
+* const html = await renderer.renderPromise(document);
+* ```
+*
+* A renderer is cheap to create and holds the resolved `Document` promise, so
+* create one per grammar at module scope rather than one per render.
+*
+* Every render sanitises first ({@link sanitiseDocument}), then rewrites the
+* envelope's `type` back to `doc` — the surface name is a persistence rename,
+* and a compiled schema's top node is always `doc`, so feeding the stored
+* shape straight in throws `RangeError: Unknown node type`.
+*/
+function createHtmlRenderer(options) {
+	const documentOf = options.document ?? resolveDefaultDocument;
+	const postProcess = options.postProcess;
+	let resolved = Option.none();
+	const documentPromise = () => {
+		if (Option.isNone(resolved)) {
+			const loading = documentOf();
+			resolved = Option.some(loading);
+			return loading;
+		}
+		return resolved.value;
+	};
+	const serialise = (doc, host) => {
+		const editorDocument = toEditorDocument(sanitiseDocument(doc));
+		const html = htmlFromJSON(editorDocument, {
+			schema: options.schema(),
+			document: host
+		});
+		return postProcess === void 0 ? html : postProcess(html, host);
+	};
+	const hostPromise = () => Result.match(Result.try(documentPromise), {
+		onSuccess: (loading) => loading,
+		onFailure: (cause) => Promise.reject(cause)
+	});
+	const renderPromise = (doc) => hostPromise().then((host) => Result.match(Result.try(() => serialise(doc, host)), {
+		onSuccess: (html) => html,
+		onFailure: (cause) => Promise.reject(new HtmlRenderError({
+			reason: "serialise",
+			cause
+		}))
+	}), (cause) => Promise.reject(new HtmlRenderError({
+		reason: "dom-unavailable",
+		cause
+	})));
+	return {
+		renderPromise,
+		render: (doc) => Effect.tryPromise({
+			try: () => renderPromise(doc),
+			catch: (cause) => cause instanceof HtmlRenderError ? cause : new HtmlRenderError({
+				reason: "serialise",
+				cause
+			})
+		})
+	};
+}
+// src/prosekit/marks.ts
+/**
+* Mark extensions: ProseKit's stock set, re-exported, plus the three marks
+* this library defines itself and the opt-in `citation` mark.
+*
+* `highlight`, `subscript` and `superscript` are **not** taken from
+* `prosekit/extensions/*` even though ProseKit ships same-named extensions:
+* theirs carry different attribute shapes, and the specs here are
+* wire-identical to documents the source applications have already persisted.
+* Since the derived wire schema reads its mark set off the compiled
+* ProseMirror schema, swapping in the stock versions would change what
+* already-stored rows decode as. They are exported individually as well as
+* through {@link defineStandardMarks} so an application composing a narrower
+* grammar can pick them up one at a time.
+*
+* The mark set is half of what constrains rendered HTML — a mark is what
+* turns a run of text into an element — so it is part of the same defence as
+* the HTML serialiser's link allow-list (SEC-XSS-001 in the source
+* applications).
+*
+* @module
+*/
+/** The `highlight` mark: a run of text marked for attention, rendered `<mark>`. */
+function defineHighlight() {
+	return defineMarkSpec({
+		name: "highlight",
+		parseDOM: [{ tag: "mark" }],
+		toDOM() {
+			return ["mark", 0];
+		}
+	});
+}
+/**
+* The `subscript` mark, rendered `<sub>`.
+*
+* Excludes {@link defineSuperscript}'s mark: a run of text is one or the
+* other, never both, and ProseMirror enforces that at the model level rather
+* than leaving it to the toolbar.
+*/
+function defineSubscript() {
+	return defineMarkSpec({
+		name: "subscript",
+		excludes: "superscript",
+		parseDOM: [{ tag: "sub" }],
+		toDOM() {
+			return ["sub", 0];
+		}
+	});
+}
+/** The `superscript` mark, rendered `<sup>`; excludes `subscript` — see {@link defineSubscript}. */
+function defineSuperscript() {
+	return defineMarkSpec({
+		name: "superscript",
+		excludes: "subscript",
+		parseDOM: [{ tag: "sup" }],
+		toDOM() {
+			return ["sup", 0];
+		}
+	});
+}
+/**
+* An inline mark binding a run of text to a cited work by id, rendered
+* `<cite data-work-id>`.
+*
+* A mark rather than a node, deliberately: marks carry no content, so a
+* citation annotates a run of prose and can never swallow structure the way a
+* footnote node could. `workId` is a caller-owned handle and is emitted as a
+* data attribute, never as a URL.
+*
+* Opt-in: not part of {@link defineStandardMarks}, because adding it changes
+* what the derived wire schema accepts.
+*/
+function defineCitation() {
+	return defineMarkSpec({
+		name: "citation",
+		attrs: { workId: { default: "" } },
+		parseDOM: [{
+			tag: "cite[data-work-id]",
+			getAttrs: (dom) => ({ workId: dom.getAttribute("data-work-id") ?? "" })
+		}],
+		toDOM(mark) {
+			return [
+				"cite",
+				{ "data-work-id": mark.attrs.workId },
+				0
+			];
+		}
+	});
+}
+/**
+* The nine marks both presets in `./presets.ts` compose: ProseKit's `bold`,
+* `italic`, `underline`, `strike`, `code` and `link`, plus this library's
+* `highlight`, `subscript` and `superscript`.
+*
+* `citation` is not in the set — it is opt-in, and an application that wants
+* it passes `defineCitation()` as an extra to the preset.
+*/
+function defineStandardMarks() {
+	return union(defineBold$1(), defineItalic$1(), defineUnderline$1(), defineStrike$1(), defineCode$1(), defineLink$1(), defineHighlight(), defineSubscript(), defineSuperscript());
+}
+// src/prosekit/nodes.ts
+/**
+* Node extensions: ProseKit's stock set, re-exported, plus the opt-in node
+* definitions this library adds.
+*
+* The stock re-exports exist so a consumer composes one grammar from one
+* import rather than a dozen `prosekit/extensions/*` specifiers, and so the
+* presets in `./presets.ts` and an application's own extension are provably
+* built from the same definitions.
+*
+* The opt-in nodes below are **not** in either preset. Each one changes what
+* the derived wire schema accepts, and a document written under a grammar
+* that includes `mention` does not decode under one that does not, so adding
+* one is a deliberate act at the application's own `defineBlockDocumentExtension(…)`
+* call site. Every `toDOM` here emits data attributes only — no `href`, no
+* `src` — so the one URL-valued attribute in the stock grammar stays the
+* `image` node's `src`, which `sanitiseDocument` and `isSafeHref` already
+* gate (SEC-XSS-001 in the source applications).
+*
+* @module
+*/
+/**
+* A `doc` top node that accepts inline content only (`content: "inline*"`).
+*
+* The shape a single-line rich-text field wants: marks and text, no
+* paragraphs, no blocks. Each compiled schema owns its own node registry, so
+* this never conflicts with the stock `defineDoc()` (`content: "block+"`) —
+* the two simply belong to different extensions.
+*/
+function defineInlineDoc() {
+	return defineNodeSpec({
+		name: "doc",
+		content: "inline*",
+		topNode: true
+	});
+}
+/**
+* An inline atom that points at an entity by id and carries the text to
+* render for it — the `@name` shape.
+*
+* `id` is the stable handle a consumer resolves (a notification fan-out, a
+* profile link); `label` is display text and is untrusted, which is why
+* `toDOM` emits it as a text child rather than as markup. The node is an
+* atom, so nothing can be typed inside it and the label only ever changes by
+* replacing the whole node.
+*
+* This is deliberately **not** `prosekit/extensions/mention`: ProseKit's stock
+* mention carries a different attribute shape, and this one is wire-identical
+* to documents the source applications have already persisted.
+*/
+function defineMention() {
+	return defineNodeSpec({
+		name: "mention",
+		group: "inline",
+		inline: true,
+		atom: true,
+		attrs: {
+			id: { default: "" },
+			label: { default: "" }
+		},
+		parseDOM: [{
+			tag: "span[data-mention-id]",
+			getAttrs: (dom) => ({
+				id: dom.getAttribute("data-mention-id") ?? "",
+				label: dom.getAttribute("data-mention-label") ?? ""
+			})
+		}],
+		toDOM(node) {
+			const { id, label } = node.attrs;
+			return [
+				"span",
+				{
+					"data-mention-id": id,
+					"data-mention-label": label,
+					class: "mention"
+				},
+				`@${label}`
+			];
+		}
+	});
+}
+/**
+* The caption half of a figure: inline content only.
+*
+* `content: "inline*"` rather than `block+` is what stops a caption nesting a
+* paragraph, a list, or another figure — a caption is a line of prose, and
+* the derived wire schema enforces exactly that because it reads this content
+* expression off the compiled schema.
+*
+* The derived wire schema does not, however, require a figure to carry a
+* caption: see {@link defineFigureNode} for what it does and does not enforce
+* about the pair.
+*/
+function defineFigcaption() {
+	return defineNodeSpec({
+		name: "figcaption",
+		content: "inline*",
+		parseDOM: [{ tag: "figcaption" }],
+		toDOM() {
+			return ["figcaption", 0];
+		}
+	});
+}
+/**
+* A captioned image block: in the editor, exactly one `image` followed by
+* exactly one `figcaption`.
+*
+* The fixed content expression is the point — a figure is a pair, not a
+* container, so ProseMirror's DOM parser and its editing transactions never
+* let either half be dropped or duplicated. `defining` keeps the figure as its
+* own context on paste rather than dissolving into the surrounding block.
+*
+* Loading JSON is not checked the same way: ProseMirror's
+* `schema.nodeFromJSON` validates attributes but not content, and ProseKit's
+* `defaultContent` goes through it, so a stored captionless figure loads into
+* an editor unchecked. A consumer that wants the content expression enforced
+* on a loaded document calls `node.check()`, which ProseKit's
+* `editor.setContent` already does.
+*
+* The derived wire schema is deliberately laxer. Derivation reads the set of
+* admissible children and the empty-vs-non-empty distinction off the compiled
+* content expression, not the ordered sequence (see `derive/Content`), so a
+* stored `figure` decodes when its `content` is any non-empty array of `image`
+* and `figcaption` nodes: a figure without a figcaption, a figcaption alone,
+* the halves reordered or one duplicated all decode. An empty figure and any
+* other child type are still rejected. A consumer that needs the pair enforced
+* at the wire adds its own check, for example `node.check()` on the node it
+* builds from the decoded JSON.
+*
+* Use {@link defineFigure} unless you are composing the two halves yourself:
+* this node is unusable without {@link defineFigcaption} in the same
+* extension, and the stock `image` node besides.
+*/
+function defineFigureNode() {
+	return defineNodeSpec({
+		name: "figure",
+		group: "block",
+		content: "image figcaption",
+		defining: true,
+		parseDOM: [{ tag: "figure" }],
+		toDOM() {
+			return ["figure", 0];
+		}
+	});
+}
+/** {@link defineFigureNode} together with its {@link defineFigcaption} child. */
+function defineFigure() {
+	return union(defineFigureNode(), defineFigcaption());
+}
+/**
+* An inline aside that sits alongside the body prose — a reference note the
+* reader can take or leave, rendered in the margin on wide viewports and as a
+* footnote-like inline block on narrow ones.
+*
+* The note holds **rich inline content** (text plus the surrounding marks),
+* not a plain-text attribute, so a link or emphasis inside a note round-trips
+* through the node's own children on every surface: the editor, the HTML
+* serialiser, the Markdown walk and paste.
+*
+* It is `inline: true` but deliberately **not** `atom`: that is what lets the
+* cursor enter the note and edit its content in place with the same toolbar
+* that styles body prose, with no nested editor and no node view. An `atom`
+* inline node cannot hold editable inline children without one. `selectable`
+* makes the whole note pickable; `defining` keeps its boundary on paste.
+*
+* Its content is `(text | hardBreak)*` — the two text-like inline nodes by
+* name, not the broad `inline` group — so **a note can never nest a note**.
+* `sidenote` is itself in group `inline`, so `content: "inline*"` would admit
+* `^[…^[…]…]`, which has no valid inline-footnote rendering in Markdown; the
+* derived wire schema reads this very expression off the compiled schema and
+* rejects the nesting for free.
+*
+* Placement is a render-time, CSS-only concern: the node is layout-agnostic
+* and ships no styles.
+*/
+function defineSidenote() {
+	return defineNodeSpec({
+		name: "sidenote",
+		group: "inline",
+		inline: true,
+		content: "(text | hardBreak)*",
+		defining: true,
+		selectable: true,
+		parseDOM: [{ tag: "span[data-sidenote]" }],
+		toDOM: () => [
+			"span",
+			{ "data-sidenote": "" },
+			0
+		]
+	});
+}
+// src/prosekit/presets.ts
+/**
+* The two composite extensions an application starts from, and the editor
+* behaviour they share.
+*
+* Each preset takes `...extra` extensions and unions them in last, which is
+* how an opt-in node or mark joins a grammar:
+*
+* ```ts
+* const extension = () =>
+*   defineBlockDocumentExtension(defineMention(), defineFigure(), defineCitation());
+* ```
+*
+* The presets are deliberately not configurable beyond that. A grammar is a
+* wire contract: adding an extension widens what decodes, and an options bag
+* that could *remove* a stock node would silently narrow it for documents
+* already written. Composing a narrower grammar means calling `union` over
+* the node and mark definitions directly.
+*
+* @module
+*/
+/**
+* The interaction tail every editor wants and no document shape depends on:
+* the base keymap, the base commands, undo/redo history, the gap cursor, the
+* virtual selection and mod-click prevention.
+*
+* None of these registers a node or a mark, so including them changes nothing
+* about what a derived wire schema accepts — which is why compiling a schema
+* for validation alone can include them without consequence, and why they are
+* a separate export rather than baked into the node lists.
+*/
+function defineEditorBehaviour() {
+	return union(defineBaseKeymap(), defineBaseCommands(), defineHistory(), defineGapCursor(), defineVirtualSelection(), defineModClickPrevention());
+}
+/**
+* The block-document grammar: a `block+` top node, text, ProseKit's stock
+* block set (paragraph, heading, list, blockquote, image, horizontal rule,
+* hard break, table, code block), {@link defineStandardMarks} and
+* {@link defineEditorBehaviour}, plus whatever `extra` extensions the caller
+* composes in.
+*/
+function defineBlockDocumentExtension(...extra) {
+	return union(defineDoc(), defineText(), defineParagraph(), defineHeading(), defineList(), defineBlockquote(), defineImage(), defineHorizontalRule(), defineHardBreak(), defineTable(), defineCodeBlock(), defineStandardMarks(), defineEditorBehaviour(), ...extra);
+}
+/**
+* The inline-document grammar: an `inline*` top node
+* ({@link defineInlineDoc}), text, {@link defineStandardMarks} and
+* {@link defineEditorBehaviour}, plus whatever `extra` extensions the caller
+* composes in.
+*
+* No block node is registered at all, so a paragraph is not merely
+* unreachable from the toolbar — it fails to decode.
+*/
+function defineInlineDocumentExtension(...extra) {
+	return union(defineInlineDoc(), defineText(), defineStandardMarks(), defineEditorBehaviour(), ...extra);
+}
+export { DocumentDecodeError, HtmlRenderError, MENTION_ATTRIBUTE_OVERRIDES, STANDARD_ATTRIBUTE_OVERRIDES, createHtmlRenderer, defineBlockDocumentExtension, defineBlockquote, defineBold, defineCitation, defineCode, defineCodeBlock, defineDoc, defineDocumentSchema, defineEditorBehaviour, defineFigcaption, defineFigure, defineFigureNode, defineHardBreak, defineHeading, defineHighlight, defineHorizontalRule, defineImage, defineInlineDoc, defineInlineDocumentExtension, defineItalic, defineLink, defineList, defineMention, defineParagraph, defineSidenote, defineStandardMarks, defineStrike, defineSubscript, defineSuperscript, defineTable, defineText, defineUnderline, installDocumentGrammars, lazySchema, mergeAttributeOverrides, sanitiseDocument };