@quillmark/quiver 0.4.1 → 0.5.1

package/README.md

@@ -19,8 +19,8 @@ an npm package. Consumers decide how to consume it:
   output as static assets, loading it with `Quiver.fromBuilt`.
 
 Each loader names exactly what it loads: `fromPackage` and `fromDir` always
-read source layouts; `fromBuilt` always reads build output over HTTP/HTTPS.
-No auto-detection, no branching on artifact shape.
+read source layouts; `fromBuilt` always reads build output over an HTTP(S)
+or origin-relative URL. No auto-detection, no branching on artifact shape.
 
 This keeps the author flow to a single command (`npm publish` or `git tag`)
 and puts the deployment-topology decision where it belongs: with the
@@ -115,10 +115,12 @@ const quiver = await Quiver.fromBuilt("https://cdn.example.com/quivers/my-quiver
 await quiver.warm();
 ```
 
-`warm()` is network-only: it fetches every quill's tree and caches them.
-It does not require an engine and does not materialize Quill instances —
-that happens lazily on the first `getQuill` call, which is microseconds.
-A subsequent `getQuill` reuses the cached tree, skipping the fetch.
+`warm()` is I/O-only: it loads every quill's tree (over the network for
+`fromBuilt`, off the filesystem for `fromPackage`/`fromDir`) and caches
+them. It does not require an engine and does not materialize Quill
+instances — that happens lazily on the first `getQuill` call, which is
+microseconds. A subsequent `getQuill` reuses the cached tree, skipping
+the load.
 
 Once a tree has been turned into a Quill, the cached tree is dropped so
 its bytes can be GC'd — the materialized Quill is the runtime artifact.

package/dist/bundle.js

@@ -4,9 +4,15 @@
 import { zipSync, unzipSync } from "fflate";
 /**
  * Fixed epoch mtime for deterministic zip output.
- * All entries get this timestamp so byte-identical inputs → byte-identical zips.
+ *
+ * fflate reads mtime via local-time getters (getFullYear/getMonth/...) and rejects
+ * years before 1980. Date.UTC(1980, 0, 1) becomes 1979-12-31 in any TZ west of UTC,
+ * which both crashes the encoder and (where it doesn't crash) produces TZ-dependent
+ * bytes. Using the local-time constructor anchors the components to 1980-01-01
+ * 00:00:00 in *every* timezone, so the DOS timestamp written into the zip header
+ * is always identical.
  */
-const ZIP_EPOCH = new Date(Date.UTC(1980, 0, 1));
+const ZIP_EPOCH = new Date(1980, 0, 1, 0, 0, 0, 0);
 /**
  * Pack a flat file map into a deterministic zip.
  * Keys are sorted before zipping so insertion order doesn't affect output.

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 export { QuiverError } from "./errors.js";
 export type { QuiverErrorCode } from "./errors.js";
 export { Quiver } from "./quiver.js";
-export type { BuildOptions } from "./build.js";
 export type { QuillmarkLike, QuillLike } from "./engine-types.js";

package/dist/index.js

@@ -1,3 +1,7 @@
 // Main browser-safe entrypoint.
+//
+// Exposes only browser-safe surface. Node-only factories
+// (`Quiver.fromDir`, `fromPackage`, `build`) and the `BuildOptions` type
+// live at `@quillmark/quiver/node`.
 export { QuiverError } from "./errors.js";
 export { Quiver } from "./quiver.js";

package/dist/node.d.ts

@@ -1 +1,57 @@
-export * from "./index.js";
+/**
+ * Node-only entrypoint.
+ *
+ * Importing this module is the consumer's explicit declaration of intent:
+ * "I am running in Node and want the Node-only Quiver factories." It exposes
+ * the same `Quiver` class as the main entry, augmented with `fromDir`,
+ * `fromPackage`, and `build` static methods.
+ *
+ * Side effect: at module evaluation time, the Node-only static methods are
+ * installed on the shared `Quiver` constructor. Any other module that already
+ * imports `Quiver` from the main entry will see the additional methods at
+ * runtime — but TypeScript will only expose them on the binding imported from
+ * here, so the import path remains the contract.
+ *
+ * Bundler note: importing this entry pulls in `./source-loader.js` and
+ * `./build.js`, both of which statically import `node:*` builtins. Browser
+ * bundles must never reach this module. The main entry (`./index.js`) makes
+ * no static or dynamic reference to it.
+ */
+import { Quiver as Base } from "./quiver.js";
+import { type BuildOptions } from "./build.js";
+type NodeQuiverStatics = {
+    /**
+     * Resolves an npm specifier against `node_modules` and loads the source
+     * layout at the package root. The resolved package must have `Quiver.yaml`
+     * at its root.
+     *
+     * Throws `transport_error` on resolution/I/O failure, `quiver_invalid` on
+     * schema violations.
+     */
+    fromPackage(specifier: string): Promise<Base>;
+    /**
+     * Reads a Source Quiver from a local directory containing `Quiver.yaml`
+     * and `quills/<name>/<version>/Quill.yaml` entries.
+     *
+     * Also accepts `import.meta.url`-style `file://` URLs as a convenience for
+     * tests; the URL's parent directory is used as the source root.
+     *
+     * Throws `quiver_invalid` on schema violations, `transport_error` on I/O
+     * failure.
+     */
+    fromDir(pathOrFileUrl: string): Promise<Base>;
+    /**
+     * Reads the Source Quiver at sourceDir, validates it, and writes the
+     * runtime build artifact to outDir.
+     *
+     * Throws `quiver_invalid` on source validation failures, `transport_error`
+     * on I/O failures.
+     */
+    build(sourceDir: string, outDir: string, opts?: BuildOptions): Promise<void>;
+};
+export type Quiver = Base;
+export declare const Quiver: typeof Base & NodeQuiverStatics;
+export { QuiverError } from "./errors.js";
+export type { QuiverErrorCode } from "./errors.js";
+export type { BuildOptions } from "./build.js";
+export type { QuillmarkLike, QuillLike } from "./engine-types.js";

package/dist/node.js

@@ -1,5 +1,55 @@
-// Node-only entrypoint.
-// Re-export everything from the main browser-safe entrypoint.
-// Node-only factories (fromPackage, fromDir, build) are methods on
-// Quiver itself — no additional exports are needed here.
-export * from "./index.js";
+/**
+ * Node-only entrypoint.
+ *
+ * Importing this module is the consumer's explicit declaration of intent:
+ * "I am running in Node and want the Node-only Quiver factories." It exposes
+ * the same `Quiver` class as the main entry, augmented with `fromDir`,
+ * `fromPackage`, and `build` static methods.
+ *
+ * Side effect: at module evaluation time, the Node-only static methods are
+ * installed on the shared `Quiver` constructor. Any other module that already
+ * imports `Quiver` from the main entry will see the additional methods at
+ * runtime — but TypeScript will only expose them on the binding imported from
+ * here, so the import path remains the contract.
+ *
+ * Bundler note: importing this entry pulls in `./source-loader.js` and
+ * `./build.js`, both of which statically import `node:*` builtins. Browser
+ * bundles must never reach this module. The main entry (`./index.js`) makes
+ * no static or dynamic reference to it.
+ */
+import { Quiver as Base } from "./quiver.js";
+import { QuiverError } from "./errors.js";
+import { scanSourceQuiver, SourceLoader } from "./source-loader.js";
+import { buildQuiver } from "./build.js";
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+export const Quiver = Base;
+// ---------------------------------------------------------------------------
+// 2. Runtime patch — install Node-only statics on the shared class.
+// ---------------------------------------------------------------------------
+Quiver.fromDir = async function fromDir(pathOrFileUrl) {
+    const dir = pathOrFileUrl.startsWith("file://")
+        ? fileURLToPath(new URL(".", pathOrFileUrl))
+        : pathOrFileUrl;
+    const { meta, catalog } = await scanSourceQuiver(dir);
+    return Base._fromLoader(meta.name, catalog, new SourceLoader(dir));
+};
+Quiver.fromPackage = async function fromPackage(specifier) {
+    const req = createRequire(import.meta.url);
+    let yamlPath;
+    try {
+        yamlPath = req.resolve(`${specifier}/Quiver.yaml`);
+    }
+    catch (err) {
+        throw new QuiverError("transport_error", `Failed to resolve quiver package "${specifier}": ${err.message}`, { cause: err });
+    }
+    return Quiver.fromDir(dirname(yamlPath));
+};
+Quiver.build = async function build(sourceDir, outDir, opts) {
+    return buildQuiver(sourceDir, outDir, opts);
+};
+// ---------------------------------------------------------------------------
+// 3. Re-export the rest of the public surface so consumers get one import.
+// ---------------------------------------------------------------------------
+export { QuiverError } from "./errors.js";

package/dist/quiver.d.ts

@@ -3,8 +3,12 @@
  *
  * Polymorphism via composition: internally stores a pluggable loader
  * (either source-backed or build-output-backed).
+ *
+ * This module is browser-safe: only `fromBuilt` and the instance API live
+ * here. Node-only factories (`fromDir`, `fromPackage`, `build`) are installed
+ * on this class by `./node.js`, which is the consumer's explicit opt-in to
+ * the Node API surface.
  */
-import type { BuildOptions } from "./build.js";
 import type { QuillmarkLike, QuillLike } from "./engine-types.js";
 /** @internal Internal loader strategy: source or build output. */
 export interface QuiverLoader {
@@ -14,33 +18,18 @@ export declare class Quiver {
     #private;
     readonly name: string;
     /**
-     * Private constructor — use static factory methods.
-     * TS prevents external `new Quiver(...)` at compile time.
-     * Static methods inside can still call it.
+     * Private constructor — use static factory methods (`Quiver.fromBuilt`, or
+     * the Node-only `Quiver.fromDir` / `Quiver.fromPackage` installed by
+     * `@quillmark/quiver/node`). TS prevents external `new Quiver(...)` at
+     * compile time.
      */
     private constructor();
-    /** @internal Used by loadBuiltQuiver. Not part of the public API. */
-    static _fromLoader(name: string, catalog: Map<string, string[]>, loader: QuiverLoader): Quiver;
     /**
-     * Node-only factory. Resolves an npm specifier against `node_modules` and
-     * loads the source layout at the package root.
-     *
-     * The resolved package must have `Quiver.yaml` at its root.
-     *
-     * Throws `transport_error` on resolution/I/O failure, `quiver_invalid`
-     * on schema violations.
+     * @internal Construction escape hatch around the private constructor. Used
+     * by `loadBuiltQuiver` and by the Node entry (`./node.js`) when installing
+     * `fromDir` / `fromPackage`. Not part of the public API.
      */
-    static fromPackage(specifier: string): Promise<Quiver>;
-    /**
-     * Node-only factory. Reads a Source Quiver from a local directory containing
-     * `Quiver.yaml` and `quills/<name>/<version>/Quill.yaml` entries.
-     *
-     * Also accepts `import.meta.url`-style `file://` URLs as a convenience for
-     * tests; the URL's parent directory is used as the source root.
-     *
-     * Throws `quiver_invalid` on schema violations, `transport_error` on I/O failure.
-     */
-    static fromDir(pathOrFileUrl: string): Promise<Quiver>;
+    static _fromLoader(name: string, catalog: Map<string, string[]>, loader: QuiverLoader): Quiver;
     /**
      * Browser-safe factory. Loads build output from an HTTP/HTTPS URL.
      *
@@ -60,17 +49,6 @@ export declare class Quiver {
      * Returns an empty array if the quill name is not in the catalog.
      */
     versionsOf(name: string): string[];
-    /**
-     * Node-only tooling. Reads the Source Quiver at sourceDir, validates it,
-     * and writes the runtime build artifact to outDir.
-     *
-     * Uses dynamic import of `./build.js` so that this module stays
-     * browser-safe at evaluation time.
-     *
-     * Throws `quiver_invalid` on source validation failures,
-     * `transport_error` on I/O failures.
-     */
-    static build(sourceDir: string, outDir: string, opts?: BuildOptions): Promise<void>;
     /**
      * Lazily loads the file tree for a specific quill version.
      *

package/dist/quiver.js

@@ -3,9 +3,13 @@
  *
  * Polymorphism via composition: internally stores a pluggable loader
  * (either source-backed or build-output-backed).
+ *
+ * This module is browser-safe: only `fromBuilt` and the instance API live
+ * here. Node-only factories (`fromDir`, `fromPackage`, `build`) are installed
+ * on this class by `./node.js`, which is the consumer's explicit opt-in to
+ * the Node API surface.
  */
 import { QuiverError } from "./errors.js";
-import { assertNode } from "./assert-node.js";
 import { parseQuillRef } from "./ref.js";
 import { matchesSemverSelector, chooseHighestVersion } from "./semver.js";
 export class Quiver {
@@ -25,62 +29,23 @@ export class Quiver {
      */
     #treeCache = new Map();
     /**
-     * Private constructor — use static factory methods.
-     * TS prevents external `new Quiver(...)` at compile time.
-     * Static methods inside can still call it.
+     * Private constructor — use static factory methods (`Quiver.fromBuilt`, or
+     * the Node-only `Quiver.fromDir` / `Quiver.fromPackage` installed by
+     * `@quillmark/quiver/node`). TS prevents external `new Quiver(...)` at
+     * compile time.
      */
     constructor(name, catalog, loader) {
         this.name = name;
         this.#catalog = new Map(catalog);
         this.#loader = loader;
     }
-    /** @internal Used by loadBuiltQuiver. Not part of the public API. */
-    static _fromLoader(name, catalog, loader) {
-        return new Quiver(name, catalog, loader);
-    }
     /**
-     * Node-only factory. Resolves an npm specifier against `node_modules` and
-     * loads the source layout at the package root.
-     *
-     * The resolved package must have `Quiver.yaml` at its root.
-     *
-     * Throws `transport_error` on resolution/I/O failure, `quiver_invalid`
-     * on schema violations.
+     * @internal Construction escape hatch around the private constructor. Used
+     * by `loadBuiltQuiver` and by the Node entry (`./node.js`) when installing
+     * `fromDir` / `fromPackage`. Not part of the public API.
      */
-    static async fromPackage(specifier) {
-        assertNode("Quiver.fromPackage");
-        const { createRequire } = await import("node:module");
-        const { dirname } = await import("node:path");
-        const req = createRequire(import.meta.url);
-        let yamlPath;
-        try {
-            yamlPath = req.resolve(`${specifier}/Quiver.yaml`);
-        }
-        catch (err) {
-            throw new QuiverError("transport_error", `Failed to resolve quiver package "${specifier}": ${err.message}`, { cause: err });
-        }
-        return Quiver.fromDir(dirname(yamlPath));
-    }
-    /**
-     * Node-only factory. Reads a Source Quiver from a local directory containing
-     * `Quiver.yaml` and `quills/<name>/<version>/Quill.yaml` entries.
-     *
-     * Also accepts `import.meta.url`-style `file://` URLs as a convenience for
-     * tests; the URL's parent directory is used as the source root.
-     *
-     * Throws `quiver_invalid` on schema violations, `transport_error` on I/O failure.
-     */
-    static async fromDir(pathOrFileUrl) {
-        assertNode("Quiver.fromDir");
-        let dir = pathOrFileUrl;
-        if (pathOrFileUrl.startsWith("file://")) {
-            const { fileURLToPath } = await import("node:url");
-            dir = fileURLToPath(new URL(".", pathOrFileUrl));
-        }
-        const { scanSourceQuiver, SourceLoader } = await import("./source-loader.js");
-        const { meta, catalog } = await scanSourceQuiver(dir);
-        const loader = new SourceLoader(dir);
-        return new Quiver(meta.name, catalog, loader);
+    static _fromLoader(name, catalog, loader) {
+        return new Quiver(name, catalog, loader);
     }
     /**
      * Browser-safe factory. Loads build output from an HTTP/HTTPS URL.
@@ -113,21 +78,6 @@ export class Quiver {
     versionsOf(name) {
         return [...(this.#catalog.get(name) ?? [])];
     }
-    /**
-     * Node-only tooling. Reads the Source Quiver at sourceDir, validates it,
-     * and writes the runtime build artifact to outDir.
-     *
-     * Uses dynamic import of `./build.js` so that this module stays
-     * browser-safe at evaluation time.
-     *
-     * Throws `quiver_invalid` on source validation failures,
-     * `transport_error` on I/O failures.
-     */
-    static async build(sourceDir, outDir, opts) {
-        assertNode("Quiver.build");
-        const { buildQuiver } = await import("./build.js");
-        return buildQuiver(sourceDir, outDir, opts);
-    }
     /**
      * Lazily loads the file tree for a specific quill version.
      *

package/dist/testing.js

@@ -15,7 +15,10 @@
  * Run with `node --test`.
  */
 import { describe, it, before } from "node:test";
-import { Quiver } from "./quiver.js";
+// Import from the Node entry: this installs the runtime patch so
+// `Quiver.fromDir` is callable at runtime, and gives us the augmented
+// static-method type signature.
+import { Quiver } from "./node.js";
 /**
  * Registers a `node:test` describe block that validates every quill
  * version in the quiver at `metaUrlOrDir` against the provided engine.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/quiver",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Quiver registry and build tooling for Quillmark",
   "type": "module",
   "license": "MIT",
@@ -36,6 +36,10 @@
       "import": "./dist/testing.js"
     }
   },
+  "sideEffects": [
+    "./dist/node.js",
+    "./dist/testing.js"
+  ],
   "files": [
     "dist",
     "PROGRAM.md",

package/dist/assert-node.d.ts

@@ -1,5 +0,0 @@
-/**
- * Throws a `transport_error` when called outside a Node.js environment.
- * Call at the top of each Node-only static factory to fail fast in browsers.
- */
-export declare function assertNode(method: string): void;

package/dist/assert-node.js

@@ -1,12 +0,0 @@
-import { QuiverError } from "./errors.js";
-/**
- * Throws a `transport_error` when called outside a Node.js environment.
- * Call at the top of each Node-only static factory to fail fast in browsers.
- */
-export function assertNode(method) {
-    if (typeof globalThis.process === "undefined" ||
-        !globalThis.process
-            ?.versions?.node) {
-        throw new QuiverError("transport_error", `${method} is only available in Node.js`);
-    }
-}