@quillmark/quiver 0.19.0 → 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.
 
@@ -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/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,6 +1,6 @@
 {
 	"name": "@quillmark/quiver",
-	"version": "0.19.0",
+	"version": "0.20.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",