@quillmark/wasm 0.54.1 → 0.58.0

package/README.md

@@ -1,177 +1,70 @@
 # 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
+## Test
 
 ```bash
 bash scripts/build-wasm.sh
-```
-
-## Testing
-
-Minimal smoke tests validate the core WASM functionality:
-
-```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 { ParsedDocument, 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.
-`;
-
-const parsed = Quillmark.parseMarkdown(markdown);
+# Hello`;
 
-// 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 = ParsedDocument.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
-
-### Render Options
+### `new Quillmark()`
+Create engine.
 
-```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
-}
-```
+### `engine.quill(tree)`
+Build + validate + attach backend. Returns a render-ready `Quill`.
 
-## WASM Boundary Types
+### `ParsedDocument.fromMarkdown(markdown)`
+Parse markdown to parsed document.
 
-Data crossing the JavaScript ↔ WebAssembly boundary:
+### `quill.render(parsed, opts?)`
+Render with a pre-parsed `ParsedDocument`.
 
-- **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,8 +6,6 @@ export interface Artifact {
     mimeType: string;
 }
 
-export interface CompileOptions {}
-
 export interface Diagnostic {
     severity: Severity;
     code?: string;
@@ -28,26 +26,11 @@ export interface ParsedDocument {
     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,53 @@ export type OutputFormat = "pdf" | "svg" | "txt" | "png";
 export type Severity = "error" | "warning" | "note";
 
 
-export class CompiledDocument {
+/**
+ * Opaque, shareable Quill handle.
+ */
+export class Quill {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Render selected pages. `pages = null/undefined` renders all pages.
+     * Open an iterative render session for page-selective rendering.
      */
-    renderPages(pages: Uint32Array | null | undefined, opts: RenderPagesOptions): RenderResult;
+    open(parsed: ParsedDocument): RenderSession;
     /**
-     * Number of pages in this compiled document.
+     * Render a document to final artifacts.
      */
-    readonly pageCount: number;
+    render(parsed: ParsedDocument, opts: RenderOptions): RenderResult;
 }
 
 /**
  * Quillmark WASM Engine
- *
- * Create once, register Quills, render markdown. That's it.
  */
 export class Quillmark {
     free(): void;
     [Symbol.dispose](): void;
-    /**
-     * Compile a parsed document into an opaque compiled document handle.
-     */
-    compile(parsed: ParsedDocument, opts?: CompileOptions | null): CompiledDocument;
-    /**
-     * Compile markdown to JSON data without rendering artifacts.
-     *
-     * This exposes the intermediate data structure that would be passed to the backend.
-     * Useful for debugging and validation.
-     */
-    compileData(markdown: string): any;
-    /**
-     * 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.
-     *
-     * The quill name is read from the markdown's required QUILL tag.
-     *
-     * This is useful for fast feedback loops in LLM-driven document generation.
-     */
-    dryRun(markdown: string): void;
-    /**
-     * Get shallow information about a registered Quill
-     *
-     * This returns metadata, backend info, field schemas, and supported formats
-     * that consumers need to configure render options for the next step.
-     */
-    getQuillInfo(name: string): QuillInfo;
-    /**
-     * Get the public YAML schema contract for a registered quill.
-     */
-    getQuillSchema(name: string): string;
-    /**
-     * List registered Quills with their exact versions
-     *
-     * Returns strings in the format "name@version" (e.g. "resume-template@2.1.0")
-     */
-    listQuills(): string[];
     /**
      * JavaScript constructor: `new Quillmark()`
      */
     constructor();
     /**
-     * Parse markdown into a ParsedDocument
-     *
-     * This is the first step in the workflow. The returned ParsedDocument contains
-     * the parsed YAML frontmatter fields and the quill_ref from QUILL.
-     */
-    static parseMarkdown(markdown: string): ParsedDocument;
-    /**
-     * Register a Quill template bundle
-     *
-     * Accepts either a JSON string or a JsValue object representing the Quill file tree.
-     * Validation happens automatically on registration.
-     */
-    registerQuill(quill_json: any): QuillInfo;
-    /**
-     * Render a ParsedDocument to final artifacts (PDF, SVG, TXT)
+     * Load a quill from a file tree and attach the appropriate backend.
      *
-     * Uses the Quill specified in the ParsedDocument's quill_ref field.
+     * The tree must be a `Map<string, Uint8Array>`.
      */
-    render(parsed: ParsedDocument, opts: RenderOptions): RenderResult;
+    quill(tree: any): Quill;
+}
+
+export class RenderSession {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
     /**
-     * Resolve a Quill reference to a registered Quill, or null if not available
-     *
-     * 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.
+     * Render all or selected pages from this session.
      */
-    resolveQuill(quill_ref: string): any;
+    render(opts: RenderOptions): RenderResult;
     /**
-     * Unregister a Quill by name or specific version
-     *
-     * 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.
+     * Number of pages in this render session.
      */
-    unregisterQuill(name_or_ref: string): boolean;
+    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
+    ParsedDocument, Quill, Quillmark, RenderSession, init
 } from "./wasm_bg.js";