@farming-labs/docs 0.2.119 → 0.2.121

package/dist/openapi-overlays.mjs

@@ -0,0 +1,221 @@
+import { paths, query } from "jsonpath-rfc9535";
+
+//#region src/openapi-overlays.ts
+var OpenApiOverlayError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "OpenApiOverlayError";
+	}
+};
+function isJsonObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isJsonPrimitive(value) {
+	return value === null || typeof value !== "object";
+}
+function assertAllowedFields(value, allowed, location) {
+	const allowedSet = new Set(allowed);
+	const unexpected = Object.keys(value).find((key) => !allowedSet.has(key) && !key.startsWith("x-"));
+	if (unexpected) throw new OpenApiOverlayError(`${location} contains an unsupported \`${unexpected}\` field.`);
+}
+function requireNonEmptyString(value, location) {
+	if (typeof value !== "string" || !value.trim()) throw new OpenApiOverlayError(`${location} must be a non-empty string.`);
+	return value.trim();
+}
+function assertValidOpenApiOverlayDocument(value, source = "OpenAPI Overlay document") {
+	if (!isJsonObject(value)) throw new OpenApiOverlayError(`${source} must contain an object.`);
+	const overlayVersion = requireNonEmptyString(value.overlay, `${source} \`overlay\``);
+	const match = /^1\.(0|1)\.\d+$/.exec(overlayVersion);
+	if (!match) throw new OpenApiOverlayError(`${source} uses unsupported Overlay version \`${overlayVersion}\`. Supported versions are 1.0.x and 1.1.x.`);
+	const featureVersion = match[1] === "0" ? "1.0" : "1.1";
+	assertAllowedFields(value, [
+		"overlay",
+		"info",
+		"extends",
+		"actions"
+	], source);
+	if (!isJsonObject(value.info)) throw new OpenApiOverlayError(`${source} \`info\` must be an object.`);
+	assertAllowedFields(value.info, featureVersion === "1.1" ? [
+		"title",
+		"version",
+		"description"
+	] : ["title", "version"], `${source} \`info\``);
+	requireNonEmptyString(value.info.title, `${source} \`info.title\``);
+	requireNonEmptyString(value.info.version, `${source} \`info.version\``);
+	if (value.extends !== void 0 && typeof value.extends !== "string") throw new OpenApiOverlayError(`${source} \`extends\` must be a URI-reference string.`);
+	if (!Array.isArray(value.actions) || value.actions.length === 0) throw new OpenApiOverlayError(`${source} \`actions\` must contain at least one action.`);
+	const serializedActions = /* @__PURE__ */ new Set();
+	value.actions.forEach((action, index) => {
+		const location = `${source} action ${index + 1}`;
+		if (!isJsonObject(action)) throw new OpenApiOverlayError(`${location} must be an object.`);
+		assertAllowedFields(action, featureVersion === "1.1" ? [
+			"target",
+			"description",
+			"update",
+			"copy",
+			"remove"
+		] : [
+			"target",
+			"description",
+			"update",
+			"remove"
+		], location);
+		if (!requireNonEmptyString(action.target, `${location} \`target\``).startsWith("$")) throw new OpenApiOverlayError(`${location} \`target\` must start with \`$\`.`);
+		if (action.description !== void 0 && typeof action.description !== "string") throw new OpenApiOverlayError(`${location} \`description\` must be a string.`);
+		if (action.remove !== void 0 && typeof action.remove !== "boolean") throw new OpenApiOverlayError(`${location} \`remove\` must be a boolean.`);
+		if (action.copy !== void 0) {
+			if (!requireNonEmptyString(action.copy, `${location} \`copy\``).startsWith("$")) throw new OpenApiOverlayError(`${location} \`copy\` must start with \`$\`.`);
+		}
+		const serialized = JSON.stringify(action);
+		if (serializedActions.has(serialized)) throw new OpenApiOverlayError(`${location} duplicates an earlier action.`);
+		serializedActions.add(serialized);
+	});
+}
+function validateOverlay(value, source) {
+	assertValidOpenApiOverlayDocument(value, source);
+	return {
+		version: String(value.overlay).startsWith("1.0.") ? "1.0" : "1.1",
+		actions: value.actions
+	};
+}
+function decodeNormalizedPathKey(value) {
+	return value.replace(/\\(?:['\\bfnrt]|u[\da-fA-F]{4})/g, (match) => {
+		const escape = match.slice(1);
+		if (escape.startsWith("u")) return String.fromCharCode(Number.parseInt(escape.slice(1), 16));
+		return {
+			"'": "'",
+			"\\": "\\",
+			b: "\b",
+			f: "\f",
+			n: "\n",
+			r: "\r",
+			t: "	"
+		}[escape];
+	});
+}
+function parseNormalizedJsonPath(path) {
+	if (path === "$") return [];
+	const segments = [];
+	const segmentPattern = /\[(?:(\d+)|'((?:\\.|[^'])*)')\]/gy;
+	segmentPattern.lastIndex = 1;
+	while (segmentPattern.lastIndex < path.length) {
+		const match = segmentPattern.exec(path);
+		if (!match) throw new OpenApiOverlayError(`JSONPath returned an unsupported normalized path: ${path}`);
+		segments.push(match[1] === void 0 ? decodeNormalizedPathKey(match[2] ?? "") : Number(match[1]));
+	}
+	return segments;
+}
+function getAtPath(root, path) {
+	let value = root;
+	for (const segment of path) {
+		if (Array.isArray(value) && typeof segment === "number") {
+			value = value[segment];
+			continue;
+		}
+		if (isJsonObject(value) && typeof segment === "string") {
+			value = value[segment];
+			continue;
+		}
+		throw new OpenApiOverlayError("An Overlay action selected a node that no longer exists.");
+	}
+	return value;
+}
+function setAtPath(root, path, value) {
+	if (path.length === 0) return value;
+	const parent = getAtPath(root, path.slice(0, -1));
+	const key = path[path.length - 1];
+	if (Array.isArray(parent) && typeof key === "number") parent[key] = value;
+	else if (isJsonObject(parent) && typeof key === "string") parent[key] = value;
+	else throw new OpenApiOverlayError("An Overlay action selected an invalid parent node.");
+	return root;
+}
+function removeAtPath(root, path) {
+	if (path.length === 0) throw new OpenApiOverlayError("An Overlay action cannot remove the document root.");
+	const parent = getAtPath(root, path.slice(0, -1));
+	const key = path[path.length - 1];
+	if (Array.isArray(parent) && typeof key === "number") parent.splice(key, 1);
+	else if (isJsonObject(parent) && typeof key === "string") delete parent[key];
+	else throw new OpenApiOverlayError("An Overlay remove action selected an invalid parent node.");
+}
+function mergeObjectValues(target, update, location) {
+	const result = structuredClone(target);
+	for (const [key, updateValue] of Object.entries(update)) {
+		if (!(key in result)) {
+			result[key] = structuredClone(updateValue);
+			continue;
+		}
+		const targetValue = result[key];
+		if (isJsonObject(targetValue) && isJsonObject(updateValue)) result[key] = mergeObjectValues(targetValue, updateValue, `${location}.${key}`);
+		else if (Array.isArray(targetValue) && Array.isArray(updateValue)) result[key] = [...targetValue, ...structuredClone(updateValue)];
+		else if (isJsonPrimitive(targetValue) && isJsonPrimitive(updateValue)) result[key] = updateValue;
+		else throw new OpenApiOverlayError(`${location} cannot merge incompatible values for \`${key}\`.`);
+	}
+	return result;
+}
+function applyUpdate(target, update, version, location) {
+	if (isJsonObject(target)) {
+		if (!isJsonObject(update)) throw new OpenApiOverlayError(`${location} must use an object update for an object target.`);
+		return mergeObjectValues(target, update, location);
+	}
+	if (Array.isArray(target)) return Array.isArray(update) ? [...target, ...structuredClone(update)] : [...target, structuredClone(update)];
+	if (version === "1.0") throw new OpenApiOverlayError(`${location} selects a primitive, which Overlay 1.0 cannot update.`);
+	if (!isJsonPrimitive(update)) throw new OpenApiOverlayError(`${location} must use a primitive update for a primitive target.`);
+	return update;
+}
+function queryPaths(document, expression, location) {
+	try {
+		return paths(document, expression);
+	} catch (error) {
+		throw new OpenApiOverlayError(`${location} contains invalid RFC 9535 JSONPath: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+function queryCopyValue(document, expression, location) {
+	let values;
+	try {
+		values = query(document, expression);
+	} catch (error) {
+		throw new OpenApiOverlayError(`${location} contains invalid RFC 9535 JSONPath: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (values.length !== 1) throw new OpenApiOverlayError(`${location} must select exactly one node, but selected ${values.length}.`);
+	return structuredClone(values[0]);
+}
+function compareRemovalPaths(a, b) {
+	if (a.length !== b.length) return b.length - a.length;
+	const aLast = a[a.length - 1];
+	const bLast = b[b.length - 1];
+	return typeof aLast === "number" && typeof bLast === "number" ? bLast - aLast : 0;
+}
+function getJsonValueKind(value) {
+	if (Array.isArray(value)) return "array";
+	return isJsonObject(value) ? "object" : "primitive";
+}
+function applyOpenApiOverlayDocuments(document, overlays) {
+	let result = structuredClone(document);
+	for (const overlaySource of overlays) {
+		const overlay = validateOverlay(overlaySource.document, overlaySource.source);
+		for (const [actionIndex, action] of overlay.actions.entries()) {
+			const location = `${overlaySource.source} action ${actionIndex + 1}`;
+			const normalizedPaths = queryPaths(result, action.target, `${location} \`target\``);
+			if (normalizedPaths.length === 0) throw new OpenApiOverlayError(`${location} target \`${action.target}\` did not match any nodes.`);
+			const selectedPaths = normalizedPaths.map(parseNormalizedJsonPath);
+			if (action.remove === true) {
+				for (const path of selectedPaths.sort(compareRemovalPaths)) removeAtPath(result, path);
+				continue;
+			}
+			const hasUpdate = Object.prototype.hasOwnProperty.call(action, "update");
+			const hasCopy = typeof action.copy === "string";
+			if (!hasUpdate && !hasCopy) continue;
+			if (new Set(selectedPaths.map((path) => getJsonValueKind(getAtPath(result, path)))).size > 1) throw new OpenApiOverlayError(`${location} must select only objects, only arrays, or only primitives for an update or copy action.`);
+			const updateValue = hasUpdate ? action.update : queryCopyValue(result, action.copy, `${location} \`copy\``);
+			for (const path of selectedPaths) {
+				const updated = applyUpdate(getAtPath(result, path), updateValue, overlay.version, location);
+				result = setAtPath(result, path, updated);
+			}
+		}
+	}
+	if (!isJsonObject(result)) throw new OpenApiOverlayError("OpenAPI Overlay actions must leave an object document root.");
+	return result;
+}
+
+//#endregion
+export { applyOpenApiOverlayDocuments };

package/dist/openapi-references.mjs

@@ -0,0 +1,233 @@
+import { createHash } from "node:crypto";
+
+//#region src/openapi-references.ts
+const OPENAPI_BUNDLED_REFERENCES_EXTENSION = "x-farming-labs-references";
+const OPENAPI_REFERENCE_MAX_DOCUMENTS = 32;
+function resolveOpenApiReferencesSync(document, options) {
+	const sourceUri = normalizeDocumentUri(options.sourceUri);
+	const entry = createDocumentState({
+		uri: sourceUri,
+		document
+	}, true);
+	const documents = /* @__PURE__ */ new Map();
+	registerDocument(documents, entry, sourceUri);
+	const bundle = {};
+	const maxDocuments = normalizeMaxDocuments(options.maxDocuments);
+	const getDocument = (requestedUri, fromUri) => {
+		const normalizedRequest = normalizeDocumentUri(requestedUri);
+		const cached = documents.get(normalizedRequest);
+		if (cached) return cached;
+		if (!options.loadDocument) throw new Error(`OpenAPI reference requires an external document: ${normalizedRequest}`);
+		if (countDocuments(documents) >= maxDocuments) throw new Error(`OpenAPI references exceed the ${maxDocuments}-document limit.`);
+		const state = createDocumentState(options.loadDocument(new URL(normalizedRequest), new URL(fromUri)), false);
+		registerDocument(documents, state, normalizedRequest);
+		return state;
+	};
+	const processDocument = (state) => {
+		if (state.processed || state.processing) return state.output;
+		state.processing = true;
+		state.output = structuredClone(state.document);
+		if (!state.entry) {
+			state.bundleKey = createBundleKey(state.retrievalUri);
+			bundle[state.bundleKey] = state.output;
+		}
+		rewriteReferencesSync(state.output, state, getDocument, processDocument);
+		state.processing = false;
+		state.processed = true;
+		return state.output;
+	};
+	const output = processDocument(entry);
+	if (!isRecord(output)) throw new Error("The OpenAPI entry document must be an object.");
+	if (Object.keys(bundle).length > 0) {
+		if (Object.hasOwn(output, OPENAPI_BUNDLED_REFERENCES_EXTENSION)) throw new Error(`The OpenAPI document uses the reserved \`${OPENAPI_BUNDLED_REFERENCES_EXTENSION}\` extension.`);
+		output[OPENAPI_BUNDLED_REFERENCES_EXTENSION] = bundle;
+	}
+	return output;
+}
+async function resolveOpenApiReferences(document, options) {
+	const sourceUri = normalizeDocumentUri(options.sourceUri);
+	const entry = createDocumentState({
+		uri: sourceUri,
+		document
+	}, true);
+	const documents = /* @__PURE__ */ new Map();
+	registerDocument(documents, entry, sourceUri);
+	const bundle = {};
+	const maxDocuments = normalizeMaxDocuments(options.maxDocuments);
+	const getDocument = async (requestedUri, fromUri) => {
+		const normalizedRequest = normalizeDocumentUri(requestedUri);
+		const cached = documents.get(normalizedRequest);
+		if (cached) return cached;
+		if (!options.loadDocument) throw new Error(`OpenAPI reference requires an external document: ${normalizedRequest}`);
+		if (countDocuments(documents) >= maxDocuments) throw new Error(`OpenAPI references exceed the ${maxDocuments}-document limit.`);
+		const state = createDocumentState(await options.loadDocument(new URL(normalizedRequest), new URL(fromUri)), false);
+		registerDocument(documents, state, normalizedRequest);
+		return state;
+	};
+	const processDocument = async (state) => {
+		if (state.processed || state.processing) return state.output;
+		state.processing = true;
+		state.output = structuredClone(state.document);
+		if (!state.entry) {
+			state.bundleKey = createBundleKey(state.retrievalUri);
+			bundle[state.bundleKey] = state.output;
+		}
+		await rewriteReferences(state.output, state, getDocument, processDocument);
+		state.processing = false;
+		state.processed = true;
+		return state.output;
+	};
+	const output = await processDocument(entry);
+	if (!isRecord(output)) throw new Error("The OpenAPI entry document must be an object.");
+	if (Object.keys(bundle).length > 0) {
+		if (Object.hasOwn(output, OPENAPI_BUNDLED_REFERENCES_EXTENSION)) throw new Error(`The OpenAPI document uses the reserved \`${OPENAPI_BUNDLED_REFERENCES_EXTENSION}\` extension.`);
+		output[OPENAPI_BUNDLED_REFERENCES_EXTENSION] = bundle;
+	}
+	return output;
+}
+function rewriteReferencesSync(value, currentDocument, getDocument, processDocument, ancestors = /* @__PURE__ */ new WeakSet()) {
+	if (!value || typeof value !== "object") return;
+	if (ancestors.has(value)) throw new Error("OpenAPI source documents cannot contain cyclic YAML aliases.");
+	ancestors.add(value);
+	if (Array.isArray(value)) {
+		for (const item of value) rewriteReferencesSync(item, currentDocument, getDocument, processDocument, ancestors);
+		ancestors.delete(value);
+		return;
+	}
+	const record = value;
+	if (Object.hasOwn(record, "$ref")) record.$ref = rewriteReferenceSync(record.$ref, currentDocument, getDocument, processDocument);
+	for (const [key, child] of Object.entries(record)) {
+		if (key === "$ref") continue;
+		rewriteReferencesSync(child, currentDocument, getDocument, processDocument, ancestors);
+	}
+	ancestors.delete(value);
+}
+async function rewriteReferences(value, currentDocument, getDocument, processDocument, ancestors = /* @__PURE__ */ new WeakSet()) {
+	if (!value || typeof value !== "object") return;
+	if (ancestors.has(value)) throw new Error("OpenAPI source documents cannot contain cyclic YAML aliases.");
+	ancestors.add(value);
+	if (Array.isArray(value)) {
+		for (const item of value) await rewriteReferences(item, currentDocument, getDocument, processDocument, ancestors);
+		ancestors.delete(value);
+		return;
+	}
+	const record = value;
+	if (Object.hasOwn(record, "$ref")) record.$ref = await rewriteReference(record.$ref, currentDocument, getDocument, processDocument);
+	for (const [key, child] of Object.entries(record)) {
+		if (key === "$ref") continue;
+		await rewriteReferences(child, currentDocument, getDocument, processDocument, ancestors);
+	}
+	ancestors.delete(value);
+}
+function rewriteReferenceSync(reference, currentDocument, getDocument, processDocument) {
+	const target = resolveReference(reference, currentDocument.baseUri);
+	const targetDocument = getDocument(target.documentUri, currentDocument.baseUri);
+	assertReferenceTarget(targetDocument.document, target.pointer, reference);
+	processDocument(targetDocument);
+	return buildBundledReference(targetDocument, target.pointer);
+}
+async function rewriteReference(reference, currentDocument, getDocument, processDocument) {
+	const target = resolveReference(reference, currentDocument.baseUri);
+	const targetDocument = await getDocument(target.documentUri, currentDocument.baseUri);
+	assertReferenceTarget(targetDocument.document, target.pointer, reference);
+	await processDocument(targetDocument);
+	return buildBundledReference(targetDocument, target.pointer);
+}
+function resolveReference(reference, baseUri) {
+	if (typeof reference !== "string" || !reference.trim()) throw new Error("OpenAPI `$ref` values must be non-empty URI strings.");
+	let url;
+	try {
+		url = new URL(reference, baseUri);
+	} catch {
+		throw new Error(`OpenAPI reference is not a valid URI: ${reference}`);
+	}
+	const pointer = normalizePointerFragment(url.hash, reference);
+	url.hash = "";
+	return {
+		documentUri: url.href,
+		pointer
+	};
+}
+function normalizePointerFragment(hash, reference) {
+	if (!hash || hash === "#") return "";
+	let decoded;
+	try {
+		decoded = decodeURIComponent(hash.slice(1));
+	} catch {
+		throw new Error(`OpenAPI reference has an invalid encoded fragment: ${String(reference)}`);
+	}
+	if (!decoded.startsWith("/")) throw new Error(`OpenAPI reference anchors are not supported yet; use a JSON Pointer fragment: ${String(reference)}`);
+	return decoded;
+}
+function assertReferenceTarget(document, pointer, reference) {
+	if (!pointer) return;
+	let current = document;
+	for (const token of pointer.slice(1).split("/")) {
+		if (!current || typeof current !== "object") throw new Error(`OpenAPI reference target was not found: ${String(reference)}`);
+		const key = decodeJsonPointerToken(token, reference);
+		if (!Object.hasOwn(current, key)) throw new Error(`OpenAPI reference target was not found: ${String(reference)}`);
+		current = current[key];
+	}
+}
+function decodeJsonPointerToken(token, reference) {
+	if (/~(?:[^01]|$)/.test(token)) throw new Error(`OpenAPI reference has an invalid JSON Pointer fragment: ${String(reference)}`);
+	return token.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+function buildBundledReference(document, pointer) {
+	if (document.entry) return `#${pointer}`;
+	if (!document.bundleKey) throw new Error(`OpenAPI reference document was not bundled: ${document.retrievalUri}`);
+	return `#/${OPENAPI_BUNDLED_REFERENCES_EXTENSION}/${escapeJsonPointer(document.bundleKey)}${pointer}`;
+}
+function createDocumentState(loaded, entry) {
+	const retrievalUri = normalizeDocumentUri(loaded.uri);
+	const self = isRecord(loaded.document) ? loaded.document.$self : void 0;
+	let baseUri = retrievalUri;
+	if (typeof self === "string" && self.trim()) try {
+		baseUri = normalizeDocumentUri(new URL(self, retrievalUri).href);
+	} catch {
+		throw new Error(`OpenAPI document has an invalid \`$self\` URI: ${self}`);
+	}
+	return {
+		retrievalUri,
+		baseUri,
+		document: loaded.document,
+		entry,
+		processing: false,
+		processed: false
+	};
+}
+function registerDocument(documents, document, requestedUri) {
+	for (const uri of [
+		requestedUri,
+		document.retrievalUri,
+		document.baseUri
+	]) {
+		const normalized = normalizeDocumentUri(uri);
+		const existing = documents.get(normalized);
+		if (existing && existing !== document) throw new Error(`Multiple OpenAPI documents claim the same base URI: ${normalized}`);
+		documents.set(normalized, document);
+	}
+}
+function countDocuments(documents) {
+	return new Set(documents.values()).size;
+}
+function normalizeDocumentUri(value) {
+	const url = new URL(value);
+	url.hash = "";
+	return url.href;
+}
+function normalizeMaxDocuments(value) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : OPENAPI_REFERENCE_MAX_DOCUMENTS;
+}
+function createBundleKey(uri) {
+	return `ref-${createHash("sha256").update(uri).digest("hex").slice(0, 16)}`;
+}
+function escapeJsonPointer(value) {
+	return value.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+//#endregion
+export { resolveOpenApiReferences, resolveOpenApiReferencesSync };

package/dist/pagination.d.mts

@@ -0,0 +1,7 @@
+//#region src/pagination.d.ts
+declare class DocsPaginationCursorError extends Error {
+  readonly code = "invalid_cursor";
+  constructor();
+}
+//#endregion
+export { DocsPaginationCursorError };

package/dist/pagination.mjs

@@ -0,0 +1,100 @@
+import { digestDocsRetrievalContent } from "./retrieval-digest.mjs";
+
+//#region src/pagination.ts
+const DOCS_PAGINATION_CURSOR_VERSION = 1;
+const MAX_DOCS_PAGINATION_CURSOR_CHARS = 4096;
+const MAX_DOCS_PAGINATION_STATE_CHARS = 1024;
+const MAX_DOCS_PAGINATION_OFFSET = 1e7;
+const DOCS_PAGINATION_DIGEST_PATTERN = /^sha256:[a-f\d]{64}$/u;
+var DocsPaginationCursorError = class extends Error {
+	code = "invalid_cursor";
+	constructor() {
+		super("Invalid or stale pagination cursor.");
+		this.name = "DocsPaginationCursorError";
+	}
+};
+function paginationDigest(label, value) {
+	return digestDocsRetrievalContent(`${label}\0${value}`);
+}
+function cursorChecksum(payload) {
+	return paginationDigest("docs-pagination-checksum.v1", JSON.stringify(payload));
+}
+function encodeBase64Url(value) {
+	const bytes = new TextEncoder().encode(value);
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/gu, "-").replace(/\//gu, "_").replace(/=+$/u, "");
+}
+function decodeBase64Url(value) {
+	const padded = `${value.replace(/-/gu, "+").replace(/_/gu, "/")}${"=".repeat((4 - value.length % 4) % 4)}`;
+	const binary = atob(padded);
+	const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+	return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+function isDigest(value) {
+	return typeof value === "string" && DOCS_PAGINATION_DIGEST_PATTERN.test(value);
+}
+function assertCursorOptions(options) {
+	if (!/^[a-z][a-z\d._/-]{0,127}$/u.test(options.kind) || typeof options.scope !== "string" || typeof options.snapshot !== "string") throw new TypeError("Pagination cursor options must contain a valid kind, scope, and snapshot.");
+}
+function createDocsPaginationCursor(offset, options) {
+	assertCursorOptions(options);
+	if (!Number.isSafeInteger(offset) || offset <= 0 || offset > MAX_DOCS_PAGINATION_OFFSET) throw new TypeError("Pagination cursor offsets must be positive safe integers.");
+	if (options.state !== void 0 && (options.state.length === 0 || options.state.length > MAX_DOCS_PAGINATION_STATE_CHARS)) throw new TypeError("Pagination provider state must be a bounded, non-empty string.");
+	const unsigned = [
+		DOCS_PAGINATION_CURSOR_VERSION,
+		options.kind,
+		offset,
+		paginationDigest("docs-pagination-scope.v1", options.scope),
+		paginationDigest("docs-pagination-snapshot.v1", options.snapshot),
+		options.state ?? null
+	];
+	return encodeBase64Url(JSON.stringify([...unsigned, cursorChecksum(unsigned)]));
+}
+function resolveDocsPaginationCursor(cursor, options) {
+	assertCursorOptions(options);
+	if (cursor === void 0) return { offset: 0 };
+	if (cursor.length === 0 || cursor.length > MAX_DOCS_PAGINATION_CURSOR_CHARS || !/^[A-Za-z\d_-]+$/u.test(cursor)) throw new DocsPaginationCursorError();
+	let parsed;
+	try {
+		parsed = JSON.parse(decodeBase64Url(cursor));
+	} catch {
+		throw new DocsPaginationCursorError();
+	}
+	if (!Array.isArray(parsed) || parsed.length !== 7 || encodeBase64Url(JSON.stringify(parsed)) !== cursor) throw new DocsPaginationCursorError();
+	const [version, kind, offset, scopeDigest, snapshotDigest, state, checksum] = parsed;
+	const unsigned = [
+		version,
+		kind,
+		offset,
+		scopeDigest,
+		snapshotDigest,
+		state
+	];
+	if (version !== DOCS_PAGINATION_CURSOR_VERSION || kind !== options.kind || !Number.isSafeInteger(offset) || offset <= 0 || offset > MAX_DOCS_PAGINATION_OFFSET || !isDigest(scopeDigest) || !isDigest(snapshotDigest) || !(state === null || typeof state === "string" && state.length > 0 && state.length <= MAX_DOCS_PAGINATION_STATE_CHARS) || !isDigest(checksum) || scopeDigest !== paginationDigest("docs-pagination-scope.v1", options.scope) || snapshotDigest !== paginationDigest("docs-pagination-snapshot.v1", options.snapshot) || checksum !== cursorChecksum(unsigned)) throw new DocsPaginationCursorError();
+	return {
+		offset,
+		...typeof state === "string" ? { state } : {}
+	};
+}
+function resolveDocsPaginationOffset(cursor, options) {
+	return resolveDocsPaginationCursor(cursor, options).offset;
+}
+function paginateDocsItems(items, options) {
+	if (!Number.isSafeInteger(options.pageSize) || options.pageSize <= 0) throw new TypeError("Pagination page sizes must be positive safe integers.");
+	const offset = resolveDocsPaginationOffset(options.cursor, options);
+	if (offset >= items.length && options.cursor !== void 0) throw new DocsPaginationCursorError();
+	const pageItems = items.slice(offset, offset + options.pageSize);
+	const nextOffset = offset + pageItems.length;
+	const hasMore = nextOffset < items.length;
+	return {
+		items: pageItems,
+		resultCount: pageItems.length,
+		total: items.length,
+		hasMore,
+		...hasMore ? { nextCursor: createDocsPaginationCursor(nextOffset, options) } : {}
+	};
+}
+
+//#endregion
+export { DocsPaginationCursorError, createDocsPaginationCursor, paginateDocsItems, resolveDocsPaginationCursor, resolveDocsPaginationOffset };

package/dist/prompt-references.d.mts

@@ -0,0 +1,12 @@
+//#region src/prompt-references.d.ts
+/**
+ * Keep `<Prompt>` children literal before Markdown reference definitions are
+ * resolved by the MDX compiler.
+ *
+ * Definitions inside Prompt are copyable source, not page-level definitions.
+ * References inside Prompt always remain source text, while references outside
+ * Prompt only remain live when they have a definition outside Prompt.
+ */
+declare function isolateDocsMarkdownPromptReferences(root: unknown, value?: unknown): void;
+//#endregion
+export { isolateDocsMarkdownPromptReferences };