@orkestrel/markdown 0.0.1 → 0.0.3

package/dist/src/core/index.js

@@ -1,3 +1,4 @@
+import { arrayOf, booleanShape, createContract, integerShape, isBoolean, isEmptyString, isNonEmptyArray, isNonEmptyString, isNumber, isString, lazyOf, literalOf, literalShape, objectShape, optionalShape, parseInteger, recordOf, stringShape, unionOf } from "@orkestrel/contract";
 //#region src/core/constants.ts
 /**
 * The URL schemes `renderHTML` permits on a link `href` - anything else (notably
@@ -21,1050 +22,6 @@ var SAFE_URL_SCHEMES = /* @__PURE__ */ new Set([
 * 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
 /**
@@ -1073,6 +30,12 @@ function optionalShape(inner) {
 *
 * @param character - The character to test
 * @returns `true` when it is inline whitespace
+*
+* @example
+* ```ts
+* isWhitespace(' ') // true
+* isWhitespace('a') // false
+* ```
 */
 function isWhitespace(character) {
 	return character === " " || character === "	" || character === "\n";
@@ -1083,6 +46,12 @@ function isWhitespace(character) {
 *
 * @param character - The single character after a backslash
 * @returns `true` when a backslash before it is an escape
+*
+* @example
+* ```ts
+* isEscapable('*') // true
+* isEscapable('a') // false
+* ```
 */
 function isEscapable(character) {
 	return /[\\`*_{}[\]()#+\-.!>~|]/.test(character);
@@ -1094,6 +63,11 @@ function isEscapable(character) {
 *
 * @param line - The candidate line
 * @returns `true` when the line is blank
+*
+* @example
+* ```ts
+* isBlankLine('   ') // true
+* ```
 */
 function isBlankLine(line) {
 	return isEmptyString(line.trim());
@@ -1104,6 +78,11 @@ function isBlankLine(line) {
 *
 * @param line - The candidate line
 * @returns `true` when the line begins a blockquote
+*
+* @example
+* ```ts
+* isQuote('> quoted') // true
+* ```
 */
 function isQuote(line) {
 	return /^\s{0,3}>/.test(line);
@@ -1115,6 +94,11 @@ function isQuote(line) {
 * @param line - The candidate closing line
 * @param marker - The opening fence's marker run (from {@link extractFence})
 * @returns `true` when `line` closes the fence
+*
+* @example
+* ```ts
+* isFenceClose('```', '```') // true
+* ```
 */
 function isFenceClose(line, marker) {
 	const character = marker[0] === "~" ? "~" : "`";
@@ -1135,6 +119,12 @@ function isFenceClose(line, marker) {
 *
 * @param character - The single character to test, or `undefined` past the end of a line
 * @returns `true` when it is whitespace
+*
+* @example
+* ```ts
+* isFenceWhitespace(' ')         // true
+* isFenceWhitespace(undefined)   // false
+* ```
 */
 function isFenceWhitespace(character) {
 	return character === " " || character === "	" || character === "\n" || character === "\r" || character === "\f" || character === "\v";
@@ -1146,6 +136,11 @@ function isFenceWhitespace(character) {
 *
 * @param line - The candidate line
 * @returns `true` when the line is a thematic break
+*
+* @example
+* ```ts
+* isThematicBreak('---') // true
+* ```
 */
 function isThematicBreak(line) {
 	const stripped = line.trim().replace(/\s+/g, "");
@@ -1162,6 +157,11 @@ function isThematicBreak(line) {
 * @param header - The candidate header line
 * @param delimiter - The line after it (the candidate delimiter)
 * @returns `true` when the two lines open a table
+*
+* @example
+* ```ts
+* isTableStart('| a |', '| - |') // true
+* ```
 */
 function isTableStart(header, delimiter) {
 	if (delimiter === void 0 || !header.includes("|")) return false;
@@ -1173,11 +173,25 @@ function isTableStart(header, delimiter) {
 function isHeadingNode(node) {
 	return node.element === "heading";
 }
-/** Determine whether a node is a paragraph block. */
+/**
+* Determine whether a node is a paragraph block.
+*
+* @example
+* ```ts
+* isParagraphNode({ element: 'paragraph', children: [] }) // true
+* ```
+*/
 function isParagraphNode(node) {
 	return node.element === "paragraph";
 }
-/** Determine whether a node is a list block. */
+/**
+* Determine whether a node is a list block.
+*
+* @example
+* ```ts
+* isListNode({ element: 'list', ordered: false, start: 1, items: [] }) // true
+* ```
+*/
 function isListNode(node) {
 	return node.element === "list";
 }
@@ -1185,23 +199,58 @@ function isListNode(node) {
 function isTableNode(node) {
 	return node.element === "table";
 }
-/** Determine whether a node is a fenced code block. */
+/**
+* Determine whether a node is a fenced code block.
+*
+* @example
+* ```ts
+* isCodeBlockNode({ element: 'codeBlock', code: 'x' }) // true
+* ```
+*/
 function isCodeBlockNode(node) {
 	return node.element === "codeBlock";
 }
-/** Determine whether a node is a blockquote block. */
+/**
+* Determine whether a node is a blockquote block.
+*
+* @example
+* ```ts
+* isBlockquoteNode({ element: 'blockquote', children: [] }) // true
+* ```
+*/
 function isBlockquoteNode(node) {
 	return node.element === "blockquote";
 }
-/** Determine whether a node is a thematic break (horizontal rule) block. */
+/**
+* Determine whether a node is a thematic break (horizontal rule) block.
+*
+* @example
+* ```ts
+* isThematicBreakNode({ element: 'thematicBreak' }) // true
+* ```
+*/
 function isThematicBreakNode(node) {
 	return node.element === "thematicBreak";
 }
-/** Determine whether a node is a plain text run. */
+/**
+* Determine whether a node is a plain text run.
+*
+* @example
+* ```ts
+* isTextNode({ element: 'text', value: 'hi' }) // true
+* ```
+*/
 function isTextNode(node) {
 	return node.element === "text";
 }
-/** Determine whether a node is an emphasis run (`*em*` / `**strong**`). */
+/**
+* Determine whether a node is an emphasis run (`*em*` / `**strong**`).
+*
+* @example
+* ```ts
+* isEmphasisNode({ element: 'emphasis', strong: false, children: [] }) // true
+* ```
+*/
 function isEmphasisNode(node) {
 	return node.element === "emphasis";
 }
@@ -1211,6 +260,11 @@ function isEmphasisNode(node) {
 * @remarks
 * Narrows to {@link CodeSpanNode} - the node whose `element` discriminant is
 * `'codeSpan'`.
+*
+* @example
+* ```ts
+* isCodeSpanNode({ element: 'codeSpan', value: 'x' }) // true
+* ```
 */
 function isCodeSpanNode(node) {
 	return node.element === "codeSpan";
@@ -1367,6 +421,11 @@ var isMarkdownDocument = recordOf({
 *
 * @param markdown - The raw markdown source
 * @returns The document's lines, line-terminators stripped
+*
+* @example
+* ```ts
+* splitLines('a\r\nb\nc') // ['a', 'b', 'c']
+* ```
 */
 function splitLines(markdown) {
 	const lines = markdown.replace(/\r\n?/g, "\n").split("\n");
@@ -1379,6 +438,11 @@ function splitLines(markdown) {
 *
 * @param line - The line to measure
 * @returns The number of leading space / tab characters
+*
+* @example
+* ```ts
+* leadingIndent('  text') // 2
+* ```
 */
 function leadingIndent(line) {
 	let count = 0;
@@ -1394,6 +458,11 @@ function leadingIndent(line) {
 *
 * @param line - The candidate line
 * @returns The heading level (1–6) and its raw inline text, or `undefined`
+*
+* @example
+* ```ts
+* extractHeading('## Title') // { level: 2, text: 'Title' }
+* ```
 */
 function extractHeading(line) {
 	const match = /^(#{1,6})(?:\s+(.*))?$/.exec(line.trimStart());
@@ -1411,6 +480,11 @@ function extractHeading(line) {
 *
 * @param line - The candidate line
 * @returns The fence marker run and its language tag, or `undefined`
+*
+* @example
+* ```ts
+* extractFence('```ts') // { marker: '```', lang: 'ts' }
+* ```
 */
 function extractFence(line) {
 	const match = /^\s*(`{3,}|~{3,})\s*(.*)$/.exec(line);
@@ -1431,6 +505,11 @@ function extractFence(line) {
 *
 * @param line - The candidate line
 * @returns The list-item parts, or `undefined` when not a list item
+*
+* @example
+* ```ts
+* extractListItem('- item') // { ordered: false, start: 1, content: 'item', indent: 0, marker: 2 }
+* ```
 */
 function extractListItem(line) {
 	const unordered = /^(\s*)([-*+])\s+(.*)$/.exec(line);
@@ -1464,6 +543,11 @@ function extractListItem(line) {
 *
 * @param line - A blockquote line (per {@link isQuote})
 * @returns The line with its leading `>` (and one space) removed
+*
+* @example
+* ```ts
+* stripQuote('> text') // 'text'
+* ```
 */
 function stripQuote(line) {
 	return line.replace(/^\s{0,3}>\s?/, "");
@@ -1475,6 +559,11 @@ function stripQuote(line) {
 *
 * @param row - The raw table row line
 * @returns The row's cells, in column order
+*
+* @example
+* ```ts
+* splitTableRow('|a|b|') // ['a', 'b']
+* ```
 */
 function splitTableRow(row) {
 	const cells = [];
@@ -1501,6 +590,11 @@ function splitTableRow(row) {
 *
 * @param delimiter - The table's delimiter row
 * @returns One alignment per column, in column order
+*
+* @example
+* ```ts
+* tableAlignments('| :--- | ---: |') // ['left', 'right']
+* ```
 */
 function tableAlignments(delimiter) {
 	return splitTableRow(delimiter).map((cell) => {
@@ -1523,6 +617,11 @@ function tableAlignments(delimiter) {
 * @param lines - The document's lines
 * @param index - The line index to test
 * @returns `true` when the line begins a different block
+*
+* @example
+* ```ts
+* startsBlock(['text', '## Heading'], 1) // true
+* ```
 */
 function startsBlock(lines, index) {
 	const line = lines[index] ?? "";
@@ -1534,6 +633,11 @@ function startsBlock(lines, index) {
 *
 * @param text - The raw text possibly carrying `\x` escapes
 * @returns The text with escapable `\x` reduced to `x`
+*
+* @example
+* ```ts
+* unescapeText('\\*hi\\*') // '*hi*'
+* ```
 */
 function unescapeText(text) {
 	let out = "";
@@ -1552,6 +656,12 @@ function unescapeText(text) {
 *
 * @param nodes - The inline nodes (possibly with adjacent text runs)
 * @returns The nodes with consecutive text nodes concatenated
+*
+* @example
+* ```ts
+* coalesceText([{ element: 'text', value: 'a' }, { element: 'text', value: 'b' }])
+* // [{ element: 'text', value: 'ab' }]
+* ```
 */
 function coalesceText(nodes) {
 	const out = [];
@@ -1575,6 +685,11 @@ function coalesceText(nodes) {
 * @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`
+*
+* @example
+* ```ts
+* scanCode('`code`', 0, 6) // { value: 'code', end: 6 }
+* ```
 */
 function scanCode(source, start, to) {
 	let run = 0;
@@ -1608,6 +723,12 @@ function scanCode(source, start, to) {
 *   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`
+*
+* @example
+* ```ts
+* scanLink('[text](url)', 0, 11)
+* // { node: { element: 'link', href: 'url', children: [...] }, end: 11 }
+* ```
 */
 function scanLink(source, start, to, depth = 0) {
 	let bracketDepth = 0;
@@ -1669,6 +790,12 @@ function scanLink(source, start, to, depth = 0) {
 *   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`
+*
+* @example
+* ```ts
+* scanEmphasis('*em*', 0, 4)
+* // { node: { element: 'emphasis', strong: false, children: [...] }, end: 4 }
+* ```
 */
 function scanEmphasis(source, start, to, depth = 0) {
 	const marker = source[start] ?? "";
@@ -1721,6 +848,11 @@ function scanEmphasis(source, start, to, depth = 0) {
 *   it emits as a single literal text node - so pathological nesting (`[[[[…`,
 *   `****…`) cannot exhaust the call stack.
 * @returns The parsed inline nodes (NOT yet coalesced)
+*
+* @example
+* ```ts
+* scanInline('hi *there*', 0, 10) // [{ element: 'text', value: 'hi ' }, { element: 'emphasis', ... }]
+* ```
 */
 function scanInline(source, from, to, depth = 0) {
 	if (depth >= 64) return from < to ? [{
@@ -1789,6 +921,11 @@ function scanInline(source, from, to, depth = 0) {
 *
 * @param text - The raw text
 * @returns The HTML-escaped text
+*
+* @example
+* ```ts
+* escapeHtml('<a>&"\'') // '&lt;a&gt;&amp;&quot;&#39;'
+* ```
 */
 function escapeHtml(text) {
 	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
@@ -1806,6 +943,12 @@ function escapeHtml(text) {
 *
 * @param href - The raw link destination
 * @returns A safe, escaped `href` (empty when the scheme is unsafe or protocol-relative)
+*
+* @example
+* ```ts
+* sanitizeUrl('javascript:alert(1)') // ''
+* sanitizeUrl('/path')               // '/path'
+* ```
 */
 function sanitizeUrl(href) {
 	let cleaned = "";
@@ -2304,6 +1447,11 @@ function flattenText(node) {
 * @param lines - The markdown lines to parse.
 * @param depth - The current recursion depth (blockquotes/lists increment it).
 * @returns The parsed block nodes.
+*
+* @example
+* ```ts
+* parseBlocks(['# Hi'], 0) // [{ element: 'heading', level: 1, children: [...] }]
+* ```
 */
 function parseBlocks(lines, depth) {
 	if (depth >= 64) return lines.length > 0 ? [{
@@ -2395,6 +1543,11 @@ function parseBlocks(lines, depth) {
 * @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.
+*
+* @example
+* ```ts
+* collectTable(['| a |', '| - |'], 0) // { node: { element: 'table', ... }, next: 2 }
+* ```
 */
 function collectTable(lines, start) {
 	const headerCells = splitTableRow(lines[start] ?? "");
@@ -2430,6 +1583,11 @@ function collectTable(lines, start) {
 * @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.
+*
+* @example
+* ```ts
+* collectList(['- item'], 0, 0) // { node: { element: 'list', ... }, next: 1 }
+* ```
 */
 function collectList(lines, start, depth) {
 	const first = extractListItem(lines[start] ?? "");