@quillmark/quiver 0.28.0 → 0.30.0

package/MIGRATION.md

@@ -2,6 +2,22 @@
 
 Upgrade notes per range. The [CHANGELOG](CHANGELOG.md) is the full record; this page is the subset that breaks a working consumer, ordered by how late you find out.
 
+## 0.29 → 0.30
+
+### Rebuild every artifact, and move quiver and quillkit together
+
+A built quiver is `quiver.json` beside one bundle per quill and a `fonts/` directory. The hashed manifest and `store/` are gone, and `latest.json` carries only `format`, now 2. An old artifact under 0.30 is a `transport_error` on `quiver.json`; a 0.30 artifact under an older reader is refused with the upgrade named. Re-run `build`; nothing in the source layout changes.
+
+`quillkit`'s client carries its own copy of this package's reader and packs through the collection's, so a collection upgrades `@quillmark/quiver` in the same change as `quillkit`. `quillkit site` and `quillkit studio` refuse a pack with no `quiver.json`, naming the upgrade.
+
+A host rule naming `quiver/latest.json` now names `quiver/quiver.json`.
+
+### Runtime, not build time
+
+**`Quiver.fromBuiltUrl(url, { seed })` takes no `seed`.** TypeScript refuses the second argument; plain JavaScript ignores it, so a seeded call fetches what it used to hold. Hold the whole artifact and call `Quiver.fromBuiltFiles(files)`, or fetch it.
+
+**Fetched bytes are not checked against their names**, and no fetch carries a byte ceiling; a bundle's unpack budget is unchanged. A bundle that does not open as a zip and a font that does not open as a font are refused, and `build` refuses a font file of the second kind where it packs it. Serve the artifact over `https`, which is what answers a corrupted byte.
+
 ## 0.16 → 0.19
 
 ### Runtime, not build time

package/README.md

@@ -99,7 +99,7 @@ const quiver = await fromBuiltDir('./static/quills/my-quiver');
 
 ## Server-side runtime (no filesystem)
 
-A serverless function's packed artifact is not on a path the invocation can read, so `fromBuiltDir` cannot see it. Hand over the bytes instead, keyed by artifact-relative path as `build` writes them (`latest.json`, `manifest.<digest>.json`, `<name>@<x.y.z>.<digest>.zip`, `store/<hash>`):
+A serverless function's packed artifact is not on a path the invocation can read, so `fromBuiltDir` cannot see it. Hand over the bytes instead, keyed by artifact-relative path as `build` writes them (`quiver.json`, `<name>@<x.y.z>.<digest>.zip`, `fonts/<hash>`):
 
 ```ts
 import { Quiver } from '@quillmark/quiver';
@@ -109,30 +109,17 @@ const quiver = await Quiver.fromBuiltFiles(artifactFiles); // Map<string, Uint8A
 
 Nothing is fetched, so nothing self-fetches over your own load balancer. The map must carry the whole artifact; a path it lacks is a `transport_error` naming that path.
 
-Where inlining the bundles and fonts is not practical, hold the two small documents and let the host serve the rest:
+## The `quiver.json` index
 
-```ts
-const quiver = await Quiver.fromBuiltUrl('/quills/my-quiver/', {
-	seed: new Map([
-		['latest.json', pointerBytes],
-		[manifestName, manifestBytes]
-	])
-});
-```
-
-The seed answers first and the URL serves what it does not carry. Seeding `latest.json` also settles which catalog the process reads at deploy time rather than at cache-revalidation time. Seeded bytes are checked against the digest in their name exactly as fetched bytes are.
-
-## The `latest.json` pointer
-
-`Quiver.fromBuiltUrl(url)` first fetches `<url>/latest.json`, a stable-named pointer to the current manifest. Everything behind that pointer is content-addressed and checked against the digest in its name; the pointer itself is not, so a cache layer can serve a stale one and silently pin the client to the old catalog. It is therefore the one request fetched `no-cache` (revalidate with the origin; a 304 still serves from disk), and every other request is `force-cache`, a digest-carrying name being entitled to whatever the cache already holds. Both are the browser layer only: a stale CDN edge is answered by that host's cache headers, and `quillkit`'s README states the whole contract for a deploy serving a client over one.
+`Quiver.fromBuiltUrl(url)` first fetches `<url>/quiver.json`: the format and the catalog, naming each quill's bundle and fonts. Every other name carries the digest of its own bytes, so a changed file is a changed name and is safe to cache forever; `quiver.json` is not, and a cache layer serving a stale one silently pins the client to the old catalog. It is therefore the one request fetched `no-cache` (revalidate with the origin; a 304 still serves from disk), and every other request is `force-cache`, read once more with `reload` if what the cache answered fails. Both are the browser layer only: a stale CDN edge is answered by that host's cache headers, and `quillkit`'s README states the whole contract for a deploy serving a client over one.
 
-The check itself needs `crypto.subtle`, which a browser exposes only in a secure context. An `https` page, `http://localhost` and Node have one; a page served over plain `http` to anything else — a dev host on a LAN address, a staging box without a certificate — has none, and there every fetch passes through unchecked.
+A `getQuill` reads one bundle and the fonts it names, nothing of another quill. Fonts are stored once by hash, so a release that edits a template re-downloads that quill's bundle and not its fonts. A tab still holding the previous release's `quiver.json` rereads it once when a read fails.
 
 ## What a quiver is trusted to be
 
 **A quill is a template the backend executes, so loading a quiver runs its author's code.** Point one at a source you would take a dependency from — an npm package or a git tag, pinned like any other — because nothing here sandboxes a quill, and a collection assembled from anywhere else is a decision to make on purpose.
 
-Content addressing is an integrity check and not a provenance one: the digest in each name catches a corrupted object, a partial sync and a name reused across releases, and says nothing about who packed the bytes. Where the primitive behind it is absent the page is no secure context either, so the pointer, the manifest, the digests and the client itself all arrived over the same unauthenticated channel — which is the whole of why a built quiver is served over `https`.
+Nothing checks fetched bytes against their names: the digests are there for caching, and what answers a corrupted or substituted byte is the channel. `quiver.json`, the bundles and the client itself arrive over the same one, which is the whole of why a built quiver is served over `https`.
 
 ## Error handling
 

package/dist/build.d.ts

@@ -9,22 +9,22 @@
 export interface BuildOptions {
     /**
      * Pack versions below `MIN_PUBLISHED_VERSION` too. Off by default: the
-     * artifact is a deployment, and the draft space is not part of one. An
-     * author's own viewer turns it on, which is the only caller that should.
+     * artifact is a deployment, and the draft space is not part of one. A
+     * viewer of the collection as it stands turns it on.
      */
     drafts?: boolean;
 }
 /**
  * Reads a Source Quiver, validates it, and writes the build output to outDir.
  *
- * Output layout. Every name but the pointer carries the SHA-256 of what it
- * names, which is what the loader checks on fetch:
+ * Output layout. Every name but the two JSON documents carries the SHA-256 of what it
+ * names, which is what makes it safe to cache forever:
  *   outDir/
- *     latest.json                     # the format, and a stable pointer to the manifest
- *     manifest.<sha256:32>.json       # hashed manifest
+ *     quiver.json                       # the format and the catalog
+ *     latest.json                       # the format alone, for a reader of format 1
  *     <name>@<version>.<sha256:32>.zip  # one bundle per quill
- *     store/
- *       <sha256>                      # dehydrated font bytes (full hash, no ext)
+ *     fonts/
+ *       <sha256>                        # dehydrated font bytes (full hash, no ext)
  *
  * A generation is assembled beside outDir and moved in whole, so a reader
  * fetching mid-build reads the previous one rather than a torn tree, and a
@@ -32,7 +32,7 @@ export interface BuildOptions {
  *
  * Versions below `MIN_PUBLISHED_VERSION` are drafts and are left out unless
  * `options.drafts` asks for them; a quill with nothing above the floor is
- * absent from the manifest entirely.
+ * absent from `quiver.json` entirely.
  *
  * Throws:
  *   - `quiver_invalid` on source validation failures (propagated from scanner)

package/dist/build.js

@@ -7,9 +7,11 @@
  */
 import { QuiverError } from './errors.js';
 import { packFiles } from './bundle.js';
-import { NAME_DIGEST_LENGTH } from './digest.js';
-import { MANIFEST_VERSION, POINTER_FORMAT } from './format.js';
+import { FORMAT, INDEX, LEGACY_POINTER } from './format.js';
+import { isFont } from './signature.js';
 import { isDraft } from './semver.js';
+/** Hex chars of SHA-256 in a bundle's name: enough that a changed bundle never reuses one. */
+const NAME_DIGEST_LENGTH = 32;
 /** Font file extensions recognised by the builder (case-insensitive). */
 const FONT_EXT = /\.(ttf|otf|woff|woff2)$/i;
 /** The two trees a build owns beside its output: where a generation is assembled, and
@@ -52,14 +54,14 @@ function assertSafeOutDir(path, sourceDir, outDir) {
 /**
  * Reads a Source Quiver, validates it, and writes the build output to outDir.
  *
- * Output layout. Every name but the pointer carries the SHA-256 of what it
- * names, which is what the loader checks on fetch:
+ * Output layout. Every name but the two JSON documents carries the SHA-256 of what it
+ * names, which is what makes it safe to cache forever:
  *   outDir/
- *     latest.json                     # the format, and a stable pointer to the manifest
- *     manifest.<sha256:32>.json       # hashed manifest
+ *     quiver.json                       # the format and the catalog
+ *     latest.json                       # the format alone, for a reader of format 1
  *     <name>@<version>.<sha256:32>.zip  # one bundle per quill
- *     store/
- *       <sha256>                      # dehydrated font bytes (full hash, no ext)
+ *     fonts/
+ *       <sha256>                        # dehydrated font bytes (full hash, no ext)
  *
  * A generation is assembled beside outDir and moved in whole, so a reader
  * fetching mid-build reads the previous one rather than a torn tree, and a
@@ -67,7 +69,7 @@ function assertSafeOutDir(path, sourceDir, outDir) {
  *
  * Versions below `MIN_PUBLISHED_VERSION` are drafts and are left out unless
  * `options.drafts` asks for them; a quill with nothing above the floor is
- * absent from the manifest entirely.
+ * absent from `quiver.json` entirely.
  *
  * Throws:
  *   - `quiver_invalid` on source validation failures (propagated from scanner)
@@ -111,14 +113,12 @@ export async function buildQuiver(sourceDir, outDir, options = {}) {
     async function packGeneration() {
         try {
             await rm(stage, { recursive: true, force: true });
-            await mkdir(join(stage, 'store'), { recursive: true });
+            await mkdir(join(stage, 'fonts'), { recursive: true });
         }
         catch (err) {
             throw new QuiverError('transport_error', `Failed to prepare output directory "${outDir}": ${err.message}`, { cause: err });
         }
-        const manifestQuills = [];
-        // Font hashes already in the store. The store is content-addressed, so a font
-        // shared across quills or versions is written once.
+        const quills = [];
         const stored = new Set();
         for (const [quillName, versions] of catalog) {
             for (const version of versions) {
@@ -133,17 +133,22 @@ export async function buildQuiver(sourceDir, outDir, options = {}) {
                         contentRecord[rel] = bytes;
                         continue;
                     }
-                    // Full width: the store is keyed by hash, so two distinct fonts
-                    // sharing a prefix would merge into one entry.
+                    // The loader refuses what does not open as a font, so the build refuses it
+                    // first, where the author it names can do something about it.
+                    if (!isFont(bytes, rel)) {
+                        throw new QuiverError('quiver_invalid', `Quill "${quillName}@${version}": "${rel}" does not open as the font its extension names`, { quiverName: meta.name, version });
+                    }
+                    // Full width: fonts are keyed by hash, so two distinct fonts sharing a
+                    // prefix would merge into one file.
                     const hash = createHash('sha256').update(bytes).digest('hex');
                     fonts[rel] = hash;
                     if (stored.has(hash))
                         continue;
                     try {
-                        await writeFile(join(stage, 'store', hash), bytes);
+                        await writeFile(join(stage, 'fonts', hash), bytes);
                     }
                     catch (err) {
-                        throw new QuiverError('transport_error', `Failed to write font store entry "${join(outDir, 'store', hash)}": ${err.message}`, { cause: err });
+                        throw new QuiverError('transport_error', `Failed to write font "${join(outDir, 'fonts', hash)}": ${err.message}`, { cause: err });
                     }
                     stored.add(hash);
                 }
@@ -168,35 +173,23 @@ export async function buildQuiver(sourceDir, outDir, options = {}) {
                 catch (err) {
                     throw new QuiverError('transport_error', `Failed to write bundle "${join(outDir, bundleName)}": ${err.message}`, { cause: err });
                 }
-                manifestQuills.push({ name: quillName, version, bundle: bundleName, fonts });
+                quills.push({ name: quillName, version, bundle: bundleName, fonts });
             }
         }
-        const manifest = {
-            version: MANIFEST_VERSION,
+        // The format is stamped here and read first, so a client older than the tree says so
+        // rather than misreading it.
+        const index = {
+            format: FORMAT,
             name: meta.name,
             ...(meta.description === undefined ? {} : { description: meta.description }),
-            quills: manifestQuills
+            quills
         };
-        const manifestJson = JSON.stringify(manifest, null, 2);
-        const manifestHash = createHash('sha256')
-            .update(manifestJson)
-            .digest('hex')
-            .slice(0, NAME_DIGEST_LENGTH);
-        const manifestFileName = `manifest.${manifestHash}.json`;
-        try {
-            await writeFile(join(stage, manifestFileName), manifestJson, 'utf-8');
-        }
-        catch (err) {
-            throw new QuiverError('transport_error', `Failed to write manifest "${join(outDir, manifestFileName)}": ${err.message}`, { cause: err });
-        }
-        // The format is stamped here and read first, so a client older than the tree
-        // says so rather than misreading it.
-        const pointer = { format: POINTER_FORMAT, manifest: manifestFileName };
         try {
-            await writeFile(join(stage, 'latest.json'), JSON.stringify(pointer), 'utf-8');
+            await writeFile(join(stage, INDEX), JSON.stringify(index, null, 2), 'utf-8');
+            await writeFile(join(stage, LEGACY_POINTER), JSON.stringify({ format: FORMAT }), 'utf-8');
         }
         catch (err) {
-            throw new QuiverError('transport_error', `Failed to write pointer "${join(outDir, 'latest.json')}": ${err.message}`, { cause: err });
+            throw new QuiverError('transport_error', `Failed to write "${join(outDir, INDEX)}" or its legacy pointer: ${err.message}`, { cause: err });
         }
         // `prev` is cleared first: a rename onto a non-empty directory fails, and the
         // tree left by an interrupted run is one.

package/dist/built-loader.d.ts

@@ -1,33 +1,19 @@
 /**
- * Built-quiver loader: reads a packed artifact through a transport, validates
- * its pointer and manifest, and hands back a Quiver whose loader fetches
- * bundles and fonts on demand, each checked against the digest in its name.
+ * Built-quiver loader: reads `quiver.json` through a reader, validates it, and hands back
+ * a Quiver whose loader reads bundles and fonts on demand.
  *
  * Package-internal, and browser-safe: no static `node:` imports at any level.
  */
 import type { Quiver } from './quiver.js';
 /**
- * Transport abstraction: fetch raw bytes by relative path within the packed
- * artifact. Implemented by HttpTransport (browser + Node) and FsBuiltTransport
- * (Node).
+ * Bytes at an artifact-relative path, under a `fetch` cache mode. `no-cache` is
+ * `quiver.json`'s, the one name read that carries no digest; every other name is read
+ * `force-cache`, and `reload` once a cached answer failed, since a digest in a name
+ * does not stop a host's page from being cached under it.
  */
-export interface BuiltTransport {
-    fetchBytes(relativePath: string, opts: FetchOptions): Promise<Uint8Array>;
-}
-/**
- * `revalidate` marks the one request that must not be answered from a cache:
- * `latest.json`, the only name in the artifact that is not content-addressed.
- * Everything else is safe to cache forever by construction, and a transport over a
- * cache says so itself rather than leaving the fact to a host's headers.
- *
- * `maxBytes` is what the response may weigh, required because only the caller knows what
- * it asked for: a pointer, a bundle and a font carry their own ceilings. A transport
- * holding a stream refuses past it before the bytes are resident; one over a file or a
- * held map ignores it.
- */
-export interface FetchOptions {
-    maxBytes: number;
-    revalidate?: boolean;
-}
-/** Load a build-output quiver via the given transport. */
-export declare function loadBuiltQuiver(transport: BuiltTransport): Promise<Quiver>;
+export type ReadMode = 'no-cache' | 'force-cache' | 'reload';
+export type ArtifactReader = (path: string, mode: ReadMode) => Promise<Uint8Array>;
+export declare function httpReader(base: string): ArtifactReader;
+/** Over bytes the caller holds; a leading `./` or `/` on a key is dropped. */
+export declare function filesReader(files: ReadonlyMap<string, Uint8Array>): ArtifactReader;
+export declare function loadBuiltQuiver(read: ArtifactReader): Promise<Quiver>;