@quillmark/wasm 0.55.0 → 0.58.2-rc.4

package/README.md

@@ -1,177 +1,74 @@
 # Quillmark WASM
 
-WebAssembly bindings for the Quillmark markdown rendering engine.
+WebAssembly bindings for Quillmark.
 
 Maintained by [TTQ](https://tonguetoquill.com).
 
 ## Overview
 
-This crate provides WASM bindings for Quillmark, enabling use in web browsers, Node.js, and other JavaScript/TypeScript environments. All data exchange uses JSON serialization, and JavaScript is responsible for all I/O operations.
+Use Quillmark in browsers/Node.js with explicit in-memory trees (`Map<string, Uint8Array>` / `Record<string, Uint8Array>`).
 
-## Building
-
-### For Web (bundler)
+## Build
 
 ```bash
 wasm-pack build --target bundler --scope quillmark
 ```
 
-### For Node.js
-
-```bash
-wasm-pack build --target nodejs --scope quillmark
-```
-
-### All targets
-
-```bash
-bash scripts/build-wasm.sh
-```
-
-## Testing
-
-Minimal smoke tests validate the core WASM functionality:
+## Test
 
 ```bash
-# Build WASM module first
 bash scripts/build-wasm.sh
-
-# Run tests
-cd quillmark-wasm
+cd crates/bindings/wasm
 npm install
 npm test
 ```
 
-The test suite includes:
-- `basic.test.js` - Core WASM API functionality tests
-- `resolve.test.js` - Quill version resolution against the WASM engine
-
 ## Usage
 
-```typescript
-import { Quillmark } from '@quillmark-test/wasm';
+```ts
+import { Document, Quillmark } from "@quillmark-test/wasm";
+
+const engine = new Quillmark();
+const quill = engine.quill(tree);
 
-// Step 1: Parse markdown
 const markdown = `---
-title: My Document
-author: Alice
 QUILL: my_quill
+title: My Document
 ---
 
-# Hello World
-
-This is my document.
-`;
+# Hello`;
 
-const parsed = Quillmark.parseMarkdown(markdown);
-
-// Step 2: Create engine and register Quill
-const engine = new Quillmark();
-
-const quillJson = {
-  files: {
-    'Quill.yaml': {
-      contents: 'Quill:\n  name: my_quill\n  version: "1.0"\n  backend: typst\n  plate_file: plate.typ\n  description: My template\n'
-    },
-    'plate.typ': { 
-      contents: '= {{ title }}\n\n{{ body | Content }}' 
-    }
-  }
-};
-
-engine.registerQuill(quillJson);
-
-// Step 3: Get Quill info (optional)
-const info = engine.getQuillInfo('my-quill');
-console.log('Supported formats:', info.supportedFormats);
-console.log('Schema YAML:', info.schema);
-
-// Step 4: Render
-const result = engine.render(parsed, { format: 'pdf' });
-
-// Access the PDF bytes
-const pdfArtifact = result.artifacts[0];
-const blob = new Blob([pdfArtifact.bytes], { type: pdfArtifact.mimeType });
-const url = URL.createObjectURL(blob);
-window.open(url);
+const parsed = Document.fromMarkdown(markdown);
+const result = quill.render(parsed, { format: "pdf" });
 ```
 
 ## API
 
-The `Quillmark` class provides the following methods:
-
-### Workflow Methods
-
-The main workflow for rendering documents:
-
-- `static parseMarkdown(markdown)` - Parse markdown into a ParsedDocument (Step 1)
-- `registerQuill(quillJson)` - Register a Quill template bundle from JSON (Step 2)
-- `render(parsedDoc, options)` - Render a ParsedDocument to final artifacts using the required `QUILL` reference parsed from the document (Step 4)
-
-### Utility Methods
-
-Additional methods for managing the engine and debugging:
-
-- `new Quillmark()` - Create a new engine instance
-- `renderQuill(RenderOptions, markdown)` - Load markdown and map it onto an internally fetched Quill, resolving to `RenderResult` including output format, the artifact byte slice buffer, and time to render
-- `processPlate(quillRef, markdown)` - Debug helper that processes markdown through the template engine and returns the intermediate template source code (e.g., Typst, LaTeX) without compiling to final artifacts. Useful for inspecting template output during development.
-- `fetchQuillInfo(quillRef)` - Fetches metadata and schema about an available Quill from the configured registry without loading the full filesystem or rendering context.
-- `listQuills()` - List all registered Quill names
-- `unregisterQuill(name)` - Unregister a Quill to free memory
+### `new Quillmark()`
+Create engine.
 
-### Render Options
+### `engine.quill(tree)`
+Build + validate + attach backend. Returns a render-ready `Quill`.
 
-```typescript
-type RenderOptions = {
-  format?: 'pdf' | 'svg' | 'txt'
-  assets?: Record<string, Uint8Array | number[]> 
-}
-```
-
-### ParsedDocument
-
-Returned by `parseMarkdown()`:
-
-```typescript
-{
-  fields: object,  // YAML frontmatter fields
-  quillRef: string  // Quill reference from required QUILL field
-}
-```
-
-### QuillInfo
-
-Returned by `getQuillInfo()`:
-
-```typescript
-{
-  name: string,
-  backend: string,  // e.g., "typst"
-  metadata: object,  // Quill metadata from Quill.yaml
-  example?: string,  // Example markdown (if available)
-  schema: string,  // Public schema YAML text
-  supportedFormats: Array<'pdf' | 'svg' | 'txt'>  // Formats this backend supports
-}
-```
+### `Document.fromMarkdown(markdown)`
+Parse markdown to parsed document.
 
-## WASM Boundary Types
+### `doc.toMarkdown()`
+Emit canonical Quillmark Markdown. Type-fidelity round-trip safe:
+`Document.fromMarkdown(doc.toMarkdown())` returns a document equal to `doc`.
 
-Data crossing the JavaScript ↔ WebAssembly boundary:
+### `quill.render(parsed, opts?)`
+Render with a pre-parsed `Document`.
 
-- **Enums**: Serialized as lowercase strings (`"pdf"`, `"svg"`, `"txt"`)
-- **Binary data**: `Vec<u8>` maps to `Uint8Array`
-- **Collections**: `Vec<T>` maps to JS arrays; object types use plain JS objects `{}`
-- **Option**: `Option<T>` maps to `T | null`
-- **Errors**: Thrown as exceptions using `SerializableDiagnostic` from core, containing structured diagnostic information (severity, message, location, hint, source chain)
+### `quill.open(parsed)` + `session.render(opts?)`
+Open once, render all or selected pages (`opts.pages`).
 
-## Design Principles
+## Notes
 
-- **JSON-Only Data Exchange**: All structured data uses `serde-wasm-bindgen`
-- **JavaScript Handles I/O**: WASM layer only handles rendering
-- **Synchronous Operations**: Rendering is fast enough (<100ms typically)
-- **No File System Abstractions**: JavaScript prepares all data
-- **Error Delegation**: Error handling delegated to core types (`SerializableDiagnostic`) for consistency with Python bindings
+- Parsed markdown requires top-level `QUILL` in frontmatter.
+- QUILL mismatch during `quill.render(parsed)` is a warning (`quill::ref_mismatch`), not an error.
+- Output schema APIs are no longer engine-level in WASM.
 
 ## License
 
-Licensed under the Apache License, Version 2.0.
+Apache-2.0

package/bundler/wasm.d.ts

@@ -6,7 +6,11 @@ export interface Artifact {
     mimeType: string;
 }
 
-export interface CompileOptions {}
+export interface Card {
+    tag: string;
+    fields: Record<string, unknown>;
+    body: string;
+}
 
 export interface Diagnostic {
     severity: Severity;
@@ -23,31 +27,10 @@ export interface Location {
     column: number;
 }
 
-export interface ParsedDocument {
-    fields: Record<string, any>;
-    quillRef: string;
-}
-
-export interface QuillInfo {
-    name: string;
-    backend: string;
-    metadata: Record<string, any>;
-    example?: string;
-    schema: string;
-    defaults: Record<string, any>;
-    examples: Record<string, any[]>;
-    supportedFormats: OutputFormat[];
-}
-
 export interface RenderOptions {
     format?: OutputFormat;
-    assets?: Record<string, Uint8Array | number[]>;
-    ppi?: number;
-}
-
-export interface RenderPagesOptions {
-    format: OutputFormat;
     ppi?: number;
+    pages?: number[];
 }
 
 export interface RenderResult {
@@ -62,108 +45,220 @@ export type OutputFormat = "pdf" | "svg" | "txt" | "png";
 export type Severity = "error" | "warning" | "note";
 
 
-export class CompiledDocument {
+/**
+ * Typed in-memory Quillmark document.
+ *
+ * Created via `Document.fromMarkdown(markdown)`. Exposes:
+ * - `quillRef` (string)
+ * - `frontmatter` (JS object/Record)
+ * - `body` (string)
+ * - `cards` (array of Card objects)
+ * - `warnings` (array of Diagnostic objects)
+ *
+ * `toMarkdown()` emits canonical Quillmark Markdown that round-trips back to
+ * an equal `Document` by value and by type.
+ */
+export class Document {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Render selected pages. `pages = null/undefined` renders all pages.
+     * Parse markdown into a typed Document.
+     *
+     * Returns the document with any parse-time warnings accessible via `.warnings`.
+     * Throws on parse errors.
      */
-    renderPages(pages: Uint32Array | null | undefined, opts: RenderPagesOptions): RenderResult;
+    static fromMarkdown(markdown: string): Document;
     /**
-     * Number of pages in this compiled document.
+     * Insert a card at the given index.
+     *
+     * `index` must be in `0..=cards.length`. Out-of-range throws an `Error`.
+     *
+     * Mutators never modify `warnings`.
      */
-    readonly pageCount: number;
-}
-
-/**
- * Quillmark WASM Engine
- *
- * Create once, register Quills, render markdown. That's it.
- */
-export class Quillmark {
-    free(): void;
-    [Symbol.dispose](): void;
+    insertCard(index: number, card: any): void;
     /**
-     * Compile a parsed document into an opaque compiled document handle.
+     * Move the card at `from` to position `to`.
+     *
+     * `from == to` is a no-op. Both indices must be in `0..cards.length`.
+     * Out-of-range throws an `Error`.
+     *
+     * Mutators never modify `warnings`.
      */
-    compile(parsed: ParsedDocument, opts?: CompileOptions | null): CompiledDocument;
+    moveCard(from: number, to: number): void;
     /**
-     * Compile markdown to JSON data without rendering artifacts.
+     * Append a card to the end of the card list.
+     *
+     * `card` must be a JS object with a `tag` string field and optional
+     * `fields` (object) and `body` (string).
      *
-     * This exposes the intermediate data structure that would be passed to the backend.
-     * Useful for debugging and validation.
+     * Throws an `Error` if `card.tag` is not a valid tag name.
+     *
+     * Mutators never modify `warnings`.
      */
-    compileData(markdown: string): any;
+    pushCard(card: any): void;
     /**
-     * Perform a dry run validation without backend compilation.
-     *
-     * Executes parsing, schema validation, and template composition to
-     * surface input errors quickly. Returns successfully on valid input,
-     * or throws an error with diagnostic payload on failure.
+     * Remove the card at `index` and return it, or `undefined` if out of range.
      *
-     * The quill name is read from the markdown's required QUILL tag.
+     * Mutators never modify `warnings`.
+     */
+    removeCard(index: number): any;
+    /**
+     * Remove a frontmatter field, returning the removed value or `undefined`.
      *
-     * This is useful for fast feedback loops in LLM-driven document generation.
+     * Mutators never modify `warnings`.
      */
-    dryRun(markdown: string): void;
+    removeField(name: string): any;
     /**
-     * Get shallow information about a registered Quill
+     * Replace the global Markdown body.
      *
-     * This returns metadata, backend info, field schemas, and supported formats
-     * that consumers need to configure render options for the next step.
+     * Mutators never modify `warnings`.
      */
-    getQuillInfo(name: string): QuillInfo;
+    replaceBody(body: string): void;
     /**
-     * Get the public YAML schema contract for a registered quill.
+     * Set a frontmatter field.
+     *
+     * Throws an `Error` whose message includes the `EditError` variant name and
+     * details if `name` is reserved (`BODY`, `CARDS`, `QUILL`, `CARD`) or does
+     * not match `[a-z_][a-z0-9_]*`.
+     *
+     * Mutators never modify `warnings`.
      */
-    getQuillSchema(name: string): string;
+    setField(name: string, value: any): void;
     /**
-     * List registered Quills with their exact versions
+     * Replace the QUILL reference string.
+     *
+     * Throws if `ref_str` is not a valid `QuillReference`.
      *
-     * Returns strings in the format "name@version" (e.g. "resume-template@2.1.0")
+     * Mutators never modify `warnings`.
      */
-    listQuills(): string[];
+    setQuillRef(ref_str: string): void;
     /**
-     * JavaScript constructor: `new Quillmark()`
+     * Emit canonical Quillmark Markdown.
+     *
+     * Returns the document serialised as a Quillmark Markdown string.
+     * The output is type-fidelity round-trip safe: re-parsing the result
+     * produces a `Document` equal to `self` by value and by type.
      */
-    constructor();
+    toMarkdown(): string;
     /**
-     * Parse markdown into a ParsedDocument
+     * Replace the body of the card at `index`.
+     *
+     * Throws if `index` is out of range.
      *
-     * This is the first step in the workflow. The returned ParsedDocument contains
-     * the parsed YAML frontmatter fields and the quill_ref from QUILL.
+     * Mutators never modify `warnings`.
      */
-    static parseMarkdown(markdown: string): ParsedDocument;
+    updateCardBody(index: number, body: string): void;
     /**
-     * Register a Quill template bundle
+     * Update a field on the card at `index`.
      *
-     * Accepts either a JSON string or a JsValue object representing the Quill file tree.
-     * Validation happens automatically on registration.
+     * Convenience method: equivalent to `doc.card_mut(index)?.set_field(name, value)`.
+     *
+     * Throws if `index` is out of range, `name` is reserved or invalid, or
+     * `value` cannot be serialized.
+     *
+     * Mutators never modify `warnings`.
      */
-    registerQuill(quill_json: any): QuillInfo;
+    updateCardField(index: number, name: string, value: any): void;
     /**
-     * Render a ParsedDocument to final artifacts (PDF, SVG, TXT)
+     * Global Markdown body between frontmatter and the first card.
+     *
+     * Trailing newlines are stripped — those are structural separators in
+     * the Markdown wire format, not content the consumer wrote.
      *
-     * Uses the Quill specified in the ParsedDocument's quill_ref field.
+     * Empty string when no body is present.
+     */
+    readonly body: string;
+    /**
+     * Ordered list of card blocks as JS objects with `tag`, `fields`, and `body`.
      */
-    render(parsed: ParsedDocument, opts: RenderOptions): RenderResult;
+    readonly cards: any;
     /**
-     * Resolve a Quill reference to a registered Quill, or null if not available
+     * Typed YAML frontmatter fields as a JS object (no QUILL, BODY, or CARDS keys).
+     */
+    readonly frontmatter: any;
+    /**
+     * The QUILL reference string (e.g. `"usaf_memo@0.1"`).
+     */
+    readonly quillRef: string;
+    /**
+     * Non-fatal parse-time warnings as a JS array of Diagnostic objects.
+     */
+    readonly warnings: any;
+}
+
+/**
+ * Opaque, shareable Quill handle.
+ */
+export class Quill {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Open an iterative render session for page-selective rendering.
+     */
+    open(doc: Document): RenderSession;
+    /**
+     * Project a document through this quill's schema.
+     *
+     * Returns a plain JS object (not a class) that is immediately
+     * `JSON.stringify`-able. The shape mirrors [`FormProjection`]:
+     *
+     * ```json
+     * {
+     *   "main":  { "schema": {...}, "values": { "field": {...} } },
+     *   "cards": [ ... ],
+     *   "diagnostics": [ ... ]
+     * }
+     * ```
      *
-     * Accepts a quill reference string like "resume-template", "resume-template@2",
-     * or "resume-template@2.1.0". Returns QuillInfo if the engine can resolve it
-     * locally, or null if an external fetch is needed.
+     * **Snapshot semantics.** This is a read-only snapshot of the document
+     * at call time. Subsequent edits to `doc` require calling `projectForm`
+     * again.
+     *
+     * [`FormProjection`]: quillmark::form::FormProjection
+     */
+    projectForm(doc: Document): any;
+    /**
+     * Render a document to final artifacts.
+     */
+    render(doc: Document, opts?: RenderOptions | null): RenderResult;
+    /**
+     * The resolved backend identifier (e.g. `"typst"`).
      */
-    resolveQuill(quill_ref: string): any;
+    readonly backendId: string;
+}
+
+/**
+ * Quillmark WASM Engine
+ */
+export class Quillmark {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * JavaScript constructor: `new Quillmark()`
+     */
+    constructor();
     /**
-     * Unregister a Quill by name or specific version
+     * Load a quill from a file tree and attach the appropriate backend.
      *
-     * If a base name is provided (e.g., "my-quill"), all versions of that quill are freed.
-     * If a versioned name is provided (e.g., "my-quill@2.1.0"), only that specific version is freed.
-     * Returns true if something was unregistered, false if not found.
+     * The tree must be a `Map<string, Uint8Array>`.
      */
-    unregisterQuill(name_or_ref: string): boolean;
+    quill(tree: any): Quill;
+}
+
+export class RenderSession {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Render all or selected pages from this session.
+     */
+    render(opts?: RenderOptions | null): RenderResult;
+    /**
+     * Number of pages in this render session.
+     */
+    readonly pageCount: number;
 }
 
 /**

package/bundler/wasm.js

@@ -1,9 +1,9 @@
 /* @ts-self-types="./wasm.d.ts" */
-
 import * as wasm from "./wasm_bg.wasm";
 import { __wbg_set_wasm } from "./wasm_bg.js";
+
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    CompiledDocument, Quillmark, init
+    Document, Quill, Quillmark, RenderSession, init
 } from "./wasm_bg.js";