@orkestrel/markdown 0.0.1

package/dist/src/core/index.js

@@ -0,0 +1,2833 @@
+//#region src/core/constants.ts
+/**
+* The URL schemes `renderHTML` permits on a link `href` - anything else (notably
+* `javascript:`, `data:`, `vbscript:`, `file:`) is dropped to an empty `href` so a
+* hostile link can never execute. Frozen, lower-case; a relative / anchor /
+* scheme-less `href` (no `scheme:` prefix) is always allowed.
+*/
+var SAFE_URL_SCHEMES = /* @__PURE__ */ new Set([
+	"http",
+	"https",
+	"mailto",
+	"tel"
+]);
+/**
+* The maximum recursion depth the parse pipeline (`parseDocument` and its
+* `parsers.ts` helpers) and the `helpers.ts` traversal / render functions
+* (`renderHTML`, `renderMarkdown`, `walkNodes`, `foldNode`) honor before degrading to
+* literal text - bounds blockquote nesting, inline nesting (emphasis / links), and
+* traversal/render recursion so pathological or hostile input (deeply nested
+* blockquotes, runaway emphasis) cannot exhaust the call stack. Past this depth the
+* parser treats the remaining content as literal text instead of recursing further.
+*/
+var MAX_DEPTH = 64;
+Object.freeze([
+	"null",
+	"boolean",
+	"object",
+	"array",
+	"number",
+	"integer",
+	"string"
+]);
+/** Determine whether a value is `null`. */
+function isNull(value) {
+	return value === null;
+}
+/** Determine whether a value is `undefined`. */
+function isUndefined(value) {
+	return value === void 0;
+}
+/** Determine whether a value is a string. */
+function isString(value) {
+	return typeof value === "string";
+}
+/**
+* Determine whether a value is a number.
+*
+* @remarks
+* Includes `NaN` and `±Infinity` — use {@link isFiniteNumber} to exclude them.
+*/
+function isNumber(value) {
+	return typeof value === "number";
+}
+/** Determine whether a value is a finite number (excludes `NaN` and `±Infinity`). */
+function isFiniteNumber(value) {
+	return typeof value === "number" && Number.isFinite(value);
+}
+/** Determine whether a value is a finite integer (excludes `NaN`, `±Infinity`, and fractional numbers). */
+function isInteger(value) {
+	return Number.isInteger(value);
+}
+/** Determine whether a value is a boolean. */
+function isBoolean(value) {
+	return typeof value === "boolean";
+}
+/**
+* Determine whether a value is a non-null object.
+*
+* @remarks
+* `true` for arrays, class instances, plain objects, `Map`, `Set`, etc. — use
+* {@link isRecord} when you need a plain-record check.
+*/
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* Determine whether a value is a plain record (object literal or null-prototype),
+* not an array or class instance.
+*
+* @remarks
+* Use instead of {@link isObject} to distinguish a plain `{}` /
+* `Object.create(null)` from arrays, `Date`, `Map`, etc. The prototype-chain
+* test is realm-agnostic: rather than comparing against the current realm's
+* `Object.prototype` (which a plain object from another `vm.Context`, iframe,
+* or worker would fail), it accepts any value whose prototype is `null`, OR
+* whose prototype's own prototype is `null` — the shape every plain object
+* has in every realm, since `Object.prototype` itself always sits one step
+* above `null`. Arrays and class instances are still rejected: an array's
+* prototype chain runs through `Array.prototype` before `null`, and a class
+* instance's runs through the class's own prototype. The whole body runs
+* inside `attempt` (AGENTS §14) so a revoked `Proxy` or a hostile
+* `getPrototypeOf` trap cannot escape as a thrown error.
+*/
+function isRecord(value) {
+	const outcome = attempt(() => {
+		if (!isObject(value) || isArray(value)) return false;
+		const prototype = Object.getPrototypeOf(value);
+		return prototype === null || Object.getPrototypeOf(prototype) === null;
+	});
+	return outcome.success && outcome.value;
+}
+/** Determine whether a value is an array. */
+function isArray(value) {
+	return Array.isArray(value);
+}
+/** Determine whether a value is the empty string `''`. */
+function isEmptyString(value) {
+	return isString(value) && value.length === 0;
+}
+/** Determine whether a value is a non-empty string (at least one character). */
+function isNonEmptyString(value) {
+	return isString(value) && value.length > 0;
+}
+/** Determine whether a value is a non-empty array (at least one element). */
+function isNonEmptyArray(value) {
+	return isArray(value) && value.length > 0;
+}
+/**
+* Determine whether a value is a cycle-safe JSON value.
+*
+* @remarks
+* Total guard: never throws, returns `false` for cycles, functions, `Date`
+* instances, class instances, `NaN`, and `±Infinity`. Arrays and plain records
+* are walked with an ancestor set so recursive input fails instead of hanging.
+* The whole walk runs inside `attempt` (AGENTS §14): a hostile getter on a
+* record property, or a revoked `Proxy` anywhere in the structure, is caught
+* and yields `false` instead of escaping as a thrown error.
+*
+* @param value - The value to test
+* @returns `true` when the value has a JSON representation
+*
+* @example
+* ```ts
+* isJSONValue({ nested: [1, 'x', null] }) // true
+* isJSONValue(Number.NaN)                 // false
+* ```
+*/
+function isJSONValue(value) {
+	const ancestors = /* @__PURE__ */ new WeakSet();
+	const check = (entry) => {
+		if (entry === null || isString(entry) || isBoolean(entry) || isFiniteNumber(entry)) return true;
+		if (Array.isArray(entry)) {
+			if (ancestors.has(entry)) return false;
+			ancestors.add(entry);
+			const valid = entry.every(check);
+			ancestors.delete(entry);
+			return valid;
+		}
+		if (!isRecord(entry)) return false;
+		if (ancestors.has(entry)) return false;
+		ancestors.add(entry);
+		const valid = Object.values(entry).every(check);
+		ancestors.delete(entry);
+		return valid;
+	};
+	const outcome = attempt(() => check(value));
+	return outcome.success && outcome.value;
+}
+/**
+* Invoke a callback and capture its outcome as a {@link Result}, never letting
+* a throw escape.
+*
+* @remarks
+* The single sanctioned never-throw boundary for the guards (AGENTS §14). The
+* `whereOf`, `lazyOf`, and `transformOf` combinators invoke caller-supplied
+* callbacks *inside* a guard body, yet a guard must NEVER throw — it returns a
+* `boolean`. This converts a throwing callback into a `Failure` so the
+* surrounding guard can treat it as a non-match instead of propagating the
+* exception, written once and shared rather than copy-pasted as ad-hoc
+* `try`/`catch`.
+*
+* @param callback - The callback to invoke with no arguments
+* @returns A `Success` carrying the return value, or a `Failure` carrying the
+*          thrown reason normalised to an `Error`
+*
+* @example
+* ```ts
+* const outcome = attempt(() => predicate(value))
+* return outcome.success && outcome.value
+* ```
+*/
+function attempt(callback) {
+	try {
+		return {
+			success: true,
+			value: callback()
+		};
+	} catch (reason) {
+		if (reason instanceof Error) return {
+			success: false,
+			error: reason
+		};
+		let message = "Unknown thrown value";
+		try {
+			message = String(reason);
+		} catch {}
+		return {
+			success: false,
+			error: new Error(message)
+		};
+	}
+}
+/**
+* Build a deterministic pseudo-random source seeded from a single number.
+*
+* @remarks
+* A mulberry32 generator — the same seed always yields the same sequence, so
+* generated seed data is reproducible across runs. Used as the default random
+* source for {@link compileGenerator}, seeded from the wall clock so casual
+* callers still get varied output without passing a source themselves.
+*
+* @param seed - The seed for the sequence
+* @returns A {@link RandomFunction} returning values in `[0, 1)`
+*
+* @example
+* ```ts
+* const random = seededRandom(42)
+* random() // always the same first value for seed 42
+* ```
+*/
+function seededRandom(seed) {
+	let state = seed >>> 0;
+	return () => {
+		state = state + 1831565813 >>> 0;
+		let t = state;
+		t = Math.imul(t ^ t >>> 15, t | 1);
+		t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+}
+function arrayOf(elementGuard) {
+	return (value) => {
+		if (!isArray(value)) return false;
+		const outcome = attempt(() => value.every(elementGuard));
+		return outcome.success && outcome.value;
+	};
+}
+/**
+* Build a guard that accepts values identical (via `Object.is`) to one of the
+* provided literal primitives.
+*
+* @example
+* ```ts
+* const isRole = literalOf('admin', 'member', 'guest')
+* isRole('admin') // true
+* isRole('owner') // false
+* ```
+*/
+function literalOf(...literals) {
+	return (value) => literals.some((literal) => Object.is(literal, value));
+}
+/**
+* Build a guard that accepts plain records matching a guard shape.
+*
+* @remarks
+* Three calling modes depending on the `optional` argument:
+* - **No `optional`** — all shape keys required; extra keys rejected.
+* - **`optional: K[]`** — the listed keys are optional; all others required.
+* - **`optional: true`** — every shape key is optional.
+*
+* Key presence is tested with `Object.hasOwn`, so a shape key satisfied only by
+* an inherited prototype member (`toString`, `constructor`, …) counts as absent.
+* A non-object / `null` / array input returns `false` rather than throwing. The
+* extra-key check only inspects `Object.keys` (string keys), so an extra
+* enumerable SYMBOL key is never rejected — intentional, for JSON fidelity, and
+* matches the compiled guard.
+*
+* @example
+* ```ts
+* const isUser = recordOf({ name: isString, age: isNumber })
+* isUser({ name: 'Ada', age: 36 }) // true
+* isUser({ name: 'Ada' })          // false — age missing
+*
+* const isPartial = recordOf({ name: isString, age: isNumber }, ['age'])
+* isPartial({ name: 'Ada' }) // true
+* ```
+*/
+function recordOf(shape, optional) {
+	const allowed = /* @__PURE__ */ new Set();
+	for (const key in shape) if (Object.prototype.hasOwnProperty.call(shape, key)) allowed.add(key);
+	const optionalSet = new Set(optional === true ? [...allowed] : isArray(optional) ? optional.map((key) => String(key)) : []);
+	return (value) => {
+		if (!isRecord(value)) return false;
+		const outcome = attempt(() => {
+			for (const key of Object.keys(value)) if (!allowed.has(key)) return false;
+			for (const key in shape) {
+				if (!Object.prototype.hasOwnProperty.call(shape, key)) continue;
+				const present = Object.hasOwn(value, key);
+				if (!optionalSet.has(key) && !present) return false;
+				if (present) {
+					const guard = shape[key];
+					if (!guard(value[key])) return false;
+				}
+			}
+			return true;
+		});
+		return outcome.success && outcome.value;
+	};
+}
+function orOf(left, right) {
+	return (value) => left(value) || right(value);
+}
+function unionOf(...guards) {
+	return (value) => guards.some((guard) => guard(value));
+}
+function intersectionOf(...guards) {
+	return (value) => guards.every((guard) => guard(value));
+}
+function whereOf(base, predicate) {
+	return (value) => {
+		if (!base(value)) return false;
+		const outcome = attempt(() => predicate(value));
+		return outcome.success && outcome.value;
+	};
+}
+/**
+* Defer guard creation until first use by calling `thunk()` on every
+* invocation.
+*
+* @remarks
+* `thunk` is called on every guard call, not cached — this lets it close over a
+* binding assigned *after* `lazyOf` is called, the primary use case for
+* self-referential recursive guards. Per §14 a throw from `thunk` (or the guard
+* it resolves to) is contained and reported as a non-match.
+*
+* A recursive guard built this way has no cycle/depth detection: a cyclic or
+* pathologically deep input is stack-bounded — the overflow is contained and the
+* guard returns `false` rather than throwing, but it is not validated correctly
+* past that bound.
+*
+* @example
+* ```ts
+* type Tree = { value: number; children: Tree[] }
+* let isTree: Guard<Tree>
+* isTree = recordOf({ value: isNumber, children: arrayOf(lazyOf(() => isTree)) })
+* ```
+*/
+function lazyOf(thunk) {
+	return (value) => {
+		const outcome = attempt(() => thunk()(value));
+		return outcome.success && outcome.value;
+	};
+}
+/**
+* Build a guard that accepts finite numbers within an inclusive `[min, max]`
+* range.
+*
+* @remarks
+* Refines {@link isFiniteNumber} with the bound comparison, so `NaN` /
+* `±Infinity` are rejected before any comparison runs. An absent bound never
+* constrains that side. Reused for a number's own value AND, applied to a
+* `.length`, for string and array length refinements — the single source of the
+* bound logic shared by the compiled guard and parser (compilers.ts).
+*
+* @example
+* ```ts
+* const inRange = boundsOf(1, 5)
+* inRange(3)  // true
+* inRange(0)  // false — below min
+* inRange(6)  // false — above max
+*
+* const atLeastTwo = boundsOf(2)
+* atLeastTwo(2) // true — unbounded above
+* ```
+*/
+function boundsOf(min, max) {
+	return whereOf(isFiniteNumber, (value) => (min === void 0 || value >= min) && (max === void 0 || value <= max));
+}
+/**
+* Build a guard that accepts strings satisfying optional length and pattern
+* refinements — `min` / `max` length and a `pattern`.
+*
+* @remarks
+* Composes {@link isString} with {@link boundsOf} on the string's `.length` and
+* an inline `pattern.test` (the same refinement {@link matchOf} performs). When all three options are absent it returns
+* the bare {@link isString} guard (the unconstrained fast path), so an
+* unrefined string leaf pays no wrapping cost. The single source of the string
+* refinement shared by the compiled guard and parser (compilers.ts).
+*
+* @example
+* ```ts
+* const isSlug = stringOf({ min: 1, max: 32, pattern: /^[a-z-]+$/ })
+* isSlug('hello-world') // true
+* isSlug('')            // false — below min
+* isSlug('Hello')       // false — pattern miss
+*
+* stringOf() // identical to isString
+* ```
+*/
+function stringOf(options) {
+	const min = options?.min;
+	const max = options?.max;
+	const pattern = options?.pattern;
+	if (min === void 0 && max === void 0 && pattern === void 0) return isString;
+	const withinLength = boundsOf(min, max);
+	return whereOf(isString, (value) => withinLength(value.length) && (pattern === void 0 || pattern.test(value)));
+}
+/**
+* Extend a guard to also allow `null`.
+*
+* @example
+* ```ts
+* const isNullableString = nullableOf(isString)
+* isNullableString('hi') // true
+* isNullableString(null) // true
+* isNullableString(42)   // false
+* ```
+*/
+function nullableOf(guard) {
+	return (value) => value === null || guard(value);
+}
+/**
+* Parse an unknown value to a string.
+*
+* @remarks
+* A string is returned unchanged; a finite number is coerced to its decimal
+* string (`42` → `'42'`). `NaN`, `±Infinity`, and every other type → `undefined`.
+*
+* @param value - The value to parse
+* @returns A string, or `undefined`
+*/
+function parseString(value) {
+	if (isString(value)) return value;
+	if (isFiniteNumber(value)) return String(value);
+}
+/**
+* Parse an unknown value to a finite number.
+*
+* @remarks
+* A finite number is returned unchanged; a non-blank numeric string is parsed
+* via `Number(...)`. `NaN`, `±Infinity`, blank/non-numeric strings, and every
+* other type → `undefined`.
+*
+* @param value - The value to parse
+* @returns A finite number, or `undefined`
+*/
+function parseNumber(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+	if (isString(value)) {
+		if (value.trim() === "") return void 0;
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : void 0;
+	}
+}
+/**
+* Parse an unknown value to a finite integer.
+*
+* @remarks
+* Accepts whatever {@link parseNumber} accepts, then requires the result to have
+* no fractional part. `3.14` / `'3.14'` → `undefined`.
+*
+* @param value - The value to parse
+* @returns A finite integer, or `undefined`
+*/
+function parseInteger(value) {
+	const parsed = parseNumber(value);
+	if (parsed === void 0) return void 0;
+	return Number.isInteger(parsed) ? parsed : void 0;
+}
+/**
+* Parse an unknown value to a boolean.
+*
+* @remarks
+* A boolean is returned unchanged. The strings `'true'` / `'false'` / `'1'` /
+* `'0'` and the numbers `1` / `0` coerce to the matching boolean. Everything
+* else → `undefined`.
+*
+* @param value - The value to parse
+* @returns A boolean, or `undefined`
+*/
+function parseBoolean(value) {
+	if (typeof value === "boolean") return value;
+	if (value === "true" || value === "1" || value === 1) return true;
+	if (value === "false" || value === "0" || value === 0) return false;
+}
+/**
+* Parse an unknown value to a plain record — the input reference, never cloned.
+*
+* @param value - The value to parse
+* @returns The record, or `undefined`
+*/
+function parseRecord(value) {
+	return isRecord(value) ? value : void 0;
+}
+/**
+* Validate that a {@link ContractShape} tree is well-formed — a pure recursive
+* prepass run before compilation.
+*
+* @remarks
+* Fail-fast, per AGENTS §12: a malformed shape is a programmer error, so this
+* throws a plain `Error` immediately rather than surfacing as a silently-wrong
+* guard, parser, schema, or generator later. Checks, recursively:
+*
+* - An {@link OptionalShape} is only legal as a direct object-property value —
+*   `optionalShape` wrapping an array item, a union variant, another
+*   optional/nullable's inner shape, `additionalProperties`, or the top-level
+*   shape all throw. An object property IS the one legal placement: its value
+*   is unwrapped to `.inner` before recursing, so `.inner` itself is validated
+*   as a normal (non-optional-wrapping) shape.
+* - A {@link UnionShape} needs at least one variant; a {@link LiteralShape}
+*   needs at least one value and rejects non-finite (`NaN` / `Infinity` /
+*   `-Infinity`) number values.
+* - A bounded {@link StringShape} / {@link NumberShape} / {@link ArrayShape}
+*   needs `min <= max` when both are set.
+* - An integer {@link NumberShape} (`integer: true`) needs a non-empty integer
+*   range: `Math.ceil(min ?? -Infinity) <= Math.floor(max ?? Infinity)`.
+* - `null` / `json` / `raw` / `boolean` are always-valid leaves. Recursion
+*   continues into array items, object properties (and `additionalProperties`
+*   when it is a shape), union variants, and optional/nullable inner shapes.
+*
+* @param shape - The shape to validate
+* @throws {Error} When the shape is malformed
+*/
+function validateShape(shape) {
+	switch (shape.type) {
+		case "string":
+			if (shape.min !== void 0 && shape.max !== void 0 && shape.min > shape.max) throw new Error("validateShape: a string shape has min greater than max");
+			return;
+		case "number":
+			if (shape.min !== void 0 && shape.max !== void 0 && shape.min > shape.max) throw new Error("validateShape: a number shape has min greater than max");
+			if (shape.integer === true) {
+				if (Math.ceil(shape.min ?? Number.NEGATIVE_INFINITY) > Math.floor(shape.max ?? Number.POSITIVE_INFINITY)) throw new Error("validateShape: an integer number shape has an empty integer range");
+			}
+			return;
+		case "boolean":
+		case "null":
+		case "json":
+		case "raw": return;
+		case "literal":
+			if (shape.values.length === 0) throw new Error("validateShape: a literal shape needs at least one value");
+			for (const value of shape.values) if (typeof value === "number" && !Number.isFinite(value)) throw new Error("validateShape: a literal shape may not contain non-finite number values");
+			return;
+		case "array":
+			if (shape.min !== void 0 && shape.max !== void 0 && shape.min > shape.max) throw new Error("validateShape: an array shape has min greater than max");
+			validateShape(shape.items);
+			return;
+		case "object": {
+			for (const key of Object.keys(shape.properties)) {
+				const child = shape.properties[key];
+				if (child === void 0) continue;
+				validateShape(child.type === "optional" ? child.inner : child);
+			}
+			const extra = shape.additionalProperties;
+			if (extra !== void 0 && extra !== true && extra !== false) validateShape(extra);
+			return;
+		}
+		case "union":
+			if (shape.variants.length === 0) throw new Error("validateShape: a union shape needs at least one variant");
+			for (const variant of shape.variants) validateShape(variant);
+			return;
+		case "optional": throw new Error("validateShape: an optional shape may only appear as a direct object-property value");
+		case "nullable":
+			validateShape(shape.inner);
+			return;
+	}
+}
+/**
+* Compile a {@link ContractShape} into a JSON Schema document.
+*
+* @remarks
+* Object shapes emit `additionalProperties: false` (unless opened) and list only
+* required keys in `required`; nullable shapes emit an `anyOf` with `{ type:
+* 'null' }`. Emission only — it never inspects a runtime value.
+*
+* @param shape - The shape to compile
+* @returns The emitted JSON Schema
+*/
+function compileSchema(shape) {
+	switch (shape.type) {
+		case "string": return {
+			type: "string",
+			...shape.min !== void 0 ? { minLength: shape.min } : {},
+			...shape.max !== void 0 ? { maxLength: shape.max } : {},
+			...shape.pattern !== void 0 ? { pattern: shape.pattern.source } : {},
+			...shape.description !== void 0 ? { description: shape.description } : {}
+		};
+		case "number": return {
+			type: shape.integer === true ? "integer" : "number",
+			...shape.min !== void 0 ? { minimum: shape.min } : {},
+			...shape.max !== void 0 ? { maximum: shape.max } : {},
+			...shape.description !== void 0 ? { description: shape.description } : {}
+		};
+		case "boolean": return {
+			type: "boolean",
+			...shape.description !== void 0 ? { description: shape.description } : {}
+		};
+		case "null": return {
+			type: "null",
+			...shape.description !== void 0 ? { description: shape.description } : {}
+		};
+		case "json": return { ...shape.description !== void 0 ? { description: shape.description } : {} };
+		case "literal": return {
+			enum: [...shape.values],
+			...shape.description !== void 0 ? { description: shape.description } : {}
+		};
+		case "array": return {
+			type: "array",
+			items: compileSchema(shape.items),
+			...shape.min !== void 0 ? { minItems: shape.min } : {},
+			...shape.max !== void 0 ? { maxItems: shape.max } : {},
+			...shape.description !== void 0 ? { description: shape.description } : {}
+		};
+		case "object": {
+			const properties = {};
+			const required = [];
+			for (const key of Object.keys(shape.properties)) {
+				const child = shape.properties[key];
+				if (child === void 0) continue;
+				properties[key] = compileSchema(child);
+				if (child.type !== "optional") required.push(key);
+			}
+			const extra = shape.additionalProperties;
+			const additionalProperties = extra === true ? true : extra !== void 0 && extra !== false ? compileSchema(extra) : false;
+			return {
+				type: "object",
+				...Object.keys(properties).length > 0 ? { properties } : {},
+				...required.length > 0 ? { required } : {},
+				additionalProperties,
+				...shape.description !== void 0 ? { description: shape.description } : {}
+			};
+		}
+		case "union": return {
+			...shape.mode === "oneOf" ? { oneOf: shape.variants.map((variant) => compileSchema(variant)) } : { anyOf: shape.variants.map((variant) => compileSchema(variant)) },
+			...shape.description !== void 0 ? { description: shape.description } : {}
+		};
+		case "optional": return compileSchema(shape.inner);
+		case "nullable": return { anyOf: [compileSchema(shape.inner), { type: "null" }] };
+		case "raw": return shape.schema;
+	}
+}
+/**
+* Compile a {@link ContractShape} into a runtime type guard.
+*
+* @remarks
+* Reuses the combinators: `literalOf` for literals, `arrayOf` for arrays,
+* `recordOf` for closed objects, `unionOf` for unions, `nullableOf` for nullable,
+* and `whereOf` for constraint refinement. Like every guard it is total — it
+* never throws (AGENTS §14).
+*
+* @param shape - The shape to compile
+* @returns A guard narrowing to the shape's inferred type
+*/
+function compileGuard(shape) {
+	switch (shape.type) {
+		case "string": return stringOf({
+			min: shape.min,
+			max: shape.max,
+			pattern: shape.pattern
+		});
+		case "number": {
+			const base = shape.integer === true ? isInteger : isFiniteNumber;
+			if (shape.min === void 0 && shape.max === void 0) return base;
+			return shape.integer === true ? intersectionOf(isInteger, boundsOf(shape.min, shape.max)) : boundsOf(shape.min, shape.max);
+		}
+		case "boolean": return isBoolean;
+		case "null": return isNull;
+		case "json": return isJSONValue;
+		case "literal": return literalOf(...shape.values);
+		case "array": {
+			const base = arrayOf(compileGuard(shape.items));
+			if (shape.min === void 0 && shape.max === void 0) return base;
+			const withinLength = boundsOf(shape.min, shape.max);
+			return whereOf(base, (value) => withinLength(value.length));
+		}
+		case "object": {
+			const map = Object.create(null);
+			const optionalKeys = [];
+			for (const key of Object.keys(shape.properties)) {
+				const child = shape.properties[key];
+				if (child === void 0) continue;
+				if (child.type === "optional") {
+					map[key] = compileGuard(child.inner);
+					optionalKeys.push(key);
+				} else map[key] = compileGuard(child);
+			}
+			const extra = shape.additionalProperties;
+			if (extra === void 0 || extra === false) return optionalKeys.length > 0 ? recordOf(map, optionalKeys) : recordOf(map);
+			const additional = extra === true ? void 0 : compileGuard(extra);
+			const required = Object.keys(map).filter((key) => !optionalKeys.includes(key));
+			return (value) => {
+				if (!isRecord(value)) return false;
+				for (const key of required) if (!Object.hasOwn(value, key)) return false;
+				const outcome = attempt(() => {
+					for (const key of Object.keys(value)) {
+						const guard = Object.hasOwn(map, key) ? map[key] : void 0;
+						if (guard !== void 0) {
+							if (!guard(value[key])) return false;
+						} else if (additional !== void 0 && !additional(value[key])) return false;
+					}
+					return true;
+				});
+				return outcome.success && outcome.value;
+			};
+		}
+		case "union": return unionOf(...shape.variants.map((variant) => compileGuard(variant)));
+		case "optional": return orOf(isUndefined, compileGuard(shape.inner));
+		case "nullable": return nullableOf(compileGuard(shape.inner));
+		case "raw": return (_value) => true;
+	}
+}
+/**
+* Compile a {@link ContractShape} into an input parser.
+*
+* @remarks
+* Reuses the leaf parsers (`parseString` / `parseInteger` / `parseNumber` /
+* `parseBoolean` / `parseRecord`) and coerces structurally. An object fails as a
+* whole on any required-field failure; a union returns a guard-valid value
+* unchanged, otherwise the first variant that both parses and guards wins.
+*
+* After coercing a leaf, it re-applies that leaf's REFINEMENTS through the same
+* combinators `compileGuard` uses — `stringOf` for a string's length/pattern and
+* `boundsOf` for a number's value and an array's length — so a value that coerces
+* but violates a bound parses to `undefined`. The result is full parse↔guard
+* soundness (AGENTS §14): a non-`undefined` parse always satisfies the contract's
+* `is`, refinements included.
+*
+* @param shape - The shape to compile
+* @returns A parser yielding the shape's inferred type or `undefined`
+*/
+function compileParser(shape) {
+	switch (shape.type) {
+		case "string": {
+			if (shape.min === void 0 && shape.max === void 0 && shape.pattern === void 0) return parseString;
+			const guard = stringOf({
+				min: shape.min,
+				max: shape.max,
+				pattern: shape.pattern
+			});
+			return (value) => {
+				const parsed = parseString(value);
+				return parsed !== void 0 && guard(parsed) ? parsed : void 0;
+			};
+		}
+		case "number": {
+			const base = shape.integer === true ? parseInteger : parseNumber;
+			if (shape.min === void 0 && shape.max === void 0) return base;
+			const within = boundsOf(shape.min, shape.max);
+			return (value) => {
+				const parsed = base(value);
+				return parsed !== void 0 && within(parsed) ? parsed : void 0;
+			};
+		}
+		case "boolean": return parseBoolean;
+		case "null": return (value) => value === null ? null : void 0;
+		case "json": return (value) => isJSONValue(value) ? value : void 0;
+		case "literal": {
+			const allowed = new Set(shape.values);
+			return (value) => {
+				if (allowed.has(value)) return value;
+				if (isString(value)) {
+					const trimmed = value.trim();
+					if (allowed.has(trimmed)) return trimmed;
+				}
+			};
+		}
+		case "array": {
+			const item = compileParser(shape.items);
+			const unbounded = shape.min === void 0 && shape.max === void 0;
+			const withinLength = boundsOf(shape.min, shape.max);
+			return (value) => {
+				if (!isArray(value)) return void 0;
+				const result = [];
+				for (const entry of value) {
+					const parsed = item(entry);
+					if (parsed === void 0) return void 0;
+					result.push(parsed);
+				}
+				return unbounded || withinLength(result.length) ? result : void 0;
+			};
+		}
+		case "object": {
+			const entries = [];
+			for (const key of Object.keys(shape.properties)) {
+				const child = shape.properties[key];
+				if (child === void 0) continue;
+				const optional = child.type === "optional";
+				entries.push({
+					key,
+					parse: compileParser(optional ? child.inner : child),
+					optional
+				});
+			}
+			const known = new Set(entries.map((entry) => entry.key));
+			const extra = shape.additionalProperties;
+			const additional = extra === void 0 || extra === false || extra === true ? void 0 : compileParser(extra);
+			const open = extra === true || additional !== void 0;
+			return (value) => {
+				const record = parseRecord(value);
+				if (record === void 0) return void 0;
+				const outcome = attempt(() => {
+					const result = Object.create(null);
+					for (const entry of entries) {
+						const raw = record[entry.key];
+						if (raw === void 0) {
+							if (entry.optional) continue;
+							return;
+						}
+						const parsed = entry.parse(raw);
+						if (parsed === void 0) return void 0;
+						result[entry.key] = parsed;
+					}
+					if (open) for (const key of Object.keys(record)) {
+						if (known.has(key)) continue;
+						if (additional === void 0) result[key] = record[key];
+						else {
+							const parsed = additional(record[key]);
+							if (parsed === void 0) return void 0;
+							result[key] = parsed;
+						}
+					}
+					return result;
+				});
+				return outcome.success ? outcome.value : void 0;
+			};
+		}
+		case "union": {
+			const variants = shape.variants.map((variant) => ({
+				parse: compileParser(variant),
+				guard: compileGuard(variant)
+			}));
+			return (value) => {
+				for (const variant of variants) if (variant.guard(value)) return value;
+				for (const variant of variants) {
+					const parsed = variant.parse(value);
+					if (parsed !== void 0 && variant.guard(parsed)) return parsed;
+				}
+			};
+		}
+		case "optional": {
+			const inner = compileParser(shape.inner);
+			return (value) => value === void 0 ? void 0 : inner(value);
+		}
+		case "nullable": {
+			const inner = compileParser(shape.inner);
+			return (value) => value === null ? null : inner(value);
+		}
+		case "raw": return (value) => value;
+	}
+}
+/**
+* Compile a {@link ContractShape} into a deterministic seed value.
+*
+* @remarks
+* The same shape and the same `random` source always produce the same value, so
+* seed data is reproducible. Defaults to a {@link seededRandom} source seeded
+* from the wall clock when none is supplied. Throws on a degenerate empty
+* `literalShape` / `unionShape`, on a pattern-constrained `stringShape` whose
+* generated sample cannot satisfy the pattern, or on a `rawShape` (its embedded
+* schema is arbitrary and cannot be auto-generated) — a programmer error that
+* cannot generate a value (AGENTS §12). `createContract` runs
+* {@link validateShape} first, so a degenerate `literalShape` / `unionShape` /
+* bounded shape is normally caught there; these throws remain here as defense
+* for standalone `compileGenerator` use.
+*
+* @param shape - The shape to generate from
+* @param random - A seeded random source (defaults to `seededRandom(Date.now())`)
+* @returns A value matching the shape
+*/
+function compileGenerator(shape, random = seededRandom(Date.now())) {
+	switch (shape.type) {
+		case "string": {
+			const min = shape.min ?? 0;
+			const max = shape.max ?? Math.max(min, 12);
+			const length = Math.max(min, Math.min(max, 8));
+			const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
+			let value = "";
+			for (let index = 0; index < length; index += 1) value += alphabet[Math.floor(random() * 36)];
+			if (shape.pattern !== void 0 && !shape.pattern.test(value)) throw new Error("compileGenerator: a pattern-constrained string shape cannot be auto-generated — supply or verify values another way");
+			return value;
+		}
+		case "number": {
+			const min = shape.min ?? 0;
+			const max = shape.max ?? 100;
+			if (shape.integer === true) {
+				const lo = Math.ceil(min);
+				const hi = Math.floor(max);
+				return Math.floor(random() * (hi - lo + 1)) + lo;
+			}
+			return random() * (max - min) + min;
+		}
+		case "boolean": return random() >= .5;
+		case "null": return null;
+		case "json": {
+			const pick = Math.floor(random() * 5);
+			if (pick === 0) return null;
+			if (pick === 1) return random() >= .5;
+			if (pick === 2) return Math.floor(random() * 1e3);
+			if (pick === 3) {
+				const alphabet = "abcdefghijklmnopqrstuvwxyz";
+				let value = "";
+				for (let index = 0; index < 6; index += 1) value += alphabet[Math.floor(random() * 26)];
+				return value;
+			}
+			return { value: Math.floor(random() * 1e3) };
+		}
+		case "literal":
+			if (shape.values.length === 0) throw new Error("compileGenerator: a literal shape needs at least one value");
+			return shape.values[Math.floor(random() * shape.values.length)];
+		case "array": {
+			const lo = shape.min ?? Math.min(1, shape.max ?? 1);
+			const hi = shape.max ?? Math.max(lo, 3);
+			const length = Math.floor(random() * (hi - lo + 1)) + lo;
+			const result = [];
+			for (let index = 0; index < length; index += 1) result.push(compileGenerator(shape.items, random));
+			return result;
+		}
+		case "object": {
+			const result = {};
+			for (const key of Object.keys(shape.properties)) {
+				const child = shape.properties[key];
+				if (child === void 0) continue;
+				if (child.type === "optional" && random() < .3) continue;
+				result[key] = compileGenerator(child, random);
+			}
+			const extra = shape.additionalProperties;
+			if (extra !== void 0 && extra !== true && extra !== false) {
+				const count = 1 + Math.floor(random() * 2);
+				for (let index = 0; index < count; index += 1) {
+					const key = `key${index}`;
+					if (Object.hasOwn(result, key)) continue;
+					result[key] = compileGenerator(extra, random);
+				}
+			}
+			return result;
+		}
+		case "union":
+			if (shape.variants.length === 0) throw new Error("compileGenerator: a union shape needs at least one variant");
+			return compileGenerator(shape.variants[Math.floor(random() * shape.variants.length)], random);
+		case "optional": return compileGenerator(shape.inner, random);
+		case "nullable": return random() < .2 ? null : compileGenerator(shape.inner, random);
+		case "raw": throw new Error("compileGenerator: a raw shape embeds an arbitrary JSON Schema and cannot be auto-generated — supply values another way");
+	}
+}
+function createContract(shape) {
+	validateShape(shape);
+	const schema = compileSchema(shape);
+	const guard = compileGuard(shape);
+	const parser = compileParser(shape);
+	return {
+		schema,
+		is: guard,
+		parse(value) {
+			return parser(value);
+		},
+		generate(random) {
+			return compileGenerator(shape, random);
+		}
+	};
+}
+/**
+* Build a string {@link StringShape}.
+*
+* @param options - Optional length (`min` / `max`), `pattern`, and `description`
+* @returns A string shape
+*
+* @example
+* ```ts
+* const name = stringShape({ min: 1, max: 80, description: 'Display name' })
+* ```
+*/
+function stringShape(options) {
+	return {
+		type: "string",
+		min: options?.min,
+		max: options?.max,
+		pattern: options?.pattern,
+		description: options?.description
+	};
+}
+/**
+* Build an integer {@link NumberShape} — forces `integer: true`.
+*
+* @remarks
+* The emitted JSON Schema uses `"type": "integer"` and the guard rejects
+* fractional numbers.
+*
+* @param options - Optional bounds and `description` (no `integer` key)
+* @returns An integer number shape
+*/
+function integerShape(options) {
+	return {
+		type: "number",
+		integer: true,
+		min: options?.min,
+		max: options?.max,
+		description: options?.description
+	};
+}
+/**
+* Build a {@link BooleanShape}.
+*
+* @param options - Optional `description`
+* @returns A boolean shape
+*/
+function booleanShape(options) {
+	return {
+		type: "boolean",
+		description: options?.description
+	};
+}
+/**
+* Build a literal shape from a fixed set of primitive values.
+*
+* @param values - The permitted literals
+* @param options - Optional `description`
+* @returns A literal shape whose `Infer` is the union of `values`
+*
+* @example
+* ```ts
+* const role = literalShape(['admin', 'member', 'guest'])
+* // Infer<typeof role> = 'admin' | 'member' | 'guest'
+*
+* const via = literalShape(['function', 'tool', 'agent'], { description: 'How to run the step.' })
+* ```
+*/
+function literalShape(values, options) {
+	return {
+		type: "literal",
+		values,
+		description: options?.description
+	};
+}
+/**
+* Build an {@link ObjectShape} from a property map.
+*
+* @remarks
+* Wrap any property in {@link optionalShape} to allow its absence. By default
+* the compiled guard rejects unknown keys; pass `additionalProperties` to open
+* the object.
+*
+* @param properties - Map of property names to child shapes
+* @param options - Optional `additionalProperties` and `description`
+* @returns An object shape
+*
+* @example
+* ```ts
+* const user = objectShape({
+* 	name: stringShape({ min: 1 }),
+* 	age: integerShape({ min: 0, max: 120 }),
+* 	bio: optionalShape(stringShape()),
+* })
+* ```
+*/
+function objectShape(properties, options) {
+	return {
+		type: "object",
+		properties,
+		additionalProperties: options?.additionalProperties,
+		description: options?.description
+	};
+}
+/**
+* Wrap a shape so it may be absent (`undefined`).
+*
+* @remarks
+* As an {@link objectShape} property, the field becomes a true optional property
+* in the inferred type.
+*
+* @param inner - The wrapped shape
+* @returns An optional shape
+*/
+function optionalShape(inner) {
+	return {
+		type: "optional",
+		inner
+	};
+}
+//#endregion
+//#region src/core/validators.ts
+/**
+* Whether `character` is an inline whitespace character (space / tab / newline) - the
+* emphasis flanking rule's space test.
+*
+* @param character - The character to test
+* @returns `true` when it is inline whitespace
+*/
+function isWhitespace(character) {
+	return character === " " || character === "	" || character === "\n";
+}
+/**
+* Whether `character` is escapable by a leading backslash - the ASCII punctuation
+* markdown gives meaning to (so `\*` becomes `*` but `\.` stays `\.`).
+*
+* @param character - The single character after a backslash
+* @returns `true` when a backslash before it is an escape
+*/
+function isEscapable(character) {
+	return /[\\`*_{}[\]()#+\-.!>~|]/.test(character);
+}
+/**
+* Whether `line` is blank - empty, or containing only whitespace - the markdown
+* definition of a blank line that block parsing uses to separate paragraphs, skip
+* gaps, and end list continuations.
+*
+* @param line - The candidate line
+* @returns `true` when the line is blank
+*/
+function isBlankLine(line) {
+	return isEmptyString(line.trim());
+}
+/**
+* Whether `line` is a blockquote line (`>` optionally indented up to three spaces) -
+* its content is de-quoted by {@link stripQuote}.
+*
+* @param line - The candidate line
+* @returns `true` when the line begins a blockquote
+*/
+function isQuote(line) {
+	return /^\s{0,3}>/.test(line);
+}
+/**
+* Whether `line` closes a fence opened by `marker` - the same fence character, a run
+* at least as long, and nothing else but surrounding whitespace.
+*
+* @param line - The candidate closing line
+* @param marker - The opening fence's marker run (from {@link extractFence})
+* @returns `true` when `line` closes the fence
+*/
+function isFenceClose(line, marker) {
+	const character = marker[0] === "~" ? "~" : "`";
+	let index = 0;
+	while (index < line.length && isFenceWhitespace(line[index])) index++;
+	let run = 0;
+	while (index < line.length && line[index] === character) {
+		run++;
+		index++;
+	}
+	if (run < marker.length) return false;
+	while (index < line.length && isFenceWhitespace(line[index])) index++;
+	return index === line.length;
+}
+/**
+* Whether `character` is a regex-`\s`-equivalent whitespace character - the
+* character class {@link isFenceClose}'s scan treats as surrounding padding.
+*
+* @param character - The single character to test, or `undefined` past the end of a line
+* @returns `true` when it is whitespace
+*/
+function isFenceWhitespace(character) {
+	return character === " " || character === "	" || character === "\n" || character === "\r" || character === "\f" || character === "\v";
+}
+/**
+* Whether `line` is a thematic break (horizontal rule) - three or more of the SAME
+* marker `-`, `*`, or `_` (optionally space-separated) and nothing else (`---`,
+* `***`, `___`, `- - -`).
+*
+* @param line - The candidate line
+* @returns `true` when the line is a thematic break
+*/
+function isThematicBreak(line) {
+	const stripped = line.trim().replace(/\s+/g, "");
+	if (stripped.length < 3) return false;
+	const marker = stripped[0];
+	if (marker !== "-" && marker !== "*" && marker !== "_") return false;
+	return [...stripped].every((character) => character === marker);
+}
+/**
+* Whether the pair (`header`, `delimiter`) opens a GFM table - `delimiter` is a row of
+* `|`-separated cells each matching `:?-+:?`, the GFM rule that a table requires a
+* header row IMMEDIATELY followed by a delimiter row.
+*
+* @param header - The candidate header line
+* @param delimiter - The line after it (the candidate delimiter)
+* @returns `true` when the two lines open a table
+*/
+function isTableStart(header, delimiter) {
+	if (delimiter === void 0 || !header.includes("|")) return false;
+	const cells = splitTableRow(delimiter);
+	if (cells.length === 0) return false;
+	return cells.every((cell) => /^:?-+:?$/.test(cell.trim()));
+}
+/** Determine whether a node is a heading block. */
+function isHeadingNode(node) {
+	return node.element === "heading";
+}
+/** Determine whether a node is a paragraph block. */
+function isParagraphNode(node) {
+	return node.element === "paragraph";
+}
+/** Determine whether a node is a list block. */
+function isListNode(node) {
+	return node.element === "list";
+}
+/** Determine whether a node is a GFM table block. */
+function isTableNode(node) {
+	return node.element === "table";
+}
+/** Determine whether a node is a fenced code block. */
+function isCodeBlockNode(node) {
+	return node.element === "codeBlock";
+}
+/** Determine whether a node is a blockquote block. */
+function isBlockquoteNode(node) {
+	return node.element === "blockquote";
+}
+/** Determine whether a node is a thematic break (horizontal rule) block. */
+function isThematicBreakNode(node) {
+	return node.element === "thematicBreak";
+}
+/** Determine whether a node is a plain text run. */
+function isTextNode(node) {
+	return node.element === "text";
+}
+/** Determine whether a node is an emphasis run (`*em*` / `**strong**`). */
+function isEmphasisNode(node) {
+	return node.element === "emphasis";
+}
+/**
+* Determine whether a node is an inline code span.
+*
+* @remarks
+* Narrows to {@link CodeSpanNode} - the node whose `element` discriminant is
+* `'codeSpan'`.
+*/
+function isCodeSpanNode(node) {
+	return node.element === "codeSpan";
+}
+/** Determine whether a node is a link. */
+function isLinkNode(node) {
+	return node.element === "link";
+}
+/**
+* Determine whether an arbitrary value is a valid {@link InlineNode} - a text
+* run, emphasis, code span, or link, recursively validated.
+*
+* @remarks
+* Total: never throws, even on cyclic or pathologically deep input - every
+* combinator involved (`unionOf`, `recordOf`, `arrayOf`, `lazyOf`) is
+* throw-contained per the `@orkestrel/contract` guard contract (AGENTS §14).
+*
+* @param value - The value to test
+* @returns `true` when `value` is a well-formed {@link InlineNode}
+*
+* @example
+* ```ts
+* import { isInlineNode } from '@orkestrel/markdown'
+*
+* isInlineNode({ element: 'text', value: 'hi' }) // true
+* isInlineNode({ element: 'text' })               // false - missing `value`
+* ```
+*/
+var isInlineNode = unionOf(recordOf({
+	element: literalOf("text"),
+	value: isString
+}), recordOf({
+	element: literalOf("emphasis"),
+	strong: isBoolean,
+	children: arrayOf(lazyOf(() => isInlineNode))
+}), recordOf({
+	element: literalOf("codeSpan"),
+	value: isString
+}), recordOf({
+	element: literalOf("link"),
+	href: isString,
+	children: arrayOf(lazyOf(() => isInlineNode))
+}));
+/**
+* Determine whether an arbitrary value is a valid {@link BlockNode} - a
+* heading, paragraph, list, table, code block, blockquote, or thematic break,
+* recursively validated.
+*
+* @remarks
+* Total: never throws, even on cyclic or pathologically deep input - every
+* combinator involved (`unionOf`, `recordOf`, `arrayOf`, `lazyOf`) is
+* throw-contained per the `@orkestrel/contract` guard contract (AGENTS §14).
+* A list item's shape is inlined here (and in {@link isMarkdownNode}) rather
+* than named separately - it is used at exactly these two sites.
+*
+* @param value - The value to test
+* @returns `true` when `value` is a well-formed {@link BlockNode}
+*
+* @example
+* ```ts
+* import { isBlockNode } from '@orkestrel/markdown'
+*
+* isBlockNode({ element: 'thematicBreak' }) // true
+* isBlockNode({ element: 'heading' })       // false - missing `level` / `children`
+* ```
+*/
+var isBlockNode = unionOf(recordOf({
+	element: literalOf("heading"),
+	level: isNumber,
+	children: arrayOf(isInlineNode)
+}), recordOf({
+	element: literalOf("paragraph"),
+	children: arrayOf(isInlineNode)
+}), recordOf({
+	element: literalOf("list"),
+	ordered: isBoolean,
+	start: isNumber,
+	items: arrayOf(recordOf({
+		element: literalOf("listItem"),
+		children: arrayOf(lazyOf(() => isBlockNode))
+	}))
+}), recordOf({
+	element: literalOf("table"),
+	header: arrayOf(arrayOf(isInlineNode)),
+	rows: arrayOf(arrayOf(arrayOf(isInlineNode))),
+	align: arrayOf(literalOf("none", "left", "right", "center"))
+}), recordOf({
+	element: literalOf("codeBlock"),
+	lang: isString,
+	code: isString
+}, ["lang"]), recordOf({
+	element: literalOf("blockquote"),
+	children: arrayOf(lazyOf(() => isBlockNode))
+}), recordOf({ element: literalOf("thematicBreak") }));
+/**
+* Determine whether an arbitrary value is a valid {@link MarkdownNode} - the
+* {@link MarkdownDocument} root, a {@link BlockNode}, a {@link ListItemNode}, or
+* an {@link InlineNode}, recursively validated.
+*
+* @remarks
+* Total: never throws, even on cyclic or pathologically deep input - every
+* combinator involved (`unionOf`, `recordOf`, `arrayOf`, `lazyOf`) is
+* throw-contained per the `@orkestrel/contract` guard contract (AGENTS §14).
+* A list item's shape is inlined here (and in {@link isBlockNode}) rather than
+* named separately - it is used at exactly these two sites.
+*
+* @param value - The value to test
+* @returns `true` when `value` is a well-formed {@link MarkdownNode}
+*
+* @example
+* ```ts
+* import { isMarkdownNode } from '@orkestrel/markdown'
+*
+* isMarkdownNode({ element: 'text', value: 'hi' }) // true
+* isMarkdownNode({ element: 'bogus' })              // false
+* ```
+*/
+var isMarkdownNode = unionOf(lazyOf(() => isMarkdownDocument), lazyOf(() => isBlockNode), recordOf({
+	element: literalOf("listItem"),
+	children: arrayOf(lazyOf(() => isBlockNode))
+}), lazyOf(() => isInlineNode));
+/**
+* Determine whether an arbitrary value is a valid {@link MarkdownDocument} -
+* the parsed-AST root {@link parseDocument} returns, recursively
+* validated.
+*
+* @remarks
+* Total: never throws, even on cyclic or pathologically deep input - every
+* combinator involved (`recordOf`, `arrayOf`) is throw-contained per the
+* `@orkestrel/contract` guard contract (AGENTS §14).
+*
+* @param value - The value to test
+* @returns `true` when `value` is a well-formed {@link MarkdownDocument}
+*
+* @example
+* ```ts
+* import { isMarkdownDocument } from '@orkestrel/markdown'
+*
+* isMarkdownDocument({ element: 'document', children: [] }) // true
+* isMarkdownDocument({ element: 'document' })                 // false - missing `children`
+* ```
+*/
+var isMarkdownDocument = recordOf({
+	element: literalOf("document"),
+	children: arrayOf(isBlockNode)
+});
+//#endregion
+//#region src/core/helpers.ts
+/**
+* Normalize line endings to `\n` and split a markdown document into its lines - CRLF
+* (`\r\n`) and bare CR (`\r`) both collapse to `\n` first, so a Windows-origin
+* document parses identically. A single trailing newline does not yield a final
+* empty line.
+*
+* @param markdown - The raw markdown source
+* @returns The document's lines, line-terminators stripped
+*/
+function splitLines(markdown) {
+	const lines = markdown.replace(/\r\n?/g, "\n").split("\n");
+	if (lines.length > 1 && lines[lines.length - 1] === "") lines.pop();
+	return lines;
+}
+/**
+* The count of leading space / tab characters on `line` (a tab counts as one) - the
+* indent that decides whether a list item's continuation belongs to the item.
+*
+* @param line - The line to measure
+* @returns The number of leading space / tab characters
+*/
+function leadingIndent(line) {
+	let count = 0;
+	for (const character of line) if (character === " " || character === "	") count += 1;
+	else break;
+	return count;
+}
+/**
+* Extract an ATX heading line (`#` … `######` followed by text) into its
+* `{ level, text }`, or `undefined` when `line` is not a heading. A run of more than 6
+* `#`s, or `#`s not followed by whitespace + text, is not a
+* heading; an optional closing `###` run is stripped.
+*
+* @param line - The candidate line
+* @returns The heading level (1–6) and its raw inline text, or `undefined`
+*/
+function extractHeading(line) {
+	const match = /^(#{1,6})(?:\s+(.*))?$/.exec(line.trimStart());
+	if (!match || match[1] === void 0) return void 0;
+	return {
+		level: match[1].length,
+		text: (match[2] ?? "").replace(/\s+#+\s*$/, "").trim()
+	};
+}
+/**
+* Extract a fenced-code opening line (```` ``` ```` or `~~~`, optionally with an info
+* string) into its `{ marker, lang }`, or `undefined` when `line` is not a fence
+* opener. `marker` is the exact fence run (the closer must match the same character +
+* at least the same length); `lang` is the first word of the info string.
+*
+* @param line - The candidate line
+* @returns The fence marker run and its language tag, or `undefined`
+*/
+function extractFence(line) {
+	const match = /^\s*(`{3,}|~{3,})\s*(.*)$/.exec(line);
+	if (!match || match[1] === void 0) return void 0;
+	const info = (match[2] ?? "").trim();
+	if (match[1].startsWith("`") && info.includes("`")) return void 0;
+	const lang = isNonEmptyString(info) ? info.split(/\s+/)[0] : void 0;
+	return {
+		marker: match[1],
+		lang
+	};
+}
+/**
+* Extract a list-item line (`-` / `*` / `+` bullet, or `1.` / `1)` ordinal, followed by
+* a space) into its {@link ListItemParts}, or `undefined` when `line` is not a list
+* item. `content` is the text after the marker; `marker` is the full marker-plus-space
+* width (for measuring a continuation's indent).
+*
+* @param line - The candidate line
+* @returns The list-item parts, or `undefined` when not a list item
+*/
+function extractListItem(line) {
+	const unordered = /^(\s*)([-*+])\s+(.*)$/.exec(line);
+	if (unordered && unordered[1] !== void 0) {
+		const indent = unordered[1].length;
+		const content = unordered[3] ?? "";
+		return {
+			ordered: false,
+			start: 1,
+			content,
+			indent,
+			marker: line.length - content.length
+		};
+	}
+	const ordered = /^(\s*)(\d{1,9})[.)]\s+(.*)$/.exec(line);
+	if (ordered && ordered[1] !== void 0 && ordered[2] !== void 0) {
+		const indent = ordered[1].length;
+		const content = ordered[3] ?? "";
+		return {
+			ordered: true,
+			start: parseInteger(ordered[2]) ?? 1,
+			content,
+			indent,
+			marker: line.length - content.length
+		};
+	}
+}
+/**
+* Strip one level of blockquote marker (`>` plus one optional following space) from a
+* blockquote line, so the de-quoted lines re-parse as nested blocks.
+*
+* @param line - A blockquote line (per {@link isQuote})
+* @returns The line with its leading `>` (and one space) removed
+*/
+function stripQuote(line) {
+	return line.replace(/^\s{0,3}>\s?/, "");
+}
+/**
+* Split one GFM table row into its cell strings - outer pipes are optional, an escaped
+* pipe (`\|`) inside a cell is NOT a separator (it becomes a literal `|`), and the
+* empty leading / trailing cell produced by an outer `|` is dropped.
+*
+* @param row - The raw table row line
+* @returns The row's cells, in column order
+*/
+function splitTableRow(row) {
+	const cells = [];
+	let current = "";
+	const trimmed = row.trim();
+	for (let index = 0; index < trimmed.length; index += 1) {
+		const character = trimmed[index];
+		if (character === "\\" && trimmed[index + 1] === "|") {
+			current += "|";
+			index += 1;
+		} else if (character === "|") {
+			cells.push(current);
+			current = "";
+		} else current += character;
+	}
+	cells.push(current);
+	if (isNonEmptyArray(cells) && isEmptyString((cells[0] ?? "").trim())) cells.shift();
+	if (isNonEmptyArray(cells) && isEmptyString((cells[cells.length - 1] ?? "").trim())) cells.pop();
+	return cells;
+}
+/**
+* Derive the per-column {@link TableAlign} list from a GFM delimiter row - `:---`
+* left, `---:` right, `:---:` center, `---` none.
+*
+* @param delimiter - The table's delimiter row
+* @returns One alignment per column, in column order
+*/
+function tableAlignments(delimiter) {
+	return splitTableRow(delimiter).map((cell) => {
+		const text = cell.trim();
+		const left = text.startsWith(":");
+		const right = text.endsWith(":");
+		if (left && right) return "center";
+		if (right) return "right";
+		if (left) return "left";
+		return "none";
+	});
+}
+/**
+* Whether the line at `index` starts a NEW block kind (heading / fence / thematic
+* break / blockquote / list / table) - the paragraph collector stops at such a line
+* so a block following a paragraph without a blank line still parses (a trusted-input
+* caller writing a `##` heading directly under a paragraph, with no intervening blank
+* line).
+*
+* @param lines - The document's lines
+* @param index - The line index to test
+* @returns `true` when the line begins a different block
+*/
+function startsBlock(lines, index) {
+	const line = lines[index] ?? "";
+	return extractHeading(line) !== void 0 || extractFence(line) !== void 0 || isThematicBreak(line) || isQuote(line) || extractListItem(line) !== void 0 || isTableStart(line, lines[index + 1]);
+}
+/**
+* Resolve backslash escapes in a raw string to their literal characters - used for a
+* link `href` (which is not otherwise inline-parsed) and any plain text run.
+*
+* @param text - The raw text possibly carrying `\x` escapes
+* @returns The text with escapable `\x` reduced to `x`
+*/
+function unescapeText(text) {
+	let out = "";
+	for (let index = 0; index < text.length; index += 1) {
+		const character = text[index] ?? "";
+		if (character === "\\" && isEscapable(text[index + 1] ?? "")) {
+			out += text[index + 1] ?? "";
+			index += 1;
+		} else out += character;
+	}
+	return out;
+}
+/**
+* Merge adjacent text nodes into one - the inline scanner emits a text node per
+* unrecognized character, so coalescing keeps the AST clean and assertion-friendly.
+*
+* @param nodes - The inline nodes (possibly with adjacent text runs)
+* @returns The nodes with consecutive text nodes concatenated
+*/
+function coalesceText(nodes) {
+	const out = [];
+	for (const node of nodes) {
+		const last = out[out.length - 1];
+		if (node.element === "text" && last !== void 0 && last.element === "text") out[out.length - 1] = {
+			element: "text",
+			value: last.value + node.value
+		};
+		else out.push(node);
+	}
+	return out;
+}
+/**
+* Scan an inline code span at `start` (a `` ` ``-run … a matching `` ` ``-run of the
+* SAME length, the CommonMark rule that lets a span contain backticks). Returns the
+* span's literal text + end index, or `undefined` when no matching closer exists (it
+* then degrades to literal backticks).
+*
+* @param source - The inline source text
+* @param start - The index of the opening backtick
+* @param to - The exclusive end of the scan window
+* @returns The span text + end index, or `undefined`
+*/
+function scanCode(source, start, to) {
+	let run = 0;
+	while (start + run < to && source[start + run] === "`") run += 1;
+	const open = "`".repeat(run);
+	let search = start + run;
+	for (;;) {
+		const closeAt = source.indexOf(open, search);
+		if (closeAt === -1 || closeAt + run > to) return void 0;
+		if (source[closeAt - 1] !== "`" && source[closeAt + run] !== "`") {
+			let value = source.slice(start + run, closeAt);
+			if (value.length > 2 && value.startsWith(" ") && value.endsWith(" ") && value.trim().length > 0) value = value.slice(1, -1);
+			return {
+				value,
+				end: closeAt + run
+			};
+		}
+		search = closeAt + 1;
+	}
+}
+/**
+* Scan a link `[text](href)` at `start` - the text runs to a BALANCED `]`, then `(`
+* must immediately follow and the destination runs to the matching `)` (both respect
+* nested delimiters + escapes). Returns the link node, or `undefined` when the shape
+* does not hold (it then degrades to a literal `[`).
+*
+* @param source - The inline source text
+* @param start - The index of the opening `[`
+* @param to - The exclusive end of the scan window
+* @param depth - The current inline-recursion depth (defaults to 0 at the entry point);
+*   at {@link MAX_DEPTH} the link's text children degrade to literal text instead of
+*   recursing further
+* @returns The parsed {@link LinkNode} + end index, or `undefined`
+*/
+function scanLink(source, start, to, depth = 0) {
+	let bracketDepth = 0;
+	let close = -1;
+	for (let index = start; index < to; index += 1) {
+		const character = source[index] ?? "";
+		if (character === "\\") {
+			index += 1;
+			continue;
+		}
+		if (character === "[") bracketDepth += 1;
+		else if (character === "]") {
+			bracketDepth -= 1;
+			if (bracketDepth === 0) {
+				close = index;
+				break;
+			}
+		}
+	}
+	if (close === -1 || source[close + 1] !== "(") return void 0;
+	let parenDepth = 0;
+	let parenClose = -1;
+	for (let index = close + 1; index < to; index += 1) {
+		const character = source[index] ?? "";
+		if (character === "\\") {
+			index += 1;
+			continue;
+		}
+		if (character === "(") parenDepth += 1;
+		else if (character === ")") {
+			parenDepth -= 1;
+			if (parenDepth === 0) {
+				parenClose = index;
+				break;
+			}
+		}
+	}
+	if (parenClose === -1) return void 0;
+	return {
+		node: {
+			element: "link",
+			href: unescapeText(source.slice(close + 2, parenClose).trim()),
+			children: scanInline(source, start + 1, close, depth + 1)
+		},
+		end: parenClose + 1
+	};
+}
+/**
+* Scan an emphasis run at `start` (`*` / `_`, doubled for strong) - finds the nearest
+* matching closing run of the same marker + width, requiring non-space immediately
+* inside both delimiters (the CommonMark flanking simplification that blocks `* x *`).
+* Returns the emphasis node, or `undefined` when no valid closer exists (it then
+* degrades to a literal marker).
+*
+* @param source - The inline source text
+* @param start - The index of the opening marker
+* @param to - The exclusive end of the scan window
+* @param depth - The current inline-recursion depth (defaults to 0 at the entry point);
+*   at {@link MAX_DEPTH} the emphasis's children degrade to literal text instead of
+*   recursing further
+* @returns The parsed {@link EmphasisNode} + end index, or `undefined`
+*/
+function scanEmphasis(source, start, to, depth = 0) {
+	const marker = source[start] ?? "";
+	let run = 0;
+	while (start + run < to && source[start + run] === marker && run < 2) run += 1;
+	const strong = run === 2;
+	const openEnd = start + run;
+	if (openEnd >= to || isWhitespace(source[openEnd] ?? "")) return void 0;
+	let index = openEnd;
+	while (index < to) {
+		const character = source[index] ?? "";
+		if (character === "\\") {
+			index += 2;
+			continue;
+		}
+		if (character === "`") {
+			const span = scanCode(source, index, to);
+			index = span ? span.end : index + 1;
+			continue;
+		}
+		if (character === marker) {
+			let closeRun = 0;
+			while (index + closeRun < to && source[index + closeRun] === marker) closeRun += 1;
+			if (closeRun >= run && !isWhitespace(source[index - 1] ?? "")) return {
+				node: {
+					element: "emphasis",
+					strong,
+					children: scanInline(source, openEnd, index, depth + 1)
+				},
+				end: index + run
+			};
+			index += closeRun;
+			continue;
+		}
+		index += 1;
+	}
+}
+/**
+* Scan the window `[from, to)` of `source` into inline nodes - the single recursive
+* engine the inline phase runs on (emphasis / link text recurse through it). Linear:
+* each character is consumed once; a failed construct emits its opening character as
+* text and advances by one, so there is no re-scan (no ReDoS).
+*
+* @param source - The inline source text
+* @param from - The inclusive start of the scan window
+* @param to - The exclusive end of the scan window
+* @param depth - The current inline-recursion depth (defaults to 0 at the entry point);
+*   incremented by one on every recursive descent through {@link scanLink} /
+*   {@link scanEmphasis}. At {@link MAX_DEPTH} the window is never scanned for markup -
+*   it emits as a single literal text node - so pathological nesting (`[[[[…`,
+*   `****…`) cannot exhaust the call stack.
+* @returns The parsed inline nodes (NOT yet coalesced)
+*/
+function scanInline(source, from, to, depth = 0) {
+	if (depth >= 64) return from < to ? [{
+		element: "text",
+		value: source.slice(from, to)
+	}] : [];
+	const nodes = [];
+	let index = from;
+	let pending = "";
+	const flush = () => {
+		if (pending.length > 0) {
+			nodes.push({
+				element: "text",
+				value: pending
+			});
+			pending = "";
+		}
+	};
+	while (index < to) {
+		const character = source[index] ?? "";
+		if (character === "\\" && index + 1 < to && isEscapable(source[index + 1] ?? "")) {
+			pending += source[index + 1] ?? "";
+			index += 2;
+			continue;
+		}
+		if (character === "`") {
+			const span = scanCode(source, index, to);
+			if (span) {
+				flush();
+				nodes.push({
+					element: "codeSpan",
+					value: span.value
+				});
+				index = span.end;
+				continue;
+			}
+		}
+		if (character === "[") {
+			const link = scanLink(source, index, to, depth);
+			if (link) {
+				flush();
+				nodes.push(link.node);
+				index = link.end;
+				continue;
+			}
+		}
+		if (character === "*" || character === "_") {
+			const emphasis = scanEmphasis(source, index, to, depth);
+			if (emphasis) {
+				flush();
+				nodes.push(emphasis.node);
+				index = emphasis.end;
+				continue;
+			}
+		}
+		pending += character;
+		index += 1;
+	}
+	flush();
+	return nodes;
+}
+/**
+* HTML-escape text content - `&` / `<` / `>` / `"` / `'` to their entities - so text
+* from a markdown document can never inject markup. The renderer applies this to every
+* text run, code body, and (escaped further) attribute value.
+*
+* @param text - The raw text
+* @returns The HTML-escaped text
+*/
+function escapeHtml(text) {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+/**
+* Sanitize + HTML-attribute-escape a link `href` - a destination whose scheme is not
+* in {@link SAFE_URL_SCHEMES} (notably `javascript:` / `data:` / `vbscript:`), or that
+* is protocol-relative (`//host/path`, or a backslash variant a browser normalizes to
+* the same effect - `\\host`, `/\host`, `\/host` - inherits whatever scheme the
+* embedding page is served over, including an unsafe one), is dropped to an empty
+* string; a relative / anchor / scheme-less (and non-protocol-relative) destination
+* (including a SINGLE leading `/` or `\`) is kept;
+* the surviving value is then HTML-escaped. Defence-in-depth against an XSS `href`,
+* even though the input is trusted.
+*
+* @param href - The raw link destination
+* @returns A safe, escaped `href` (empty when the scheme is unsafe or protocol-relative)
+*/
+function sanitizeUrl(href) {
+	let cleaned = "";
+	for (const character of href) {
+		const code = character.codePointAt(0) ?? 0;
+		if (code > 32 && !(code >= 127 && code <= 159)) cleaned += character;
+	}
+	if (/^[/\\]{2}/.exec(cleaned)) return "";
+	const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(cleaned);
+	if (scheme && scheme[1] !== void 0 && !SAFE_URL_SCHEMES.has(scheme[1].toLowerCase())) return "";
+	return escapeHtml(cleaned);
+}
+/**
+* Render a {@link MarkdownNode} (typically a {@link MarkdownDocument}) to a safe HTML
+* string - the recursive AST → HTML engine (headings, paragraphs, lists, GFM tables,
+* fenced code, blockquotes, links, emphasis, inline code), escaping every text run and
+* sanitizing every link `href`.
+*
+* @remarks
+* Total: never throws. At {@link MAX_DEPTH} a value-bearing node (`text` / `codeSpan`)
+* degrades to its escaped `value`; any other node degrades to `''` instead of
+* recursing further, so pathologically deep input cannot exhaust the call stack. The
+* recursive engine and its per-shape sub-steps (inline concatenation, table cell,
+* tight list-item) are nested inner functions - the only exported surface is
+* `renderHTML` itself.
+*
+* @param node - The AST node to render (a full document, or any sub-node)
+* @returns The rendered, XSS-safe HTML string
+*
+* @example
+* ```ts
+* renderHTML({ element: 'document', children: [
+*   { element: 'heading', level: 1, children: [{ element: 'text', value: 'Hi' }] },
+* ] })
+* // '<h1>Hi</h1>'
+* ```
+*/
+function renderHTML(node) {
+	function render(current, depth) {
+		if (depth >= 64) return "value" in current && typeof current.value === "string" ? escapeHtml(current.value) : "";
+		switch (current.element) {
+			case "document": return current.children.map((child) => render(child, depth + 1)).join("\n");
+			case "heading": return `<h${current.level}>${renderInline(current.children, depth)}</h${current.level}>`;
+			case "paragraph": return `<p>${renderInline(current.children, depth)}</p>`;
+			case "thematicBreak": return "<hr>";
+			case "blockquote": return `<blockquote>\n${current.children.map((child) => render(child, depth + 1)).join("\n")}\n</blockquote>`;
+			case "codeBlock": return `<pre>${current.lang === void 0 ? "<code>" : `<code class="language-${escapeHtml(current.lang)}">`}${escapeHtml(current.code)}</code></pre>`;
+			case "list": {
+				const items = current.items.map((item) => render(item, depth + 1)).join("\n");
+				if (!current.ordered) return `<ul>\n${items}\n</ul>`;
+				return `<ol${current.start !== 1 ? ` start="${current.start}"` : ""}>\n${items}\n</ol>`;
+			}
+			case "listItem": return `<li>${renderItem(current.children, depth)}</li>`;
+			case "table": {
+				const head = `<tr>${current.header.map((cell, column) => renderCell("th", cell, current.align[column], depth)).join("")}</tr>`;
+				const body = current.rows.map((row) => `<tr>${row.map((cell, column) => renderCell("td", cell, current.align[column], depth)).join("")}</tr>`).join("\n");
+				return `<table>\n<thead>\n${head}\n</thead>${isNonEmptyArray(current.rows) ? `\n<tbody>\n${body}\n</tbody>` : ""}\n</table>`;
+			}
+			case "text": return escapeHtml(current.value);
+			case "emphasis": return current.strong ? `<strong>${renderInline(current.children, depth + 1)}</strong>` : `<em>${renderInline(current.children, depth + 1)}</em>`;
+			case "codeSpan": return `<code>${escapeHtml(current.value)}</code>`;
+			case "link": return `<a href="${sanitizeUrl(current.href)}">${renderInline(current.children, depth + 1)}</a>`;
+			default: return "";
+		}
+	}
+	function renderInline(nodes, depth) {
+		return nodes.map((child) => render(child, depth + 1)).join("");
+	}
+	function renderCell(tag, cell, align, depth) {
+		return `<${tag}${align === "left" || align === "right" || align === "center" ? ` style="text-align:${align}"` : ""}>${renderInline(cell, depth + 1)}</${tag}>`;
+	}
+	function renderItem(children, depth) {
+		if (children.length === 1) {
+			const only = children[0];
+			if (only !== void 0 && only.element === "paragraph") return renderInline(only.children, depth);
+		}
+		return children.map((child) => render(child, depth + 1)).join("\n");
+	}
+	return render(node, 0);
+}
+/**
+* Render a {@link MarkdownNode} to its CANONICAL markdown source - the inverse
+* projection of `renderHTML`, and the serializer a `parse(renderMarkdown(doc))`
+* round-trip is built on. Canonical forms: `*em*` / `**strong**` (underscore emphasis
+* normalizes to asterisks), `- ` bullets, `N. ` sequential ordinals (from the list's
+* `start`), `---` thematic breaks, fenced code blocks (backtick run widened past any
+* 3+ backtick run inside the body), ATX headings, `> `-prefixed blockquote lines, GFM
+* tables (1-space-padded cells, `\|`-escaped pipes, an alignment delimiter row), and
+* `[text](href)` links. A `text` node's literal content is backslash-escaped wherever
+* it would otherwise re-parse as markup (AGENTS §14 parse↔render soundness).
+*
+* @remarks
+* Total: never throws. At {@link MAX_DEPTH} a value-bearing node degrades to its
+* escaped `value`; any other node degrades to `''`. Blocks are joined by exactly one
+* blank line; a document with zero blocks renders `''`.
+*
+* @param node - The AST node to render (a full document, or any sub-node)
+* @returns The canonical markdown source
+*
+* @example
+* ```ts
+* renderMarkdown({ element: 'document', children: [
+*   { element: 'heading', level: 2, children: [{ element: 'text', value: 'Hi' }] },
+* ] })
+* // '## Hi'
+* ```
+*/
+function renderMarkdown(node) {
+	function escapeText(value) {
+		let out = "";
+		for (let index = 0; index < value.length; index += 1) {
+			const character = value[index] ?? "";
+			const atLineStart = index === 0 || value[index - 1] === "\n";
+			if (character === "\\" || character === "*" || character === "_" || character === "`" || character === "[" || character === "]") {
+				out += `\\${character}`;
+				continue;
+			}
+			if (atLineStart) {
+				if (character === "#" || character === ">") {
+					out += `\\${character}`;
+					continue;
+				}
+				if ((character === "-" || character === "+") && (value[index + 1] ?? " ") === " ") {
+					out += `\\${character}`;
+					continue;
+				}
+				if (/[0-9]/.test(character)) {
+					let end = index;
+					while (end < value.length && /[0-9]/.test(value[end] ?? "")) end += 1;
+					const marker = value[end];
+					if ((marker === "." || marker === ")") && value[end + 1] === " ") {
+						out += `${value.slice(index, end)}\\${marker}`;
+						index = end;
+						continue;
+					}
+				}
+			}
+			out += character;
+		}
+		return out;
+	}
+	function fenceFor(body, minimum) {
+		let longest = 0;
+		let run = 0;
+		for (const character of body) if (character === "`") {
+			run += 1;
+			longest = Math.max(longest, run);
+		} else run = 0;
+		return "`".repeat(Math.max(minimum, longest + 1));
+	}
+	function renderInline(nodes, depth) {
+		return nodes.map((child) => render(child, depth + 1)).join("");
+	}
+	function renderBlocks(blocks, depth) {
+		return blocks.map((block) => render(block, depth + 1)).join("\n\n");
+	}
+	function renderItem(item, marker, depth) {
+		const body = renderBlocks(item.children, depth + 1);
+		const pad = " ".repeat(marker.length);
+		return body.split("\n").map((line, index) => index === 0 ? marker + line : line === "" ? "" : pad + line).join("\n");
+	}
+	function renderCell(cell, depth) {
+		return renderInline(cell, depth + 1).replace(/\|/g, "\\|");
+	}
+	function renderTable(current, depth) {
+		const columns = current.header.length;
+		return [
+			`| ${current.header.map((cell) => renderCell(cell, depth)).join(" | ")} |`,
+			`| ${current.align.map((align) => {
+				if (align === "left") return ":--";
+				if (align === "right") return "--:";
+				if (align === "center") return ":-:";
+				return "---";
+			}).join(" | ")} |`,
+			...current.rows.map((row) => {
+				const cells = [];
+				for (let column = 0; column < columns; column += 1) {
+					const cell = row[column];
+					cells.push(cell === void 0 ? "" : renderCell(cell, depth));
+				}
+				return `| ${cells.join(" | ")} |`;
+			})
+		].join("\n");
+	}
+	function render(current, depth) {
+		if (depth >= 64) return "value" in current && typeof current.value === "string" ? escapeText(current.value) : "";
+		switch (current.element) {
+			case "document": return renderBlocks(current.children, depth);
+			case "heading": {
+				const escaped = renderInline(current.children, depth).replace(/(^|[^\\])(#+)$/, (_match, pre, hashes) => {
+					return `${pre}\\${hashes[0] ?? ""}${hashes.slice(1)}`;
+				});
+				return `${"#".repeat(current.level)} ${escaped}`;
+			}
+			case "paragraph": return renderInline(current.children, depth);
+			case "thematicBreak": return "---";
+			case "blockquote": return renderBlocks(current.children, depth).split("\n").map((line) => line === "" ? ">" : `> ${line}`).join("\n");
+			case "codeBlock": {
+				const fence = fenceFor(current.code, 3);
+				return `${fence}${current.lang === void 0 ? "" : current.lang}\n${current.code}\n${fence}`;
+			}
+			case "list": {
+				let ordinal = current.start;
+				return current.items.map((item) => {
+					return renderItem(item, current.ordered ? `${ordinal++}. ` : "- ", depth);
+				}).join("\n");
+			}
+			case "listItem": return renderBlocks(current.children, depth);
+			case "table": return renderTable(current, depth);
+			case "text": return escapeText(current.value);
+			case "emphasis": {
+				const marker = current.strong ? "**" : "*";
+				return `${marker}${renderInline(current.children, depth)}${marker}`;
+			}
+			case "codeSpan": {
+				const fence = fenceFor(current.value, 1);
+				const pad = current.value.startsWith("`") || current.value.endsWith("`") ? " " : "";
+				return `${fence}${pad}${current.value}${pad}${fence}`;
+			}
+			case "link": {
+				const href = current.href.replace(/[\\()]/g, (character) => `\\${character}`);
+				return `[${renderInline(current.children, depth)}](${href})`;
+			}
+			default: return "";
+		}
+	}
+	return render(node, 0);
+}
+/**
+* Depth-first, pre-order, root-inclusive traversal of a {@link MarkdownNode} - yields
+* the node itself, then recurses into its children (block children, list items, table
+* header/row cells' inline nodes) in walk order.
+*
+* @remarks
+* Total: never throws. Descent stops at {@link MAX_DEPTH} (the node at the cap is
+* still yielded; its children are not) so pathologically deep input cannot exhaust
+* the call stack.
+*
+* @param node - The AST node to walk (a full document, or any sub-node)
+* @returns A generator yielding every visited node, pre-order
+*
+* @example
+* ```ts
+* const doc = { element: 'document', children: [{ element: 'thematicBreak' }] } as const
+* [...walkNodes(doc)].map((node) => node.element) // ['document', 'thematicBreak']
+* ```
+*/
+function* walkNodes(node) {
+	function* walk(current, depth) {
+		yield current;
+		if (depth >= 64) return;
+		switch (current.element) {
+			case "document":
+			case "heading":
+			case "paragraph":
+			case "blockquote":
+			case "listItem":
+			case "emphasis":
+			case "link":
+				for (const child of current.children) yield* walk(child, depth + 1);
+				return;
+			case "list":
+				for (const item of current.items) yield* walk(item, depth + 1);
+				return;
+			case "table":
+				for (const cell of current.header) for (const inline of cell) yield* walk(inline, depth + 1);
+				for (const row of current.rows) for (const cell of row) for (const inline of cell) yield* walk(inline, depth + 1);
+				return;
+			default: return;
+		}
+	}
+	yield* walk(node, 0);
+}
+/**
+* Fold a {@link MarkdownNode} into a `T` via a total catamorphism - children are
+* folded first (post-order), then the node's own {@link MarkdownHandler} is invoked
+* with the already-folded children.
+*
+* @remarks
+* **Table contract.** A {@link TableNode} has no single `children` array - its cells
+* live in `header` (one inline-node list per column) and `rows` (a list of such
+* rows). The `table` handler receives ONE folded `T` per inline node, flattened in
+* walk order across ALL cells - every header cell's inline nodes (column order), then
+* every body row's cells' inline nodes (row order, then column order) - and reads
+* `node.header[c].length` / `node.rows[r][c].length` off the table node itself to
+* recover cell boundaries within the flat list.
+*
+* Total: never throws. At `depth >= {@link MAX_DEPTH}` the node's handler is invoked
+* with an empty children list instead of recursing further.
+*
+* @param node - The AST node to fold
+* @param handlers - The total {@link MarkdownHandlers} table, one handler per element
+* @param depth - The starting recursion depth (pass `0` at the entry point)
+* @returns The folded `T`
+*
+* @example
+* ```ts
+* const countHandlers: MarkdownHandlers<number> = {
+*   document: (_, children) => children.reduce((a, b) => a + b, 1),
+*   // ...one handler per element, each summing its folded children
+* }
+* foldNode(document, countHandlers, 0) // total node count
+* ```
+*/
+function foldNode(node, handlers, depth) {
+	function dispatch(current, children) {
+		switch (current.element) {
+			case "document": return handlers.document(current, children);
+			case "heading": return handlers.heading(current, children);
+			case "paragraph": return handlers.paragraph(current, children);
+			case "thematicBreak": return handlers.thematicBreak(current, children);
+			case "blockquote": return handlers.blockquote(current, children);
+			case "codeBlock": return handlers.codeBlock(current, children);
+			case "list": return handlers.list(current, children);
+			case "listItem": return handlers.listItem(current, children);
+			case "table": return handlers.table(current, children);
+			case "text": return handlers.text(current, children);
+			case "emphasis": return handlers.emphasis(current, children);
+			case "codeSpan": return handlers.codeSpan(current, children);
+			case "link": return handlers.link(current, children);
+		}
+	}
+	function childNodes(current) {
+		switch (current.element) {
+			case "document":
+			case "heading":
+			case "paragraph":
+			case "blockquote":
+			case "listItem":
+			case "emphasis":
+			case "link": return current.children;
+			case "list": return current.items;
+			case "table": {
+				const header = current.header.flatMap((cell) => cell);
+				const rows = current.rows.flatMap((row) => row.flatMap((cell) => cell));
+				return [...header, ...rows];
+			}
+			default: return [];
+		}
+	}
+	function fold(current, level) {
+		if (level >= 64) return dispatch(current, []);
+		return dispatch(current, childNodes(current).map((child) => fold(child, level + 1)));
+	}
+	return fold(node, depth);
+}
+/**
+* Rewrite a {@link MarkdownDocument} bottom-up (copy-on-write) - each node's children
+* are rewritten first (post-order), then `rewrite` is applied to the node itself; the
+* document ROOT is never passed to `rewrite` (the `element: 'document'` invariant
+* always holds). A table's inline cells and a list's items ARE rewritten.
+*
+* @remarks
+* Never mutates `document` - every level is rebuilt into a fresh object/array, even
+* when `rewrite` returns its input unchanged. When `rewrite` returns a node whose
+* `element` does not fit the slot it was called for (a block slot handed a
+* non-{@link BlockNode}, an inline slot handed a non-{@link InlineNode}, a list-item
+* slot handed a non-`listItem`), the ill-fitting result is discarded and the
+* freshly-rebuilt (unrewritten-at-this-level) node is kept instead - `rewriteDocument`
+* stays total and never produces a structurally invalid document.
+*
+* Descent is capped at {@link MAX_DEPTH}, the same cap {@link walkNodes} and
+* {@link foldNode} observe: at `depth >= MAX_DEPTH` the subtree is passed through
+* UNCHANGED (by reference, not rebuilt, and `rewrite` is not invoked on it) instead of
+* recursing further, so a pathologically deep adopted document cannot exhaust the
+* call stack. {@link MarkdownInterface.map} inherits this cap since it delegates here.
+*
+* @param document - The document AST to rewrite
+* @param rewrite - The bottom-up {@link MarkdownRewriteHandler}
+* @returns A new, rewritten {@link MarkdownDocument}
+*
+* @example
+* ```ts
+* rewriteDocument(document, (node) =>
+*   node.element === 'text' ? { element: 'text', value: node.value.toUpperCase() } : node,
+* )
+* ```
+*/
+function rewriteDocument(document, rewrite) {
+	function rewriteInline(node, depth) {
+		if (depth >= 64) return node;
+		const rebuilt = rebuildInline(node, depth);
+		const result = rewrite(rebuilt);
+		return isInlineNode(result) ? result : rebuilt;
+	}
+	function rewriteBlock(node, depth) {
+		if (depth >= 64) return node;
+		const rebuilt = rebuildBlock(node, depth);
+		const result = rewrite(rebuilt);
+		return isBlockNode(result) ? result : rebuilt;
+	}
+	function rewriteItem(item, depth) {
+		if (depth >= 64) return item;
+		const rebuilt = {
+			element: "listItem",
+			children: item.children.map((child) => rewriteBlock(child, depth + 1))
+		};
+		const result = rewrite(rebuilt);
+		return result.element === "listItem" ? result : rebuilt;
+	}
+	function rebuildInline(node, depth) {
+		switch (node.element) {
+			case "emphasis": return {
+				...node,
+				children: node.children.map((child) => rewriteInline(child, depth + 1))
+			};
+			case "link": return {
+				...node,
+				children: node.children.map((child) => rewriteInline(child, depth + 1))
+			};
+			case "text":
+			case "codeSpan": return node;
+		}
+	}
+	function rebuildBlock(node, depth) {
+		switch (node.element) {
+			case "heading": return {
+				...node,
+				children: node.children.map((child) => rewriteInline(child, depth + 1))
+			};
+			case "paragraph": return {
+				...node,
+				children: node.children.map((child) => rewriteInline(child, depth + 1))
+			};
+			case "blockquote": return {
+				...node,
+				children: node.children.map((child) => rewriteBlock(child, depth + 1))
+			};
+			case "list": return {
+				...node,
+				items: node.items.map((item) => rewriteItem(item, depth + 1))
+			};
+			case "table": return {
+				...node,
+				header: node.header.map((cell) => cell.map((inline) => rewriteInline(inline, depth + 1))),
+				rows: node.rows.map((row) => row.map((cell) => cell.map((inline) => rewriteInline(inline, depth + 1))))
+			};
+			case "codeBlock":
+			case "thematicBreak": return node;
+		}
+	}
+	return {
+		element: "document",
+		children: document.children.map((child) => rewriteBlock(child, 0))
+	};
+}
+/**
+* Concatenate the `value` / `code` content of every descendant text / code-span /
+* code-block node under `node`, in walk order - the plain-text projection of an AST
+* (search indexing, word counts, a text-only preview).
+*
+* @remarks
+* Total: never throws. Descent stops at {@link MAX_DEPTH} (contributes `''` past the
+* cap instead of recursing further).
+*
+* @param node - The AST node to flatten (a full document, or any sub-node)
+* @returns The concatenated text content
+*
+* @example
+* ```ts
+* flattenText({ element: 'paragraph', children: [
+*   { element: 'text', value: 'a ' },
+*   { element: 'codeSpan', value: 'b' },
+* ] })
+* // 'a b'
+* ```
+*/
+function flattenText(node) {
+	function flatten(current, depth) {
+		if (depth >= 64) return "";
+		switch (current.element) {
+			case "text": return current.value;
+			case "codeSpan": return current.value;
+			case "codeBlock": return current.code;
+			case "document":
+			case "heading":
+			case "paragraph":
+			case "blockquote":
+			case "listItem":
+			case "emphasis":
+			case "link": return current.children.map((child) => flatten(child, depth + 1)).join("");
+			case "list": return current.items.map((item) => flatten(item, depth + 1)).join("");
+			case "table": return current.header.map((cell) => cell.map((inline) => flatten(inline, depth + 1)).join("")).join("") + current.rows.map((row) => row.map((cell) => cell.map((inline) => flatten(inline, depth + 1)).join("")).join("")).join("");
+			case "thematicBreak": return "";
+			default: return "";
+		}
+	}
+	return flatten(node, 0);
+}
+//#endregion
+//#region src/core/parsers.ts
+/**
+* Parses a run of markdown lines into a block AST, recursing into nested
+* blockquotes, list items, and depth-capped degrade paragraphs.
+*
+* @param lines - The markdown lines to parse.
+* @param depth - The current recursion depth (blockquotes/lists increment it).
+* @returns The parsed block nodes.
+*/
+function parseBlocks(lines, depth) {
+	if (depth >= 64) return lines.length > 0 ? [{
+		element: "paragraph",
+		children: [{
+			element: "text",
+			value: lines.join("\n")
+		}]
+	}] : [];
+	const blocks = [];
+	let index = 0;
+	while (index < lines.length) {
+		const line = lines[index] ?? "";
+		if (isBlankLine(line)) {
+			index += 1;
+			continue;
+		}
+		const fence = extractFence(line);
+		if (fence) {
+			const body = [];
+			index += 1;
+			while (index < lines.length && !isFenceClose(lines[index] ?? "", fence.marker)) {
+				body.push(lines[index] ?? "");
+				index += 1;
+			}
+			index += 1;
+			blocks.push({
+				element: "codeBlock",
+				...fence.lang === void 0 ? {} : { lang: fence.lang },
+				code: body.join("\n")
+			});
+			continue;
+		}
+		if (isThematicBreak(line)) {
+			blocks.push({ element: "thematicBreak" });
+			index += 1;
+			continue;
+		}
+		const heading = extractHeading(line);
+		if (heading) {
+			blocks.push({
+				element: "heading",
+				level: heading.level,
+				children: parseInline(heading.text)
+			});
+			index += 1;
+			continue;
+		}
+		if (isQuote(line)) {
+			const quoted = [];
+			while (index < lines.length && isQuote(lines[index] ?? "")) {
+				quoted.push(stripQuote(lines[index] ?? ""));
+				index += 1;
+			}
+			blocks.push({
+				element: "blockquote",
+				children: parseBlocks(quoted, depth + 1)
+			});
+			continue;
+		}
+		if (isTableStart(line, lines[index + 1])) {
+			const table = collectTable(lines, index);
+			blocks.push(table.node);
+			index = table.next;
+			continue;
+		}
+		if (extractListItem(line)) {
+			const list = collectList(lines, index, depth);
+			blocks.push(list.node);
+			index = list.next;
+			continue;
+		}
+		const paragraph = [];
+		while (index < lines.length && !isBlankLine(lines[index] ?? "") && !(isNonEmptyArray(paragraph) && startsBlock(lines, index))) {
+			paragraph.push((lines[index] ?? "").trim());
+			index += 1;
+		}
+		blocks.push({
+			element: "paragraph",
+			children: parseInline(paragraph.join("\n"))
+		});
+	}
+	return blocks;
+}
+/**
+* Collects a GFM table starting at a header row, parsing the header, the
+* alignment row, and every contiguous body row that follows.
+*
+* @param lines - The markdown lines to scan.
+* @param start - The index of the header row.
+* @returns The parsed table node and the index of the first line after it.
+*/
+function collectTable(lines, start) {
+	const headerCells = splitTableRow(lines[start] ?? "");
+	const columns = headerCells.length;
+	const header = headerCells.map((cell) => parseInline(cell.trim()));
+	const align = tableAlignments(lines[start + 1] ?? "");
+	const padded = [];
+	for (let column = 0; column < columns; column += 1) padded.push(align[column] ?? "none");
+	const rows = [];
+	let index = start + 2;
+	while (index < lines.length && !isBlankLine(lines[index] ?? "") && (lines[index] ?? "").includes("|")) {
+		const cells = splitTableRow(lines[index] ?? "");
+		const row = [];
+		for (let column = 0; column < columns; column += 1) row.push(parseInline((cells[column] ?? "").trim()));
+		rows.push(row);
+		index += 1;
+	}
+	return {
+		node: {
+			element: "table",
+			header,
+			rows,
+			align: padded
+		},
+		next: index
+	};
+}
+/**
+* Collects a list starting at the first item, gathering sibling items at the
+* same indent/ordering and recursing into each item's own block content.
+*
+* @param lines - The markdown lines to scan.
+* @param start - The index of the first list item.
+* @param depth - The current recursion depth (each item recurses at `depth + 1`).
+* @returns The parsed list node and the index of the first line after it.
+*/
+function collectList(lines, start, depth) {
+	const first = extractListItem(lines[start] ?? "");
+	const ordered = first?.ordered ?? false;
+	const startOrdinal = first?.start ?? 1;
+	const topIndent = first?.indent ?? 0;
+	const items = [];
+	let index = start;
+	while (index < lines.length) {
+		const parsed = extractListItem(lines[index] ?? "");
+		if (!parsed || parsed.indent > topIndent || parsed.ordered !== ordered) break;
+		const itemLines = [parsed.content];
+		const continuation = parsed.marker;
+		index += 1;
+		while (index < lines.length) {
+			const next = lines[index] ?? "";
+			if (isBlankLine(next)) {
+				const after = lines[index + 1] ?? "";
+				if (index + 1 < lines.length && !isBlankLine(after) && leadingIndent(after) >= continuation) {
+					itemLines.push("");
+					index += 1;
+					continue;
+				}
+				break;
+			}
+			if (leadingIndent(next) >= continuation) {
+				itemLines.push(next.slice(continuation));
+				index += 1;
+				continue;
+			}
+			if (extractListItem(next) || startsBlock(lines, index)) break;
+			itemLines.push(next.trim());
+			index += 1;
+		}
+		items.push({
+			element: "listItem",
+			children: parseBlocks(itemLines, depth + 1)
+		});
+	}
+	return {
+		node: {
+			element: "list",
+			ordered,
+			start: startOrdinal,
+			items
+		},
+		next: index
+	};
+}
+/**
+* Parses a markdown string into a typed {@link MarkdownDocument} AST via the
+* block phase.
+*
+* @param markdown - The markdown source to parse.
+* @returns The parsed document.
+*/
+function parseDocument(markdown) {
+	return {
+		element: "document",
+		children: parseBlocks(splitLines(markdown), 0)
+	};
+}
+/**
+* Parses inline markdown text (emphasis, code spans, links) into inline AST
+* nodes, coalescing adjacent text runs.
+*
+* @param text - The inline markdown text to parse.
+* @returns The parsed inline nodes.
+*/
+function parseInline(text) {
+	return coalesceText(scanInline(text, 0, text.length));
+}
+//#endregion
+//#region src/core/shapers.ts
+/**
+* The shape of a {@link TextNode} - a plain-text leaf inline run.
+*
+* @example
+* ```ts
+* import { createContract } from '@orkestrel/contract'
+* import { textShape } from '@src/core'
+*
+* const text = createContract(textShape)
+* text.is({ element: 'text', value: 'hi' }) // true
+* ```
+*/
+var textShape = objectShape({
+	element: literalShape(["text"]),
+	value: stringShape()
+});
+/**
+* The shape of a {@link CodeSpanNode} - an inline code span (`` `code` ``).
+*
+* @example
+* ```ts
+* import { createContract } from '@orkestrel/contract'
+* import { codeSpanShape } from '@src/core'
+*
+* const codeSpan = createContract(codeSpanShape)
+* codeSpan.is({ element: 'codeSpan', value: 'const x = 1' }) // true
+* ```
+*/
+var codeSpanShape = objectShape({
+	element: literalShape(["codeSpan"]),
+	value: stringShape()
+});
+/**
+* The shape of a {@link CodeBlockNode} - a fenced code block. `lang` is
+* optional (absent when the opening fence carries no info-string).
+*
+* @example
+* ```ts
+* import { createContract } from '@orkestrel/contract'
+* import { codeBlockShape } from '@src/core'
+*
+* const codeBlock = createContract(codeBlockShape)
+* codeBlock.is({ element: 'codeBlock', code: 'x' })                    // true
+* codeBlock.is({ element: 'codeBlock', code: 'x', lang: 'ts' })        // true
+* ```
+*/
+var codeBlockShape = objectShape({
+	element: literalShape(["codeBlock"]),
+	lang: optionalShape(stringShape()),
+	code: stringShape()
+});
+/**
+* The shape of a {@link ThematicBreakNode} - a horizontal rule. Carries no
+* fields beyond its `element` discriminant.
+*
+* @example
+* ```ts
+* import { createContract } from '@orkestrel/contract'
+* import { thematicBreakShape } from '@src/core'
+*
+* const thematicBreak = createContract(thematicBreakShape)
+* thematicBreak.is({ element: 'thematicBreak' }) // true
+* ```
+*/
+var thematicBreakShape = objectShape({ element: literalShape(["thematicBreak"]) });
+/**
+* The shape of a {@link TableAlign} - the per-column GFM table alignment
+* literal.
+*
+* @example
+* ```ts
+* import { createContract } from '@orkestrel/contract'
+* import { tableAlignShape } from '@src/core'
+*
+* const tableAlign = createContract(tableAlignShape)
+* tableAlign.is('left')   // true
+* tableAlign.is('center') // true
+* tableAlign.is('top')    // false
+* ```
+*/
+var tableAlignShape = literalShape([
+	"none",
+	"left",
+	"right",
+	"center"
+]);
+/**
+* The shape of {@link ListItemParts} - the parsed parts of a single list-item
+* line the block phase's list detector returns. Fully non-recursive (no
+* nested node fields), so every field shapes directly.
+*
+* @example
+* ```ts
+* import { createContract } from '@orkestrel/contract'
+* import { listItemPartsShape } from '@src/core'
+*
+* const listItemParts = createContract(listItemPartsShape)
+* listItemParts.is({ ordered: false, start: 1, content: 'hi', indent: 0, marker: 2 }) // true
+* ```
+*/
+var listItemPartsShape = objectShape({
+	ordered: booleanShape(),
+	start: integerShape(),
+	content: stringShape(),
+	indent: integerShape(),
+	marker: integerShape()
+});
+//#endregion
+//#region src/core/Markdown.ts
+/**
+* A stateful, parsed markdown document - wraps a typed {@link MarkdownDocument} AST
+* with the query (`find` / `filter` / `reduce` / iteration), rewrite (`map`), fold, and
+* streaming operations {@link MarkdownInterface} declares.
+*
+* @remarks
+* - **Construction.** Given a `string`, the constructor runs {@link parseDocument} (the
+*   block phase then the inline phase) to build the AST. Given a {@link MarkdownDocument},
+*   the document is adopted AS-IS and is NOT re-validated - a caller adopting an
+*   untrusted value should gate it with `isMarkdownDocument` first.
+* - **Immutable.** {@link map} never mutates the stored AST - it returns a NEW `Markdown`
+*   instance; the document root invariant (`element: 'document'`) always holds.
+* - **Traversal order.** {@link walk} and the `find` / `filter` / `reduce` queries built
+*   on it walk the AST depth-first, pre-order, root-inclusive (via {@link walkNodes});
+*   `stream` is shallow - only the document's direct block children.
+*
+* @example
+* ```ts
+* import { Markdown, isHeadingNode, renderMarkdown } from '@src/core'
+*
+* const markdown = new Markdown('# Title\n\nA **bold** [link](https://x.dev).')
+* const heading = markdown.find(isHeadingNode) // the HeadingNode, or undefined
+* const shouted = markdown.map((node) =>
+*   node.element === 'text' ? { element: 'text', value: node.value.toUpperCase() } : node,
+* )
+* renderMarkdown(shouted.document) // '# TITLE\n\nA **BOLD** [LINK](https://x.dev).'
+* ```
+*/
+var Markdown = class Markdown {
+	#document;
+	constructor(input) {
+		this.#document = typeof input === "string" ? parseDocument(input) : input;
+	}
+	/** The stored {@link MarkdownDocument} AST root. */
+	get document() {
+		return this.#document;
+	}
+	/**
+	* THE deep traversal - a lazy, depth-first, pre-order, root-inclusive generator
+	* over every {@link MarkdownNode} in the document. `find` / `filter` / `reduce`
+	* all iterate this single traversal.
+	*
+	* @example
+	* ```ts
+	* for (const node of markdown.walk()) {
+	*   // every node, depth-first, pre-order, root-inclusive
+	* }
+	*
+	* // also consumable by for-await - JS accepts a sync iterable in for-await
+	* for await (const node of markdown.walk()) {
+	*   // same sequence, no separate async iterator needed
+	* }
+	* ```
+	*/
+	*walk() {
+		yield* walkNodes(this.#document);
+	}
+	find(predicate) {
+		for (const node of this.walk()) if (predicate(node)) return node;
+	}
+	filter(predicate) {
+		const out = [];
+		for (const node of this.walk()) if (predicate(node)) out.push(node);
+		return out;
+	}
+	/** Rewrites the AST bottom-up (copy-on-write) and returns a new {@link Markdown}. */
+	map(rewrite) {
+		return new Markdown(rewriteDocument(this.#document, rewrite));
+	}
+	/** Folds the AST depth-first, pre-order into an accumulator. */
+	reduce(callback, initial) {
+		let accumulator = initial;
+		for (const node of this.walk()) accumulator = callback(accumulator, node);
+		return accumulator;
+	}
+	/** Runs a total catamorphism over the document using a {@link MarkdownHandlers} table. */
+	fold(handlers) {
+		return foldNode(this.#document, handlers, 0);
+	}
+	/**
+	* A web-standard {@link ReadableStream} over the document's top-level block nodes
+	* (shallow, source order) - a fresh, pull-based source per call: one block is
+	* enqueued per `pull`, so a slow reader's backpressure is respected. Cancellable,
+	* async-iterable wherever the platform supports it (Node, Deno), and pipeable
+	* through any {@link TransformStream} / {@link WritableStream}.
+	*
+	* @example
+	* ```ts
+	* // universal - works in every ReadableStream-supporting environment
+	* const reader = markdown.stream().getReader()
+	* for (let result = await reader.read(); !result.done; result = await reader.read()) {
+	*   console.log(result.value) // one BlockNode
+	* }
+	*
+	* // Node / Deno / Firefox support async iteration of ReadableStream natively;
+	* // other environments should use the reader loop above instead.
+	* for await (const block of markdown.stream()) {
+	*   console.log(block)
+	* }
+	* ```
+	*/
+	stream() {
+		const blocks = this.#document.children;
+		let index = 0;
+		return new ReadableStream({ pull(controller) {
+			if (index < blocks.length) {
+				controller.enqueue(blocks[index]);
+				index += 1;
+			} else controller.close();
+		} });
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Create a stateful markdown handle from a markdown string or an already-parsed
+* {@link MarkdownDocument} - a typed AST plus the query, rewrite, and fold operations
+* {@link MarkdownInterface} exposes.
+*
+* @remarks
+* Given a `string`, runs a block phase (headings / paragraphs / lists / GFM tables /
+* fenced code / blockquotes / thematic breaks) then an inline phase (emphasis /
+* inline code / links) to build a render-agnostic {@link MarkdownDocument}. Given a
+* {@link MarkdownDocument}, adopts it AS-IS without re-validation - gate an untrusted
+* value with `isMarkdownDocument` first. Pure + total parse (malformed markdown
+* degrades to text, never throws) and zero-dependency - a hand-written scanner, no
+* regex-only structural parse, linear-time (no ReDoS).
+*
+* @param input - A markdown string to parse, or an already-parsed {@link MarkdownDocument}
+* @returns A working {@link MarkdownInterface}
+*
+* @example
+* ```ts
+* import { createMarkdown } from '@src/core'
+*
+* const markdown = createMarkdown('# Hi\n\nRead the [guide](./guide.md).')
+* markdown.document.children[0] // { element: 'heading', ... }
+* ```
+*/
+function createMarkdown(input) {
+	return new Markdown(input);
+}
+/**
+* Compile the {@link textShape} into a {@link ContractInterface} for
+* {@link TextNode} - a guard, coercing parser, JSON Schema, and seeded
+* generator from one shape declaration (AGENTS §14).
+*
+* @returns A `TextNode` contract bundling `schema` / `is` / `parse` / `generate`
+*
+* @example
+* ```ts
+* import { createTextContract } from '@src/core'
+*
+* const text = createTextContract()
+* text.is({ element: 'text', value: 'hi' }) // true
+* ```
+*/
+function createTextContract() {
+	return createContract(textShape);
+}
+/**
+* Compile the {@link codeSpanShape} into a {@link ContractInterface} for
+* {@link CodeSpanNode} - a guard, coercing parser, JSON Schema, and seeded
+* generator from one shape declaration (AGENTS §14).
+*
+* @returns A `CodeSpanNode` contract bundling `schema` / `is` / `parse` / `generate`
+*
+* @example
+* ```ts
+* import { createCodeSpanContract } from '@src/core'
+*
+* const codeSpan = createCodeSpanContract()
+* codeSpan.is({ element: 'codeSpan', value: 'const x = 1' }) // true
+* ```
+*/
+function createCodeSpanContract() {
+	return createContract(codeSpanShape);
+}
+/**
+* Compile the {@link codeBlockShape} into a {@link ContractInterface} for
+* {@link CodeBlockNode} - a guard, coercing parser, JSON Schema, and seeded
+* generator from one shape declaration (AGENTS §14).
+*
+* @returns A `CodeBlockNode` contract bundling `schema` / `is` / `parse` / `generate`
+*
+* @example
+* ```ts
+* import { createCodeBlockContract } from '@src/core'
+*
+* const codeBlock = createCodeBlockContract()
+* codeBlock.is({ element: 'codeBlock', code: 'x' }) // true
+* ```
+*/
+function createCodeBlockContract() {
+	return createContract(codeBlockShape);
+}
+/**
+* Compile the {@link thematicBreakShape} into a {@link ContractInterface} for
+* {@link ThematicBreakNode} - a guard, coercing parser, JSON Schema, and
+* seeded generator from one shape declaration (AGENTS §14).
+*
+* @returns A `ThematicBreakNode` contract bundling `schema` / `is` / `parse` / `generate`
+*
+* @example
+* ```ts
+* import { createThematicBreakContract } from '@src/core'
+*
+* const thematicBreak = createThematicBreakContract()
+* thematicBreak.is({ element: 'thematicBreak' }) // true
+* ```
+*/
+function createThematicBreakContract() {
+	return createContract(thematicBreakShape);
+}
+//#endregion
+export { MAX_DEPTH, Markdown, SAFE_URL_SCHEMES, coalesceText, codeBlockShape, codeSpanShape, collectList, collectTable, createCodeBlockContract, createCodeSpanContract, createMarkdown, createTextContract, createThematicBreakContract, escapeHtml, extractFence, extractHeading, extractListItem, flattenText, foldNode, isBlankLine, isBlockNode, isBlockquoteNode, isCodeBlockNode, isCodeSpanNode, isEmphasisNode, isEscapable, isFenceClose, isFenceWhitespace, isHeadingNode, isInlineNode, isLinkNode, isListNode, isMarkdownDocument, isMarkdownNode, isParagraphNode, isQuote, isTableNode, isTableStart, isTextNode, isThematicBreak, isThematicBreakNode, isWhitespace, leadingIndent, listItemPartsShape, parseBlocks, parseDocument, parseInline, renderHTML, renderMarkdown, rewriteDocument, sanitizeUrl, scanCode, scanEmphasis, scanInline, scanLink, splitLines, splitTableRow, startsBlock, stripQuote, tableAlignShape, tableAlignments, textShape, thematicBreakShape, unescapeText, walkNodes };
+
+//# sourceMappingURL=index.js.map