@quillmark/quiver 0.38.1 → 0.39.0

package/MIGRATION.md

@@ -2,6 +2,22 @@
 
 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.38 → 0.39
+
+### Rebuild every artifact
+
+A built quiver is `quiver.json` beside one `<name>@<x.y.z>.<digest>.quill` bundle per quill, each carrying its quill's fonts; `fonts/` is gone, and `quiver.json` and `latest.json` state format 3. A format-2 artifact under 0.39 is refused as `quiver_invalid` naming the rebuild; a 0.39 artifact under an older reader is refused with the upgrade named. Re-run `build`; nothing in the source layout changes.
+
+`quillkit` packs and reads with the `@quillmark/quiver` it carries, so a quillkit deploy moves to format 3 with the quillkit release that carries 0.39, and nothing in the collection pins this package.
+
+A host rule naming `fonts/*` or `*.zip` under a built quiver names `*.quill` now. A server whose static handler types files by extension serves `.quill` as `application/vnd.quillmark.quill+zip` or `application/octet-stream`; the loader reads the bytes whatever the type.
+
+### Runtime, not build time
+
+**A quill whose tree holds a file name the `.quill` format refuses fails `build`**: one that holds `\`, `:` or NUL, which a filesystem on Linux or macOS allows. Rename the file.
+
+**A bundle the `.quill` format refuses fails `getQuill` with the `QuillmarkError` `Quill.fromBundle` throws**, its diagnostic a `quill::bundle_*` code, where an over-budget or misnamed entry was a `QuiverError` coded `quiver_invalid`. Code that sorts a `getQuill` failure by `QuiverError.code` reads `diagnostics` off the error `isQuillmarkError` narrows. The `@quillmark/wasm` peer floor is `>=0.133.0-0`.
+
 ## 0.29 → 0.30
 
 ### Rebuild every artifact, and move quiver and quillkit together

package/README.md

@@ -37,17 +37,17 @@ const root = dirname(createRequire(import.meta.url).resolve('@org/my-quiver/Quiv
 const quiver = await fromDir(root);
 const engine = new Engine();
 
-const { Document } = await init(); // the gate is the only door to Document
+const { Document } = await init(); // Document is exported only through init()
 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.0"`) 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.
+`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.0"`) and canonical ones (`"memo@1.0.0"`), resolves the selector, materializes the quill via `Quill.fromBundle` (a built quiver) or `Quill.fromTree` (a source one), 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.
 
-This package produces quills; `@quillmark/wasm` renders them. A quill from `getQuill` is engine-free portable data — schema inspection, validation, blueprint access, `seedDocument()` — and passes straight to `engine.render(quill, doc)`, which routes on `quill.backendId`, loads that backend, clones both handles into its memory, renders, and frees the clones. There is no boundary-crossing step to perform. `Engine.render`, `open` and `supportedFormats` are **async**. The canonical `Quill` / `Document` / `Engine` types are not re-exported here; import them from the `@quillmark/wasm` peer, their single source of truth.
+This package produces quills; `@quillmark/wasm` renders them. A quill from `getQuill` is engine-free portable data — schema inspection, validation, `authoringSchema`, `seedDocument()` — and passes straight to `engine.render(quill, doc)`, which routes on `quill.backendId`, loads that backend, clones both handles into its memory, renders, and frees the clones. There is no boundary-crossing step to perform. `Engine.render`, `open` and `supportedFormats` are **async**. The canonical `Quill` / `Document` / `Engine` types are not re-exported here; import them from the `@quillmark/wasm` peer, their single source of truth.
 
 One narrower verb sits beside `getQuill`: `resolve(ref)` returns the canonical ref without materializing anything, and is **sync** (the catalog is in memory from the moment the quiver is built).
 
@@ -82,7 +82,7 @@ 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 { Document } = await init(); // Document is exported only through init()
 const doc = Document.fromMarkdown(markdownString);
 const quill = await quiver.getQuill(doc.quillRef);
 const result = await engine.render(quill, doc, { format: 'pdf' });
@@ -103,7 +103,7 @@ 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 (`quiver.json`, `<name>@<x.y.z>.<digest>.zip`, `fonts/<hash>`):
+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 (`quiver.json`, `<name>@<x.y.z>.<digest>.quill`):
 
 ```ts
 import { Quiver } from '@quillmark/quiver';
@@ -115,9 +115,9 @@ Nothing is fetched, so nothing self-fetches over your own load balancer. The map
 
 ## The `quiver.json` index
 
-`Quiver.fromBuiltUrl(url)` first fetches `<url>/quiver.json`: the format and the catalog, naming each quill's bundle and fonts. Every other name carries the digest of its own bytes, so a changed file is a changed name and is safe to cache forever; `quiver.json` is not, and a cache layer serving a stale one silently pins 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), and every other request is `force-cache`, read once more with `reload` if what the cache answered fails. Both are the browser layer only: a stale CDN edge is answered by that host's cache headers, and `quillkit`'s README states the whole contract for a deploy serving a client over one.
+`Quiver.fromBuiltUrl(url)` first fetches `<url>/quiver.json`: the format and the catalog, naming each quill's bundle. Every other name carries the digest of its own bytes, so a changed file is a changed name and is safe to cache forever; `quiver.json` is not, and a cache layer serving a stale one silently pins 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), and every other request is `force-cache`, read once more with `reload` if what the cache answered fails. Both are the browser layer only: a stale CDN edge is answered by that host's cache headers, and `quillkit`'s README states the whole contract for a deploy serving a client over one.
 
-A `getQuill` reads one bundle and the fonts it names, nothing of another quill. Fonts are stored once by hash, so a release that edits a template re-downloads that quill's bundle and not its fonts. A tab still holding the previous release's `quiver.json` rereads it once when a read fails.
+A `getQuill` reads one bundle, nothing of another quill. Each bundle is a `.quill` bundle: the quill's whole tree as one zip, fonts included, `Quill.yaml` at the root — the file `Quill.fromBundle` in `@quillmark/wasm`, `Quill.from_bundle` in Python and the `quillmark` CLI read. A release that edits a template re-downloads that quill's bundle, fonts and all. A tab still holding the previous release's `quiver.json` rereads it once when a read fails.
 
 ## What a quiver is trusted to be
 
@@ -127,7 +127,7 @@ Nothing checks fetched bytes against their names: the digests are there for cach
 
 ## Error handling
 
-Every error is a `QuiverError` carrying a `code` from a closed set — `invalid_ref`, `quill_not_found`, `quiver_invalid`, `transport_error` — a human-readable `message`, and the offending `ref` where there is one.
+Every error is a `QuiverError` carrying a `code` from a closed set — `invalid_ref`, `quill_not_found`, `quiver_invalid`, `transport_error` — a human-readable `message`, and the offending `ref` where there is one. A quill that does not load, a bundle the `.quill` format refuses among them, is the exception: `getQuill` throws what `Quill.fromBundle` or `Quill.fromTree` threw, a `QuillmarkError` carrying its `diagnostics`.
 
 ```ts
 import { QuiverError } from '@quillmark/quiver';
@@ -169,15 +169,15 @@ A consumer reaches an installed quiver by resolving `<specifier>/Quiver.yaml`, w
 
 ## Authoring is [quillkit](../quillkit#readme)'s
 
-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:
+This package is a library: it loads a quiver and packs one, and it has no CLI. The verbs a quill author runs (start, gate, look at, build) are `quillkit`'s, which carries this package at an exact version, so a quiver installs the tool alone and the format it is packed in is the one quillkit's clients read:
 
 ```sh
-npm install --save-dev @quillmark/quiver @quillmark/wasm quillkit
+npm install --save-dev quillkit
 ```
 
 ```jsonc
 // package.json
 {
-	"scripts": { "test": "quillkit test" }
+	"scripts": { "test": "quillkit check" }
 }
 ```

package/dist/build.d.ts

@@ -20,11 +20,9 @@ export interface BuildOptions {
  * Output layout. Every name but the two JSON documents carries the SHA-256 of what it
  * names, which is what makes it safe to cache forever:
  *   outDir/
- *     quiver.json                       # the format and the catalog
- *     latest.json                       # the format alone, for a reader of format 1
- *     <name>@<version>.<sha256:32>.zip  # one bundle per quill
- *     fonts/
- *       <sha256>                        # dehydrated font bytes (full hash, no ext)
+ *     quiver.json                         # the format and the catalog
+ *     latest.json                         # the format alone, for a reader of format 1
+ *     <name>@<version>.<sha256:32>.quill  # one `.quill` bundle per quill, fonts and all
  *
  * 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

package/dist/build.js

@@ -6,7 +6,7 @@
  * `node:crypto` into a browser bundle.
  */
 import { QuiverError } from './errors.js';
-import { packFiles } from './bundle.js';
+import { BUNDLE_EXTENSION, packFiles } from './bundle.js';
 import { FORMAT, INDEX, LEGACY_POINTER } from './format.js';
 import { isFont } from './signature.js';
 import { isDraft } from './semver.js';
@@ -24,7 +24,7 @@ const stagesOf = (out) => ({
 /**
  * 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,
+ * from. `quillkit build quiver --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.
@@ -57,11 +57,9 @@ function assertSafeOutDir(path, sourceDir, outDir) {
  * Output layout. Every name but the two JSON documents carries the SHA-256 of what it
  * names, which is what makes it safe to cache forever:
  *   outDir/
- *     quiver.json                       # the format and the catalog
- *     latest.json                       # the format alone, for a reader of format 1
- *     <name>@<version>.<sha256:32>.zip  # one bundle per quill
- *     fonts/
- *       <sha256>                        # dehydrated font bytes (full hash, no ext)
+ *     quiver.json                         # the format and the catalog
+ *     latest.json                         # the format alone, for a reader of format 1
+ *     <name>@<version>.<sha256:32>.quill  # one `.quill` bundle per quill, fonts and all
  *
  * 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
@@ -113,44 +111,26 @@ export async function buildQuiver(sourceDir, outDir, options = {}) {
     async function packGeneration() {
         try {
             await rm(stage, { recursive: true, force: true });
-            await mkdir(join(stage, 'fonts'), { recursive: true });
+            await mkdir(stage, { recursive: true });
         }
         catch (err) {
             throw new QuiverError('transport_error', `Failed to prepare output directory "${outDir}": ${err.message}`, { cause: err });
         }
         const quills = [];
-        const stored = new Set();
         for (const [quillName, versions] of catalog) {
             for (const version of versions) {
                 if (!options.drafts && isDraft(version))
                     continue;
                 const quillDir = join(sourceDir, 'quills', quillName, version);
                 const tree = await readQuillTree(quillDir);
-                const fonts = {};
                 const contentRecord = {};
                 for (const [rel, bytes] of tree) {
-                    if (!FONT_EXT.test(rel)) {
-                        contentRecord[rel] = bytes;
-                        continue;
-                    }
-                    // The loader refuses what does not open as a font, so the build refuses it
-                    // first, where the author it names can do something about it.
-                    if (!isFont(bytes, rel)) {
+                    // Typst substitutes a font it cannot parse without a word, so a font file
+                    // that is not one is refused where the author it names can fix it.
+                    if (FONT_EXT.test(rel) && !isFont(bytes, rel)) {
                         throw new QuiverError('quiver_invalid', `Quill "${quillName}@${version}": "${rel}" does not open as the font its extension names`, { quiverName: meta.name, version });
                     }
-                    // Full width: fonts are keyed by hash, so two distinct fonts sharing a
-                    // prefix would merge into one file.
-                    const hash = createHash('sha256').update(bytes).digest('hex');
-                    fonts[rel] = hash;
-                    if (stored.has(hash))
-                        continue;
-                    try {
-                        await writeFile(join(stage, 'fonts', hash), bytes);
-                    }
-                    catch (err) {
-                        throw new QuiverError('transport_error', `Failed to write font "${join(outDir, 'fonts', hash)}": ${err.message}`, { cause: err });
-                    }
-                    stored.add(hash);
+                    contentRecord[rel] = bytes;
                 }
                 // The budget `bundle.ts` carries is spent here as well as at the read, so
                 // a quill no loader would take is refused by the build that packs it,
@@ -166,14 +146,14 @@ export async function buildQuiver(sourceDir, outDir, options = {}) {
                     .update(zipBytes)
                     .digest('hex')
                     .slice(0, NAME_DIGEST_LENGTH);
-                const bundleName = `${quillName}@${version}.${bundleHash}.zip`;
+                const bundleName = `${quillName}@${version}.${bundleHash}.${BUNDLE_EXTENSION}`;
                 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 });
                 }
-                quills.push({ name: quillName, version, bundle: bundleName, fonts });
+                quills.push({ name: quillName, version, bundle: bundleName });
             }
         }
         // The format is stamped here and read first, so a client older than the tree says so

package/dist/built-loader.d.ts

@@ -1,6 +1,6 @@
 /**
  * Built-quiver loader: reads `quiver.json` through a reader, validates it, and hands back
- * a Quiver whose loader reads bundles and fonts on demand.
+ * a Quiver whose loader reads one `.quill` bundle per quill on demand.
  *
  * Package-internal, and browser-safe: no static `node:` imports at any level.
  */

package/dist/built-loader.js

@@ -1,15 +1,14 @@
 /**
  * Built-quiver loader: reads `quiver.json` through a reader, validates it, and hands back
- * a Quiver whose loader reads bundles and fonts on demand.
+ * a Quiver whose loader reads one `.quill` bundle per quill on demand.
  *
  * Package-internal, and browser-safe: no static `node:` imports at any level.
  */
 import { QuiverError } from './errors.js';
-import { unpackFiles } from './bundle.js';
 import { isQuillName } from './ref.js';
 import { isCanonicalSemver, compareSemver } from './semver.js';
 import { FORMAT, INDEX } from './format.js';
-import { isFont, isZip } from './signature.js';
+import { isZip } from './signature.js';
 import { createQuiver } from './quiver.js';
 export function httpReader(base) {
     const root = base.endsWith('/') ? base : `${base}/`;
@@ -44,10 +43,9 @@ export function filesReader(files) {
         return bytes;
     };
 }
-// The shapes `build` writes. Neither admits a separator, so a validated name read off
+// The shape `build` writes. It admits no separator, so a validated name read off
 // `quiver.json` stays inside the artifact on every reader.
-const BUNDLE_RE = /^[A-Za-z0-9_-]+@[0-9]+\.[0-9]+\.[0-9]+\.[0-9a-f]+\.zip$/;
-const FONT_HASH_RE = /^[0-9a-f]{64}$/;
+const BUNDLE_RE = /^[A-Za-z0-9_-]+@[0-9]+\.[0-9]+\.[0-9]+\.[0-9a-f]+\.quill$/;
 /** Bytes a host answered with that are not the file named: a `transport_error`, so the
  *  reread below gets its turn. */
 function refused(path, what) {
@@ -72,7 +70,6 @@ async function readChecked(read, path, opens, what) {
 class BuiltLoader {
     read;
     entries;
-    #fonts = new Map();
     #rereading;
     constructor(read, entries) {
         this.read = read;
@@ -84,11 +81,11 @@ class BuiltLoader {
      * names other files. A reread refusing the index is the error that explains the
      * failure, and is the one thrown.
      */
-    async loadTree(name, version) {
+    async load(name, version) {
         const key = `${name}@${version}`;
         const entry = this.entries.get(key);
         try {
-            return await this.#treeOf(entry);
+            return await this.#bundleOf(entry);
         }
         catch (err) {
             let index;
@@ -99,9 +96,9 @@ class BuiltLoader {
                 throw reread instanceof QuiverError && reread.code === 'quiver_invalid' ? reread : err;
             }
             const fresh = index.entries.get(key);
-            if (fresh === undefined || sameFiles(fresh, entry))
+            if (fresh === undefined || fresh.bundle === entry.bundle)
                 throw err;
-            return this.#treeOf(fresh);
+            return this.#bundleOf(fresh);
         }
     }
     /** One reread in flight, taking every entry both generations carry. */
@@ -118,30 +115,10 @@ class BuiltLoader {
             this.#rereading = undefined;
         }));
     }
-    async #treeOf(entry) {
-        const zip = await readChecked(this.read, entry.bundle, isZip, 'a zip');
-        const files = unpackFiles(zip);
-        await Promise.all(Object.entries(entry.fonts).map(async ([path, hash]) => {
-            files[path] = await this.#font(hash, path);
-        }));
-        return new Map(Object.entries(files));
-    }
-    /** One read per hash, coalesced; a failure is evicted so a retry reads again. */
-    #font(hash, rel) {
-        let bytes = this.#fonts.get(hash);
-        if (bytes === undefined) {
-            bytes = readChecked(this.read, `fonts/${hash}`, (font) => isFont(font, rel), 'a font').catch((err) => {
-                this.#fonts.delete(hash);
-                throw err;
-            });
-            this.#fonts.set(hash, bytes);
-        }
-        return bytes;
+    #bundleOf(entry) {
+        return readChecked(this.read, entry.bundle, isZip, 'a zip');
     }
 }
-function sameFiles(a, b) {
-    return a.bundle === b.bundle && JSON.stringify(a.fonts) === JSON.stringify(b.fonts);
-}
 async function readIndex(read) {
     let bytes;
     try {
@@ -176,6 +153,10 @@ function parseIndex(raw) {
         throw new QuiverError('quiver_invalid', `This quiver is built in format ${format} and this loader reads ${FORMAT}. ` +
             `Upgrade @quillmark/quiver, or for a served client the client itself, which carries the copy that reads this.`);
     }
+    if (format < FORMAT) {
+        throw new QuiverError('quiver_invalid', `This quiver is built in format ${format} and this loader reads ${FORMAT}. ` +
+            `Rebuild it with a @quillmark/quiver that writes format ${FORMAT}, in the collection where it is packed.`);
+    }
     const name = obj['name'];
     if (typeof name !== 'string' || name.length === 0) {
         throw new QuiverError('quiver_invalid', `${INDEX} must have a non-empty string "name" field`);
@@ -214,22 +195,11 @@ function parseIndex(raw) {
         if (typeof bundle !== 'string' || !BUNDLE_RE.test(bundle)) {
             throw new QuiverError('quiver_invalid', `${at}.bundle is invalid: "${String(bundle)}"`);
         }
-        const declared = e['fonts'];
-        if (typeof declared !== 'object' || declared === null || Array.isArray(declared)) {
-            throw new QuiverError('quiver_invalid', `${at}.fonts must be an object`);
-        }
-        const fonts = {};
-        for (const [path, hash] of Object.entries(declared)) {
-            if (typeof hash !== 'string' || !FONT_HASH_RE.test(hash)) {
-                throw new QuiverError('quiver_invalid', `${at}.fonts["${path}"] is not a font hash: ${JSON.stringify(hash)}`);
-            }
-            fonts[path] = hash;
-        }
         const key = `${quillName}@${version}`;
         if (entries.has(key)) {
             throw new QuiverError('quiver_invalid', `Duplicate quill entry in ${INDEX}: "${key}"`);
         }
-        entries.set(key, { name: quillName, version, bundle, fonts });
+        entries.set(key, { name: quillName, version, bundle });
     }
     return { name, description, entries };
 }

package/dist/bundle.d.ts

@@ -1,17 +1,13 @@
 /**
- * Zip utilities — browser-safe (uses fflate only).
+ * The `.quill` bundle, written through fflate. The format is Quillmark's (quill-bundle.md
+ * in the quillmark repository): one quill's tree as one zip, `Quill.yaml` at the root.
+ * `Quill.fromBundle` reads it.
  */
+/** The extension a `.quill` bundle's name ends in. */
+export declare const BUNDLE_EXTENSION = "quill";
 /**
  * Pack a flat file map into a deterministic zip.
  * Keys are sorted before zipping so insertion order doesn't affect output.
- * Throws `quiver_invalid` where the budget is spent.
+ * Throws `quiver_invalid` where the budget is spent or a name is one the format refuses.
  */
 export declare function packFiles(files: Record<string, Uint8Array>): Uint8Array;
-/**
- * Unpack a zip into a flat file map.
- * Returns { path: Uint8Array } for every file entry in the archive.
- * Throws `quiver_invalid` where the budget is spent. fflate filters and inflates one
- * entry per pass, so the entries the budget already took are resident when it throws —
- * bounded, being what fit inside it.
- */
-export declare function unpackFiles(data: Uint8Array): Record<string, Uint8Array>;

package/dist/bundle.js

@@ -1,8 +1,12 @@
 /**
- * Zip utilities — browser-safe (uses fflate only).
+ * The `.quill` bundle, written through fflate. The format is Quillmark's (quill-bundle.md
+ * in the quillmark repository): one quill's tree as one zip, `Quill.yaml` at the root.
+ * `Quill.fromBundle` reads it.
  */
-import { zipSync, unzipSync } from 'fflate';
+import { zipSync } from 'fflate';
 import { QuiverError } from './errors.js';
+/** The extension a `.quill` bundle's name ends in. */
+export const BUNDLE_EXTENSION = 'quill';
 /**
  * Fixed epoch mtime for deterministic zip output.
  *
@@ -15,29 +19,31 @@ import { QuiverError } from './errors.js';
  */
 const ZIP_EPOCH = new Date(1980, 0, 1, 0, 0, 0, 0);
 /**
- * What a bundle may hold. Deflate tops out near 1032:1, so a megabyte of zip is a
- * gigabyte resident and the bundle is what a reader inflates to find that out.
- *
- * The ceiling is a constant rather than something a consumer raises, because a quiver
- * is a dependency pinned like any other (README, "What a quiver is trusted to be") and
- * what a budget bounds there is a build that packed something enormous. Both ends spend
- * it, so an artifact no loader would read is refused where it is written.
- *
- * Fonts are not in here: `build` writes them under `fonts/` and `quiver.json` names them,
- * leaving a bundle its markdown, its Typst, and what those inline.
+ * What a bundle may hold: the `.quill` format's budget, which every Quillmark runtime
+ * spends on the same three bounds. A constant rather than something a consumer raises,
+ * because the format fixes it. The reader spends it too, so an artifact no loader would
+ * read is refused where it is written.
  */
 const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
-const MAX_ENTRY_BYTES = 16 * 1024 * 1024;
+const MAX_ENTRY_BYTES = 32 * 1024 * 1024;
 const MAX_BUNDLE_ENTRIES = 2048;
 /**
- * The budget, spent one entry at a time. Throws `quiver_invalid`.
- *
- * Unpacking spends the sizes the central directory declares, and those are the sizes
- * fflate allocates: each entry inflates into a buffer of exactly its declared size,
- * which never grows. So a header cannot buy more than it declares — it can only
- * understate itself and truncate its own entry, which is a corrupt bundle rather than an
- * allocation.
+ * The `.quill` format's entry names: relative, `/`-separated, and no segment empty, `.`
+ * or `..`, nor holding `\`, `:` or NUL. Throws `quiver_invalid`.
  */
+function checkPath(name) {
+    const why = name.startsWith('/')
+        ? 'is absolute'
+        : /[\\:\0]/.test(name)
+            ? 'holds a \\, : or NUL'
+            : name.split('/').some((s) => s === '' || s === '.' || s === '..')
+                ? 'has an empty, "." or ".." segment'
+                : undefined;
+    if (why !== undefined) {
+        throw new QuiverError('quiver_invalid', `Bundled file "${name}" ${why}`);
+    }
+}
+/** The budget, spent one entry at a time. Throws `quiver_invalid`. */
 function bundleBudget() {
     let total = 0;
     let count = 0;
@@ -57,7 +63,7 @@ function bundleBudget() {
 /**
  * Pack a flat file map into a deterministic zip.
  * Keys are sorted before zipping so insertion order doesn't affect output.
- * Throws `quiver_invalid` where the budget is spent.
+ * Throws `quiver_invalid` where the budget is spent or a name is one the format refuses.
  */
 export function packFiles(files) {
     const spend = bundleBudget();
@@ -65,24 +71,9 @@ export function packFiles(files) {
     const input = {};
     for (const key of sorted) {
         const bytes = files[key];
+        checkPath(key);
         spend(key, bytes.length);
         input[key] = [bytes, { mtime: ZIP_EPOCH }];
     }
     return zipSync(input, { level: 6 });
 }
-/**
- * Unpack a zip into a flat file map.
- * Returns { path: Uint8Array } for every file entry in the archive.
- * Throws `quiver_invalid` where the budget is spent. fflate filters and inflates one
- * entry per pass, so the entries the budget already took are resident when it throws —
- * bounded, being what fit inside it.
- */
-export function unpackFiles(data) {
-    const spend = bundleBudget();
-    return unzipSync(data, {
-        filter: ({ name, originalSize }) => {
-            spend(name, originalSize);
-            return true;
-        }
-    });
-}

package/dist/format.d.ts

@@ -2,12 +2,12 @@
  *  other name is read off. */
 export declare const INDEX = "quiver.json";
 /**
- * The artifact's format, stamped into `quiver.json` and refused to be read past (QUIVER
- * §"The index"). A change a reader assuming the previous shape would misread moves it, and
- * so does the first added field, which format-2 readers before 0.38 refuse; from 3 on, an
- * added field a reader can skip does not.
+ * The artifact's format, stamped into `quiver.json` and read at exactly this value (QUIVER
+ * §"The index"). A change a reader assuming the previous shape would misread moves it; an
+ * added field a reader can skip does not. Format 3 is one `.quill` bundle per quill and no
+ * `fonts/`.
  */
-export declare const FORMAT = 2;
+export declare const FORMAT = 3;
 /**
  * What a reader of format 1 fetches first. It reads `format` off it before anything else,
  * so a file carrying this format and nothing more is refused there with the upgrade named,

package/dist/format.js

@@ -2,12 +2,12 @@
  *  other name is read off. */
 export const INDEX = 'quiver.json';
 /**
- * The artifact's format, stamped into `quiver.json` and refused to be read past (QUIVER
- * §"The index"). A change a reader assuming the previous shape would misread moves it, and
- * so does the first added field, which format-2 readers before 0.38 refuse; from 3 on, an
- * added field a reader can skip does not.
+ * The artifact's format, stamped into `quiver.json` and read at exactly this value (QUIVER
+ * §"The index"). A change a reader assuming the previous shape would misread moves it; an
+ * added field a reader can skip does not. Format 3 is one `.quill` bundle per quill and no
+ * `fonts/`.
  */
-export const FORMAT = 2;
+export const FORMAT = 3;
 /**
  * What a reader of format 1 fetches first. It reads `format` off it before anything else,
  * so a file carrying this format and nothing more is refused there with the upgrade named,

package/dist/node.d.ts

@@ -28,7 +28,7 @@ import type { BuildOptions } from './build.js';
 export declare function fromDir(pathOrFileUrl: string): Promise<Quiver>;
 /**
  * Loads a packed (build-output) quiver from a local directory containing
- * `quiver.json` and the bundles and fonts written by `build`.
+ * `quiver.json` and the `.quill` bundles written by `build`.
  * Symmetric to `Quiver.fromBuiltUrl(url)` but reads from disk instead of HTTP:
  * no network required.
  *

package/dist/node.js

@@ -40,7 +40,7 @@ export async function fromDir(pathOrFileUrl) {
 }
 /**
  * Loads a packed (build-output) quiver from a local directory containing
- * `quiver.json` and the bundles and fonts written by `build`.
+ * `quiver.json` and the `.quill` bundles written by `build`.
  * Symmetric to `Quiver.fromBuiltUrl(url)` but reads from disk instead of HTTP:
  * no network required.
  *
@@ -79,6 +79,6 @@ export async function build(sourceDir, outDir, options) {
 export { Quiver } from './quiver.js';
 export { QuiverError } from './errors.js';
 export { isDraft } from './semver.js';
-// Engine types (`Quillmark`, `Quill`, `Document`, `RenderResult`, …) are not
+// The canonical types (`Quill`, `Document`, `Engine`, `RenderResult`, …) are not
 // re-exported: import them straight from the `@quillmark/wasm` peer dependency,
-// which is the single source of truth for the engine contract.
+// which is their single source of truth.

package/dist/quiver.d.ts

@@ -8,9 +8,11 @@
  * the same either way.
  */
 import type { Quill } from '@quillmark/wasm';
+/** A quill as a loader holds it: a source quiver's file tree, or a built one's `.quill` bundle. */
+export type QuillSource = Map<string, Uint8Array> | Uint8Array;
 /** Loader strategy: source or build output. Package-internal. */
 export interface QuiverLoader {
-    loadTree(name: string, version: string): Promise<Map<string, Uint8Array>>;
+    load(name: string, version: string): Promise<QuillSource>;
 }
 /**
  * The private constructor's only door, closed over by the static block below.
@@ -42,8 +44,8 @@ export declare class Quiver {
     static fromBuiltUrl(url: string): Promise<Quiver>;
     /**
      * Browser-safe factory. Loads build output from the bytes themselves, keyed
-     * by artifact-relative path (`quiver.json`, `<name>@<x.y.z>.<digest>.zip`,
-     * `fonts/<hash>`) — the shape `build` writes and `fromBuiltDir` reads back.
+     * by artifact-relative path (`quiver.json`, `<name>@<x.y.z>.<digest>.quill`)
+     * — 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
@@ -71,7 +73,7 @@ export declare class Quiver {
      *
      * Sync, and in-memory by construction rather than by implementation: every
      * loader materializes the catalog as the quiver is built, and `QuiverLoader`
-     * carries one verb, `loadTree`, which resolution never reaches.
+     * carries one verb, `load`, which resolution never reaches.
      *
      * Throws:
      *   - `invalid_ref` if ref fails parseQuillRef
@@ -83,7 +85,7 @@ export declare class Quiver {
      *
      * The returned quill is materialized from the `@quillmark/wasm` root export
      * — it is engine-free, portable data suitable for schema inspection,
-     * validation, blueprint access, and document seeding.
+     * validation, authoring-schema access, and document seeding.
      *
      * A core `Quill` renders directly: pass it to `engine.render(quill, doc)`.
      *
@@ -100,7 +102,8 @@ export declare class Quiver {
      *   - `invalid_ref` if ref is malformed
      *   - `quill_not_found` if ref does not match any version in this quiver
      *   - propagates I/O errors from the loader unchanged
-     *   - propagates validation errors from Quill.fromTree() unchanged
+     *   - propagates errors from Quill.fromTree() or Quill.fromBundle() unchanged,
+     *     a bundle the format refuses among them as `quill::bundle_*`
      */
     getQuill(ref: string): Promise<Quill>;
 }

package/dist/quiver.js

@@ -63,8 +63,8 @@ export class Quiver {
     }
     /**
      * Browser-safe factory. Loads build output from the bytes themselves, keyed
-     * by artifact-relative path (`quiver.json`, `<name>@<x.y.z>.<digest>.zip`,
-     * `fonts/<hash>`) — the shape `build` writes and `fromBuiltDir` reads back.
+     * by artifact-relative path (`quiver.json`, `<name>@<x.y.z>.<digest>.quill`)
+     * — 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
@@ -99,7 +99,7 @@ export class Quiver {
      *
      * Sync, and in-memory by construction rather than by implementation: every
      * loader materializes the catalog as the quiver is built, and `QuiverLoader`
-     * carries one verb, `loadTree`, which resolution never reaches.
+     * carries one verb, `load`, which resolution never reaches.
      *
      * Throws:
      *   - `invalid_ref` if ref fails parseQuillRef
@@ -124,7 +124,7 @@ export class Quiver {
      *
      * The returned quill is materialized from the `@quillmark/wasm` root export
      * — it is engine-free, portable data suitable for schema inspection,
-     * validation, blueprint access, and document seeding.
+     * validation, authoring-schema access, and document seeding.
      *
      * A core `Quill` renders directly: pass it to `engine.render(quill, doc)`.
      *
@@ -141,7 +141,8 @@ export class Quiver {
      *   - `invalid_ref` if ref is malformed
      *   - `quill_not_found` if ref does not match any version in this quiver
      *   - propagates I/O errors from the loader unchanged
-     *   - propagates validation errors from Quill.fromTree() unchanged
+     *   - propagates errors from Quill.fromTree() or Quill.fromBundle() unchanged,
+     *     a bundle the format refuses among them as `quill::bundle_*`
      */
     async getQuill(ref) {
         const canonicalRef = this.resolve(ref);
@@ -156,12 +157,13 @@ export class Quiver {
         return entry;
     }
     /**
-     * Internal: load the tree + construct via Quill.fromTree. Errors propagate.
+     * Internal: load the tree or bundle + construct via Quill.fromTree or
+     * Quill.fromBundle. Errors propagate.
      *
-     * The tree is held only for the length of this call: the quill cache holds the
-     * materialized result, and it is the one cache. A second tree cache beside it
-     * would buy a retry after a `Quill.fromTree` throw its refetch, which is a
-     * saved round-trip on the path where the quill is broken.
+     * The source is held only for the length of this call: the quill cache holds the
+     * materialized result, and it is the one cache. A second source cache beside it
+     * would buy a retry after a throw its refetch, which is a saved round-trip on the
+     * path where the quill is broken.
      *
      * Every caller arrives through `resolve` or the catalog itself, so the ref is
      * catalog-backed by construction and the loader needs no gate.
@@ -172,11 +174,11 @@ export class Quiver {
      */
     async #materializeQuill(canonicalRef) {
         const at = canonicalRef.indexOf('@');
-        const [{ Quill }, tree] = await Promise.all([
+        const [{ Quill }, source] = await Promise.all([
             init(),
-            this.#loader.loadTree(canonicalRef.slice(0, at), canonicalRef.slice(at + 1))
+            this.#loader.load(canonicalRef.slice(0, at), canonicalRef.slice(at + 1))
         ]);
-        return Quill.fromTree(tree);
+        return source instanceof Uint8Array ? Quill.fromBundle(source) : Quill.fromTree(source);
     }
 }
 export { create as createQuiver };

package/dist/ref.d.ts

@@ -8,7 +8,7 @@ export interface ParsedQuillRef {
 }
 /**
  * Whether `name` is a quill name: `[a-z][a-z0-9_]*`, at most 64 characters, the
- * engine's rule. A quiver's own name and every catalog row are held to it.
+ * Quillmark's rule. A quiver's own name and every catalog row are held to it.
  */
 export declare function isQuillName(name: string): boolean;
 /**

package/dist/ref.js

@@ -3,7 +3,7 @@ const NAME_RE = /^[a-z][a-z0-9_]{0,63}$/;
 const SELECTOR_RE = /^\d+\.\d+(\.\d+)?$/;
 /**
  * Whether `name` is a quill name: `[a-z][a-z0-9_]*`, at most 64 characters, the
- * engine's rule. A quiver's own name and every catalog row are held to it.
+ * Quillmark's rule. A quiver's own name and every catalog row are held to it.
  */
 export function isQuillName(name) {
     return NAME_RE.test(name);

package/dist/signature.d.ts

@@ -1,6 +1,6 @@
 /**
  * TrueType, OpenType or a collection of either; WOFF or WOFF2 where `path` names one.
- * The engine parses sfnt alone, so a `.ttf` holding WOFF bytes is refused.
+ * Quillmark parses sfnt alone, so a `.ttf` holding WOFF bytes is refused.
  */
 export declare const isFont: (bytes: Uint8Array, path: string) => boolean;
 export declare const isZip: (bytes: Uint8Array) => boolean;

package/dist/signature.js

@@ -1,13 +1,14 @@
 /**
- * The leading bytes of what an artifact holds. A host answering a missing name with a
- * page of its own answers 200, and nothing else read here tells that page from a font.
+ * Leading bytes. A host answering a missing name with a page of its own answers 200, so a
+ * bundle is read only once it opens as a zip; and Typst substitutes a font it cannot parse
+ * without a word, so `build` packs a font file only once it opens as a font.
  */
 const SFNT = ['\0\x01\0\0', 'OTTO', 'true', 'ttcf'];
 const WOFF = ['wOFF', 'wOF2'];
 const opens = (bytes, magic) => bytes.length >= magic.length && [...magic].every((c, i) => bytes[i] === c.charCodeAt(0));
 /**
  * TrueType, OpenType or a collection of either; WOFF or WOFF2 where `path` names one.
- * The engine parses sfnt alone, so a `.ttf` holding WOFF bytes is refused.
+ * Quillmark parses sfnt alone, so a `.ttf` holding WOFF bytes is refused.
  */
 export const isFont = (bytes, path) => (/\.woff2?$/i.test(path) ? WOFF : SFNT).some((magic) => opens(bytes, magic));
 export const isZip = (bytes) => opens(bytes, 'PK\x03\x04');

package/dist/source-loader.d.ts

@@ -38,5 +38,5 @@ export declare function readQuillTree(quillDir: string): Promise<Map<string, Uin
 export declare class SourceLoader implements QuiverLoader {
     private readonly rootDir;
     constructor(rootDir: string);
-    loadTree(name: string, version: string): Promise<Map<string, Uint8Array>>;
+    load(name: string, version: string): Promise<Map<string, Uint8Array>>;
 }

package/dist/source-loader.js

@@ -34,7 +34,7 @@ function refuseUnnamedQuill(quillName, quiverName) {
  * Refuse a `Quill.yaml` whose `quill.name` or `quill.version` disagrees with the
  * path it sits at: the catalog serves the path, and a document saved from the quill
  * names what `Quill.yaml` says. A canonical version has one spelling, so the declared
- * one is compared as written. A field absent or not a string is the engine's to report
+ * one is compared as written. A field absent or not a string is Quillmark's to report
  * when the quill loads.
  */
 function refuseMisplacedQuill(raw, name, version, quiverName) {
@@ -226,7 +226,7 @@ export class SourceLoader {
     constructor(rootDir) {
         this.rootDir = rootDir;
     }
-    async loadTree(name, version) {
+    async load(name, version) {
         const quillDir = join(this.rootDir, 'quills', name, version);
         return readQuillTree(quillDir);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quillmark/quiver",
-	"version": "0.38.1",
+	"version": "0.39.0",
 	"description": "A quiver of Quillmark quills: load one, pack one, hand out quills.",
 	"type": "module",
 	"license": "Apache-2.0",
@@ -42,7 +42,7 @@
 		"NOTICE"
 	],
 	"peerDependencies": {
-		"@quillmark/wasm": ">=0.126.0-0"
+		"@quillmark/wasm": ">=0.133.0-0"
 	},
 	"dependencies": {
 		"fflate": "^0.8.2",