markform 0.1.21 → 0.1.23

package/README.md

@@ -1,10 +1,12 @@
 # Markform
 
-[![CI](https://github.com/jlevy/markform/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/markform/actions/runs/21611973252)
-[![Coverage](https://raw.githubusercontent.com/jlevy/markform/main/badges/packages/markform/coverage-total.svg)](https://github.com/jlevy/markform/actions/runs/21611973252)
+[![CI](https://github.com/jlevy/markform/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/markform/actions/runs/21980795343)
+[![Coverage](https://raw.githubusercontent.com/jlevy/markform/main/badges/packages/markform/coverage-total.svg)](https://github.com/jlevy/markform/actions/runs/21980795343)
 [![npm version](https://img.shields.io/npm/v/markform)](https://www.npmjs.com/package/markform)
 [![X Follow](https://img.shields.io/twitter/follow/ojoshe)](https://x.com/ojoshe)
 
+### What if your Markdown docs had an agent-friendly semantic API?
+
 **Markform** is a text format for defining structured forms that humans can read,
 machines can parse, and agents can fill via tool calls.
 
@@ -13,12 +15,14 @@ Agents fill forms incrementally via patches.
 Fields are validated, so errors are caught early and can be corrected.
 Humans can review or intervene at any point.
 
-**Why forms?** For deep research or complex AI tasks, you need more than just prompts or
+### Why forms?
+
+For deep research or complex AI tasks, you need more than just prompts or
 flow: you need *structure*, which is precise control over agent output at every stage of
 a workflow. A well-designed form combines instructions, structured data, and validations
 in one place.
 
-**How it works:**
+### How it Works
 
 - A Markform document exposes a programmatic interface: users fill fields via CLI or web
   UI, agents fill via tool calls ([Vercel AI SDK](https://github.com/vercel/ai)
@@ -33,9 +37,25 @@ in one place.
   [precise specification](https://github.com/jlevy/markform/blob/main/docs/markform-spec.md).
   Export Markform syntax to JSON, YAML, JSON Schema, or plain Markdown reports.
 
-Markform syntax is a good source format: token-efficient text you can read, diff, and
-version control. Structure is defined with HTML comment tags (`<!-- field -->`) that
-render invisibly on GitHub, so forms look like regular Markdown.
+- Optionally, the whole thing is wrapped in a harness where large forms can be filled
+  concurrently by any LLM in a structured agentic loop.
+
+### Useful details
+
+- Markform syntax is a good source format: it is **token-efficient text** you can read, diff, and
+  version control and it is **ideal for context engineering** because it combines
+  document context, data schema, and memory (data filled so far).
+
+- Structure is defined with HTML comment tags (`<!-- field -->`) that
+  render invisibly on GitHub, so **forms look like regular Markdown**. (Jinja-style
+  tag syntax also works if you prefer.)
+
+- Optionally, **a fill record** of the form-filling process is kept, so you can see
+  and debug exactly how forms are filled by agents, tool usage, LLM call time, etc.
+
+- The CLI has a built-in web renderer, **`markform serve`**, for easy viewing and debugging
+  of forms (including a form web UI, the form schema, and a waterfall-style overview of the
+  fill record, including performance details, which is useful for large, concurrently filled forms).
 
 ## Simple Example: Research a Movie
 
@@ -364,16 +384,16 @@ flowchart LR
     subgraph SPEC["<b>MARKFORM SPEC</b>"]
         direction TB
 
-        subgraph L1["<b>LAYER 1: SYNTAX</b><br/>Markdoc tag syntax and frontmatter (form, group, string-field, checkboxes, etc.)"]
+        subgraph L1["<b>LAYER 1: SYNTAX</b><br/>Markdoc tag syntax<br/>and frontmatter (form,<br/>group, string-field, <br/>checkboxes, etc.)"]
         end
 
-        subgraph L2["<b>LAYER 2: FORM DATA MODEL</b><br/>Schema definitions for forms, fields, values (in Zod but mappable to JSON Schema or Pydantic)"]
+        subgraph L2["<b>LAYER 2: FORM DATA MODEL</b><br/>Schema definitions<br/>for forms, fields, values"]
         end
 
-        subgraph L3["<b>LAYER 3: VALIDATION & FORM FILLING</b><br/>Rules for filling forms via patches, field ids, required field semantics, validation hooks"]
+        subgraph L3["<b>LAYER 3: VALIDATION <br/>AND PATCHES</b><br/>Rules for filling forms<br/>via patches, required<br/>field semantics, validation"]
         end
 
-        subgraph L4["<b>LAYER 4: TOOL API & INTERFACES</b><br/>Abstract API for agents and humans (TypeScript and AI SDK integration)"]
+        subgraph L4["<b>LAYER 4: TOOL API <br/>AND INTERFACES</b><br/>Abstract form-filling<br/>loop, concurrency<br/>model, tool layer"]
         end
 
         L4 --> L3 --> L2 --> L1
@@ -382,19 +402,19 @@ flowchart LR
     subgraph IMPL["<b>THIS IMPLEMENTATION</b>"]
         direction TB
 
-        subgraph CLI["<b>`markform` CLI</b><br/>Command-line interface to all features"]
+        subgraph CLI["<b>`markform` CLI</b><br/>Command-line interface<br/>to all features"]
         end
 
-        subgraph AGENT["<b>AGENT TOOL INTERFACE</b><br/>Tool API library using AI SDK tools"]
+        subgraph AGENT["<b>AGENT TOOL INTERFACE</b><br/>Tool API library><br/>(AI SDK tools)"]
         end
 
-        subgraph HARNESS["<b>EXECUTION HARNESS</b><br/>Step-by-step form-filling agentic loop"]
+        subgraph HARNESS["<b>EXECUTION HARNESS</b><br/>Concurrent form-filling<br/>agentic loop<br/>(AI SDK)"]
         end
 
-        subgraph ENGINE["<b>CORE TYPESCRIPT APIS</b><br/>Markdoc parser, serializer, patch application, validation (uses jiti for TypeScript rules)"]
+        subgraph ENGINE["<b>CORE TYPESCRIPT APIS</b><br/>Markdoc parser, serializer,<br/>patch application,<br/>validation (jiti for rules)"]
         end
 
-        subgraph TEST["<b>TESTING FRAMEWORK</b><br/>Golden session testing with .session.yaml transcripts"]
+        subgraph TEST["<b>TESTING FRAMEWORK</b><br/>Golden session testing<br/>(.session.yaml transcripts)"]
         end
 
         CLI --> ENGINE
@@ -551,8 +571,8 @@ If unsure, try `gpt-5-mini` first as it’s fast and supports web search.
 
 ## Programmatic Usage
 
-Markform exports a parsing engine and AI SDK integration for use in your own
-applications.
+Markform exports a parsing engine, rendering functions, and AI SDK integration for use in
+your own applications.
 
 ### Basic Parsing
 
@@ -594,6 +614,34 @@ See the
 [API documentation](https://github.com/jlevy/markform/blob/main/docs/markform-apis.md)
 for options like parallel execution, callbacks, and checkpointing.
 
+### Rendering API
+
+Import from the `markform/render` subpath to render forms and fill records as HTML
+fragments — the same output as `markform serve`, without pulling in CLI/server
+dependencies:
+
+```typescript
+import {
+  renderViewContent,
+  renderFillRecordContent,
+  FILL_RECORD_STYLES,
+  FILL_RECORD_SCRIPTS,
+} from "markform/render";
+
+// Render a filled form as read-only HTML
+const formHtml = renderViewContent(parsedForm);
+
+// Render a fill record dashboard
+const dashboardHtml = renderFillRecordContent(fillRecord);
+```
+
+Also exports `renderSourceContent`, `renderMarkdownContent`, `renderYamlContent`,
+`renderJsonContent`, `escapeHtml`, `formatDuration`, and `formatTokens`.
+
+See the
+[API documentation](https://github.com/jlevy/markform/blob/main/docs/markform-apis.md#rendering-api)
+for full details.
+
 ### AI SDK Integration
 
 Markform provides tools compatible with the [Vercel AI SDK](https://sdk.vercel.ai/):

package/dist/ai-sdk.d.mts

@@ -1,5 +1,5 @@
 
-import { At as ParsedForm, Nt as PatchSchema, U as FieldResponse, Y as FormSchema, at as InspectResult, et as Id, hr as ValidatorRegistry, jt as Patch, r as ApplyResult } from "./coreTypes-BQrWf_Wt.mjs";
+import { At as ParsedForm, Nt as PatchSchema, U as FieldResponse, Y as FormSchema, at as InspectResult, et as Id, hr as ValidatorRegistry, jt as Patch, r as ApplyResult } from "./coreTypes-BlsJkU1w.mjs";
 import { z } from "zod";
 
 //#region src/integrations/toolTypes.d.ts

package/dist/ai-sdk.mjs

@@ -1,6 +1,6 @@
 
 import { R as PatchSchema } from "./coreTypes-CTLr-NGd.mjs";
-import { d as serializeForm, i as inspect, t as applyPatches } from "./apply-CD-t7ovb.mjs";
+import { d as serializeForm, i as inspect, t as applyPatches } from "./apply-KzQztrDV.mjs";
 import { z } from "zod";
 
 //#region src/integrations/vercelAiSdkTools.ts

package/dist/{apply-CD-t7ovb.mjs → apply-KzQztrDV.mjs}

@@ -1,8 +1,9 @@
 
+import { n as formatUrlAsMarkdownLink } from "./urlFormat-lls7CsEP.mjs";
 import YAML from "yaml";
 
 //#region src/errors.ts
-const VERSION = "0.1.21";
+const VERSION = "0.1.23";
 /**
 * Base error class for all markform errors.
 * Consumers can catch this to handle any markform error.
@@ -94,12 +95,15 @@ var MarkformLlmError = class extends MarkformError {
 	statusCode;
 	/** Whether this error is retryable */
 	retryable;
+	/** Raw response body from the API (for debugging) */
+	responseBody;
 	constructor(message, context) {
 		super(message, { cause: context.cause });
 		this.provider = context.provider;
 		this.model = context.model;
 		this.statusCode = context.statusCode;
 		this.retryable = context.retryable ?? false;
+		this.responseBody = context.responseBody;
 	}
 };
 /**
@@ -173,6 +177,86 @@ function isRetryableError(error) {
 	return isLlmError(error) && error.retryable;
 }
 /**
+* Check if an error looks like a Vercel AI SDK APICallError.
+* These errors have statusCode, responseBody, and isRetryable properties.
+*/
+function isApiCallError(error) {
+	return error instanceof Error && ("statusCode" in error || "responseBody" in error || "isRetryable" in error);
+}
+/**
+* Generate troubleshooting hints based on error status and message.
+*/
+function getTroubleshootingHints(statusCode, message, provider, model) {
+	const hints = [];
+	const lowerMessage = message.toLowerCase();
+	if (statusCode === 404 || lowerMessage.includes("not found")) {
+		hints.push(`Check if model "${model}" exists and is available for the ${provider} API`);
+		hints.push("Verify the model ID is spelled correctly (check provider documentation)");
+		hints.push("Some models require specific API tier access or waitlist approval");
+	} else if (statusCode === 403 || lowerMessage.includes("forbidden")) {
+		hints.push(`Your API key may not have permission to use model "${model}"`);
+		hints.push("Check that your API key has the required access tier/plan");
+		hints.push("Some preview models require explicit opt-in via provider dashboard");
+	} else if (statusCode === 401 || lowerMessage.includes("unauthorized") || lowerMessage.includes("invalid api key")) {
+		hints.push("Verify your API key is correct and not expired");
+		hints.push(`Check that the correct env var is set (e.g., ${provider.toUpperCase()}_API_KEY)`);
+	} else if (statusCode === 429 || lowerMessage.includes("rate limit")) {
+		hints.push("You have hit the rate limit - wait a moment and retry");
+		hints.push("Consider using a model with higher rate limits or upgrading your plan");
+	} else if (statusCode === 500 || statusCode === 502 || statusCode === 503) {
+		hints.push("The API provider is experiencing issues - retry in a few minutes");
+		hints.push("Check the provider status page for any ongoing incidents");
+	}
+	if (hints.length === 0) {
+		hints.push("Check your API key and model availability");
+		hints.push(`Run "markform models" to see available models for ${provider}`);
+	}
+	return hints;
+}
+/**
+* Wrap an API error with rich context for debugging.
+*
+* Extracts details from Vercel AI SDK APICallError and creates a MarkformLlmError
+* with actionable information including model ID, status code, response body, and
+* troubleshooting hints.
+*
+* @param error - The original error from the API call
+* @param provider - The LLM provider name (e.g., 'anthropic', 'openai')
+* @param model - The model identifier that was requested
+* @returns A MarkformLlmError with rich context
+*/
+function wrapApiError(error, provider, model) {
+	let statusCode;
+	let responseBody;
+	let retryable = false;
+	let originalMessage = "Unknown error";
+	if (isApiCallError(error)) {
+		statusCode = error.statusCode;
+		responseBody = error.responseBody;
+		retryable = error.isRetryable ?? false;
+		originalMessage = error.message;
+	} else if (error instanceof Error) originalMessage = error.message;
+	else originalMessage = String(error);
+	const parts = [];
+	parts.push(`API call failed for model "${provider}/${model}"`);
+	if (statusCode !== void 0) parts.push(`HTTP ${statusCode}`);
+	parts.push(originalMessage);
+	if (responseBody) {
+		const truncated = responseBody.length > 200 ? responseBody.slice(0, 200) + "..." : responseBody;
+		parts.push(`Response: ${truncated}`);
+	}
+	const hints = getTroubleshootingHints(statusCode, originalMessage, provider, model);
+	if (hints.length > 0) parts.push(`\n\nTroubleshooting:\n  - ${hints.join("\n  - ")}`);
+	return new MarkformLlmError(parts.join(": "), {
+		provider,
+		model,
+		statusCode,
+		retryable,
+		responseBody,
+		cause: error instanceof Error ? error : void 0
+	});
+}
+/**
 * Alias for MarkformParseError.
 * @deprecated Use MarkformParseError instead. ParseError will be removed in a future version.
 */
@@ -707,6 +791,7 @@ function extractTableContent(node) {
 	function extractTextFromNode(n) {
 		if (!n || typeof n !== "object") return "";
 		if (n.type === "text" && typeof n.attributes?.content === "string") return n.attributes.content;
+		if (n.type === "link" && typeof n.attributes?.href === "string") return `[${n.children?.map(extractTextFromNode).join("") ?? ""}](${n.attributes.href})`;
 		if (n.children && Array.isArray(n.children)) return n.children.map(extractTextFromNode).join("");
 		return "";
 	}
@@ -1357,74 +1442,6 @@ function priorityKeyComparator(priorityKeys) {
 	});
 }
 
-//#endregion
-//#region src/utils/urlFormat.ts
-/**
-* Create a friendly abbreviated display name for a URL.
-* - Drops "www." prefix from domain
-* - Adds first portion of path (up to maxPathChars) if present
-* - Adds ellipsis (…) if path is truncated
-*
-* @param url - The URL to abbreviate
-* @param maxPathChars - Maximum characters to include from the path (default: 12)
-* @returns Friendly abbreviated URL (e.g., "example.com/docs/api…")
-*/
-function friendlyUrlAbbrev(url, maxPathChars = 12) {
-	try {
-		const parsed = new URL(url);
-		let hostname = parsed.hostname;
-		if (hostname.startsWith("www.")) hostname = hostname.slice(4);
-		const path = parsed.pathname.slice(1);
-		if (!path) return hostname;
-		if (path.length <= maxPathChars) return `${hostname}/${path}`;
-		return `${hostname}/${path.slice(0, maxPathChars)}…`;
-	} catch {
-		let result = url;
-		result = result.replace(/^https?:\/\//, "");
-		result = result.replace(/^www\./, "");
-		const maxLen = 30;
-		if (result.length > maxLen) return result.slice(0, maxLen) + "…";
-		return result;
-	}
-}
-/**
-* Format a URL as a markdown link with a friendly abbreviated display text.
-* The full URL is preserved as the link target.
-*
-* @param url - The URL to format
-* @returns Markdown link in format [friendly-abbrev](url)
-*/
-function formatUrlAsMarkdownLink(url) {
-	return `[${friendlyUrlAbbrev(url)}](${url})`;
-}
-/**
-* Format bare URLs in text as HTML links with abbreviated display text.
-* Also handles markdown-style links [text](url) for consistency.
-*
-* Processing order:
-* 1. Escape all HTML to prevent XSS
-* 2. Convert markdown links [text](url) to <a> tags
-* 3. Convert bare URLs (not already in links) to <a> tags with abbreviated display
-*
-* @param text - The raw text containing URLs (will be HTML-escaped)
-* @param escapeHtml - Function to escape HTML entities
-* @returns HTML-safe text with URLs converted to <a> tags
-*/
-function formatBareUrlsAsHtmlLinks(text, escapeHtml) {
-	let result = escapeHtml(text);
-	result = result.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match, linkText, url) => {
-		const cleanUrl = url.replace(/&amp;/g, "&");
-		return `<a href="${escapeHtml(cleanUrl)}" target="_blank" class="url-link" data-url="${escapeHtml(cleanUrl)}">${linkText}</a>`;
-	});
-	result = result.replace(/(?<!href="|data-url="|">)(?:https?:\/\/|www\.)[^\s<>"]+(?<![.,;:!?'")])/g, (url) => {
-		const cleanUrl = url.replace(/&amp;/g, "&");
-		const fullUrl = cleanUrl.startsWith("www.") ? `https://${cleanUrl}` : cleanUrl;
-		const display = friendlyUrlAbbrev(fullUrl);
-		return `<a href="${escapeHtml(fullUrl)}" target="_blank" class="url-link" data-url="${escapeHtml(fullUrl)}">${escapeHtml(display)}</a>`;
-	});
-	return result;
-}
-
 //#endregion
 //#region src/engine/serialize.ts
 /**
@@ -1976,14 +1993,13 @@ function serializeYearField(field, response) {
 }
 /**
 * Serialize a cell value for table output.
-* URL-typed columns are formatted as markdown links with domain as display text.
+* Values are serialized as-is; HTML rendering handles display formatting.
 */
-function serializeCellValue(cell, columnType) {
+function serializeCellValue(cell, _columnType) {
 	if (cell.state === "skipped") return cell.reason ? `%SKIP:${cell.reason}%` : "%SKIP%";
 	if (cell.state === "aborted") return cell.reason ? `%ABORT:${cell.reason}%` : "%ABORT%";
 	if (cell.value === void 0 || cell.value === null) return "";
 	if (typeof cell.value === "number") return String(cell.value);
-	if (columnType === "url") return formatUrlAsMarkdownLink(cell.value);
 	return cell.value;
 }
 /**
@@ -2383,6 +2399,16 @@ function serializeFieldRaw(field, responses) {
 	const lines = [];
 	lines.push(`**${field.label}:**`);
 	lines.push("");
+	if (response?.state === "skipped") {
+		const text = response.reason ? `_(skipped: ${response.reason})_` : "_(skipped)_";
+		lines.push(text);
+		return lines.join("\n");
+	}
+	if (response?.state === "aborted") {
+		const text = response.reason ? `_(aborted: ${response.reason})_` : "_(aborted)_";
+		lines.push(text);
+		return lines.join("\n");
+	}
 	const value = response?.state === "answered" ? response.value : void 0;
 	switch (field.kind) {
 		case "string": {
@@ -4330,5 +4356,5 @@ function applyPatches(form, patches) {
 }
 
 //#endregion
-export { transformHarnessConfigToTs as $, parseOptionText as A, DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN as B, extractTableContent as C, getStringAttr as D, getStringArrayAttr as E, DEFAULT_MAX_PATCHES_PER_TURN as F, REPORT_EXTENSION as G, DEFAULT_ROLES as H, DEFAULT_MAX_STEPS_PER_TURN as I, deriveFillRecordPath as J, USER_ROLE as K, DEFAULT_MAX_TURNS as L, DEFAULT_FORMS_DIR as M, DEFAULT_MAX_ISSUES_PER_TURN as N, getValidateAttr as O, DEFAULT_MAX_PARALLEL_AGENTS as P, parseRolesFlag as Q, DEFAULT_PORT as R, extractOptionItems as S, getNumberAttr as T, DEFAULT_ROLE_INSTRUCTIONS as U, DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN as V, MAX_FORMS_IN_MENU as W, deriveSchemaPath as X, deriveReportPath as Y, detectFileType as Z, preprocessCommentSyntax as _, isMarkformError as _t, validate as a, parseModelIdForDisplay as at, CHECKBOX_MARKERS as b, isRetryableError as bt, computeProgressSummary as c, MarkformError as ct, serializeForm as d, MarkformPatchError as dt, SUGGESTED_LLMS as et, serializeRawMarkdown as f, MarkformValidationError as ft, detectSyntaxStyle as g, isLlmError as gt, friendlyUrlAbbrev as h, isConfigError as ht, inspect as i, hasWebSearchSupport as it, AGENT_ROLE as j, isTagNode as k, computeStructureSummary as l, MarkformLlmError as lt, formatBareUrlsAsHtmlLinks as m, isAbortError as mt, getAllFields as n, formatSuggestedLlms as nt, computeAllSummaries as o, MarkformAbortError as ot, serializeReport as p, ParseError as pt, deriveExportPath as q, getFieldsForRoles as r, getWebSearchConfig as rt, computeFormState as s, MarkformConfigError as st, applyPatches as t, WEB_SEARCH_CONFIG as tt, isFormComplete as u, MarkformParseError as ut, validateSyntaxConsistency as v, isParseError as vt, getBooleanAttr as w, extractFenceValue as x, isValidationError as xt, tryParseSentinelResponse as y, isPatchError as yt, DEFAULT_PRIORITY as z };
-//# sourceMappingURL=apply-CD-t7ovb.mjs.map
+export { WEB_SEARCH_CONFIG as $, DEFAULT_FORMS_DIR as A, DEFAULT_ROLES as B, getNumberAttr as C, isTagNode as D, getValidateAttr as E, DEFAULT_MAX_TURNS as F, deriveExportPath as G, MAX_FORMS_IN_MENU as H, DEFAULT_PORT as I, deriveSchemaPath as J, deriveFillRecordPath as K, DEFAULT_PRIORITY as L, DEFAULT_MAX_PARALLEL_AGENTS as M, DEFAULT_MAX_PATCHES_PER_TURN as N, parseOptionText as O, DEFAULT_MAX_STEPS_PER_TURN as P, SUGGESTED_LLMS as Q, DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN as R, getBooleanAttr as S, getStringAttr as T, REPORT_EXTENSION as U, DEFAULT_ROLE_INSTRUCTIONS as V, USER_ROLE as W, parseRolesFlag as X, detectFileType as Y, transformHarnessConfigToTs as Z, tryParseSentinelResponse as _, isPatchError as _t, validate as a, MarkformConfigError as at, extractOptionItems as b, wrapApiError as bt, computeProgressSummary as c, MarkformParseError as ct, serializeForm as d, ParseError as dt, formatSuggestedLlms as et, serializeRawMarkdown as f, isAbortError as ft, validateSyntaxConsistency as g, isParseError as gt, preprocessCommentSyntax as h, isMarkformError as ht, inspect as i, MarkformAbortError as it, DEFAULT_MAX_ISSUES_PER_TURN as j, AGENT_ROLE as k, computeStructureSummary as l, MarkformPatchError as lt, detectSyntaxStyle as m, isLlmError as mt, getAllFields as n, hasWebSearchSupport as nt, computeAllSummaries as o, MarkformError as ot, serializeReport as p, isConfigError as pt, deriveReportPath as q, getFieldsForRoles as r, parseModelIdForDisplay as rt, computeFormState as s, MarkformLlmError as st, applyPatches as t, getWebSearchConfig as tt, isFormComplete as u, MarkformValidationError as ut, CHECKBOX_MARKERS as v, isRetryableError as vt, getStringArrayAttr as w, extractTableContent as x, extractFenceValue as y, isValidationError as yt, DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN as z };
+//# sourceMappingURL=apply-KzQztrDV.mjs.map