@quillmark/quiver 0.2.0 → 0.3.0

package/PROGRAM.md

@@ -18,28 +18,43 @@ This means Quiver must own quill selection and lifecycle entirely. There is no e
 
 ## Core Decisions
 
-### 1) Quiver Shapes and Transports Are Orthogonal
-
-Two on-disk/data shapes:
-
-- **Source Quiver** (authoring shape)
-  - Human-authored, git-friendly
-  - Root `Quiver.yaml`
-  - Quills under `quills/<name>/<version>/Quill.yaml`
-  - Assets in normal source layout
-- **Packed Quiver** (distribution/runtime artifact)
-  - Hashed manifest
-  - Bundle zips
-  - Dehydrated shared font store (`store/<md5>`)
-  - Stable pointer file to current hashed manifest
-
-Transport is a separate axis for **Packed Quiver** loading:
-
-- `http` (browser/runtime delivery)
-- `fs` (packed artifact loaded from local disk)
-- future transports can be added without changing packed format
-
-**Naming decision:** use `pack()` (format operation), not transport-specific names.
+### 1) One Authored Shape; A Build Output Derived From It
+
+There is one user-facing shape: the **Source Quiver**.
+
+- Human-authored, git-friendly
+- Root `Quiver.yaml`
+- Quills under `quills/<name>/<version>/Quill.yaml`
+- Assets in normal source layout
+
+A build step (`Quiver.build`) derives a **runtime artifact** from the source.
+This artifact is not a peer "format" — it is the source layout's `dist/`
+output, optimized for browser delivery (hashed manifest, per-quill bundle
+zips, dehydrated shared font store, stable pointer file). Authors do not
+version it, publish it, or check it into git.
+
+Loaders are paired 1:1 with what they load:
+
+- `Quiver.fromPackage(specifier)` and `Quiver.fromDir(path)` load the
+  **source** layout (Node only).
+- `Quiver.fromBuilt(url)` loads the **build output** over HTTP/HTTPS
+  (browser-safe; works in Node too).
+
+There is no auto-detection: each loader's name commits to what it expects.
+
+**Naming decisions:**
+- The verb is `build()`. Pairs with `fromBuilt()` (past participle = "the
+  built one"). Avoids collision with `npm pack`, JS bundler vocabulary,
+  and the internal "bundle zips" term.
+- Loaders for source layouts are named by **where the source lives**
+  (`Package` / `Dir`). The loader for build output is named by **what it
+  loads** (`Built`), not by transport — `fromUrl` was rejected because it
+  hides the artifact type.
+- Build output is HTTP-served only. Loading a built artifact from local
+  disk is intentionally unsupported in V1; consumers either spin up a
+  local HTTP server or use `fromPackage`/`fromDir` against the source.
+  Adding `Quiver.fromBuiltDir(path)` later is purely additive if a real
+  use case appears.
 
 ### 2) `Quiver.yaml` Is Required in Source Quivers
 
@@ -57,10 +72,16 @@ Unknown fields in `Quiver.yaml` are a **validation error** (`quiver_invalid`). S
 ### 3) `QuillSource` Becomes Quiver-Centric
 
 - Re-express `QuillSource` concepts around Quivers
-- Split old filesystem concept into:
-  - **Source filesystem loader** (reads Source Quiver directly)
-  - **Packed filesystem transport** (loads Packed Quiver artifact from disk)
-- Treat HTTP as a Packed transport, not a separate format concept
+- Three loaders, each with one input shape and one shape-of-thing-loaded:
+  - `Quiver.fromPackage(specifier)` — Node-only; resolves an npm specifier
+    against `node_modules` and loads the source layout at the package root
+  - `Quiver.fromDir(path)` — Node-only; loads source layout from a local
+    directory. Also accepts `import.meta.url`-style `file://` URLs as a
+    convenience for tests (the URL's parent directory is used)
+  - `Quiver.fromBuilt(url)` — browser-safe; loads build output from an
+    `http(s)://` or origin-relative URL
+- "Transport" is not a first-class concept; HTTP fetching is an internal
+  detail of `fromBuilt`
 
 ### 4) Multi-Quiver Composition with Deterministic Precedence
 
@@ -118,7 +139,10 @@ Canonicalization:
 - `warm()` warms all by default in V1
 - `resolve()` must work even if nothing is warmed
 
-Warm now means "load/prepare quills and artifacts", not "register in engine". There is no engine registration step anymore.
+Warm means "load/prepare quills and materialize render-ready instances",
+not "register in engine". There is no engine registration step anymore.
+Warm semantics are identical for source-loaded and built-output-loaded
+quivers; the loader hides the difference.
 
 ### 7) Engine Boundary: New Canonical Contract (Node / JS–WASM only)
 
@@ -150,16 +174,41 @@ Upstream behavior note:
 
 ### 9) Distribution Strategy
 
-V1 supports:
-
-- npm distribution for Source Quiver projects
-- git/folder-copy consumption of Source Quivers
-- `pack()` output for Packed runtime distribution
-
-Clarification:
-
-- npm/git are developer distribution channels
-- packed artifacts are runtime delivery artifacts
+**Source-first distribution.** The published artifact is the **Source
+Quiver** — an npm package whose root contains `Quiver.yaml`. Consumers
+choose how to consume it:
+
+- **Node consumers** load the source layout directly:
+  ```ts
+  const quiver = await Quiver.fromPackage("@org/my-quiver");
+  ```
+- **Browser consumers** run a build step against the resolved source dir
+  and serve the output as static assets:
+  ```ts
+  // build step (Node)
+  await Quiver.build("./node_modules/@org/my-quiver", "./public/quivers/my-quiver");
+  // browser runtime
+  const quiver = await Quiver.fromBuilt("/quivers/my-quiver/");
+  ```
+
+Rationale:
+
+- Author release pipeline is `npm publish` (or `git tag`). No second
+  artifact, no CDN, no hash bookkeeping outside the npm tarball.
+- Deployment topology is the consumer's concern, not the author's.
+- The runtime artifact is a build output of the source, not a peer
+  distribution shape (see §1).
+
+**Pre-built distribution as a published artifact is supported but not
+the default.** Authors who need to ship runtime-ready output directly
+(e.g. their consumers cannot run a Node build step) may publish
+`Quiver.build(...)` output to a CDN and instruct consumers to use
+`Quiver.fromBuilt(<cdn-url>)`. Treated as the exception.
+
+Validation responsibility shifts left: authors should run
+`Quiver.fromDir` and `Quiver.build` in CI so `quiver_invalid` errors
+surface on publish, not on the consumer's build. The bundled
+`@quillmark/quiver/testing` harness covers this.
 
 ---
 
@@ -167,19 +216,20 @@ Clarification:
 
 V1 intentionally retains:
 
-1. Font dehydration as a Packed Quiver property
-2. Consumer validation tooling for Source Quivers (+ optional Packed parity checks)
-3. Manifest pointer resolution for Packed format
-4. HTTP loading as a Packed transport
-5. Source filesystem loading as first-class dev loop
-6. Packed filesystem loading as first-class runtime option
-7. Typed errors (`QuiverError`) with quiver/transport context
-8. Concurrency coalescing for in-flight loads
-9. Preload/fail-fast helpers where they still add value
+1. Font dehydration as a build-output property
+2. Consumer validation tooling for source layouts (+ optional build-parity checks)
+3. Manifest pointer resolution for build output
+4. HTTP/HTTPS loading via `Quiver.fromBuilt`
+5. Source layout loading as first-class dev loop (`fromPackage` / `fromDir`)
+6. Typed errors (`QuiverError`) with quiver/source context
+7. Concurrency coalescing for in-flight loads
+8. Preload/fail-fast helpers where they still add value
 
 Removed from carryover assumptions:
 
 - Any engine-registration cache fast path (`register`/`has`) because upstream removed the capability
+- "Transport" as a user-facing concept (folded into `fromBuilt` internals)
+- Loading build output from local disk (no `fromBuiltDir` in V1; YAGNI)
 
 ---
 
@@ -188,7 +238,7 @@ Removed from carryover assumptions:
 V1 should trim public API where behavior can stay internal:
 
 - Drop internal-only utility exports
-- Keep engine payload and transport internals opaque
+- Keep engine payload and loader internals opaque
 - Consolidate validation exports
 - Avoid duplicate entry points for equivalent validation workflows
 - Do not expose internal quill-object cache mechanisms as public contract
@@ -218,18 +268,22 @@ Errors must include offending ref/version/quiver identifiers when available.
 
 ---
 
-## Runtime + Packaging Model
+## Runtime + Build Model
 
 V1 runtime loading paths:
 
-1. Source Quiver from filesystem (authoring/dev)
-2. Packed Quiver over HTTP (browser/runtime)
-3. Packed Quiver from filesystem (air-gapped/container/runtime)
+1. `Quiver.fromPackage(specifier)` — npm package resolution; loads source
+   (authoring/dev/Node runtime)
+2. `Quiver.fromDir(path)` — local directory; loads source (Node)
+3. `Quiver.fromBuilt(url)` — HTTP(S); loads build output (browser; also
+   works in Node)
 
-V1 packaging behavior:
+V1 build behavior:
 
-- `Quiver.pack()` produces Packed Quiver artifact independent of transport
-- packed output includes pointer + hashed manifest + bundles + dehydrated font store
+- `Quiver.build(srcDir, outDir)` produces the runtime artifact from a
+  source layout
+- output includes pointer + hashed manifest + bundles + dehydrated font store
+  (see "Runtime Artifact Format" below)
 
 Execution behavior:
 
@@ -261,7 +315,11 @@ Caching scope:
 - Non-canonical version directories are a validation error (`quiver_invalid`).
 - Dedup of identical fonts across quills happens at pack time (into `store/<md5>`), not at the source layer.
 
-## Packed Quiver Format (normative)
+## Runtime Artifact Format (normative)
+
+Produced by `Quiver.build()`. Authors do not author this layout; consumers
+do not need to inspect it. It is an implementation detail of build output,
+specified here only because loaders must agree on its shape.
 
 ```
 <root>/
@@ -272,7 +330,7 @@ Caching scope:
     <md5>                                  # raw font bytes, no extension
 ```
 
-**Hash:** MD5 prefix-6, computed with `node:crypto` at `pack()` time only (dev/tooling; not browser runtime).
+**Hash:** MD5 prefix-6, computed with `node:crypto` at `build()` time only (dev/tooling; not browser runtime).
 
 **Pointer** `Quiver.json`:
 ```json
@@ -295,23 +353,36 @@ Caching scope:
 }
 ```
 
-**Bundle zips** contain pure quill content (`Quill.yaml` + templates + partials + non-font assets). Fonts are dehydrated at pack time: their bytes live only in `store/<md5>`; their path→hash mapping lives only in the hashed manifest. Bundles do **not** embed a `fonts.json`.
+**Bundle zips** contain pure quill content (`Quill.yaml` + templates + partials + non-font assets). Fonts are dehydrated at build time: their bytes live only in `store/<md5>`; their path→hash mapping lives only in the hashed manifest. Bundles do **not** embed a `fonts.json`.
 
-Rehydration on load: transport fetches the pointer → hashed manifest → required bundle(s) → required `store/<md5>` blobs; library reconstructs the full in-memory tree and builds a render-ready quill via `engine.quill(tree)`.
+Rehydration on load: the loader fetches the pointer → hashed manifest → required bundle(s) → required `store/<md5>` blobs; library reconstructs the full in-memory tree and builds a render-ready quill via `engine.quill(tree)`.
 
 ## API Surface (V1)
 
-Single class, three factories:
+Single class, three loaders + one builder. Each loader has one input
+shape and one shape-of-thing-loaded; no auto-detection.
 
 ```ts
 class Quiver {
-  // Node-only factories (from `@quillmark/quiver/node`). Fail fast in browser.
-  static fromSourceDir(path: string): Promise<Quiver>;
-  static fromPackedDir(path: string): Promise<Quiver>;
-  // Browser-safe factory (from `@quillmark/quiver` main).
-  static fromHttp(url: string): Promise<Quiver>;
-  // Node-only tooling. Writes a Packed Quiver to outDir.
-  static pack(sourceDir: string, outDir: string, opts?: PackOptions): Promise<void>;
+  // Node-only loader: resolve an npm specifier against node_modules and
+  // load the source layout at the package root.
+  // (From `@quillmark/quiver/node`.)
+  static fromPackage(specifier: string): Promise<Quiver>;
+
+  // Node-only loader: load source layout from a local directory.
+  // Also accepts `import.meta.url`-style `file://` URLs (the URL's parent
+  // directory is used) as a convenience for tests.
+  // (From `@quillmark/quiver/node`.)
+  static fromDir(pathOrFileUrl: string): Promise<Quiver>;
+
+  // Browser-safe loader: load build output from an http(s):// or
+  // origin-relative URL. Throws `transport_error` on file:// inputs.
+  // (From `@quillmark/quiver` main.)
+  static fromBuilt(url: string): Promise<Quiver>;
+
+  // Node-only tooling: produce the runtime artifact from a source layout.
+  // (From `@quillmark/quiver/node`.)
+  static build(sourceDir: string, outDir: string, opts?: BuildOptions): Promise<void>;
 
   readonly name: string; // from Quiver.yaml
 
@@ -345,7 +416,7 @@ class QuiverError extends Error {
 
 **No render wrapper.** Callers invoke `quill.render(doc, opts?)` (and `quill.open(doc)` when needed) after `resolve()` + `getQuill()`. Quiver never mirrors Quillmark render APIs.
 
-**Internal (not exported):** `QuiverTransport`, `QuiverManifest` (runtime shape), `parseQuillRef`, in-flight coalescing state.
+**Internal (not exported):** `QuiverManifest` (runtime shape), `parseQuillRef`, in-flight coalescing state, source-vs-built layout detection.
 
 Hot-path flow:
 ```ts
@@ -360,13 +431,23 @@ const result = quill.render(doc, { format: "pdf" });
 **Name:** `@quillmark/quiver`
 
 **Entrypoints:**
-- `@quillmark/quiver` (main, browser-safe): `Quiver` class with only `fromHttp` functional (Node-only factories/pack throw `transport_error` if reached in browser), `QuiverRegistry`, `QuiverError`, shared types.
-- `@quillmark/quiver/node`: adds `Quiver.fromSourceDir`, `Quiver.fromPackedDir`, `Quiver.pack` behaviors. Single `Quiver` class — Node-only factories fail fast outside Node.
+- `@quillmark/quiver` (main, browser-safe): `Quiver` class with only
+  `fromBuilt` functional (Node-only loaders/builder throw
+  `transport_error` if reached in browser), `QuiverRegistry`,
+  `QuiverError`, `QuillmarkLike`, `QuillLike`, shared types.
+- `@quillmark/quiver/node`: adds `Quiver.fromPackage`, `Quiver.fromDir`,
+  `Quiver.build` behaviors. Single `Quiver` class — Node-only factories
+  fail fast outside Node.
+- `@quillmark/quiver/testing` (Node-only): single export
+  `runQuiverTests(metaUrlOrDir, engine)` built on `node:test` (zero
+  external test-runner dependency). Optional convenience; users on other
+  test runners wire their own loops against the main API.
 
 **Dependencies:**
 - Peer: `@quillmark/wasm@>=0.59.0-rc.2` with `Quillmark`, `Document.fromMarkdown`, `engine.quill(tree)`, and `quill.render(doc, opts?)` APIs.
 - Runtime: `fflate ^0.8.2` for zip read/write (Node + browser)
-- Dev-only: `node:crypto` (MD5 hashing in `pack()` — never reached at runtime)
+- Dev-only: `node:crypto` (MD5 hashing in `build()` — never reached at runtime)
+- No test-runner peer dependency; `/testing` uses `node:test` (built-in)
 
 ---
 
@@ -388,12 +469,12 @@ const result = quill.render(doc, { format: "pdf" });
 
 All V1 planner questions resolved; implementation plan can proceed against the spec above.
 
-1. ~~Final `Quiver` interface shape and transport factoring style~~ → Single `Quiver` class, three static factories (`fromHttp`, `fromSourceDir`, `fromPackedDir`). Transport kept internal (no `fromTransport` in V1; YAGNI).
+1. ~~Final `Quiver` interface shape and transport factoring style~~ → Single `Quiver` class, three loaders (`fromPackage`, `fromDir`, `fromBuilt`) + one builder (`build`). Each loader names what it loads; no auto-detection.
 2. ~~Final `Quiver.yaml` schema and unknown-field policy~~ → See §2: alphanumeric `name` and optional tooling-only `description`. Unknown fields are `quiver_invalid`.
 3. ~~Canonical ref grammar and parser API contract~~ → Internal `parseQuillRef`, not exported. Selector syntax per §5. Throws `invalid_ref`.
 4. ~~Exact warning policy for shadowed refs across quivers~~ → No warnings in V1. Precedence is a hard filter (§4); duplicate quiver names error as `quiver_collision`.
-5. ~~Validation API shape consolidation~~ → No separate validation API. Validation errors surface as `QuiverError('quiver_invalid')` during load or `pack()`.
-6. ~~Pack artifact directory structure~~ → See "Packed Quiver Format (normative)".
+5. ~~Validation API shape consolidation~~ → No separate validation API. Validation errors surface as `QuiverError('quiver_invalid')` during load or `build()`.
+6. ~~Build output directory structure~~ → See "Runtime Artifact Format (normative)".
 7. ~~Node/browser entrypoint split~~ → See "Package Structure": main + `/node` subpath, single `Quiver` class.
 8. ~~Final exported type names~~ → `Quiver`, `QuiverRegistry`, `QuiverError`. Hot-path entry is `QuiverRegistry.resolve(ref)` + `QuiverRegistry.getQuill(canonicalRef)`.
 
@@ -413,7 +494,8 @@ Local copies in this repo for `@quillmark/quiver` implementation:
 ## Success Criteria
 
 - A team can author and validate a Source Quiver locally with fast filesystem loops
-- A packed artifact can be loaded via HTTP or local filesystem with equivalent semantics
+- Build output can be loaded over HTTP/HTTPS with parity behavior in browser and Node
+- Each loader names exactly what it loads — no auto-detection, no ambiguous return shape
 - Multi-quiver resolution is deterministic and matches precedence hard-filter rules
 - Selector behavior is predictable and explicitly documented
 - Quiver (Node) integrates via `engine.quill(tree)` + `quill.render(...)` only (no engine quill registration path)

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`.
+Quiver registry and build tooling for Quillmark — load, compose, and build collections of quills for rendering with `@quillmark/wasm`.
 
 ## Install
 
@@ -8,49 +8,97 @@ 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");
+const quiver = await Quiver.fromPackage("@org/my-quiver");
 
-// 2. Build a registry with one or more quivers
 const engine = new Quillmark();
 const registry = new QuiverRegistry({ engine, quivers: [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 result = quill.render(doc, { format: "pdf" });
 ```
 
-## HTTP (browser / CDN)
+## Consuming a quiver (browser)
+
+Browsers cannot read the source layout directly, so build at deploy time and
+serve the output as static files:
 
 ```ts
-import { Quiver, QuiverRegistry } from "@quillmark/quiver";
+// build script (Node) — typically wired into your existing build pipeline
+import { Quiver } from "@quillmark/quiver/node";
 
-const quiver = await Quiver.fromHttp("https://cdn.example.com/my-quiver");
-const registry = new QuiverRegistry({ engine, quivers: [quiver] });
+await Quiver.build(
+  "./node_modules/@org/my-quiver",
+  "./public/quivers/my-quiver",
+);
 ```
 
-## Packed directory (Node.js)
-
 ```ts
-import { Quiver } from "@quillmark/quiver/node";
+// browser runtime
+import { Quiver, QuiverRegistry } from "@quillmark/quiver";
 
-const quiver = await Quiver.fromPackedDir("./dist/my-quiver");
+const quiver = await Quiver.fromBuilt("/quivers/my-quiver/");
+const registry = new QuiverRegistry({ engine, quivers: [quiver] });
 ```
 
-## Pack a source quiver
+## 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
 import { Quiver } from "@quillmark/quiver/node";
 
-await Quiver.pack("./my-quiver", "./dist/my-quiver");
+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/");
 ```
 
 ## Warm (prefetch all quills)
@@ -93,4 +141,4 @@ Error codes: `invalid_ref`, `quill_not_found`, `quiver_invalid`, `transport_erro
 
 ## 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/index.d.ts

@@ -2,4 +2,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/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,10 @@
  * 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";
+/** @internal Internal loader strategy: source or build output. */
 export interface QuiverLoader {
     loadTree(name: string, version: string): Promise<Map<string, Uint8Array>>;
 }
@@ -18,33 +18,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.
+     *
+     * 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.
+     * 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,15 +60,16 @@ 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.
      *

package/dist/quiver.js

@@ -2,7 +2,7 @@
  * 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 { QuiverError } from "./errors.js";
 import { assertNode } from "./assert-node.js";
@@ -20,51 +20,73 @@ export class Quiver {
         this.#catalog = new Map(catalog);
         this.#loader = loader;
     }
-    /** @internal Used by loadPackedQuiver. Not part of the public API. */
+    /** @internal Used by loadBuiltQuiver. Not part of the public API. */
     static _fromLoader(name, catalog, loader) {
         return new Quiver(name, catalog, loader);
     }
     /**
-     * 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 async fromSourceDir(path) {
-        assertNode("Quiver.fromSourceDir");
-        const { scanSourceQuiver, SourceLoader } = await import("./source-loader.js");
-        const { meta, catalog } = await scanSourceQuiver(path);
-        const loader = new SourceLoader(path);
-        return new Quiver(meta.name, catalog, loader);
+    static async fromPackage(specifier) {
+        assertNode("Quiver.fromPackage");
+        const { createRequire } = await import("node:module");
+        const { dirname } = await import("node:path");
+        const req = createRequire(import.meta.url);
+        let yamlPath;
+        try {
+            yamlPath = req.resolve(`${specifier}/Quiver.yaml`);
+        }
+        catch (err) {
+            throw new QuiverError("transport_error", `Failed to resolve quiver package "${specifier}": ${err.message}`, { cause: err });
+        }
+        return Quiver.fromDir(dirname(yamlPath));
     }
     /**
-     * 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 async fromPackedDir(path) {
-        assertNode("Quiver.fromPackedDir");
-        const { FsTransport } = await import("./transports/fs-transport.js");
-        const { loadPackedQuiver } = await import("./packed-loader.js");
-        const transport = new FsTransport(path);
-        return loadPackedQuiver(transport);
+    static async fromDir(pathOrFileUrl) {
+        assertNode("Quiver.fromDir");
+        let dir = pathOrFileUrl;
+        if (pathOrFileUrl.startsWith("file://")) {
+            const { fileURLToPath } = await import("node:url");
+            dir = fileURLToPath(new URL(".", pathOrFileUrl));
+        }
+        const { scanSourceQuiver, SourceLoader } = await import("./source-loader.js");
+        const { meta, catalog } = await scanSourceQuiver(dir);
+        const loader = new SourceLoader(dir);
+        return new Quiver(meta.name, catalog, loader);
     }
     /**
-     * Browser-safe factory. Loads a Packed Quiver from an HTTP base URL.
+     * Browser-safe factory. Loads build output from an HTTP/HTTPS URL.
+     *
+     * 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.
+     * Throws `transport_error` on network/HTTP failure, `quiver_invalid`
+     * on format errors.
      */
-    static async fromHttp(url) {
+    static async fromBuilt(url) {
+        if (url.startsWith("file://")) {
+            throw new QuiverError("transport_error", `Quiver.fromBuilt requires an http(s):// or origin-relative URL; got "${url}". Local build output is not loadable in V1 — serve it over HTTP or load source via fromPackage/fromDir.`);
+        }
         const { HttpTransport } = await import("./transports/http-transport.js");
-        const { loadPackedQuiver } = await import("./packed-loader.js");
+        const { loadBuiltQuiver } = await import("./built-loader.js");
         const transport = new HttpTransport(url);
-        return loadPackedQuiver(transport);
+        return loadBuiltQuiver(transport);
     }
     /** Returns all known quill names, sorted lexicographically. */
     quillNames() {
@@ -78,18 +100,19 @@ export class Quiver {
         return [...(this.#catalog.get(name) ?? [])];
     }
     /**
-     * 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 async pack(sourceDir, outDir, opts) {
-        assertNode("Quiver.pack");
-        const { packQuiver } = await import("./pack.js");
-        return packQuiver(sourceDir, outDir, opts);
+    static async build(sourceDir, outDir, opts) {
+        assertNode("Quiver.build");
+        const { buildQuiver } = await import("./build.js");
+        return buildQuiver(sourceDir, outDir, opts);
     }
     /**
      * Lazily loads the file tree for a specific quill version.

package/dist/source-loader.d.ts

@@ -2,7 +2,7 @@
  * Internal filesystem scanner for Source Quiver layout.
  *
  * Uses Node.js `fs/promises` — this module must only be imported from
- * Node-only contexts (fromSourceDir, etc.).
+ * Node-only contexts (fromDir, fromPackage, etc.).
  */
 import type { QuiverMeta } from "./quiver-yaml.js";
 import type { QuiverLoader } from "./quiver.js";

package/dist/source-loader.js

@@ -2,7 +2,7 @@
  * Internal filesystem scanner for Source Quiver layout.
  *
  * Uses Node.js `fs/promises` — this module must only be imported from
- * Node-only contexts (fromSourceDir, etc.).
+ * Node-only contexts (fromDir, fromPackage, etc.).
  */
 import { readdir, readFile, stat } from "node:fs/promises";
 import { join, relative, sep } from "node:path";

package/dist/testing.d.ts

@@ -1,5 +1,9 @@
 /**
- * Plug-and-play test suite for Quiver authors.
+ * Convenience test harness for Quiver authors using `node:test`.
+ *
+ * Built into Node 18+; no extra test-runner dependency required. If you
+ * prefer vitest, jest, or another runner, write a 12-line loop against
+ * the main API instead — every primitive used here is public.
  *
  * Usage (place this file next to your Quiver.yaml):
  *
@@ -8,32 +12,17 @@
  *   const engine = await Quillmark.load();
  *   runQuiverTests(import.meta.url, engine);
  *
- * Requires vitest in your devDependencies.
- */
-import type { QuillmarkLike, QuillLike } from "./engine-types.js";
-export type { QuillmarkLike, QuillLike };
-/**
- * Returns a lightweight mock engine and a record of every tree passed to it.
- * Useful for writing custom test helpers; not intended as a substitute for the
- * real engine in runQuiverTests (the mock performs no template compilation).
+ * Run with `node --test`.
  */
-export declare function makeMockEngine(): {
-    calls: Array<Map<string, Uint8Array>>;
-    engine: QuillmarkLike;
-};
+import type { QuillmarkLike } from "./engine-types.js";
 /**
- * Registers a Vitest describe block that validates every quill version in the
- * quiver at `sourceDirOrMetaUrl` against the provided Quillmark engine.
- *
- * Pass `import.meta.url` when your test file lives at the quiver root (next to
- * Quiver.yaml). Pass an absolute directory path for any other layout.
+ * Registers a `node:test` describe block that validates every quill
+ * version in the quiver at `metaUrlOrDir` against the provided engine.
  *
- * Each (quill, version) pair gets its own `it()` so failures are reported
- * individually. The quiver and engine are initialised once in `beforeAll`.
+ * Pass `import.meta.url` when this file lives at the quiver root (next
+ * to Quiver.yaml). Pass an absolute directory path for any other layout.
  *
- * Validation covers the full loading pipeline: Quiver.yaml, Quill.yaml, all
- * template files, and engine compilation via engine.quill(tree). A quill that
- * contains a template error will cause its test to fail with the engine's own
- * error message.
+ * Validation covers the full loading pipeline: Quiver.yaml, Quill.yaml,
+ * all template files, and engine compilation via engine.quill(tree).
  */
-export declare function runQuiverTests(sourceDirOrMetaUrl: string, engine: QuillmarkLike): void;
+export declare function runQuiverTests(metaUrlOrDir: string, engine: QuillmarkLike): void;

package/dist/testing.js

@@ -1,5 +1,9 @@
 /**
- * Plug-and-play test suite for Quiver authors.
+ * Convenience test harness for Quiver authors using `node:test`.
+ *
+ * Built into Node 18+; no extra test-runner dependency required. If you
+ * prefer vitest, jest, or another runner, write a 12-line loop against
+ * the main API instead — every primitive used here is public.
  *
  * Usage (place this file next to your Quiver.yaml):
  *
@@ -8,101 +12,43 @@
  *   const engine = await Quillmark.load();
  *   runQuiverTests(import.meta.url, engine);
  *
- * Requires vitest in your devDependencies.
+ * Run with `node --test`.
  */
-import { describe, it, expect, beforeAll } from "vitest";
-import { readdirSync } from "node:fs";
-import { join, basename } from "node:path";
-import { fileURLToPath } from "node:url";
+import { describe, it, before } from "node:test";
 import { Quiver } from "./quiver.js";
 import { QuiverRegistry } from "./registry.js";
 /**
- * Returns a lightweight mock engine and a record of every tree passed to it.
- * Useful for writing custom test helpers; not intended as a substitute for the
- * real engine in runQuiverTests (the mock performs no template compilation).
- */
-export function makeMockEngine() {
-    const calls = [];
-    const engine = {
-        quill(tree) {
-            calls.push(tree);
-            return { render: () => ({ ok: true }) };
-        },
-    };
-    return { calls, engine };
-}
-function resolveSourceDir(sourceDirOrMetaUrl) {
-    if (sourceDirOrMetaUrl.startsWith("file://")) {
-        return fileURLToPath(new URL(".", sourceDirOrMetaUrl));
-    }
-    return sourceDirOrMetaUrl;
-}
-function discoverQuills(sourceDir) {
-    const quillsDir = join(sourceDir, "quills");
-    const results = [];
-    let nameDirs;
-    try {
-        nameDirs = readdirSync(quillsDir, { withFileTypes: true });
-    }
-    catch {
-        return results;
-    }
-    for (const nameEntry of nameDirs) {
-        if (!nameEntry.isDirectory() || nameEntry.name.startsWith("."))
-            continue;
-        let versionDirs;
-        try {
-            versionDirs = readdirSync(join(quillsDir, nameEntry.name), {
-                withFileTypes: true,
-            });
-        }
-        catch {
-            continue;
-        }
-        for (const versionEntry of versionDirs) {
-            if (!versionEntry.isDirectory() || versionEntry.name.startsWith("."))
-                continue;
-            results.push({ name: nameEntry.name, version: versionEntry.name });
-        }
-    }
-    return results;
-}
-/**
- * Registers a Vitest describe block that validates every quill version in the
- * quiver at `sourceDirOrMetaUrl` against the provided Quillmark engine.
+ * Registers a `node:test` describe block that validates every quill
+ * version in the quiver at `metaUrlOrDir` against the provided engine.
  *
- * Pass `import.meta.url` when your test file lives at the quiver root (next to
- * Quiver.yaml). Pass an absolute directory path for any other layout.
+ * Pass `import.meta.url` when this file lives at the quiver root (next
+ * to Quiver.yaml). Pass an absolute directory path for any other layout.
  *
- * Each (quill, version) pair gets its own `it()` so failures are reported
- * individually. The quiver and engine are initialised once in `beforeAll`.
- *
- * Validation covers the full loading pipeline: Quiver.yaml, Quill.yaml, all
- * template files, and engine compilation via engine.quill(tree). A quill that
- * contains a template error will cause its test to fail with the engine's own
- * error message.
+ * Validation covers the full loading pipeline: Quiver.yaml, Quill.yaml,
+ * all template files, and engine compilation via engine.quill(tree).
  */
-export function runQuiverTests(sourceDirOrMetaUrl, engine) {
-    const sourceDir = resolveSourceDir(sourceDirOrMetaUrl);
-    // Enumerate quills synchronously so Vitest can collect test cases before
-    // any async work begins. Errors here (missing quills/ dir, unreadable dirs)
-    // surface as the "has at least one quill" test failing rather than a
-    // collection-time crash.
-    const quills = discoverQuills(sourceDir);
-    describe(`Quiver: ${basename(sourceDir)}`, () => {
+export function runQuiverTests(metaUrlOrDir, engine) {
+    describe("Quiver", () => {
         let registry;
-        beforeAll(async () => {
-            const quiver = await Quiver.fromSourceDir(sourceDir);
+        let quiver;
+        before(async () => {
+            quiver = await Quiver.fromDir(metaUrlOrDir);
             registry = new QuiverRegistry({ engine, quivers: [quiver] });
         });
         it("has at least one quill", () => {
-            expect(quills).not.toHaveLength(0);
+            if (quiver.quillNames().length === 0) {
+                throw new Error("Quiver has no quills");
+            }
+        });
+        it("compiles every quill version without error", async () => {
+            for (const name of quiver.quillNames()) {
+                for (const version of quiver.versionsOf(name)) {
+                    const quill = await registry.getQuill(`${name}@${version}`);
+                    if (typeof quill.render !== "function") {
+                        throw new Error(`${name}@${version}: engine returned non-conforming Quill`);
+                    }
+                }
+            }
         });
-        for (const { name, version } of quills) {
-            it(`${name}@${version} compiles without error`, async () => {
-                const quill = await registry.getQuill(`${name}@${version}`);
-                expect(typeof quill.render).toBe("function");
-            });
-        }
     });
 }

package/dist/transports/http-transport.d.ts

@@ -1,11 +1,11 @@
 /**
- * HttpTransport — browser-safe packed quiver transport that fetches via HTTP.
+ * HttpTransport — browser-safe built-quiver transport that fetches via HTTP.
  * Internal; not exported from index.ts.
  *
  * Uses globalThis.fetch — no node: imports at any level.
  */
-import type { PackedTransport } from "../packed-loader.js";
-export declare class HttpTransport implements PackedTransport {
+import type { BuiltTransport } from "../built-loader.js";
+export declare class HttpTransport implements BuiltTransport {
     private readonly baseUrl;
     constructor(baseUrl: string);
     fetchBytes(relativePath: string): Promise<Uint8Array>;

package/dist/transports/http-transport.js

@@ -1,5 +1,5 @@
 /**
- * HttpTransport — browser-safe packed quiver transport that fetches via HTTP.
+ * HttpTransport — browser-safe built-quiver transport that fetches via HTTP.
  * Internal; not exported from index.ts.
  *
  * Uses globalThis.fetch — no node: imports at any level.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@quillmark/quiver",
-  "version": "0.2.0",
-  "description": "Quiver registry and packaging for Quillmark",
+  "version": "0.3.0",
+  "description": "Quiver registry and build tooling for Quillmark",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -42,20 +42,14 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@quillmark/wasm": ">=0.59.0-rc.2",
-    "vitest": ">=4.0.0"
-  },
-  "peerDependenciesMeta": {
-    "vitest": {
-      "optional": true
-    }
+    "@quillmark/wasm": ">=0.59.0"
   },
   "dependencies": {
     "fflate": "^0.8.2",
     "yaml": "^2.8.3"
   },
   "devDependencies": {
-    "@quillmark/wasm": "0.59.0-rc.2",
+    "@quillmark/wasm": "0.59.0",
     "@types/node": "^25.3.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"

package/dist/pack.d.ts

@@ -1,25 +0,0 @@
-/**
- * Pack 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.
- */
-/** Reserved for future pack options (e.g. compression level, filters). */
-export type PackOptions = Record<string, never>;
-/**
- * Reads a Source Quiver, validates it, and writes a Packed Quiver 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 packQuiver(sourceDir: string, outDir: string, _opts?: PackOptions): Promise<void>;

package/dist/transports/fs-transport.d.ts

@@ -1,14 +0,0 @@
-/**
- * FsTransport — Node-only packed quiver transport that reads from local disk.
- * Internal; not exported from index.ts.
- *
- * Uses dynamic imports of node:fs/promises and node:path so the module can be
- * imported in environments where those builtins are not available (the dynamic
- * import only executes when fetchBytes is actually called).
- */
-import type { PackedTransport } from "../packed-loader.js";
-export declare class FsTransport implements PackedTransport {
-    private rootDir;
-    constructor(rootDir: string);
-    fetchBytes(relativePath: string): Promise<Uint8Array>;
-}

package/dist/transports/fs-transport.js

@@ -1,33 +0,0 @@
-/**
- * FsTransport — Node-only packed quiver transport that reads from local disk.
- * Internal; not exported from index.ts.
- *
- * Uses dynamic imports of node:fs/promises and node:path so the module can be
- * imported in environments where those builtins are not available (the dynamic
- * import only executes when fetchBytes is actually called).
- */
-import { QuiverError } from "../errors.js";
-export class FsTransport {
-    rootDir;
-    constructor(rootDir) {
-        this.rootDir = rootDir;
-    }
-    async fetchBytes(relativePath) {
-        const { join, resolve } = await import("node:path");
-        const { readFile } = await import("node:fs/promises");
-        const rootResolved = resolve(this.rootDir);
-        const fullPath = resolve(join(this.rootDir, relativePath));
-        // Defense-in-depth: ensure resolved path stays within rootDir.
-        if (!fullPath.startsWith(rootResolved + "/") && fullPath !== rootResolved) {
-            throw new QuiverError("transport_error", `Path traversal detected: "${relativePath}" escapes quiver root`);
-        }
-        try {
-            const buf = await readFile(fullPath);
-            // Ensure we return a plain Uint8Array, not a Node.js Buffer subclass.
-            return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
-        }
-        catch (err) {
-            throw new QuiverError("transport_error", `Failed to read "${relativePath}" from packed quiver at "${this.rootDir}": ${err.message}`, { cause: err });
-        }
-    }
-}