@quillmark/quiver 0.11.0 → 0.12.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.71.0` with `Quillmark`, `Document.fromMarkdown`, `engine.quill(tree)`, and `quill.render(doc, opts?)` APIs.
+- Peer: `@quillmark/wasm@>=0.86.0` with `Quillmark`, `Document.fromMarkdown`, `engine.quill(tree)`, `quill.render(doc, opts?)`, and `quill.example` (renderable sample document) 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

@@ -45,8 +45,8 @@ my-quiver/
 
 Recommended CI: use the bundled `@quillmark/quiver/testing` harness — it
 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
+example document 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.
 
@@ -68,8 +68,10 @@ await renderQuiverSamples(import.meta.url, {
 // → 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`
+It renders every quill's illustrative example document (`quill.example` — a
+fully filled-out, always-renderable sample; the blueprint itself carries
+`<must-fill>` sentinels and is not directly renderable), 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

package/dist/bin/quiver.js

@@ -95,10 +95,10 @@ async function test() {
             const ref = `${name}@${version}`;
             try {
                 const quill = await quiver.getQuill(ref, { engine });
-                const doc = Document.fromMarkdown(quill.blueprint);
+                const doc = Document.fromMarkdown(quill.example);
                 const result = quill.render(doc);
                 if (!Array.isArray(result.artifacts) || result.artifacts.length === 0) {
-                    throw new Error("blueprint render produced no artifacts");
+                    throw new Error("example render produced no artifacts");
                 }
                 console.log(`pass  ${ref}`);
                 pass++;

package/dist/engine-types.d.ts

@@ -1,5 +1,5 @@
 /**
- * Minimal structural types matching @quillmark/wasm >=0.79.0.
+ * Minimal structural types matching @quillmark/wasm >=0.86.0.
  *
  * Shape:
  *   class Quillmark { quill(tree: Map<string, Uint8Array>): Quill }
@@ -23,6 +23,18 @@ 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. */
+    /**
+     * Auto-generated annotated Markdown blueprint for LLM/authoring consumers.
+     * Carries `<must-fill>` sentinels for Must Fill fields, so it is *not*
+     * directly renderable — render `example` instead.
+     */
     blueprint: string;
+    /**
+     * The illustrative "filled-out" reference document — always renderable.
+     * Each field resolves to its `example:`, else its `default:`, else a
+     * type-empty zero value, with no `<must-fill>` sentinels. Introduced in
+     * @quillmark/wasm >=0.86.0. Used by Quiver's preview/testing helpers to
+     * render a sample artifact for each quill.
+     */
+    example: string;
 }

package/dist/engine-types.js

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

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 blueprint, 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 example document, 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,11 @@
  *   });
  *   // → 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.
+ * The sample document is the illustrative example (`quill.example`) for each
+ * quill version — a fully filled-out, always-renderable document (the
+ * blueprint itself carries `<must-fill>` sentinels and is not renderable).
+ * Every quill always has an example, 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.
@@ -74,7 +76,7 @@ export interface RenderedSample {
     reasons: string[];
 }
 /**
- * Renders every quill's blueprint and writes the artifacts plus an
+ * Renders every quill's example document 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 blueprint, 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 example document, 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,11 @@
  *   });
  *   // → 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.
+ * The sample document is the illustrative example (`quill.example`) for each
+ * quill version — a fully filled-out, always-renderable document (the
+ * blueprint itself carries `<must-fill>` sentinels and is not renderable).
+ * Every quill always has an example, 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.
@@ -33,7 +35,7 @@ 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
+ * Renders every quill's example document 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
@@ -87,7 +89,7 @@ async function renderOne(quiver, name, version, outDir, opts) {
     let result;
     try {
         const quill = await quiver.getQuill(ref, { engine: opts.engine });
-        const markdown = quill.blueprint;
+        const markdown = quill.example;
         const doc = opts.Document.fromMarkdown(markdown);
         result = quill.render(doc, opts.format ? { format: opts.format } : undefined);
     }

package/dist/testing.d.ts

@@ -25,6 +25,6 @@ import type { DocumentFactoryLike } from "./preview.js";
  *
  * Validation covers the full loading pipeline: Quiver.yaml, Quill.yaml,
  * all template files, engine compilation via engine.quill(tree), and a
- * full render of each quill's blueprint document.
+ * full render of each quill's example document.
  */
 export declare function runQuiverTests(metaUrlOrDir: string, engine: QuillmarkLike, Document: DocumentFactoryLike): void;

package/dist/testing.js

@@ -28,7 +28,7 @@ import { Quiver } from "./node.js";
  *
  * Validation covers the full loading pipeline: Quiver.yaml, Quill.yaml,
  * all template files, engine compilation via engine.quill(tree), and a
- * full render of each quill's blueprint document.
+ * full render of each quill's example document.
  */
 export function runQuiverTests(metaUrlOrDir, engine, Document) {
     describe("Quiver", () => {
@@ -41,15 +41,15 @@ export function runQuiverTests(metaUrlOrDir, engine, Document) {
                 throw new Error("Quiver has no quills");
             }
         });
-        it("compiles and renders every quill's blueprint without error", async () => {
+        it("compiles and renders every quill's example without error", async () => {
             for (const name of quiver.quillNames()) {
                 for (const version of quiver.versionsOf(name)) {
                     const ref = `${name}@${version}`;
                     const quill = await quiver.getQuill(ref, { engine });
-                    const doc = Document.fromMarkdown(quill.blueprint);
+                    const doc = Document.fromMarkdown(quill.example);
                     const result = quill.render(doc);
                     if (!Array.isArray(result.artifacts) || result.artifacts.length === 0) {
-                        throw new Error(`${ref}: blueprint render produced no artifacts`);
+                        throw new Error(`${ref}: example render produced no artifacts`);
                     }
                 }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/quiver",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Quiver registry and build tooling for Quillmark",
   "type": "module",
   "license": "MIT",
@@ -51,14 +51,14 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@quillmark/wasm": ">=0.80.0"
+    "@quillmark/wasm": ">=0.86.0"
   },
   "dependencies": {
     "fflate": "^0.8.2",
     "yaml": "^2.8.3"
   },
   "devDependencies": {
-    "@quillmark/wasm": "^0.80.0",
+    "@quillmark/wasm": "^0.86.0",
     "@types/node": "^25.3.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"