markform 0.1.21 → 0.1.22

package/README.md

@@ -1,7 +1,7 @@
 # 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/21885509869)
+[![Coverage](https://raw.githubusercontent.com/jlevy/markform/main/badges/packages/markform/coverage-total.svg)](https://github.com/jlevy/markform/actions/runs/21885509869)
 [![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)
 
@@ -551,8 +551,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 +594,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-C7mO7VkZ.mjs";
 import { z } from "zod";
 
 //#region src/integrations/vercelAiSdkTools.ts

package/dist/{apply-CD-t7ovb.mjs → apply-C7mO7VkZ.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.22";
 /**
 * 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-C7mO7VkZ.mjs.map