@quillmark/quiver 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @quillmark/quiver
 
-Quiver registry and packaging for Quillmark — load, compose, and pack collections of quills for rendering with `@quillmark/wasm`.
+Load and build collections of quills for rendering with `@quillmark/wasm`.
 
 ## Install
 
@@ -8,69 +8,122 @@ Quiver registry and packaging for Quillmark — load, compose, and pack collecti
 npm install @quillmark/quiver @quillmark/wasm
 ```
 
-## Quick start
+## Distribution model
+
+A Quiver has one authored shape: the **source layout** (`Quiver.yaml` at the
+package root, quills under `quills/<name>/<x.y.z>/`). Authors publish it as
+an npm package. Consumers decide how to consume it:
+
+- **Node consumers** load the source layout directly with `Quiver.fromPackage`.
+- **Browser consumers** run `Quiver.build(...)` as a build step and serve the
+  output as static assets, loading it with `Quiver.fromBuilt`.
+
+Each loader names exactly what it loads: `fromPackage` and `fromDir` always
+read source layouts; `fromBuilt` always reads build output over HTTP/HTTPS.
+No auto-detection, no branching on artifact shape.
+
+This keeps the author flow to a single command (`npm publish` or `git tag`)
+and puts the deployment-topology decision where it belongs: with the
+consumer.
+
+## Authoring a quiver
+
+Lay out the source per the spec, then publish to npm (or push a git tag):
+
+```
+my-quiver/
+  Quiver.yaml
+  quills/
+    <name>/<x.y.z>/
+      Quill.yaml
+      ...
+  package.json
+```
+
+Recommended CI: use the bundled `@quillmark/quiver/testing` harness — it
+loads with `Quiver.fromDir` and exercises every quill so validation errors
+surface on publish, not on the consumer's build. The harness uses
+`node:test` (built into Node 18+); no extra test-runner dependency
+required. If you prefer vitest/jest/mocha, write a 12-line loop against
+the main API instead.
+
+## Consuming a quiver (Node)
 
 ```ts
 import { Quillmark, Document } from "@quillmark/wasm";
-import { Quiver, QuiverRegistry } from "@quillmark/quiver/node";
-
-// 1. Load a source quiver from disk (Node.js only)
-const quiver = await Quiver.fromSourceDir("./my-quiver");
+import { Quiver } from "@quillmark/quiver/node";
 
-// 2. Build a registry with one or more quivers
 const engine = new Quillmark();
-const registry = new QuiverRegistry({ engine, quivers: [quiver] });
+const quiver = await Quiver.fromPackage("@org/my-quiver");
 
-// 3. Resolve a ref, obtain a render-ready quill, and render
 const doc = Document.fromMarkdown(markdownString);
-const canonicalRef = await registry.resolve(doc.quillRef);
-const quill = await registry.getQuill(canonicalRef);
+const quill = await quiver.getQuill(doc.quillRef, { engine });
 const result = quill.render(doc, { format: "pdf" });
 ```
 
-## HTTP (browser / CDN)
+`getQuill` accepts both selector refs (`"memo"`, `"memo@1"`) and canonical
+refs (`"memo@1.0.0"`). It resolves the selector, materializes the quill via
+`engine.quill(tree)`, and caches per (engine, canonical-ref). Concurrent
+calls for the same ref share a single load.
 
-```ts
-import { Quiver, QuiverRegistry } from "@quillmark/quiver";
+If you only need the canonical ref (without materializing), use `resolve`:
 
-const quiver = await Quiver.fromHttp("https://cdn.example.com/my-quiver");
-const registry = new QuiverRegistry({ engine, quivers: [quiver] });
+```ts
+const canonicalRef = await quiver.resolve("memo"); // "memo@1.1.0"
 ```
 
-## Packed directory (Node.js)
+## Consuming a quiver (browser)
+
+Browsers cannot read the source layout directly, so build at deploy time and
+serve the output as static files:
 
 ```ts
+// build script (Node) — typically wired into your existing build pipeline
 import { Quiver } from "@quillmark/quiver/node";
 
-const quiver = await Quiver.fromPackedDir("./dist/my-quiver");
+await Quiver.build(
+  "./node_modules/@org/my-quiver",
+  "./public/quivers/my-quiver",
+);
 ```
 
-## Pack a source quiver
-
 ```ts
-import { Quiver } from "@quillmark/quiver/node";
+// browser runtime
+import { Quiver } from "@quillmark/quiver";
 
-await Quiver.pack("./my-quiver", "./dist/my-quiver");
+const quiver = await Quiver.fromBuilt("/quivers/my-quiver/");
+const quill = await quiver.getQuill(doc.quillRef, { engine });
 ```
 
-## Warm (prefetch all quills)
+## Advanced: pre-built distribution to a CDN
+
+If you need to ship the runtime artifact directly (e.g. consumers cannot run
+a Node build step), publish `Quiver.build` output to a CDN and have
+consumers point `fromBuilt` at the CDN URL:
 
 ```ts
-await registry.warm();
-```
+import { Quiver } from "@quillmark/quiver/node";
 
-## Multi-quiver composition
+await Quiver.build("./my-quiver", "./dist/my-quiver");
+// upload ./dist/my-quiver to https://cdn.example.com/quivers/my-quiver/
+const quiver = await Quiver.fromBuilt("https://cdn.example.com/quivers/my-quiver/");
+```
 
-Quivers are scanned in order. The first quiver with any matching candidate wins;
-the highest matching version within that quiver is returned.
+## Warm (prefetch all quill trees)
 
 ```ts
-const registry = new QuiverRegistry({
-  engine,
-  quivers: [primaryQuiver, fallbackQuiver],
-});
+await quiver.warm();
 ```
 
+`warm()` is network-only: it fetches every quill's tree and caches them.
+It does not require an engine and does not materialize Quill instances —
+that happens lazily on the first `getQuill` call, which is microseconds.
+A subsequent `getQuill` reuses the cached tree, skipping the fetch.
+
+Once a tree has been turned into a Quill, the cached tree is dropped so
+its bytes can be GC'd — the materialized Quill is the runtime artifact.
+Calling `warm()` again refills the tree cache.
+
 ## Error handling
 
 All errors are instances of `QuiverError` with a `code` field.
@@ -79,7 +132,7 @@ All errors are instances of `QuiverError` with a `code` field.
 import { QuiverError } from "@quillmark/quiver";
 
 try {
-  const canonicalRef = await registry.resolve("unknown_quill");
+  await quiver.resolve("unknown_quill");
 } catch (err) {
   if (err instanceof QuiverError) {
     console.error(err.code);    // e.g. "quill_not_found"
@@ -89,8 +142,8 @@ try {
 }
 ```
 
-Error codes: `invalid_ref`, `quill_not_found`, `quiver_invalid`, `transport_error`, `quiver_collision`.
+Error codes: `invalid_ref`, `quill_not_found`, `quiver_invalid`, `transport_error`.
 
 ## Full specification
 
-See [PROGRAM.md](./PROGRAM.md) for the complete API surface, packed format specification, and design decisions.
+See [PROGRAM.md](./PROGRAM.md) for the complete API surface, runtime artifact format specification, and design decisions.

package/dist/build.d.ts

@@ -0,0 +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.
+ */
+/** 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:
+ *   outDir/
+ *     Quiver.json                   # stable pointer
+ *     manifest.<md5prefix6>.json    # hashed manifest
+ *     <name>@<version>.<md5>.zip    # one bundle per quill
+ *     store/
+ *       <md5>                       # dehydrated font bytes (full hash, no ext)
+ *
+ * Throws:
+ *   - `quiver_invalid` on source validation failures (propagated from scanner)
+ *   - `transport_error` on I/O failures
+ */
+export declare function buildQuiver(sourceDir: string, outDir: string, _opts?: BuildOptions): Promise<void>;

package/dist/{pack.js → build.js}

@@ -1,16 +1,16 @@
 /**
- * Pack logic — internal, Node-only.
+ * Build logic — internal, Node-only.
  *
- * All Node.js built-in imports are done dynamically inside `packQuiver` so
- * that a type-only import of `PackOptions` 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 that a type-only import of `BuildOptions` from `src/index.ts` does
+ * NOT pull `node:fs` or `node:crypto` into browser bundles.
  */
 import { QuiverError } from "./errors.js";
 import { packFiles } from "./bundle.js";
-/** Font file extensions recognised by the packer (case-insensitive). */
+/** Font file extensions recognised by the builder (case-insensitive). */
 const FONT_EXT = /\.(ttf|otf|woff|woff2)$/i;
 /**
- * Reads a Source Quiver, validates it, and writes a Packed Quiver to outDir.
+ * Reads a Source Quiver, validates it, and writes the build output to outDir.
  *
  * Output layout:
  *   outDir/
@@ -24,7 +24,7 @@ const FONT_EXT = /\.(ttf|otf|woff|woff2)$/i;
  *   - `quiver_invalid` on source validation failures (propagated from scanner)
  *   - `transport_error` on I/O failures
  */
-export async function packQuiver(sourceDir, outDir, _opts) {
+export async function buildQuiver(sourceDir, outDir, _opts) {
     // 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");

package/dist/{packed-loader.d.ts → built-loader.d.ts}

@@ -1,27 +1,27 @@
 /**
- * Packed Quiver loader — browser-safe at module level.
+ * Built-quiver loader — browser-safe at module level.
  * Internal; not exported from index.ts.
  *
  * Exposes:
- *   - PackedTransport interface (also used by FsTransport / HttpTransport)
- *   - loadPackedQuiver(transport) → Quiver
+ *   - BuiltTransport interface (implemented by HttpTransport)
+ *   - loadBuiltQuiver(transport) → Quiver
  *
  * NO static node: imports — this module is safe to load in browser contexts.
  */
 import { Quiver } from "./quiver.js";
 /**
  * Transport abstraction: fetch raw bytes by relative path within the packed
- * artifact. Implementations are FsTransport (Node) and HttpTransport (browser).
+ * artifact. Sole implementation is HttpTransport (browser + Node).
  */
-export interface PackedTransport {
+export interface BuiltTransport {
     fetchBytes(relativePath: string): Promise<Uint8Array>;
 }
 /**
- * Load a Packed Quiver via the given transport.
+ * Load a build-output quiver via the given transport.
  *
  * 1. Fetches Quiver.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 PackedLoader.
+ * 4. Returns a Quiver instance backed by a BuiltLoader.
  */
-export declare function loadPackedQuiver(transport: PackedTransport): Promise<Quiver>;
+export declare function loadBuiltQuiver(transport: BuiltTransport): Promise<Quiver>;

package/dist/{packed-loader.js → built-loader.js}

@@ -1,10 +1,10 @@
 /**
- * Packed Quiver loader — browser-safe at module level.
+ * Built-quiver loader — browser-safe at module level.
  * Internal; not exported from index.ts.
  *
  * Exposes:
- *   - PackedTransport interface (also used by FsTransport / HttpTransport)
- *   - loadPackedQuiver(transport) → Quiver
+ *   - BuiltTransport interface (implemented by HttpTransport)
+ *   - loadBuiltQuiver(transport) → Quiver
  *
  * NO static node: imports — this module is safe to load in browser contexts.
  */
@@ -31,8 +31,8 @@ function validateFontHash(hash, context) {
         throw new QuiverError("quiver_invalid", `${context}: font hash is invalid: "${hash}"`);
     }
 }
-// ─── PackedLoader implementation ─────────────────────────────────────────────
-class PackedLoader {
+// ─── BuiltLoader implementation ─────────────────────────────────────────────
+class BuiltLoader {
     transport;
     index;
     /** Font byte cache: hash → in-flight or resolved Promise. */
@@ -50,7 +50,7 @@ class PackedLoader {
         // through. The transport will surface a transport_error naturally.
         // (Defensive: this should not be reachable in normal operation.)
         if (!entry) {
-            throw new QuiverError("transport_error", `Quill "${name}@${version}" not found in packed quiver manifest`, { version, ref: `${name}@${version}` });
+            throw new QuiverError("transport_error", `Quill "${name}@${version}" not found in built-quiver manifest`, { version, ref: `${name}@${version}` });
         }
         // 1. Fetch + unpack bundle zip.
         const zipBytes = await this.transport.fetchBytes(entry.bundle);
@@ -177,14 +177,14 @@ function parseManifest(raw) {
 }
 // ─── Main entry point ─────────────────────────────────────────────────────────
 /**
- * Load a Packed Quiver via the given transport.
+ * Load a build-output quiver via the given transport.
  *
  * 1. Fetches Quiver.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 PackedLoader.
+ * 4. Returns a Quiver instance backed by a BuiltLoader.
  */
-export async function loadPackedQuiver(transport) {
+export async function loadBuiltQuiver(transport) {
     // 1. Fetch and parse pointer.
     let pointerBytes;
     try {
@@ -226,7 +226,7 @@ export async function loadPackedQuiver(transport) {
         versions.sort((a, b) => compareSemver(b, a));
     }
     // 4. Build loader.
-    const loader = new PackedLoader(transport, index);
+    const loader = new BuiltLoader(transport, index);
     // 5. Return Quiver via internal factory.
     return Quiver._fromLoader(manifest.name, catalogRaw, loader);
 }

package/dist/engine-types.d.ts

@@ -11,7 +11,7 @@
  * test doubles) satisfy the contract structurally.
  *
  * These types are INTERNAL — never re-exported from index.ts. They exist so
- * registry.ts never imports from @quillmark/wasm directly and so test doubles
+ * quiver.ts never imports from @quillmark/wasm directly and so test doubles
  * can satisfy the contract without pulling the real WASM module.
  *
  * Call-site note: Quiver never invokes `render` or `open` itself; consumers do

package/dist/engine-types.js

@@ -11,7 +11,7 @@
  * test doubles) satisfy the contract structurally.
  *
  * These types are INTERNAL — never re-exported from index.ts. They exist so
- * registry.ts never imports from @quillmark/wasm directly and so test doubles
+ * quiver.ts never imports from @quillmark/wasm directly and so test doubles
  * can satisfy the contract without pulling the real WASM module.
  *
  * Call-site note: Quiver never invokes `render` or `open` itself; consumers do

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type QuiverErrorCode = "invalid_ref" | "quill_not_found" | "quiver_invalid" | "transport_error" | "quiver_collision";
+export type QuiverErrorCode = "invalid_ref" | "quill_not_found" | "quiver_invalid" | "transport_error";
 export declare class QuiverError extends Error {
     readonly code: QuiverErrorCode;
     /** Offending ref string, when available. */

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { QuiverError } from "./errors.js";
 export type { QuiverErrorCode } from "./errors.js";
 export { Quiver } from "./quiver.js";
-export { QuiverRegistry } from "./registry.js";
-export type { PackOptions } from "./pack.js";
+export type { BuildOptions } from "./build.js";
+export type { QuillmarkLike, QuillLike } from "./engine-types.js";

package/dist/index.js

@@ -1,4 +1,3 @@
 // Main browser-safe entrypoint.
 export { QuiverError } from "./errors.js";
 export { Quiver } from "./quiver.js";
-export { QuiverRegistry } from "./registry.js";

package/dist/node.js

@@ -1,5 +1,5 @@
 // Node-only entrypoint.
 // Re-export everything from the main browser-safe entrypoint.
-// Node-only factories (fromSourceDir, fromPackedDir, pack) are methods on
+// Node-only factories (fromPackage, fromDir, build) are methods on
 // Quiver itself — no additional exports are needed here.
 export * from "./index.js";

package/dist/quiver.d.ts

@@ -2,10 +2,11 @@
  * Quiver — primary runtime abstraction for a collection of quills.
  *
  * Polymorphism via composition: internally stores a pluggable loader
- * (either source-backed or packed-backed).
+ * (either source-backed or build-output-backed).
  */
-import type { PackOptions } from "./pack.js";
-/** @internal Internal loader strategy: source or packed. */
+import type { BuildOptions } from "./build.js";
+import type { QuillmarkLike, QuillLike } from "./engine-types.js";
+/** @internal Internal loader strategy: source or build output. */
 export interface QuiverLoader {
     loadTree(name: string, version: string): Promise<Map<string, Uint8Array>>;
 }
@@ -18,33 +19,40 @@ export declare class Quiver {
      * Static methods inside can still call it.
      */
     private constructor();
-    /** @internal Used by loadPackedQuiver. Not part of the public API. */
+    /** @internal Used by loadBuiltQuiver. Not part of the public API. */
     static _fromLoader(name: string, catalog: Map<string, string[]>, loader: QuiverLoader): Quiver;
     /**
-     * Node-only factory. Reads a Source Quiver from a directory containing
-     * `Quiver.yaml` and `quills/<name>/<version>/Quill.yaml` entries.
+     * Node-only factory. Resolves an npm specifier against `node_modules` and
+     * loads the source layout at the package root.
      *
-     * Uses dynamic import of `./source-loader.js` so that importing this module
-     * in a browser environment does not cause a crash at module evaluation time.
+     * The resolved package must have `Quiver.yaml` at its root.
      *
-     * Throws `quiver_invalid` on schema violations, `transport_error` on I/O failure.
+     * Throws `transport_error` on resolution/I/O failure, `quiver_invalid`
+     * on schema violations.
      */
-    static fromSourceDir(path: string): Promise<Quiver>;
+    static fromPackage(specifier: string): Promise<Quiver>;
     /**
-     * Node-only factory. Loads a Packed Quiver from a local directory.
+     * Node-only factory. Reads a Source Quiver from a local directory containing
+     * `Quiver.yaml` and `quills/<name>/<version>/Quill.yaml` entries.
      *
-     * Uses dynamic imports so this module stays browser-safe at evaluation time.
+     * Also accepts `import.meta.url`-style `file://` URLs as a convenience for
+     * tests; the URL's parent directory is used as the source root.
      *
-     * Throws `transport_error` on I/O failure, `quiver_invalid` on format errors.
+     * Throws `quiver_invalid` on schema violations, `transport_error` on I/O failure.
      */
-    static fromPackedDir(path: string): Promise<Quiver>;
+    static fromDir(pathOrFileUrl: string): Promise<Quiver>;
     /**
-     * Browser-safe factory. Loads a Packed Quiver from an HTTP base URL.
+     * Browser-safe factory. Loads build output from an HTTP/HTTPS URL.
      *
-     * Throws `transport_error` on network/HTTP failure, `quiver_invalid` on
-     * format errors.
+     * Origin-relative URLs (e.g. `/quivers/foo/`) are accepted in browser
+     * environments. `file://` URLs are rejected — local build output is
+     * not loadable in V1; serve over HTTP or use `fromPackage`/`fromDir`
+     * against the source.
+     *
+     * Throws `transport_error` on network/HTTP failure, `quiver_invalid`
+     * on format errors.
      */
-    static fromHttp(url: string): Promise<Quiver>;
+    static fromBuilt(url: string): Promise<Quiver>;
     /** Returns all known quill names, sorted lexicographically. */
     quillNames(): string[];
     /**
@@ -53,22 +61,61 @@ export declare class Quiver {
      */
     versionsOf(name: string): string[];
     /**
-     * Node-only tooling. Writes a Packed Quiver artifact to outDir.
+     * Node-only tooling. Reads the Source Quiver at sourceDir, validates it,
+     * and writes the runtime build artifact to outDir.
      *
-     * Uses dynamic import of `./pack.js` so that this module stays browser-safe
-     * at evaluation time.
+     * Uses dynamic import of `./build.js` so that this module stays
+     * browser-safe at evaluation time.
      *
      * Throws `quiver_invalid` on source validation failures,
      * `transport_error` on I/O failures.
      */
-    static pack(sourceDir: string, outDir: string, opts?: PackOptions): Promise<void>;
+    static build(sourceDir: string, outDir: string, opts?: BuildOptions): Promise<void>;
     /**
      * Lazily loads the file tree for a specific quill version.
      *
      * Returns `Map<string, Uint8Array>` suitable for `engine.quill(tree)`.
-     * Does NOT cache the result — caching is the registry's concern.
+     * Does NOT cache the result — caching of materialized Quill instances
+     * happens in `getQuill`.
      *
      * Throws `transport_error` if name/version not in catalog or I/O fails.
      */
     loadTree(name: string, version: string): Promise<Map<string, Uint8Array>>;
+    /**
+     * Resolves a selector ref → canonical ref (e.g. "memo" → "memo@1.1.0").
+     *
+     * Selector forms: `name`, `name@x`, `name@x.y`, `name@x.y.z`. Picks the
+     * highest matching version in this quiver.
+     *
+     * Throws:
+     *   - `invalid_ref` if ref fails parseQuillRef
+     *   - `quill_not_found` if no version matches
+     */
+    resolve(ref: string): Promise<string>;
+    /**
+     * Returns a render-ready `Quill` for a ref (selector or canonical).
+     *
+     * Selector refs (e.g. `"memo"`, `"memo@1"`) are resolved to canonical
+     * form first. Materializes via `engine.quill(tree)` on first call;
+     * caches per (engine, canonical-ref). Reuses a tree cached by `warm()`
+     * (or a previous `getQuill`) so the network fetch isn't paid twice.
+     * Concurrent calls for the same ref coalesce into a single load.
+     *
+     * Throws:
+     *   - `invalid_ref` if ref is malformed
+     *   - `quill_not_found` if ref does not match any version in this quiver
+     *   - propagates I/O errors from loadTree unchanged
+     *   - propagates engine errors from engine.quill() unchanged
+     */
+    getQuill(ref: string, opts: {
+        engine: QuillmarkLike;
+    }): Promise<QuillLike>;
+    /**
+     * Prefetches the tree for every quill version in this quiver. Fail-fast.
+     *
+     * Network-bound only — does not materialize Quill instances and does not
+     * require an engine. Subsequent `getQuill` calls reuse the cached trees,
+     * skipping the fetch. Rejects on the first fetch failure.
+     */
+    warm(): Promise<void>;
 }