@quillmark/quiver 0.15.0 → 0.17.0

package/dist/semver.js

@@ -2,17 +2,16 @@
 export function isCanonicalSemver(version) {
     return /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(version);
 }
-/** Returns true if `version` (canonical) matches `selector` (partial). */
+/**
+ * Returns true if `version` (canonical) matches `selector` (partial: `x`,
+ * `x.y`, or `x.y.z`). `parseQuillRef` owns selector validation; this is a
+ * prefix comparison over an already-valid selector.
+ */
 export function matchesSemverSelector(version, selector) {
     if (selector === version)
         return true;
-    const selectorParts = selector.split(".");
-    const versionParts = version.split(".");
-    if (selectorParts.length === 0 ||
-        selectorParts.length > 3 ||
-        selectorParts.some((p) => p.length === 0 || Number.isNaN(Number(p)))) {
-        return false;
-    }
+    const selectorParts = selector.split('.');
+    const versionParts = version.split('.');
     if (selectorParts.length > versionParts.length)
         return false;
     for (let i = 0; i < selectorParts.length; i++) {
@@ -23,8 +22,8 @@ export function matchesSemverSelector(version, selector) {
 }
 /** Compares two canonical semver strings. Returns <0, 0, or >0. */
 export function compareSemver(a, b) {
-    const partsA = a.split(".").map(Number);
-    const partsB = b.split(".").map(Number);
+    const partsA = a.split('.').map(Number);
+    const partsB = b.split('.').map(Number);
     const len = Math.max(partsA.length, partsB.length);
     for (let i = 0; i < len; i++) {
         const numA = partsA[i] ?? 0;

package/dist/source-loader.d.ts

@@ -2,10 +2,10 @@
  * Internal filesystem scanner for Source Quiver layout.
  *
  * Uses Node.js `fs/promises` — this module must only be imported from
- * Node-only contexts (fromDir, fromPackage, etc.).
+ * Node-only contexts (`fromDir`, `build`).
  */
-import type { QuiverMeta } from "./quiver-yaml.js";
-import type { QuiverLoader } from "./quiver.js";
+import type { QuiverMeta } from './quiver-yaml.js';
+import type { QuiverLoader } from './quiver.js';
 /**
  * Scans a Source Quiver root directory.
  *

package/dist/source-loader.js

@@ -2,13 +2,13 @@
  * Internal filesystem scanner for Source Quiver layout.
  *
  * Uses Node.js `fs/promises` — this module must only be imported from
- * Node-only contexts (fromDir, fromPackage, etc.).
+ * Node-only contexts (`fromDir`, `build`).
  */
-import { readdir, readFile, stat } from "node:fs/promises";
-import { join, relative, sep } from "node:path";
-import { QuiverError } from "./errors.js";
-import { parseQuiverYaml } from "./quiver-yaml.js";
-import { isCanonicalSemver, compareSemver } from "./semver.js";
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { QuiverError } from './errors.js';
+import { parseQuiverYaml } from './quiver-yaml.js';
+import { isCanonicalSemver, compareSemver } from './semver.js';
 /**
  * Scans a Source Quiver root directory.
  *
@@ -24,7 +24,7 @@ import { isCanonicalSemver, compareSemver } from "./semver.js";
  */
 export async function scanSourceQuiver(rootDir) {
     // --- Read Quiver.yaml ---
-    const quiverYamlPath = join(rootDir, "Quiver.yaml");
+    const quiverYamlPath = join(rootDir, 'Quiver.yaml');
     let raw;
     try {
         raw = await readFile(quiverYamlPath);
@@ -36,25 +36,25 @@ export async function scanSourceQuiver(rootDir) {
         // (Contrast: missing Quill.yaml inside a version dir is quiver_invalid —
         // the version dir exists but lacks its required sentinel file.)
         const code = err.code;
-        if (code === "ENOENT") {
-            throw new QuiverError("transport_error", `Source Quiver at "${rootDir}" is missing required "Quiver.yaml"`, { cause: err });
+        if (code === 'ENOENT') {
+            throw new QuiverError('transport_error', `Source Quiver at "${rootDir}" is missing required "Quiver.yaml"`, { cause: err });
         }
-        throw new QuiverError("transport_error", `Failed to read "Quiver.yaml" at "${quiverYamlPath}": ${err.message}`, { cause: err });
+        throw new QuiverError('transport_error', `Failed to read "Quiver.yaml" at "${quiverYamlPath}": ${err.message}`, { cause: err });
     }
     const meta = parseQuiverYaml(raw);
     // --- Walk quills/ directory ---
-    const quillsDir = join(rootDir, "quills");
+    const quillsDir = join(rootDir, 'quills');
     let quillNames;
     try {
         quillNames = await readdir(quillsDir);
     }
     catch (err) {
         const code = err.code;
-        if (code === "ENOENT") {
+        if (code === 'ENOENT') {
             // Missing quills/ is fine — empty catalog
             return { meta, catalog: new Map() };
         }
-        throw new QuiverError("transport_error", `Failed to read "quills/" directory at "${quillsDir}": ${err.message}`, { cause: err });
+        throw new QuiverError('transport_error', `Failed to read "quills/" directory at "${quillsDir}": ${err.message}`, { cause: err });
     }
     const catalog = new Map();
     for (const quillName of quillNames) {
@@ -65,7 +65,7 @@ export async function scanSourceQuiver(rootDir) {
             st = await stat(quillNameDir);
         }
         catch (err) {
-            throw new QuiverError("transport_error", `Failed to stat "${quillNameDir}": ${err.message}`, { cause: err });
+            throw new QuiverError('transport_error', `Failed to stat "${quillNameDir}": ${err.message}`, { cause: err });
         }
         if (!st.isDirectory())
             continue;
@@ -75,7 +75,7 @@ export async function scanSourceQuiver(rootDir) {
             versionDirs = await readdir(quillNameDir);
         }
         catch (err) {
-            throw new QuiverError("transport_error", `Failed to read versions for quill "${quillName}": ${err.message}`, { cause: err });
+            throw new QuiverError('transport_error', `Failed to read versions for quill "${quillName}": ${err.message}`, { cause: err });
         }
         const versions = [];
         for (const versionDir of versionDirs) {
@@ -86,25 +86,25 @@ export async function scanSourceQuiver(rootDir) {
                 vst = await stat(versionPath);
             }
             catch (err) {
-                throw new QuiverError("transport_error", `Failed to stat "${versionPath}": ${err.message}`, { cause: err });
+                throw new QuiverError('transport_error', `Failed to stat "${versionPath}": ${err.message}`, { cause: err });
             }
             if (!vst.isDirectory())
                 continue;
             // Non-canonical version → quiver_invalid
             if (!isCanonicalSemver(versionDir)) {
-                throw new QuiverError("quiver_invalid", `Quill "${quillName}" has non-canonical version directory "${versionDir}" — only x.y.z format is allowed`, { quiverName: meta.name, version: versionDir });
+                throw new QuiverError('quiver_invalid', `Quill "${quillName}" has non-canonical version directory "${versionDir}" — only x.y.z format is allowed`, { quiverName: meta.name, version: versionDir });
             }
             // Require Quill.yaml sentinel inside the version dir
-            const quillYamlPath = join(versionPath, "Quill.yaml");
+            const quillYamlPath = join(versionPath, 'Quill.yaml');
             try {
                 await stat(quillYamlPath);
             }
             catch (err) {
                 const code = err.code;
-                if (code === "ENOENT") {
-                    throw new QuiverError("quiver_invalid", `Quill "${quillName}@${versionDir}" is missing required "Quill.yaml"`, { quiverName: meta.name, version: versionDir });
+                if (code === 'ENOENT') {
+                    throw new QuiverError('quiver_invalid', `Quill "${quillName}@${versionDir}" is missing required "Quill.yaml"`, { quiverName: meta.name, version: versionDir });
                 }
-                throw new QuiverError("transport_error", `Failed to stat "Quill.yaml" at "${quillYamlPath}": ${err.message}`, { cause: err });
+                throw new QuiverError('transport_error', `Failed to stat "Quill.yaml" at "${quillYamlPath}": ${err.message}`, { cause: err });
             }
             versions.push(versionDir);
         }
@@ -133,7 +133,7 @@ async function walkDir(baseDir, currentDir, tree) {
         entries = await readdir(currentDir);
     }
     catch (err) {
-        throw new QuiverError("transport_error", `Failed to read directory "${currentDir}": ${err.message}`, { cause: err });
+        throw new QuiverError('transport_error', `Failed to read directory "${currentDir}": ${err.message}`, { cause: err });
     }
     for (const entry of entries) {
         const fullPath = join(currentDir, entry);
@@ -142,7 +142,7 @@ async function walkDir(baseDir, currentDir, tree) {
             st = await stat(fullPath);
         }
         catch (err) {
-            throw new QuiverError("transport_error", `Failed to stat "${fullPath}": ${err.message}`, { cause: err });
+            throw new QuiverError('transport_error', `Failed to stat "${fullPath}": ${err.message}`, { cause: err });
         }
         if (st.isDirectory()) {
             await walkDir(baseDir, fullPath, tree);
@@ -150,13 +150,13 @@ async function walkDir(baseDir, currentDir, tree) {
         else {
             // Compute relative POSIX path
             const rel = relative(baseDir, fullPath);
-            const posixRel = sep === "/" ? rel : rel.split(sep).join("/");
+            const posixRel = sep === '/' ? rel : rel.split(sep).join('/');
             let bytes;
             try {
                 bytes = await readFile(fullPath);
             }
             catch (err) {
-                throw new QuiverError("transport_error", `Failed to read file "${fullPath}": ${err.message}`, { cause: err });
+                throw new QuiverError('transport_error', `Failed to read file "${fullPath}": ${err.message}`, { cause: err });
             }
             tree.set(posixRel, bytes);
         }
@@ -173,7 +173,7 @@ export class SourceLoader {
         this.rootDir = rootDir;
     }
     async loadTree(name, version) {
-        const quillDir = join(this.rootDir, "quills", name, version);
+        const quillDir = join(this.rootDir, 'quills', name, version);
         return readQuillTree(quillDir);
     }
 }

package/dist/transports/fs-built-transport.d.ts

@@ -4,9 +4,9 @@
  * Internal; not exported from index.ts.
  *
  * Static `node:*` imports — this module must never be reached from browser
- * bundles. It is loaded lazily by `Quiver.fromBuiltDir` in `./node.js`.
+ * bundles. It is loaded lazily by `fromBuiltDir` in `./node.js`.
  */
-import type { BuiltTransport } from "../built-loader.js";
+import type { BuiltTransport } from '../built-loader.js';
 export declare class FsBuiltTransport implements BuiltTransport {
     private readonly rootDir;
     constructor(rootDir: string);

package/dist/transports/fs-built-transport.js

@@ -4,23 +4,25 @@
  * Internal; not exported from index.ts.
  *
  * Static `node:*` imports — this module must never be reached from browser
- * bundles. It is loaded lazily by `Quiver.fromBuiltDir` in `./node.js`.
+ * bundles. It is loaded lazily by `fromBuiltDir` in `./node.js`.
  */
-import { readFile } from "node:fs/promises";
-import { join, isAbsolute, normalize, sep } from "node:path";
-import { QuiverError } from "../errors.js";
+import { readFile } from 'node:fs/promises';
+import { join, isAbsolute, normalize, sep } from 'node:path';
+import { QuiverError } from '../errors.js';
 export class FsBuiltTransport {
     rootDir;
     constructor(rootDir) {
         this.rootDir = rootDir;
     }
+    // No cache sits between this and the bytes, so `FetchOptions` has nothing to
+    // act on here.
     async fetchBytes(relativePath) {
         if (isAbsolute(relativePath)) {
-            throw new QuiverError("transport_error", `FsBuiltTransport: absolute paths are not allowed: "${relativePath}"`);
+            throw new QuiverError('transport_error', `FsBuiltTransport: absolute paths are not allowed: "${relativePath}"`);
         }
         const normalized = normalize(relativePath);
-        if (normalized.startsWith("..") || normalized.split(sep).includes("..")) {
-            throw new QuiverError("transport_error", `FsBuiltTransport: path escapes root: "${relativePath}"`);
+        if (normalized.startsWith('..') || normalized.split(sep).includes('..')) {
+            throw new QuiverError('transport_error', `FsBuiltTransport: path escapes root: "${relativePath}"`);
         }
         const filePath = join(this.rootDir, normalized);
         try {
@@ -28,7 +30,7 @@ export class FsBuiltTransport {
             return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
         }
         catch (err) {
-            throw new QuiverError("transport_error", `Failed to read "${filePath}": ${err.message}`, { cause: err });
+            throw new QuiverError('transport_error', `Failed to read "${filePath}": ${err.message}`, { cause: err });
         }
     }
 }

package/dist/transports/http-transport.d.ts

@@ -4,9 +4,9 @@
  *
  * Uses globalThis.fetch — no node: imports at any level.
  */
-import type { BuiltTransport } from "../built-loader.js";
+import type { BuiltTransport, FetchOptions } from '../built-loader.js';
 export declare class HttpTransport implements BuiltTransport {
     private readonly baseUrl;
     constructor(baseUrl: string);
-    fetchBytes(relativePath: string): Promise<Uint8Array>;
+    fetchBytes(relativePath: string, opts?: FetchOptions): Promise<Uint8Array>;
 }

package/dist/transports/http-transport.js

@@ -4,28 +4,30 @@
  *
  * Uses globalThis.fetch — no node: imports at any level.
  */
-import { QuiverError } from "../errors.js";
+import { QuiverError } from '../errors.js';
 export class HttpTransport {
     baseUrl;
     constructor(baseUrl) {
         // Normalize: ensure exactly one trailing slash.
-        this.baseUrl = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+        this.baseUrl = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
     }
-    async fetchBytes(relativePath) {
+    async fetchBytes(relativePath, opts) {
         // Strip any leading slash from relativePath to avoid double slashes.
-        const cleanPath = relativePath.startsWith("/")
-            ? relativePath.slice(1)
-            : relativePath;
+        const cleanPath = relativePath.startsWith('/') ? relativePath.slice(1) : relativePath;
         const url = `${this.baseUrl}${cleanPath}`;
         let response;
         try {
-            response = await globalThis.fetch(url);
+            // `no-cache` revalidates with the origin rather than skipping the cache:
+            // a 304 still serves from disk. Only the pointer asks for it, and only
+            // the browser-cache layer of the stale-pointer failure is a client's to
+            // fix; a stale edge is answered by that host's cache headers.
+            response = await globalThis.fetch(url, opts?.revalidate ? { cache: 'no-cache' } : undefined);
         }
         catch (err) {
-            throw new QuiverError("transport_error", `Network error fetching "${url}": ${err.message}`, { cause: err });
+            throw new QuiverError('transport_error', `Network error fetching "${url}": ${err.message}`, { cause: err });
         }
         if (!response.ok) {
-            throw new QuiverError("transport_error", `HTTP ${response.status} fetching "${url}"`);
+            throw new QuiverError('transport_error', `HTTP ${response.status} fetching "${url}"`);
         }
         const buffer = await response.arrayBuffer();
         return new Uint8Array(buffer);

package/package.json

@@ -1,74 +1,68 @@
 {
-  "name": "@quillmark/quiver",
-  "version": "0.15.0",
-  "description": "Quiver registry and build tooling for Quillmark",
-  "type": "module",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/quillmark-org/quiver.git"
-  },
-  "bugs": {
-    "url": "https://github.com/quillmark-org/quiver/issues"
-  },
-  "homepage": "https://github.com/quillmark-org/quiver#readme",
-  "keywords": [
-    "quillmark",
-    "quiver",
-    "typst",
-    "markdown"
-  ],
-  "author": "Quillmark Contributors",
-  "engines": {
-    "node": ">=22"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./node": {
-      "types": "./dist/node.d.ts",
-      "import": "./dist/node.js"
-    },
-    "./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/preview.js"
-  ],
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "peerDependencies": {
-    "@quillmark/wasm": ">=0.90.0-0"
-  },
-  "dependencies": {
-    "fflate": "^0.8.2",
-    "yaml": "^2.8.3"
-  },
-  "devDependencies": {
-    "@quillmark/wasm": "0.90.0",
-    "@types/node": "^25.3.3",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
-  },
-  "bin": {
-    "quiver": "./dist/bin/quiver.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "prepack": "rm -rf dist && tsc",
-    "test": "vitest run",
-    "lint": "tsc --noEmit"
-  }
+	"name": "@quillmark/quiver",
+	"version": "0.17.0",
+	"description": "Quiver registry and build tooling for Quillmark",
+	"type": "module",
+	"license": "Apache-2.0",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/borb-sh/quillmark-js.git",
+		"directory": "packages/quiver"
+	},
+	"bugs": {
+		"url": "https://github.com/borb-sh/quillmark-js/issues"
+	},
+	"homepage": "https://github.com/borb-sh/quillmark-js/tree/main/packages/quiver#readme",
+	"keywords": [
+		"quillmark",
+		"quiver",
+		"typst",
+		"markdown"
+	],
+	"author": "Quillmark Contributors",
+	"engines": {
+		"node": ">=22"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./node": {
+			"types": "./dist/node.d.ts",
+			"import": "./dist/node.js"
+		}
+	},
+	"sideEffects": false,
+	"files": [
+		"dist",
+		"NOTICE"
+	],
+	"peerDependencies": {
+		"@quillmark/wasm": ">=0.101.0-0"
+	},
+	"dependencies": {
+		"fflate": "^0.8.2",
+		"yaml": "^2.8.3"
+	},
+	"devDependencies": {
+		"@types/node": "^25.3.3",
+		"publint": "^0.3.0",
+		"typescript": "^5.9.3",
+		"vitest": "^4.0.18"
+	},
+	"bin": {
+		"quiver": "./dist/bin/quiver.js"
+	},
+	"scripts": {
+		"build": "tsc",
+		"prepare": "npm run build",
+		"prepack": "rm -rf dist && npm run build",
+		"test": "vitest run",
+		"check": "tsc --noEmit -p tsconfig.check.json",
+		"check:pack": "publint"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
 }

package/dist/preview.d.ts

@@ -1,81 +0,0 @@
-/**
- * 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 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.
- *
- * Usage (place a script next to your Quiver.yaml):
- *
- *   import { Engine } from "@quillmark/wasm";
- *   import { renderQuiverSamples } from "@quillmark/quiver/preview";
- *
- *   await renderQuiverSamples(import.meta.url, { engine: new Engine() });
- *   // → open ./preview/index.html
- *
- * The sample document is the illustrative example seeded by
- * `quill.seedDocument()` 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 seeds 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.
- */
-import type { Engine } from "@quillmark/wasm";
-export interface RenderQuiverSamplesOptions {
-    /**
-     * Canonical render engine (`new Engine()` from `@quillmark/wasm`). It takes the
-     * core `Quill`/`Document` that quiver produces and clones them into the
-     * backend on demand — no build-matching or handle-crossing for the caller.
-     */
-    engine: Engine;
-    /** 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 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
- * 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[]>;