@quillmark/quiver 0.12.0 → 0.15.0

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();
     /**
@@ -78,22 +80,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 +106,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.
+     *
+     * 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
      */
-    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 +172,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,15 +7,13 @@
  *
  * Usage (place this file next to your Quiver.yaml):
  *
- *   import { Quillmark, Document } from "@quillmark/wasm";
+ *   import { Engine } from "@quillmark/wasm";
  *   import { runQuiverTests } from "@quillmark/quiver/testing";
- *   const engine = new Quillmark();
- *   runQuiverTests(import.meta.url, engine, Document);
+ *   runQuiverTests(import.meta.url, new Engine());
  *
  * Run with `node --test`.
  */
-import type { QuillmarkLike } from "./engine-types.js";
-import type { DocumentFactoryLike } from "./preview.js";
+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.
@@ -24,7 +22,7 @@ import type { DocumentFactoryLike } from "./preview.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 declare function runQuiverTests(metaUrlOrDir: string, engine: QuillmarkLike, Document: DocumentFactoryLike): 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, Document } from "@quillmark/wasm";
+ *   import { Engine } from "@quillmark/wasm";
  *   import { runQuiverTests } from "@quillmark/quiver/testing";
- *   const engine = new Quillmark();
- *   runQuiverTests(import.meta.url, engine, Document);
+ *   runQuiverTests(import.meta.url, new Engine());
  *
  * Run with `node --test`.
  */
@@ -27,10 +26,10 @@ 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, Document) {
+export function runQuiverTests(metaUrlOrDir, engine) {
     describe("Quiver", () => {
         let quiver;
         before(async () => {
@@ -45,9 +44,18 @@ export function runQuiverTests(metaUrlOrDir, engine, Document) {
             for (const name of quiver.quillNames()) {
                 for (const version of quiver.versionsOf(name)) {
                     const ref = `${name}@${version}`;
-                    const quill = await quiver.getQuill(ref, { engine });
-                    const doc = Document.fromMarkdown(quill.example);
-                    const result = quill.render(doc);
+                    // 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();
+                    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.12.0",
+  "version": "0.15.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": {
     ".": {
@@ -47,18 +47,17 @@
   ],
   "files": [
     "dist",
-    "PROGRAM.md",
     "README.md"
   ],
   "peerDependencies": {
-    "@quillmark/wasm": ">=0.86.0"
+    "@quillmark/wasm": ">=0.90.0-0"
   },
   "dependencies": {
     "fflate": "^0.8.2",
     "yaml": "^2.8.3"
   },
   "devDependencies": {
-    "@quillmark/wasm": "^0.86.0",
+    "@quillmark/wasm": "0.90.0",
     "@types/node": "^25.3.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
@@ -68,6 +67,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "prepack": "rm -rf dist && tsc",
     "test": "vitest run",
     "lint": "tsc --noEmit"
   }