@nhtio/adk 0.1.0-master-f0aa531d

package/spooled_markdown_artifact-BpUJol0W.mjs

@@ -0,0 +1,771 @@
+import { c as isObject, s as isInstanceOf } from "./tool_registry-DqLOyGyG.mjs";
+import { i as ArtifactTool, n as defaultSerialise, t as SpooledArtifact } from "./spooled_artifact-C5ZtGxuJ.mjs";
+import { validator } from "@nhtio/validation";
+import JSON5 from "json5";
+import { JSONPath } from "jsonpath-plus";
+import { remark } from "remark";
+import { visit } from "unist-util-visit";
+import { load } from "js-yaml";
+import remarkGfm from "remark-gfm";
+import { toString } from "mdast-util-to-string";
+import remarkFrontmatter from "remark-frontmatter";
+//#region src/lib/classes/spooled_json_artifact.ts
+/**
+* Detects the {@link JsonArtifactFormat} of a raw string.
+*
+* @remarks
+* Detection strategy (in order):
+* 1. If the content parses as strict JSON → `json`.
+* 2. If every non-empty line parses as strict JSON → `jsonl`.
+* 3. If the content parses as JSON5 → `json5`.
+* 4. Otherwise throws.
+*
+* Strict JSON is tried before JSON5 so that well-formed JSON files are not unnecessarily
+* classified as JSON5.
+*
+* @param content - The full artifact text to inspect.
+* @returns The inferred format.
+* @throws `Error` when the content cannot be classified as any supported JSON format.
+*/
+function inferFormat(content) {
+	const trimmed = content.trim();
+	try {
+		JSON.parse(trimmed);
+		return "json";
+	} catch {}
+	const nonEmptyLines = trimmed.split("\n").filter((l) => l.trim().length > 0);
+	if (nonEmptyLines.length > 0 && nonEmptyLines.every((l) => {
+		try {
+			JSON.parse(l);
+			return true;
+		} catch {
+			return false;
+		}
+	})) return "jsonl";
+	try {
+		JSON5.parse(trimmed);
+		return "json5";
+	} catch {}
+	throw new Error("Unable to infer JSON format: content is not valid JSON, JSONL, NDJSON, or JSON5");
+}
+/**
+* A {@link @nhtio/adk!SpooledArtifact} specialisation that adds JSON-aware read operations.
+*
+* @typeParam T - The expected shape of each parsed record. Defaults to `unknown`.
+*
+* @remarks
+* Construct with an optional `format` hint. When omitted the format is auto-detected on first
+* access by reading the full artifact and running {@link inferFormat}. Once detected (or
+* provided), the format is cached for the lifetime of the instance.
+*
+* All JSON methods are async, consistent with {@link @nhtio/adk!SpooledArtifact}.
+*
+* Path-based methods (`json_get`, `json_filter`, `json_pluck`) use
+* [JSONPath-Plus](https://github.com/JSONPath-Plus/JSONPath) expressions. Full JSONPath syntax
+* is supported, including recursive descent (`..`), filter expressions (`[?(@.age > 18)]`),
+* and union selectors.
+*/
+var SpooledJsonArtifact = class SpooledJsonArtifact extends SpooledArtifact {
+	#format;
+	#parsed;
+	/**
+	* @param reader - The backing store to read from.
+	* @param format - Optional format hint. When omitted, the format is inferred on first access.
+	*/
+	constructor(reader, format) {
+		super(reader);
+		this.#format = format;
+	}
+	/**
+	* Returns `true` if `value` is a {@link SpooledJsonArtifact} instance.
+	*
+	* @remarks
+	* Uses the cross-realm-safe {@link @nhtio/adk!isInstanceOf} guard: `instanceof` first, then
+	* `Symbol.hasInstance`, then a `constructor.name` fallback. Matches the pattern used by every
+	* other class guard in the ADK; safe against the dual-module-copy case where two distinct
+	* `SpooledJsonArtifact` classes coexist in the same realm.
+	*
+	* @param value - The value to test.
+	* @returns `true` when `value` is a {@link SpooledJsonArtifact} instance.
+	*/
+	static isSpooledJsonArtifact(value) {
+		return isInstanceOf(value, "SpooledJsonArtifact", SpooledJsonArtifact);
+	}
+	/**
+	* The JSON-specific artifact-query descriptors this class adds on top of the base set.
+	*
+	* @remarks
+	* Lists `artifact_json_type`, `artifact_json_keys`, `artifact_json_length`,
+	* `artifact_json_get`, `artifact_json_filter`, `artifact_json_slice`, `artifact_json_pluck`.
+	* The base seven descriptors (`artifact_head`, etc.) are NOT included here — they are
+	* forged separately by {@link SpooledJsonArtifact.forgeTools}, which calls
+	* `SpooledArtifact.forgeTools(ctx)` to produce the base-narrowed tools and then registers
+	* its own JSON tools on the result. Downstream consumers building custom subclasses
+	* should follow the same pattern: own only your own descriptors; override `forgeTools` to
+	* compose with the base output.
+	*/
+	static toolMethods = Object.freeze([
+		{
+			name: "artifact_json_type",
+			method: "json_type",
+			description: "Return the JSON format (json | json5 | jsonl | ndjson) of a JSON artifact produced earlier in this turn.",
+			argsSchema: validator.object({})
+		},
+		{
+			name: "artifact_json_keys",
+			method: "json_keys",
+			description: "Return the top-level keys of a JSON artifact produced earlier in this turn.",
+			argsSchema: validator.object({})
+		},
+		{
+			name: "artifact_json_length",
+			method: "json_length",
+			description: "Return the record count of a JSON artifact produced earlier in this turn (1 for json/json5; line count for jsonl/ndjson).",
+			argsSchema: validator.object({})
+		},
+		{
+			name: "artifact_json_get",
+			method: "json_get",
+			description: "Evaluate a JSONPath expression against a JSON artifact produced earlier in this turn.",
+			argsSchema: validator.object({ path: validator.string().required().description("JSONPath expression, e.g. '$.user.name'.") })
+		},
+		{
+			name: "artifact_json_filter",
+			method: "json_filter",
+			description: "Return records of a JSON artifact (produced earlier in this turn) matched by a JSONPath filter.",
+			argsSchema: validator.object({ path: validator.string().required().description("JSONPath filter expression, e.g. '$[?(@.age>18)]'.") })
+		},
+		{
+			name: "artifact_json_slice",
+			method: "json_slice",
+			description: "Return a slice of records by index range from a JSON artifact produced earlier in this turn.",
+			argsSchema: validator.object({
+				start: validator.number().integer().min(0).optional().description("Start index (inclusive)."),
+				end: validator.number().integer().min(0).optional().description("End index (exclusive).")
+			})
+		},
+		{
+			name: "artifact_json_pluck",
+			method: "json_pluck",
+			description: "Return all values matched by a JSONPath expression across every record of a JSON artifact produced earlier in this turn.",
+			argsSchema: validator.object({ path: validator.string().required().description("JSONPath expression, e.g. '$..name'.") })
+		}
+	]);
+	/**
+	* Forges base-class tools plus JSON-specific tools narrowed to {@link SpooledJsonArtifact}.
+	*
+	* @remarks
+	* Standard subclass extension pattern: call `SpooledArtifact.forgeTools(ctx)` to produce
+	* the base seven `artifact_*` tools narrowed to any `SpooledArtifact` in the turn, then
+	* register one `ArtifactTool` per JSON-specific descriptor narrowed to JSON artifacts.
+	* Downstream consumers building their own subclasses should follow the same shape.
+	*/
+	static forgeTools(ctx) {
+		const registry = SpooledArtifact.forgeTools(ctx);
+		const requires = SpooledJsonArtifact;
+		const compatibleIds = [...ctx.turnToolCalls].filter((tc) => !tc.fromArtifactTool && isInstanceOf(tc.results, requires.name, requires)).map((tc) => tc.id);
+		if (compatibleIds.length === 0) return registry;
+		for (const descriptor of this.toolMethods) {
+			const callIdSchema = validator.string().valid(...compatibleIds).required().description("ToolCall id of the artifact to query.");
+			const argsSchema = (descriptor.argsSchema ?? validator.object({})).append({ callId: callIdSchema });
+			const tool = new ArtifactTool({
+				name: descriptor.name,
+				description: descriptor.description,
+				inputSchema: argsSchema,
+				ephemeral: true,
+				onCollision: "replace",
+				handler: async (rawArgs, ctxInner) => {
+					const args = rawArgs;
+					const tc = [...ctxInner.turnToolCalls].find((t) => t.id === args.callId);
+					if (!tc) return `Error: no tool call with id ${args.callId} in this turn`;
+					const artifact = tc.results;
+					if (!isInstanceOf(artifact, requires.name, requires)) return `Error: tool call ${args.callId} results are not a ${requires.name} instance`;
+					const methodArgs = [];
+					if (descriptor.method === "json_get" || descriptor.method === "json_filter" || descriptor.method === "json_pluck") methodArgs.push(args.path);
+					else if (descriptor.method === "json_slice") methodArgs.push(args.start, args.end);
+					const fn = artifact[descriptor.method];
+					if (typeof fn !== "function") return `Error: artifact has no method ${descriptor.method}`;
+					const result = await Promise.resolve(fn.apply(artifact, methodArgs));
+					return (descriptor.serialise ?? defaultSerialise)(result);
+				}
+			});
+			registry.register(tool);
+		}
+		return registry;
+	}
+	/**
+	* Resolves and caches the detected or provided format.
+	*/
+	async #resolveFormat() {
+		if (this.#format !== void 0) return this.#format;
+		const lines = await this.cat();
+		this.#format = inferFormat(lines.join("\n"));
+		return this.#format;
+	}
+	/**
+	* Parses and caches all records from the artifact.
+	*
+	* @remarks
+	* For `json`/`json5` format: returns a single-element array containing the parsed root value.
+	* For `jsonl`/`ndjson` format: returns one element per non-empty line.
+	*/
+	async #resolveRecords() {
+		if (this.#parsed !== void 0) return this.#parsed;
+		const format = await this.#resolveFormat();
+		const lines = await this.cat();
+		if (format === "json") this.#parsed = [JSON.parse(lines.join("\n"))];
+		else if (format === "json5") this.#parsed = [JSON5.parse(lines.join("\n"))];
+		else this.#parsed = lines.filter((l) => l.trim().length > 0).map((l) => JSON.parse(l));
+		return this.#parsed;
+	}
+	/**
+	* Returns the detected or provided format for this artifact.
+	*
+	* @returns One of `'json'`, `'json5'`, `'jsonl'`, or `'ndjson'`.
+	*/
+	async json_type() {
+		return this.#resolveFormat();
+	}
+	/**
+	* Returns the top-level keys of the parsed content.
+	*
+	* @remarks
+	* - For `json`/`json5`: returns the keys of the root object, or `undefined` when the root is
+	*   not a plain object (e.g. an array or scalar).
+	* - For `jsonl`/`ndjson`: returns the union of keys across all records that are plain objects.
+	*   Duplicate keys are deduplicated.
+	*
+	* @returns Array of key strings, or `undefined` when no object keys are present.
+	*/
+	async json_keys() {
+		const records = await this.#resolveRecords();
+		const format = await this.#resolveFormat();
+		if (format === "json" || format === "json5") {
+			const root = records[0];
+			if (isObject(root)) return Object.keys(root);
+			return;
+		}
+		const keySet = /* @__PURE__ */ new Set();
+		for (const record of records) if (isObject(record)) for (const key of Object.keys(record)) keySet.add(key);
+		return keySet.size > 0 ? Array.from(keySet) : void 0;
+	}
+	/**
+	* Returns the total number of records in the artifact.
+	*
+	* @remarks
+	* - For `json`/`json5`: always `1` (the entire artifact is a single value).
+	* - For `jsonl`/`ndjson`: the number of non-empty lines.
+	*
+	* @returns The record count.
+	*/
+	async json_length() {
+		return (await this.#resolveRecords()).length;
+	}
+	/**
+	* Evaluates a JSONPath expression against the parsed content.
+	*
+	* @remarks
+	* Uses [JSONPath-Plus](https://github.com/JSONPath-Plus/JSONPath). Full JSONPath syntax is
+	* supported: recursive descent (`$..*`), filter expressions (`$[?(@.age > 18)]`), union
+	* selectors, and more.
+	*
+	* - For `json`/`json5`: evaluates the expression against the root value.
+	* - For `jsonl`/`ndjson`: evaluates the expression against each record and returns a flat
+	*   array of all matches across all records.
+	*
+	* @param path - A JSONPath expression (e.g. `'$.user.address.city'`, `'$..name'`).
+	* @returns Array of matched values. Empty array when no matches are found.
+	*/
+	async json_get(path) {
+		const records = await this.#resolveRecords();
+		const format = await this.#resolveFormat();
+		if (format === "json" || format === "json5") return JSONPath({
+			path,
+			json: records[0]
+		});
+		return records.flatMap((r) => JSONPath({
+			path,
+			json: r
+		}));
+	}
+	/**
+	* Returns a slice of the parsed records by index range.
+	*
+	* @remarks
+	* For `json`/`json5`: always returns `[root]` — the artifact is a single record so slicing is
+	* not meaningful. For `jsonl`/`ndjson`: behaves like `Array.prototype.slice`.
+	*
+	* @param start - Start index (inclusive). Defaults to `0`.
+	* @param end - End index (exclusive). Defaults to the record count.
+	* @returns Array of sliced records.
+	*/
+	async json_slice(start, end) {
+		const records = await this.#resolveRecords();
+		const format = await this.#resolveFormat();
+		if (format === "json" || format === "json5") return records;
+		return records.slice(start, end);
+	}
+	/**
+	* Returns records matched by a JSONPath filter expression.
+	*
+	* @remarks
+	* Evaluates `path` against each record and returns those for which the expression produces at
+	* least one match. For `json`/`json5`, evaluates against the root value and returns it in an
+	* array if matched.
+	*
+	* @param path - A JSONPath expression (e.g. `'$[?(@.status === "active")]'`).
+	* @returns Array of matching records.
+	*/
+	async json_filter(path) {
+		return (await this.#resolveRecords()).filter((r) => {
+			const matches = JSONPath({
+				path,
+				json: r
+			});
+			return Array.isArray(matches) && matches.length > 0;
+		});
+	}
+	/**
+	* Returns all values matched by a JSONPath expression across every record.
+	*
+	* @remarks
+	* Convenience over {@link SpooledJsonArtifact.json_get} with an identical signature — use
+	* whichever name better communicates intent at the call site. `json_pluck` reads well for
+	* extracting a single field column; `json_get` reads well for structured queries.
+	*
+	* @param path - A JSONPath expression (e.g. `'$..name'`).
+	* @returns Array of matched values.
+	*/
+	async json_pluck(path) {
+		return this.json_get(path);
+	}
+};
+//#endregion
+//#region src/lib/classes/spooled_markdown_artifact.ts
+/**
+* Returns a configured remark processor with frontmatter and GFM support.
+*/
+function processor() {
+	return remark().use(remarkFrontmatter).use(remarkGfm);
+}
+/**
+* Parses a heading line (e.g. `## My Heading`) and returns `{ depth, text }`, or `null` when
+* the line is not an ATX heading.
+*/
+function parseHeadingLine(line) {
+	const match = /^(#{1,6})\s+(.*)$/.exec(line);
+	if (!match) return null;
+	return {
+		depth: match[1].length,
+		text: match[2].trim()
+	};
+}
+/**
+* Returns the length of a fence marker at the start of `line` (3+), or `0` if the line is not
+* a fence opener/closer. Handles both backtick (` ``` `) and tilde (`~~~`) fences.
+*/
+function fenceLength(line) {
+	const trimmed = line.trimStart();
+	const match = /^(`{3,}|~{3,})/.exec(trimmed);
+	return match ? match[1].length : 0;
+}
+/**
+* Extracts the language identifier from a fence opener line (e.g. ` ```ts ` → `'ts'`), or
+* `null` when none is present.
+*/
+function fenceLang(line) {
+	const trimmed = line.trimStart();
+	const match = /^(?:`{3,}|~{3,})(\S+)/.exec(trimmed);
+	return match ? match[1] : null;
+}
+/**
+* A {@link @nhtio/adk!SpooledArtifact} specialisation that adds markdown-aware structural queries.
+*
+* @remarks
+* Designed for large markdown documents where loading the full content into memory is
+* impractical. The structural index (heading positions, code block positions) is built by a
+* single line-by-line scan of the {@link @nhtio/adk!SpoolReader} without retaining any content. Only the
+* tiny metadata index and the parsed frontmatter object are cached.
+*
+* Content retrieval is always bounded — use `cat(start, end)` or the `startLine`/`endLine`
+* parameters on inline methods to fetch only the lines you need.
+*
+* Inline methods (`md_links`, `md_images`, `md_text`, `md_ast`) accept optional line-range
+* arguments. Without a range they read the full document — documented trade-off, caller
+* responsibility to bound the range for large documents.
+*
+* The processor always applies `remark-gfm` (tables, task lists, strikethrough, autolinks)
+* in addition to standard CommonMark and YAML frontmatter.
+*/
+var SpooledMarkdownArtifact = class SpooledMarkdownArtifact extends SpooledArtifact {
+	#index;
+	#frontmatter;
+	/**
+	* @param reader - The backing store to read from.
+	*/
+	constructor(reader) {
+		super(reader);
+	}
+	/**
+	* Returns `true` if `value` is a {@link SpooledMarkdownArtifact} instance.
+	*
+	* @remarks
+	* Uses the cross-realm-safe {@link @nhtio/adk!isInstanceOf} guard: `instanceof` first, then
+	* `Symbol.hasInstance`, then a `constructor.name` fallback. Matches the pattern used by every
+	* other class guard in the ADK; safe against the dual-module-copy case where two distinct
+	* `SpooledMarkdownArtifact` classes coexist in the same realm.
+	*/
+	static isSpooledMarkdownArtifact(value) {
+		return isInstanceOf(value, "SpooledMarkdownArtifact", SpooledMarkdownArtifact);
+	}
+	/**
+	* The markdown-specific artifact-query descriptors this class adds on top of the base set.
+	*
+	* @remarks
+	* Lists `artifact_md_frontmatter`, `artifact_md_headings`, `artifact_md_code_blocks`,
+	* `artifact_md_sections`, `artifact_md_links`, `artifact_md_images`, `artifact_md_text`,
+	* `artifact_md_ast`. The base seven descriptors (`artifact_head`, etc.) are NOT included
+	* here — they are forged separately by {@link SpooledMarkdownArtifact.forgeTools}, which
+	* calls `SpooledArtifact.forgeTools(ctx)` to produce the base-narrowed tools and then
+	* registers its own markdown tools on the result. Downstream consumers building custom
+	* subclasses should follow the same pattern: own only your own descriptors; override
+	* `forgeTools` to compose with the base output.
+	*/
+	static toolMethods = Object.freeze([
+		{
+			name: "artifact_md_frontmatter",
+			method: "md_frontmatter",
+			description: "Return parsed YAML frontmatter (or undefined) from a markdown artifact produced earlier in this turn.",
+			argsSchema: validator.object({})
+		},
+		{
+			name: "artifact_md_headings",
+			method: "md_headings",
+			description: "Return all headings, optionally filtered by depth, from a markdown artifact produced earlier in this turn.",
+			argsSchema: validator.object({ depth: validator.number().integer().min(1).max(6).optional().description("ATX heading depth (1-6).") })
+		},
+		{
+			name: "artifact_md_code_blocks",
+			method: "md_code_blocks",
+			description: "Return all fenced code block entries, optionally filtered by language, from a markdown artifact produced earlier in this turn.",
+			argsSchema: validator.object({ lang: validator.string().optional().description("Language identifier. Pass empty string to match blocks with no lang.") })
+		},
+		{
+			name: "artifact_md_sections",
+			method: "md_sections",
+			description: "Return document sections (line-range metadata only) from a markdown artifact produced earlier in this turn.",
+			argsSchema: validator.object({ depth: validator.number().integer().min(1).max(6).optional().description("ATX heading depth (1-6).") })
+		},
+		{
+			name: "artifact_md_links",
+			method: "md_links",
+			description: "Return all inline and reference links within the given line range from a markdown artifact produced earlier in this turn.",
+			argsSchema: validator.object({
+				startLine: validator.number().integer().min(0).optional().description("Start line (inclusive)."),
+				endLine: validator.number().integer().min(0).optional().description("End line (exclusive).")
+			})
+		},
+		{
+			name: "artifact_md_images",
+			method: "md_images",
+			description: "Return all images within the given line range from a markdown artifact produced earlier in this turn.",
+			argsSchema: validator.object({
+				startLine: validator.number().integer().min(0).optional().description("Start line (inclusive)."),
+				endLine: validator.number().integer().min(0).optional().description("End line (exclusive).")
+			})
+		},
+		{
+			name: "artifact_md_text",
+			method: "md_text",
+			description: "Return plain text with markup stripped, for the given line range, from a markdown artifact produced earlier in this turn.",
+			argsSchema: validator.object({
+				startLine: validator.number().integer().min(0).optional().description("Start line (inclusive)."),
+				endLine: validator.number().integer().min(0).optional().description("End line (exclusive).")
+			})
+		},
+		{
+			name: "artifact_md_ast",
+			method: "md_ast",
+			description: "Return the full MDAST Root for the specified line range from a markdown artifact produced earlier in this turn.",
+			argsSchema: validator.object({
+				startLine: validator.number().integer().min(0).optional().description("Start line (inclusive)."),
+				endLine: validator.number().integer().min(0).optional().description("End line (exclusive).")
+			})
+		}
+	]);
+	/**
+	* Forges base-class tools plus markdown-specific tools narrowed to
+	* {@link SpooledMarkdownArtifact}.
+	*
+	* @remarks
+	* Standard subclass extension pattern: call `SpooledArtifact.forgeTools(ctx)` to produce
+	* the base seven `artifact_*` tools narrowed to any `SpooledArtifact` in the turn, then
+	* register one `ArtifactTool` per markdown-specific descriptor narrowed to markdown
+	* artifacts. Downstream consumers building their own subclasses should follow the same
+	* shape.
+	*/
+	static forgeTools(ctx) {
+		const registry = SpooledArtifact.forgeTools(ctx);
+		const requires = SpooledMarkdownArtifact;
+		const compatibleIds = [...ctx.turnToolCalls].filter((tc) => !tc.fromArtifactTool && isInstanceOf(tc.results, requires.name, requires)).map((tc) => tc.id);
+		if (compatibleIds.length === 0) return registry;
+		for (const descriptor of this.toolMethods) {
+			const callIdSchema = validator.string().valid(...compatibleIds).required().description("ToolCall id of the artifact to query.");
+			const argsSchema = (descriptor.argsSchema ?? validator.object({})).append({ callId: callIdSchema });
+			const tool = new ArtifactTool({
+				name: descriptor.name,
+				description: descriptor.description,
+				inputSchema: argsSchema,
+				ephemeral: true,
+				onCollision: "replace",
+				handler: async (rawArgs, ctxInner) => {
+					const args = rawArgs;
+					const tc = [...ctxInner.turnToolCalls].find((t) => t.id === args.callId);
+					if (!tc) return `Error: no tool call with id ${args.callId} in this turn`;
+					const artifact = tc.results;
+					if (!isInstanceOf(artifact, requires.name, requires)) return `Error: tool call ${args.callId} results are not a ${requires.name} instance`;
+					const methodArgs = [];
+					if (descriptor.method === "md_headings" || descriptor.method === "md_sections") methodArgs.push(args.depth);
+					else if (descriptor.method === "md_code_blocks") methodArgs.push(args.lang);
+					else if (descriptor.method === "md_links" || descriptor.method === "md_images" || descriptor.method === "md_text" || descriptor.method === "md_ast") methodArgs.push(args.startLine, args.endLine);
+					const fn = artifact[descriptor.method];
+					if (typeof fn !== "function") return `Error: artifact has no method ${descriptor.method}`;
+					const result = await Promise.resolve(fn.apply(artifact, methodArgs));
+					return (descriptor.serialise ?? defaultSerialise)(result);
+				}
+			});
+			registry.register(tool);
+		}
+		return registry;
+	}
+	/**
+	* Builds the structural index in a single top-to-bottom pass, retaining only metadata.
+	*/
+	async #resolveIndex() {
+		if (this.#index !== void 0) return this.#index;
+		const count = await this.lineCount();
+		const headingsRaw = [];
+		const codeBlocks = [];
+		let inFrontmatter = false;
+		let frontmatterClosed = false;
+		let inCodeBlock = false;
+		let openFenceLen = 0;
+		let openFenceStartLine = 0;
+		let openFenceLang = null;
+		for (let i = 0; i < count; i++) {
+			const l = await this.line(i) ?? "";
+			if (i === 0 && l.trim() === "---") {
+				inFrontmatter = true;
+				continue;
+			}
+			if (inFrontmatter) {
+				if (l.trim() === "---") {
+					inFrontmatter = false;
+					frontmatterClosed = true;
+				}
+				continue;
+			}
+			if (!frontmatterClosed && i === 0) {}
+			const fLen = fenceLength(l);
+			if (!inCodeBlock && fLen >= 3) {
+				inCodeBlock = true;
+				openFenceLen = fLen;
+				openFenceStartLine = i;
+				openFenceLang = fenceLang(l);
+				continue;
+			}
+			if (inCodeBlock) {
+				if (fLen >= openFenceLen) {
+					const openChar = (await this.line(openFenceStartLine) ?? "").trimStart()[0];
+					if (l.trimStart()[0] === openChar) {
+						codeBlocks.push({
+							lang: openFenceLang,
+							startLine: openFenceStartLine,
+							endLine: i
+						});
+						inCodeBlock = false;
+						openFenceLen = 0;
+					}
+				}
+				continue;
+			}
+			const heading = parseHeadingLine(l);
+			if (heading) headingsRaw.push({
+				...heading,
+				startLine: i
+			});
+		}
+		if (inCodeBlock) codeBlocks.push({
+			lang: openFenceLang,
+			startLine: openFenceStartLine,
+			endLine: count - 1
+		});
+		const headings = headingsRaw.map((h, idx) => {
+			const nextBoundary = headingsRaw.slice(idx + 1).find((n) => n.depth <= h.depth);
+			const endLine = nextBoundary ? nextBoundary.startLine - 1 : count - 1;
+			return {
+				...h,
+				endLine
+			};
+		});
+		this.#index = {
+			headings,
+			codeBlocks
+		};
+		return this.#index;
+	}
+	/**
+	* Returns the parsed YAML frontmatter, or `undefined` when no frontmatter block is present.
+	*
+	* @remarks
+	* Short-circuits after reading the frontmatter block — never reads the document body. Caches
+	* the result so subsequent calls are free. The result is `undefined` (not an empty object)
+	* when no frontmatter is found, distinguishing "no frontmatter" from "empty frontmatter".
+	*/
+	async md_frontmatter() {
+		if (this.#frontmatter !== void 0) return this.#frontmatter ?? void 0;
+		if ((await this.line(0))?.trim() !== "---") {
+			this.#frontmatter = null;
+			return;
+		}
+		const maxScan = Math.min(await this.lineCount(), 200);
+		const yamlLines = [];
+		let closed = false;
+		for (let i = 1; i < maxScan; i++) {
+			const l = await this.line(i);
+			if (l?.trim() === "---") {
+				closed = true;
+				break;
+			}
+			yamlLines.push(l ?? "");
+		}
+		if (!closed) {
+			this.#frontmatter = null;
+			return;
+		}
+		this.#frontmatter = load(yamlLines.join("\n"));
+		return this.#frontmatter;
+	}
+	/**
+	* Returns all headings in document order, optionally filtered by depth.
+	*
+	* @remarks
+	* Uses the cached structural index — no content is fetched from the {@link @nhtio/adk!SpoolReader}.
+	*
+	* @param depth - When provided, only headings at this ATX depth (1–6) are returned.
+	*/
+	async md_headings(depth) {
+		const index = await this.#resolveIndex();
+		if (depth === void 0) return index.headings.slice();
+		return index.headings.filter((h) => h.depth === depth);
+	}
+	/**
+	* Returns all fenced code block entries, optionally filtered by language identifier.
+	*
+	* @remarks
+	* Returns line-range metadata only — no content is fetched. Use `cat(entry.startLine + 1,
+	* entry.endLine)` to retrieve the code body (excluding fence lines).
+	*
+	* @param lang - When provided, only blocks with this exact lang identifier are returned.
+	*   Pass an empty string to match blocks with no lang identifier.
+	*/
+	async md_code_blocks(lang) {
+		const index = await this.#resolveIndex();
+		if (lang === void 0) return index.codeBlocks.slice();
+		const target = lang === "" ? null : lang;
+		return index.codeBlocks.filter((b) => b.lang === target);
+	}
+	/**
+	* Returns document sections derived from the structural index.
+	*
+	* @remarks
+	* Returns only line-range metadata — body content is never fetched. To retrieve the body of a
+	* section, call `cat(section.bodyStartLine, section.bodyEndLine + 1)`.
+	*
+	* When `depth` is provided, only sections introduced by a heading at that depth are returned;
+	* deeper headings become part of the body.
+	*
+	* @param depth - When provided, only sections at this ATX depth (1–6) are returned.
+	*/
+	async md_sections(depth) {
+		const index = await this.#resolveIndex();
+		return (depth !== void 0 ? index.headings.filter((h) => h.depth === depth) : index.headings).map((h) => ({
+			depth: h.depth,
+			heading: h.text,
+			headingLine: h.startLine,
+			bodyStartLine: h.startLine + 1,
+			bodyEndLine: h.endLine
+		}));
+	}
+	/**
+	* Returns the full MDAST Root for the specified line range.
+	*
+	* @remarks
+	* Without a range, reads the full document — for large documents, use
+	* {@link SpooledMarkdownArtifact.md_sections} to locate sections and pass
+	* bounded line ranges here.
+	*
+	* @param startLine - 0-based start line (inclusive). Defaults to `0`.
+	* @param endLine - 0-based end line (exclusive). Defaults to `lineCount()`.
+	*/
+	async md_ast(startLine, endLine) {
+		const lines = await this.cat(startLine, endLine);
+		return processor().parse(lines.join("\n"));
+	}
+	/**
+	* Returns all inline and reference links in the specified line range.
+	*
+	* @param startLine - 0-based start line (inclusive). Defaults to `0`.
+	* @param endLine - 0-based end line (exclusive). Defaults to `lineCount()`.
+	*/
+	async md_links(startLine, endLine) {
+		const lines = await this.cat(startLine, endLine);
+		const ast = processor().parse(lines.join("\n"));
+		const results = [];
+		visit(ast, "link", (node) => {
+			results.push({
+				text: toString(node),
+				url: node.url,
+				title: node.title ?? void 0
+			});
+		});
+		return results;
+	}
+	/**
+	* Returns all images in the specified line range.
+	*
+	* @param startLine - 0-based start line (inclusive). Defaults to `0`.
+	* @param endLine - 0-based end line (exclusive). Defaults to `lineCount()`.
+	*/
+	async md_images(startLine, endLine) {
+		const lines = await this.cat(startLine, endLine);
+		const ast = processor().parse(lines.join("\n"));
+		const results = [];
+		visit(ast, "image", (node) => {
+			results.push({
+				alt: node.alt ?? "",
+				url: node.url,
+				title: node.title ?? void 0
+			});
+		});
+		return results;
+	}
+	/**
+	* Returns all document text with markup stripped, for the specified line range.
+	*
+	* @remarks
+	* Uses `mdast-util-to-string` to extract plain text from the AST — code, link text, and
+	* alt text are included; markdown syntax is removed.
+	*
+	* @param startLine - 0-based start line (inclusive). Defaults to `0`.
+	* @param endLine - 0-based end line (exclusive). Defaults to `lineCount()`.
+	*/
+	async md_text(startLine, endLine) {
+		const lines = await this.cat(startLine, endLine);
+		return toString(processor().parse(lines.join("\n")));
+	}
+};
+//#endregion
+export { SpooledJsonArtifact as n, SpooledMarkdownArtifact as t };
+
+//# sourceMappingURL=spooled_markdown_artifact-BpUJol0W.mjs.map