markform 0.1.2 → 0.1.4

package/dist/{src-BXRkGFpG.mjs → src-BNh7Cx9P.mjs}

@@ -1,5 +1,6 @@
-import { N as PatchSchema } from "./coreTypes-Dful87E0.mjs";
-import { C as DEFAULT_ROLE_INSTRUCTIONS, N as getWebSearchConfig, S as DEFAULT_ROLES, _ as DEFAULT_MAX_TURNS, b as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, g as DEFAULT_MAX_PATCHES_PER_TURN, h as DEFAULT_MAX_ISSUES_PER_TURN, n as getFieldsForRoles, p as AGENT_ROLE, r as inspect, t as applyPatches, u as serialize, x as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN, y as DEFAULT_PRIORITY } from "./apply-BfAGTHMh.mjs";
+import { L as PatchSchema } from "./coreTypes-pyctKRgc.mjs";
+import { C as DEFAULT_ROLE_INSTRUCTIONS, P as getWebSearchConfig, S as DEFAULT_ROLES, _ as DEFAULT_MAX_TURNS, b as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, g as DEFAULT_MAX_PATCHES_PER_TURN, h as DEFAULT_MAX_ISSUES_PER_TURN, n as getFieldsForRoles, p as AGENT_ROLE, r as inspect, t as applyPatches, u as serialize, x as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN, y as DEFAULT_PRIORITY } from "./apply-C54EMAJ1.mjs";
+import { createRequire } from "node:module";
 import { z } from "zod";
 import Markdoc from "@markdoc/markdoc";
 import YAML from "yaml";
@@ -12,6 +13,27 @@ import { ZodFirstPartyTypeKind } from "zod/v3";
 import { google } from "@ai-sdk/google";
 import { xai } from "@ai-sdk/xai";
 
+//#region src/engine/fieldRegistry.ts
+/**
+* All field kinds as a const tuple - the single source of truth.
+* Adding a new kind here will cause TypeScript errors until all
+* corresponding types and handlers are added.
+*/
+const FIELD_KINDS = [
+	"string",
+	"number",
+	"string_list",
+	"checkboxes",
+	"single_select",
+	"multi_select",
+	"url",
+	"url_list",
+	"date",
+	"year",
+	"table"
+];
+
+//#endregion
 //#region src/engine/parseHelpers.ts
 /** Parse error with source location info */
 var ParseError = class extends Error {
@@ -90,6 +112,19 @@ function getValidateAttr(node) {
 	if (typeof value === "object") return [value];
 }
 /**
+* Get string array attribute value or undefined.
+* Handles both single string (converts to array) and array formats.
+*/
+function getStringArrayAttr(node, name$2) {
+	const value = node.attributes?.[name$2];
+	if (value === void 0 || value === null) return;
+	if (Array.isArray(value)) {
+		const strings = value.filter((v) => typeof v === "string");
+		return strings.length > 0 ? strings : void 0;
+	}
+	if (typeof value === "string") return [value];
+}
+/**
 * Extract option items from node children (for option lists).
 * Works with raw AST nodes. Collects text and ID from list items.
 */
@@ -146,6 +181,55 @@ function extractFenceValue(node) {
 	}
 	return null;
 }
+/**
+* Extract table content from node children.
+* Handles both raw text and Markdoc-parsed table nodes.
+* Reconstructs markdown table format from the AST.
+*/
+function extractTableContent(node) {
+	const lines = [];
+	function extractTextFromNode(n) {
+		if (!n || typeof n !== "object") return "";
+		if (n.type === "text" && typeof n.attributes?.content === "string") return n.attributes.content;
+		if (n.children && Array.isArray(n.children)) return n.children.map(extractTextFromNode).join("");
+		return "";
+	}
+	function extractTableRow(trNode) {
+		if (!trNode.children || !Array.isArray(trNode.children)) return "";
+		return `| ${trNode.children.filter((c) => c.type === "th" || c.type === "td").map((c) => extractTextFromNode(c).trim()).join(" | ")} |`;
+	}
+	function processNode(child) {
+		if (!child || typeof child !== "object") return;
+		if (child.type === "paragraph" || child.type === "inline") {
+			const text = extractTextFromNode(child).trim();
+			if (text) lines.push(text);
+			return;
+		}
+		if (child.type === "text" && typeof child.attributes?.content === "string") {
+			const text = child.attributes.content.trim();
+			if (text) lines.push(text);
+			return;
+		}
+		if (child.type === "table") {
+			const thead = child.children?.find((c) => c.type === "thead");
+			if (thead?.children) for (const tr of thead.children.filter((c) => c.type === "tr")) lines.push(extractTableRow(tr));
+			if (thead?.children?.length) {
+				const firstTr = thead.children.find((c) => c.type === "tr");
+				if (firstTr?.children) {
+					const colCount = firstTr.children.filter((c) => c.type === "th" || c.type === "td").length;
+					const separatorCells = Array(colCount).fill("----");
+					lines.push(`| ${separatorCells.join(" | ")} |`);
+				}
+			}
+			const tbody = child.children?.find((c) => c.type === "tbody");
+			if (tbody?.children) for (const tr of tbody.children.filter((c) => c.type === "tr")) lines.push(extractTableRow(tr));
+			return;
+		}
+		if (child.children && Array.isArray(child.children)) for (const c of child.children) processNode(c);
+	}
+	if (node.children && Array.isArray(node.children)) for (const child of node.children) processNode(child);
+	return lines.join("\n").trim() || null;
+}
 
 //#endregion
 //#region src/engine/parseSentinels.ts
@@ -157,7 +241,7 @@ const SENTINEL_ABORT = "%ABORT%";
 * Formats: `%SKIP%`, `%SKIP% (reason text)`, `%ABORT%`, `%ABORT% (reason text)`
 * Returns null if the content is not a sentinel.
 */
-function parseSentinel(content) {
+function parseSentinel$1(content) {
 	if (!content) return null;
 	const trimmed = content.trim();
 	const reasonPattern = /^\((.+)\)$/s;
@@ -195,7 +279,7 @@ function parseSentinel(content) {
 function tryParseSentinelResponse(node, fieldId, required) {
 	const fenceContent = extractFenceValue(node);
 	const stateAttr = getStringAttr(node, "state");
-	const sentinel = parseSentinel(fenceContent);
+	const sentinel = parseSentinel$1(fenceContent);
 	if (!sentinel) return null;
 	if (sentinel.type === "skip") {
 		if (stateAttr !== void 0 && stateAttr !== "skipped") throw new ParseError(`Field '${fieldId}' has conflicting state='${stateAttr}' with %SKIP% sentinel`);
@@ -215,6 +299,216 @@ function tryParseSentinelResponse(node, fieldId, required) {
 	return null;
 }
 
+//#endregion
+//#region src/engine/table/parseTable.ts
+/** Sentinel pattern: %SKIP% or %SKIP:reason% or %SKIP(reason)% */
+const SKIP_PATTERN = /^%SKIP(?:[:(](.*))?[)]?%$/i;
+/** Sentinel pattern: %ABORT% or %ABORT:reason% or %ABORT(reason)% */
+const ABORT_PATTERN = /^%ABORT(?:[:(](.*))?[)]?%$/i;
+/**
+* Detect if a cell value is a sentinel.
+*/
+function parseSentinel(value) {
+	const trimmed = value.trim();
+	const skipMatch = SKIP_PATTERN.exec(trimmed);
+	if (skipMatch) return {
+		type: "skip",
+		reason: skipMatch[1]
+	};
+	const abortMatch = ABORT_PATTERN.exec(trimmed);
+	if (abortMatch) return {
+		type: "abort",
+		reason: abortMatch[1]
+	};
+	return null;
+}
+/**
+* Parse a cell value according to its column type.
+* Returns a CellResponse with appropriate state.
+*/
+function parseCellValue(rawValue, columnType) {
+	const trimmed = rawValue.trim();
+	if (!trimmed) return { state: "skipped" };
+	const sentinel = parseSentinel(trimmed);
+	if (sentinel) return {
+		state: sentinel.type === "skip" ? "skipped" : "aborted",
+		reason: sentinel.reason
+	};
+	switch (columnType) {
+		case "string": return {
+			state: "answered",
+			value: trimmed
+		};
+		case "number": {
+			const num = parseFloat(trimmed);
+			if (isNaN(num)) return {
+				state: "answered",
+				value: trimmed
+			};
+			return {
+				state: "answered",
+				value: num
+			};
+		}
+		case "url": return {
+			state: "answered",
+			value: trimmed
+		};
+		case "date": return {
+			state: "answered",
+			value: trimmed
+		};
+		case "year": {
+			const year = parseInt(trimmed, 10);
+			if (isNaN(year) || !Number.isInteger(year)) return {
+				state: "answered",
+				value: trimmed
+			};
+			return {
+				state: "answered",
+				value: year
+			};
+		}
+	}
+}
+/**
+* Parse a table row into cell values.
+* Handles leading/trailing pipes and cell trimming.
+*/
+function parseTableRow(line) {
+	let trimmed = line.trim();
+	if (trimmed.startsWith("|")) trimmed = trimmed.slice(1);
+	if (trimmed.endsWith("|")) trimmed = trimmed.slice(0, -1);
+	return trimmed.split("|").map((cell) => cell.trim());
+}
+/**
+* Extract header labels from table content.
+* Returns array of header labels from the first row, or empty array if no valid header.
+*/
+function extractTableHeaderLabels(content) {
+	if (!content || content.trim() === "") return [];
+	const lines = content.trim().split("\n").filter((line) => line.trim());
+	if (lines.length === 0) return [];
+	return parseTableRow(lines[0]);
+}
+/**
+* Check if a line is a valid table separator row.
+* Each cell should contain only dashes and optional colons for alignment.
+*/
+function isValidSeparator(line, expectedCols) {
+	const cells = parseTableRow(line);
+	if (cells.length !== expectedCols) return false;
+	const separatorPattern = /^:?-+:?$/;
+	return cells.every((cell) => separatorPattern.test(cell.trim()));
+}
+/**
+* Parse a markdown table with column schema for type coercion.
+*
+* @param content - The markdown table content
+* @param columns - Column definitions from the table field schema
+* @param dataStartLine - Optional line index where data rows start (skips header validation)
+* @returns Parsed table value with typed cells
+*/
+function parseMarkdownTable(content, columns, dataStartLine) {
+	const lines = content.trim().split("\n").filter((line) => line.trim());
+	if (lines.length === 0) return {
+		ok: true,
+		value: {
+			kind: "table",
+			rows: []
+		}
+	};
+	if (lines.length < 2) return {
+		ok: false,
+		error: "Table must have at least a header and separator row"
+	};
+	const headerLine = lines[0];
+	const headers = parseTableRow(headerLine);
+	const separatorLine = lines[1];
+	if (!isValidSeparator(separatorLine, headers.length)) return {
+		ok: false,
+		error: "Invalid table separator row"
+	};
+	if (dataStartLine !== void 0) {
+		const rows$1 = [];
+		for (let i = dataStartLine; i < lines.length; i++) {
+			const rawCells = parseTableRow(lines[i]);
+			const row = {};
+			for (let j = 0; j < columns.length; j++) {
+				const column = columns[j];
+				const rawValue = rawCells[j] ?? "";
+				row[column.id] = parseCellValue(rawValue, column.type);
+			}
+			rows$1.push(row);
+		}
+		return {
+			ok: true,
+			value: {
+				kind: "table",
+				rows: rows$1
+			}
+		};
+	}
+	const columnIdToIndex = /* @__PURE__ */ new Map();
+	for (let i = 0; i < headers.length; i++) {
+		const header = headers[i];
+		const column = columns.find((c) => c.id === header || c.label === header);
+		if (column) columnIdToIndex.set(column.id, i);
+	}
+	const rows = [];
+	for (let i = 2; i < lines.length; i++) {
+		const rawCells = parseTableRow(lines[i]);
+		const row = {};
+		for (const column of columns) {
+			const cellIndex = columnIdToIndex.get(column.id);
+			const rawValue = cellIndex !== void 0 ? rawCells[cellIndex] ?? "" : "";
+			row[column.id] = parseCellValue(rawValue, column.type);
+		}
+		rows.push(row);
+	}
+	return {
+		ok: true,
+		value: {
+			kind: "table",
+			rows
+		}
+	};
+}
+/**
+* Parse just the raw table structure without schema.
+* Useful for validation and error reporting.
+*/
+function parseRawTable(content) {
+	const lines = content.trim().split("\n").filter((line) => line.trim());
+	if (lines.length === 0) return {
+		ok: true,
+		headers: [],
+		rows: []
+	};
+	if (lines.length < 2) return {
+		ok: false,
+		error: "Table must have at least a header and separator row"
+	};
+	const headers = parseTableRow(lines[0]);
+	const separatorLine = lines[1];
+	if (!isValidSeparator(separatorLine, headers.length)) return {
+		ok: false,
+		error: "Invalid table separator row"
+	};
+	const rows = [];
+	for (let i = 2; i < lines.length; i++) {
+		const row = parseTableRow(lines[i]);
+		while (row.length < headers.length) row.push("");
+		if (row.length > headers.length) row.length = headers.length;
+		rows.push(row);
+	}
+	return {
+		ok: true,
+		headers,
+		rows
+	};
+}
+
 //#endregion
 //#region src/engine/parseFields.ts
 /**
@@ -233,6 +527,7 @@ function isValueEmpty(value) {
 		case "single_select": return value.selected === null;
 		case "multi_select": return value.selected.length === 0;
 		case "checkboxes": return Object.values(value.values).every((v) => v === "todo" || v === "unfilled");
+		case "table": return value.rows.length === 0;
 	}
 }
 /**
@@ -281,27 +576,86 @@ function getPriorityAttr(node) {
 	return DEFAULT_PRIORITY;
 }
 /**
-* Parse a string-field tag.
+* Parse and validate base field attributes (id, label, required).
+* Throws ParseError if id or label is missing.
 */
-function parseStringField(node) {
+function parseBaseFieldAttrs(node, kind) {
 	const id = getStringAttr(node, "id");
 	const label = getStringAttr(node, "label");
-	if (!id) throw new ParseError("string-field missing required 'id' attribute");
-	if (!label) throw new ParseError(`string-field '${id}' missing required 'label' attribute`);
-	const required = getBooleanAttr(node, "required") ?? false;
+	if (!id) throw new ParseError(`field kind="${kind}" missing required 'id' attribute`);
+	if (!label) throw new ParseError(`field '${id}' missing required 'label' attribute`);
+	return {
+		id,
+		label,
+		required: getBooleanAttr(node, "required") ?? false
+	};
+}
+/**
+* Get common field attributes (priority, role, validate, report).
+*/
+function getCommonFieldAttrs(node) {
+	return {
+		priority: getPriorityAttr(node),
+		role: getStringAttr(node, "role") ?? AGENT_ROLE,
+		validate: getValidateAttr(node),
+		report: getBooleanAttr(node, "report")
+	};
+}
+/**
+* Validate that placeholder/examples are not used on chooser fields.
+* Throws ParseError if either attribute is present.
+*/
+function validateNoPlaceholderExamples(node, fieldType, fieldId) {
+	const placeholder = getStringAttr(node, "placeholder");
+	const examples = getStringArrayAttr(node, "examples");
+	if (placeholder !== void 0) throw new ParseError(`${fieldType} '${fieldId}' has 'placeholder' attribute, but placeholder is only valid on text-entry fields (string, number, string-list, url, url-list)`);
+	if (examples !== void 0) throw new ParseError(`${fieldType} '${fieldId}' has 'examples' attribute, but examples is only valid on text-entry fields (string, number, string-list, url, url-list)`);
+}
+/**
+* Check if a string is a valid URL.
+*/
+function isValidUrl(str) {
+	try {
+		new URL(str);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Validate examples for number fields - all must parse as numbers.
+*/
+function validateNumberExamples(examples, fieldId) {
+	if (!examples) return;
+	for (const example of examples) {
+		const parsed = Number(example);
+		if (Number.isNaN(parsed)) throw new ParseError(`number-field '${fieldId}' has invalid example '${example}' - must be a valid number`);
+	}
+}
+/**
+* Validate examples for URL fields - all must be valid URLs.
+*/
+function validateUrlExamples(examples, fieldId) {
+	if (!examples) return;
+	for (const example of examples) if (!isValidUrl(example)) throw new ParseError(`url-field '${fieldId}' has invalid example '${example}' - must be a valid URL`);
+}
+/**
+* Parse a string-field tag.
+*/
+function parseStringField(node) {
+	const { id, label, required } = parseBaseFieldAttrs(node, "string");
 	const field = {
 		kind: "string",
 		id,
 		label,
 		required,
-		priority: getPriorityAttr(node),
-		role: getStringAttr(node, "role") ?? AGENT_ROLE,
+		...getCommonFieldAttrs(node),
 		multiline: getBooleanAttr(node, "multiline"),
 		pattern: getStringAttr(node, "pattern"),
 		minLength: getNumberAttr(node, "minLength"),
 		maxLength: getNumberAttr(node, "maxLength"),
-		validate: getValidateAttr(node),
-		report: getBooleanAttr(node, "report")
+		placeholder: getStringAttr(node, "placeholder"),
+		examples: getStringArrayAttr(node, "examples")
 	};
 	const sentinelResponse = tryParseSentinelResponse(node, id, required);
 	if (sentinelResponse) return {
@@ -321,23 +675,21 @@ function parseStringField(node) {
 * Parse a number-field tag.
 */
 function parseNumberField(node) {
-	const id = getStringAttr(node, "id");
-	const label = getStringAttr(node, "label");
-	if (!id) throw new ParseError("number-field missing required 'id' attribute");
-	if (!label) throw new ParseError(`number-field '${id}' missing required 'label' attribute`);
-	const required = getBooleanAttr(node, "required") ?? false;
+	const { id, label, required } = parseBaseFieldAttrs(node, "number");
+	const placeholder = getStringAttr(node, "placeholder");
+	const examples = getStringArrayAttr(node, "examples");
+	validateNumberExamples(examples, id);
 	const field = {
 		kind: "number",
 		id,
 		label,
 		required,
-		priority: getPriorityAttr(node),
-		role: getStringAttr(node, "role") ?? AGENT_ROLE,
+		...getCommonFieldAttrs(node),
 		min: getNumberAttr(node, "min"),
 		max: getNumberAttr(node, "max"),
 		integer: getBooleanAttr(node, "integer"),
-		validate: getValidateAttr(node),
-		report: getBooleanAttr(node, "report")
+		placeholder,
+		examples
 	};
 	const sentinelResponse = tryParseSentinelResponse(node, id, required);
 	if (sentinelResponse) return {
@@ -363,25 +715,20 @@ function parseNumberField(node) {
 * Parse a string-list tag.
 */
 function parseStringListField(node) {
-	const id = getStringAttr(node, "id");
-	const label = getStringAttr(node, "label");
-	if (!id) throw new ParseError("string-list missing required 'id' attribute");
-	if (!label) throw new ParseError(`string-list '${id}' missing required 'label' attribute`);
-	const required = getBooleanAttr(node, "required") ?? false;
+	const { id, label, required } = parseBaseFieldAttrs(node, "string_list");
 	const field = {
 		kind: "string_list",
 		id,
 		label,
 		required,
-		priority: getPriorityAttr(node),
-		role: getStringAttr(node, "role") ?? AGENT_ROLE,
+		...getCommonFieldAttrs(node),
 		minItems: getNumberAttr(node, "minItems"),
 		maxItems: getNumberAttr(node, "maxItems"),
 		itemMinLength: getNumberAttr(node, "itemMinLength"),
 		itemMaxLength: getNumberAttr(node, "itemMaxLength"),
 		uniqueItems: getBooleanAttr(node, "uniqueItems"),
-		validate: getValidateAttr(node),
-		report: getBooleanAttr(node, "report")
+		placeholder: getStringAttr(node, "placeholder"),
+		examples: getStringArrayAttr(node, "examples")
 	};
 	const sentinelResponse = tryParseSentinelResponse(node, id, required);
 	if (sentinelResponse) return {
@@ -435,22 +782,16 @@ function parseOptions(node, fieldId) {
 * Parse a single-select tag.
 */
 function parseSingleSelectField(node) {
-	const id = getStringAttr(node, "id");
-	const label = getStringAttr(node, "label");
-	if (!id) throw new ParseError("single-select missing required 'id' attribute");
-	if (!label) throw new ParseError(`single-select '${id}' missing required 'label' attribute`);
-	const required = getBooleanAttr(node, "required") ?? false;
+	const { id, label, required } = parseBaseFieldAttrs(node, "single_select");
+	validateNoPlaceholderExamples(node, "single-select", id);
 	const { options, selected } = parseOptions(node, id);
 	const field = {
 		kind: "single_select",
 		id,
 		label,
 		required,
-		priority: getPriorityAttr(node),
-		role: getStringAttr(node, "role") ?? AGENT_ROLE,
-		options,
-		validate: getValidateAttr(node),
-		report: getBooleanAttr(node, "report")
+		...getCommonFieldAttrs(node),
+		options
 	};
 	let selectedOption = null;
 	for (const [optId, state] of Object.entries(selected)) if (state === "done") {
@@ -469,24 +810,18 @@ function parseSingleSelectField(node) {
 * Parse a multi-select tag.
 */
 function parseMultiSelectField(node) {
-	const id = getStringAttr(node, "id");
-	const label = getStringAttr(node, "label");
-	if (!id) throw new ParseError("multi-select missing required 'id' attribute");
-	if (!label) throw new ParseError(`multi-select '${id}' missing required 'label' attribute`);
-	const required = getBooleanAttr(node, "required") ?? false;
+	const { id, label, required } = parseBaseFieldAttrs(node, "multi_select");
+	validateNoPlaceholderExamples(node, "multi-select", id);
 	const { options, selected } = parseOptions(node, id);
 	const field = {
 		kind: "multi_select",
 		id,
 		label,
 		required,
-		priority: getPriorityAttr(node),
-		role: getStringAttr(node, "role") ?? AGENT_ROLE,
+		...getCommonFieldAttrs(node),
 		options,
 		minSelections: getNumberAttr(node, "minSelections"),
-		maxSelections: getNumberAttr(node, "maxSelections"),
-		validate: getValidateAttr(node),
-		report: getBooleanAttr(node, "report")
+		maxSelections: getNumberAttr(node, "maxSelections")
 	};
 	const selectedOptions = [];
 	for (const [optId, state] of Object.entries(selected)) if (state === "done") selectedOptions.push(optId);
@@ -504,8 +839,9 @@ function parseMultiSelectField(node) {
 function parseCheckboxesField(node) {
 	const id = getStringAttr(node, "id");
 	const label = getStringAttr(node, "label");
-	if (!id) throw new ParseError("checkboxes missing required 'id' attribute");
-	if (!label) throw new ParseError(`checkboxes '${id}' missing required 'label' attribute`);
+	if (!id) throw new ParseError("field kind=\"checkboxes\" missing required 'id' attribute");
+	if (!label) throw new ParseError(`field '${id}' missing required 'label' attribute`);
+	validateNoPlaceholderExamples(node, "checkboxes", id);
 	const { options, selected } = parseOptions(node, id);
 	const checkboxModeStr = getStringAttr(node, "checkboxMode");
 	let checkboxMode = "multi";
@@ -524,14 +860,11 @@ function parseCheckboxesField(node) {
 		id,
 		label,
 		required,
-		priority: getPriorityAttr(node),
-		role: getStringAttr(node, "role") ?? AGENT_ROLE,
+		...getCommonFieldAttrs(node),
 		checkboxMode,
 		minDone: getNumberAttr(node, "minDone"),
 		options,
-		approvalMode,
-		validate: getValidateAttr(node),
-		report: getBooleanAttr(node, "report")
+		approvalMode
 	};
 	const values = {};
 	for (const opt of options) {
@@ -551,20 +884,18 @@ function parseCheckboxesField(node) {
 * Parse a url-field tag.
 */
 function parseUrlField(node) {
-	const id = getStringAttr(node, "id");
-	const label = getStringAttr(node, "label");
-	if (!id) throw new ParseError("url-field missing required 'id' attribute");
-	if (!label) throw new ParseError(`url-field '${id}' missing required 'label' attribute`);
-	const required = getBooleanAttr(node, "required") ?? false;
+	const { id, label, required } = parseBaseFieldAttrs(node, "url");
+	const placeholder = getStringAttr(node, "placeholder");
+	const examples = getStringArrayAttr(node, "examples");
+	validateUrlExamples(examples, id);
 	const field = {
 		kind: "url",
 		id,
 		label,
 		required,
-		priority: getPriorityAttr(node),
-		role: getStringAttr(node, "role") ?? AGENT_ROLE,
-		validate: getValidateAttr(node),
-		report: getBooleanAttr(node, "report")
+		...getCommonFieldAttrs(node),
+		placeholder,
+		examples
 	};
 	const sentinelResponse = tryParseSentinelResponse(node, id, required);
 	if (sentinelResponse) return {
@@ -584,23 +915,21 @@ function parseUrlField(node) {
 * Parse a url-list tag.
 */
 function parseUrlListField(node) {
-	const id = getStringAttr(node, "id");
-	const label = getStringAttr(node, "label");
-	if (!id) throw new ParseError("url-list missing required 'id' attribute");
-	if (!label) throw new ParseError(`url-list '${id}' missing required 'label' attribute`);
-	const required = getBooleanAttr(node, "required") ?? false;
+	const { id, label, required } = parseBaseFieldAttrs(node, "url_list");
+	const placeholder = getStringAttr(node, "placeholder");
+	const examples = getStringArrayAttr(node, "examples");
+	validateUrlExamples(examples, id);
 	const field = {
 		kind: "url_list",
 		id,
 		label,
 		required,
-		priority: getPriorityAttr(node),
-		role: getStringAttr(node, "role") ?? AGENT_ROLE,
+		...getCommonFieldAttrs(node),
 		minItems: getNumberAttr(node, "minItems"),
 		maxItems: getNumberAttr(node, "maxItems"),
 		uniqueItems: getBooleanAttr(node, "uniqueItems"),
-		validate: getValidateAttr(node),
-		report: getBooleanAttr(node, "report")
+		placeholder,
+		examples
 	};
 	const sentinelResponse = tryParseSentinelResponse(node, id, required);
 	if (sentinelResponse) return {
@@ -628,22 +957,15 @@ function parseUrlListField(node) {
 * Parse a date-field tag.
 */
 function parseDateField(node) {
-	const id = getStringAttr(node, "id");
-	const label = getStringAttr(node, "label");
-	if (!id) throw new ParseError("date-field missing required 'id' attribute");
-	if (!label) throw new ParseError(`date-field '${id}' missing required 'label' attribute`);
-	const required = getBooleanAttr(node, "required") ?? false;
+	const { id, label, required } = parseBaseFieldAttrs(node, "date");
 	const field = {
 		kind: "date",
 		id,
 		label,
 		required,
-		priority: getPriorityAttr(node),
-		role: getStringAttr(node, "role") ?? AGENT_ROLE,
+		...getCommonFieldAttrs(node),
 		min: getStringAttr(node, "min"),
-		max: getStringAttr(node, "max"),
-		validate: getValidateAttr(node),
-		report: getBooleanAttr(node, "report")
+		max: getStringAttr(node, "max")
 	};
 	const sentinelResponse = tryParseSentinelResponse(node, id, required);
 	if (sentinelResponse) return {
@@ -668,22 +990,15 @@ function parseDateField(node) {
 * Parse a year-field tag.
 */
 function parseYearField(node) {
-	const id = getStringAttr(node, "id");
-	const label = getStringAttr(node, "label");
-	if (!id) throw new ParseError("year-field missing required 'id' attribute");
-	if (!label) throw new ParseError(`year-field '${id}' missing required 'label' attribute`);
-	const required = getBooleanAttr(node, "required") ?? false;
+	const { id, label, required } = parseBaseFieldAttrs(node, "year");
 	const field = {
 		kind: "year",
 		id,
 		label,
 		required,
-		priority: getPriorityAttr(node),
-		role: getStringAttr(node, "role") ?? AGENT_ROLE,
+		...getCommonFieldAttrs(node),
 		min: getNumberAttr(node, "min"),
-		max: getNumberAttr(node, "max"),
-		validate: getValidateAttr(node),
-		report: getBooleanAttr(node, "report")
+		max: getNumberAttr(node, "max")
 	};
 	const sentinelResponse = tryParseSentinelResponse(node, id, required);
 	if (sentinelResponse) return {
@@ -706,23 +1021,145 @@ function parseYearField(node) {
 	};
 }
 /**
+* Validate column type string.
+*/
+function isValidColumnType(type) {
+	return type === "string" || type === "number" || type === "url" || type === "date" || type === "year";
+}
+/**
+* Parse column definitions from attributes.
+* columnIds is required. columnLabels is optional (backfilled from tableHeaderLabels if provided).
+*/
+function parseColumnsFromAttributes(node, fieldId, tableHeaderLabels) {
+	const columnIds = getStringArrayAttr(node, "columnIds");
+	const columnLabels = getStringArrayAttr(node, "columnLabels");
+	const columnTypesRaw = node.attributes?.columnTypes;
+	if (!columnIds || columnIds.length === 0) throw new ParseError(`table-field '${fieldId}' requires 'columnIds' attribute. Example: columnIds=["name", "title", "department"]`);
+	const seenIds = /* @__PURE__ */ new Set();
+	for (const id of columnIds) {
+		if (seenIds.has(id)) throw new ParseError(`table-field '${fieldId}' has duplicate column ID '${id}'`);
+		seenIds.add(id);
+	}
+	const columns = [];
+	for (let i = 0; i < columnIds.length; i++) {
+		const id = columnIds[i];
+		const label = columnLabels?.[i] ?? tableHeaderLabels?.[i] ?? id;
+		const typeSpec = columnTypesRaw?.[i];
+		let type = "string";
+		let required = false;
+		if (typeSpec !== void 0) {
+			if (typeof typeSpec === "string") {
+				if (!isValidColumnType(typeSpec)) throw new ParseError(`table-field '${fieldId}' has invalid column type '${String(typeSpec)}' for column '${id}'. Valid types: string, number, url, date, year`);
+				type = typeSpec;
+			} else if (typeof typeSpec === "object" && typeSpec !== null) {
+				const typeObj = typeSpec;
+				if (!isValidColumnType(typeObj.type)) throw new ParseError(`table-field '${fieldId}' has invalid column type '${String(typeObj.type)}' for column '${id}'. Valid types: string, number, url, date, year`);
+				type = typeObj.type;
+				required = typeObj.required ?? false;
+			}
+		}
+		columns.push({
+			id,
+			label,
+			type,
+			required
+		});
+	}
+	return columns;
+}
+/**
+* Parse a table-field tag.
+*
+* Column definitions come from attributes:
+* - columnIds (required): array of snake_case column identifiers
+* - columnLabels (optional): array of display labels (backfilled from table header row if omitted)
+* - columnTypes (optional): array of column types (defaults to all 'string')
+*
+* Table content is a raw markdown table inside the tag (NOT a value fence).
+*/
+function parseTableField(node) {
+	const { id, label, required } = parseBaseFieldAttrs(node, "table");
+	const sentinelResponse = tryParseSentinelResponse(node, id, required);
+	const tableContent = extractTableContent(node);
+	const columns = parseColumnsFromAttributes(node, id, extractTableHeaderLabels(tableContent));
+	const dataStartLine = 2;
+	const field = {
+		kind: "table",
+		id,
+		label,
+		required,
+		...getCommonFieldAttrs(node),
+		columns,
+		minRows: getNumberAttr(node, "minRows"),
+		maxRows: getNumberAttr(node, "maxRows")
+	};
+	if (sentinelResponse) return {
+		field,
+		response: sentinelResponse
+	};
+	if (tableContent === null || tableContent.trim() === "") return {
+		field,
+		response: parseFieldResponse(node, {
+			kind: "table",
+			rows: []
+		}, id, required)
+	};
+	const parseResult = parseMarkdownTable(tableContent, columns, dataStartLine);
+	if (!parseResult.ok) throw new ParseError(`table-field '${id}': ${parseResult.error}`);
+	return {
+		field,
+		response: parseFieldResponse(node, parseResult.value, id, required)
+	};
+}
+/**
+* Map legacy tag names to field kinds for error messages.
+*/
+const LEGACY_TAG_TO_KIND = {
+	"string-field": "string",
+	"number-field": "number",
+	"string-list": "string_list",
+	"single-select": "single_select",
+	"multi-select": "multi_select",
+	checkboxes: "checkboxes",
+	"url-field": "url",
+	"url-list": "url_list",
+	"date-field": "date",
+	"year-field": "year",
+	"table-field": "table"
+};
+/**
+* Parse a unified field tag: {% field kind="..." ... %}
+*/
+function parseUnifiedField(node) {
+	const kind = getStringAttr(node, "kind");
+	if (!kind) throw new ParseError("field tag missing required 'kind' attribute");
+	if (!FIELD_KINDS.includes(kind)) throw new ParseError(`field tag has invalid kind '${kind}'. Valid kinds: ${FIELD_KINDS.join(", ")}`);
+	switch (kind) {
+		case "string": return parseStringField(node);
+		case "number": return parseNumberField(node);
+		case "string_list": return parseStringListField(node);
+		case "single_select": return parseSingleSelectField(node);
+		case "multi_select": return parseMultiSelectField(node);
+		case "checkboxes": return parseCheckboxesField(node);
+		case "url": return parseUrlField(node);
+		case "url_list": return parseUrlListField(node);
+		case "date": return parseDateField(node);
+		case "year": return parseYearField(node);
+		case "table": return parseTableField(node);
+	}
+}
+/**
 * Parse a field tag and return field schema and response.
+* Accepts both unified field syntax {% field kind="..." %} and legacy tags.
 */
 function parseField(node) {
 	if (!isTagNode(node)) return null;
-	switch (node.tag) {
-		case "string-field": return parseStringField(node);
-		case "number-field": return parseNumberField(node);
-		case "string-list": return parseStringListField(node);
-		case "single-select": return parseSingleSelectField(node);
-		case "multi-select": return parseMultiSelectField(node);
-		case "checkboxes": return parseCheckboxesField(node);
-		case "url-field": return parseUrlField(node);
-		case "url-list": return parseUrlListField(node);
-		case "date-field": return parseDateField(node);
-		case "year-field": return parseYearField(node);
-		default: return null;
+	if (node.tag === "field") return parseUnifiedField(node);
+	if (node.tag) {
+		const kind = LEGACY_TAG_TO_KIND[node.tag];
+		if (kind !== void 0) throw new ParseError(`Legacy field tag '${node.tag}' is no longer supported. Use {% field kind="${kind}" %} instead`);
 	}
+	return null;
 }
 
 //#endregion
@@ -838,6 +1275,7 @@ function parseFieldGroup(node, responsesByFieldId, orderIndex, idIndex, parentId
 }
 /**
 * Parse a form tag.
+* Handles both explicit field-groups and fields placed directly under the form.
 */
 function parseFormTag(node, responsesByFieldId, orderIndex, idIndex) {
 	const id = getStringAttr(node, "id");
@@ -846,16 +1284,51 @@ function parseFormTag(node, responsesByFieldId, orderIndex, idIndex) {
 	if (idIndex.has(id)) throw new ParseError(`Duplicate ID '${id}'`);
 	idIndex.set(id, { nodeType: "form" });
 	const groups = [];
-	function findFieldGroups(child) {
+	const ungroupedFields = [];
+	function processContent(child) {
 		if (!child || typeof child !== "object") return;
 		if (isTagNode(child, "field-group")) {
 			const group = parseFieldGroup(child, responsesByFieldId, orderIndex, idIndex, id);
 			groups.push(group);
 			return;
 		}
-		if (child.children && Array.isArray(child.children)) for (const c of child.children) findFieldGroups(c);
+		const result = parseField(child);
+		if (result) {
+			if (idIndex.has(result.field.id)) throw new ParseError(`Duplicate ID '${result.field.id}'`);
+			idIndex.set(result.field.id, {
+				nodeType: "field",
+				parentId: id
+			});
+			ungroupedFields.push(result.field);
+			responsesByFieldId[result.field.id] = result.response;
+			orderIndex.push(result.field.id);
+			if ("options" in result.field) for (const opt of result.field.options) {
+				const qualifiedRef = `${result.field.id}.${opt.id}`;
+				if (idIndex.has(qualifiedRef)) throw new ParseError(`Duplicate option ref '${qualifiedRef}'`);
+				idIndex.set(qualifiedRef, {
+					nodeType: "option",
+					parentId: id,
+					fieldId: result.field.id
+				});
+			}
+			return;
+		}
+		if (child.children && Array.isArray(child.children)) for (const c of child.children) processContent(c);
+	}
+	if (node.children && Array.isArray(node.children)) for (const child of node.children) processContent(child);
+	if (ungroupedFields.length > 0) {
+		const implicitGroupId = `_default`;
+		if (idIndex.has(implicitGroupId)) throw new ParseError(`ID '${implicitGroupId}' is reserved for implicit field groups. Please use a different ID for your field or group.`);
+		idIndex.set(implicitGroupId, {
+			nodeType: "group",
+			parentId: id
+		});
+		groups.push({
+			id: implicitGroupId,
+			children: ungroupedFields,
+			implicit: true
+		});
 	}
-	if (node.children && Array.isArray(node.children)) for (const child of node.children) findFieldGroups(child);
 	return {
 		id,
 		title,
@@ -982,6 +1455,137 @@ function parseForm(markdown) {
 	};
 }
 
+//#endregion
+//#region src/engine/scopeRef.ts
+/**
+* Pattern for cell reference: fieldId[row].columnId
+* - fieldId: identifier (letters, digits, underscores, hyphens)
+* - row: non-negative integer
+* - columnId: identifier
+*/
+const CELL_REF_PATTERN = /^([a-zA-Z_][a-zA-Z0-9_-]*)\[(\d+)\]\.([a-zA-Z_][a-zA-Z0-9_-]*)$/;
+/**
+* Pattern for qualified reference: fieldId.qualifierId
+* - fieldId: identifier
+* - qualifierId: identifier (optionId or columnId)
+*/
+const QUALIFIED_REF_PATTERN = /^([a-zA-Z_][a-zA-Z0-9_-]*)\.([a-zA-Z_][a-zA-Z0-9_-]*)$/;
+/**
+* Pattern for simple field reference: fieldId
+* - fieldId: identifier
+*/
+const FIELD_REF_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
+/**
+* Parse a scope reference string into a structured format.
+*
+* @param refStr - The scope reference string to parse
+* @returns Parsed scope reference or error
+*
+* @example
+* parseScopeRef('myField')
+* // => { ok: true, ref: { type: 'field', fieldId: 'myField' } }
+*
+* parseScopeRef('myField.optA')
+* // => { ok: true, ref: { type: 'qualified', fieldId: 'myField', qualifierId: 'optA' } }
+*
+* parseScopeRef('myTable[2].name')
+* // => { ok: true, ref: { type: 'cell', fieldId: 'myTable', row: 2, columnId: 'name' } }
+*/
+function parseScopeRef(refStr) {
+	const trimmed = refStr.trim();
+	if (!trimmed) return {
+		ok: false,
+		error: "Empty scope reference"
+	};
+	const cellMatch = CELL_REF_PATTERN.exec(trimmed);
+	if (cellMatch) {
+		const fieldId = cellMatch[1];
+		const rowStr = cellMatch[2];
+		const columnId = cellMatch[3];
+		const row = parseInt(rowStr, 10);
+		if (row < 0 || !Number.isInteger(row)) return {
+			ok: false,
+			error: `Invalid row index: ${rowStr}`
+		};
+		return {
+			ok: true,
+			ref: {
+				type: "cell",
+				fieldId,
+				row,
+				columnId
+			}
+		};
+	}
+	const qualifiedMatch = QUALIFIED_REF_PATTERN.exec(trimmed);
+	if (qualifiedMatch) return {
+		ok: true,
+		ref: {
+			type: "qualified",
+			fieldId: qualifiedMatch[1],
+			qualifierId: qualifiedMatch[2]
+		}
+	};
+	if (FIELD_REF_PATTERN.test(trimmed)) return {
+		ok: true,
+		ref: {
+			type: "field",
+			fieldId: trimmed
+		}
+	};
+	return {
+		ok: false,
+		error: `Invalid scope reference format: ${refStr}`
+	};
+}
+/**
+* Serialize a parsed scope reference back to a string.
+*
+* @param ref - The parsed scope reference
+* @returns Serialized string
+*
+* @example
+* serializeScopeRef({ type: 'field', fieldId: 'myField' })
+* // => 'myField'
+*
+* serializeScopeRef({ type: 'qualified', fieldId: 'myField', qualifierId: 'optA' })
+* // => 'myField.optA'
+*
+* serializeScopeRef({ type: 'cell', fieldId: 'myTable', row: 2, columnId: 'name' })
+* // => 'myTable[2].name'
+*/
+function serializeScopeRef(ref) {
+	switch (ref.type) {
+		case "field": return ref.fieldId;
+		case "qualified": return `${ref.fieldId}.${ref.qualifierId}`;
+		case "cell": return `${ref.fieldId}[${ref.row}].${ref.columnId}`;
+	}
+}
+/**
+* Check if a scope reference is a cell reference.
+*/
+function isCellRef(ref) {
+	return ref.type === "cell";
+}
+/**
+* Check if a scope reference is a qualified reference.
+*/
+function isQualifiedRef(ref) {
+	return ref.type === "qualified";
+}
+/**
+* Check if a scope reference is a simple field reference.
+*/
+function isFieldRef(ref) {
+	return ref.type === "field";
+}
+/**
+* Extract the field ID from any scope reference.
+*/
+function getFieldId(ref) {
+	return ref.fieldId;
+}
+
 //#endregion
 //#region src/engine/valueCoercion.ts
 /**
@@ -1387,6 +1991,51 @@ function coerceToYear(fieldId, rawValue) {
 	};
 }
 /**
+* Coerce raw value to SetTablePatch.
+* Accepts:
+* - Array of row objects: [{ col1: value1, col2: value2 }, ...]
+* - Empty array: [] (valid for optional tables or minRows=0)
+*/
+function coerceToTable(fieldId, rawValue) {
+	if (rawValue === null) return {
+		ok: true,
+		patch: {
+			op: "set_table",
+			fieldId,
+			rows: []
+		}
+	};
+	if (!Array.isArray(rawValue)) return {
+		ok: false,
+		error: `Table value for field '${fieldId}' must be an array of rows, got ${typeof rawValue}`
+	};
+	if (rawValue.length === 0) return {
+		ok: true,
+		patch: {
+			op: "set_table",
+			fieldId,
+			rows: []
+		}
+	};
+	const rows = [];
+	for (let i = 0; i < rawValue.length; i++) {
+		const row = rawValue[i];
+		if (typeof row !== "object" || row === null || Array.isArray(row)) return {
+			ok: false,
+			error: `Row ${i} for table field '${fieldId}' must be an object, got ${Array.isArray(row) ? "array" : typeof row}`
+		};
+		rows.push(row);
+	}
+	return {
+		ok: true,
+		patch: {
+			op: "set_table",
+			fieldId,
+			rows
+		}
+	};
+}
+/**
 * Coerce a raw value to a Patch for a specific field.
 */
 function coerceToFieldPatch(form, fieldId, rawValue) {
@@ -1406,6 +2055,7 @@ function coerceToFieldPatch(form, fieldId, rawValue) {
 		case "url_list": return coerceToUrlList(fieldId, rawValue);
 		case "date": return coerceToDate(fieldId, rawValue);
 		case "year": return coerceToYear(fieldId, rawValue);
+		case "table": return coerceToTable(fieldId, rawValue);
 	}
 }
 /**
@@ -1758,6 +2408,9 @@ var MockAgent = class {
 			case "checkboxes": return true;
 			case "url": return value.value !== null && value.value !== "";
 			case "url_list": return value.items.length > 0;
+			case "date": return value.value !== null;
+			case "year": return value.value !== null;
+			case "table": return value.rows.length > 0;
 			default: return false;
 		}
 	}
@@ -1806,6 +2459,25 @@ var MockAgent = class {
 				fieldId,
 				items: value.items
 			};
+			case "date": return {
+				op: "set_date",
+				fieldId,
+				value: value.value
+			};
+			case "year": return {
+				op: "set_year",
+				fieldId,
+				value: value.value
+			};
+			case "table": return {
+				op: "set_table",
+				fieldId,
+				rows: value.rows.map((row) => {
+					const patchRow = {};
+					for (const [colId, cellResponse] of Object.entries(row)) patchRow[colId] = cellResponse.value ?? null;
+					return patchRow;
+				})
+			};
 			default: return null;
 		}
 	}
@@ -6886,12 +7558,12 @@ function getIssuesIntro(maxPatches) {
 /**
 * Instructions section for the context prompt.
 *
-* This explains the patch format for each field type.
+* This explains the patch format for each field kind.
 */
 const PATCH_FORMAT_INSTRUCTIONS = `# Instructions
 
 Use the generatePatches tool to submit patches for the fields above.
-Each patch should match the field type:
+Each patch should match the field kind:
 - string: { op: "set_string", fieldId: "...", value: "..." }
 - number: { op: "set_number", fieldId: "...", value: 123 }
 - string_list: { op: "set_string_list", fieldId: "...", items: ["...", "..."] }
@@ -6927,13 +7599,15 @@ var LiveAgent = class {
 	provider;
 	enableWebSearch;
 	webSearchTools = null;
+	additionalTools;
 	constructor(config) {
 		this.model = config.model;
 		this.maxStepsPerTurn = config.maxStepsPerTurn ?? 3;
 		this.systemPromptAddition = config.systemPromptAddition;
 		this.targetRole = config.targetRole ?? AGENT_ROLE;
 		this.provider = config.provider;
-		this.enableWebSearch = config.enableWebSearch ?? true;
+		this.enableWebSearch = config.enableWebSearch;
+		this.additionalTools = config.additionalTools ?? {};
 		if (this.enableWebSearch && this.provider) this.webSearchTools = loadWebSearchTools(this.provider);
 	}
 	/**
@@ -6943,7 +7617,8 @@ var LiveAgent = class {
 	getAvailableToolNames() {
 		const tools = ["generatePatches"];
 		if (this.webSearchTools) tools.push(...Object.keys(this.webSearchTools));
-		return tools;
+		tools.push(...Object.keys(this.additionalTools));
+		return [...new Set(tools)];
 	}
 	/**
 	* Generate patches using the LLM.
@@ -6963,7 +7638,8 @@ var LiveAgent = class {
 				description: GENERATE_PATCHES_TOOL_DESCRIPTION,
 				inputSchema: zodSchema(z.object({ patches: z.array(PatchSchema).max(maxPatches).describe("Array of patches. Each patch sets a value for one field.") }))
 			},
-			...this.webSearchTools
+			...this.webSearchTools,
+			...this.additionalTools
 		};
 		const result = await generateText({
 			model: this.model,
@@ -7389,7 +8065,8 @@ async function fillForm(options) {
 		systemPromptAddition: options.systemPromptAddition,
 		targetRole: targetRoles[0] ?? AGENT_ROLE,
 		provider,
-		enableWebSearch: true
+		enableWebSearch: options.enableWebSearch,
+		additionalTools: options.additionalTools
 	});
 	let turnCount = 0;
 	let stepResult = harness.step();
@@ -7488,7 +8165,9 @@ async function runResearch(form, options) {
 	const agent = createLiveAgent({
 		model,
 		provider,
-		targetRole: config.targetRoles?.[0] ?? AGENT_ROLE
+		targetRole: config.targetRoles?.[0] ?? AGENT_ROLE,
+		enableWebSearch: options.enableWebSearch,
+		additionalTools: options.additionalTools
 	});
 	const availableTools = agent.getAvailableToolNames();
 	let totalInputTokens = 0;
@@ -7580,8 +8259,9 @@ function validateResearchForm(form) {
 * This is the main library entry point that exports the core engine,
 * types, and utilities for working with .form.md files.
 */
-/** Markform version. */
-const VERSION = "0.1.0";
+const pkg = createRequire(import.meta.url)("../package.json");
+/** Markform version (read from package.json). */
+const VERSION = pkg.version;
 
 //#endregion
-export { findFieldById as _, resolveHarnessConfig as a, getProviderNames as c, MockAgent as d, createMockAgent as f, coerceToFieldPatch as g, coerceInputContext as h, runResearch as i, resolveModel as l, createHarness as m, isResearchForm as n, fillForm as o, FormHarness as p, validateResearchForm as r, getProviderInfo as s, VERSION as t, createLiveAgent as u, parseForm as v, ParseError as y };
+export { serializeScopeRef as C, parseRawTable as D, parseMarkdownTable as E, ParseError as O, parseScopeRef as S, parseCellValue as T, findFieldById as _, resolveHarnessConfig as a, isFieldRef as b, getProviderNames as c, MockAgent as d, createMockAgent as f, coerceToFieldPatch as g, coerceInputContext as h, runResearch as i, resolveModel as l, createHarness as m, isResearchForm as n, fillForm as o, FormHarness as p, validateResearchForm as r, getProviderInfo as s, VERSION as t, createLiveAgent as u, getFieldId as v, parseForm as w, isQualifiedRef as x, isCellRef as y };