@quillmark/quiver 0.12.0 → 0.15.0

package/README.md

@@ -29,6 +29,24 @@ This keeps the author flow to a single command (`npm publish` or `git tag`)
 and puts the deployment-topology decision where it belongs: with the
 consumer.
 
+## The render model
+
+`@quillmark/quiver` produces quills; `@quillmark/wasm` renders them.
+
+- `quiver.getQuill(ref)` returns a core `Quill` — engine-free, portable data,
+  good for schema inspection, validation, blueprint access, and seeding. It is
+  the **only** way to obtain a quill from a quiver.
+- `const engine = new Engine()` (from the `@quillmark/wasm` root) renders it:
+  `await engine.render(quill, doc, opts?)`. The Engine routes on
+  `quill.backendId`, lazily loads that backend, clones the quill and document
+  into the backend's WASM memory, renders, and frees the clones — so a core
+  `Quill` passes straight to `engine.render` with no boundary-crossing step.
+
+`Engine.render`, `open`, `supportedFormats`, and `supportsCanvas` are all
+**async** — always `await` them. The canonical `Quill`/`Document`/`Engine`
+types are not re-exported from `@quillmark/quiver`; import them straight from
+the `@quillmark/wasm` peer dependency, which is the single source of truth.
+
 ## Authoring a quiver
 
 Lay out the source per the spec, then publish to npm (or push a git tag):
@@ -50,6 +68,14 @@ consumer's build. The harness uses `node:test` (built into Node 18+); no extra
 test-runner dependency required. If you prefer vitest/jest/mocha, write a
 12-line loop against the main API instead.
 
+```ts
+// quiver.test.ts — run with: node --test
+import { Engine } from "@quillmark/wasm";
+import { runQuiverTests } from "@quillmark/quiver/testing";
+
+runQuiverTests(import.meta.url, new Engine());
+```
+
 ## Manual validation (rendering samples)
 
 The CI harness proves every quill _compiles_; it does not produce output a
@@ -58,19 +84,19 @@ human can look at. To eyeball real renders, run the
 
 ```ts
 // scripts/preview.ts — run with: node --experimental-strip-types scripts/preview.ts
-import { Quillmark, Document } from "@quillmark/wasm";
+import { Engine } from "@quillmark/wasm";
 import { renderQuiverSamples } from "@quillmark/quiver/preview";
 
 await renderQuiverSamples(import.meta.url, {
-  engine: new Quillmark(),
-  Document,
+  engine: new Engine(),
 });
 // → writes ./preview/<name>@<version>.<fmt> + index.html
 ```
 
-It renders every quill's illustrative example document (`quill.example` — a
-fully filled-out, always-renderable sample; the blueprint itself carries
-`<must-fill>` sentinels and is not directly renderable), writes the artifacts
+It renders every quill's illustrative example document (seeded via
+`quill.seedDocument()` — a fully filled-out, always-renderable sample; the
+blueprint itself carries `<must-fill>` sentinels and is not directly
+renderable), writes the artifacts
 to `outDir` (default `preview/`), and emits an `index.html`
 gallery. A `.gitignore` is written into `outDir` so the generated artifacts
 are never accidentally committed. A quill that throws is recorded as failed —
@@ -82,8 +108,7 @@ quill name or canonical ref):
 
 ```ts
 await renderQuiverSamples(import.meta.url, {
-  engine: new Quillmark(),
-  Document,
+  engine: new Engine(),
   exclude: ["broken-quill"], // or: include: ["memo@1.0.0"]
 });
 ```
@@ -96,21 +121,38 @@ await renderQuiverSamples(import.meta.url, {
 ## Consuming a quiver (Node)
 
 ```ts
-import { Quillmark, Document } from "@quillmark/wasm";
+import { Engine, Document } from "@quillmark/wasm";
 import { Quiver } from "@quillmark/quiver/node";
 
-const engine = new Quillmark();
 const quiver = await Quiver.fromPackage("@org/my-quiver");
+const engine = new Engine();
 
 const doc = Document.fromMarkdown(markdownString);
-const quill = await quiver.getQuill(doc.quillRef, { engine });
-const result = quill.render(doc, { format: "pdf" });
+const quill = await quiver.getQuill(doc.quillRef);
+const result = await engine.render(quill, doc, { format: "pdf" });
 ```
 
 `getQuill` accepts both selector refs (`"memo"`, `"memo@1"`) and canonical
 refs (`"memo@1.0.0"`). It resolves the selector, materializes the quill via
-`engine.quill(tree)`, and caches per (engine, canonical-ref). Concurrent
-calls for the same ref share a single load.
+`Quill.fromTree(tree)` (engine-free), and caches one instance per canonical
+ref for the lifetime of the `Quiver`. Concurrent calls for the same ref
+coalesce into a single load.
+
+The returned quill lives in the core build's WASM memory and is suitable for
+schema inspection, validation, blueprint access, and seeding. To render it,
+hand it straight to `engine.render(quill, doc)` — the Engine clones both
+handles into the backend on demand, so no separate boundary-crossing step is
+needed:
+
+```ts
+// Editor path — core only, ~0.66 MB gzip
+const coreQuill = await quiver.getQuill(ref);
+coreQuill.schema; // ✓ schema, validate, blueprint, seed — all fine
+const doc = coreQuill.seedDocument(); // a fully-filled example document
+
+// Render path — the same core handles render directly.
+const result = await engine.render(coreQuill, doc, { format: "pdf" });
+```
 
 If you only need the canonical ref (without materializing), use `resolve`:
 
@@ -118,6 +160,10 @@ If you only need the canonical ref (without materializing), use `resolve`:
 const canonicalRef = await quiver.resolve("memo"); // "memo@1.1.0"
 ```
 
+If you need the raw file tree (e.g. to drive a backend binary directly), call
+`(await quiver.getQuill(ref)).toTree()` on the core `Quill` — it is I/O-free
+once the quill is materialized.
+
 ## Consuming a quiver (browser)
 
 Browsers cannot read the source layout directly, so build at deploy time and
@@ -135,10 +181,15 @@ await Quiver.build(
 
 ```ts
 // browser runtime
+import { Engine, Document } from "@quillmark/wasm";
 import { Quiver } from "@quillmark/quiver";
 
 const quiver = await Quiver.fromBuiltUrl("/quivers/my-quiver/");
-const quill = await quiver.getQuill(doc.quillRef, { engine });
+const engine = new Engine();
+
+const doc = Document.fromMarkdown(markdownString);
+const quill = await quiver.getQuill(doc.quillRef);
+const result = await engine.render(quill, doc, { format: "pdf" });
 ```
 
 ## Server-side runtime (Node, packed artifact on disk)
@@ -178,15 +229,10 @@ await quiver.warm();
 
 `warm()` is I/O-only: it loads every quill's tree (over the network for
 `fromBuiltUrl`, off the filesystem for `fromPackage` / `fromDir` /
-`fromBuiltDir`) and caches
-them. It does not require an engine and does not materialize Quill
-instances — that happens lazily on the first `getQuill` call, which is
-microseconds. A subsequent `getQuill` reuses the cached tree, skipping
-the load.
-
-Once a tree has been turned into a Quill, the cached tree is dropped so
-its bytes can be GC'd — the materialized Quill is the runtime artifact.
-Calling `warm()` again refills the tree cache.
+`fromBuiltDir`) and caches them. It does not require an engine and does
+not materialize Quill instances — that happens lazily on the first
+`getQuill` call, which is microseconds. A subsequent `getQuill` reuses
+the cached tree, skipping the load.
 
 ## Error handling
 
@@ -208,6 +254,26 @@ try {
 
 Error codes: `invalid_ref`, `quill_not_found`, `quiver_invalid`, `transport_error`.
 
-## Full specification
+## Using `getQuill` vs calling `Quill.fromTree` directly
+
+`getQuill(ref)` is the correct entry point for any code that loads a quill
+through a `Quiver`. It handles ref resolution, tree fetching, `Quill.fromTree`
+construction, and per-ref caching in one call. Do **not** reach for
+`Quill.fromTree` directly inside a Quiver consumer:
+
+```ts
+import { Quill } from "@quillmark/wasm";
+
+// wrong — bypasses Quiver's cache; duplicates work getQuill already does
+const tree = new Map<string, Uint8Array>();
+tree.set("Quill.yaml", new TextEncoder().encode("name: memo\n..."));
+// ...assemble the rest of the file tree by hand...
+const quill = Quill.fromTree(tree);
+
+// right
+const quill = await quiver.getQuill(ref);
+```
 
-See [PROGRAM.md](./PROGRAM.md) for the complete API surface, runtime artifact format specification, and design decisions.
+`Quill.fromTree` is for code that builds quills **outside** of a Quiver (e.g.
+a server route that receives a raw file tree over the network, or a test
+fixture that constructs a quill from a hand-rolled in-memory tree).

package/dist/bin/quiver.d.ts

@@ -9,8 +9,8 @@
  *                  [--include <ref>...] [--exclude <ref>...]
  *
  * Engine discovery (for `test` and `preview`):
- *   1. Named exports `engine` and `Document` from `quiver.config.js` at the
- *      collection root, if the file exists.
+ *   1. Named export `engine` from `quiver.config.js` at the collection root,
+ *      if the file exists.
  *   2. Auto-imported `@quillmark/wasm` from the collection's node_modules.
  */
 export {};

package/dist/bin/quiver.js

@@ -9,8 +9,8 @@
  *                  [--include <ref>...] [--exclude <ref>...]
  *
  * Engine discovery (for `test` and `preview`):
- *   1. Named exports `engine` and `Document` from `quiver.config.js` at the
- *      collection root, if the file exists.
+ *   1. Named export `engine` from `quiver.config.js` at the collection root,
+ *      if the file exists.
  *   2. Auto-imported `@quillmark/wasm` from the collection's node_modules.
  */
 import { createRequire } from "node:module";
@@ -42,32 +42,35 @@ function hasFlag(name) {
 // Engine discovery
 // ---------------------------------------------------------------------------
 async function loadEngine(cwd) {
-    // 1. Named exports from quiver.config.js, if present.
+    // Resolve @quillmark/wasm from the collection's node_modules (best-effort).
+    // Its `Engine` renders every quill (cloning the core Quill/Document into the
+    // backend itself). A quiver.config.js may export a custom `engine`.
+    let wasm;
     try {
-        const cfg = await import(pathToFileURL(join(cwd, "quiver.config.js")).href);
-        if (cfg.engine != null && cfg.Document != null) {
-            return {
-                engine: cfg.engine,
-                Document: cfg.Document,
-            };
-        }
+        const req = createRequire(pathToFileURL(join(cwd, "package.json")).href);
+        const wasmPath = req.resolve("@quillmark/wasm");
+        wasm = (await import(pathToFileURL(wasmPath).href));
     }
     catch {
-        // File absent or incomplete — fall through to auto-discovery.
+        // Not installed — a quiver.config.js may still provide an engine.
     }
-    // 2. Auto-discover @quillmark/wasm from the collection's own node_modules.
-    const req = createRequire(pathToFileURL(join(cwd, "package.json")).href);
-    let wasmPath;
+    // 1. Named `engine` export from quiver.config.js, if present.
     try {
-        wasmPath = req.resolve("@quillmark/wasm");
+        const cfg = await import(pathToFileURL(join(cwd, "quiver.config.js")).href);
+        if (cfg.engine != null) {
+            return cfg.engine;
+        }
     }
     catch {
+        // File absent or incomplete — fall through to auto-discovery.
+    }
+    // 2. Auto-discover from @quillmark/wasm.
+    if (wasm == null) {
         throw new Error("Cannot find @quillmark/wasm in this collection's node_modules.\n" +
             "  Install it:  npm install @quillmark/wasm\n" +
-            "  Or export { engine, Document } from quiver.config.js for a custom engine.");
+            "  Or export { engine } from quiver.config.js for a custom engine.");
     }
-    const wasm = (await import(pathToFileURL(wasmPath).href));
-    return { engine: new wasm.Quillmark(), Document: wasm.Document };
+    return new wasm.Engine();
 }
 // ---------------------------------------------------------------------------
 // Commands
@@ -81,7 +84,7 @@ async function build() {
 }
 async function test() {
     const cwd = process.cwd();
-    const { engine, Document } = await loadEngine(cwd);
+    const engine = await loadEngine(cwd);
     const quiver = await Quiver.fromDir(cwd);
     const names = quiver.quillNames();
     if (names.length === 0) {
@@ -94,9 +97,15 @@ async function test() {
         for (const version of quiver.versionsOf(name)) {
             const ref = `${name}@${version}`;
             try {
-                const quill = await quiver.getQuill(ref, { engine });
-                const doc = Document.fromMarkdown(quill.example);
-                const result = quill.render(doc);
+                const quill = await quiver.getQuill(ref);
+                const doc = quill.seedDocument();
+                let result;
+                try {
+                    result = await engine.render(quill, doc);
+                }
+                finally {
+                    doc.free();
+                }
                 if (!Array.isArray(result.artifacts) || result.artifacts.length === 0) {
                     throw new Error("example render produced no artifacts");
                 }
@@ -116,7 +125,7 @@ async function test() {
 }
 async function preview() {
     const cwd = process.cwd();
-    const { engine, Document } = await loadEngine(cwd);
+    const engine = await loadEngine(cwd);
     const outDir = flag("--out");
     const format = flag("--format");
     const quiet = hasFlag("--quiet");
@@ -124,7 +133,6 @@ async function preview() {
     const exclude = multiFlag("--exclude");
     await renderQuiverSamples(cwd, {
         engine,
-        Document,
         ...(outDir !== undefined && { outDir }),
         ...(format !== undefined && { format }),
         quiet,

package/dist/index.d.ts

@@ -1,4 +1,3 @@
 export { QuiverError } from "./errors.js";
 export type { QuiverErrorCode } from "./errors.js";
 export { Quiver } from "./quiver.js";
-export type { QuillmarkLike, QuillLike } from "./engine-types.js";

package/dist/index.js

@@ -5,3 +5,8 @@
 // live at `@quillmark/quiver/node`.
 export { QuiverError } from "./errors.js";
 export { Quiver } from "./quiver.js";
+// The canonical API (`Quill`, `Document`, `Engine`, `RenderResult`, …) is not
+// re-exported: import it straight from the `@quillmark/wasm` peer dependency,
+// which is the single source of truth. `quiver.getQuill(ref)` returns a core
+// `Quill` that an `Engine` renders directly — the engine clones it into the
+// backend, so no boundary-crossing helper is needed.

package/dist/node.d.ts

@@ -79,4 +79,3 @@ export declare const Quiver: typeof Base & NodeQuiverStatics;
 export { QuiverError } from "./errors.js";
 export type { QuiverErrorCode } from "./errors.js";
 export type { BuildOptions } from "./build.js";
-export type { QuillmarkLike, QuillLike } from "./engine-types.js";

package/dist/node.js

@@ -70,3 +70,6 @@ Quiver.buildPackage = async function buildPackage(specifier, outDir, opts) {
 // 3. Re-export the rest of the public surface so consumers get one import.
 // ---------------------------------------------------------------------------
 export { QuiverError } from "./errors.js";
+// Engine types (`Quillmark`, `Quill`, `Document`, `RenderResult`, …) are not
+// re-exported: import them straight from the `@quillmark/wasm` peer dependency,
+// which is the single source of truth for the engine contract.

package/dist/preview.d.ts

@@ -11,37 +11,29 @@
  *
  * Usage (place a script next to your Quiver.yaml):
  *
- *   import { Quillmark, Document } from "@quillmark/wasm";
+ *   import { Engine } from "@quillmark/wasm";
  *   import { renderQuiverSamples } from "@quillmark/quiver/preview";
  *
- *   await renderQuiverSamples(import.meta.url, {
- *     engine: new Quillmark(),
- *     Document,
- *   });
+ *   await renderQuiverSamples(import.meta.url, { engine: new Engine() });
  *   // → open ./preview/index.html
  *
- * The sample document is the illustrative example (`quill.example`) for each
- * quill version — a fully filled-out, always-renderable document (the
- * blueprint itself carries `<must-fill>` sentinels and is not renderable).
- * Every quill always has an example, so no quills are skipped for lack of a
- * sample document.
+ * The sample document is the illustrative example seeded by
+ * `quill.seedDocument()` for each quill version — a fully filled-out,
+ * always-renderable document (the blueprint itself carries `<must-fill>`
+ * sentinels and is not renderable). Every quill always seeds an example, so no
+ * quills are skipped for lack of a sample document.
  *
  * A `.gitignore` is written into `outDir` so the generated artifacts are not
  * accidentally committed.
  */
-import type { QuillmarkLike } from "./engine-types.js";
-/**
- * Structural shape of the `Document` class from `@quillmark/wasm`. Only the
- * `fromMarkdown` factory is used; passing the real class satisfies this.
- */
-export interface DocumentFactoryLike {
-    fromMarkdown(markdown: string): unknown;
-}
+import type { Engine } from "@quillmark/wasm";
 export interface RenderQuiverSamplesOptions {
-    /** Quillmark engine instance (`new Quillmark()` from `@quillmark/wasm`). */
-    engine: QuillmarkLike;
-    /** The `Document` class from `@quillmark/wasm`. */
-    Document: DocumentFactoryLike;
+    /**
+     * Canonical render engine (`new Engine()` from `@quillmark/wasm`). It takes the
+     * core `Quill`/`Document` that quiver produces and clones them into the
+     * backend on demand — no build-matching or handle-crossing for the caller.
+     */
+    engine: Engine;
     /** Directory to write rendered artifacts into. Default: `preview`. */
     outDir?: string;
     /** Force an output format (`pdf`/`svg`/`png`/`txt`). Default: engine's choice. */

package/dist/preview.js

@@ -11,20 +11,17 @@
  *
  * Usage (place a script next to your Quiver.yaml):
  *
- *   import { Quillmark, Document } from "@quillmark/wasm";
+ *   import { Engine } from "@quillmark/wasm";
  *   import { renderQuiverSamples } from "@quillmark/quiver/preview";
  *
- *   await renderQuiverSamples(import.meta.url, {
- *     engine: new Quillmark(),
- *     Document,
- *   });
+ *   await renderQuiverSamples(import.meta.url, { engine: new Engine() });
  *   // → open ./preview/index.html
  *
- * The sample document is the illustrative example (`quill.example`) for each
- * quill version — a fully filled-out, always-renderable document (the
- * blueprint itself carries `<must-fill>` sentinels and is not renderable).
- * Every quill always has an example, so no quills are skipped for lack of a
- * sample document.
+ * The sample document is the illustrative example seeded by
+ * `quill.seedDocument()` for each quill version — a fully filled-out,
+ * always-renderable document (the blueprint itself carries `<must-fill>`
+ * sentinels and is not renderable). Every quill always seeds an example, so no
+ * quills are skipped for lack of a sample document.
  *
  * A `.gitignore` is written into `outDir` so the generated artifacts are not
  * accidentally committed.
@@ -32,6 +29,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { Quiver } from "./node.js";
+import { isQuillmarkError } from "@quillmark/wasm";
 /** Default directory rendered artifacts are written to. */
 const DEFAULT_OUT_DIR = "preview";
 /**
@@ -74,13 +72,12 @@ function isSelected(name, ref, opts) {
 }
 /**
  * Formats a thrown render error into one string per diagnostic. `@quillmark/wasm`
- * attaches a `diagnostics` array to its errors; fall back to the message when
- * an error carries none.
+ * throws `QuillmarkError`s (an `Error` carrying `diagnostics`); fall back to
+ * the message for anything else.
  */
 function failureReasons(err) {
-    const diagnostics = err.diagnostics;
-    if (Array.isArray(diagnostics) && diagnostics.length > 0) {
-        return diagnostics.map((d) => `${d.severity}: ${d.message}`);
+    if (isQuillmarkError(err) && err.diagnostics.length > 0) {
+        return err.diagnostics.map((d) => `${d.severity}: ${d.message}`);
     }
     return [err.message];
 }
@@ -88,10 +85,16 @@ async function renderOne(quiver, name, version, outDir, opts) {
     const ref = `${name}@${version}`;
     let result;
     try {
-        const quill = await quiver.getQuill(ref, { engine: opts.engine });
-        const markdown = quill.example;
-        const doc = opts.Document.fromMarkdown(markdown);
-        result = quill.render(doc, opts.format ? { format: opts.format } : undefined);
+        // Canonical render path: a core Quill + its seeded Document handed straight
+        // to the Engine, which clones them into the backend and frees the clones.
+        const quill = await quiver.getQuill(ref);
+        const doc = quill.seedDocument();
+        try {
+            result = await opts.engine.render(quill, doc, opts.format ? { format: opts.format } : undefined);
+        }
+        finally {
+            doc.free();
+        }
     }
     catch (err) {
         return {

package/dist/quiver.d.ts

@@ -9,7 +9,7 @@
  * `build`) are installed on this class by `./node.js`, which is the
  * consumer's explicit opt-in to the Node API surface.
  */
-import type { QuillmarkLike, QuillLike } from "./engine-types.js";
+import { Quill } from "@quillmark/wasm";
 /** @internal Internal loader strategy: source or build output. */
 export interface QuiverLoader {
     loadTree(name: string, version: string): Promise<Map<string, Uint8Array>>;
@@ -49,16 +49,6 @@ export declare class Quiver {
      * Returns an empty array if the quill name is not in the catalog.
      */
     versionsOf(name: string): string[];
-    /**
-     * Lazily loads the file tree for a specific quill version.
-     *
-     * Returns `Map<string, Uint8Array>` suitable for `engine.quill(tree)`.
-     * Does NOT cache the result — caching of materialized Quill instances
-     * happens in `getQuill`.
-     *
-     * Throws `transport_error` if name/version not in catalog or I/O fails.
-     */
-    loadTree(name: string, version: string): Promise<Map<string, Uint8Array>>;
     /**
      * Resolves a selector ref → canonical ref (e.g. "memo" → "memo@1.1.0").
      *
@@ -71,29 +61,32 @@ export declare class Quiver {
      */
     resolve(ref: string): Promise<string>;
     /**
-     * Returns a render-ready `Quill` for a ref (selector or canonical).
+     * Returns a `Quill` for a ref (selector or canonical).
+     *
+     * The returned quill is materialized from the `@quillmark/wasm` root export
+     * — it is engine-free, portable data suitable for schema inspection,
+     * validation, blueprint access, and document seeding.
+     *
+     * A core `Quill` renders directly: pass it to `engine.render(quill, doc)`.
      *
-     * Selector refs (e.g. `"memo"`, `"memo@1"`) are resolved to canonical
-     * form first. Materializes via `engine.quill(tree)` on first call;
-     * caches per (engine, canonical-ref). Reuses a tree cached by `warm()`
-     * (or a previous `getQuill`) so the network fetch isn't paid twice.
-     * Concurrent calls for the same ref coalesce into a single load.
+     * Selector refs (e.g. `"memo"`, `"memo@1"`) are resolved to canonical form
+     * first. Materializes once and caches per canonical ref — concurrent calls
+     * coalesce into a single load.
      *
      * Throws:
      *   - `invalid_ref` if ref is malformed
      *   - `quill_not_found` if ref does not match any version in this quiver
-     *   - propagates I/O errors from loadTree unchanged
-     *   - propagates engine errors from engine.quill() unchanged
+     *   - propagates I/O errors from the loader unchanged
+     *   - propagates validation errors from Quill.fromTree() unchanged
      */
-    getQuill(ref: string, opts: {
-        engine: QuillmarkLike;
-    }): Promise<QuillLike>;
+    getQuill(ref: string): Promise<Quill>;
     /**
      * Prefetches the tree for every quill version in this quiver. Fail-fast.
      *
      * Network-bound only — does not materialize Quill instances and does not
      * require an engine. Subsequent `getQuill` calls reuse the cached trees,
-     * skipping the fetch. Rejects on the first fetch failure.
+     * skipping the fetch (the tree then evicts as its quill materializes).
+     * Rejects on the first fetch failure.
      */
     warm(): Promise<void>;
 }