@quillmark/quiver 0.1.1 → 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/assert-node.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Throws a `transport_error` when called outside a Node.js environment.
+ * Call at the top of each Node-only static factory to fail fast in browsers.
+ */
+export declare function assertNode(method: string): void;

package/dist/assert-node.js

@@ -0,0 +1,12 @@
+import { QuiverError } from "./errors.js";
+/**
+ * Throws a `transport_error` when called outside a Node.js environment.
+ * Call at the top of each Node-only static factory to fail fast in browsers.
+ */
+export function assertNode(method) {
+    if (typeof globalThis.process === "undefined" ||
+        !globalThis.process
+            ?.versions?.node) {
+        throw new QuiverError("transport_error", `${method} is only available in Node.js`);
+    }
+}

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/build.js

@@ -0,0 +1,120 @@
+/**
+ * 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.
+ */
+import { QuiverError } from "./errors.js";
+import { packFiles } from "./bundle.js";
+/** 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 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 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");
+    const { createHash } = await import("node:crypto");
+    const { scanSourceQuiver, readQuillTree } = await import("./source-loader.js");
+    // 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 });
+    }
+    catch (err) {
+        throw new QuiverError("transport_error", `Failed to prepare output directory "${outDir}": ${err.message}`, { cause: err });
+    }
+    // 3. Process each quill version.
+    const manifestQuills = [];
+    for (const [quillName, versions] of catalog) {
+        for (const version of versions) {
+            const quillDir = join(sourceDir, "quills", quillName, version);
+            // a. Read quill file tree.
+            const tree = await readQuillTree(quillDir);
+            // b. Partition fonts vs content.
+            const fontEntries = [];
+            const contentEntries = [];
+            for (const [path, bytes] of tree) {
+                if (FONT_EXT.test(path)) {
+                    fontEntries.push([path, bytes]);
+                }
+                else {
+                    contentEntries.push([path, bytes]);
+                }
+            }
+            // 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);
+                try {
+                    await writeFile(storePath, bytes);
+                }
+                catch (err) {
+                    throw new QuiverError("transport_error", `Failed to write font store entry "${storePath}": ${err.message}`, { cause: err });
+                }
+                fonts[path] = hash;
+            }
+            // d. Zip content files (deterministic: sorted paths, fixed mtime).
+            const contentRecord = {};
+            for (const [path, bytes] of contentEntries) {
+                contentRecord[path] = bytes;
+            }
+            const zipBytes = packFiles(contentRecord);
+            // e–f. Compute bundle hash and name.
+            const bundleHash = createHash("md5").update(zipBytes).digest("hex").slice(0, 6);
+            const bundleName = `${quillName}@${version}.${bundleHash}.zip`;
+            // g. Write bundle zip.
+            const bundlePath = join(outDir, bundleName);
+            try {
+                await writeFile(bundlePath, zipBytes);
+            }
+            catch (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 });
+        }
+    }
+    // 4–8. Build and write hashed manifest.
+    const manifest = {
+        version: 1,
+        name: meta.name,
+        quills: manifestQuills,
+    };
+    const manifestJson = JSON.stringify(manifest, null, 2);
+    const manifestHash = createHash("md5").update(manifestJson).digest("hex").slice(0, 6);
+    const manifestFileName = `manifest.${manifestHash}.json`;
+    const manifestPath = join(outDir, manifestFileName);
+    try {
+        await writeFile(manifestPath, manifestJson, "utf-8");
+    }
+    catch (err) {
+        throw new QuiverError("transport_error", `Failed to write manifest "${manifestPath}": ${err.message}`, { cause: err });
+    }
+    // 9–10. Write stable pointer Quiver.json.
+    const pointer = { manifest: manifestFileName };
+    const pointerPath = join(outDir, "Quiver.json");
+    try {
+        await writeFile(pointerPath, JSON.stringify(pointer), "utf-8");
+    }
+    catch (err) {
+        throw new QuiverError("transport_error", `Failed to write pointer "${pointerPath}": ${err.message}`, { cause: err });
+    }
+}