@quillmark/quiver 0.15.0 → 0.16.0

package/README.md

@@ -192,6 +192,53 @@ const quill = await quiver.getQuill(doc.quillRef);
 const result = await engine.render(quill, doc, { format: "pdf" });
 ```
 
+## SSR seeding (skip the `latest.json` pointer)
+
+`Quiver.fromBuiltUrl(url)` first fetches `<url>/latest.json` — a stable-named,
+non-content-addressed pointer to the current manifest — before fetching the
+manifest itself. Because that one filename is stable, a CDN edge or browser
+cache can serve a **stale pointer** after a release and silently pin the
+client to the old catalog, with no error. Per-host cache headers only fix this
+one serving layer at a time.
+
+If you already hold the manifest bytes at build time — a common case for SSR
+consumers, which read the built artifact during their own build — seed the
+catalog from them directly with `Quiver.fromManifest`. It never requests
+`latest.json`; bundles and fonts are still fetched lazily and
+content-addressed, relative to `baseUrl`, exactly as with `fromBuiltUrl`:
+
+```ts
+// Server build step — read the manifest the build wrote.
+// build-output/latest.json → { "manifest": "manifest.<hash>.json" }
+import { readFile } from "node:fs/promises";
+
+const { manifest } = JSON.parse(
+  await readFile("./public/quivers/my-quiver/latest.json", "utf8"),
+);
+const manifestBytes = new Uint8Array(
+  await readFile(`./public/quivers/my-quiver/${manifest}`),
+);
+// Inline manifestBytes into the page payload (e.g. base64) for the client.
+```
+
+```ts
+// Browser / SSR runtime — seed from the bytes you shipped, no pointer fetch.
+import { Engine, Document } from "@quillmark/wasm";
+import { Quiver } from "@quillmark/quiver";
+
+const quiver = await Quiver.fromManifest("/quivers/my-quiver/", manifestBytes);
+const engine = new Engine();
+
+const doc = Document.fromMarkdown(markdownString);
+const quill = await quiver.getQuill(doc.quillRef);
+const result = await engine.render(quill, doc, { format: "pdf" });
+```
+
+`fromManifest` is browser-safe (no `node:*` imports) and shares
+`fromBuiltUrl`'s error semantics: `quiver_invalid` for malformed manifest
+bytes, `transport_error` for a `file://` `baseUrl` or a later bundle-fetch
+failure.
+
 ## Server-side runtime (Node, packed artifact on disk)
 
 For server-side rendering where the packed artifact ships in the deployment

package/dist/build.d.ts

@@ -12,7 +12,7 @@ export type BuildOptions = Record<string, never>;
  *
  * Output layout:
  *   outDir/
- *     Quiver.json                   # stable pointer
+ *     latest.json                   # stable pointer to the current manifest
  *     manifest.<md5prefix6>.json    # hashed manifest
  *     <name>@<version>.<md5>.zip    # one bundle per quill
  *     store/

package/dist/build.js

@@ -14,7 +14,7 @@ const FONT_EXT = /\.(ttf|otf|woff|woff2)$/i;
  *
  * Output layout:
  *   outDir/
- *     Quiver.json                   # stable pointer
+ *     latest.json                   # stable pointer to the current manifest
  *     manifest.<md5prefix6>.json    # hashed manifest
  *     <name>@<version>.<md5>.zip    # one bundle per quill
  *     store/
@@ -108,9 +108,9 @@ export async function buildQuiver(sourceDir, outDir, _opts) {
     catch (err) {
         throw new QuiverError("transport_error", `Failed to write manifest "${manifestPath}": ${err.message}`, { cause: err });
     }
-    // 9–10. Write stable pointer Quiver.json.
+    // 9–10. Write stable pointer latest.json.
     const pointer = { manifest: manifestFileName };
-    const pointerPath = join(outDir, "Quiver.json");
+    const pointerPath = join(outDir, "latest.json");
     try {
         await writeFile(pointerPath, JSON.stringify(pointer), "utf-8");
     }

package/dist/built-loader.d.ts

@@ -19,9 +19,15 @@ export interface BuiltTransport {
 /**
  * Load a build-output quiver via the given transport.
  *
- * 1. Fetches Quiver.json (pointer) and parses it.
+ * 1. Fetches latest.json (pointer) and parses it.
  * 2. Fetches the manifest file it points to and validates it.
  * 3. Builds a catalog from manifest entries (versions sorted descending).
  * 4. Returns a Quiver instance backed by a BuiltLoader.
  */
 export declare function loadBuiltQuiver(transport: BuiltTransport): Promise<Quiver>;
+/**
+ * Seed a quiver from caller-provided manifest bytes, skipping the latest.json
+ * pointer fetch. `transport` is used only for lazy bundle/font fetches.
+ * Throws `quiver_invalid` on malformed bytes.
+ */
+export declare function seedBuiltQuiver(transport: BuiltTransport, manifestBytes: Uint8Array): Quiver;

package/dist/built-loader.js

@@ -96,15 +96,15 @@ function parsePointer(raw) {
         parsed = JSON.parse(raw);
     }
     catch {
-        throw new QuiverError("quiver_invalid", "Quiver.json contains invalid JSON");
+        throw new QuiverError("quiver_invalid", "latest.json contains invalid JSON");
     }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        throw new QuiverError("quiver_invalid", "Quiver.json must be a JSON object");
+        throw new QuiverError("quiver_invalid", "latest.json must be a JSON object");
     }
     const obj = parsed;
-    assertNoUnknownKeys(obj, ["manifest"], "Quiver.json");
+    assertNoUnknownKeys(obj, ["manifest"], "latest.json");
     if (typeof obj["manifest"] !== "string" || obj["manifest"].length === 0) {
-        throw new QuiverError("quiver_invalid", 'Quiver.json must have a non-empty string "manifest" field');
+        throw new QuiverError("quiver_invalid", 'latest.json must have a non-empty string "manifest" field');
     }
     return obj["manifest"];
 }
@@ -175,11 +175,38 @@ function parseManifest(raw) {
         quills,
     };
 }
-// ─── Main entry point ─────────────────────────────────────────────────────────
+// ─── Catalog assembly ─────────────────────────────────────────────────────────
+/**
+ * Validate manifest bytes (`quiver_invalid` on format errors) and assemble a
+ * Quiver backed by a BuiltLoader over `transport`. Shared by `loadBuiltQuiver`
+ * (pointer-following) and `seedBuiltQuiver` (seed).
+ */
+function buildQuiverFromManifestBytes(transport, manifestBytes) {
+    const manifest = parseManifest(new TextDecoder().decode(manifestBytes));
+    // catalog: name → versions (desc); index: "name@version" → entry (dedup).
+    const catalogRaw = new Map();
+    const index = new Map();
+    for (const entry of manifest.quills) {
+        const key = `${entry.name}@${entry.version}`;
+        if (index.has(key)) {
+            throw new QuiverError("quiver_invalid", `Duplicate quill entry in manifest: "${key}"`);
+        }
+        index.set(key, entry);
+        const versions = catalogRaw.get(entry.name) ?? [];
+        versions.push(entry.version);
+        catalogRaw.set(entry.name, versions);
+    }
+    for (const [, versions] of catalogRaw) {
+        versions.sort((a, b) => compareSemver(b, a));
+    }
+    const loader = new BuiltLoader(transport, index);
+    return Quiver._fromLoader(manifest.name, catalogRaw, loader);
+}
+// ─── Main entry points ────────────────────────────────────────────────────────
 /**
  * Load a build-output quiver via the given transport.
  *
- * 1. Fetches Quiver.json (pointer) and parses it.
+ * 1. Fetches latest.json (pointer) and parses it.
  * 2. Fetches the manifest file it points to and validates it.
  * 3. Builds a catalog from manifest entries (versions sorted descending).
  * 4. Returns a Quiver instance backed by a BuiltLoader.
@@ -188,12 +215,12 @@ export async function loadBuiltQuiver(transport) {
     // 1. Fetch and parse pointer.
     let pointerBytes;
     try {
-        pointerBytes = await transport.fetchBytes("Quiver.json");
+        pointerBytes = await transport.fetchBytes("latest.json");
     }
     catch (err) {
         if (err instanceof QuiverError)
             throw err;
-        throw new QuiverError("transport_error", `Failed to fetch Quiver.json: ${err.message}`, { cause: err });
+        throw new QuiverError("transport_error", `Failed to fetch latest.json: ${err.message}`, { cause: err });
     }
     const manifestFileName = parsePointer(new TextDecoder().decode(pointerBytes));
     validateManifestFileName(manifestFileName);
@@ -207,26 +234,14 @@ export async function loadBuiltQuiver(transport) {
             throw err;
         throw new QuiverError("transport_error", `Failed to fetch manifest "${manifestFileName}": ${err.message}`, { cause: err });
     }
-    const manifest = parseManifest(new TextDecoder().decode(manifestBytes));
-    // 3. Build catalog: name → versions sorted descending.
-    //    Also build index map: "name@version" → entry (with duplicate detection).
-    const catalogRaw = new Map();
-    const index = new Map();
-    for (const entry of manifest.quills) {
-        const key = `${entry.name}@${entry.version}`;
-        if (index.has(key)) {
-            throw new QuiverError("quiver_invalid", `Duplicate quill entry in manifest: "${key}"`);
-        }
-        index.set(key, entry);
-        const versions = catalogRaw.get(entry.name) ?? [];
-        versions.push(entry.version);
-        catalogRaw.set(entry.name, versions);
-    }
-    for (const [, versions] of catalogRaw) {
-        versions.sort((a, b) => compareSemver(b, a));
-    }
-    // 4. Build loader.
-    const loader = new BuiltLoader(transport, index);
-    // 5. Return Quiver via internal factory.
-    return Quiver._fromLoader(manifest.name, catalogRaw, loader);
+    // 3–4. Validate manifest + assemble catalog/loader.
+    return buildQuiverFromManifestBytes(transport, manifestBytes);
+}
+/**
+ * Seed a quiver from caller-provided manifest bytes, skipping the latest.json
+ * pointer fetch. `transport` is used only for lazy bundle/font fetches.
+ * Throws `quiver_invalid` on malformed bytes.
+ */
+export function seedBuiltQuiver(transport, manifestBytes) {
+    return buildQuiverFromManifestBytes(transport, manifestBytes);
 }

package/dist/node.d.ts

@@ -43,7 +43,7 @@ type NodeQuiverStatics = {
     fromDir(pathOrFileUrl: string): Promise<Base>;
     /**
      * Loads a packed (build-output) quiver from a local directory containing
-     * `Quiver.json` and the manifest/bundle/store files written by
+     * `latest.json` and the manifest/bundle/store files written by
      * `Quiver.build`. Symmetric to `fromBuiltUrl(url)` but reads from disk
      * instead of HTTP — no network required.
      *

package/dist/quiver.d.ts

@@ -42,6 +42,16 @@ export declare class Quiver {
      * on format errors.
      */
     static fromBuiltUrl(url: string): Promise<Quiver>;
+    /**
+     * Browser-safe factory. Seeds the catalog from caller-provided manifest
+     * bytes — never fetches `latest.json` — then fetches bundles lazily and
+     * content-addressed, relative to `baseUrl`, like `fromBuiltUrl`. For SSR
+     * consumers that already hold the manifest at build time.
+     *
+     * Throws `quiver_invalid` on malformed manifest bytes, `transport_error`
+     * on a `file://` baseUrl or a later bundle fetch failure.
+     */
+    static fromManifest(baseUrl: string, manifestBytes: Uint8Array): Promise<Quiver>;
     /** Returns all known quill names, sorted lexicographically. */
     quillNames(): string[];
     /**

package/dist/quiver.js

@@ -69,6 +69,24 @@ export class Quiver {
         const transport = new HttpTransport(url);
         return loadBuiltQuiver(transport);
     }
+    /**
+     * Browser-safe factory. Seeds the catalog from caller-provided manifest
+     * bytes — never fetches `latest.json` — then fetches bundles lazily and
+     * content-addressed, relative to `baseUrl`, like `fromBuiltUrl`. For SSR
+     * consumers that already hold the manifest at build time.
+     *
+     * Throws `quiver_invalid` on malformed manifest bytes, `transport_error`
+     * on a `file://` baseUrl or a later bundle fetch failure.
+     */
+    static async fromManifest(baseUrl, manifestBytes) {
+        if (baseUrl.startsWith("file://")) {
+            throw new QuiverError("transport_error", `Quiver.fromManifest requires an http(s):// or origin-relative baseUrl; got "${baseUrl}". For local build output, use Quiver.fromBuiltDir from @quillmark/quiver/node.`);
+        }
+        const { HttpTransport } = await import("./transports/http-transport.js");
+        const { seedBuiltQuiver } = await import("./built-loader.js");
+        const transport = new HttpTransport(baseUrl);
+        return seedBuiltQuiver(transport, manifestBytes);
+    }
     /** Returns all known quill names, sorted lexicographically. */
     quillNames() {
         return [...this.#catalog.keys()].sort();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/quiver",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Quiver registry and build tooling for Quillmark",
   "type": "module",
   "license": "MIT",
@@ -57,7 +57,7 @@
     "yaml": "^2.8.3"
   },
   "devDependencies": {
-    "@quillmark/wasm": "0.90.0",
+    "@quillmark/wasm": "0.91.0",
     "@types/node": "^25.3.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"