@thomasfosterau/prosekit-utilities 0.0.0 → 0.1.0

package/dist/index.js

@@ -0,0 +1,723 @@
+import { i as isSafeHref, n as toEditorDocument, r as DEFAULT_SAFE_SCHEMES, t as fromEditorDocument } from "./envelope-DQS7tt8f.js";
+import * as Array from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as HashSet from "effect/HashSet";
+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 String from "effect/String";
+// src/allow-list.ts
+/**
+* Node / mark allow-lists: the narrowing a write seam applies on top of a
+* document's grammar.
+*
+* ## Why an allow-list rather than another compiled schema
+*
+* A document's trust boundary (SEC-XSS-001) is the schema derived from the
+* compiled ProseMirror grammar — one block grammar and one inline grammar,
+* deliberately, so that the editor, the renderer and the column codec never
+* disagree about what a node is. Named surfaces differ only in which subset
+* of that vocabulary they admit: a public comment gets the minimal inline
+* set, an article section gets tables and figures. Those are policy
+* decisions, applied where the surface is known, not separate persistence
+* formats.
+*
+* They are also cheap to apply as a tree-walk and expensive to apply as a
+* schema: the derived schema is `Schema.suspend`-wrapped so the ProseMirror
+* compile stays lazy, and `Schema.check` cannot be appended to a `Suspend`.
+* {@link allowListFilter} is composable onto a `DocumentShape`'s schema
+* (which is not suspended) for that reason; {@link checkAllowList} is the
+* Effect-shaped seam for everything else.
+*
+* Link `href`s are additionally checked against {@link isSafeHref} unless a
+* list opts out — an unsafe scheme is a violation at the write boundary, not
+* merely something the renderer drops later.
+*
+* @module
+*/
+/**
+* Builds an {@link AllowList} from any iterables of node and mark type
+* names — an array literal, a `Set`, another list's `HashSet`.
+*
+* `checkLinkHref` defaults to `true`: an allow-list that admits the `link`
+* mark is opting into untrusted URLs, and the scheme check is the cheap half
+* of that. Pass `false` only where something else already decides.
+*/
+const defineAllowList = (options) => ({
+	label: options.label,
+	nodes: HashSet.fromIterable(options.nodes),
+	marks: HashSet.fromIterable(options.marks),
+	checkLinkHref: options.checkLinkHref ?? true
+});
+/**
+* The first thing an allow-list walk found outside its vocabulary, as data
+* rather than as a bare string.
+*
+* `kind` says which of the three checks failed and `name` says what tripped
+* it (the offending node or mark type), so a caller can map a violation onto
+* its own error envelope without re-parsing `message`. `message` carries the
+* human-readable form both source applications emitted, unchanged, because
+* it is what an API returns to the author.
+*/
+var DocumentViolation = class extends (/* @__PURE__ */ Schema.TaggedError()("DocumentViolation", {
+	label: Schema.String,
+	kind: /* @__PURE__ */ Schema.Literals([
+		"node",
+		"mark",
+		"href"
+	]),
+	name: Schema.String,
+	message: Schema.String
+})) {};
+/**
+* A node's or mark's `type`, or `''` for anything that is not one at all.
+*
+* `''` is in no vocabulary, so a `null`, a stray string or a node missing
+* its `type` reports as a violation rather than throwing halfway through the
+* walk. The walk runs on values a structural check has only proved to be
+* JSON, so that case is reachable.
+*/
+const typeNameOf = (value) => Predicate.isObjectOrArray(value) && Predicate.isString(value.type) ? value.type : "";
+const nodeViolationOf = (allowList, type) => new DocumentViolation({
+	label: allowList.label,
+	kind: "node",
+	name: type,
+	message: `node type "${type}" is not permitted in ${allowList.label}`
+});
+const markViolationOf = (allowList, type) => new DocumentViolation({
+	label: allowList.label,
+	kind: "mark",
+	name: type,
+	message: `mark type "${type}" is not permitted in ${allowList.label}`
+});
+const hrefViolationOf = (allowList) => new DocumentViolation({
+	label: allowList.label,
+	kind: "href",
+	name: "link",
+	message: `link href is not a permitted URL scheme`
+});
+const markViolation = (allowList) => (mark) => {
+	const type = typeNameOf(mark);
+	if (!HashSet.has(allowList.marks, type)) return Result.succeed(markViolationOf(allowList, type));
+	if (allowList.checkLinkHref && type === "link" && !isSafeHref(mark.attrs?.href)) return Result.succeed(hrefViolationOf(allowList));
+	return Result.failVoid;
+};
+const firstMarkViolation = (allowList, node) => {
+	const marks = node.marks;
+	if (!Array.isArray(marks)) return Option.none();
+	return Array.head(Array.filterMap(marks, markViolation(allowList)));
+};
+const firstViolation = (allowList, nodes) => Array.head(Array.filterMap(nodes, nodeViolation(allowList)));
+const nodeViolation = (allowList) => (node) => {
+	const type = typeNameOf(node);
+	if (!HashSet.has(allowList.nodes, type)) return Result.succeed(nodeViolationOf(allowList, type));
+	const marks = firstMarkViolation(allowList, node);
+	if (Option.isSome(marks)) return Result.succeed(marks.value);
+	const content = node.content;
+	if (!Array.isArray(content)) return Result.failVoid;
+	const nested = firstViolation(allowList, content);
+	return Option.isNone(nested) ? Result.failVoid : Result.succeed(nested.value);
+};
+/**
+* The first node or mark type outside `allowList`'s vocabulary — or the
+* first unsafe `link` `href` — in an already shape-valid document.
+*
+* Depth-first in document order, so the violation names the earliest
+* offender, and `Option.none()` when the whole tree is admissible. The
+* envelope's own `type` is not checked against the node list; only its
+* `content` children are.
+*/
+const allowListViolation = (allowList, doc) => firstViolation(allowList, doc.content);
+/**
+* The Effect-shaped write seam: succeeds with the document it was given, or
+* fails with the first {@link DocumentViolation}.
+*
+* Curried so an application can name the check once
+* (`const checkComment = checkAllowList(COMMENT)`) and apply it per write,
+* and generic in the document so the value that comes out is the exact type
+* that went in — including a branded or narrowed one.
+*/
+const checkAllowList = (allowList) => (doc) => Effect.gen(function* () {
+	const violation = allowListViolation(allowList, doc);
+	if (Option.isSome(violation)) return yield* violation.value;
+	return doc;
+});
+/**
+* The same walk as a `Schema.check`-compatible filter, so an allow-list can
+* be composed onto a schema rather than applied beside it.
+*
+* This is what `DocumentShape.narrow` uses. The failure message is the
+* violation's own `message`, so a decode error reads exactly like the
+* write-seam error for the same document.
+*/
+const allowListFilter = (allowList) => Schema.makeFilter((value) => Option.match(allowListViolation(allowList, value), {
+	onNone: () => true,
+	onSome: (violation) => violation.message
+}), {
+	identifier: "documentAllowList",
+	title: `${allowList.label} allow-list`,
+	description: `Rejects a document carrying a node or mark type outside ${allowList.label}'s vocabulary.`
+});
+// src/document-shape.ts
+/**
+* Document shapes: the ProseKit-free view onto a document wire schema.
+*
+* ## Why this module exists
+*
+* A schema derived from a compiled ProseMirror grammar (the ProseKit entry point's
+* `defineDocumentSchema`) has to import the editor runtime — `createEditor`
+* and the whole node / mark registry — to exist at all. A model layer that
+* declares a document-valued attribute is genuinely browser-reachable (API
+* clients, form components), so declaring it with the derived schema
+* statically bundles the editor, the single largest client chunk, into every
+* page including anonymous read-only ones.
+*
+* ## What a shape does instead
+*
+* A {@link DocumentShape} validates the ProseMirror JSON tree
+* **structurally** — the top-level `type`, and that `content` is an array of
+* JSON — with no ProseKit import at all. On top of that sits a pluggable
+* grammar check: a server runtime calls {@link DocumentShape.install} once
+* (the ProseKit entry point's `installDocumentGrammars` does it for a whole set), and
+* from then on the shape rejects exactly what the derived schema rejects.
+*
+* The structural check is a strict superset of the grammar check — anything
+* the compiled ProseMirror schema accepts passes it — so an uninstalled
+* runtime is permissive, never spuriously rejecting. That direction matters:
+* a client that wrongly rejected a valid document would break authoring,
+* whereas a client that wrongly accepts an invalid one is caught by the
+* server that actually decides. SEC-XSS-001's trust boundary is unchanged on
+* the server, and the browser — which is not a trust boundary — gets the
+* structural check alone.
+*
+* @module
+*/
+/**
+* The document's `content`: an array of ProseMirror node JSON, checked only
+* as far as "it is JSON".
+*
+* **Deliberately shallow, and measured.** An earlier version of this check
+* walked the node graph structurally — `type` / `attrs` / `marks` /
+* `content` / `text` per node, recursively. That is redundant work on a
+* server, where the installed grammar guard already checks strictly more
+* than any structural walk can, and near-worthless in a browser, which
+* validates documents the server produced rather than untrusted input. It
+* was not free: on a 20-paragraph document the deep walk cost 0.157 ms
+* against the grammar check's own 0.141 ms — a 1.76x decode, per document,
+* on a path an API runs per row. Flattening to `Schema.Json` takes the
+* structural walk to 0.039 ms (1.26x), and costs the browser only per-node
+* shape errors it was never the right place to catch.
+*
+* `Schema.Json` rather than `Schema.Unknown` because an open leaf here would
+* put a fresh `Unknown` inside the response schema of every endpoint
+* carrying a document attribute, which a wire contract that forbids
+* structurally open response schemas (JSONAPI-WIRE-001 in the source
+* applications) rejects without explicit coercion. `Schema.Json` is closed
+* and JSON-safe by construction — and a non-JSON value (a `Date`, a
+* function) is still rejected rather than waved through.
+*/
+const ContentShape = /* @__PURE__ */ Schema.Array(Schema.Json);
+/**
+* Splits a camel-case shape name into the words a violation message reads
+* with: `blockDocument` → `block document`.
+*/
+const wordsOf = (name) => name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").toLowerCase();
+/**
+* Declares a document surface.
+*
+* ```ts
+* const blockDocument = defineDocumentShape({ name: 'blockDocument' });
+* ```
+*
+* Each call gets its own guard slot, so two shapes never share an install.
+* `label` defaults to the name split into words (`blockDocument` → `block
+* document`), which is what the validation message reads with: `must be a
+* valid block document`.
+*/
+function defineDocumentShape(options) {
+	const name = options.name;
+	const label = options.label ?? wordsOf(name);
+	let grammar = Option.none();
+	const documentSchema = Schema.Struct({
+		type: Schema.Literal(name),
+		content: ContentShape
+	}).pipe(Schema.check(Schema.makeFilter((value) => {
+		const check = grammar;
+		return Option.isNone(check) || check.value(value) ? true : `must be a valid ${label}`;
+	}, {
+		identifier: `${name}Grammar`,
+		title: `${label} grammar`,
+		description: `Rejects a structurally valid ProseMirror tree that the installed ${label} grammar does not accept.`
+	})));
+	const guard = Schema.is(documentSchema);
+	return {
+		name,
+		label,
+		Schema: documentSchema,
+		is: (value) => Result.getOrElse(Result.try(() => guard(value)), () => false),
+		install: (installed) => {
+			grammar = Option.some(installed);
+		},
+		isInstalled: () => Option.isSome(grammar),
+		empty: () => ({
+			type: name,
+			content: []
+		}),
+		narrow: (allowList) => documentSchema.pipe(Schema.check(allowListFilter(allowList)))
+	};
+}
+// src/document-text.ts
+/**
+* Plain-text extraction from a ProseMirror document.
+*
+* Two joins, because two callers want different things. A search index or an
+* embedding queue wants block text with word boundaries preserved across
+* nodes ({@link extractDocumentText}, `' '`); a title rendered back into
+* prose must not gain spaces its author never typed
+* ({@link inlineDocumentText}, `''`).
+*
+* Both are pure, total and DOM-free, so they run anywhere — including a
+* Worker with no document.
+*
+* @module
+*/
+/**
+* Extracts plain text from a document, joining the `text` leaves with
+* `options.separator` (default `' '`).
+*
+* Tolerant by design: `null`, `undefined`, a document with no `content`, a
+* stray string or `null` inside `content`, and a `text`-typed node whose
+* `text` is not a string all contribute nothing rather than throwing. The
+* callers are database columns and queue payloads, where a malformed row
+* must degrade to empty text rather than fail a batch.
+*/
+function extractDocumentText(doc, options) {
+	if (!doc || !doc.content) return "";
+	return textParts(doc.content).join(options?.separator ?? " ");
+}
+/** The `text` leaves of one node subtree, in document order. */
+function textParts(nodes) {
+	return Array.flatMap(nodes, (node) => {
+		if (!Predicate.isObjectOrArray(node)) return [];
+		const own = Predicate.hasProperty(node, "type") && node.type === "text" && Predicate.hasProperty(node, "text") && Predicate.isString(node.text) ? [node.text] : [];
+		return Predicate.hasProperty(node, "content") && Array.isArray(node.content) ? [...own, ...textParts(node.content)] : own;
+	});
+}
+/**
+* Extracts plain text from an inline document, joining the `text` leaves
+* with nothing at all.
+*
+* This is the form a title or other flat field wants: `extractDocumentText`
+* would turn `Rosa` + `canina` (two runs, one styled) into `Rosa canina`
+* with a space that is already in the first run, or into `Rosacanina` with
+* one missing — the `''` join keeps whatever whitespace the author wrote.
+* Recurses into any node that carries `content`, so a wrapping inline node
+* (a sidenote, a mention) still contributes its text.
+*/
+function inlineDocumentText(doc) {
+	return inlineTextParts(doc).join("");
+}
+/** The `text` leaves of a document subtree, in document order. */
+function inlineTextParts(node) {
+	return Array.flatMap(node?.content ?? [], (child) => child.text ? [child.text] : "content" in child ? inlineTextParts(child) : []);
+}
+// src/markdown/escape.ts
+/**
+* CommonMark escaping for literal text.
+*
+* @module
+*/
+/** Every CommonMark inline metacharacter, in one class. */
+const METACHARACTERS = /([\\`*_{}[\]()#+\-.!<>|~])/g;
+/**
+* Backslash-escapes the CommonMark inline metacharacters in literal text, so
+* an author's `*` stays an asterisk instead of opening emphasis.
+*
+* Exported because an application's own node serialiser emits literal text
+* too — a mention's `@label`, a caption — and must escape it the same way
+* the stock serialisers do.
+*/
+function escapeMarkdown(text) {
+	return text.replace(METACHARACTERS, "\\$1");
+}
+// src/markdown/stock.ts
+/**
+* The stock Markdown cases: every node and mark in the shared base grammar.
+*
+* These are what `createMarkdownSerialiser` starts from, and an application
+* may replace any of them by name. They are exported individually so one can
+* be reused inside a replacement (a custom `image` that adds alt text can
+* still defer to `imageMarkdown` for the safe-URL check).
+*
+* @module
+*/
+/**
+* A node's children as an array, whether or not it has any.
+*
+* Shared by the engine and by every serialiser that renders its own
+* children, so a missing `content` is one empty array rather than a
+* different guard in each case.
+*/
+const childrenOf = (node) => node.content ?? [];
+/** `` `code` `` — verbatim, so the engine skips escaping and other emphasis. */
+const codeMarkdown = (text) => `\`${text}\``;
+/** `~~strike~~`. */
+const strikeMarkdown = (text) => `~~${text}~~`;
+/** `*italic*`. */
+const italicMarkdown = (text) => `*${text}*`;
+/** `**bold**`. */
+const boldMarkdown = (text) => `**${text}**`;
+/**
+* `[text](href)`, but only for an `href` the safe-URL allow-list admits — an
+* unsafe scheme degrades to the plain (still styled) link text rather than
+* emitting an executable URI.
+*/
+const linkMarkdown = (text, mark) => {
+	const href = mark.attrs?.href;
+	return isSafeHref(href) ? `[${text}](${href.trim()})` : text;
+};
+/**
+* The marks with a Markdown rendering.
+*
+* Underline, highlight, subscript and superscript are deliberately absent:
+* CommonMark has no form for them, and a mark with no entry passes its text
+* through unchanged, which is what both source applications do.
+*/
+const stockMarks = {
+	bold: boldMarkdown,
+	code: codeMarkdown,
+	italic: italicMarkdown,
+	link: linkMarkdown,
+	strike: strikeMarkdown
+};
+/**
+* A hard break as a backslash line break, which is more robust than two
+* trailing spaces (an editor or a diff tool that trims trailing whitespace
+* cannot silently delete it).
+*/
+const hardBreakMarkdown = () => "\\\n";
+/** The inline nodes in the shared base grammar. */
+const stockInlines = { hardBreak: hardBreakMarkdown };
+/** A paragraph: its inline content, nothing more. */
+const paragraphMarkdown = (node, context) => context.serialiseInline(childrenOf(node));
+/** `## Heading`, clamped into the 1..6 range CommonMark defines. */
+const headingMarkdown = (node, context) => {
+	const declared = Predicate.isNumber(node.attrs?.level) ? node.attrs.level : 1;
+	const level = Math.min(Math.max(declared, 1), 6);
+	return `${"#".repeat(level)} ${context.serialiseInline(childrenOf(node))}`;
+};
+/** `> quoted`, with a bare `>` on the blank lines between inner blocks. */
+const blockquoteMarkdown = (node, context) => context.serialiseBlocks(childrenOf(node)).split("\n").map((line) => String.isNonEmpty(line) ? `> ${line}` : ">").join("\n");
+/**
+* A fenced code block.
+*
+* The language token is stripped of newlines and backticks so it cannot
+* break out of the fence line, and the fence itself is at least one
+* backtick longer than the longest run inside the code, so embedded triple
+* backticks cannot close the block early.
+*/
+const codeBlockMarkdown = (node) => {
+	const language = (Predicate.isString(node.attrs?.language) ? node.attrs.language : "").replace(/[\n\r`]/g, "");
+	const code = childrenOf(node).map((child) => child.text ?? "").join("");
+	const longestRun = Math.max(0, ...[...code.matchAll(/`+/g)].map((match) => match[0].length));
+	const fence = "`".repeat(Math.max(3, longestRun + 1));
+	return `${fence}${language}\n${code}\n${fence}`;
+};
+/** `---`. */
+const horizontalRuleMarkdown = () => "---";
+/**
+* `![](src)` for a `src` the safe-URL allow-list admits; the empty string
+* otherwise, which drops the block from the output entirely.
+*/
+const imageMarkdown = (node) => {
+	const src = node.attrs?.src;
+	return isSafeHref(src) ? `![](${src.trim()})` : "";
+};
+/**
+* A GitHub-flavoured pipe table, best-effort: the first row becomes the
+* header, every row is padded out to the widest row's column count, and a
+* cell's own block structure is flattened onto one line with its pipes
+* escaped.
+*/
+const tableMarkdown = (node, context) => {
+	const cellText = (cell) => context.serialiseBlocks(childrenOf(cell)).trim().replace(/\n+/g, " ").replace(/\|/g, "\\|");
+	return Array.match(childrenOf(node).filter((row) => row.type === "tableRow"), {
+		onEmpty: () => "",
+		onNonEmpty: (rows) => {
+			const [header, ...body] = Array.map(rows, (row) => childrenOf(row).map(cellText));
+			const columns = Math.max(header.length, ...body.map((row) => row.length), 1);
+			const pad = (cells) => `| ${Array.pad(cells, columns, "").join(" | ")} |`;
+			return [
+				pad(header),
+				`| ${Array.replicate("---", columns).join(" | ")} |`,
+				...body.map(pad)
+			].join("\n");
+		}
+	});
+};
+/**
+* The block nodes in the shared base grammar.
+*
+* `list` is absent on purpose: consecutive `list` siblings are one list in
+* the prosemirror-flat-list model, so the run, not the node, is the unit of
+* serialisation and the engine owns it.
+*/
+const stockBlocks = {
+	blockquote: blockquoteMarkdown,
+	codeBlock: codeBlockMarkdown,
+	heading: headingMarkdown,
+	horizontalRule: horizontalRuleMarkdown,
+	image: imageMarkdown,
+	paragraph: paragraphMarkdown,
+	table: tableMarkdown
+};
+// src/markdown/serialiser.ts
+/**
+* The Markdown serialiser engine: the dispatch, the mark ladder and the
+* prosemirror-flat-list run model that every stock and application node
+* serialiser plugs into.
+*
+* Walks the ProseMirror document JSON tree directly (no DOM) and emits
+* clean, CommonMark-flavoured Markdown — the representation an agent-facing
+* `Accept: text/markdown` surface serves. A pure, dependency-free tree-walk,
+* so it runs on a Worker without a DOM shim, unlike the HTML serialiser in
+* the ProseKit entry point.
+*
+* Security: link `href`s and image `src`s go through the same `isSafeHref`
+* allow-list the HTML serialiser uses; an unsafe `href` degrades to plain
+* link text, never an executable URI.
+*
+* @module
+*/
+/**
+* Emphasis marks in the order they wrap, innermost first.
+*
+* Fixed rather than document order, because a text run's `marks` array is in
+* whatever order the editor happened to add them and `***~~x~~***` must come
+* out the same way every time. A mark outside this list (an application's
+* own) wraps after these and before the link.
+*/
+const EMPHASIS_ORDER = [
+	"strike",
+	"italic",
+	"bold"
+];
+/** One nesting level of list indentation. */
+const LIST_INDENT = "  ";
+/**
+* The serialiser registered for a type name: the application's own entry if
+* it has one, the stock entry otherwise — the application's map merged over
+* the stock one.
+*/
+const serialiserLookup = (stock, overrides) => (type) => Option.fromNullishOr(overrides[type] ?? stock[type]);
+/** Marker for one list item, given the list node and its position. */
+const listMarker = (item, index) => {
+	const attrs = item.attrs;
+	if (attrs === void 0) return "- ";
+	if (attrs.kind === "ordered") return `${(Predicate.isNumber(attrs.order) ? attrs.order : 1) + index}. `;
+	if (attrs.kind === "task") return attrs.checked === true ? "- [x] " : "- [ ] ";
+	return "- ";
+};
+/** The first of `marks` whose type is `type`. */
+const markOfType = (marks, type) => Array.findFirst(marks, (mark) => mark.type === type);
+/**
+* Builds a Markdown serialiser.
+*
+* The stock cases — paragraph, heading, blockquote, code block, horizontal
+* rule, image, table, hard break and the five marks with a Markdown form —
+* are built in, along with the flat-list run model and the fallback that
+* emits an unknown node's inline text rather than dropping it. `blocks`,
+* `inlines` and `marks` are merged **over** the stock maps, so an
+* application adds its own nodes (and may replace a stock one) without
+* restating any of this:
+*
+* ```ts
+* const toMarkdown = createMarkdownSerialiser({
+*   inlines: { mention: mentionMarkdown },
+*   blocks: { figure: figureMarkdown },
+* });
+* ```
+*
+* `list` is the one type a `blocks` entry cannot override: consecutive
+* `list` siblings are one list, so the run — not the node — is the unit of
+* serialisation, and that grouping lives here.
+*/
+function createMarkdownSerialiser(options) {
+	const blocks = serialiserLookup(stockBlocks, options?.blocks ?? {});
+	const inlines = serialiserLookup(stockInlines, options?.inlines ?? {});
+	const marks = serialiserLookup(stockMarks, options?.marks ?? {});
+	/** Wraps `text` in `mark`'s syntax when a serialiser exists for it. */
+	const applyMark = (text, mark) => Option.match(marks(mark.type), {
+		onNone: () => text,
+		onSome: (serialiser) => serialiser(text, mark)
+	});
+	/**
+	* Applies a text node's marks to its text.
+	*
+	* `code` is verbatim: its content is never escaped and the other emphasis
+	* marks do not wrap a code span, because they have no meaning inside one.
+	* A `link` always wraps outermost, so the styled text becomes the label.
+	* A mark with no serialiser (underline, highlight, sub- and superscript
+	* have no Markdown form) passes through as plain styled-or-unstyled text.
+	*/
+	const applyMarks = (text, nodeMarks) => Array.match(nodeMarks, {
+		onEmpty: () => escapeMarkdown(text),
+		onNonEmpty: (present) => {
+			const verbatim = Option.zipWith(markOfType(present, "code"), marks("code"), (codeMark, serialiser) => serialiser(text, codeMark));
+			const styled = Option.getOrElse(verbatim, () => Array.reduce(present, Array.reduce(EMPHASIS_ORDER, escapeMarkdown(text), (out, type) => Option.match(markOfType(present, type), {
+				onNone: () => out,
+				onSome: (mark) => applyMark(out, mark)
+			})), (out, mark) => mark.type === "code" || mark.type === "link" || EMPHASIS_ORDER.includes(mark.type) ? out : applyMark(out, mark)));
+			return Option.getOrElse(Option.zipWith(markOfType(present, "link"), marks("link"), (link, serialiser) => serialiser(styled, link)), () => styled);
+		}
+	});
+	/** Serialise a run of inline nodes to a single line-ish string. */
+	const serialiseInline = (nodes) => Array.map(nodes, (node) => node.type === "text" && Predicate.isString(node.text) ? applyMarks(node.text, node.marks ?? []) : Option.match(inlines(node.type), {
+		onNone: () => "",
+		onSome: (serialiser) => serialiser(node, context)
+	})).join("");
+	/**
+	* Serialise a run of sibling `list` nodes. In the prosemirror-flat-list
+	* model each `list` node is one item and consecutive siblings form the
+	* list; a nested list is a `list` child inside an item's content, so it
+	* recurses with deeper indentation.
+	*/
+	const serialiseListRun = (items, indent) => Array.flatMap(items, (item, index) => {
+		const marker = listMarker(item, index);
+		const itemBlocks = childrenOf(item);
+		const ownBlocks = itemBlocks.filter((child) => child.type !== "list");
+		const nested = itemBlocks.filter((child) => child.type === "list");
+		const body = serialiseBlocks(ownBlocks).trim();
+		const continuation = indent + " ".repeat(marker.length);
+		const bodyLines = body.split("\n");
+		const line = indent + marker + (bodyLines[0] ?? "") + bodyLines.slice(1).map((next) => "\n" + (String.isNonEmpty(next) ? continuation + next : "")).join("");
+		return Array.match(nested, {
+			onEmpty: () => [line],
+			onNonEmpty: (sublist) => [line, serialiseListRun(sublist, indent + LIST_INDENT)]
+		});
+	}).join("\n");
+	/** Serialise a single block node (no trailing blank line). */
+	const serialiseBlock = (node) => Option.match(blocks(node.type), {
+		onSome: (serialiser) => serialiser(node, context),
+		onNone: () => serialiseInline(childrenOf(node))
+	});
+	/**
+	* Serialise an array of block nodes, grouping consecutive `list` siblings
+	* into one list and separating blocks with blank lines. Every other block
+	* is a group of its own, and one that renders to nothing is dropped.
+	*/
+	const serialiseBlocks = (nodes) => Array.match(nodes, {
+		onEmpty: () => "",
+		onNonEmpty: (present) => Array.filterMap(Array.groupWith(present, (left, right) => left.type === "list" && right.type === "list"), (group) => {
+			if (group[0].type === "list") return Result.succeed(serialiseListRun(group, ""));
+			const rendered = serialiseBlock(group[0]);
+			return String.isNonEmpty(rendered) ? Result.succeed(rendered) : Result.failVoid;
+		}).join("\n\n")
+	});
+	const context = {
+		serialiseInline,
+		serialiseBlocks,
+		escape: escapeMarkdown
+	};
+	return {
+		document: (doc) => serialiseBlocks(childrenOf(doc)).trim(),
+		inline: (doc) => serialiseInline(childrenOf(doc)).trim()
+	};
+}
+// src/markdown/optional.ts
+/**
+* Markdown cases for the opt-in nodes — the ones an application composes
+* into its grammar rather than getting for free.
+*
+* Each is an ordinary {@link BlockSerialiser} / {@link InlineSerialiser}, so
+* it is wired in through `createMarkdownSerialiser`'s option maps:
+*
+* ```ts
+* const toMarkdown = createMarkdownSerialiser({
+*   blocks: { figure: figureMarkdown },
+*   inlines: { mention: mentionMarkdown, sidenote: sidenoteMarkdown },
+* });
+* ```
+*
+* They exist because a node with no faithful Markdown form must still emit
+* its closest textual equivalent rather than vanish: the Markdown has to
+* stay a truthful reflection of what the HTML renders.
+*
+* @module
+*/
+/**
+* A mention as its `@label`, escaped.
+*
+* The referenced account's id has no Markdown form and is dropped: a
+* mention is a link to something only the application can resolve, so the
+* text is all that survives. The label is escaped like any other literal
+* text, so a display name containing `*` cannot open emphasis.
+*/
+const mentionMarkdown = (node, context) => {
+	const label = Predicate.isString(node.attrs?.label) ? node.attrs.label : "";
+	return context.escape(`@${label}`);
+};
+/**
+* A figure as its image line followed by the caption as an italic
+* paragraph — Markdown has no figure element, and this is the form a reader
+* renders closest to one.
+*
+* A figure whose image is dropped (an unsafe `src`) still emits its caption;
+* a figure with no caption emits the image line alone.
+*/
+const figureMarkdown = (node, context) => {
+	const [image, caption] = childrenOf(node);
+	const imageLine = image === void 0 ? "" : context.serialiseBlocks([image]);
+	const captionText = caption === void 0 ? "" : context.serialiseInline(childrenOf(caption)).trim();
+	return String.isNonEmpty(captionText) ? `${imageLine}\n_${captionText}_` : imageLine;
+};
+/**
+* A sidenote as a Pandoc inline footnote (`^[note]`).
+*
+* This is the established Markdown form for a reference aside with no
+* separate definition block: it keeps the note where it sits in the prose
+* and renders as a footnote in Pandoc-flavoured pipelines, the closest
+* faithful analogue to a margin note. `^[…]` is a Pandoc extension, not core
+* CommonMark; a plain CommonMark reader shows the bracketed content inline,
+* which still reads as a parenthetical aside.
+*
+* The note holds rich inline content, so its children go through the same
+* inline pass body prose does — `^[…]` legitimately contains inline Markdown
+* (`[t](u)`, `*em*`, `` `code` ``), and literal `[` / `]` in a text run is
+* already backslash-escaped so it cannot close the note early. Any newline
+* (a hard break renders as `\␤`) is collapsed to a space afterwards: a
+* literal newline would terminate the inline footnote and split the
+* surrounding paragraph.
+*
+* A nested sidenote is flattened to its body first. A grammar restricting a
+* sidenote to `(text | hardBreak)*` rules one out, but a persistence guard
+* checks the node registry rather than content expressions, so a
+* hand-crafted or migrated document can still carry one — and `^[…^[…]…]`
+* has no valid Pandoc rendering, since the inner `]` closes the outer note.
+*/
+const sidenoteMarkdown = (node, context) => {
+	const inlineChildren = childrenOf(node).flatMap((child) => child.type === "sidenote" ? childrenOf(child) : [child]);
+	const body = context.serialiseInline(inlineChildren).replace(/\\?\n/g, " ").trim();
+	return String.isNonEmpty(body) ? `^[${body}]` : "";
+};
+// src/markdown/index.ts
+/**
+* Markdown serialisation for ProseKit documents.
+*
+* `createMarkdownSerialiser` builds one; `toMarkdown` is the ready-made
+* instance over the shared base grammar; the entries in `./optional.ts`
+* cover the opt-in nodes an application composes in.
+*
+* @module
+*/
+/**
+* The default serialiser: the shared base grammar and nothing else.
+*
+* An application whose grammar includes an opt-in node builds its own with
+* `createMarkdownSerialiser` rather than reaching for this one, because a
+* node with no serialiser falls back to its inline text — readable, but not
+* a faithful rendering of a figure or a sidenote.
+*/
+const toMarkdown = /* @__PURE__ */ createMarkdownSerialiser();
+export { DEFAULT_SAFE_SCHEMES, DocumentViolation, allowListFilter, allowListViolation, checkAllowList, createMarkdownSerialiser, defineAllowList, defineDocumentShape, escapeMarkdown, extractDocumentText, figureMarkdown, fromEditorDocument, inlineDocumentText, isSafeHref, mentionMarkdown, sidenoteMarkdown, toEditorDocument, toMarkdown };