@quillmark/quiver 0.3.0 → 0.4.1

package/PROGRAM.md

@@ -83,27 +83,15 @@ Unknown fields in `Quiver.yaml` are a **validation error** (`quiver_invalid`). S
 - "Transport" is not a first-class concept; HTTP fetching is an internal
   detail of `fromBuilt`
 
-### 4) Multi-Quiver Composition with Deterministic Precedence
+### 4) Single-Quiver Scope (V1)
 
-`QuiverRegistry` accepts multiple quivers with explicit order.
+V1 has no multi-quiver composition layer. Each `Quiver` instance is
+independent: consumers load one quiver and call `resolve` / `getQuill` /
+`warm` directly on it. There is no `QuiverRegistry`.
 
-This registry/composition layer lives entirely in `@quillmark/quiver`; it is not a Quillmark engine feature.
-
-Precedence rule:
-
-- **Precedence is a hard filter**
-- Scan quivers in order
-- First quiver with any matching candidate wins
-- Choose highest matching version **within that quiver**
-
-Applies to:
-
-- unqualified refs (e.g. `usaf_memo`)
-- selector refs (e.g. `usaf_memo@1.2`)
-
-No global highest-across-all-quivers behavior.
-
-**Identity collision:** duplicate `Quiver.yaml.name` across composed quivers is an error in V1.
+If composition becomes a real use case, the additive path is a thin
+`Quiver.compose([a, b, ...])` factory that returns a quiver-shaped
+composite — it is intentionally out of scope for V1.
 
 ### 5) Semver Selector Rules Are Strict and Small
 
@@ -129,20 +117,35 @@ Canonical version format:
 
 Canonicalization:
 
-- resolve selector to canonical ref once per manifest snapshot
-- key internal caches by canonical ref
+- resolve selector to canonical ref once per call to `getQuill`
+- key the tree cache by canonical ref; key the quill cache by (engine, canonical-ref)
 
 ### 6) Warm/Prefetch Is Purely a Quiver Concern
 
-`warm()` remains a quiver-layer optimization:
+`warm()` is the network prefetch step. It fetches every quill's tree and
+populates the per-quiver tree cache. It does **not** materialize Quill
+instances and does **not** require an engine — `engine.quill(tree)` is
+microseconds and runs lazily inside `getQuill`. A subsequent `getQuill`
+reuses the cached tree, so the network fetch isn't paid twice.
+
+Tree cache lifecycle:
 
-- `warm()` warms all by default in V1
-- `resolve()` must work even if nothing is warmed
+- `warm()` populates the tree cache.
+- First `getQuill(ref, { engine })` reads the tree, materializes the
+  Quill via `engine.quill(tree)`, then evicts the tree so its bytes can
+  be GC'd. The materialized Quill is what's kept (per engine).
+- If `engine.quill` throws, the tree is retained so a retry skips the
+  network.
+- Repeated `getQuill` on the same engine hits the per-engine quill cache
+  — no tree access at all.
+- A subsequent `getQuill` for a different engine refetches the tree
+  (single-engine apps never pay this cost).
 
-Warm means "load/prepare quills and materialize render-ready instances",
-not "register in engine". There is no engine registration step anymore.
-Warm semantics are identical for source-loaded and built-output-loaded
-quivers; the loader hides the difference.
+Other invariants:
+
+- `resolve()` works whether or not anything is warmed.
+- Warm semantics are identical for source-loaded and built-output-loaded
+  quivers; the loader hides the difference.
 
 ### 7) Engine Boundary: New Canonical Contract (Node / JS–WASM only)
 
@@ -157,14 +160,14 @@ Important implications:
 - No engine quill registry in the JS binding; no `registerQuill`, `hasQuill`, or engine-level `render(doc)` in Quiver’s flow
 - Quiver owns mapping from canonical ref → in-memory tree → `Quill` instance
 - Cache optimization is in-process reuse of `Quill` instances, not registration checks
-- Path-based loading (`quill_from_path`) exists in **other** bindings only; in Node, Quiver reads files and assembles `tree` for `engine.quill(tree)` (see upstream `references/quillmark/docs/integration/javascript/api.md`)
+- Path-based loading (`quill_from_path`) exists in **other** bindings only; in Node, Quiver reads files and assembles `tree` for `engine.quill(tree)` (see the upstream `@quillmark/wasm` JS/WASM API docs)
 
 For advanced dynamic-asset behavior, defer to Quillmark’s JS/WASM docs; the default integration path here is `engine.quill` + `quill.render`.
 
 ### 8) Markdown and Ref Parsing Boundary
 
 - Markdown parsing does not require a quill registry: `Document.fromMarkdown(markdown)`
-- Quiver owns ref parsing and selector resolution for its own API (`resolve`, `warm`, validation)
+- Quiver owns ref parsing and selector resolution for its own API (`resolve`, `getQuill`, `warm`, validation)
 - QUILL field is informational at render time; Quiver routes to the intended quill explicitly without mutating the parsed document in V1
 
 Upstream behavior note:
@@ -254,13 +257,12 @@ V1 code catalog (closed set):
 | Code | Fires when |
 |---|---|
 | `invalid_ref` | Malformed ref string at `resolve()`/`warm()` boundary (fails `parseQuillRef`) |
-| `quill_not_found` | Selector did not match any quill in any composed quiver |
+| `quill_not_found` | Selector did not match any quill in the quiver |
 | `quiver_invalid` | `Quiver.yaml` or hashed manifest malformed, unknown field, non-canonical version on disk, or font/bundle hash mismatch |
 | `transport_error` | I/O failure: missing path, HTTP non-2xx, network error, permission error. Wraps underlying cause. |
-| `quiver_collision` | Two composed quivers share `Quiver.yaml.name` at registry construction |
 
 Notes:
-- `quill_not_found` is selector-resolution failure after quiver composition and precedence.
+- `quill_not_found` is selector-resolution failure within a quiver's catalog.
 - `transport_error` is artifact access failure (filesystem/HTTP/network/permissions), including missing packed files and HTTP 404.
 - Legacy categories such as `manifest_invalid`, `quill_load_failed`, and `backend_not_found` are folded into `quiver_invalid` or `transport_error` in V1.
 
@@ -386,43 +388,38 @@ class Quiver {
 
   readonly name: string; // from Quiver.yaml
 
-  // Read-only introspection and lazy tree access used by QuiverRegistry
-  // internally; also available for external debugging and tooling.
+  // Read-only introspection and lazy tree access; also used internally by
+  // resolve/getQuill/warm.
   quillNames(): string[];                                              // sorted lex
   versionsOf(name: string): string[];                                  // sorted desc
   loadTree(name: string, version: string): Promise<Map<string, Uint8Array>>;
-}
-```
-
-```ts
-class QuiverRegistry {
-  constructor(args: { engine: Quillmark; quivers: Quiver[] });
 
   // Selector ref -> canonical ref. Throws invalid_ref / quill_not_found.
   resolve(ref: string): Promise<string>;
 
-  // Canonical ref -> render-ready quill handle (materialized via engine.quill(tree), cached in-process).
-  getQuill(canonicalRef: string): Promise<Quill>;
+  // Selector or canonical ref -> render-ready quill handle (materialized via
+  // engine.quill(tree), cached per (engine, canonical-ref)).
+  getQuill(ref: string, opts: { engine: Quillmark }): Promise<Quill>;
 
-  // Warms every ref in every composed quiver. Fail-fast. Zero params in V1.
+  // Prefetches every quill tree (network-only; engine not required).
+  // Subsequent getQuill calls reuse the cached tree. Fail-fast.
   warm(): Promise<void>;
 }
 
 class QuiverError extends Error {
-  code: "invalid_ref" | "quill_not_found" | "quiver_invalid" | "transport_error" | "quiver_collision";
+  code: "invalid_ref" | "quill_not_found" | "quiver_invalid" | "transport_error";
   // plus contextual payload fields
 }
 ```
 
-**No render wrapper.** Callers invoke `quill.render(doc, opts?)` (and `quill.open(doc)` when needed) after `resolve()` + `getQuill()`. Quiver never mirrors Quillmark render APIs.
+**No render wrapper.** Callers invoke `quill.render(doc, opts?)` (and `quill.open(doc)` when needed) after `getQuill()`. Quiver never mirrors Quillmark render APIs.
 
-**Internal (not exported):** `QuiverManifest` (runtime shape), `parseQuillRef`, in-flight coalescing state, source-vs-built layout detection.
+**Internal (not exported):** `BuiltManifest` (runtime shape), `parseQuillRef`, in-flight coalescing state, source-vs-built layout detection.
 
 Hot-path flow:
 ```ts
 const doc = Document.fromMarkdown(md);
-const canonicalRef = await registry.resolve(doc.quillRef);
-const quill = await registry.getQuill(canonicalRef);
+const quill = await quiver.getQuill(doc.quillRef, { engine });
 const result = quill.render(doc, { format: "pdf" });
 ```
 
@@ -433,8 +430,8 @@ const result = quill.render(doc, { format: "pdf" });
 **Entrypoints:**
 - `@quillmark/quiver` (main, browser-safe): `Quiver` class with only
   `fromBuilt` functional (Node-only loaders/builder throw
-  `transport_error` if reached in browser), `QuiverRegistry`,
-  `QuiverError`, `QuillmarkLike`, `QuillLike`, shared types.
+  `transport_error` if reached in browser), `QuiverError`,
+  `QuillmarkLike`, `QuillLike`, shared types.
 - `@quillmark/quiver/node`: adds `Quiver.fromPackage`, `Quiver.fromDir`,
   `Quiver.build` behaviors. Single `Quiver` class — Node-only factories
   fail fast outside Node.
@@ -444,7 +441,7 @@ const result = quill.render(doc, { format: "pdf" });
   test runners wire their own loops against the main API.
 
 **Dependencies:**
-- Peer: `@quillmark/wasm@>=0.59.0-rc.2` with `Quillmark`, `Document.fromMarkdown`, `engine.quill(tree)`, and `quill.render(doc, opts?)` APIs.
+- Peer: `@quillmark/wasm@>=0.59.0` with `Quillmark`, `Document.fromMarkdown`, `engine.quill(tree)`, and `quill.render(doc, opts?)` APIs.
 - Runtime: `fflate ^0.8.2` for zip read/write (Node + browser)
 - Dev-only: `node:crypto` (MD5 hashing in `build()` — never reached at runtime)
 - No test-runner peer dependency; `/testing` uses `node:test` (built-in)
@@ -461,7 +458,7 @@ const result = quill.render(doc, { format: "pdf" });
 - inter-quiver dependency graph in `Quiver.yaml`
 - marketplace/discovery service
 - advanced warm strategies beyond API-compatible hooks
-- multi-quiver name-collision soft handling (V1 errors on duplicate `Quiver.yaml.name`)
+- multi-quiver composition (single quiver per consumer in V1)
 
 ---
 
@@ -472,22 +469,11 @@ All V1 planner questions resolved; implementation plan can proceed against the s
 1. ~~Final `Quiver` interface shape and transport factoring style~~ → Single `Quiver` class, three loaders (`fromPackage`, `fromDir`, `fromBuilt`) + one builder (`build`). Each loader names what it loads; no auto-detection.
 2. ~~Final `Quiver.yaml` schema and unknown-field policy~~ → See §2: alphanumeric `name` and optional tooling-only `description`. Unknown fields are `quiver_invalid`.
 3. ~~Canonical ref grammar and parser API contract~~ → Internal `parseQuillRef`, not exported. Selector syntax per §5. Throws `invalid_ref`.
-4. ~~Exact warning policy for shadowed refs across quivers~~ → No warnings in V1. Precedence is a hard filter (§4); duplicate quiver names error as `quiver_collision`.
+4. ~~Exact warning policy for shadowed refs across quivers~~ → N/A in V1: no multi-quiver composition layer; each `Quiver` instance is independent (§4).
 5. ~~Validation API shape consolidation~~ → No separate validation API. Validation errors surface as `QuiverError('quiver_invalid')` during load or `build()`.
 6. ~~Build output directory structure~~ → See "Runtime Artifact Format (normative)".
 7. ~~Node/browser entrypoint split~~ → See "Package Structure": main + `/node` subpath, single `Quiver` class.
-8. ~~Final exported type names~~ → `Quiver`, `QuiverRegistry`, `QuiverError`. Hot-path entry is `QuiverRegistry.resolve(ref)` + `QuiverRegistry.getQuill(canonicalRef)`.
-
----
-
-## References
-
-Local copies in this repo for `@quillmark/quiver` implementation:
-
-- `references/quillmark-registry/` — prior `@quillmark/registry` source and patterns to mine or replace
-- `references/quillmark/docs/integration/javascript/api.md` — JS/WASM API this package integrates with
-- `references/quillmark/prose/designs/WASM.md` — WASM binding shape
-- `references/quillmark/prose/taskings/quill_render_api.md` — upstream render API overhaul (cross-binding; use the JS/WASM sections for Node)
+8. ~~Final exported type names~~ → `Quiver`, `QuiverError`. Hot-path entry is `Quiver.getQuill(ref, { engine })`.
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # @quillmark/quiver
 
-Quiver registry and build tooling for Quillmark — load, compose, and build collections of quills for rendering with `@quillmark/wasm`.
+Load and build collections of quills for rendering with `@quillmark/wasm`.
 
 ## Install
 
@@ -51,19 +51,27 @@ the main API instead.
 
 ```ts
 import { Quillmark, Document } from "@quillmark/wasm";
-import { Quiver, QuiverRegistry } from "@quillmark/quiver/node";
-
-const quiver = await Quiver.fromPackage("@org/my-quiver");
+import { Quiver } from "@quillmark/quiver/node";
 
 const engine = new Quillmark();
-const registry = new QuiverRegistry({ engine, quivers: [quiver] });
+const quiver = await Quiver.fromPackage("@org/my-quiver");
 
 const doc = Document.fromMarkdown(markdownString);
-const canonicalRef = await registry.resolve(doc.quillRef);
-const quill = await registry.getQuill(canonicalRef);
+const quill = await quiver.getQuill(doc.quillRef, { engine });
 const result = quill.render(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.
+
+If you only need the canonical ref (without materializing), use `resolve`:
+
+```ts
+const canonicalRef = await quiver.resolve("memo"); // "memo@1.1.0"
+```
+
 ## Consuming a quiver (browser)
 
 Browsers cannot read the source layout directly, so build at deploy time and
@@ -81,10 +89,10 @@ await Quiver.build(
 
 ```ts
 // browser runtime
-import { Quiver, QuiverRegistry } from "@quillmark/quiver";
+import { Quiver } from "@quillmark/quiver";
 
 const quiver = await Quiver.fromBuilt("/quivers/my-quiver/");
-const registry = new QuiverRegistry({ engine, quivers: [quiver] });
+const quill = await quiver.getQuill(doc.quillRef, { engine });
 ```
 
 ## Advanced: pre-built distribution to a CDN
@@ -101,23 +109,20 @@ await Quiver.build("./my-quiver", "./dist/my-quiver");
 const quiver = await Quiver.fromBuilt("https://cdn.example.com/quivers/my-quiver/");
 ```
 
-## Warm (prefetch all quills)
+## Warm (prefetch all quill trees)
 
 ```ts
-await registry.warm();
+await quiver.warm();
 ```
 
-## Multi-quiver composition
+`warm()` is network-only: it fetches every quill's tree 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 fetch.
 
-Quivers are scanned in order. The first quiver with any matching candidate wins;
-the highest matching version within that quiver is returned.
-
-```ts
-const registry = new QuiverRegistry({
-  engine,
-  quivers: [primaryQuiver, fallbackQuiver],
-});
-```
+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.
 
 ## Error handling
 
@@ -127,7 +132,7 @@ All errors are instances of `QuiverError` with a `code` field.
 import { QuiverError } from "@quillmark/quiver";
 
 try {
-  const canonicalRef = await registry.resolve("unknown_quill");
+  await quiver.resolve("unknown_quill");
 } catch (err) {
   if (err instanceof QuiverError) {
     console.error(err.code);    // e.g. "quill_not_found"
@@ -137,7 +142,7 @@ try {
 }
 ```
 
-Error codes: `invalid_ref`, `quill_not_found`, `quiver_invalid`, `transport_error`, `quiver_collision`.
+Error codes: `invalid_ref`, `quill_not_found`, `quiver_invalid`, `transport_error`.
 
 ## Full specification
 

package/dist/engine-types.d.ts

@@ -1,18 +1,18 @@
 /**
- * Minimal structural types matching @quillmark/wasm >=0.57.0 (verified against 0.59.0-rc.2).
+ * Minimal structural types matching @quillmark/wasm >=0.59.0.
  *
  * Shape:
  *   class Quillmark { quill(tree: Map<string, Uint8Array>): Quill }
  *   class Quill     { render(doc, opts?): RenderResult; open(doc): RenderSession }
  *
- * Note: as of 0.59.0-rc.2 the first arg to render/open is a `Document` instance
- * (from `Document.fromMarkdown(...)`), not the old `ParsedDocument` interface.
- * Quiver keeps the arg typed as `unknown` so consumers of either shape (and
- * test doubles) satisfy the contract structurally.
+ * The first arg to `render`/`open` is a `Document` instance (from
+ * `Document.fromMarkdown(...)`). Quiver keeps the arg typed as `unknown` so
+ * consumers (and test doubles) satisfy the contract structurally without
+ * importing from @quillmark/wasm.
  *
- * These types are INTERNAL — never re-exported from index.ts. They exist so
- * registry.ts never imports from @quillmark/wasm directly and so test doubles
- * can satisfy the contract without pulling the real WASM module.
+ * These types are re-exported from `index.ts` so consumers can type their
+ * own engine wrappers / test doubles against them. Quiver itself never
+ * imports from @quillmark/wasm directly.
  *
  * Call-site note: Quiver never invokes `render` or `open` itself; consumers do
  * after `getQuill()`. The loose `unknown` parameter typing is intentional.

package/dist/engine-types.js

@@ -1,18 +1,18 @@
 /**
- * Minimal structural types matching @quillmark/wasm >=0.57.0 (verified against 0.59.0-rc.2).
+ * Minimal structural types matching @quillmark/wasm >=0.59.0.
  *
  * Shape:
  *   class Quillmark { quill(tree: Map<string, Uint8Array>): Quill }
  *   class Quill     { render(doc, opts?): RenderResult; open(doc): RenderSession }
  *
- * Note: as of 0.59.0-rc.2 the first arg to render/open is a `Document` instance
- * (from `Document.fromMarkdown(...)`), not the old `ParsedDocument` interface.
- * Quiver keeps the arg typed as `unknown` so consumers of either shape (and
- * test doubles) satisfy the contract structurally.
+ * The first arg to `render`/`open` is a `Document` instance (from
+ * `Document.fromMarkdown(...)`). Quiver keeps the arg typed as `unknown` so
+ * consumers (and test doubles) satisfy the contract structurally without
+ * importing from @quillmark/wasm.
  *
- * These types are INTERNAL — never re-exported from index.ts. They exist so
- * registry.ts never imports from @quillmark/wasm directly and so test doubles
- * can satisfy the contract without pulling the real WASM module.
+ * These types are re-exported from `index.ts` so consumers can type their
+ * own engine wrappers / test doubles against them. Quiver itself never
+ * imports from @quillmark/wasm directly.
  *
  * Call-site note: Quiver never invokes `render` or `open` itself; consumers do
  * after `getQuill()`. The loose `unknown` parameter typing is intentional.

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type QuiverErrorCode = "invalid_ref" | "quill_not_found" | "quiver_invalid" | "transport_error" | "quiver_collision";
+export type QuiverErrorCode = "invalid_ref" | "quill_not_found" | "quiver_invalid" | "transport_error";
 export declare class QuiverError extends Error {
     readonly code: QuiverErrorCode;
     /** Offending ref string, when available. */

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 export { QuiverError } from "./errors.js";
 export type { QuiverErrorCode } from "./errors.js";
 export { Quiver } from "./quiver.js";
-export { QuiverRegistry } from "./registry.js";
 export type { BuildOptions } from "./build.js";
 export type { QuillmarkLike, QuillLike } from "./engine-types.js";

package/dist/index.js

@@ -1,4 +1,3 @@
 // Main browser-safe entrypoint.
 export { QuiverError } from "./errors.js";
 export { Quiver } from "./quiver.js";
-export { QuiverRegistry } from "./registry.js";

package/dist/quiver.d.ts

@@ -5,6 +5,7 @@
  * (either source-backed or build-output-backed).
  */
 import type { BuildOptions } from "./build.js";
+import type { QuillmarkLike, QuillLike } from "./engine-types.js";
 /** @internal Internal loader strategy: source or build output. */
 export interface QuiverLoader {
     loadTree(name: string, version: string): Promise<Map<string, Uint8Array>>;
@@ -74,9 +75,47 @@ export declare class Quiver {
      * 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 is the registry's concern.
+     * 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").
+     *
+     * Selector forms: `name`, `name@x`, `name@x.y`, `name@x.y.z`. Picks the
+     * highest matching version in this quiver.
+     *
+     * Throws:
+     *   - `invalid_ref` if ref fails parseQuillRef
+     *   - `quill_not_found` if no version matches
+     */
+    resolve(ref: string): Promise<string>;
+    /**
+     * Returns a render-ready `Quill` for a ref (selector or canonical).
+     *
+     * 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.
+     *
+     * 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
+     */
+    getQuill(ref: string, opts: {
+        engine: QuillmarkLike;
+    }): Promise<QuillLike>;
+    /**
+     * 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.
+     */
+    warm(): Promise<void>;
 }

package/dist/quiver.js

@@ -6,10 +6,24 @@
  */
 import { QuiverError } from "./errors.js";
 import { assertNode } from "./assert-node.js";
+import { parseQuillRef } from "./ref.js";
+import { matchesSemverSelector, chooseHighestVersion } from "./semver.js";
 export class Quiver {
     name;
     #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.
+     */
+    #quillCache = new WeakMap();
+    /**
+     * 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.
+     */
+    #treeCache = new Map();
     /**
      * Private constructor — use static factory methods.
      * TS prevents external `new Quiver(...)` at compile time.
@@ -118,7 +132,8 @@ export class Quiver {
      * 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 is the registry's concern.
+     * 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.
      */
@@ -129,4 +144,110 @@ export class Quiver {
         }
         return this.#loader.loadTree(name, version);
     }
+    /**
+     * Resolves a selector ref → canonical ref (e.g. "memo" → "memo@1.1.0").
+     *
+     * Selector forms: `name`, `name@x`, `name@x.y`, `name@x.y.z`. Picks the
+     * highest matching version in this quiver.
+     *
+     * Throws:
+     *   - `invalid_ref` if ref fails parseQuillRef
+     *   - `quill_not_found` if no version matches
+     */
+    async resolve(ref) {
+        const parsed = parseQuillRef(ref);
+        const versions = this.#catalog.get(parsed.name);
+        if (versions && versions.length > 0) {
+            const candidates = parsed.selector === undefined
+                ? [...versions]
+                : versions.filter((v) => matchesSemverSelector(v, parsed.selector));
+            if (candidates.length > 0) {
+                // chooseHighestVersion returns null only for empty arrays; candidates is non-empty.
+                const winner = chooseHighestVersion(candidates);
+                return `${parsed.name}@${winner}`;
+            }
+        }
+        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).
+     *
+     * 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.
+     *
+     * 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
+     */
+    async getQuill(ref, opts) {
+        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);
+        if (entry === undefined) {
+            entry = this.#materializeQuill(canonicalRef, engine).catch((err) => {
+                perEngine.delete(canonicalRef);
+                throw err;
+            });
+            perEngine.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.
+     */
+    async #materializeQuill(canonicalRef, engine) {
+        const tree = await this.#getTreeCached(canonicalRef);
+        const quill = engine.quill(tree);
+        this.#treeCache.delete(canonicalRef);
+        return quill;
+    }
+    /**
+     * 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) {
+        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) => {
+                this.#treeCache.delete(canonicalRef);
+                throw err;
+            });
+            this.#treeCache.set(canonicalRef, entry);
+        }
+        return entry;
+    }
+    /**
+     * 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.
+     */
+    async warm() {
+        const promises = [];
+        for (const name of this.quillNames()) {
+            for (const version of this.versionsOf(name)) {
+                promises.push(this.#getTreeCached(`${name}@${version}`));
+            }
+        }
+        await Promise.all(promises);
+    }
 }

package/dist/testing.d.ts

@@ -9,7 +9,7 @@
  *
  *   import { Quillmark } from "@quillmark/wasm";
  *   import { runQuiverTests } from "@quillmark/quiver/testing";
- *   const engine = await Quillmark.load();
+ *   const engine = new Quillmark();
  *   runQuiverTests(import.meta.url, engine);
  *
  * Run with `node --test`.

package/dist/testing.js

@@ -9,14 +9,13 @@
  *
  *   import { Quillmark } from "@quillmark/wasm";
  *   import { runQuiverTests } from "@quillmark/quiver/testing";
- *   const engine = await Quillmark.load();
+ *   const engine = new Quillmark();
  *   runQuiverTests(import.meta.url, engine);
  *
  * Run with `node --test`.
  */
 import { describe, it, before } from "node:test";
 import { Quiver } from "./quiver.js";
-import { QuiverRegistry } from "./registry.js";
 /**
  * Registers a `node:test` describe block that validates every quill
  * version in the quiver at `metaUrlOrDir` against the provided engine.
@@ -29,11 +28,9 @@ import { QuiverRegistry } from "./registry.js";
  */
 export function runQuiverTests(metaUrlOrDir, engine) {
     describe("Quiver", () => {
-        let registry;
         let quiver;
         before(async () => {
             quiver = await Quiver.fromDir(metaUrlOrDir);
-            registry = new QuiverRegistry({ engine, quivers: [quiver] });
         });
         it("has at least one quill", () => {
             if (quiver.quillNames().length === 0) {
@@ -43,7 +40,7 @@ export function runQuiverTests(metaUrlOrDir, engine) {
         it("compiles every quill version without error", async () => {
             for (const name of quiver.quillNames()) {
                 for (const version of quiver.versionsOf(name)) {
-                    const quill = await registry.getQuill(`${name}@${version}`);
+                    const quill = await quiver.getQuill(`${name}@${version}`, { engine });
                     if (typeof quill.render !== "function") {
                         throw new Error(`${name}@${version}: engine returned non-conforming Quill`);
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/quiver",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Quiver registry and build tooling for Quillmark",
   "type": "module",
   "license": "MIT",

package/dist/registry.d.ts

@@ -1,39 +0,0 @@
-import type { QuillmarkLike, QuillLike } from "./engine-types.js";
-import type { Quiver } from "./quiver.js";
-export declare class QuiverRegistry {
-    #private;
-    constructor(args: {
-        engine: QuillmarkLike;
-        quivers: Quiver[];
-    });
-    /**
-     * Resolves a selector ref → canonical ref (e.g. "memo" → "memo@1.1.0").
-     *
-     * Applies multi-quiver precedence (§4): scan quivers in order, first quiver
-     * with any matching candidate wins, highest match within that quiver returned.
-     *
-     * Throws:
-     *   - `invalid_ref` if ref fails parseQuillRef
-     *   - `quill_not_found` if no quiver has a matching candidate
-     */
-    resolve(ref: string): Promise<string>;
-    /**
-     * Returns a render-ready QuillLike instance for a canonical ref.
-     * Materializes via engine.quill(tree) on first call; caches by canonical ref.
-     *
-     * Throws:
-     *   - `invalid_ref` if canonicalRef is not valid canonical x.y.z form
-     *   - `quill_not_found` if canonical ref doesn't map to a loaded quiver
-     *   - propagates I/O errors from loadTree unchanged
-     *   - propagates engine errors from engine.quill() unchanged (not wrapped)
-     */
-    getQuill(canonicalRef: string): Promise<QuillLike>;
-    /**
-     * Warms all quill refs across all composed quivers. Fail-fast.
-     *
-     * Calls loadTree + engine.quill(tree) for every known quill version in
-     * parallel. Already-cached refs resolve instantly (idempotent). Rejects on
-     * the first failure (Promise.all fail-fast semantics).
-     */
-    warm(): Promise<void>;
-}

package/dist/registry.js

@@ -1,115 +0,0 @@
-import { QuiverError } from "./errors.js";
-import { parseQuillRef } from "./ref.js";
-import { matchesSemverSelector, chooseHighestVersion } from "./semver.js";
-export class QuiverRegistry {
-    #engine;
-    #quivers;
-    /** Cache: canonical ref → pending or resolved Promise<QuillLike>. */
-    #cache = new Map();
-    constructor(args) {
-        this.#engine = args.engine;
-        // Validate no two quivers share Quiver.yaml.name → quiver_collision.
-        const seen = new Map();
-        for (const quiver of args.quivers) {
-            const existing = seen.get(quiver.name);
-            if (existing !== undefined) {
-                throw new QuiverError("quiver_collision", `Two quivers share the name "${quiver.name}": first quiver and a later quiver both declare this name. ` +
-                    `Quiver names must be unique within a registry.`, { quiverName: quiver.name });
-            }
-            seen.set(quiver.name, quiver.name);
-        }
-        this.#quivers = Object.freeze([...args.quivers]);
-    }
-    /**
-     * Resolves a selector ref → canonical ref (e.g. "memo" → "memo@1.1.0").
-     *
-     * Applies multi-quiver precedence (§4): scan quivers in order, first quiver
-     * with any matching candidate wins, highest match within that quiver returned.
-     *
-     * Throws:
-     *   - `invalid_ref` if ref fails parseQuillRef
-     *   - `quill_not_found` if no quiver has a matching candidate
-     */
-    async resolve(ref) {
-        // Throws invalid_ref on malformed input.
-        const parsed = parseQuillRef(ref);
-        for (const quiver of this.#quivers) {
-            const versions = quiver.versionsOf(parsed.name);
-            if (versions.length === 0)
-                continue;
-            // Filter by selector if present; otherwise all versions are candidates.
-            const candidates = parsed.selector === undefined
-                ? versions
-                : versions.filter((v) => matchesSemverSelector(v, parsed.selector));
-            if (candidates.length === 0)
-                continue;
-            // First quiver with any candidate wins — pick highest within that quiver.
-            const winner = chooseHighestVersion(candidates);
-            // chooseHighestVersion returns null only for empty arrays; candidates is non-empty.
-            return `${parsed.name}@${winner}`;
-        }
-        throw new QuiverError("quill_not_found", `No quill found for ref "${ref}" in any registered quiver.`, { ref });
-    }
-    /**
-     * Returns a render-ready QuillLike instance for a canonical ref.
-     * Materializes via engine.quill(tree) on first call; caches by canonical ref.
-     *
-     * Throws:
-     *   - `invalid_ref` if canonicalRef is not valid canonical x.y.z form
-     *   - `quill_not_found` if canonical ref doesn't map to a loaded quiver
-     *   - propagates I/O errors from loadTree unchanged
-     *   - propagates engine errors from engine.quill() unchanged (not wrapped)
-     */
-    async getQuill(canonicalRef) {
-        let entry = this.#cache.get(canonicalRef);
-        if (entry === undefined) {
-            entry = this.#loadQuill(canonicalRef).catch((err) => {
-                this.#cache.delete(canonicalRef);
-                throw err;
-            });
-            this.#cache.set(canonicalRef, entry);
-        }
-        return entry;
-    }
-    /** Internal: does the actual loading work for getQuill. */
-    async #loadQuill(canonicalRef) {
-        // Parse and validate canonical form (must be x.y.z).
-        const parsed = parseQuillRef(canonicalRef);
-        if (parsed.selectorDepth !== 3) {
-            throw new QuiverError("invalid_ref", `getQuill requires a canonical ref (x.y.z) but received "${canonicalRef}". ` +
-                `Use resolve() first to obtain a canonical ref.`, { ref: canonicalRef });
-        }
-        const version = parsed.selector;
-        // Find the first quiver that owns this exact (name, version) pair.
-        const owningQuiver = this.#quivers.find((q) => q.versionsOf(parsed.name).includes(version));
-        if (owningQuiver === undefined) {
-            throw new QuiverError("quill_not_found", `Quill "${canonicalRef}" was not found in any registered quiver.`, { ref: canonicalRef, version });
-        }
-        // Load the file tree — I/O errors propagate as-is.
-        const tree = await owningQuiver.loadTree(parsed.name, version);
-        // Materialize the Quill via the engine.
-        // Engine errors propagate unchanged — they are not QuiverErrors and we
-        // should not mask them. The caller's error-handling stack will see the
-        // engine's own error type directly.
-        const quill = this.#engine.quill(tree);
-        return quill;
-    }
-    /**
-     * Warms all quill refs across all composed quivers. Fail-fast.
-     *
-     * Calls loadTree + engine.quill(tree) for every known quill version in
-     * parallel. Already-cached refs resolve instantly (idempotent). Rejects on
-     * the first failure (Promise.all fail-fast semantics).
-     */
-    async warm() {
-        const promises = [];
-        for (const quiver of this.#quivers) {
-            for (const name of quiver.quillNames()) {
-                for (const version of quiver.versionsOf(name)) {
-                    promises.push(this.getQuill(`${name}@${version}`));
-                }
-            }
-        }
-        await Promise.all(promises);
-    }
-}