markform 0.1.3 → 0.1.4

package/README.md

@@ -63,39 +63,53 @@ markform:
 ---
 {% form id="movie_research_minimal" title="Movie Research (Minimal)" %}
 
-<!-- The first field group is filled in by the user (role="user"): -->
+## Movie Research Example
 
 {% field-group id="movie_input" title="Movie Identification" %}
 
-{% string-field id="movie" label="Movie" role="user" required=true minLength=1 maxLength=300 %}{% /string-field %}
+What movie do you want to research? \[*This field is filled in by the user (`role="user"`).*\]
+
+{% field kind="string" id="movie" label="Movie" role="user" required=true minLength=1 maxLength=300 %}{% /field %}
 {% instructions ref="movie" %}Enter the movie title (add year or details for disambiguation).{% /instructions %}
 
 {% /field-group %}
 
-<!-- Everything else is filled in by the agent (role="agent"): -->
+## About the Movie
 
 {% field-group id="about_the_movie" title="About the Movie" %}
 
-{% string-field id="full_title" label="Full Title" role="agent" required=true %}{% /string-field %}
-{% instructions ref="full_title" %}Official title including subtitle if any.{% /instructions %}
+**Title:**
+
+{% field kind="string" id="full_title" label="Full Title" role="agent" required=true %}{% /field %}
+{% instructions ref="full_title" %}Official title, including subtitle if any.{% /instructions %}
+
+**Release year:**
 
-{% number-field id="year" label="Release Year" role="agent" required=true min=1888 max=2030 %}{% /number-field %}
+{% field kind="number" id="year" label="Release Year" role="agent" required=true min=1888 max=2030 %}{% /field %}
 
-{% url-field id="imdb_url" label="IMDB URL" role="agent" required=true %}{% /url-field %}
+**IMDB:**
 
-{% single-select id="mpaa_rating" label="MPAA Rating" role="agent" %}
+{% field kind="url" id="imdb_url" label="IMDB URL" role="agent" required=true %}{% /field %}
+
+**MPAA rating:**
+
+{% field kind="single_select" id="mpaa_rating" label="MPAA Rating" role="agent" %}
 - [ ] G {% #g %}
 - [ ] PG {% #pg %}
 - [ ] PG-13 {% #pg_13 %}
 - [ ] R {% #r %}
 - [ ] NC-17 {% #nc_17 %}
 - [ ] NR/Unrated {% #nr %}
-{% /single-select %}
+{% /field %}
+
+**IMDB rating:**
 
-{% number-field id="imdb_rating" label="IMDB Rating" role="agent" min=1.0 max=10.0 %}{% /number-field %}
+{% field kind="number" id="imdb_rating" label="IMDB Rating" role="agent" min=1.0 max=10.0 %}{% /field %}
 {% instructions ref="imdb_rating" %}IMDB user rating (1.0-10.0 scale).{% /instructions %}
 
-{% string-field id="logline" label="One-Line Summary" role="agent" maxLength=300 %}{% /string-field %}
+**Summary:**
+
+{% field kind="string" id="logline" label="One-Line Summary" role="agent" maxLength=300 %}{% /field %}
 {% instructions ref="logline" %}Brief plot summary in 1-2 sentences, no spoilers.{% /instructions %}
 
 {% /field-group %}
@@ -103,18 +117,48 @@ markform:
 {% /form %}
 ```
 
-This is the minimal movie research form.
+Run the `npx markform examples` and select the `Movie Research (Minimal)` example and
+view the report:
+
+```markdown
+# Movie Research (Minimal)
+
+## Movie Identification
+
+Movie:
+shawshank redemption
+
+## About the Movie
+
+Full Title:
+The Shawshank Redemption
+
+Release Year:
+1994
+
+IMDB URL:
+https://www.imdb.com/title/tt0111161/
+
+MPAA Rating:
+R
+
+IMDB Rating:
+9.3
+
+One-Line Summary:
+Convicted banker Andy Dufresne is sent to Shawshank State Penitentiary, where he forms an unexpected friendship with inmate Red while holding onto hope and striving to maintain his dignity in a corrupt prison system.
+```
+
 See the
 [examples/](https://github.com/jlevy/markform/tree/main/packages/markform/examples)
-directory for forms with more fields, including multiple rating sources (IMDB, Rotten
-Tomatoes, Metacritic) and comprehensive analysis.
+directory for a few more complex form examples.
 
 **Key concepts:**
 
 - **Roles**: Define who fills what (`user` for humans, `agent` for AI)
 
-- **Field types**: `string-field`, `number-field`, `url-field`, `string-list`,
-  `single-select`, `multi-select`, `checkboxes`
+- **Field kinds**: `string-field`, `number-field`, `date-field`, `year-field`,
+  `url-field`, `url-list`, `string-list`, `single-select`, `multi-select`, `checkboxes`
 
 - **Validation**: `required`, `min/max`, `minLength/maxLength`, `pattern`
 
@@ -137,7 +181,7 @@ The package includes example forms in
   \- Comprehensive analysis with streaming, box office
 
 - [`simple/simple.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/simple/simple.form.md)
-  \- Basic form demonstrating all field types
+  \- Basic form demonstrating all field kinds
 
 - [`earnings-analysis/earnings-analysis.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/earnings-analysis/earnings-analysis.form.md)
   \- Financial analysis form
@@ -250,9 +294,12 @@ markform serve my-form.form.md
 # Quick reference for writing forms (agent-friendly)
 markform docs
 
-# Full specification (SPEC.md)
+# Full specification
 markform spec
 
+# TypeScript and AI SDK API documentation
+markform apis
+
 # This README
 markform readme
 
@@ -391,7 +438,8 @@ But it’s been useful for me already.
 
 It’s all written by LLMs but using a strongly spec-driven process, using rules from
 [Speculate](https://github.com/jlevy/speculate).
-See [the spec](SPEC.md) and the architecture docs and specs in [docs/](docs/).
+See [the spec](docs/markform-spec.md) and the architecture docs and specs in
+[docs/](docs/).
 
 ### What are the goals of Markform?
 
@@ -446,12 +494,13 @@ Not really. The closest alternatives are:
   human-friendly UI. But these do not have a human-friendly text format for use by
   agents as well as humans.
 
-| Approach | Human-readable | Agent-editable | Custom validations |
-| --- | :---: | :---: | :---: |
-| Plain Markdown | ✅ | ⚠️ fragile | ❌ |
-| JSON Schema | ❌ | ✅ | ✅ |
-| PDF Forms, SaaS tools | ⚠️ | ❌ | ⚠️ |
-| **Markform** | ✅ | ✅ | ✅ |
+| Approach | Has GUI | Human-readable text format | Agent-editable | APIs and validation rules |
+| --- | :---: | :---: | :---: | :---: |
+| Plain Markdown | ☑️ existing tools | ✅ | ⚠️ fragile | ❌ |
+| JSON with schema | ☑️ existing tools | ⚠️ hey it’s JSON | ✅ | ✅ |
+| SaaS tools (Typeform, Docusign, PDF forms) | ✅ | ⚠️ rarely | ⚠️ if they add it | ⚠️ if they add it |
+| Excel/Google Sheets | ✅ | ❌ .xlsx | ⚠️ with tools | ✅ |
+| **Markform** | ☑️ existing tools | ✅ | ✅ | ✅ |
 
 ### What are example use cases?
 
@@ -496,11 +545,15 @@ Or see [markdoc/language-server](https://github.com/markdoc/language-server).
 ## Documentation
 
 - **[Quick
-  Reference](https://github.com/jlevy/markform/blob/main/packages/markform/DOCS.md)**
+  Reference](https://github.com/jlevy/markform/blob/main/docs/markform-reference.md)**
   (or run `markform docs`) - Concise syntax reference (agent-friendly)
 
-- **[Markform Spec](https://github.com/jlevy/markform/blob/main/SPEC.md)** (or run
-  `markform spec`) - Complete syntax and semantics
+- **[Markform Spec](https://github.com/jlevy/markform/blob/main/docs/markform-spec.md)**
+  (or run `markform spec`) - Complete syntax and semantics
+
+- **[API
+  Documentation](https://github.com/jlevy/markform/blob/main/docs/markform-apis.md)**
+  (or run `markform apis`) - TypeScript and AI SDK APIs
 
 - **[Design
   Doc](https://github.com/jlevy/markform/blob/main/docs/project/architecture/current/arch-markform-design.md)**

package/dist/ai-sdk.d.mts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { H as Id, L as FormSchema, Sn as ValidatorRegistry, _t as ParsedForm, j as FieldResponse, q as InspectResult, r as ApplyResult, vt as Patch, yt as PatchSchema } from "./coreTypes-BXhhz9Iq.mjs";
+import { Dt as PatchSchema, Et as Patch, G as FormSchema, Tt as ParsedForm, X as Id, ar as ValidatorRegistry, r as ApplyResult, tt as InspectResult, z as FieldResponse } from "./coreTypes-cbNTYAcb.mjs";
 import { z } from "zod";
 
 //#region src/integrations/toolTypes.d.ts
@@ -62,7 +62,7 @@ interface MarkformToolSet {
   markform_get_markdown?: MarkformTool<Record<string, never>, GetMarkdownToolResult>;
 }
 //#endregion
-//#region src/integrations/ai-sdk.d.ts
+//#region src/integrations/vercelAiSdkTools.d.ts
 /**
  * Session store for managing form state during AI interactions.
  *

package/dist/ai-sdk.mjs

@@ -1,8 +1,8 @@
-import { N as PatchSchema } from "./coreTypes-Dful87E0.mjs";
-import { r as inspect, t as applyPatches, u as serialize } from "./apply-00UmzDKL.mjs";
+import { L as PatchSchema } from "./coreTypes-pyctKRgc.mjs";
+import { r as inspect, t as applyPatches, u as serialize } from "./apply-C54EMAJ1.mjs";
 import { z } from "zod";
 
-//#region src/integrations/ai-sdk.ts
+//#region src/integrations/vercelAiSdkTools.ts
 /**
 * AI SDK Integration for Markform.
 *
@@ -63,7 +63,7 @@ const InspectInputSchema = z.object({}).describe("No input parameters required.
 /**
 * Input schema for markform_apply tool.
 */
-const ApplyInputSchema = z.object({ patches: z.array(PatchSchema).min(1).max(20).describe("Array of patches to apply to the form. Each patch sets or clears a field value. Operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, set_checkboxes, clear_field. Example: [{ \"op\": \"set_string\", \"fieldId\": \"name\", \"value\": \"Alice\" }]") }).describe("Apply patches to update form field values.");
+const ApplyInputSchema = z.object({ patches: z.array(PatchSchema).min(1).max(20).describe("Array of patches to apply to the form. Each patch sets or clears a field value. Operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, set_checkboxes, set_url, set_url_list, set_date, set_year, set_table, clear_field, skip_field, abort_field. Example: [{ \"op\": \"set_string\", \"fieldId\": \"name\", \"value\": \"Alice\" }]") }).describe("Apply patches to update form field values.");
 /**
 * Input schema for markform_export tool (no parameters).
 */
@@ -115,7 +115,7 @@ function createMarkformTools(options) {
 			}
 		},
 		markform_apply: {
-			description: "Apply patches to update form field values. Use this after inspecting the form to set values for fields that need to be filled. Patches are applied as a transaction - all succeed or all fail. Returns the updated form state and any remaining issues. Patch operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, set_checkboxes, clear_field.",
+			description: "Apply patches to update form field values. Use this after inspecting the form to set values for fields that need to be filled. Patches are applied as a transaction - all succeed or all fail. Returns the updated form state and any remaining issues. Patch operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, set_checkboxes, set_url, set_url_list, set_date, set_year, set_table, clear_field, skip_field, abort_field.",
 			inputSchema: ApplyInputSchema,
 			execute: ({ patches }) => {
 				const form = sessionStore.getForm();