@quillmark/quiver 0.8.0 → 0.9.0

package/README.md

@@ -44,17 +44,16 @@ 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, drop an `example.md` next to a
-quill's template (`quills/<name>/<x.y.z>/example.md`) and run the
+human can look at. To eyeball real renders, run the
 `@quillmark/quiver/preview` helper:
 
 ```ts
@@ -69,12 +68,12 @@ await renderQuiverSamples(import.meta.url, {
 // → 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.
+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):

package/dist/engine-types.d.ts

@@ -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/preview.d.ts

@@ -3,9 +3,9 @@
  *
  * `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.
+ * 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.
  *
@@ -20,9 +20,9 @@
  *   });
  *   // → 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.
+ * 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.
@@ -61,8 +61,8 @@ export interface RenderQuiverSamplesOptions {
 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";
+    /** `rendered` — artifacts written; `failed` — error. */
+    status: "rendered" | "failed";
     /** Artifact filenames written under `outDir` (relative). */
     files: string[];
     /** Render warnings, formatted `"severity: message"`. */
@@ -74,7 +74,7 @@ export interface RenderedSample {
     reasons: string[];
 }
 /**
- * Renders every quill's `example.md` and writes the artifacts plus an
+ * 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

package/dist/preview.js

@@ -3,9 +3,9 @@
  *
  * `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.
+ * 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.
  *
@@ -20,9 +20,9 @@
  *   });
  *   // → 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.
+ * 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.
@@ -30,12 +30,10 @@
 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
+ * 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
@@ -86,21 +84,10 @@ function failureReasons(err) {
 }
 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 markdown = quill.blueprint;
         const doc = opts.Document.fromMarkdown(markdown);
         result = quill.render(doc, opts.format ? { format: opts.format } : undefined);
     }
@@ -145,8 +132,7 @@ function printSummary(quiverName, outDir, results) {
         for (const w of r.warnings)
             console.log(`             ⚠ ${w}`);
     }
-    console.log(`\n${count("rendered")} rendered, ${count("skipped")} skipped, ` +
-        `${count("failed")} failed`);
+    console.log(`\n${count("rendered")} rendered, ${count("failed")} failed`);
     console.log(`Open ${join(outDir, "index.html")} to review.\n`);
 }
 function escapeHtml(text) {
@@ -198,7 +184,6 @@ function renderIndexHtml(quiverName, results) {
   .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; }

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,6 +1,6 @@
 {
   "name": "@quillmark/quiver",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Quiver registry and build tooling for Quillmark",
   "type": "module",
   "license": "MIT",