@quillmark/quiver 0.19.0 → 0.21.0

package/MIGRATION.md

@@ -0,0 +1,91 @@
+# Migrating `@quillmark/quiver`
+
+Upgrade notes per range. The [CHANGELOG](CHANGELOG.md) is the full record; this page is the subset that breaks a working consumer, ordered by how late you find out.
+
+## 0.16 → 0.19
+
+### Runtime, not build time
+
+Four removals leave valid JavaScript. A consumer on plain JS, or on TypeScript reaching these through an `any`, learns about them from a `TypeError` at runtime naming neither the version nor the replacement.
+
+**`Quiver.buildPackage(specifier, outDir)` and `Quiver.fromPackage(specifier)` are gone.** An npm-installed quiver is a directory, and resolving it belongs to the caller: the resolution base has to be your module, because under an isolated `node_modules` layout your dependencies are reachable from you and not from this package.
+
+```js
+// 0.16
+await Quiver.buildPackage('@org/my-quiver', './public/quills');
+const quiver = await Quiver.fromPackage('@org/my-quiver');
+
+// 0.19
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import { build, fromDir } from '@quillmark/quiver/node';
+
+const root = dirname(createRequire(import.meta.url).resolve('@org/my-quiver/Quiver.yaml'));
+await build(root, './public/quills');
+const quiver = await fromDir(root);
+```
+
+That resolution goes through the collection's `exports` map. A collection that declares one and does not expose `./Quiver.yaml` fails here with a module-resolution error naming neither the collection nor the convention; the fix is in the collection's `package.json`, not at your call site.
+
+**`quiver.warm()` is gone.** It prefetched every tree into a second cache that no longer exists. `getQuill` caches and coalesces per canonical ref, so prefetching is calling it early:
+
+```js
+const refs = quiver.quillNames().flatMap((n) => quiver.versionsOf(n).map((v) => `${n}@${v}`));
+await Promise.allSettled(refs.map((r) => quiver.getQuill(r)));
+```
+
+Skipping it costs one fetch on first open of each quill, cached from then on.
+
+**`Quiver.fromManifest(baseUrl, bytes)` is gone**, replaced by two doors that cover more than it did. Pass the whole artifact and fetch nothing, or seed what you hold and let the URL serve the rest:
+
+```js
+// 0.16
+const quiver = await Quiver.fromManifest('/quills/my-quiver/', manifestBytes);
+
+// 0.19 — whole artifact in hand, no filesystem, no fetch
+const quiver = await Quiver.fromBuiltFiles(artifactFiles);
+
+// 0.19 — hold the small documents, fetch the heavy ones
+const quiver = await Quiver.fromBuiltUrl('/quills/my-quiver/', {
+	seed: new Map([
+		['latest.json', pointerBytes],
+		[manifestName, manifestBytes]
+	])
+});
+```
+
+Keys are artifact-relative, as `build` writes them. `fromManifest` took manifest bytes and skipped the pointer; the seed takes any subset of the artifact, so it covers that and the case where the bundles are in hand too.
+
+**`quiver.resolve(ref)` is sync.** `await` on it still works, so this breaks only a call site that used the promise as one: `.then()`, `Promise.all([...])`, or a `.catch()` that now has a throw to catch instead of a rejection.
+
+### Rebuild every artifact
+
+Build output moved from MD5 to SHA-256, and the loader verifies fetched bytes against the digest in their name. An artifact packed by 0.16 fails to load under 0.19. Re-run `build`; nothing in the source layout changes.
+
+### The compiler-caught rest
+
+| 0.16                                                              | 0.19                                           |
+| ----------------------------------------------------------------- | ---------------------------------------------- |
+| `Quiver.fromDir`, `Quiver.fromBuiltDir`, `Quiver.build` (statics) | free functions from `@quillmark/quiver/node`   |
+| `Quiver._fromLoader`                                              | removed; construction is sealed                |
+| `BuildOptions`                                                    | removed; `build(src, out)` takes two arguments |
+| `@quillmark/quiver/preview`, `renderQuiverSamples`                | removed; `quillkit studio` answers live        |
+| `@quillmark/quiver/testing`, `runQuiverTests`                     | removed; `quillkit test` is the gate           |
+| `quiver` / `quillmark-quiver` bin                                 | removed; the verbs are `quillkit`'s            |
+| `quiver.config.js`                                                | `quillkit.config.js`                           |
+
+The `@quillmark/wasm` peer floor is `>=0.101.0-0`. That range carries its own boundary changes, several of which a type checker also misses; the ledger is [`DOCUMENT_MODEL.md`](../svelte/prose/canon/DOCUMENT_MODEL.md) in `@quillmark/svelte`.
+
+### Installing the tooling
+
+The bin left this package in 0.19. A collection that ran `quiver test` or `quillmark-quiver build` from its `scripts` installs `quillkit` and keeps depending on this package for the format its quiver is packed in:
+
+```sh
+npm install --save-dev @quillmark/quiver @quillmark/wasm quillkit
+```
+
+```jsonc
+{
+	"scripts": { "test": "quillkit test", "build": "quillkit build" }
+}
+```

package/README.md

@@ -8,17 +8,20 @@ Load and build collections of quills for rendering with `@quillmark/wasm`.
 npm install @quillmark/quiver @quillmark/wasm
 ```
 
+Upgrading from an earlier version: [`MIGRATION.md`](MIGRATION.md).
+
 ## Loading a quiver
 
 A quiver has one authored shape, the **source layout** (`Quiver.yaml` at the package root, quills under `quills/<name>/<x.y.z>/`), published as an npm package. Browsers cannot read that layout, so `build(src, out)` packs it at deploy time and the output is served as static assets. Each loader names exactly what it reads; there is no auto-detection.
 
-| Loader                     | Reads                   | Import                   |
-| -------------------------- | ----------------------- | ------------------------ |
-| `fromDir(path)`            | the source layout       | `@quillmark/quiver/node` |
-| `fromBuiltDir(path)`       | build output, off disk  | `@quillmark/quiver/node` |
-| `Quiver.fromBuiltUrl(url)` | build output, over HTTP | `@quillmark/quiver`      |
+| Loader                         | Reads                     | Import                   |
+| ------------------------------ | ------------------------- | ------------------------ |
+| `fromDir(path)`                | the source layout         | `@quillmark/quiver/node` |
+| `fromBuiltDir(path)`           | build output, off disk    | `@quillmark/quiver/node` |
+| `Quiver.fromBuiltUrl(url)`     | build output, over HTTP   | `@quillmark/quiver`      |
+| `Quiver.fromBuiltFiles(files)` | build output, from memory | `@quillmark/quiver`      |
 
-The filesystem factories are free functions from `/node`; the one that reaches across HTTP is a static on `Quiver`. Importing `/node` adds nothing to the class, so a bundler drops the verbs you do not call.
+The filesystem factories are free functions from `/node`; the two that reach no filesystem are statics on `Quiver`. Importing `/node` adds nothing to the class, so a bundler drops the verbs you do not call.
 
 ## Consuming a quiver (Node)
 
@@ -27,19 +30,20 @@ A quiver installed from npm is a directory like any other. Resolve its root from
 ```ts
 import { createRequire } from 'node:module';
 import { dirname } from 'node:path';
-import { Engine, Document } from '@quillmark/wasm';
+import { Engine, init } from '@quillmark/wasm';
 import { fromDir } from '@quillmark/quiver/node';
 
 const root = dirname(createRequire(import.meta.url).resolve('@org/my-quiver/Quiver.yaml'));
 const quiver = await fromDir(root);
 const engine = new Engine();
 
+const { Document } = await init(); // the gate is the only door to Document
 const doc = Document.fromMarkdown(markdownString);
 const quill = await quiver.getQuill(doc.quillRef);
 const result = await engine.render(quill, doc, { format: 'pdf' });
 ```
 
-`getQuill(ref)` is the only way to obtain a quill from a quiver, and the only entry point most consumers need. It accepts selector refs (`"memo"`, `"memo@1"`) and canonical ones (`"memo@1.0.0"`), resolves the selector, materializes the quill via `Quill.fromTree`, and caches one instance per canonical ref for the quiver's lifetime; concurrent calls for the same ref coalesce into a single load.
+`getQuill(ref)` is the only way to obtain a quill from a quiver, and the only entry point most consumers need. It accepts selector refs (`"memo"`, `"memo@1"`) and canonical ones (`"memo@1.0.0"`), resolves the selector, materializes the quill via `Quill.fromTree`, and caches one instance per canonical ref for the quiver's lifetime; concurrent calls for the same ref coalesce into a single load. It awaits `init()` itself, so instantiating the core is not a precondition of calling it.
 
 That quill is **borrowed, not owned**: every caller asking for that ref gets the same instance, so `free()` on it hands the next caller a freed handle. Code that owns its quill mints one from `(await quiver.getQuill(ref)).toTree()` and frees that.
 
@@ -66,12 +70,13 @@ await build('./node_modules/@org/my-quiver', './public/quivers/my-quiver');
 
 ```ts
 // browser runtime
-import { Engine, Document } from '@quillmark/wasm';
+import { Engine, init } from '@quillmark/wasm';
 import { Quiver } from '@quillmark/quiver';
 
 const quiver = await Quiver.fromBuiltUrl('/quivers/my-quiver/');
 const engine = new Engine();
 
+const { Document } = await init(); // the gate is the only door to Document
 const doc = Document.fromMarkdown(markdownString);
 const quill = await quiver.getQuill(doc.quillRef);
 const result = await engine.render(quill, doc, { format: 'pdf' });
@@ -90,6 +95,31 @@ import { fromBuiltDir } from '@quillmark/quiver/node';
 const quiver = await fromBuiltDir('./static/quills/my-quiver');
 ```
 
+## Server-side runtime (no filesystem)
+
+A serverless function's packed artifact is not on a path the invocation can read, so `fromBuiltDir` cannot see it. Hand over the bytes instead, keyed by artifact-relative path as `build` writes them (`latest.json`, `manifest.<digest>.json`, `<name>@<x.y.z>.<digest>.zip`, `store/<hash>`):
+
+```ts
+import { Quiver } from '@quillmark/quiver';
+
+const quiver = await Quiver.fromBuiltFiles(artifactFiles); // Map<string, Uint8Array>
+```
+
+Nothing is fetched, so nothing self-fetches over your own load balancer. The map must carry the whole artifact; a path it lacks is a `transport_error` naming that path.
+
+Where inlining the bundles and fonts is not practical, hold the two small documents and let the host serve the rest:
+
+```ts
+const quiver = await Quiver.fromBuiltUrl('/quills/my-quiver/', {
+	seed: new Map([
+		['latest.json', pointerBytes],
+		[manifestName, manifestBytes]
+	])
+});
+```
+
+The seed answers first and the URL serves what it does not carry. Seeding `latest.json` also settles which catalog the process reads at deploy time rather than at cache-revalidation time. Seeded bytes are checked against the digest in their name exactly as fetched bytes are.
+
 ## The `latest.json` pointer
 
 `Quiver.fromBuiltUrl(url)` first fetches `<url>/latest.json`, a stable-named pointer to the current manifest. Everything behind that pointer is content-addressed and checked against the digest in its name; the pointer itself is not, so a cache layer can serve a stale one and silently pin the client to the old catalog. It is therefore the one request fetched `no-cache` (revalidate with the origin; a 304 still serves from disk), which closes the browser-cache layer. A stale CDN edge is answered by that host's cache headers.

package/dist/build.js

@@ -77,12 +77,9 @@ export async function buildQuiver(sourceDir, outDir) {
     const { existsSync } = await import('node:fs');
     const { createHash } = await import('node:crypto');
     const { scanSourceQuiver, readQuillTree } = await import('./source-loader.js');
-    // 0. Three trees get cleared here; refuse the paths where that deletes the
-    //    caller instead of a previous build.
     assertSafeOutDir(path, sourceDir, outDir);
     const out = resolve(outDir);
     const { stage, prev } = stagesOf(out);
-    // 1. Scan + validate source quiver (throws quiver_invalid on bad input).
     const { meta, catalog } = await scanSourceQuiver(sourceDir);
     try {
         await packGeneration();
@@ -103,7 +100,6 @@ export async function buildQuiver(sourceDir, outDir) {
      * wide against the seconds a build takes.
      */
     async function packGeneration() {
-        // 2. Clear and recreate the staged tree + its store/.
         try {
             await rm(stage, { recursive: true, force: true });
             await mkdir(join(stage, 'store'), { recursive: true });
@@ -111,14 +107,11 @@ export async function buildQuiver(sourceDir, outDir) {
         catch (err) {
             throw new QuiverError('transport_error', `Failed to prepare output directory "${outDir}": ${err.message}`, { cause: err });
         }
-        // 3. Process each quill version.
         const manifestQuills = [];
         for (const [quillName, versions] of catalog) {
             for (const version of versions) {
                 const quillDir = join(sourceDir, 'quills', quillName, version);
-                // a. Read quill file tree.
                 const tree = await readQuillTree(quillDir);
-                // b. Partition fonts vs content.
                 const fontEntries = [];
                 const contentEntries = [];
                 for (const [path, bytes] of tree) {
@@ -129,7 +122,6 @@ export async function buildQuiver(sourceDir, outDir) {
                         contentEntries.push([path, bytes]);
                     }
                 }
-                // c. Dehydrate fonts into store/.
                 const fonts = {};
                 for (const [path, bytes] of fontEntries) {
                     // Full width: the store is keyed by hash, so two distinct fonts
@@ -143,30 +135,25 @@ export async function buildQuiver(sourceDir, outDir) {
                     }
                     fonts[path] = hash;
                 }
-                // d. Zip content files (deterministic: sorted paths, fixed mtime).
                 const contentRecord = {};
                 for (const [path, bytes] of contentEntries) {
                     contentRecord[path] = bytes;
                 }
                 const zipBytes = packFiles(contentRecord);
-                // e–f. Compute bundle hash and name.
                 const bundleHash = createHash('sha256')
                     .update(zipBytes)
                     .digest('hex')
                     .slice(0, NAME_DIGEST_LENGTH);
                 const bundleName = `${quillName}@${version}.${bundleHash}.zip`;
-                // g. Write bundle zip.
                 try {
                     await writeFile(join(stage, bundleName), zipBytes);
                 }
                 catch (err) {
                     throw new QuiverError('transport_error', `Failed to write bundle "${join(outDir, bundleName)}": ${err.message}`, { cause: err });
                 }
-                // h. Record manifest entry.
                 manifestQuills.push({ name: quillName, version, bundle: bundleName, fonts });
             }
         }
-        // 4–8. Build and write hashed manifest.
         const manifest = {
             version: 1,
             name: meta.name,
@@ -184,8 +171,8 @@ export async function buildQuiver(sourceDir, outDir) {
         catch (err) {
             throw new QuiverError('transport_error', `Failed to write manifest "${join(outDir, manifestFileName)}": ${err.message}`, { cause: err });
         }
-        // 9–10. Write stable pointer latest.json. The format is stamped here and read first,
-        //       so a client older than the tree says so rather than misreading it.
+        // The format is stamped here and read first, so a client older than the tree
+        // says so rather than misreading it.
         const pointer = { format: POINTER_FORMAT, manifest: manifestFileName };
         try {
             await writeFile(join(stage, 'latest.json'), JSON.stringify(pointer), 'utf-8');
@@ -193,9 +180,8 @@ export async function buildQuiver(sourceDir, outDir) {
         catch (err) {
             throw new QuiverError('transport_error', `Failed to write pointer "${join(outDir, 'latest.json')}": ${err.message}`, { cause: err });
         }
-        // 11. Move the generation in. `prev` is cleared first: a rename onto a
-        //     non-empty directory fails, and the tree left by an interrupted run is
-        //     one.
+        // `prev` is cleared first: a rename onto a non-empty directory fails, and the
+        // tree left by an interrupted run is one.
         try {
             await mkdir(dirname(out), { recursive: true });
             await rm(prev, { recursive: true, force: true });

package/dist/built-loader.d.ts

@@ -22,12 +22,5 @@ export interface BuiltTransport {
 export interface FetchOptions {
     revalidate?: boolean;
 }
-/**
- * Load a build-output quiver via the given transport.
- *
- * 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.
- */
+/** Load a build-output quiver via the given transport. */
 export declare function loadBuiltQuiver(transport: BuiltTransport): Promise<Quiver>;

package/dist/built-loader.js

@@ -68,15 +68,12 @@ class BuiltLoader {
         // The catalog the outer Quiver resolves against derives from this index,
         // so every ref reaching here has an entry.
         const entry = this.index.get(`${name}@${version}`);
-        // 1. Fetch + unpack bundle zip.
         const zipBytes = await fetchVerified(this.transport, entry.bundle, digestOfName(BUNDLE_FILENAME_RE, entry.bundle, 'bundle filename'));
         const files = unpackFiles(zipBytes);
-        // 2. Rehydrate fonts from store (coalesced).
         const fontEntries = Object.entries(entry.fonts);
         await Promise.all(fontEntries.map(async ([path, hash]) => {
             files[path] = await this.fetchFont(hash);
         }));
-        // 3. Convert to Map.
         return new Map(Object.entries(files));
     }
     /**
@@ -116,7 +113,7 @@ function parsePointer(raw) {
         throw new QuiverError('quiver_invalid', 'latest.json must be a JSON object');
     }
     const obj = parsed;
-    // The format, read before anything is believed about the rest. An unknown key is NOT
+    // The format, read before anything is believed about the rest. An unknown key is not
     // a failure here: this is the document a newer format announces itself on, and a
     // reader rejecting what it does not recognise refuses the announcement too. Absent
     // means a build from before the marker (`format.ts`).
@@ -215,17 +212,10 @@ function catalogOf(index) {
     return catalog;
 }
 // ─── Main entry point ─────────────────────────────────────────────────────────
-/**
- * Load a build-output quiver via the given transport.
- *
- * 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.
- */
+/** Load a build-output quiver via the given transport. */
 export async function loadBuiltQuiver(transport) {
-    // 1. Fetch and parse pointer. It is the one name that is not
-    //    content-addressed, so it is also the one fetch that must revalidate.
+    // The pointer is the one name that is not content-addressed, so it is also the
+    // one fetch that must revalidate.
     let pointerBytes;
     try {
         pointerBytes = await transport.fetchBytes('latest.json', { revalidate: true });
@@ -237,7 +227,6 @@ export async function loadBuiltQuiver(transport) {
     }
     const manifestFileName = parsePointer(new TextDecoder().decode(pointerBytes));
     const manifestDigest = digestOfName(MANIFEST_FILENAME_RE, manifestFileName, 'Pointer manifest filename');
-    // 2. Fetch and parse manifest.
     let manifestBytes;
     try {
         manifestBytes = await fetchVerified(transport, manifestFileName, manifestDigest);
@@ -247,7 +236,6 @@ export async function loadBuiltQuiver(transport) {
             throw err;
         throw new QuiverError('transport_error', `Failed to fetch manifest "${manifestFileName}": ${err.message}`, { cause: err });
     }
-    // 3–4. Validate manifest + assemble catalog/loader.
     const manifest = parseManifest(new TextDecoder().decode(manifestBytes));
     const index = new Map();
     for (const entry of manifest.quills) {

package/dist/format.d.ts

@@ -3,7 +3,7 @@
  * (QUIVER §"The pointer" for why the pointer carries it and reads past keys it does not
  * know).
  *
- * It moves when a reader assuming it would MISREAD a tree rather than fail on it: a
+ * It moves when a reader assuming it would misread a tree rather than fail on it: a
  * renamed pointer field, a second pointer, a store keyed by something other than the
  * full hash. A change confined to the manifest's own shape moves the manifest's
  * `version` instead.

package/dist/format.js

@@ -3,7 +3,7 @@
  * (QUIVER §"The pointer" for why the pointer carries it and reads past keys it does not
  * know).
  *
- * It moves when a reader assuming it would MISREAD a tree rather than fail on it: a
+ * It moves when a reader assuming it would misread a tree rather than fail on it: a
  * renamed pointer field, a second pointer, a store keyed by something other than the
  * full hash. A change confined to the manifest's own shape moves the manifest's
  * `version` instead.

package/dist/node.d.ts

@@ -4,9 +4,8 @@
  * from the main entry, unmodified. Importing this module installs nothing, so
  * the import path is the whole contract and a bundler drops what is not called.
  *
- * Bundler note: this entry pulls in `./source-loader.js`, `./build.js`, and
- * `./transports/fs-built-transport.js`, all of which statically import `node:*`
- * builtins. Browser bundles must never reach it. The main entry (`./index.js`)
+ * The modules behind these factories statically import `node:*` builtins, so a
+ * browser bundle must never reach this entry. The main entry (`./index.js`)
  * makes no static or dynamic reference to it.
  */
 import { Quiver } from './quiver.js';

package/dist/node.js

@@ -4,9 +4,8 @@
  * from the main entry, unmodified. Importing this module installs nothing, so
  * the import path is the whole contract and a bundler drops what is not called.
  *
- * Bundler note: this entry pulls in `./source-loader.js`, `./build.js`, and
- * `./transports/fs-built-transport.js`, all of which statically import `node:*`
- * builtins. Browser bundles must never reach it. The main entry (`./index.js`)
+ * The modules behind these factories statically import `node:*` builtins, so a
+ * browser bundle must never reach this entry. The main entry (`./index.js`)
  * makes no static or dynamic reference to it.
  */
 import { createQuiver } from './quiver.js';

package/dist/quiver-yaml.d.ts

@@ -1,9 +1,7 @@
 /**
- * Internal parser/validator for Quiver.yaml files.
- *
- * Uses the `yaml` npm package for robust YAML parsing. Quiver.yaml has a
- * simple two-field schema (name, description), but using a proper YAML parser
- * ensures correct handling of quoting, escaping, and multi-line strings.
+ * Internal parser/validator for Quiver.yaml: two fields, `name` and
+ * `description`, strict about everything else. Parsed through the `yaml`
+ * package, so quoting, escaping and multi-line strings behave as YAML.
  */
 export interface QuiverMeta {
     name: string;

package/dist/quiver-yaml.js

@@ -1,9 +1,7 @@
 /**
- * Internal parser/validator for Quiver.yaml files.
- *
- * Uses the `yaml` npm package for robust YAML parsing. Quiver.yaml has a
- * simple two-field schema (name, description), but using a proper YAML parser
- * ensures correct handling of quoting, escaping, and multi-line strings.
+ * Internal parser/validator for Quiver.yaml: two fields, `name` and
+ * `description`, strict about everything else. Parsed through the `yaml`
+ * package, so quoting, escaping and multi-line strings behave as YAML.
  */
 import { parse as parseYaml } from 'yaml';
 import { QuiverError } from './errors.js';
@@ -32,13 +30,11 @@ export function parseQuiverYaml(raw) {
         throw new QuiverError('quiver_invalid', `Quiver.yaml: expected a mapping at the top level, got ${Array.isArray(parsed) ? 'array' : String(parsed)}`);
     }
     const doc = parsed;
-    // Check for unknown fields (strict mode)
     for (const key of Object.keys(doc)) {
         if (!KNOWN_FIELDS.has(key)) {
             throw new QuiverError('quiver_invalid', `Quiver.yaml: unknown field "${key}" — only "name" and "description" are valid in V1`);
         }
     }
-    // Validate `name`
     if (!('name' in doc)) {
         throw new QuiverError('quiver_invalid', `Quiver.yaml: required field "name" is missing`);
     }
@@ -49,7 +45,6 @@ export function parseQuiverYaml(raw) {
     if (!NAME_RE.test(name)) {
         throw new QuiverError('quiver_invalid', `Quiver.yaml: "name" value "${name}" contains invalid characters — only [A-Za-z0-9_-] are allowed`);
     }
-    // Validate optional `description`
     if ('description' in doc && doc['description'] !== undefined) {
         if (typeof doc['description'] !== 'string') {
             throw new QuiverError('quiver_invalid', `Quiver.yaml: "description" must be a string if present, got ${typeof doc['description']}`);

package/dist/quiver.d.ts

@@ -1,14 +1,13 @@
 /**
- * Quiver — primary runtime abstraction for a collection of quills.
+ * A collection of quills, addressed by ref. One class over a composed
+ * `QuiverLoader`, source-backed or built, so what a quiver reads is the loader's
+ * business and never the class's.
  *
- * Polymorphism via composition: internally stores a pluggable loader
- * (either source-backed or build-output-backed).
- *
- * This module is browser-safe: only `fromBuiltUrl` and the instance API live
- * here. The filesystem factories are free functions in `./node.js`; the class
- * is the same either way.
+ * Browser-safe: only `fromBuiltUrl`, `fromBuiltFiles` and the instance API live
+ * here. The filesystem factories are free functions in `./node.js`; the class is
+ * the same either way.
  */
-import { Quill } from '@quillmark/wasm';
+import type { Quill } from '@quillmark/wasm';
 /** Loader strategy: source or build output. Package-internal. */
 export interface QuiverLoader {
     loadTree(name: string, version: string): Promise<Map<string, Uint8Array>>;
@@ -24,8 +23,8 @@ export declare class Quiver {
     readonly name: string;
     /**
      * Private constructor. A Quiver comes from a factory (`Quiver.fromBuiltUrl`,
-     * or `fromDir` / `fromBuiltDir` from `@quillmark/quiver/node`), which is what
-     * names the thing being read.
+     * `Quiver.fromBuiltFiles`, or `fromDir` / `fromBuiltDir` from
+     * `@quillmark/quiver/node`), which is what names the thing being read.
      */
     private constructor();
     /**
@@ -35,10 +34,37 @@ export declare class Quiver {
      * environments. `file://` URLs are rejected — to load build output from
      * disk in Node, use `fromBuiltDir(path)` from `@quillmark/quiver/node`.
      *
+     * `seed` answers for the artifact bytes the caller already holds, keyed by
+     * artifact-relative path; the URL serves the rest. Seeding `latest.json`
+     * settles which catalog this process reads at deploy time rather than at
+     * cache-revalidation time. Seeded bytes are digest-checked as fetched ones
+     * are.
+     *
      * Throws `transport_error` on network/HTTP failure, `quiver_invalid`
      * on format errors.
      */
-    static fromBuiltUrl(url: string): Promise<Quiver>;
+    static fromBuiltUrl(url: string, opts?: {
+        seed?: ReadonlyMap<string, Uint8Array>;
+    }): Promise<Quiver>;
+    /**
+     * Browser-safe factory. Loads build output from the bytes themselves, keyed
+     * by artifact-relative path (`latest.json`, `manifest.<digest>.json`,
+     * `<name>@<x.y.z>.<digest>.zip`, `store/<hash>`) — the shape `build` writes
+     * and `fromBuiltDir` reads back.
+     *
+     * Nothing is fetched, so a runtime whose artifact is not on a path it can
+     * read (a serverless function, a bundler that inlines it, a test) reaches
+     * one without fetching its own static output back over its own load
+     * balancer.
+     *
+     * The map must carry the whole artifact; a missing path is a
+     * `transport_error` naming it. To hold part and fetch the rest, pass the map
+     * as `fromBuiltUrl`'s `seed`.
+     *
+     * Throws `quiver_invalid` on format errors, `transport_error` on a path the
+     * map does not carry.
+     */
+    static fromBuiltFiles(files: ReadonlyMap<string, Uint8Array>): Promise<Quiver>;
     /** Returns all known quill names, sorted lexicographically. */
     quillNames(): string[];
     /**
@@ -74,7 +100,7 @@ export declare class Quiver {
      * first. Materializes once and caches per canonical ref — concurrent calls
      * coalesce into a single load.
      *
-     * BORROWED, not handed over: the quill is the quiver's, shared with every
+     * Borrowed, not handed over: the quill is the quiver's, shared with every
      * other caller for the same ref, and lives as long as the quiver. Do not
      * `free()` it: the next `getQuill` for that ref would hand out a freed
      * handle. A caller wanting one of its own mints it from `.toTree()`.

package/dist/quiver.js

@@ -1,15 +1,14 @@
 /**
- * Quiver — primary runtime abstraction for a collection of quills.
+ * A collection of quills, addressed by ref. One class over a composed
+ * `QuiverLoader`, source-backed or built, so what a quiver reads is the loader's
+ * business and never the class's.
  *
- * Polymorphism via composition: internally stores a pluggable loader
- * (either source-backed or build-output-backed).
- *
- * This module is browser-safe: only `fromBuiltUrl` and the instance API live
- * here. The filesystem factories are free functions in `./node.js`; the class
- * is the same either way.
+ * Browser-safe: only `fromBuiltUrl`, `fromBuiltFiles` and the instance API live
+ * here. The filesystem factories are free functions in `./node.js`; the class is
+ * the same either way.
  */
 import { QuiverError } from './errors.js';
-import { Quill } from '@quillmark/wasm';
+import { init } from '@quillmark/wasm';
 import { parseQuillRef } from './ref.js';
 import { matchesSemverSelector, chooseHighestVersion } from './semver.js';
 /**
@@ -23,7 +22,7 @@ export class Quiver {
     #catalog;
     #loader;
     /**
-     * Cache of materialized quills, keyed by canonical ref. A `Quill` is now
+     * Cache of materialized quills, keyed by canonical ref. A `Quill` is
      * 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.
@@ -31,8 +30,8 @@ export class Quiver {
     #quillCache = new Map();
     /**
      * Private constructor. A Quiver comes from a factory (`Quiver.fromBuiltUrl`,
-     * or `fromDir` / `fromBuiltDir` from `@quillmark/quiver/node`), which is what
-     * names the thing being read.
+     * `Quiver.fromBuiltFiles`, or `fromDir` / `fromBuiltDir` from
+     * `@quillmark/quiver/node`), which is what names the thing being read.
      */
     constructor(name, catalog, loader) {
         this.name = name;
@@ -49,17 +48,49 @@ export class Quiver {
      * environments. `file://` URLs are rejected — to load build output from
      * disk in Node, use `fromBuiltDir(path)` from `@quillmark/quiver/node`.
      *
+     * `seed` answers for the artifact bytes the caller already holds, keyed by
+     * artifact-relative path; the URL serves the rest. Seeding `latest.json`
+     * settles which catalog this process reads at deploy time rather than at
+     * cache-revalidation time. Seeded bytes are digest-checked as fetched ones
+     * are.
+     *
      * Throws `transport_error` on network/HTTP failure, `quiver_invalid`
      * on format errors.
      */
-    static async fromBuiltUrl(url) {
+    static async fromBuiltUrl(url, opts) {
         if (url.startsWith('file://')) {
             throw new QuiverError('transport_error', `Quiver.fromBuiltUrl requires an http(s):// or origin-relative URL; got "${url}". For local build output, use import { fromBuiltDir } from '@quillmark/quiver/node'.`);
         }
         const { HttpTransport } = await import('./transports/http-transport.js');
         const { loadBuiltQuiver } = await import('./built-loader.js');
-        const transport = new HttpTransport(url);
-        return loadBuiltQuiver(transport);
+        const http = new HttpTransport(url);
+        if (opts?.seed === undefined)
+            return loadBuiltQuiver(http);
+        const { MemoryTransport } = await import('./transports/memory-transport.js');
+        return loadBuiltQuiver(new MemoryTransport(opts.seed, http));
+    }
+    /**
+     * Browser-safe factory. Loads build output from the bytes themselves, keyed
+     * by artifact-relative path (`latest.json`, `manifest.<digest>.json`,
+     * `<name>@<x.y.z>.<digest>.zip`, `store/<hash>`) — the shape `build` writes
+     * and `fromBuiltDir` reads back.
+     *
+     * Nothing is fetched, so a runtime whose artifact is not on a path it can
+     * read (a serverless function, a bundler that inlines it, a test) reaches
+     * one without fetching its own static output back over its own load
+     * balancer.
+     *
+     * The map must carry the whole artifact; a missing path is a
+     * `transport_error` naming it. To hold part and fetch the rest, pass the map
+     * as `fromBuiltUrl`'s `seed`.
+     *
+     * Throws `quiver_invalid` on format errors, `transport_error` on a path the
+     * map does not carry.
+     */
+    static async fromBuiltFiles(files) {
+        const { MemoryTransport } = await import('./transports/memory-transport.js');
+        const { loadBuiltQuiver } = await import('./built-loader.js');
+        return loadBuiltQuiver(new MemoryTransport(files));
     }
     /** Returns all known quill names, sorted lexicographically. */
     quillNames() {
@@ -114,7 +145,7 @@ export class Quiver {
      * first. Materializes once and caches per canonical ref — concurrent calls
      * coalesce into a single load.
      *
-     * BORROWED, not handed over: the quill is the quiver's, shared with every
+     * Borrowed, not handed over: the quill is the quiver's, shared with every
      * other caller for the same ref, and lives as long as the quiver. Do not
      * `free()` it: the next `getQuill` for that ref would hand out a freed
      * handle. A caller wanting one of its own mints it from `.toTree()`.
@@ -147,10 +178,17 @@ export class Quiver {
      *
      * Every caller arrives through `resolve` or the catalog itself, so the ref is
      * catalog-backed by construction and the loader needs no gate.
+     *
+     * `init()` is the only door to `Quill`, awaited here rather than left a
+     * precondition of `getQuill`. The gate is memoized, so this is one instantiation
+     * across every caller, overlapped with the load that pays for it.
      */
     async #materializeQuill(canonicalRef) {
         const at = canonicalRef.indexOf('@');
-        const tree = await this.#loader.loadTree(canonicalRef.slice(0, at), canonicalRef.slice(at + 1));
+        const [{ Quill }, tree] = await Promise.all([
+            init(),
+            this.#loader.loadTree(canonicalRef.slice(0, at), canonicalRef.slice(at + 1))
+        ]);
         return Quill.fromTree(tree);
     }
 }

package/dist/ref.d.ts

@@ -1,7 +1,7 @@
 /** Internal parsed representation of a quill reference. */
 export interface ParsedQuillRef {
     name: string;
-    /** Undefined = "highest in first-winning quiver". */
+    /** Undefined selects the highest version present. */
     selector?: string;
     /** Selector part count: 1 = `x`, 2 = `x.y`, 3 = `x.y.z` (exact). */
     selectorDepth?: 1 | 2 | 3;

package/dist/ref.js

@@ -12,18 +12,15 @@ export function parseQuillRef(ref) {
     }
     const atIndex = ref.indexOf('@');
     if (atIndex === 0) {
-        // Starts with @, no name
         throw new QuiverError('invalid_ref', `Invalid ref: missing name in "${ref}"`, { ref });
     }
     if (atIndex === -1) {
-        // No selector — just a name
         const name = ref;
         if (!NAME_RE.test(name)) {
             throw new QuiverError('invalid_ref', `Invalid ref: name "${name}" contains invalid characters`, { ref });
         }
         return { name };
     }
-    // Has @
     const name = ref.slice(0, atIndex);
     const selector = ref.slice(atIndex + 1);
     if (!name) {

package/dist/source-loader.d.ts

@@ -1,8 +1,6 @@
 /**
- * Internal filesystem scanner for Source Quiver layout.
- *
- * Uses Node.js `fs/promises` — this module must only be imported from
- * Node-only contexts (`fromDir`, `build`).
+ * Internal filesystem scanner for the Source Quiver layout. Statically imports
+ * `node:fs`, so it is reachable from the Node entry alone.
  */
 import type { QuiverMeta } from './quiver-yaml.js';
 import type { QuiverLoader } from './quiver.js';
@@ -17,7 +15,7 @@ import type { QuiverLoader } from './quiver.js';
  *     non-canonical, or a version dir is missing its Quill.yaml sentinel.
  *   - `transport_error` for I/O failures (permissions, etc.).
  *
- * Missing `quills/` directory is NOT an error — the quiver is valid but empty.
+ * Missing `quills/` directory is not an error — the quiver is valid but empty.
  */
 export declare function scanSourceQuiver(rootDir: string): Promise<{
     meta: QuiverMeta;
@@ -32,8 +30,8 @@ export declare function scanSourceQuiver(rootDir: string): Promise<{
 export declare function readQuillTree(quillDir: string): Promise<Map<string, Uint8Array>>;
 /**
  * Source-backed QuiverLoader: loads file trees from a Source Quiver on disk.
- * The outer Quiver.loadTree already validates name/version against the catalog,
- * so this loader trusts the gate and goes straight to reading files.
+ * `Quiver` resolves every ref against its catalog before reaching a loader, so
+ * the name and version arrive catalog-backed and go straight to the disk.
  */
 export declare class SourceLoader implements QuiverLoader {
     private readonly rootDir;

package/dist/source-loader.js

@@ -1,8 +1,6 @@
 /**
- * Internal filesystem scanner for Source Quiver layout.
- *
- * Uses Node.js `fs/promises` — this module must only be imported from
- * Node-only contexts (`fromDir`, `build`).
+ * Internal filesystem scanner for the Source Quiver layout. Statically imports
+ * `node:fs`, so it is reachable from the Node entry alone.
  */
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
@@ -20,10 +18,9 @@ import { isCanonicalSemver, compareSemver } from './semver.js';
  *     non-canonical, or a version dir is missing its Quill.yaml sentinel.
  *   - `transport_error` for I/O failures (permissions, etc.).
  *
- * Missing `quills/` directory is NOT an error — the quiver is valid but empty.
+ * Missing `quills/` directory is not an error — the quiver is valid but empty.
  */
 export async function scanSourceQuiver(rootDir) {
-    // --- Read Quiver.yaml ---
     const quiverYamlPath = join(rootDir, 'Quiver.yaml');
     let raw;
     try {
@@ -42,7 +39,6 @@ export async function scanSourceQuiver(rootDir) {
         throw new QuiverError('transport_error', `Failed to read "Quiver.yaml" at "${quiverYamlPath}": ${err.message}`, { cause: err });
     }
     const meta = parseQuiverYaml(raw);
-    // --- Walk quills/ directory ---
     const quillsDir = join(rootDir, 'quills');
     let quillNames;
     try {
@@ -51,7 +47,6 @@ export async function scanSourceQuiver(rootDir) {
     catch (err) {
         const code = err.code;
         if (code === 'ENOENT') {
-            // Missing quills/ is fine — empty catalog
             return { meta, catalog: new Map() };
         }
         throw new QuiverError('transport_error', `Failed to read "quills/" directory at "${quillsDir}": ${err.message}`, { cause: err });
@@ -59,7 +54,6 @@ export async function scanSourceQuiver(rootDir) {
     const catalog = new Map();
     for (const quillName of quillNames) {
         const quillNameDir = join(quillsDir, quillName);
-        // Ensure it's a directory
         let st;
         try {
             st = await stat(quillNameDir);
@@ -69,7 +63,6 @@ export async function scanSourceQuiver(rootDir) {
         }
         if (!st.isDirectory())
             continue;
-        // Read version directories
         let versionDirs;
         try {
             versionDirs = await readdir(quillNameDir);
@@ -80,7 +73,6 @@ export async function scanSourceQuiver(rootDir) {
         const versions = [];
         for (const versionDir of versionDirs) {
             const versionPath = join(quillNameDir, versionDir);
-            // Ensure it's a directory
             let vst;
             try {
                 vst = await stat(versionPath);
@@ -90,11 +82,9 @@ export async function scanSourceQuiver(rootDir) {
             }
             if (!vst.isDirectory())
                 continue;
-            // Non-canonical version → quiver_invalid
             if (!isCanonicalSemver(versionDir)) {
                 throw new QuiverError('quiver_invalid', `Quill "${quillName}" has non-canonical version directory "${versionDir}" — only x.y.z format is allowed`, { quiverName: meta.name, version: versionDir });
             }
-            // Require Quill.yaml sentinel inside the version dir
             const quillYamlPath = join(versionPath, 'Quill.yaml');
             try {
                 await stat(quillYamlPath);
@@ -109,7 +99,6 @@ export async function scanSourceQuiver(rootDir) {
             versions.push(versionDir);
         }
         if (versions.length > 0) {
-            // Sort descending
             versions.sort((a, b) => compareSemver(b, a));
             catalog.set(quillName, versions);
         }
@@ -148,7 +137,6 @@ async function walkDir(baseDir, currentDir, tree) {
             await walkDir(baseDir, fullPath, tree);
         }
         else {
-            // Compute relative POSIX path
             const rel = relative(baseDir, fullPath);
             const posixRel = sep === '/' ? rel : rel.split(sep).join('/');
             let bytes;
@@ -164,8 +152,8 @@ async function walkDir(baseDir, currentDir, tree) {
 }
 /**
  * Source-backed QuiverLoader: loads file trees from a Source Quiver on disk.
- * The outer Quiver.loadTree already validates name/version against the catalog,
- * so this loader trusts the gate and goes straight to reading files.
+ * `Quiver` resolves every ref against its catalog before reaching a loader, so
+ * the name and version arrive catalog-backed and go straight to the disk.
  */
 export class SourceLoader {
     rootDir;

package/dist/transports/http-transport.js

@@ -8,11 +8,9 @@ import { QuiverError } from '../errors.js';
 export class HttpTransport {
     baseUrl;
     constructor(baseUrl) {
-        // Normalize: ensure exactly one trailing slash.
         this.baseUrl = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
     }
     async fetchBytes(relativePath, opts) {
-        // Strip any leading slash from relativePath to avoid double slashes.
         const cleanPath = relativePath.startsWith('/') ? relativePath.slice(1) : relativePath;
         const url = `${this.baseUrl}${cleanPath}`;
         let response;

package/dist/transports/memory-transport.d.ts

@@ -0,0 +1,15 @@
+/**
+ * MemoryTransport — built-quiver transport over bytes the caller already holds,
+ * falling through to another transport for what the map does not carry.
+ * Internal; not exported from index.ts.
+ *
+ * Browser-safe: no `node:` imports at any level.
+ */
+import type { BuiltTransport, FetchOptions } from '../built-loader.js';
+export declare class MemoryTransport implements BuiltTransport {
+    private readonly fallback?;
+    private readonly files;
+    constructor(files: ReadonlyMap<string, Uint8Array>, fallback?: BuiltTransport | undefined);
+    /** The map answers first. `FetchOptions` reaches only the fallback: a held byte has no cache to revalidate against. */
+    fetchBytes(relativePath: string, opts?: FetchOptions): Promise<Uint8Array>;
+}

package/dist/transports/memory-transport.js

@@ -0,0 +1,34 @@
+/**
+ * MemoryTransport — built-quiver transport over bytes the caller already holds,
+ * falling through to another transport for what the map does not carry.
+ * Internal; not exported from index.ts.
+ *
+ * Browser-safe: no `node:` imports at any level.
+ */
+import { QuiverError } from '../errors.js';
+/** Keys are artifact-relative, as the loader asks for them; a leading `./` or `/` is stripped. */
+function normalizeKeys(files) {
+    const out = new Map();
+    for (const [key, bytes] of files) {
+        out.set(key.replace(/^\.?\//, ''), bytes);
+    }
+    return out;
+}
+export class MemoryTransport {
+    fallback;
+    files;
+    constructor(files, fallback) {
+        this.fallback = fallback;
+        this.files = normalizeKeys(files);
+    }
+    /** The map answers first. `FetchOptions` reaches only the fallback: a held byte has no cache to revalidate against. */
+    async fetchBytes(relativePath, opts) {
+        const bytes = this.files.get(relativePath);
+        if (bytes !== undefined)
+            return bytes;
+        if (this.fallback === undefined) {
+            throw new QuiverError('transport_error', `No bytes held for "${relativePath}". Quiver.fromBuiltFiles needs the whole artifact; to hold part and fetch the rest, pass the map as Quiver.fromBuiltUrl's \`seed\`.`);
+        }
+        return this.fallback.fetchBytes(relativePath, opts);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quillmark/quiver",
-	"version": "0.19.0",
+	"version": "0.21.0",
 	"description": "A quiver of Quillmark quills: load one, pack one, hand out quills.",
 	"type": "module",
 	"license": "Apache-2.0",
@@ -38,10 +38,11 @@
 	"sideEffects": false,
 	"files": [
 		"dist",
+		"MIGRATION.md",
 		"NOTICE"
 	],
 	"peerDependencies": {
-		"@quillmark/wasm": ">=0.101.0-0"
+		"@quillmark/wasm": ">=0.103.0-0"
 	},
 	"dependencies": {
 		"fflate": "^0.8.2",