@quillmark/quiver 0.6.0 → 0.8.0

package/PROGRAM.md

@@ -465,7 +465,7 @@ const result = quill.render(doc, { format: "pdf" });
   test runners wire their own loops against the main API.
 
 **Dependencies:**
-- Peer: `@quillmark/wasm@>=0.59.0` with `Quillmark`, `Document.fromMarkdown`, `engine.quill(tree)`, and `quill.render(doc, opts?)` APIs.
+- Peer: `@quillmark/wasm@>=0.71.0` 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 `build()` — never reached at runtime)
 - No test-runner peer dependency; `/testing` uses `node:test` (built-in)

package/README.md

@@ -50,6 +50,48 @@ surface on publish, not on the consumer's build. The harness uses
 required. If you prefer vitest/jest/mocha, write a 12-line loop against
 the main API instead.
 
+## Manual validation (rendering samples)
+
+The CI harness proves every quill _compiles_; it does not produce output a
+human can look at. To eyeball real renders, drop an `example.md` next to a
+quill's template (`quills/<name>/<x.y.z>/example.md`) and run the
+`@quillmark/quiver/preview` helper:
+
+```ts
+// scripts/preview.ts — run with: node --experimental-strip-types scripts/preview.ts
+import { Quillmark, Document } from "@quillmark/wasm";
+import { renderQuiverSamples } from "@quillmark/quiver/preview";
+
+await renderQuiverSamples(import.meta.url, {
+  engine: new Quillmark(),
+  Document,
+});
+// → writes ./preview/<name>@<version>.<fmt> + index.html
+```
+
+It renders every quill's `example.md`, writes the artifacts to `outDir`
+(default `preview/`), and emits an `index.html` gallery. A `.gitignore` is
+written into `outDir` so the generated artifacts are never accidentally
+committed. Quills without an `example.md` are skipped; a quill that throws
+is recorded as failed — with every diagnostic, not just the first —
+without aborting the run, so one broken quill never hides the rest.
+
+To iterate on a subset, pass `include` / `exclude` (each entry matches a
+quill name or canonical ref):
+
+```ts
+await renderQuiverSamples(import.meta.url, {
+  engine: new Quillmark(),
+  Document,
+  exclude: ["broken-quill"], // or: include: ["memo@1.0.0"]
+});
+```
+
+> **Linking the source repo?** `@quillmark/quiver/preview` resolves to
+> `./dist/preview.js`, which only exists after `npm install && npm run build`
+> in the `@quillmark/quiver` checkout. If you `npm link` it and see
+> `Cannot find module './dist/preview.js'`, build the linked package first.
+
 ## Consuming a quiver (Node)
 
 ```ts

package/dist/engine-types.d.ts

@@ -1,5 +1,5 @@
 /**
- * Minimal structural types matching @quillmark/wasm >=0.59.0.
+ * Minimal structural types matching @quillmark/wasm >=0.79.0.
  *
  * Shape:
  *   class Quillmark { quill(tree: Map<string, Uint8Array>): Quill }

package/dist/engine-types.js

@@ -1,5 +1,5 @@
 /**
- * Minimal structural types matching @quillmark/wasm >=0.59.0.
+ * Minimal structural types matching @quillmark/wasm >=0.79.0.
  *
  * Shape:
  *   class Quillmark { quill(tree: Map<string, Uint8Array>): Quill }

package/dist/node.d.ts

@@ -4,7 +4,7 @@
  * Importing this module is the consumer's explicit declaration of intent:
  * "I am running in Node and want the Node-only Quiver factories." It exposes
  * the same `Quiver` class as the main entry, augmented with `fromDir`,
- * `fromPackage`, `fromBuiltDir`, and `build` static methods.
+ * `fromPackage`, `fromBuiltDir`, `build`, and `buildPackage` static methods.
  *
  * Side effect: at module evaluation time, the Node-only static methods are
  * installed on the shared `Quiver` constructor. Any other module that already
@@ -63,6 +63,16 @@ type NodeQuiverStatics = {
      * on I/O failures.
      */
     build(sourceDir: string, outDir: string, opts?: BuildOptions): Promise<void>;
+    /**
+     * Resolves an npm specifier against `node_modules` and builds the source
+     * layout at the package root. The resolved package must have `Quiver.yaml`
+     * at its root. Symmetric to `fromPackage` but writes a runtime build
+     * artifact to outDir instead of loading.
+     *
+     * Throws `transport_error` on resolution/I/O failure, `quiver_invalid` on
+     * source validation failures.
+     */
+    buildPackage(specifier: string, outDir: string, opts?: BuildOptions): Promise<void>;
 };
 export type Quiver = Base;
 export declare const Quiver: typeof Base & NodeQuiverStatics;

package/dist/node.js

@@ -4,7 +4,7 @@
  * Importing this module is the consumer's explicit declaration of intent:
  * "I am running in Node and want the Node-only Quiver factories." It exposes
  * the same `Quiver` class as the main entry, augmented with `fromDir`,
- * `fromPackage`, `fromBuiltDir`, and `build` static methods.
+ * `fromPackage`, `fromBuiltDir`, `build`, and `buildPackage` static methods.
  *
  * Side effect: at module evaluation time, the Node-only static methods are
  * installed on the shared `Quiver` constructor. Any other module that already
@@ -55,6 +55,17 @@ Quiver.fromPackage = async function fromPackage(specifier) {
 Quiver.build = async function build(sourceDir, outDir, opts) {
     return buildQuiver(sourceDir, outDir, opts);
 };
+Quiver.buildPackage = async function buildPackage(specifier, outDir, opts) {
+    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 buildQuiver(dirname(yamlPath), outDir, opts);
+};
 // ---------------------------------------------------------------------------
 // 3. Re-export the rest of the public surface so consumers get one import.
 // ---------------------------------------------------------------------------

package/dist/preview.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Manual-validation helper for Quiver authors.
+ *
+ * `runQuiverTests` (`@quillmark/quiver/testing`) proves every quill *compiles*
+ * — it never produces a rendered artifact a human can look at. This module
+ * closes that gap: it renders each quill's bundled `example.md`, writes the
+ * artifacts to a directory, and emits an `index.html` gallery so an author
+ * can eyeball real output before publishing.
+ *
+ * Node-only: writes files and loads a source quiver from disk.
+ *
+ * Usage (place a script next to your Quiver.yaml):
+ *
+ *   import { Quillmark, Document } from "@quillmark/wasm";
+ *   import { renderQuiverSamples } from "@quillmark/quiver/preview";
+ *
+ *   await renderQuiverSamples(import.meta.url, {
+ *     engine: new Quillmark(),
+ *     Document,
+ *   });
+ *   // → open ./preview/index.html
+ *
+ * The example document is the `example.md` file inside each quill version
+ * directory (`quills/<name>/<version>/example.md`). Quills without one are
+ * skipped, not failed.
+ *
+ * A `.gitignore` is written into `outDir` so the generated artifacts are not
+ * accidentally committed.
+ */
+import type { QuillmarkLike } from "./engine-types.js";
+/**
+ * Structural shape of the `Document` class from `@quillmark/wasm`. Only the
+ * `fromMarkdown` factory is used; passing the real class satisfies this.
+ */
+export interface DocumentFactoryLike {
+    fromMarkdown(markdown: string): unknown;
+}
+export interface RenderQuiverSamplesOptions {
+    /** Quillmark engine instance (`new Quillmark()` from `@quillmark/wasm`). */
+    engine: QuillmarkLike;
+    /** The `Document` class from `@quillmark/wasm`. */
+    Document: DocumentFactoryLike;
+    /** Directory to write rendered artifacts into. Default: `preview`. */
+    outDir?: string;
+    /** Force an output format (`pdf`/`svg`/`png`/`txt`). Default: engine's choice. */
+    format?: string;
+    /** Suppress the console summary. Default: false. */
+    quiet?: boolean;
+    /**
+     * Render only these quills. Each entry matches a quill name (`"memo"`) or a
+     * canonical ref (`"memo@1.0.0"`). Omit to render all quills.
+     */
+    include?: string[];
+    /**
+     * Skip these quills. Each entry matches a quill name (`"memo"`) or a
+     * canonical ref (`"memo@1.0.0"`). Applied after `include`.
+     */
+    exclude?: string[];
+}
+/** Per-quill outcome returned by `renderQuiverSamples`. */
+export interface RenderedSample {
+    /** Canonical ref, e.g. `"memo@1.0.0"`. */
+    ref: string;
+    /** `rendered` — artifacts written; `skipped` — no example; `failed` — error. */
+    status: "rendered" | "skipped" | "failed";
+    /** Artifact filenames written under `outDir` (relative). */
+    files: string[];
+    /** Render warnings, formatted `"severity: message"`. */
+    warnings: string[];
+    /**
+     * Why the quill was skipped or failed. Empty when rendered. A failed render
+     * carries every diagnostic from the engine, not just the first.
+     */
+    reasons: string[];
+}
+/**
+ * Renders every quill's `example.md` and writes the artifacts plus an
+ * `index.html` gallery to `outDir`.
+ *
+ * Does NOT fail fast: a quill that throws is recorded as `failed` and the
+ * run continues, so one broken quill never hides the others. Inspect the
+ * returned array (or `index.html`) for the full picture.
+ *
+ * @param metaUrlOrDir `import.meta.url` when called from the quiver root, or
+ *   an absolute path to the source quiver directory.
+ */
+export declare function renderQuiverSamples(metaUrlOrDir: string, opts: RenderQuiverSamplesOptions): Promise<RenderedSample[]>;

package/dist/preview.js

@@ -0,0 +1,218 @@
+/**
+ * Manual-validation helper for Quiver authors.
+ *
+ * `runQuiverTests` (`@quillmark/quiver/testing`) proves every quill *compiles*
+ * — it never produces a rendered artifact a human can look at. This module
+ * closes that gap: it renders each quill's bundled `example.md`, writes the
+ * artifacts to a directory, and emits an `index.html` gallery so an author
+ * can eyeball real output before publishing.
+ *
+ * Node-only: writes files and loads a source quiver from disk.
+ *
+ * Usage (place a script next to your Quiver.yaml):
+ *
+ *   import { Quillmark, Document } from "@quillmark/wasm";
+ *   import { renderQuiverSamples } from "@quillmark/quiver/preview";
+ *
+ *   await renderQuiverSamples(import.meta.url, {
+ *     engine: new Quillmark(),
+ *     Document,
+ *   });
+ *   // → open ./preview/index.html
+ *
+ * The example document is the `example.md` file inside each quill version
+ * directory (`quills/<name>/<version>/example.md`). Quills without one are
+ * skipped, not failed.
+ *
+ * A `.gitignore` is written into `outDir` so the generated artifacts are not
+ * accidentally committed.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Quiver } from "./node.js";
+/** The `example.md` filename looked up inside each quill version directory. */
+const EXAMPLE_FILE = "example.md";
+/** Default directory rendered artifacts are written to. */
+const DEFAULT_OUT_DIR = "preview";
+/**
+ * Renders every quill's `example.md` and writes the artifacts plus an
+ * `index.html` gallery to `outDir`.
+ *
+ * Does NOT fail fast: a quill that throws is recorded as `failed` and the
+ * run continues, so one broken quill never hides the others. Inspect the
+ * returned array (or `index.html`) for the full picture.
+ *
+ * @param metaUrlOrDir `import.meta.url` when called from the quiver root, or
+ *   an absolute path to the source quiver directory.
+ */
+export async function renderQuiverSamples(metaUrlOrDir, opts) {
+    const outDir = opts.outDir ?? DEFAULT_OUT_DIR;
+    const quiver = await Quiver.fromDir(metaUrlOrDir);
+    await mkdir(outDir, { recursive: true });
+    const results = [];
+    for (const name of quiver.quillNames()) {
+        for (const version of quiver.versionsOf(name)) {
+            if (!isSelected(name, `${name}@${version}`, opts))
+                continue;
+            results.push(await renderOne(quiver, name, version, outDir, opts));
+        }
+    }
+    await writeFile(join(outDir, ".gitignore"), "*\n");
+    await writeFile(join(outDir, "index.html"), renderIndexHtml(quiver.name, results));
+    if (!opts.quiet)
+        printSummary(quiver.name, outDir, results);
+    return results;
+}
+/** Whether a quill passes the `include`/`exclude` filters. */
+function isSelected(name, ref, opts) {
+    const matches = (list) => list.includes(name) || list.includes(ref);
+    if (opts.include && !matches(opts.include))
+        return false;
+    if (opts.exclude && matches(opts.exclude))
+        return false;
+    return true;
+}
+/**
+ * Formats a thrown render error into one string per diagnostic. `@quillmark/wasm`
+ * attaches a `diagnostics` array to its errors; fall back to the message when
+ * an error carries none.
+ */
+function failureReasons(err) {
+    const diagnostics = err.diagnostics;
+    if (Array.isArray(diagnostics) && diagnostics.length > 0) {
+        return diagnostics.map((d) => `${d.severity}: ${d.message}`);
+    }
+    return [err.message];
+}
+async function renderOne(quiver, name, version, outDir, opts) {
+    const ref = `${name}@${version}`;
+    const tree = await quiver.loadTree(name, version);
+    const exampleBytes = tree.get(EXAMPLE_FILE);
+    if (exampleBytes === undefined) {
+        return {
+            ref,
+            status: "skipped",
+            files: [],
+            warnings: [],
+            reasons: [`no ${EXAMPLE_FILE} in quill directory`],
+        };
+    }
+    let result;
+    try {
+        const quill = await quiver.getQuill(ref, { engine: opts.engine });
+        const markdown = new TextDecoder().decode(exampleBytes);
+        const doc = opts.Document.fromMarkdown(markdown);
+        result = quill.render(doc, opts.format ? { format: opts.format } : undefined);
+    }
+    catch (err) {
+        return {
+            ref,
+            status: "failed",
+            files: [],
+            warnings: [],
+            reasons: failureReasons(err),
+        };
+    }
+    const warnings = (result.warnings ?? []).map((w) => `${w.severity}: ${w.message}`);
+    const artifacts = result.artifacts ?? [];
+    if (artifacts.length === 0) {
+        return {
+            ref,
+            status: "failed",
+            files: [],
+            warnings,
+            reasons: ["render produced no artifacts"],
+        };
+    }
+    const files = [];
+    for (let i = 0; i < artifacts.length; i++) {
+        const artifact = artifacts[i];
+        const suffix = artifacts.length > 1 ? `.${i}` : "";
+        const fileName = `${ref}${suffix}.${artifact.format}`;
+        await writeFile(join(outDir, fileName), artifact.bytes);
+        files.push(fileName);
+    }
+    return { ref, status: "rendered", files, warnings, reasons: [] };
+}
+function printSummary(quiverName, outDir, results) {
+    const count = (s) => results.filter((r) => r.status === s).length;
+    console.log(`\nQuiver "${quiverName}" — sample render`);
+    for (const r of results) {
+        const detail = r.status === "rendered" ? r.files.join(", ") : (r.reasons[0] ?? "");
+        console.log(`  [${r.status.padEnd(8)}] ${r.ref}${detail ? ` — ${detail}` : ""}`);
+        for (const extra of r.reasons.slice(1))
+            console.log(`             ${extra}`);
+        for (const w of r.warnings)
+            console.log(`             ⚠ ${w}`);
+    }
+    console.log(`\n${count("rendered")} rendered, ${count("skipped")} skipped, ` +
+        `${count("failed")} failed`);
+    console.log(`Open ${join(outDir, "index.html")} to review.\n`);
+}
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function embedArtifact(fileName) {
+    const ext = fileName.slice(fileName.lastIndexOf(".") + 1).toLowerCase();
+    const src = escapeHtml(fileName);
+    if (ext === "pdf") {
+        return `<iframe class="art" src="${src}" title="${src}"></iframe>`;
+    }
+    if (ext === "png" || ext === "svg") {
+        return `<img class="art" src="${src}" alt="${src}" />`;
+    }
+    return `<a href="${src}">${src}</a>`;
+}
+function renderIndexHtml(quiverName, results) {
+    const cards = results
+        .map((r) => {
+        const body = r.status === "rendered"
+            ? r.files.map(embedArtifact).join("\n")
+            : `<ul class="reasons">${r.reasons
+                .map((reason) => `<li>${escapeHtml(reason)}</li>`)
+                .join("")}</ul>`;
+        const warnings = r.warnings.length
+            ? `<ul class="warnings">${r.warnings
+                .map((w) => `<li>${escapeHtml(w)}</li>`)
+                .join("")}</ul>`
+            : "";
+        return `<section class="card ${r.status}">
+  <h2>${escapeHtml(r.ref)} <span class="badge">${r.status}</span></h2>
+  ${warnings}
+  ${body}
+</section>`;
+    })
+        .join("\n");
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>Quiver preview — ${escapeHtml(quiverName)}</title>
+<style>
+  body { font-family: system-ui, sans-serif; margin: 2rem; background: #fafafa; }
+  h1 { font-size: 1.4rem; }
+  .card { background: #fff; border: 1px solid #ddd; border-radius: 8px;
+          padding: 1rem; margin: 1rem 0; }
+  .card.failed { border-color: #e0b4b4; }
+  .card.skipped { opacity: 0.7; }
+  h2 { font-size: 1rem; margin: 0 0 0.5rem; }
+  .badge { font-size: 0.7rem; text-transform: uppercase; background: #eee;
+           border-radius: 4px; padding: 2px 6px; vertical-align: middle; }
+  .failed .badge { background: #f3d2d2; }
+  .art { width: 100%; height: 600px; border: 1px solid #eee; }
+  img.art { height: auto; }
+  .reasons { color: #a33; font-style: italic; }
+  .warnings { color: #96690a; font-size: 0.85rem; }
+</style>
+</head>
+<body>
+<h1>Quiver preview — ${escapeHtml(quiverName)}</h1>
+${cards}
+</body>
+</html>
+`;
+}

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@quillmark/quiver",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Quiver registry and build tooling for Quillmark",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/nibsbin/quillmark-quiver.git"
+    "url": "git+https://github.com/quillmark-org/quiver.git"
   },
   "bugs": {
-    "url": "https://github.com/nibsbin/quillmark-quiver/issues"
+    "url": "https://github.com/quillmark-org/quiver/issues"
   },
-  "homepage": "https://github.com/nibsbin/quillmark-quiver#readme",
+  "homepage": "https://github.com/quillmark-org/quiver#readme",
   "keywords": [
     "quillmark",
     "quiver",
@@ -20,7 +20,7 @@
   ],
   "author": "Quillmark Contributors",
   "engines": {
-    "node": ">=18"
+    "node": ">=24"
   },
   "exports": {
     ".": {
@@ -34,11 +34,16 @@
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"
+    },
+    "./preview": {
+      "types": "./dist/preview.d.ts",
+      "import": "./dist/preview.js"
     }
   },
   "sideEffects": [
     "./dist/node.js",
-    "./dist/testing.js"
+    "./dist/testing.js",
+    "./dist/preview.js"
   ],
   "files": [
     "dist",
@@ -46,14 +51,14 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@quillmark/wasm": ">=0.59.0"
+    "@quillmark/wasm": ">=0.79.0"
   },
   "dependencies": {
     "fflate": "^0.8.2",
     "yaml": "^2.8.3"
   },
   "devDependencies": {
-    "@quillmark/wasm": "0.59.0",
+    "@quillmark/wasm": "^0.79.0",
     "@types/node": "^25.3.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"