@quillmark/quiver 0.21.0 → 0.22.0

package/dist/build.js

@@ -8,7 +8,7 @@
 import { QuiverError } from './errors.js';
 import { packFiles } from './bundle.js';
 import { NAME_DIGEST_LENGTH } from './digest.js';
-import { POINTER_FORMAT } from './format.js';
+import { MANIFEST_VERSION, 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
@@ -155,8 +155,9 @@ export async function buildQuiver(sourceDir, outDir) {
             }
         }
         const manifest = {
-            version: 1,
+            version: MANIFEST_VERSION,
             name: meta.name,
+            ...(meta.description === undefined ? {} : { description: meta.description }),
             quills: manifestQuills
         };
         const manifestJson = JSON.stringify(manifest, null, 2);

package/dist/built-loader.js

@@ -9,7 +9,7 @@ import { QuiverError } from './errors.js';
 import { unpackFiles } from './bundle.js';
 import { isCanonicalSemver, compareSemver } from './semver.js';
 import { NAME_DIGEST_LENGTH, sha256Hex } from './digest.js';
-import { POINTER_FORMAT } from './format.js';
+import { MANIFEST_VERSION, POINTER_FORMAT } from './format.js';
 import { createQuiver } from './quiver.js';
 /**
  * Fetch, then check the bytes against the digest their name carries. That
@@ -142,13 +142,21 @@ function parseManifest(raw) {
         throw new QuiverError('quiver_invalid', 'Manifest must be a JSON object');
     }
     const obj = parsed;
-    assertNoUnknownKeys(obj, ['version', 'name', 'quills'], 'manifest');
-    if (obj['version'] !== 1) {
-        throw new QuiverError('quiver_invalid', `Manifest version must be 1, got ${String(obj['version'])}`);
+    assertNoUnknownKeys(obj, ['version', 'name', 'description', 'quills'], 'manifest');
+    const version = obj['version'];
+    if (typeof version !== 'number' || !Number.isInteger(version) || version < 1) {
+        throw new QuiverError('quiver_invalid', `Manifest version must be a positive integer, got ${JSON.stringify(version)}`);
+    }
+    if (version > MANIFEST_VERSION) {
+        throw new QuiverError('quiver_invalid', `This quiver's manifest is version ${version} and this loader reads ${MANIFEST_VERSION}. ` +
+            `Upgrade @quillmark/quiver, or for a served client the client itself, which carries the copy that reads this.`);
     }
     if (typeof obj['name'] !== 'string' || obj['name'].length === 0) {
         throw new QuiverError('quiver_invalid', 'Manifest must have a non-empty string "name" field');
     }
+    if (obj['description'] !== undefined && typeof obj['description'] !== 'string') {
+        throw new QuiverError('quiver_invalid', `Manifest "description" must be a string if present, got ${typeof obj['description']}`);
+    }
     if (!Array.isArray(obj['quills'])) {
         throw new QuiverError('quiver_invalid', 'Manifest must have a "quills" array');
     }
@@ -188,8 +196,8 @@ function parseManifest(raw) {
         });
     }
     return {
-        version: 1,
         name: obj['name'],
+        description: obj['description'],
         quills
     };
 }
@@ -245,5 +253,5 @@ export async function loadBuiltQuiver(transport) {
         }
         index.set(key, entry);
     }
-    return createQuiver(manifest.name, catalogOf(index), new BuiltLoader(transport, index));
+    return createQuiver(manifest.name, manifest.description, catalogOf(index), new BuiltLoader(transport, index));
 }

package/dist/format.d.ts

@@ -9,3 +9,13 @@
  * `version` instead.
  */
 export declare const POINTER_FORMAT = 1;
+/**
+ * The manifest's shape, stated in the document and refused to be read past. Version 2
+ * carries the quiver's `description`; version 1 is the same document without it.
+ *
+ * The manifest is closed, so a field added to it is a field an older reader rejects as an
+ * unknown key, naming neither what happened nor what to do. The version is what that
+ * reader reads first instead, and a manifest above its own is refused with the upgrade
+ * named.
+ */
+export declare const MANIFEST_VERSION = 2;

package/dist/format.js

@@ -9,3 +9,13 @@
  * `version` instead.
  */
 export const POINTER_FORMAT = 1;
+/**
+ * The manifest's shape, stated in the document and refused to be read past. Version 2
+ * carries the quiver's `description`; version 1 is the same document without it.
+ *
+ * The manifest is closed, so a field added to it is a field an older reader rejects as an
+ * unknown key, naming neither what happened nor what to do. The version is what that
+ * reader reads first instead, and a manifest above its own is refused with the upgrade
+ * named.
+ */
+export const MANIFEST_VERSION = 2;

package/dist/node.js

@@ -34,7 +34,7 @@ export async function fromDir(pathOrFileUrl) {
         ? fileURLToPath(new URL('.', pathOrFileUrl))
         : pathOrFileUrl;
     const { meta, catalog } = await scanSourceQuiver(dir);
-    return createQuiver(meta.name, catalog, new SourceLoader(dir));
+    return createQuiver(meta.name, meta.description, catalog, new SourceLoader(dir));
 }
 /**
  * Loads a packed (build-output) quiver from a local directory containing

package/dist/quiver.d.ts

@@ -17,10 +17,12 @@ export interface QuiverLoader {
  * Exported as `createQuiver` for this package's loaders and reachable from no
  * entry in `exports`, so a consumer holds the factories and nothing else.
  */
-declare let create: (name: string, catalog: Map<string, string[]>, loader: QuiverLoader) => Quiver;
+declare let create: (name: string, description: string | undefined, catalog: Map<string, string[]>, loader: QuiverLoader) => Quiver;
 export declare class Quiver {
     #private;
     readonly name: string;
+    /** What `Quiver.yaml` says the collection is; `undefined` where the field is absent. */
+    readonly description: string | undefined;
     /**
      * Private constructor. A Quiver comes from a factory (`Quiver.fromBuiltUrl`,
      * `Quiver.fromBuiltFiles`, or `fromDir` / `fromBuiltDir` from

package/dist/quiver.js

@@ -19,6 +19,8 @@ import { matchesSemverSelector, chooseHighestVersion } from './semver.js';
 let create;
 export class Quiver {
     name;
+    /** What `Quiver.yaml` says the collection is; `undefined` where the field is absent. */
+    description;
     #catalog;
     #loader;
     /**
@@ -33,13 +35,14 @@ export class Quiver {
      * `Quiver.fromBuiltFiles`, or `fromDir` / `fromBuiltDir` from
      * `@quillmark/quiver/node`), which is what names the thing being read.
      */
-    constructor(name, catalog, loader) {
+    constructor(name, description, catalog, loader) {
         this.name = name;
+        this.description = description;
         this.#catalog = new Map(catalog);
         this.#loader = loader;
     }
     static {
-        create = (name, catalog, loader) => new Quiver(name, catalog, loader);
+        create = (name, description, catalog, loader) => new Quiver(name, description, catalog, loader);
     }
     /**
      * Browser-safe factory. Loads build output from an HTTP/HTTPS URL.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quillmark/quiver",
-	"version": "0.21.0",
+	"version": "0.22.0",
 	"description": "A quiver of Quillmark quills: load one, pack one, hand out quills.",
 	"type": "module",
 	"license": "Apache-2.0",
@@ -21,7 +21,7 @@
 	],
 	"author": "Quillmark Contributors",
 	"engines": {
-		"node": ">=22"
+		"node": ">=24"
 	},
 	"exports": {
 		".": {
@@ -42,7 +42,7 @@
 		"NOTICE"
 	],
 	"peerDependencies": {
-		"@quillmark/wasm": ">=0.103.0-0"
+		"@quillmark/wasm": ">=0.104.0-0"
 	},
 	"dependencies": {
 		"fflate": "^0.8.2",