@quillmark/quiver 0.16.0 → 0.18.1

package/dist/bin/quiver.d.ts

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

package/dist/bin/quiver.js

@@ -1,43 +1,32 @@
 #!/usr/bin/env node
 /**
- * Quiver CLI — build, test, and preview a quiver collection.
+ * Quiver CLI — build and test a quiver collection. Two verbs, and they are the
+ * whole of what a quiver author gets from here: `build` packs, `test` gates.
+ * Looking at rendered output is studio's, an app rather than a verb.
  *
  * Commands:
- *   quiver build [--out <dir>]
- *   quiver test
- *   quiver preview [--out <dir>] [--format <fmt>] [--quiet]
- *                  [--include <ref>...] [--exclude <ref>...]
+ *   quillmark-quiver build [--out <dir>]
+ *   quillmark-quiver test
  *
- * Engine discovery (for `test` and `preview`):
+ * Engine discovery (for `test`):
  *   1. Named export `engine` from `quiver.config.js` at the collection root,
  *      if the file exists.
  *   2. Auto-imported `@quillmark/wasm` from the collection's node_modules.
  */
-import { createRequire } from "node:module";
-import { join } from "node:path";
-import { pathToFileURL } from "node:url";
-import { Quiver } from "../node.js";
-import { renderQuiverSamples } from "../preview.js";
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { build as buildQuiver, fromDir } from '../node.js';
 // ---------------------------------------------------------------------------
 // Arg parsing helpers
 // ---------------------------------------------------------------------------
 const argv = process.argv.slice(2);
 const command = argv[0];
+/** One flag with a value. `build --out` is the only one either verb takes. */
 function flag(name) {
     const i = argv.indexOf(name);
     return i !== -1 && i + 1 < argv.length ? argv[i + 1] : undefined;
 }
-function multiFlag(name) {
-    const out = [];
-    for (let i = 0; i < argv.length - 1; i++) {
-        if (argv[i] === name)
-            out.push(argv[i + 1]);
-    }
-    return out;
-}
-function hasFlag(name) {
-    return argv.includes(name);
-}
 // ---------------------------------------------------------------------------
 // Engine discovery
 // ---------------------------------------------------------------------------
@@ -47,16 +36,21 @@ async function loadEngine(cwd) {
     // backend itself). A quiver.config.js may export a custom `engine`.
     let wasm;
     try {
-        const req = createRequire(pathToFileURL(join(cwd, "package.json")).href);
-        const wasmPath = req.resolve("@quillmark/wasm");
+        const req = createRequire(pathToFileURL(join(cwd, 'package.json')).href);
+        const wasmPath = req.resolve('@quillmark/wasm');
         wasm = (await import(pathToFileURL(wasmPath).href));
+        // Instantiate the core. Every `@quillmark/wasm` export throws
+        // `runtime::not_initialized` until `init()` resolves, and `new Engine()` is
+        // lazy, so without this the throw arrives at the first render and reads as a
+        // failing quill rather than an uninitialized runtime.
+        await wasm.init();
     }
     catch {
         // Not installed — a quiver.config.js may still provide an engine.
     }
     // 1. Named `engine` export from quiver.config.js, if present.
     try {
-        const cfg = await import(pathToFileURL(join(cwd, "quiver.config.js")).href);
+        const cfg = await import(pathToFileURL(join(cwd, 'quiver.config.js')).href);
         if (cfg.engine != null) {
             return cfg.engine;
         }
@@ -67,8 +61,8 @@ async function loadEngine(cwd) {
     // 2. Auto-discover from @quillmark/wasm.
     if (wasm == null) {
         throw new Error("Cannot find @quillmark/wasm in this collection's node_modules.\n" +
-            "  Install it:  npm install @quillmark/wasm\n" +
-            "  Or export { engine } from quiver.config.js for a custom engine.");
+            '  Install it:  npm install @quillmark/wasm\n' +
+            '  Or export { engine } from quiver.config.js for a custom engine.');
     }
     return new wasm.Engine();
 }
@@ -77,18 +71,18 @@ async function loadEngine(cwd) {
 // ---------------------------------------------------------------------------
 async function build() {
     const cwd = process.cwd();
-    const outDir = flag("--out") ?? "dist";
-    console.log(`quiver build: ${cwd} → ${outDir}`);
-    await Quiver.build(cwd, outDir);
-    console.log("done.");
+    const outDir = flag('--out') ?? 'dist';
+    console.log(`quillmark-quiver build: ${cwd} → ${outDir}`);
+    await buildQuiver(cwd, outDir);
+    console.log('done.');
 }
 async function test() {
     const cwd = process.cwd();
     const engine = await loadEngine(cwd);
-    const quiver = await Quiver.fromDir(cwd);
+    const quiver = await fromDir(cwd);
     const names = quiver.quillNames();
     if (names.length === 0) {
-        console.error("error: quiver has no quills");
+        console.error('error: quiver has no quills');
         process.exit(1);
     }
     let pass = 0;
@@ -107,7 +101,7 @@ async function test() {
                     doc.free();
                 }
                 if (!Array.isArray(result.artifacts) || result.artifacts.length === 0) {
-                    throw new Error("example render produced no artifacts");
+                    throw new Error('example render produced no artifacts');
                 }
                 console.log(`pass  ${ref}`);
                 pass++;
@@ -123,34 +117,11 @@ async function test() {
     if (fail > 0)
         process.exit(1);
 }
-async function preview() {
-    const cwd = process.cwd();
-    const engine = await loadEngine(cwd);
-    const outDir = flag("--out");
-    const format = flag("--format");
-    const quiet = hasFlag("--quiet");
-    const include = multiFlag("--include");
-    const exclude = multiFlag("--exclude");
-    await renderQuiverSamples(cwd, {
-        engine,
-        ...(outDir !== undefined && { outDir }),
-        ...(format !== undefined && { format }),
-        quiet,
-        ...(include.length > 0 && { include }),
-        ...(exclude.length > 0 && { exclude }),
-    });
-}
 // ---------------------------------------------------------------------------
 // Dispatch
 // ---------------------------------------------------------------------------
 function usage() {
-    console.error([
-        "Usage:",
-        "  quiver build [--out <dir>]",
-        "  quiver test",
-        "  quiver preview [--out <dir>] [--format <fmt>] [--quiet]",
-        "                 [--include <ref>...] [--exclude <ref>...]",
-    ].join("\n"));
+    console.error(['Usage:', '  quillmark-quiver build [--out <dir>]', '  quillmark-quiver test'].join('\n'));
 }
 function die(err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -158,15 +129,12 @@ function die(err) {
     process.exit(1);
 }
 switch (command) {
-    case "build":
+    case 'build':
         build().catch(die);
         break;
-    case "test":
+    case 'test':
         test().catch(die);
         break;
-    case "preview":
-        preview().catch(die);
-        break;
     default:
         usage();
         process.exit(1);

package/dist/build.d.ts

@@ -1,25 +1,25 @@
 /**
  * Build logic — internal, Node-only.
  *
- * All Node.js built-in imports are done dynamically inside `buildQuiver`
- * so that a type-only import of `BuildOptions` from `src/index.ts` does
- * NOT pull `node:fs` or `node:crypto` into browser bundles.
+ * All Node.js built-in imports are done dynamically inside `buildQuiver`, so
+ * a module reaching this one for types alone does not pull `node:fs` or
+ * `node:crypto` into a browser bundle.
  */
-/** Reserved for future build options (e.g. compression level, filters). */
-export type BuildOptions = Record<string, never>;
 /**
  * Reads a Source Quiver, validates it, and writes the build output to outDir.
  *
- * Output layout:
+ * Output layout. Every name but the pointer carries the SHA-256 of what it
+ * names, which is what the loader checks on fetch:
  *   outDir/
- *     latest.json                   # stable pointer to the current manifest
- *     manifest.<md5prefix6>.json    # hashed manifest
- *     <name>@<version>.<md5>.zip    # one bundle per quill
+ *     latest.json                     # the format, and a stable pointer to the manifest
+ *     manifest.<sha256:12>.json       # hashed manifest
+ *     <name>@<version>.<sha256:12>.zip  # one bundle per quill
  *     store/
- *       <md5>                       # dehydrated font bytes (full hash, no ext)
+ *       <sha256>                      # dehydrated font bytes (full hash, no ext)
  *
  * Throws:
  *   - `quiver_invalid` on source validation failures (propagated from scanner)
- *   - `transport_error` on I/O failures
+ *   - `transport_error` on I/O failures, and on an outDir the build would have
+ *     to delete something it does not own to write (see `assertSafeOutDir`)
  */
-export declare function buildQuiver(sourceDir: string, outDir: string, _opts?: BuildOptions): Promise<void>;
+export declare function buildQuiver(sourceDir: string, outDir: string): Promise<void>;

package/dist/build.js

@@ -1,50 +1,86 @@
 /**
  * Build logic — internal, Node-only.
  *
- * All Node.js built-in imports are done dynamically inside `buildQuiver`
- * so that a type-only import of `BuildOptions` from `src/index.ts` does
- * NOT pull `node:fs` or `node:crypto` into browser bundles.
+ * All Node.js built-in imports are done dynamically inside `buildQuiver`, so
+ * a module reaching this one for types alone does not pull `node:fs` or
+ * `node:crypto` into a browser bundle.
  */
-import { QuiverError } from "./errors.js";
-import { packFiles } from "./bundle.js";
+import { QuiverError } from './errors.js';
+import { packFiles } from './bundle.js';
+import { NAME_DIGEST_LENGTH } from './digest.js';
+import { POINTER_FORMAT } from './format.js';
 /** Font file extensions recognised by the builder (case-insensitive). */
 const FONT_EXT = /\.(ttf|otf|woff|woff2)$/i;
+/**
+ * The build's first act is `rm(outDir, { recursive: true })`, so an outDir that
+ * is, or contains, the source quiver or the working directory deletes the
+ * thing the caller was building from. `quillmark-quiver build --out .` and a
+ * mistyped `--out ..` are both one keystroke away, and the failure is
+ * unrecoverable, so an outDir that owns the caller is refused up front.
+ *
+ * An outDir *inside* sourceDir stays allowed: the scan reads the source before
+ * any write, and `dist/` under the quiver root is the ordinary layout.
+ *
+ * Throws `transport_error`.
+ */
+function assertSafeOutDir(path, sourceDir, outDir) {
+    const out = path.resolve(outDir);
+    /** True when `dir` is `target` or an ancestor of it. */
+    const owns = (target) => {
+        const rel = path.relative(out, path.resolve(target));
+        return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+    };
+    const what = owns(sourceDir)
+        ? 'the source quiver'
+        : owns(process.cwd())
+            ? 'the working directory'
+            : undefined;
+    if (what !== undefined) {
+        throw new QuiverError('transport_error', `Refusing to build into "${outDir}": the build clears its output directory, and this one holds ${what} ("${out}"). Point --out at a directory the build owns.`);
+    }
+}
 /**
  * Reads a Source Quiver, validates it, and writes the build output to outDir.
  *
- * Output layout:
+ * Output layout. Every name but the pointer carries the SHA-256 of what it
+ * names, which is what the loader checks on fetch:
  *   outDir/
- *     latest.json                   # stable pointer to the current manifest
- *     manifest.<md5prefix6>.json    # hashed manifest
- *     <name>@<version>.<md5>.zip    # one bundle per quill
+ *     latest.json                     # the format, and a stable pointer to the manifest
+ *     manifest.<sha256:12>.json       # hashed manifest
+ *     <name>@<version>.<sha256:12>.zip  # one bundle per quill
  *     store/
- *       <md5>                       # dehydrated font bytes (full hash, no ext)
+ *       <sha256>                      # dehydrated font bytes (full hash, no ext)
  *
  * Throws:
  *   - `quiver_invalid` on source validation failures (propagated from scanner)
- *   - `transport_error` on I/O failures
+ *   - `transport_error` on I/O failures, and on an outDir the build would have
+ *     to delete something it does not own to write (see `assertSafeOutDir`)
  */
-export async function buildQuiver(sourceDir, outDir, _opts) {
+export async function buildQuiver(sourceDir, outDir) {
     // Dynamic imports keep this module safe to type-import from browser contexts.
-    const { join } = await import("node:path");
-    const { mkdir, rm, writeFile, } = await import("node:fs/promises");
-    const { createHash } = await import("node:crypto");
-    const { scanSourceQuiver, readQuillTree } = await import("./source-loader.js");
+    const path = await import('node:path');
+    const { join } = path;
+    const { mkdir, rm, writeFile } = await import('node:fs/promises');
+    const { createHash } = await import('node:crypto');
+    const { scanSourceQuiver, readQuillTree } = await import('./source-loader.js');
+    // 0. The first write is a recursive delete of outDir; refuse the paths where
+    //    that deletes the caller instead of a previous build.
+    assertSafeOutDir(path, sourceDir, outDir);
     // 1. Scan + validate source quiver (throws quiver_invalid on bad input).
     const { meta, catalog } = await scanSourceQuiver(sourceDir);
     // 2. Clear and recreate outDir + outDir/store/.
     try {
         await rm(outDir, { recursive: true, force: true });
-        await mkdir(join(outDir, "store"), { recursive: true });
+        await mkdir(join(outDir, 'store'), { recursive: true });
     }
     catch (err) {
-        throw new QuiverError("transport_error", `Failed to prepare output directory "${outDir}": ${err.message}`, { cause: 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);
+            const quillDir = join(sourceDir, 'quills', quillName, version);
             // a. Read quill file tree.
             const tree = await readQuillTree(quillDir);
             // b. Partition fonts vs content.
@@ -61,13 +97,15 @@ export async function buildQuiver(sourceDir, outDir, _opts) {
             // c. Dehydrate fonts into store/.
             const fonts = {};
             for (const [path, bytes] of fontEntries) {
-                const hash = createHash("md5").update(bytes).digest("hex");
-                const storePath = join(outDir, "store", hash);
+                // Full width: the store is keyed by hash, so two distinct fonts
+                // sharing a prefix would merge into one entry.
+                const hash = createHash('sha256').update(bytes).digest('hex');
+                const storePath = join(outDir, 'store', hash);
                 try {
                     await writeFile(storePath, bytes);
                 }
                 catch (err) {
-                    throw new QuiverError("transport_error", `Failed to write font store entry "${storePath}": ${err.message}`, { cause: err });
+                    throw new QuiverError('transport_error', `Failed to write font store entry "${storePath}": ${err.message}`, { cause: err });
                 }
                 fonts[path] = hash;
             }
@@ -78,7 +116,10 @@ export async function buildQuiver(sourceDir, outDir, _opts) {
             }
             const zipBytes = packFiles(contentRecord);
             // e–f. Compute bundle hash and name.
-            const bundleHash = createHash("md5").update(zipBytes).digest("hex").slice(0, 6);
+            const bundleHash = createHash('sha256')
+                .update(zipBytes)
+                .digest('hex')
+                .slice(0, NAME_DIGEST_LENGTH);
             const bundleName = `${quillName}@${version}.${bundleHash}.zip`;
             // g. Write bundle zip.
             const bundlePath = join(outDir, bundleName);
@@ -86,7 +127,7 @@ export async function buildQuiver(sourceDir, outDir, _opts) {
                 await writeFile(bundlePath, zipBytes);
             }
             catch (err) {
-                throw new QuiverError("transport_error", `Failed to write bundle "${bundlePath}": ${err.message}`, { cause: err });
+                throw new QuiverError('transport_error', `Failed to write bundle "${bundlePath}": ${err.message}`, { cause: err });
             }
             // h. Record manifest entry.
             manifestQuills.push({ name: quillName, version, bundle: bundleName, fonts });
@@ -96,25 +137,29 @@ export async function buildQuiver(sourceDir, outDir, _opts) {
     const manifest = {
         version: 1,
         name: meta.name,
-        quills: manifestQuills,
+        quills: manifestQuills
     };
     const manifestJson = JSON.stringify(manifest, null, 2);
-    const manifestHash = createHash("md5").update(manifestJson).digest("hex").slice(0, 6);
+    const manifestHash = createHash('sha256')
+        .update(manifestJson)
+        .digest('hex')
+        .slice(0, NAME_DIGEST_LENGTH);
     const manifestFileName = `manifest.${manifestHash}.json`;
     const manifestPath = join(outDir, manifestFileName);
     try {
-        await writeFile(manifestPath, manifestJson, "utf-8");
+        await writeFile(manifestPath, manifestJson, 'utf-8');
     }
     catch (err) {
-        throw new QuiverError("transport_error", `Failed to write manifest "${manifestPath}": ${err.message}`, { cause: err });
+        throw new QuiverError('transport_error', `Failed to write manifest "${manifestPath}": ${err.message}`, { cause: err });
     }
-    // 9–10. Write stable pointer latest.json.
-    const pointer = { manifest: manifestFileName };
-    const pointerPath = join(outDir, "latest.json");
+    // 9–10. Write stable pointer latest.json. The format is stamped here and read first,
+    //       so a client older than the tree says so rather than misreading it.
+    const pointer = { format: POINTER_FORMAT, manifest: manifestFileName };
+    const pointerPath = join(outDir, 'latest.json');
     try {
-        await writeFile(pointerPath, JSON.stringify(pointer), "utf-8");
+        await writeFile(pointerPath, JSON.stringify(pointer), 'utf-8');
     }
     catch (err) {
-        throw new QuiverError("transport_error", `Failed to write pointer "${pointerPath}": ${err.message}`, { cause: err });
+        throw new QuiverError('transport_error', `Failed to write pointer "${pointerPath}": ${err.message}`, { cause: err });
     }
 }

package/dist/built-loader.d.ts

@@ -1,20 +1,26 @@
 /**
- * Built-quiver loader — browser-safe at module level.
- * Internal; not exported from index.ts.
+ * Built-quiver loader: reads a packed artifact through a transport, validates
+ * its pointer and manifest, and hands back a Quiver whose loader fetches
+ * bundles and fonts on demand, each checked against the digest in its name.
  *
- * Exposes:
- *   - BuiltTransport interface (implemented by HttpTransport)
- *   - loadBuiltQuiver(transport) → Quiver
- *
- * NO static node: imports — this module is safe to load in browser contexts.
+ * Package-internal, and browser-safe: no static `node:` imports at any level.
  */
-import { Quiver } from "./quiver.js";
+import type { Quiver } from './quiver.js';
 /**
  * Transport abstraction: fetch raw bytes by relative path within the packed
- * artifact. Sole implementation is HttpTransport (browser + Node).
+ * artifact. Implemented by HttpTransport (browser + Node) and FsBuiltTransport
+ * (Node).
  */
 export interface BuiltTransport {
-    fetchBytes(relativePath: string): Promise<Uint8Array>;
+    fetchBytes(relativePath: string, opts?: FetchOptions): Promise<Uint8Array>;
+}
+/**
+ * `revalidate` marks the one request that must not be answered from a cache:
+ * `latest.json`, the only name in the artifact that is not content-addressed.
+ * Everything else is safe to cache forever by construction.
+ */
+export interface FetchOptions {
+    revalidate?: boolean;
 }
 /**
  * Load a build-output quiver via the given transport.
@@ -25,9 +31,3 @@ export interface BuiltTransport {
  * 4. Returns a Quiver instance backed by a BuiltLoader.
  */
 export declare function loadBuiltQuiver(transport: BuiltTransport): Promise<Quiver>;
-/**
- * Seed a quiver from caller-provided manifest bytes, skipping the latest.json
- * pointer fetch. `transport` is used only for lazy bundle/font fetches.
- * Throws `quiver_invalid` on malformed bytes.
- */
-export declare function seedBuiltQuiver(transport: BuiltTransport, manifestBytes: Uint8Array): Quiver;