@quillmark/quiver 0.18.1 → 0.20.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.
 
@@ -62,16 +66,17 @@ import { build } from '@quillmark/quiver/node';
 await build('./node_modules/@org/my-quiver', './public/quivers/my-quiver');
 ```
 
-`build` clears its output directory before writing, so it owns that path outright. An `outDir` that is, or contains, the source quiver or the working directory is refused with a `transport_error` rather than deleted.
+`build` owns its output path outright: it assembles a generation in `<outDir>.stage`, moves it in whole, and deletes the one it replaced. A reader fetching mid-build sees the previous generation rather than a torn tree, and a build that throws leaves it serving. An `outDir` that is, or contains, the source quiver or the working directory is refused with a `transport_error` rather than deleted.
 
 ```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.
@@ -134,32 +164,17 @@ A consumer reaches an installed quiver by resolving `<specifier>/Quiver.yaml`, w
 }
 ```
 
-Gate the quiver in CI so a validation failure surfaces on publish rather than on a consumer's build. `quillmark-quiver test` loads with `fromDir`, compiles every quill, and renders each quill's example document. One door, so what you run locally is what CI runs.
+## Authoring is [quillkit](../quillkit#readme)'s
 
-The CLI needs no file. Installing the package links `quillmark-quiver` into `node_modules/.bin`, which npm puts on PATH for every script:
+This package is a library: it loads a quiver and packs one, and it has no CLI. The verbs a quill author runs (gate, pack, look at, deploy) are `quillkit`'s, and it resolves this package out of the collection's own `node_modules`. Depend on it here and the version you pin is the format your quiver is packed in:
 
 ```sh
-npm install --save-dev @quillmark/quiver @quillmark/wasm
+npm install --save-dev @quillmark/quiver @quillmark/wasm quillkit
 ```
 
 ```jsonc
 // package.json
 {
-	"scripts": { "test": "quillmark-quiver test" }
+	"scripts": { "test": "quillkit test" }
 }
 ```
-
-It finds the engine itself: a named `engine` export from `quiver.config.js` at the collection root, else `@quillmark/wasm` from your own `node_modules`. `quillmark-quiver build [--out <dir>]` packs the same source into a servable artifact.
-
-On vitest, jest or `node:test`, spawn the bin from a test rather than rebuilding the loop against the main API. The gate stays one implementation, and the case gates what CI gates:
-
-```ts
-// quiver.test.ts
-import { execFileSync } from 'node:child_process';
-
-it('gates the quiver', () => {
-	execFileSync('quillmark-quiver', ['test'], { stdio: 'inherit' });
-});
-```
-
-It answers _does it work_, and that is the whole of what this package offers a quill author: _what is it like to use_ is answered by working a real document through the quill live, which is an app rather than a subpath.

package/dist/build.d.ts

@@ -17,6 +17,10 @@
  *     store/
  *       <sha256>                      # dehydrated font bytes (full hash, no ext)
  *
+ * A generation is assembled beside outDir and moved in whole, so a reader
+ * fetching mid-build reads the previous one rather than a torn tree, and a
+ * build that throws leaves the previous one serving.
+ *
  * Throws:
  *   - `quiver_invalid` on source validation failures (propagated from scanner)
  *   - `transport_error` on I/O failures, and on an outDir the build would have

package/dist/build.js

@@ -11,12 +11,20 @@ import { NAME_DIGEST_LENGTH } from './digest.js';
 import { POINTER_FORMAT } from './format.js';
 /** Font file extensions recognised by the builder (case-insensitive). */
 const FONT_EXT = /\.(ttf|otf|woff|woff2)$/i;
+/** The two trees a build owns beside its output: where a generation is assembled, and
+ *  where the one it replaces waits to be deleted. Siblings of outDir, so the swap is a
+ *  rename rather than a copy across filesystems. */
+const stagesOf = (out) => ({
+    stage: `${out}.stage`,
+    prev: `${out}.prev`
+});
 /**
- * The build's first act is `rm(outDir, { recursive: true })`, so an outDir that
- * is, or contains, the source quiver or the working directory deletes the
- * thing the caller was building from. `quillmark-quiver build --out .` and a
- * mistyped `--out ..` are both one keystroke away, and the failure is
- * unrecoverable, so an outDir that owns the caller is refused up front.
+ * The build deletes each of the three trees it owns, so an outDir that is, or contains,
+ * the source quiver or the working directory deletes the thing the caller was building
+ * from. `quillkit build --out .` and a mistyped `--out ..` are both one keystroke away,
+ * and the failure is unrecoverable, so an outDir that owns the caller is refused up
+ * front. The staging siblings are checked too: they are named off outDir and cleared
+ * with it, so a caller who avoids one spelling has not avoided the others.
  *
  * An outDir *inside* sourceDir stays allowed: the scan reads the source before
  * any write, and `dist/` under the quiver root is the ordinary layout.
@@ -25,18 +33,19 @@ const FONT_EXT = /\.(ttf|otf|woff|woff2)$/i;
  */
 function assertSafeOutDir(path, sourceDir, outDir) {
     const out = path.resolve(outDir);
-    /** True when `dir` is `target` or an ancestor of it. */
-    const owns = (target) => {
-        const rel = path.relative(out, path.resolve(target));
+    const { stage, prev } = stagesOf(out);
+    /** True when one of the owned trees is `target` or an ancestor of it. */
+    const owns = (target) => [out, stage, prev].some((dir) => {
+        const rel = path.relative(dir, path.resolve(target));
         return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
-    };
+    });
     const what = owns(sourceDir)
         ? 'the source quiver'
         : owns(process.cwd())
             ? 'the working directory'
             : undefined;
     if (what !== undefined) {
-        throw new QuiverError('transport_error', `Refusing to build into "${outDir}": the build clears its output directory, and this one holds ${what} ("${out}"). Point --out at a directory the build owns.`);
+        throw new QuiverError('transport_error', `Refusing to build into "${outDir}": the build clears that directory and two staging siblings beside it, and this one holds ${what} ("${out}"). Point --out somewhere the build can own outright.`);
     }
 }
 /**
@@ -51,6 +60,10 @@ function assertSafeOutDir(path, sourceDir, outDir) {
  *     store/
  *       <sha256>                      # dehydrated font bytes (full hash, no ext)
  *
+ * A generation is assembled beside outDir and moved in whole, so a reader
+ * fetching mid-build reads the previous one rather than a torn tree, and a
+ * build that throws leaves the previous one serving.
+ *
  * Throws:
  *   - `quiver_invalid` on source validation failures (propagated from scanner)
  *   - `transport_error` on I/O failures, and on an outDir the build would have
@@ -59,107 +72,139 @@ function assertSafeOutDir(path, sourceDir, outDir) {
 export async function buildQuiver(sourceDir, outDir) {
     // Dynamic imports keep this module safe to type-import from browser contexts.
     const path = await import('node:path');
-    const { join } = path;
-    const { mkdir, rm, writeFile } = await import('node:fs/promises');
+    const { dirname, join, resolve } = path;
+    const { mkdir, rename, rm, writeFile } = await import('node:fs/promises');
+    const { existsSync } = await import('node:fs');
     const { createHash } = await import('node:crypto');
     const { scanSourceQuiver, readQuillTree } = await import('./source-loader.js');
-    // 0. The first write is a recursive delete of outDir; refuse the paths where
-    //    that deletes the caller instead of a previous build.
+    // 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);
-    // 2. Clear and recreate outDir + outDir/store/.
     try {
-        await rm(outDir, { recursive: true, force: true });
-        await mkdir(join(outDir, 'store'), { recursive: true });
+        await packGeneration();
     }
-    catch (err) {
-        throw new QuiverError('transport_error', `Failed to prepare output directory "${outDir}": ${err.message}`, { cause: err });
+    finally {
+        // A throw anywhere above leaves a partial generation staged, and outDir
+        // untouched. Neither tree outlives the call either way. Swept rather than
+        // checked: a sweep that threw would answer for the build, and what a caller
+        // needs to hear is why the build failed.
+        for (const at of [stage, prev])
+            await rm(at, { recursive: true, force: true }).catch(() => { });
     }
-    // 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) {
-                if (FONT_EXT.test(path)) {
-                    fontEntries.push([path, bytes]);
+    /**
+     * Write a whole generation into `stage`, then move it to outDir.
+     *
+     * The move is two renames: a directory rename refuses a non-empty target, so the
+     * outgoing generation steps aside first. That is the window, and it is two syscalls
+     * 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 });
+        }
+        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) {
+                    if (FONT_EXT.test(path)) {
+                        fontEntries.push([path, bytes]);
+                    }
+                    else {
+                        contentEntries.push([path, bytes]);
+                    }
                 }
-                else {
-                    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
+                    // sharing a prefix would merge into one entry.
+                    const hash = createHash('sha256').update(bytes).digest('hex');
+                    try {
+                        await writeFile(join(stage, 'store', hash), bytes);
+                    }
+                    catch (err) {
+                        throw new QuiverError('transport_error', `Failed to write font store entry "${join(outDir, 'store', hash)}": ${err.message}`, { cause: err });
+                    }
+                    fonts[path] = hash;
                 }
-            }
-            // 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
-                // sharing a prefix would merge into one entry.
-                const hash = createHash('sha256').update(bytes).digest('hex');
-                const storePath = join(outDir, 'store', 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(storePath, bytes);
+                    await writeFile(join(stage, bundleName), zipBytes);
                 }
                 catch (err) {
-                    throw new QuiverError('transport_error', `Failed to write font store entry "${storePath}": ${err.message}`, { cause: err });
+                    throw new QuiverError('transport_error', `Failed to write bundle "${join(outDir, bundleName)}": ${err.message}`, { cause: err });
                 }
-                fonts[path] = hash;
+                // h. Record manifest entry.
+                manifestQuills.push({ name: quillName, version, bundle: bundleName, fonts });
             }
-            // 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.
-            const bundlePath = join(outDir, bundleName);
-            try {
-                await writeFile(bundlePath, zipBytes);
-            }
-            catch (err) {
-                throw new QuiverError('transport_error', `Failed to write bundle "${bundlePath}": ${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,
-        quills: manifestQuills
-    };
-    const manifestJson = JSON.stringify(manifest, null, 2);
-    const manifestHash = createHash('sha256')
-        .update(manifestJson)
-        .digest('hex')
-        .slice(0, NAME_DIGEST_LENGTH);
-    const manifestFileName = `manifest.${manifestHash}.json`;
-    const manifestPath = join(outDir, manifestFileName);
-    try {
-        await writeFile(manifestPath, manifestJson, 'utf-8');
-    }
-    catch (err) {
-        throw new QuiverError('transport_error', `Failed to write manifest "${manifestPath}": ${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.
-    const pointer = { format: POINTER_FORMAT, manifest: manifestFileName };
-    const pointerPath = join(outDir, 'latest.json');
-    try {
-        await writeFile(pointerPath, JSON.stringify(pointer), 'utf-8');
-    }
-    catch (err) {
-        throw new QuiverError('transport_error', `Failed to write pointer "${pointerPath}": ${err.message}`, { cause: err });
+        // 4–8. Build and write hashed manifest.
+        const manifest = {
+            version: 1,
+            name: meta.name,
+            quills: manifestQuills
+        };
+        const manifestJson = JSON.stringify(manifest, null, 2);
+        const manifestHash = createHash('sha256')
+            .update(manifestJson)
+            .digest('hex')
+            .slice(0, NAME_DIGEST_LENGTH);
+        const manifestFileName = `manifest.${manifestHash}.json`;
+        try {
+            await writeFile(join(stage, manifestFileName), manifestJson, 'utf-8');
+        }
+        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.
+        const pointer = { format: POINTER_FORMAT, manifest: manifestFileName };
+        try {
+            await writeFile(join(stage, 'latest.json'), JSON.stringify(pointer), 'utf-8');
+        }
+        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.
+        try {
+            await mkdir(dirname(out), { recursive: true });
+            await rm(prev, { recursive: true, force: true });
+            if (existsSync(out))
+                await rename(out, prev);
+            await rename(stage, out);
+        }
+        catch (err) {
+            throw new QuiverError('transport_error', `Failed to move the build into "${outDir}": ${err.message}`, { cause: err });
+        }
     }
 }

package/dist/quiver.d.ts

@@ -4,11 +4,11 @@
  * 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.
+ * This module is 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 +24,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 +35,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[];
     /**

package/dist/quiver.js

@@ -4,12 +4,12 @@
  * 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.
+ * This module is 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';
 /**
@@ -31,8 +31,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 +49,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() {
@@ -147,10 +179,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/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,7 +1,7 @@
 {
 	"name": "@quillmark/quiver",
-	"version": "0.18.1",
-	"description": "Quiver registry and build tooling for Quillmark",
+	"version": "0.20.0",
+	"description": "A quiver of Quillmark quills: load one, pack one, hand out quills.",
 	"type": "module",
 	"license": "Apache-2.0",
 	"repository": {
@@ -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",
@@ -53,9 +54,6 @@
 		"typescript": "^5.9.3",
 		"vitest": "^4.0.18"
 	},
-	"bin": {
-		"quillmark-quiver": "./dist/bin/quiver.js"
-	},
 	"scripts": {
 		"build": "tsc",
 		"prepare": "npm run build",

package/dist/bin/quiver.d.ts

@@ -1,16 +0,0 @@
-#!/usr/bin/env node
-/**
- * Quiver CLI — build and test a quiver collection. Two verbs, and they are the
- * whole of what a quiver author gets from here: `build` packs, `test` gates.
- * Looking at rendered output is studio's, an app rather than a verb.
- *
- * Commands:
- *   quillmark-quiver build [--out <dir>]
- *   quillmark-quiver test
- *
- * Engine discovery (for `test`):
- *   1. Named export `engine` from `quiver.config.js` at the collection root,
- *      if the file exists.
- *   2. Auto-imported `@quillmark/wasm` from the collection's node_modules.
- */
-export {};

package/dist/bin/quiver.js

@@ -1,141 +0,0 @@
-#!/usr/bin/env node
-/**
- * Quiver CLI — build and test a quiver collection. Two verbs, and they are the
- * whole of what a quiver author gets from here: `build` packs, `test` gates.
- * Looking at rendered output is studio's, an app rather than a verb.
- *
- * Commands:
- *   quillmark-quiver build [--out <dir>]
- *   quillmark-quiver test
- *
- * Engine discovery (for `test`):
- *   1. Named export `engine` from `quiver.config.js` at the collection root,
- *      if the file exists.
- *   2. Auto-imported `@quillmark/wasm` from the collection's node_modules.
- */
-import { createRequire } from 'node:module';
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { build as buildQuiver, fromDir } from '../node.js';
-// ---------------------------------------------------------------------------
-// Arg parsing helpers
-// ---------------------------------------------------------------------------
-const argv = process.argv.slice(2);
-const command = argv[0];
-/** One flag with a value. `build --out` is the only one either verb takes. */
-function flag(name) {
-    const i = argv.indexOf(name);
-    return i !== -1 && i + 1 < argv.length ? argv[i + 1] : undefined;
-}
-// ---------------------------------------------------------------------------
-// Engine discovery
-// ---------------------------------------------------------------------------
-async function loadEngine(cwd) {
-    // Resolve @quillmark/wasm from the collection's node_modules (best-effort).
-    // Its `Engine` renders every quill (cloning the core Quill/Document into the
-    // backend itself). A quiver.config.js may export a custom `engine`.
-    let wasm;
-    try {
-        const req = createRequire(pathToFileURL(join(cwd, 'package.json')).href);
-        const wasmPath = req.resolve('@quillmark/wasm');
-        wasm = (await import(pathToFileURL(wasmPath).href));
-        // Instantiate the core. Every `@quillmark/wasm` export throws
-        // `runtime::not_initialized` until `init()` resolves, and `new Engine()` is
-        // lazy, so without this the throw arrives at the first render and reads as a
-        // failing quill rather than an uninitialized runtime.
-        await wasm.init();
-    }
-    catch {
-        // Not installed — a quiver.config.js may still provide an engine.
-    }
-    // 1. Named `engine` export from quiver.config.js, if present.
-    try {
-        const cfg = await import(pathToFileURL(join(cwd, 'quiver.config.js')).href);
-        if (cfg.engine != null) {
-            return cfg.engine;
-        }
-    }
-    catch {
-        // File absent or incomplete — fall through to auto-discovery.
-    }
-    // 2. Auto-discover from @quillmark/wasm.
-    if (wasm == null) {
-        throw new Error("Cannot find @quillmark/wasm in this collection's node_modules.\n" +
-            '  Install it:  npm install @quillmark/wasm\n' +
-            '  Or export { engine } from quiver.config.js for a custom engine.');
-    }
-    return new wasm.Engine();
-}
-// ---------------------------------------------------------------------------
-// Commands
-// ---------------------------------------------------------------------------
-async function build() {
-    const cwd = process.cwd();
-    const outDir = flag('--out') ?? 'dist';
-    console.log(`quillmark-quiver build: ${cwd} → ${outDir}`);
-    await buildQuiver(cwd, outDir);
-    console.log('done.');
-}
-async function test() {
-    const cwd = process.cwd();
-    const engine = await loadEngine(cwd);
-    const quiver = await fromDir(cwd);
-    const names = quiver.quillNames();
-    if (names.length === 0) {
-        console.error('error: quiver has no quills');
-        process.exit(1);
-    }
-    let pass = 0;
-    let fail = 0;
-    for (const name of names) {
-        for (const version of quiver.versionsOf(name)) {
-            const ref = `${name}@${version}`;
-            try {
-                const quill = await quiver.getQuill(ref);
-                const doc = quill.seedDocument();
-                let result;
-                try {
-                    result = await engine.render(quill, doc);
-                }
-                finally {
-                    doc.free();
-                }
-                if (!Array.isArray(result.artifacts) || result.artifacts.length === 0) {
-                    throw new Error('example render produced no artifacts');
-                }
-                console.log(`pass  ${ref}`);
-                pass++;
-            }
-            catch (err) {
-                console.error(`FAIL  ${ref} — ${err.message}`);
-                fail++;
-            }
-        }
-    }
-    const total = pass + fail;
-    console.log(`\n${pass}/${total} passed`);
-    if (fail > 0)
-        process.exit(1);
-}
-// ---------------------------------------------------------------------------
-// Dispatch
-// ---------------------------------------------------------------------------
-function usage() {
-    console.error(['Usage:', '  quillmark-quiver build [--out <dir>]', '  quillmark-quiver test'].join('\n'));
-}
-function die(err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(`error: ${msg}`);
-    process.exit(1);
-}
-switch (command) {
-    case 'build':
-        build().catch(die);
-        break;
-    case 'test':
-        test().catch(die);
-        break;
-    default:
-        usage();
-        process.exit(1);
-}