@quillmark/quiver 0.29.0 → 0.30.0

package/dist/quiver.d.ts

@@ -36,33 +36,20 @@ export declare class Quiver {
      * environments. `file://` URLs are rejected — to load build output from
      * disk in Node, use `fromBuiltDir(path)` from `@quillmark/quiver/node`.
      *
-     * `seed` answers for the artifact bytes the caller already holds, keyed by
-     * artifact-relative path; the URL serves the rest. Seeding `latest.json`
-     * settles which catalog this process reads at deploy time rather than at
-     * cache-revalidation time. Seeded bytes are digest-checked as fetched ones
-     * are.
-     *
      * Throws `transport_error` on network/HTTP failure, `quiver_invalid`
      * on format errors.
      */
-    static fromBuiltUrl(url: string, opts?: {
-        seed?: ReadonlyMap<string, Uint8Array>;
-    }): Promise<Quiver>;
+    static fromBuiltUrl(url: string): Promise<Quiver>;
     /**
      * Browser-safe factory. Loads build output from the bytes themselves, keyed
-     * by artifact-relative path (`latest.json`, `manifest.<digest>.json`,
-     * `<name>@<x.y.z>.<digest>.zip`, `store/<hash>`) — the shape `build` writes
-     * and `fromBuiltDir` reads back.
+     * by artifact-relative path (`quiver.json`, `<name>@<x.y.z>.<digest>.zip`,
+     * `fonts/<hash>`) — the shape `build` writes and `fromBuiltDir` reads back.
      *
      * Nothing is fetched, so a runtime whose artifact is not on a path it can
      * read (a serverless function, a bundler that inlines it, a test) reaches
      * one without fetching its own static output back over its own load
      * balancer.
      *
-     * The map must carry the whole artifact; a missing path is a
-     * `transport_error` naming it. To hold part and fetch the rest, pass the map
-     * as `fromBuiltUrl`'s `seed`.
-     *
      * Throws `quiver_invalid` on format errors, `transport_error` on a path the
      * map does not carry.
      */

package/dist/quiver.js

@@ -51,49 +51,32 @@ export class Quiver {
      * environments. `file://` URLs are rejected — to load build output from
      * disk in Node, use `fromBuiltDir(path)` from `@quillmark/quiver/node`.
      *
-     * `seed` answers for the artifact bytes the caller already holds, keyed by
-     * artifact-relative path; the URL serves the rest. Seeding `latest.json`
-     * settles which catalog this process reads at deploy time rather than at
-     * cache-revalidation time. Seeded bytes are digest-checked as fetched ones
-     * are.
-     *
      * Throws `transport_error` on network/HTTP failure, `quiver_invalid`
      * on format errors.
      */
-    static async fromBuiltUrl(url, opts) {
+    static async fromBuiltUrl(url) {
         if (url.startsWith('file://')) {
             throw new QuiverError('transport_error', `Quiver.fromBuiltUrl requires an http(s):// or origin-relative URL; got "${url}". For local build output, use import { fromBuiltDir } from '@quillmark/quiver/node'.`);
         }
-        const { HttpTransport } = await import('./transports/http-transport.js');
-        const { loadBuiltQuiver } = await import('./built-loader.js');
-        const http = new HttpTransport(url);
-        if (opts?.seed === undefined)
-            return loadBuiltQuiver(http);
-        const { MemoryTransport } = await import('./transports/memory-transport.js');
-        return loadBuiltQuiver(new MemoryTransport(opts.seed, http));
+        const { httpReader, loadBuiltQuiver } = await import('./built-loader.js');
+        return loadBuiltQuiver(httpReader(url));
     }
     /**
      * Browser-safe factory. Loads build output from the bytes themselves, keyed
-     * by artifact-relative path (`latest.json`, `manifest.<digest>.json`,
-     * `<name>@<x.y.z>.<digest>.zip`, `store/<hash>`) — the shape `build` writes
-     * and `fromBuiltDir` reads back.
+     * by artifact-relative path (`quiver.json`, `<name>@<x.y.z>.<digest>.zip`,
+     * `fonts/<hash>`) — the shape `build` writes and `fromBuiltDir` reads back.
      *
      * Nothing is fetched, so a runtime whose artifact is not on a path it can
      * read (a serverless function, a bundler that inlines it, a test) reaches
      * one without fetching its own static output back over its own load
      * balancer.
      *
-     * The map must carry the whole artifact; a missing path is a
-     * `transport_error` naming it. To hold part and fetch the rest, pass the map
-     * as `fromBuiltUrl`'s `seed`.
-     *
      * Throws `quiver_invalid` on format errors, `transport_error` on a path the
      * map does not carry.
      */
     static async fromBuiltFiles(files) {
-        const { MemoryTransport } = await import('./transports/memory-transport.js');
-        const { loadBuiltQuiver } = await import('./built-loader.js');
-        return loadBuiltQuiver(new MemoryTransport(files));
+        const { filesReader, loadBuiltQuiver } = await import('./built-loader.js');
+        return loadBuiltQuiver(filesReader(files));
     }
     /** Returns all known quill names, sorted lexicographically. */
     quillNames() {

package/dist/signature.d.ts

@@ -0,0 +1,6 @@
+/**
+ * TrueType, OpenType or a collection of either; WOFF or WOFF2 where `path` names one.
+ * The engine parses sfnt alone, so a `.ttf` holding WOFF bytes is refused.
+ */
+export declare const isFont: (bytes: Uint8Array, path: string) => boolean;
+export declare const isZip: (bytes: Uint8Array) => boolean;

package/dist/signature.js

@@ -0,0 +1,13 @@
+/**
+ * The leading bytes of what an artifact holds. A host answering a missing name with a
+ * page of its own answers 200, and nothing else read here tells that page from a font.
+ */
+const SFNT = ['\0\x01\0\0', 'OTTO', 'true', 'ttcf'];
+const WOFF = ['wOFF', 'wOF2'];
+const opens = (bytes, magic) => bytes.length >= magic.length && [...magic].every((c, i) => bytes[i] === c.charCodeAt(0));
+/**
+ * TrueType, OpenType or a collection of either; WOFF or WOFF2 where `path` names one.
+ * The engine parses sfnt alone, so a `.ttf` holding WOFF bytes is refused.
+ */
+export const isFont = (bytes, path) => (/\.woff2?$/i.test(path) ? WOFF : SFNT).some((magic) => opens(bytes, magic));
+export const isZip = (bytes) => opens(bytes, 'PK\x03\x04');

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quillmark/quiver",
-	"version": "0.29.0",
+	"version": "0.30.0",
 	"description": "A quiver of Quillmark quills: load one, pack one, hand out quills.",
 	"type": "module",
 	"license": "Apache-2.0",
@@ -42,7 +42,7 @@
 		"NOTICE"
 	],
 	"peerDependencies": {
-		"@quillmark/wasm": ">=0.115.0-0"
+		"@quillmark/wasm": ">=0.116.0-0"
 	},
 	"dependencies": {
 		"fflate": "^0.8.2",

package/dist/digest.d.ts

@@ -1,23 +0,0 @@
-/**
- * Content addressing. Browser-safe.
- *
- * `crypto.subtle` is the one digest primitive a browser and Node both expose,
- * and it exists only in a secure context: a page served over plain `http://`
- * to something other than localhost has no digest at all. Verification
- * degrades to a no-op there rather than failing every fetch, so `undefined`
- * means "cannot check", never "check failed". Node and any https page always
- * have one.
- */
-/**
- * Digest width in the names `build` writes, in hex chars: 128 bits of SHA-256.
- *
- * The width answers a chosen prefix, not a collision. Where the manifest is trusted
- * and the bundles are not — the seeded deployment, where the two come from different
- * places by design — this is the only thing between a served zip and the quill it
- * claims to be, and a quill is a template the backend executes. Grinding padding until
- * SHA-256 lands on a chosen prefix costs hours of one GPU at 48 bits and is out of
- * reach at 128.
- */
-export declare const NAME_DIGEST_LENGTH = 32;
-/** SHA-256 over `bytes` as lowercase hex, or undefined where no digest exists. */
-export declare function sha256Hex(bytes: Uint8Array): Promise<string | undefined>;

package/dist/digest.js

@@ -1,29 +0,0 @@
-/**
- * Content addressing. Browser-safe.
- *
- * `crypto.subtle` is the one digest primitive a browser and Node both expose,
- * and it exists only in a secure context: a page served over plain `http://`
- * to something other than localhost has no digest at all. Verification
- * degrades to a no-op there rather than failing every fetch, so `undefined`
- * means "cannot check", never "check failed". Node and any https page always
- * have one.
- */
-/**
- * Digest width in the names `build` writes, in hex chars: 128 bits of SHA-256.
- *
- * The width answers a chosen prefix, not a collision. Where the manifest is trusted
- * and the bundles are not — the seeded deployment, where the two come from different
- * places by design — this is the only thing between a served zip and the quill it
- * claims to be, and a quill is a template the backend executes. Grinding padding until
- * SHA-256 lands on a chosen prefix costs hours of one GPU at 48 bits and is out of
- * reach at 128.
- */
-export const NAME_DIGEST_LENGTH = 32;
-/** SHA-256 over `bytes` as lowercase hex, or undefined where no digest exists. */
-export async function sha256Hex(bytes) {
-    const subtle = globalThis.crypto?.subtle;
-    if (subtle === undefined)
-        return undefined;
-    const digest = await subtle.digest('SHA-256', bytes);
-    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
-}

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

@@ -1,14 +0,0 @@
-/**
- * FsBuiltTransport — Node-only built-quiver transport that reads packed
- * artifacts from the local filesystem.
- * Internal; not exported from index.ts.
- *
- * Static `node:*` imports — this module must never be reached from browser
- * bundles. It is loaded lazily by `fromBuiltDir` in `./node.js`.
- */
-import type { BuiltTransport } from '../built-loader.js';
-export declare class FsBuiltTransport implements BuiltTransport {
-    private readonly rootDir;
-    constructor(rootDir: string);
-    fetchBytes(relativePath: string): Promise<Uint8Array>;
-}

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

@@ -1,36 +0,0 @@
-/**
- * FsBuiltTransport — Node-only built-quiver transport that reads packed
- * artifacts from the local filesystem.
- * Internal; not exported from index.ts.
- *
- * Static `node:*` imports — this module must never be reached from browser
- * 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';
-export class FsBuiltTransport {
-    rootDir;
-    constructor(rootDir) {
-        this.rootDir = rootDir;
-    }
-    // No cache sits between this and the bytes, and a file is read at the size it
-    // is, 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}"`);
-        }
-        const normalized = normalize(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 {
-            const buf = await readFile(filePath);
-            return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
-        }
-        catch (err) {
-            throw new QuiverError('transport_error', `Failed to read "${filePath}": ${err.message}`, { cause: err });
-        }
-    }
-}

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

@@ -1,12 +0,0 @@
-/**
- * HttpTransport — browser-safe built-quiver transport that fetches via HTTP.
- * Internal; not exported from index.ts.
- *
- * Uses globalThis.fetch — no node: imports at any level.
- */
-import type { BuiltTransport, FetchOptions } from '../built-loader.js';
-export declare class HttpTransport implements BuiltTransport {
-    private readonly baseUrl;
-    constructor(baseUrl: string);
-    fetchBytes(relativePath: string, opts: FetchOptions): Promise<Uint8Array>;
-}

package/dist/transports/http-transport.js

@@ -1,87 +0,0 @@
-/**
- * HttpTransport — browser-safe built-quiver transport that fetches via HTTP.
- * Internal; not exported from index.ts.
- *
- * Uses globalThis.fetch — no node: imports at any level.
- */
-import { QuiverError } from '../errors.js';
-/** Over the ceiling is `quiver_invalid`, not `transport_error`: a retry fetches the same
- *  response, so there is nothing for an evicting cache to fix. */
-function oversized(url, max, says) {
-    return new QuiverError('quiver_invalid', `"${url}" ${says} the ${max} bytes a fetch may read`);
-}
-/** The body chunk by chunk, refused past the ceiling. Cancelling the reader terminates
- *  the fetch, so nothing more of a refused response is pulled off the socket. */
-async function readCapped(body, url, max) {
-    const reader = body.getReader();
-    const chunks = [];
-    let total = 0;
-    for (;;) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        total += value.byteLength;
-        if (total > max) {
-            await reader.cancel();
-            throw oversized(url, max, 'is over');
-        }
-        chunks.push(value);
-    }
-    const bytes = new Uint8Array(total);
-    let at = 0;
-    for (const chunk of chunks) {
-        bytes.set(chunk, at);
-        at += chunk.byteLength;
-    }
-    return bytes;
-}
-export class HttpTransport {
-    baseUrl;
-    constructor(baseUrl) {
-        this.baseUrl = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
-    }
-    async fetchBytes(relativePath, opts) {
-        const cleanPath = relativePath.startsWith('/') ? relativePath.slice(1) : relativePath;
-        const url = `${this.baseUrl}${cleanPath}`;
-        let response;
-        try {
-            // `no-cache` revalidates with the origin rather than skipping the cache: a 304
-            // still serves from disk. `force-cache` takes a cached response whatever its
-            // age, which a digest-carrying name is entitled to; a stale one fails
-            // verification upstream as `transport_error`, which an evicting cache clears.
-            response = await globalThis.fetch(url, {
-                cache: opts.revalidate ? 'no-cache' : 'force-cache'
-            });
-        }
-        catch (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}"`);
-        }
-        // A fast reject; the running total below is what holds the ceiling. `Content-Length`
-        // is the encoded length, so under `Content-Encoding` it under-reports; a missing one is
-        // 0 and an unparseable one NaN, neither over the ceiling, so both accept early.
-        const declared = Number(response.headers.get('content-length'));
-        if (declared > opts.maxBytes) {
-            throw oversized(url, opts.maxBytes, `states ${declared} bytes, over`);
-        }
-        try {
-            // A host that hands back no stream is measured after the fact rather than
-            // refused: the degraded check still bounds what reaches the unpack budget,
-            // and refusing outright would cost hosts that work today.
-            if (response.body === null) {
-                const buffer = await response.arrayBuffer();
-                if (buffer.byteLength > opts.maxBytes)
-                    throw oversized(url, opts.maxBytes, 'is over');
-                return new Uint8Array(buffer);
-            }
-            return await readCapped(response.body, url, opts.maxBytes);
-        }
-        catch (err) {
-            if (err instanceof QuiverError)
-                throw err;
-            throw new QuiverError('transport_error', `Network error reading "${url}": ${err.message}`, { cause: err });
-        }
-    }
-}

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

@@ -1,16 +0,0 @@
-/**
- * MemoryTransport — built-quiver transport over bytes the caller already holds,
- * falling through to another transport for what the map does not carry.
- * Internal; not exported from index.ts.
- *
- * Browser-safe: no `node:` imports at any level.
- */
-import type { BuiltTransport, FetchOptions } from '../built-loader.js';
-export declare class MemoryTransport implements BuiltTransport {
-    private readonly fallback?;
-    private readonly files;
-    constructor(files: ReadonlyMap<string, Uint8Array>, fallback?: BuiltTransport | undefined);
-    /** The map answers first. `FetchOptions` reaches only the fallback: a held byte has no
-     *  cache to revalidate against and no arrival to refuse. */
-    fetchBytes(relativePath: string, opts: FetchOptions): Promise<Uint8Array>;
-}

package/dist/transports/memory-transport.js

@@ -1,35 +0,0 @@
-/**
- * MemoryTransport — built-quiver transport over bytes the caller already holds,
- * falling through to another transport for what the map does not carry.
- * Internal; not exported from index.ts.
- *
- * Browser-safe: no `node:` imports at any level.
- */
-import { QuiverError } from '../errors.js';
-/** Keys are artifact-relative, as the loader asks for them; a leading `./` or `/` is stripped. */
-function normalizeKeys(files) {
-    const out = new Map();
-    for (const [key, bytes] of files) {
-        out.set(key.replace(/^\.?\//, ''), bytes);
-    }
-    return out;
-}
-export class MemoryTransport {
-    fallback;
-    files;
-    constructor(files, fallback) {
-        this.fallback = fallback;
-        this.files = normalizeKeys(files);
-    }
-    /** The map answers first. `FetchOptions` reaches only the fallback: a held byte has no
-     *  cache to revalidate against and no arrival to refuse. */
-    async fetchBytes(relativePath, opts) {
-        const bytes = this.files.get(relativePath);
-        if (bytes !== undefined)
-            return bytes;
-        if (this.fallback === undefined) {
-            throw new QuiverError('transport_error', `No bytes held for "${relativePath}". Quiver.fromBuiltFiles needs the whole artifact; to hold part and fetch the rest, pass the map as Quiver.fromBuiltUrl's \`seed\`.`);
-        }
-        return this.fallback.fetchBytes(relativePath, opts);
-    }
-}