@quillmark/quiver 0.7.0 → 0.9.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

@@ -44,11 +44,52 @@ my-quiver/
 ```
 
 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.
+loads with `Quiver.fromDir`, compiles every quill, and renders each quill's
+blueprint 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.
+
+## 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, 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 auto-generated blueprint (`quill.blueprint`), 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. 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)
 

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 }
@@ -23,4 +23,6 @@ export interface QuillmarkLike {
 export interface QuillLike {
     render(doc: unknown, opts?: unknown): unknown;
     open?: (doc: unknown) => unknown;
+    /** Auto-generated annotated Markdown blueprint — always present in @quillmark/wasm >=0.79.0. */
+    blueprint: string;
 }

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/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 blueprint, 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 sample document is the auto-generated blueprint (`quill.blueprint`) for
+ * each quill version. Every quill always has a blueprint, so no quills are
+ * skipped for lack of a sample document.
+ *
+ * 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; `failed` — error. */
+    status: "rendered" | "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 blueprint 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,203 @@
+/**
+ * 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 blueprint, 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 sample document is the auto-generated blueprint (`quill.blueprint`) for
+ * each quill version. Every quill always has a blueprint, so no quills are
+ * skipped for lack of a sample document.
+ *
+ * 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";
+/** Default directory rendered artifacts are written to. */
+const DEFAULT_OUT_DIR = "preview";
+/**
+ * Renders every quill's blueprint 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}`;
+    let result;
+    try {
+        const quill = await quiver.getQuill(ref, { engine: opts.engine });
+        const markdown = quill.blueprint;
+        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("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; }
+  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/dist/testing.d.ts

@@ -7,14 +7,15 @@
  *
  * Usage (place this file next to your Quiver.yaml):
  *
- *   import { Quillmark } from "@quillmark/wasm";
+ *   import { Quillmark, Document } from "@quillmark/wasm";
  *   import { runQuiverTests } from "@quillmark/quiver/testing";
  *   const engine = new Quillmark();
- *   runQuiverTests(import.meta.url, engine);
+ *   runQuiverTests(import.meta.url, engine, Document);
  *
  * Run with `node --test`.
  */
 import type { QuillmarkLike } from "./engine-types.js";
+import type { DocumentFactoryLike } from "./preview.js";
 /**
  * Registers a `node:test` describe block that validates every quill
  * version in the quiver at `metaUrlOrDir` against the provided engine.
@@ -23,6 +24,7 @@ import type { QuillmarkLike } from "./engine-types.js";
  * 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).
+ * all template files, engine compilation via engine.quill(tree), and a
+ * full render of each quill's blueprint document.
  */
-export declare function runQuiverTests(metaUrlOrDir: string, engine: QuillmarkLike): void;
+export declare function runQuiverTests(metaUrlOrDir: string, engine: QuillmarkLike, Document: DocumentFactoryLike): void;

package/dist/testing.js

@@ -7,10 +7,10 @@
  *
  * Usage (place this file next to your Quiver.yaml):
  *
- *   import { Quillmark } from "@quillmark/wasm";
+ *   import { Quillmark, Document } from "@quillmark/wasm";
  *   import { runQuiverTests } from "@quillmark/quiver/testing";
  *   const engine = new Quillmark();
- *   runQuiverTests(import.meta.url, engine);
+ *   runQuiverTests(import.meta.url, engine, Document);
  *
  * Run with `node --test`.
  */
@@ -27,9 +27,10 @@ import { Quiver } from "./node.js";
  * 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).
+ * all template files, engine compilation via engine.quill(tree), and a
+ * full render of each quill's blueprint document.
  */
-export function runQuiverTests(metaUrlOrDir, engine) {
+export function runQuiverTests(metaUrlOrDir, engine, Document) {
     describe("Quiver", () => {
         let quiver;
         before(async () => {
@@ -40,12 +41,15 @@ export function runQuiverTests(metaUrlOrDir, engine) {
                 throw new Error("Quiver has no quills");
             }
         });
-        it("compiles every quill version without error", async () => {
+        it("compiles and renders every quill's blueprint without error", async () => {
             for (const name of quiver.quillNames()) {
                 for (const version of quiver.versionsOf(name)) {
-                    const quill = await quiver.getQuill(`${name}@${version}`, { engine });
-                    if (typeof quill.render !== "function") {
-                        throw new Error(`${name}@${version}: engine returned non-conforming Quill`);
+                    const ref = `${name}@${version}`;
+                    const quill = await quiver.getQuill(ref, { engine });
+                    const doc = Document.fromMarkdown(quill.blueprint);
+                    const result = quill.render(doc);
+                    if (!Array.isArray(result.artifacts) || result.artifacts.length === 0) {
+                        throw new Error(`${ref}: blueprint render produced no artifacts`);
                     }
                 }
             }

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@quillmark/quiver",
-  "version": "0.7.0",
+  "version": "0.9.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"