@quillmark/quiver 0.13.0 → 0.16.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,11 +84,11 @@ 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 } from "@quillmark/wasm";
+import { Engine } from "@quillmark/wasm";
 import { renderQuiverSamples } from "@quillmark/quiver/preview";
 
 await renderQuiverSamples(import.meta.url, {
-  engine: new Quillmark(),
+  engine: new Engine(),
 });
 // → writes ./preview/<name>@<version>.<fmt> + index.html
 ```
@@ -82,7 +108,7 @@ quill name or canonical ref):
 
 ```ts
 await renderQuiverSamples(import.meta.url, {
-  engine: new Quillmark(),
+  engine: new Engine(),
   exclude: ["broken-quill"], // or: include: ["memo@1.0.0"]
 });
 ```
@@ -95,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`:
 
@@ -117,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
@@ -134,12 +181,64 @@ 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" });
+```
+
+## SSR seeding (skip the `latest.json` pointer)
+
+`Quiver.fromBuiltUrl(url)` first fetches `<url>/latest.json` — a stable-named,
+non-content-addressed pointer to the current manifest — before fetching the
+manifest itself. Because that one filename is stable, a CDN edge or browser
+cache can serve a **stale pointer** after a release and silently pin the
+client to the old catalog, with no error. Per-host cache headers only fix this
+one serving layer at a time.
+
+If you already hold the manifest bytes at build time — a common case for SSR
+consumers, which read the built artifact during their own build — seed the
+catalog from them directly with `Quiver.fromManifest`. It never requests
+`latest.json`; bundles and fonts are still fetched lazily and
+content-addressed, relative to `baseUrl`, exactly as with `fromBuiltUrl`:
+
+```ts
+// Server build step — read the manifest the build wrote.
+// build-output/latest.json → { "manifest": "manifest.<hash>.json" }
+import { readFile } from "node:fs/promises";
+
+const { manifest } = JSON.parse(
+  await readFile("./public/quivers/my-quiver/latest.json", "utf8"),
+);
+const manifestBytes = new Uint8Array(
+  await readFile(`./public/quivers/my-quiver/${manifest}`),
+);
+// Inline manifestBytes into the page payload (e.g. base64) for the client.
+```
+
+```ts
+// Browser / SSR runtime — seed from the bytes you shipped, no pointer fetch.
+import { Engine, Document } from "@quillmark/wasm";
+import { Quiver } from "@quillmark/quiver";
+
+const quiver = await Quiver.fromManifest("/quivers/my-quiver/", manifestBytes);
+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" });
 ```
 
+`fromManifest` is browser-safe (no `node:*` imports) and shares
+`fromBuiltUrl`'s error semantics: `quiver_invalid` for malformed manifest
+bytes, `transport_error` for a `file://` `baseUrl` or a later bundle-fetch
+failure.
+
 ## Server-side runtime (Node, packed artifact on disk)
 
 For server-side rendering where the packed artifact ships in the deployment
@@ -177,15 +276,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
 
@@ -206,3 +300,27 @@ try {
 ```
 
 Error codes: `invalid_ref`, `quill_not_found`, `quiver_invalid`, `transport_error`.
+
+## 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);
+```
+
+`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.js

@@ -42,29 +42,35 @@ function hasFlag(name) {
 // Engine discovery
 // ---------------------------------------------------------------------------
 async function loadEngine(cwd) {
-    // 1. Named export 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 req = createRequire(pathToFileURL(join(cwd, "package.json")).href);
+        const wasmPath = req.resolve("@quillmark/wasm");
+        wasm = (await import(pathToFileURL(wasmPath).href));
+    }
+    catch {
+        // Not installed — a quiver.config.js may still provide an engine.
+    }
+    // 1. Named `engine` export from quiver.config.js, if present.
     try {
         const cfg = await import(pathToFileURL(join(cwd, "quiver.config.js")).href);
         if (cfg.engine != null) {
-            return { engine: cfg.engine };
+            return cfg.engine;
         }
     }
     catch {
         // File absent or incomplete — fall through to auto-discovery.
     }
-    // 2. Auto-discover @quillmark/wasm from the collection's own node_modules.
-    const req = createRequire(pathToFileURL(join(cwd, "package.json")).href);
-    let wasmPath;
-    try {
-        wasmPath = req.resolve("@quillmark/wasm");
-    }
-    catch {
+    // 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 } from quiver.config.js for a custom engine.");
     }
-    const wasm = (await import(pathToFileURL(wasmPath).href));
-    return { engine: new wasm.Quillmark() };
+    return new wasm.Engine();
 }
 // ---------------------------------------------------------------------------
 // Commands
@@ -78,7 +84,7 @@ async function build() {
 }
 async function test() {
     const cwd = process.cwd();
-    const { engine } = await loadEngine(cwd);
+    const engine = await loadEngine(cwd);
     const quiver = await Quiver.fromDir(cwd);
     const names = quiver.quillNames();
     if (names.length === 0) {
@@ -91,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 quill = await quiver.getQuill(ref);
                 const doc = quill.seedDocument();
-                const result = quill.render(doc);
+                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");
                 }
@@ -113,7 +125,7 @@ async function test() {
 }
 async function preview() {
     const cwd = process.cwd();
-    const { engine } = await loadEngine(cwd);
+    const engine = await loadEngine(cwd);
     const outDir = flag("--out");
     const format = flag("--format");
     const quiet = hasFlag("--quiet");

package/dist/build.d.ts

@@ -12,7 +12,7 @@ export type BuildOptions = Record<string, never>;
  *
  * Output layout:
  *   outDir/
- *     Quiver.json                   # stable pointer
+ *     latest.json                   # stable pointer to the current manifest
  *     manifest.<md5prefix6>.json    # hashed manifest
  *     <name>@<version>.<md5>.zip    # one bundle per quill
  *     store/

package/dist/build.js

@@ -14,7 +14,7 @@ const FONT_EXT = /\.(ttf|otf|woff|woff2)$/i;
  *
  * Output layout:
  *   outDir/
- *     Quiver.json                   # stable pointer
+ *     latest.json                   # stable pointer to the current manifest
  *     manifest.<md5prefix6>.json    # hashed manifest
  *     <name>@<version>.<md5>.zip    # one bundle per quill
  *     store/
@@ -108,9 +108,9 @@ export async function buildQuiver(sourceDir, outDir, _opts) {
     catch (err) {
         throw new QuiverError("transport_error", `Failed to write manifest "${manifestPath}": ${err.message}`, { cause: err });
     }
-    // 9–10. Write stable pointer Quiver.json.
+    // 9–10. Write stable pointer latest.json.
     const pointer = { manifest: manifestFileName };
-    const pointerPath = join(outDir, "Quiver.json");
+    const pointerPath = join(outDir, "latest.json");
     try {
         await writeFile(pointerPath, JSON.stringify(pointer), "utf-8");
     }

package/dist/built-loader.d.ts

@@ -19,9 +19,15 @@ export interface BuiltTransport {
 /**
  * Load a build-output quiver via the given transport.
  *
- * 1. Fetches Quiver.json (pointer) and parses it.
+ * 1. Fetches latest.json (pointer) and parses it.
  * 2. Fetches the manifest file it points to and validates it.
  * 3. Builds a catalog from manifest entries (versions sorted descending).
  * 4. Returns a Quiver instance backed by a BuiltLoader.
  */
 export declare function loadBuiltQuiver(transport: BuiltTransport): Promise<Quiver>;
+/**
+ * Seed a quiver from caller-provided manifest bytes, skipping the latest.json
+ * pointer fetch. `transport` is used only for lazy bundle/font fetches.
+ * Throws `quiver_invalid` on malformed bytes.
+ */
+export declare function seedBuiltQuiver(transport: BuiltTransport, manifestBytes: Uint8Array): Quiver;

package/dist/built-loader.js

@@ -96,15 +96,15 @@ function parsePointer(raw) {
         parsed = JSON.parse(raw);
     }
     catch {
-        throw new QuiverError("quiver_invalid", "Quiver.json contains invalid JSON");
+        throw new QuiverError("quiver_invalid", "latest.json contains invalid JSON");
     }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        throw new QuiverError("quiver_invalid", "Quiver.json must be a JSON object");
+        throw new QuiverError("quiver_invalid", "latest.json must be a JSON object");
     }
     const obj = parsed;
-    assertNoUnknownKeys(obj, ["manifest"], "Quiver.json");
+    assertNoUnknownKeys(obj, ["manifest"], "latest.json");
     if (typeof obj["manifest"] !== "string" || obj["manifest"].length === 0) {
-        throw new QuiverError("quiver_invalid", 'Quiver.json must have a non-empty string "manifest" field');
+        throw new QuiverError("quiver_invalid", 'latest.json must have a non-empty string "manifest" field');
     }
     return obj["manifest"];
 }
@@ -175,11 +175,38 @@ function parseManifest(raw) {
         quills,
     };
 }
-// ─── Main entry point ─────────────────────────────────────────────────────────
+// ─── Catalog assembly ─────────────────────────────────────────────────────────
+/**
+ * Validate manifest bytes (`quiver_invalid` on format errors) and assemble a
+ * Quiver backed by a BuiltLoader over `transport`. Shared by `loadBuiltQuiver`
+ * (pointer-following) and `seedBuiltQuiver` (seed).
+ */
+function buildQuiverFromManifestBytes(transport, manifestBytes) {
+    const manifest = parseManifest(new TextDecoder().decode(manifestBytes));
+    // catalog: name → versions (desc); index: "name@version" → entry (dedup).
+    const catalogRaw = new Map();
+    const index = new Map();
+    for (const entry of manifest.quills) {
+        const key = `${entry.name}@${entry.version}`;
+        if (index.has(key)) {
+            throw new QuiverError("quiver_invalid", `Duplicate quill entry in manifest: "${key}"`);
+        }
+        index.set(key, entry);
+        const versions = catalogRaw.get(entry.name) ?? [];
+        versions.push(entry.version);
+        catalogRaw.set(entry.name, versions);
+    }
+    for (const [, versions] of catalogRaw) {
+        versions.sort((a, b) => compareSemver(b, a));
+    }
+    const loader = new BuiltLoader(transport, index);
+    return Quiver._fromLoader(manifest.name, catalogRaw, loader);
+}
+// ─── Main entry points ────────────────────────────────────────────────────────
 /**
  * Load a build-output quiver via the given transport.
  *
- * 1. Fetches Quiver.json (pointer) and parses it.
+ * 1. Fetches latest.json (pointer) and parses it.
  * 2. Fetches the manifest file it points to and validates it.
  * 3. Builds a catalog from manifest entries (versions sorted descending).
  * 4. Returns a Quiver instance backed by a BuiltLoader.
@@ -188,12 +215,12 @@ export async function loadBuiltQuiver(transport) {
     // 1. Fetch and parse pointer.
     let pointerBytes;
     try {
-        pointerBytes = await transport.fetchBytes("Quiver.json");
+        pointerBytes = await transport.fetchBytes("latest.json");
     }
     catch (err) {
         if (err instanceof QuiverError)
             throw err;
-        throw new QuiverError("transport_error", `Failed to fetch Quiver.json: ${err.message}`, { cause: err });
+        throw new QuiverError("transport_error", `Failed to fetch latest.json: ${err.message}`, { cause: err });
     }
     const manifestFileName = parsePointer(new TextDecoder().decode(pointerBytes));
     validateManifestFileName(manifestFileName);
@@ -207,26 +234,14 @@ export async function loadBuiltQuiver(transport) {
             throw err;
         throw new QuiverError("transport_error", `Failed to fetch manifest "${manifestFileName}": ${err.message}`, { cause: err });
     }
-    const manifest = parseManifest(new TextDecoder().decode(manifestBytes));
-    // 3. Build catalog: name → versions sorted descending.
-    //    Also build index map: "name@version" → entry (with duplicate detection).
-    const catalogRaw = new Map();
-    const index = new Map();
-    for (const entry of manifest.quills) {
-        const key = `${entry.name}@${entry.version}`;
-        if (index.has(key)) {
-            throw new QuiverError("quiver_invalid", `Duplicate quill entry in manifest: "${key}"`);
-        }
-        index.set(key, entry);
-        const versions = catalogRaw.get(entry.name) ?? [];
-        versions.push(entry.version);
-        catalogRaw.set(entry.name, versions);
-    }
-    for (const [, versions] of catalogRaw) {
-        versions.sort((a, b) => compareSemver(b, a));
-    }
-    // 4. Build loader.
-    const loader = new BuiltLoader(transport, index);
-    // 5. Return Quiver via internal factory.
-    return Quiver._fromLoader(manifest.name, catalogRaw, loader);
+    // 3–4. Validate manifest + assemble catalog/loader.
+    return buildQuiverFromManifestBytes(transport, manifestBytes);
+}
+/**
+ * Seed a quiver from caller-provided manifest bytes, skipping the latest.json
+ * pointer fetch. `transport` is used only for lazy bundle/font fetches.
+ * Throws `quiver_invalid` on malformed bytes.
+ */
+export function seedBuiltQuiver(transport, manifestBytes) {
+    return buildQuiverFromManifestBytes(transport, manifestBytes);
 }

package/dist/index.js

@@ -5,6 +5,8 @@
 // live at `@quillmark/quiver/node`.
 export { QuiverError } from "./errors.js";
 export { Quiver } from "./quiver.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.
+// 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

@@ -43,7 +43,7 @@ type NodeQuiverStatics = {
     fromDir(pathOrFileUrl: string): Promise<Base>;
     /**
      * Loads a packed (build-output) quiver from a local directory containing
-     * `Quiver.json` and the manifest/bundle/store files written by
+     * `latest.json` and the manifest/bundle/store files written by
      * `Quiver.build`. Symmetric to `fromBuiltUrl(url)` but reads from disk
      * instead of HTTP — no network required.
      *

package/dist/preview.d.ts

@@ -11,12 +11,10 @@
  *
  * Usage (place a script next to your Quiver.yaml):
  *
- *   import { Quillmark } from "@quillmark/wasm";
+ *   import { Engine } from "@quillmark/wasm";
  *   import { renderQuiverSamples } from "@quillmark/quiver/preview";
  *
- *   await renderQuiverSamples(import.meta.url, {
- *     engine: new Quillmark(),
- *   });
+ *   await renderQuiverSamples(import.meta.url, { engine: new Engine() });
  *   // → open ./preview/index.html
  *
  * The sample document is the illustrative example seeded by
@@ -28,10 +26,14 @@
  * A `.gitignore` is written into `outDir` so the generated artifacts are not
  * accidentally committed.
  */
-import type { Quillmark } from "@quillmark/wasm";
+import type { Engine } from "@quillmark/wasm";
 export interface RenderQuiverSamplesOptions {
-    /** Quillmark engine instance (`new Quillmark()` from `@quillmark/wasm`). */
-    engine: Quillmark;
+    /**
+     * 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,12 +11,10 @@
  *
  * Usage (place a script next to your Quiver.yaml):
  *
- *   import { Quillmark } from "@quillmark/wasm";
+ *   import { Engine } from "@quillmark/wasm";
  *   import { renderQuiverSamples } from "@quillmark/quiver/preview";
  *
- *   await renderQuiverSamples(import.meta.url, {
- *     engine: new Quillmark(),
- *   });
+ *   await renderQuiverSamples(import.meta.url, { engine: new Engine() });
  *   // → open ./preview/index.html
  *
  * The sample document is the illustrative example seeded by
@@ -31,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";
 /**
@@ -73,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];
 }
@@ -87,9 +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 });
+        // 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();
-        result = quill.render(doc, opts.format ? { format: opts.format } : undefined);
+        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 { Quillmark, Quill } from "@quillmark/wasm";
+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>>;
@@ -42,6 +42,16 @@ export declare class Quiver {
      * on format errors.
      */
     static fromBuiltUrl(url: string): Promise<Quiver>;
+    /**
+     * Browser-safe factory. Seeds the catalog from caller-provided manifest
+     * bytes — never fetches `latest.json` — then fetches bundles lazily and
+     * content-addressed, relative to `baseUrl`, like `fromBuiltUrl`. For SSR
+     * consumers that already hold the manifest at build time.
+     *
+     * Throws `quiver_invalid` on malformed manifest bytes, `transport_error`
+     * on a `file://` baseUrl or a later bundle fetch failure.
+     */
+    static fromManifest(baseUrl: string, manifestBytes: Uint8Array): Promise<Quiver>;
     /** Returns all known quill names, sorted lexicographically. */
     quillNames(): string[];
     /**
@@ -49,16 +59,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 +71,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: Quillmark;
-    }): Promise<Quill>;
+    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>;
 }

package/dist/quiver.js

@@ -10,6 +10,7 @@
  * consumer's explicit opt-in to the Node API surface.
  */
 import { QuiverError } from "./errors.js";
+import { Quill } from "@quillmark/wasm";
 import { parseQuillRef } from "./ref.js";
 import { matchesSemverSelector, chooseHighestVersion } from "./semver.js";
 export class Quiver {
@@ -17,15 +18,16 @@ export class Quiver {
     #catalog;
     #loader;
     /**
-     * Per-engine cache of materialized quills, keyed by canonical ref.
-     * WeakMap so engines can be GC'd; Promise values so concurrent
-     * getQuill calls coalesce into a single materialization.
+     * Cache of materialized quills, keyed by canonical ref. A `Quill` is now
+     * engine-free, portable data (`Quill.fromTree`), so one instance per ref is
+     * shared across every engine. Promise values so concurrent getQuill calls
+     * coalesce into a single materialization.
      */
-    #quillCache = new WeakMap();
+    #quillCache = new Map();
     /**
-     * Engine-independent cache of fetched trees, keyed by canonical ref.
-     * Populated by `warm()` and on first `getQuill` for a ref. Promise
-     * values so concurrent fetches coalesce.
+     * Cache of fetched trees, keyed by canonical ref. Populated by `warm()`
+     * and on first `getQuill` for a ref; an entry is evicted once its quill
+     * materializes successfully. Promise values so concurrent fetches coalesce.
      */
     #treeCache = new Map();
     /**
@@ -67,6 +69,24 @@ export class Quiver {
         const transport = new HttpTransport(url);
         return loadBuiltQuiver(transport);
     }
+    /**
+     * Browser-safe factory. Seeds the catalog from caller-provided manifest
+     * bytes — never fetches `latest.json` — then fetches bundles lazily and
+     * content-addressed, relative to `baseUrl`, like `fromBuiltUrl`. For SSR
+     * consumers that already hold the manifest at build time.
+     *
+     * Throws `quiver_invalid` on malformed manifest bytes, `transport_error`
+     * on a `file://` baseUrl or a later bundle fetch failure.
+     */
+    static async fromManifest(baseUrl, manifestBytes) {
+        if (baseUrl.startsWith("file://")) {
+            throw new QuiverError("transport_error", `Quiver.fromManifest requires an http(s):// or origin-relative baseUrl; got "${baseUrl}". For local build output, use Quiver.fromBuiltDir from @quillmark/quiver/node.`);
+        }
+        const { HttpTransport } = await import("./transports/http-transport.js");
+        const { seedBuiltQuiver } = await import("./built-loader.js");
+        const transport = new HttpTransport(baseUrl);
+        return seedBuiltQuiver(transport, manifestBytes);
+    }
     /** Returns all known quill names, sorted lexicographically. */
     quillNames() {
         return [...this.#catalog.keys()].sort();
@@ -78,22 +98,6 @@ export class Quiver {
     versionsOf(name) {
         return [...(this.#catalog.get(name) ?? [])];
     }
-    /**
-     * 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.
-     */
-    async loadTree(name, version) {
-        const versions = this.#catalog.get(name);
-        if (!versions || !versions.includes(version)) {
-            throw new QuiverError("transport_error", `Quill "${name}@${version}" not found in quiver "${this.name}"`, { quiverName: this.name, version, ref: `${name}@${version}` });
-        }
-        return this.#loader.loadTree(name, version);
-    }
     /**
      * Resolves a selector ref → canonical ref (e.g. "memo" → "memo@1.1.0").
      *
@@ -120,63 +124,65 @@ export class Quiver {
         throw new QuiverError("quill_not_found", `No quill found for ref "${ref}" in quiver "${this.name}".`, { ref, quiverName: this.name });
     }
     /**
-     * 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.
      *
-     * 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.
+     * 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 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
      */
-    async getQuill(ref, opts) {
+    async getQuill(ref) {
         const canonicalRef = await this.resolve(ref);
-        const engine = opts.engine;
-        let perEngine = this.#quillCache.get(engine);
-        if (perEngine === undefined) {
-            perEngine = new Map();
-            this.#quillCache.set(engine, perEngine);
-        }
-        let entry = perEngine.get(canonicalRef);
+        let entry = this.#quillCache.get(canonicalRef);
         if (entry === undefined) {
-            entry = this.#materializeQuill(canonicalRef, engine).catch((err) => {
-                perEngine.delete(canonicalRef);
+            entry = this.#materializeQuill(canonicalRef).catch((err) => {
+                this.#quillCache.delete(canonicalRef);
                 throw err;
             });
-            perEngine.set(canonicalRef, entry);
+            this.#quillCache.set(canonicalRef, entry);
         }
         return entry;
     }
     /**
-     * Internal: load tree (cached) + invoke engine.quill. Errors propagate.
-     *
-     * On success, evicts the tree from the cache so its bytes can be GC'd —
-     * the materialized Quill is the runtime artifact; the tree is dead weight
-     * once a Quill exists. On failure, the tree is retained so retries skip
-     * the network.
+     * Internal: load tree (cached) + construct via Quill.fromTree. Errors
+     * propagate. On success the tree is evicted from `#treeCache` (the quill
+     * cache now holds the materialized result), so the tree is not retained
+     * past materialization. On `Quill.fromTree` failure the tree stays cached,
+     * so a retry skips the refetch.
      */
-    async #materializeQuill(canonicalRef, engine) {
-        const tree = await this.#getTreeCached(canonicalRef);
-        const quill = engine.quill(tree);
-        this.#treeCache.delete(canonicalRef);
+    async #materializeQuill(canonicalRef) {
+        const entry = this.#getTreeCached(canonicalRef);
+        const tree = await entry;
+        const quill = Quill.fromTree(tree);
+        // Evict by identity: only drop the entry if it is still the promise this
+        // materialization consumed (a concurrent refetch may have replaced it).
+        if (this.#treeCache.get(canonicalRef) === entry) {
+            this.#treeCache.delete(canonicalRef);
+        }
         return quill;
     }
     /**
-     * Internal: tree cache reader. On miss, fetches via `loadTree` and stores
+     * Internal: tree cache reader. On miss, fetches via `#loadTree` and stores
      * the in-flight Promise. On rejection, evicts so a retry can succeed.
      */
-    async #getTreeCached(canonicalRef) {
+    #getTreeCached(canonicalRef) {
         let entry = this.#treeCache.get(canonicalRef);
         if (entry === undefined) {
             const at = canonicalRef.indexOf("@");
             const name = canonicalRef.slice(0, at);
             const version = canonicalRef.slice(at + 1);
-            entry = this.loadTree(name, version).catch((err) => {
+            entry = this.#loadTree(name, version).catch((err) => {
                 this.#treeCache.delete(canonicalRef);
                 throw err;
             });
@@ -184,12 +190,27 @@ export class Quiver {
         }
         return entry;
     }
+    /**
+     * Internal: validates name/version against the catalog, then delegates to
+     * the loader. Returns `Map<string, Uint8Array>` suitable for
+     * `Quill.fromTree(tree)`. Does NOT cache — caching lives in `#getTreeCached`.
+     *
+     * Throws `transport_error` if name/version not in catalog or I/O fails.
+     */
+    async #loadTree(name, version) {
+        const versions = this.#catalog.get(name);
+        if (!versions || !versions.includes(version)) {
+            throw new QuiverError("transport_error", `Quill "${name}@${version}" not found in quiver "${this.name}"`, { quiverName: this.name, version, ref: `${name}@${version}` });
+        }
+        return this.#loader.loadTree(name, version);
+    }
     /**
      * 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.
      */
     async warm() {
         const promises = [];

package/dist/testing.d.ts

@@ -7,14 +7,13 @@
  *
  * Usage (place this file next to your Quiver.yaml):
  *
- *   import { Quillmark } from "@quillmark/wasm";
+ *   import { Engine } from "@quillmark/wasm";
  *   import { runQuiverTests } from "@quillmark/quiver/testing";
- *   const engine = new Quillmark();
- *   runQuiverTests(import.meta.url, engine);
+ *   runQuiverTests(import.meta.url, new Engine());
  *
  * Run with `node --test`.
  */
-import type { Quillmark } from "@quillmark/wasm";
+import type { Engine } from "@quillmark/wasm";
 /**
  * Registers a `node:test` describe block that validates every quill
  * version in the quiver at `metaUrlOrDir` against the provided engine.
@@ -23,7 +22,7 @@ import type { Quillmark } from "@quillmark/wasm";
  * to Quiver.yaml). Pass an absolute directory path for any other layout.
  *
  * Validation covers the full loading pipeline: Quiver.yaml, Quill.yaml,
- * all template files, engine compilation via engine.quill(tree), and a
- * full render of each quill's example document.
+ * all template files, quill construction via Quill.fromTree(tree), and a
+ * full render of each quill's example document via engine.render(quill, doc).
  */
-export declare function runQuiverTests(metaUrlOrDir: string, engine: Quillmark): void;
+export declare function runQuiverTests(metaUrlOrDir: string, engine: Engine): void;

package/dist/testing.js

@@ -7,10 +7,9 @@
  *
  * Usage (place this file next to your Quiver.yaml):
  *
- *   import { Quillmark } from "@quillmark/wasm";
+ *   import { Engine } from "@quillmark/wasm";
  *   import { runQuiverTests } from "@quillmark/quiver/testing";
- *   const engine = new Quillmark();
- *   runQuiverTests(import.meta.url, engine);
+ *   runQuiverTests(import.meta.url, new Engine());
  *
  * Run with `node --test`.
  */
@@ -27,8 +26,8 @@ import { Quiver } from "./node.js";
  * to Quiver.yaml). Pass an absolute directory path for any other layout.
  *
  * Validation covers the full loading pipeline: Quiver.yaml, Quill.yaml,
- * all template files, engine compilation via engine.quill(tree), and a
- * full render of each quill's example document.
+ * all template files, quill construction via Quill.fromTree(tree), and a
+ * full render of each quill's example document via engine.render(quill, doc).
  */
 export function runQuiverTests(metaUrlOrDir, engine) {
     describe("Quiver", () => {
@@ -45,9 +44,18 @@ export function runQuiverTests(metaUrlOrDir, engine) {
             for (const name of quiver.quillNames()) {
                 for (const version of quiver.versionsOf(name)) {
                     const ref = `${name}@${version}`;
-                    const quill = await quiver.getQuill(ref, { engine });
+                    // The Engine takes the core Quill + its seeded Document directly and
+                    // clones them into the backend; the doc clone is freed inside render,
+                    // and we free our own core Document here.
+                    const quill = await quiver.getQuill(ref);
                     const doc = quill.seedDocument();
-                    const result = quill.render(doc);
+                    let result;
+                    try {
+                        result = await engine.render(quill, doc);
+                    }
+                    finally {
+                        doc.free();
+                    }
                     if (!Array.isArray(result.artifacts) || result.artifacts.length === 0) {
                         throw new Error(`${ref}: example render produced no artifacts`);
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/quiver",
-  "version": "0.13.0",
+  "version": "0.16.0",
   "description": "Quiver registry and build tooling for Quillmark",
   "type": "module",
   "license": "MIT",
@@ -20,7 +20,7 @@
   ],
   "author": "Quillmark Contributors",
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "exports": {
     ".": {
@@ -50,14 +50,14 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@quillmark/wasm": ">=0.88.0"
+    "@quillmark/wasm": ">=0.90.0-0"
   },
   "dependencies": {
     "fflate": "^0.8.2",
     "yaml": "^2.8.3"
   },
   "devDependencies": {
-    "@quillmark/wasm": "^0.88.0",
+    "@quillmark/wasm": "0.91.0",
     "@types/node": "^25.3.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
@@ -67,6 +67,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "prepack": "rm -rf dist && tsc",
     "test": "vitest run",
     "lint": "tsc --noEmit"
   }