@thomasfosterau/prosekit-utilities 0.0.0 → 0.1.0

package/dist/derive-BtbsOqS7.js

@@ -0,0 +1,479 @@
+import { t as __exportAll } from "./rolldown-runtime-D8jQpDG7.js";
+import * as Array from "effect/Array";
+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";
+import * as Record from "effect/Record";
+// src/derive/Options.ts
+/**
+* @copyright Thomas Foster
+*
+* Public option and result types for the derivation entry points.
+*
+* ProseMirror exposes a schema's *structure* at runtime — node and mark
+* names, groups, the compiled content model, which marks each node admits,
+* and per-attribute defaults — but it does **not** expose attribute *value
+* types*: an {@link AttributeSpec} carries only a `default` and an optional
+* `validate` hint. So a faithful derivation recovers the structure exactly and
+* makes a best effort at attributes, leaving a seam — the {@link AttributeOverlay}
+* — through which a caller supplies the value schemas ProseMirror cannot. The
+* derived schema complements, rather than replaces, a hand-written generative
+* document contract, which still owns the attribute value types.
+*
+* @module @thomasfosterau/prosekit-utilities/derive/Options
+*/
+var Options_exports = /* @__PURE__ */ __exportAll({
+	attributeOverlay: () => attributeOverlay,
+	isRequiredAttribute: () => isRequiredAttribute,
+	required: () => required
+});
+const RequiredAttributeTypeId = Symbol.for("@thomasfosterau/prosekit-utilities/RequiredAttribute");
+/** Wraps `schema` as a {@link RequiredAttribute}. */
+const required = (schema) => ({
+	[RequiredAttributeTypeId]: true,
+	schema
+});
+/** True when `value` is a {@link RequiredAttribute} produced by {@link required}. */
+const isRequiredAttribute = (value) => Predicate.isObjectOrArray(value) && RequiredAttributeTypeId in value;
+/**
+* Builds an {@link AttributeOverlay} from a nested record keyed by owner name
+* then attribute name. A convenience over writing the function by hand when the
+* overrides are static:
+*
+* ```ts
+* const overlay = attributeOverlay({
+*   heading: { level: Schema.Literals([1, 2, 3, 4, 5, 6]) },
+*   image: { src: Schema.NullOr(Schema.String) },
+* });
+* ```
+*
+* Keys match on the owning type's name regardless of whether it is a node or a
+* mark; a node and a mark sharing a name (unusual) would share overrides.
+*/
+function attributeOverlay(overrides) {
+	return (owner, attribute) => Option.fromNullishOr(overrides[owner.name]?.[attribute]);
+}
+// src/derive/Attribute.ts
+/**
+* @copyright Thomas Foster
+*
+* Attribute derivation — the part of a ProseMirror schema that is only
+* *partially* recoverable at runtime.
+*
+* An {@link AttributeSpec} carries a `default` and an optional `validate`
+* hint, nothing more. So this module recovers what it can, in priority order:
+*
+* 1. A caller {@link AttributeOverlay} override, if one is supplied.
+* 2. The `validate` string grammar (`"number | string | null"` …), parsed
+*    into a union of primitives — this is the one place ProseMirror records an
+*    attribute's value type.
+* 3. The `typeof` of a non-null `default` value.
+* 4. `Schema.Unknown` as the last resort.
+*
+* Key optionality follows ProseMirror's own rule: an attribute with a
+* `default` (of any value, `null` included) may be omitted and is emitted as
+* an optional key; an attribute with no default is required — the same split
+* `NodeType.hasRequiredAttrs()` reports.
+*
+* @module @thomasfosterau/prosekit-utilities/derive/Attribute
+*/
+var Attribute_exports = /* @__PURE__ */ __exportAll({
+	deriveAttribute: () => deriveAttribute,
+	deriveAttrsStruct: () => deriveAttrsStruct,
+	parseValidateGrammar: () => parseValidateGrammar
+});
+const PRIMITIVE_BY_NAME = {
+	string: Schema.String,
+	number: Schema.Finite,
+	boolean: Schema.Boolean,
+	null: Schema.Null
+};
+/**
+* Parses ProseMirror's `validate` string grammar — a `|`-separated list of the
+* primitive names `"string"`, `"number"`, `"boolean"`, `"null"`, and
+* `"undefined"` — into an Effect schema.
+*
+* The `"undefined"` member is not represented as a value (there is no
+* first-class `undefined` schema for a present key); it is reported via the
+* returned `optional` flag so the caller can drop the key instead.
+*
+* An empty or all-unknown grammar yields `Schema.Unknown`.
+*/
+function parseValidateGrammar(validate) {
+	const tokens = validate.split("|").map((t) => t.trim()).filter(String.isNonEmpty);
+	const optional = tokens.includes("undefined");
+	const keys = Array.dedupe(Array.filterMap(tokens, (token) => token === "undefined" ? Result.failVoid : Result.succeed(token in PRIMITIVE_BY_NAME ? token : "")));
+	const members = Array.map(keys, (key) => PRIMITIVE_BY_NAME[key] ?? Schema.Unknown);
+	return Array.match(members, {
+		onEmpty: () => ({
+			schema: Schema.Unknown,
+			optional
+		}),
+		onNonEmpty: (present) => present.length === 1 ? {
+			schema: Array.headNonEmpty(present),
+			optional
+		} : {
+			schema: Schema.Union(members),
+			optional
+		}
+	});
+}
+/** Best-effort schema for an attribute value inferred from its default. */
+function schemaFromDefault(value) {
+	if (Predicate.isString(value)) return Schema.String;
+	if (Predicate.isNumber(value)) return Schema.Finite;
+	if (Predicate.isBoolean(value)) return Schema.Boolean;
+	return value === null ? Schema.NullOr(Schema.Unknown) : Schema.Unknown;
+}
+/**
+* Derives the schema and key-optionality for one node or mark attribute.
+*
+* @param owner  The node or mark type the attribute belongs to (for the overlay).
+* @param name   The attribute name.
+* @param spec   The ProseMirror attribute spec.
+* @param overlay Optional caller override consulted first.
+*/
+function deriveAttribute(owner, name, spec, overlay) {
+	const hasDefault = spec.default !== void 0;
+	const override = overlay === void 0 ? Option.none() : overlay(owner, name, spec);
+	if (Option.isSome(override)) {
+		const value = override.value;
+		if (isRequiredAttribute(value)) return {
+			schema: value.schema,
+			optional: false
+		};
+		return {
+			schema: value,
+			optional: hasDefault
+		};
+	}
+	if (Predicate.isString(spec.validate)) {
+		const { schema, optional } = parseValidateGrammar(spec.validate);
+		return {
+			schema,
+			optional: optional || hasDefault
+		};
+	}
+	return {
+		schema: hasDefault ? schemaFromDefault(spec.default) : Schema.Unknown,
+		optional: hasDefault
+	};
+}
+/**
+* Derives the `attrs` struct schema for a node or mark from its attribute
+* specs, or `Option.none()` when the type declares no attributes.
+*
+* `attrs` is an `Option` because ProseMirror's own `NodeSpec`/`MarkSpec` leaves
+* `attrs` absent for an attribute-less type — the caller converts that foreign
+* `undefined` at the boundary (`Option.fromNullishOr(nodeType.spec.attrs)`).
+*/
+function deriveAttrsStruct(owner, attrs, overlay) {
+	if (Option.isNone(attrs) || Record.isEmptyReadonlyRecord(attrs.value)) return Option.none();
+	const fields = Record.map(attrs.value, (spec, name) => {
+		const { schema, optional } = deriveAttribute(owner, name, spec, overlay);
+		return optional ? Schema.optionalKey(schema) : schema;
+	});
+	return Option.some(Schema.Struct(fields));
+}
+// src/derive/Content.ts
+/**
+* @copyright Thomas Foster
+*
+* Content-model derivation — reading a node type's allowed children and
+* cardinality straight from ProseMirror's compiled content expression.
+*
+* A node's content expression (`"block+"`, `"(tableCell | tableHeaderCell)*"`,
+* …) is compiled into a {@link ContentMatch} finite automaton at schema-build
+* time. Rather than re-parse the source string — which ProseMirror also
+* exposes as `spec.content`, but only as an opaque string — we walk that
+* automaton. Every edge names a {@link NodeType} that may appear, and the
+* start state's `validEnd` tells us whether empty content is legal (`*`/`?`
+* style) or at least one child is required (`+`).
+*
+* Walking the DFA is robust for arbitrary expressions and needs no grammar
+* parser of our own; the trade-off is that we recover the *set* of admissible
+* child types and the empty-vs-non-empty distinction, not the full ordered
+* sequence. That is exactly the granularity the derived Effect schema models
+* (an array of a child union). A fixed sequence such as the figure node's
+* `image figcaption` therefore derives as a non-empty array of
+* `image | figcaption`: a stored figure without its caption, or with the two
+* halves reordered, decodes. This is intended: order and per-type
+* multiplicity within a content expression are left to ProseMirror's DOM
+* parser and editing transactions, which enforce them. Loading JSON does not:
+* `schema.nodeFromJSON` (and so ProseKit's `defaultContent`) checks attributes
+* but not content, so such a figure loads unchecked unless the consumer calls
+* `node.check()`, as ProseKit's `editor.setContent` already does.
+*
+* @module @thomasfosterau/prosekit-utilities/derive/Content
+*/
+var Content_exports = /* @__PURE__ */ __exportAll({
+	allowedContentTypes: () => allowedContentTypes,
+	contentCardinality: () => contentCardinality
+});
+/**
+* Collects the distinct set of node types that may appear anywhere in a node
+* type's content, by breadth-first walk of its content-match automaton.
+*
+* Order follows first-discovery, which for the typical single-group
+* expression (`block+`, `inline*`) matches the schema's node declaration
+* order.
+*/
+function allowedContentTypes(nodeType) {
+	const result = [];
+	const seenTypes = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	const queue = [nodeType.contentMatch];
+	while (Array.isArrayNonEmpty(queue)) {
+		const match = Array.headNonEmpty(queue);
+		queue.shift();
+		if (visited.has(match)) continue;
+		visited.add(match);
+		for (let i = 0; i < match.edgeCount; i++) {
+			const edge = match.edge(i);
+			if (!seenTypes.has(edge.type.name)) {
+				seenTypes.add(edge.type.name);
+				result.push(edge.type);
+			}
+			queue.push(edge.next);
+		}
+	}
+	return result;
+}
+/**
+* Classifies a node type's content cardinality from its content-match
+* automaton: `none` when it admits no children, `optional` when the empty
+* fragment is a valid end (`*` / `?`), and `required` otherwise (`+`).
+*/
+function contentCardinality(nodeType) {
+	const match = nodeType.contentMatch;
+	if (match.edgeCount === 0) return "none";
+	return match.validEnd ? "optional" : "required";
+}
+// src/derive/Registry.ts
+/**
+* @copyright Thomas Foster
+*
+* The derivation engine: a memoised builder that turns one ProseMirror
+* {@link PmSchema} plus a set of {@link DeriveOptions} into Effect schemas for
+* its marks and (mutually recursive) nodes.
+*
+* Nodes reference each other through their content models, so the node
+* schemas form a mutually recursive graph. The graph is expressed with
+* `Schema.suspend`: a node's content field holds a union of *deferred*
+* references to its admissible child schemas, and each reference resolves
+* through {@link Registry.node}, which memoises so the graph is built once and
+* cycles terminate. `suspend` also keeps construction lazy — building one node
+* never forces its children — so declaration order is irrelevant and recursive
+* grammars (a list inside a list) are fine.
+*
+* A {@link Registry} is internal plumbing; the public entry points in
+* `./Derive` create one and read a single schema out of it. Several
+* `Registry` instances — one per ProseMirror schema — can share a single
+* {@link RegistryCache} so structure the schemas have in common (e.g. two
+* ProseKit extensions both composing the same `defineAllMarks()`) is built
+* once rather than once per schema; {@link import("./Derive.ts").deriveDocumentSchemas}
+* is the public entry point that does this. Memoization is by mark/node
+* *name*, so sharing a cache across schemas is only correct when same-named
+* types across those schemas are structurally identical — true by
+* construction when the schemas are assembled from the same extension
+* definitions, which is the only scenario `deriveDocumentSchemas` targets.
+*
+* That includes the **mark set**. An inline node's derived `marks` field is
+* the schema-wide union of inline marks (see `#inlineMarks`), so two schemas
+* that both define `text` identically but admit different marks still derive
+* different `text` schemas, and the cache keeps whichever was built first. A
+* schema with an extra mark that is derived first makes the other accept that
+* mark; derived second, it rejects its own mark. Nothing reports the clash.
+*
+* @module @thomasfosterau/prosekit-utilities/derive/Registry
+*/
+/** A fresh, empty {@link RegistryCache} — private to one `Registry` unless explicitly shared. */
+function createRegistryCache() {
+	return {
+		nodeCache: /* @__PURE__ */ new Map(),
+		markCache: /* @__PURE__ */ new Map()
+	};
+}
+/** Builds and memoises the derived schemas for a single ProseMirror schema. */
+var Registry = class {
+	#schema;
+	#options;
+	#cache;
+	constructor(schema, options = {}, cache = createRegistryCache()) {
+		this.#schema = schema;
+		this.#options = options;
+		this.#cache = cache;
+	}
+	/** The derived schema for a mark type, built once and memoised by name. */
+	mark(markType) {
+		const cached = this.#cache.markCache.get(markType.name);
+		if (cached) return cached;
+		const built = this.#buildMark(markType);
+		this.#cache.markCache.set(markType.name, built);
+		return built;
+	}
+	/** The derived schema for a node type, built once and memoised by name. */
+	node(nodeType) {
+		const cached = this.#cache.nodeCache.get(nodeType.name);
+		if (cached) return cached;
+		const built = this.#buildNode(nodeType, nodeType.name);
+		this.#cache.nodeCache.set(nodeType.name, built);
+		return built;
+	}
+	/**
+	* The derived schema for a node type with its `type` literal overridden —
+	* used for a renamed top node (e.g. `doc` → `blockDocument`). Not memoised,
+	* since the override makes it distinct from the canonical node schema.
+	*/
+	nodeAs(nodeType, typeName) {
+		return this.#buildNode(nodeType, typeName);
+	}
+	#buildMark(markType) {
+		const fields = { type: Schema.Literal(markType.name) };
+		const attrs = deriveAttrsStruct({
+			kind: "mark",
+			name: markType.name
+		}, Option.fromNullishOr(markType.spec.attrs), this.#options.attributes);
+		if (Option.isSome(attrs)) fields.attrs = attrs.value;
+		return Schema.Struct(fields);
+	}
+	#inlineMarkCache = Option.none();
+	/**
+	* The marks admissible on inline content anywhere in the schema.
+	*
+	* In ProseMirror JSON marks are serialised on the inline nodes, but the
+	* *permission* to carry a mark comes from the containing textblock's
+	* `markSet` (a node's own `markSet` — `text`'s included — governs what it may
+	* hold, and a textblock's governs its inline children). Rather than thread
+	* parent context through the memoised node graph, we take the schema-wide
+	* union: a mark that some textblock (`inlineContent`) admits may appear on
+	* inline nodes. A `null` `markSet` on any textblock means all marks.
+	*/
+	#inlineMarks() {
+		if (Option.isSome(this.#inlineMarkCache)) return this.#inlineMarkCache.value;
+		const inlineNodes = Array.filter(Record.values(this.#schema.nodes), (node) => node.inlineContent);
+		if (Array.some(inlineNodes, (node) => node.markSet === null)) {
+			const all = Record.values(this.#schema.marks);
+			this.#inlineMarkCache = Option.some(all);
+			return all;
+		}
+		const deduped = Array.dedupeWith(Array.flatMap(inlineNodes, (node) => node.markSet ?? []), (a, b) => a.name === b.name);
+		this.#inlineMarkCache = Option.some(deduped);
+		return deduped;
+	}
+	/** The union of mark schemas a node may carry in JSON, or `Option.none()`. */
+	#marksFor(nodeType) {
+		if (this.#options.includeMarks === false) return Option.none();
+		if (!nodeType.isInline) return Option.none();
+		const markTypes = this.#inlineMarks();
+		if (!Array.isReadonlyArrayNonEmpty(markTypes)) return Option.none();
+		const members = Array.map(markTypes, (m) => this.mark(m));
+		return Option.some(members.length === 1 ? Array.headNonEmpty(members) : Schema.Union(members));
+	}
+	/** The content field schema for a node, or `Option.none()` for a leaf. */
+	#contentFor(nodeType) {
+		const cardinality = contentCardinality(nodeType);
+		if (cardinality === "none") return Option.none();
+		const childTypes = allowedContentTypes(nodeType);
+		if (!Array.isReadonlyArrayNonEmpty(childTypes)) return Option.none();
+		const childMembers = Array.map(childTypes, (child) => Schema.suspend(() => this.node(child)));
+		const child = childMembers.length === 1 ? Array.headNonEmpty(childMembers) : Schema.Union(childMembers);
+		if (cardinality === "required" && this.#options.nonEmptyRequiredContent !== false) return Option.some(Schema.NonEmptyArray(child));
+		return Option.some(Schema.Array(child));
+	}
+	#buildNode(nodeType, typeName) {
+		const fields = { type: Schema.Literal(typeName) };
+		const attrs = deriveAttrsStruct({
+			kind: "node",
+			name: nodeType.name
+		}, Option.fromNullishOr(nodeType.spec.attrs), this.#options.attributes);
+		if (Option.isSome(attrs)) fields.attrs = attrs.value;
+		if (nodeType.isText) fields.text = Schema.String;
+		else {
+			const content = this.#contentFor(nodeType);
+			if (Option.isSome(content)) fields.content = contentCardinality(nodeType) === "optional" ? Schema.optionalKey(content.value) : content.value;
+		}
+		const marks = this.#marksFor(nodeType);
+		if (Option.isSome(marks)) fields.marks = Schema.optionalKey(Schema.Array(marks.value));
+		return Schema.Struct(fields);
+	}
+};
+// src/derive/Derive.ts
+var Derive_exports = /* @__PURE__ */ __exportAll({
+	deriveDocumentSchema: () => deriveDocumentSchema,
+	deriveDocumentSchemas: () => deriveDocumentSchemas,
+	deriveMarkSchema: () => deriveMarkSchema,
+	deriveNodeSchema: () => deriveNodeSchema
+});
+/**
+* Derives an Effect schema for a single ProseMirror mark type: a struct with a
+* `type` literal and, when the mark declares attributes, an `attrs` field.
+*/
+function deriveMarkSchema(markType, options) {
+	return new Registry(markType.schema, options).mark(markType);
+}
+/**
+* Derives an Effect schema for a single ProseMirror node type, recursively
+* modelling its content via the node's own schema. The result validates a JSON
+* subtree rooted at this node.
+*/
+function deriveNodeSchema(nodeType, options) {
+	return new Registry(nodeType.schema, options).node(nodeType);
+}
+/**
+* Derives an Effect schema for a whole document from a ProseMirror schema,
+* rooted at its top node (`schema.topNodeType`, usually `doc`).
+*
+* Pass `topTypeName` to rename the top node's `type` literal — for an
+* application that persists the top node under a different name than
+* ProseMirror's internal `doc` (e.g. `blockDocument`).
+*/
+function deriveDocumentSchema(schema, options) {
+	return documentNode(new Registry(schema, options), schema, Option.fromNullishOr(options?.topTypeName));
+}
+/** The document-envelope node a {@link deriveDocumentSchema} / {@link deriveDocumentSchemas} entry resolves to. */
+function documentNode(registry, schema, topTypeName) {
+	return Option.isNone(topTypeName) ? registry.node(schema.topNodeType) : registry.nodeAs(schema.topNodeType, topTypeName.value);
+}
+/**
+* Derives Effect schemas for two or more related ProseMirror document
+* schemas in one call, sharing a single {@link Registry} — and so its
+* mark/node memoization — across all of them.
+*
+* Use this instead of separate {@link deriveDocumentSchema} calls when the
+* schemas are assembled from overlapping ProseKit extensions (e.g. two
+* document types that both compose the same `defineAllMarks()` or
+* `defineText()`): the marks and nodes the schemas have in common are then
+* derived once rather than once per document. The results stay fully
+* independent `Schema.Codec`s — this shares derivation machinery, not the
+* documents' wire shapes.
+*
+* **Precondition:** sharing is by mark/node *name*, so this is only correct
+* when every schema in the call defines same-named marks/nodes identically
+* (the same extension composed into each schema, as opposed to two schemas
+* that coincidentally both declare a differently-shaped type under the same
+* name) **and admits the same set of marks** — an inline node's derived
+* `marks` field is the schema's whole inline mark union, so a schema with an
+* extra mark derives a different `text`. A mismatch would silently resolve
+* to whichever schema's version was derived first, for every schema after
+* it, with no error.
+*
+* All entries are built eagerly in this one call — pass already-compiled
+* schemas. A caller that needs each document to stay independently lazy
+* (e.g. never compiling schema B just because schema A was validated) should
+* instead share a {@link import("./Registry.ts").RegistryCache} across
+* separate `Registry` instances directly, one per schema, each built inside
+* its own deferred call site — the pattern
+* `@thomasfosterau/prosekit-utilities/prosekit`'s `defineDocumentSchema`
+* implements.
+*
+* `options` applies to every schema in the call; use each entry's own
+* `topTypeName` for a per-document top-node rename.
+*/
+function deriveDocumentSchemas(schemas, options) {
+	const cache = createRegistryCache();
+	return Record.map(schemas, ({ schema, topTypeName }) => documentNode(new Registry(schema, options, cache), schema, Option.fromNullishOr(topTypeName)));
+}
+export { deriveNodeSchema as a, Content_exports as c, attributeOverlay as d, isRequiredAttribute as f, deriveMarkSchema as i, Attribute_exports as l, deriveDocumentSchema as n, Registry as o, required as p, deriveDocumentSchemas as r, createRegistryCache as s, Derive_exports as t, Options_exports as u };

package/dist/derive.d.ts

@@ -0,0 +1,2 @@
+import { S as required, _ as DerivedNodeJSON, a as Attribute_d_exports, b as attributeOverlay, c as deriveDocumentSchema, d as deriveNodeSchema, f as AttributeOverlay, g as DerivedMarkJSON, h as DeriveOptions, i as Content_d_exports, l as deriveDocumentSchemas, m as DeriveDocumentOptions, n as RegistryCache, o as Derive_d_exports, p as AttributeOwner, r as createRegistryCache, s as DocumentSchemaSpec, t as Registry, u as deriveMarkSchema, v as Options_d_exports, x as isRequiredAttribute, y as RequiredAttribute } from "./index-DlgceBHe.js";
+export { Attribute_d_exports as Attribute, type AttributeOverlay, type AttributeOwner, Content_d_exports as Content, Derive_d_exports as Derive, type DeriveDocumentOptions, type DeriveOptions, type DerivedMarkJSON, type DerivedNodeJSON, type DocumentSchemaSpec, Options_d_exports as Options, Registry, type RegistryCache, type RequiredAttribute, attributeOverlay, createRegistryCache, deriveDocumentSchema, deriveDocumentSchemas, deriveMarkSchema, deriveNodeSchema, isRequiredAttribute, required };

package/dist/derive.js

@@ -0,0 +1 @@
+export { l as Attribute, c as Content, t as Derive, u as Options, o as Registry, d as attributeOverlay, s as createRegistryCache, n as deriveDocumentSchema, r as deriveDocumentSchemas, i as deriveMarkSchema, a as deriveNodeSchema, f as isRequiredAttribute, p as required } from "./derive-BtbsOqS7.js";

package/dist/document-shape-CrKjPIEf.d.ts

@@ -0,0 +1,195 @@
+import * as Effect from "effect/Effect";
+import * as HashSet from "effect/HashSet";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SchemaAST from "effect/SchemaAST";
+/**
+ * The ProseMirror JSON shapes, declared here rather than imported.
+ *
+ * `prosekit/core` exports a `NodeJSON` interface of exactly this shape, but
+ * importing it — even as a type — would put `prosekit` in this entry's
+ * import graph, and a `verbatimModuleSyntax` type-only import is easy to
+ * turn into a value import by accident. The root entry's whole purpose is
+ * that a model layer can name a document type without the editor runtime
+ * reaching the bundle, so the types are restated here instead.
+ *
+ * These are structural twins: `prosekit/core`'s `NodeJSON` is assignable to
+ * {@link NodeJSON} and vice versa where the mutability allows, so a document
+ * read out of an editor passes straight into anything here.
+ *
+ * @module
+ */
+/**
+ * One ProseMirror mark in its JSON form — a type name and its attributes.
+ *
+ * `attrs` is `unknown`-valued rather than `any`-valued: a serialiser that
+ * reads `mark.attrs?.href` has to narrow it, which is what keeps the
+ * `isSafeHref` check from being accidentally skipped.
+ */
+interface MarkJSON {
+  readonly type: string;
+  readonly attrs?: Record<string, unknown> | undefined;
+}
+/**
+ * One ProseMirror node in its JSON form.
+ *
+ * Every field but `type` is optional, exactly as ProseMirror's own
+ * serialisation is: a text leaf carries `text`, a container carries
+ * `content`, an atom carries neither.
+ */
+interface NodeJSON {
+  readonly type: string;
+  readonly attrs?: Record<string, unknown> | undefined;
+  readonly content?: ReadonlyArray<NodeJSON> | undefined;
+  readonly marks?: ReadonlyArray<MarkJSON> | undefined;
+  readonly text?: string | undefined;
+}
+/**
+ * The persisted document envelope: a ProseMirror document whose top-level
+ * `type` is the application's own name for the surface (`blockDocument`,
+ * `inlineDocument`, …) rather than ProseMirror's `doc`.
+ *
+ * Storing the surface name in the envelope is what lets one column's rows
+ * say which grammar they were written under; {@link NodeJSON} is what the
+ * editor itself wants, and `toEditorDocument` / `fromEditorDocument` move
+ * between the two.
+ */
+interface DocumentJSON<Name extends string = string> {
+  readonly type: Name;
+  readonly content: ReadonlyArray<NodeJSON>;
+}
+/**
+ * One surface's vocabulary: the node and mark type names it admits, whether
+ * link `href`s are scheme-checked, and the name used in violation messages.
+ *
+ * `label` reads as a noun phrase in `node type "x" is not permitted in
+ * <label>` — "a comment", "an article section".
+ */
+interface AllowList {
+  readonly label: string;
+  readonly nodes: HashSet.HashSet<string>;
+  readonly marks: HashSet.HashSet<string>;
+  readonly checkLinkHref: boolean;
+}
+/**
+ * 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.
+ */
+declare const defineAllowList: (options: {
+  readonly label: string;
+  readonly nodes: Iterable<string>;
+  readonly marks: Iterable<string>;
+  readonly checkLinkHref?: boolean | undefined;
+}) => AllowList;
+declare const DocumentViolation_base: Schema.Class<DocumentViolation, Schema.TaggedStruct<"DocumentViolation", {
+  readonly label: Schema.String;
+  readonly kind: Schema.Literals<readonly ["node", "mark", "href"]>;
+  readonly name: Schema.String;
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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.
+ */
+declare class DocumentViolation extends /* @__PURE__ */ DocumentViolation_base {}
+/** A document as the walk needs to see it: an envelope with `content`. */
+interface WithContent {
+  readonly content: ReadonlyArray<NodeJSON>;
+}
+/**
+ * The widest thing {@link allowListFilter} can be pointed at: anything whose
+ * `content` is an array, whatever the element type. A document shape's
+ * `content` is `ReadonlyArray<Json>` at the schema level — a `null` entry
+ * gets past the structural check — so the walk below never assumes an entry
+ * is an object.
+ */
+interface ContentCarrier {
+  readonly content: ReadonlyArray<unknown>;
+}
+/**
+ * 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.
+ */
+declare const allowListViolation: (allowList: AllowList, doc: WithContent) => Option.Option<DocumentViolation>;
+/**
+ * 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.
+ */
+declare const checkAllowList: (allowList: AllowList) => <D extends WithContent>(doc: D) => Effect.Effect<D, DocumentViolation>;
+/**
+ * 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.
+ */
+declare const allowListFilter: (allowList: AllowList) => SchemaAST.Filter<ContentCarrier>;
+/**
+ * A whole-document type guard — what the ProseKit entry point's `DocumentSchema.is`
+ * provides and what {@link DocumentShape.install} accepts.
+ */
+type DocumentGrammarGuard = (value: unknown) => boolean;
+/**
+ * One document surface, declared once and shared by the model layer, the
+ * persistence layer and the editor.
+ *
+ * `Schema` is the browser-cheap codec; `narrow` composes an allow-list onto
+ * it; `install` upgrades every one of them, for the life of the isolate, to
+ * the full grammar check.
+ */
+interface DocumentShape<Name extends string> {
+  /** The envelope's top-level `type` — `blockDocument`, `inlineDocument`, … */
+  readonly name: Name;
+  /** The human-readable noun phrase used in validation messages. */
+  readonly label: string;
+  /** The structural codec, grammar-checked wherever {@link install} has run. */
+  readonly Schema: Schema.Codec<DocumentJSON<Name>>;
+  /** `Schema.is` over {@link Schema}, with a defect net — see below. */
+  readonly is: (value: unknown) => value is DocumentJSON<Name>;
+  /** Installs the grammar guard for the life of the isolate. Idempotent in effect. */
+  readonly install: (guard: DocumentGrammarGuard) => void;
+  /** Whether a grammar guard is installed. For tests; production code should not branch on it. */
+  readonly isInstalled: () => boolean;
+  /** An empty document of this shape — the value a fresh editor field starts from. */
+  readonly empty: () => DocumentJSON<Name>;
+  /** {@link Schema} with an allow-list filter appended. */
+  readonly narrow: (allowList: AllowList) => Schema.Codec<DocumentJSON<Name>>;
+}
+/**
+ * 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`.
+ */
+declare function defineDocumentShape<Name extends string>(options: {
+  readonly name: Name;
+  readonly label?: string | undefined;
+}): DocumentShape<Name>;
+export { DocumentViolation as a, checkAllowList as c, MarkJSON as d, NodeJSON as f, AllowList as i, defineAllowList as l, DocumentShape as n, allowListFilter as o, defineDocumentShape as r, allowListViolation as s, DocumentGrammarGuard as t, DocumentJSON as u };