@quillmark/quiver 0.20.0 → 0.21.0

package/dist/build.js

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

package/dist/built-loader.d.ts

@@ -22,12 +22,5 @@ export interface BuiltTransport {
 export interface FetchOptions {
     revalidate?: boolean;
 }
-/**
- * Load a build-output quiver via the given transport.
- *
- * 1. Fetches latest.json (pointer) and parses it.
- * 2. Fetches the manifest file it points to and validates it.
- * 3. Builds a catalog from manifest entries (versions sorted descending).
- * 4. Returns a Quiver instance backed by a BuiltLoader.
- */
+/** Load a build-output quiver via the given transport. */
 export declare function loadBuiltQuiver(transport: BuiltTransport): Promise<Quiver>;

package/dist/built-loader.js

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

package/dist/format.d.ts

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

package/dist/format.js

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

package/dist/node.d.ts

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

package/dist/node.js

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

package/dist/quiver-yaml.d.ts

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

package/dist/quiver-yaml.js

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

package/dist/quiver.d.ts

@@ -1,12 +1,11 @@
 /**
- * Quiver — primary runtime abstraction for a collection of quills.
+ * A collection of quills, addressed by ref. One class over a composed
+ * `QuiverLoader`, source-backed or built, so what a quiver reads is the loader's
+ * business and never the class's.
  *
- * Polymorphism via composition: internally stores a pluggable loader
- * (either source-backed or build-output-backed).
- *
- * This module is browser-safe: only `fromBuiltUrl`, `fromBuiltFiles` and the
- * instance API live here. The filesystem factories are free functions in
- * `./node.js`; the class is the same either way.
+ * Browser-safe: only `fromBuiltUrl`, `fromBuiltFiles` and the instance API live
+ * here. The filesystem factories are free functions in `./node.js`; the class is
+ * the same either way.
  */
 import type { Quill } from '@quillmark/wasm';
 /** Loader strategy: source or build output. Package-internal. */
@@ -101,7 +100,7 @@ export declare class Quiver {
      * first. Materializes once and caches per canonical ref — concurrent calls
      * coalesce into a single load.
      *
-     * BORROWED, not handed over: the quill is the quiver's, shared with every
+     * Borrowed, not handed over: the quill is the quiver's, shared with every
      * other caller for the same ref, and lives as long as the quiver. Do not
      * `free()` it: the next `getQuill` for that ref would hand out a freed
      * handle. A caller wanting one of its own mints it from `.toTree()`.

package/dist/quiver.js

@@ -1,12 +1,11 @@
 /**
- * Quiver — primary runtime abstraction for a collection of quills.
+ * A collection of quills, addressed by ref. One class over a composed
+ * `QuiverLoader`, source-backed or built, so what a quiver reads is the loader's
+ * business and never the class's.
  *
- * Polymorphism via composition: internally stores a pluggable loader
- * (either source-backed or build-output-backed).
- *
- * This module is browser-safe: only `fromBuiltUrl`, `fromBuiltFiles` and the
- * instance API live here. The filesystem factories are free functions in
- * `./node.js`; the class is the same either way.
+ * Browser-safe: only `fromBuiltUrl`, `fromBuiltFiles` and the instance API live
+ * here. The filesystem factories are free functions in `./node.js`; the class is
+ * the same either way.
  */
 import { QuiverError } from './errors.js';
 import { init } from '@quillmark/wasm';
@@ -23,7 +22,7 @@ export class Quiver {
     #catalog;
     #loader;
     /**
-     * Cache of materialized quills, keyed by canonical ref. A `Quill` is now
+     * Cache of materialized quills, keyed by canonical ref. A `Quill` is
      * engine-free, portable data (`Quill.fromTree`), so one instance per ref is
      * shared across every engine. Promise values so concurrent getQuill calls
      * coalesce into a single materialization.
@@ -146,7 +145,7 @@ export class Quiver {
      * first. Materializes once and caches per canonical ref — concurrent calls
      * coalesce into a single load.
      *
-     * BORROWED, not handed over: the quill is the quiver's, shared with every
+     * Borrowed, not handed over: the quill is the quiver's, shared with every
      * other caller for the same ref, and lives as long as the quiver. Do not
      * `free()` it: the next `getQuill` for that ref would hand out a freed
      * handle. A caller wanting one of its own mints it from `.toTree()`.

package/dist/ref.d.ts

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

package/dist/ref.js

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

package/dist/source-loader.d.ts

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

package/dist/source-loader.js

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

package/dist/transports/http-transport.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quillmark/quiver",
-	"version": "0.20.0",
+	"version": "0.21.0",
 	"description": "A quiver of Quillmark quills: load one, pack one, hand out quills.",
 	"type": "module",
 	"license": "Apache-2.0",