@quillmark/quiver 0.4.0 → 0.5.0

package/PROGRAM.md

@@ -160,7 +160,7 @@ Important implications:
 - No engine quill registry in the JS binding; no `registerQuill`, `hasQuill`, or engine-level `render(doc)` in Quiver’s flow
 - Quiver owns mapping from canonical ref → in-memory tree → `Quill` instance
 - Cache optimization is in-process reuse of `Quill` instances, not registration checks
-- Path-based loading (`quill_from_path`) exists in **other** bindings only; in Node, Quiver reads files and assembles `tree` for `engine.quill(tree)` (see upstream `references/quillmark/docs/integration/javascript/api.md`)
+- Path-based loading (`quill_from_path`) exists in **other** bindings only; in Node, Quiver reads files and assembles `tree` for `engine.quill(tree)` (see the upstream `@quillmark/wasm` JS/WASM API docs)
 
 For advanced dynamic-asset behavior, defer to Quillmark’s JS/WASM docs; the default integration path here is `engine.quill` + `quill.render`.
 
@@ -414,7 +414,7 @@ class QuiverError extends Error {
 
 **No render wrapper.** Callers invoke `quill.render(doc, opts?)` (and `quill.open(doc)` when needed) after `getQuill()`. Quiver never mirrors Quillmark render APIs.
 
-**Internal (not exported):** `QuiverManifest` (runtime shape), `parseQuillRef`, in-flight coalescing state, source-vs-built layout detection.
+**Internal (not exported):** `BuiltManifest` (runtime shape), `parseQuillRef`, in-flight coalescing state, source-vs-built layout detection.
 
 Hot-path flow:
 ```ts
@@ -441,7 +441,7 @@ const result = quill.render(doc, { format: "pdf" });
   test runners wire their own loops against the main API.
 
 **Dependencies:**
-- Peer: `@quillmark/wasm@>=0.59.0-rc.2` with `Quillmark`, `Document.fromMarkdown`, `engine.quill(tree)`, and `quill.render(doc, opts?)` APIs.
+- Peer: `@quillmark/wasm@>=0.59.0` with `Quillmark`, `Document.fromMarkdown`, `engine.quill(tree)`, and `quill.render(doc, opts?)` APIs.
 - Runtime: `fflate ^0.8.2` for zip read/write (Node + browser)
 - Dev-only: `node:crypto` (MD5 hashing in `build()` — never reached at runtime)
 - No test-runner peer dependency; `/testing` uses `node:test` (built-in)
@@ -477,17 +477,6 @@ All V1 planner questions resolved; implementation plan can proceed against the s
 
 ---
 
-## References
-
-Local copies in this repo for `@quillmark/quiver` implementation:
-
-- `references/quillmark-registry/` — prior `@quillmark/registry` source and patterns to mine or replace
-- `references/quillmark/docs/integration/javascript/api.md` — JS/WASM API this package integrates with
-- `references/quillmark/prose/designs/WASM.md` — WASM binding shape
-- `references/quillmark/prose/taskings/quill_render_api.md` — upstream render API overhaul (cross-binding; use the JS/WASM sections for Node)
-
----
-
 ## Success Criteria
 
 - A team can author and validate a Source Quiver locally with fast filesystem loops

package/dist/engine-types.d.ts

@@ -1,18 +1,18 @@
 /**
- * Minimal structural types matching @quillmark/wasm >=0.57.0 (verified against 0.59.0-rc.2).
+ * Minimal structural types matching @quillmark/wasm >=0.59.0.
  *
  * Shape:
  *   class Quillmark { quill(tree: Map<string, Uint8Array>): Quill }
  *   class Quill     { render(doc, opts?): RenderResult; open(doc): RenderSession }
  *
- * Note: as of 0.59.0-rc.2 the first arg to render/open is a `Document` instance
- * (from `Document.fromMarkdown(...)`), not the old `ParsedDocument` interface.
- * Quiver keeps the arg typed as `unknown` so consumers of either shape (and
- * test doubles) satisfy the contract structurally.
+ * The first arg to `render`/`open` is a `Document` instance (from
+ * `Document.fromMarkdown(...)`). Quiver keeps the arg typed as `unknown` so
+ * consumers (and test doubles) satisfy the contract structurally without
+ * importing from @quillmark/wasm.
  *
- * These types are INTERNAL — never re-exported from index.ts. They exist so
- * quiver.ts never imports from @quillmark/wasm directly and so test doubles
- * can satisfy the contract without pulling the real WASM module.
+ * These types are re-exported from `index.ts` so consumers can type their
+ * own engine wrappers / test doubles against them. Quiver itself never
+ * imports from @quillmark/wasm directly.
  *
  * Call-site note: Quiver never invokes `render` or `open` itself; consumers do
  * after `getQuill()`. The loose `unknown` parameter typing is intentional.

package/dist/engine-types.js

@@ -1,18 +1,18 @@
 /**
- * Minimal structural types matching @quillmark/wasm >=0.57.0 (verified against 0.59.0-rc.2).
+ * Minimal structural types matching @quillmark/wasm >=0.59.0.
  *
  * Shape:
  *   class Quillmark { quill(tree: Map<string, Uint8Array>): Quill }
  *   class Quill     { render(doc, opts?): RenderResult; open(doc): RenderSession }
  *
- * Note: as of 0.59.0-rc.2 the first arg to render/open is a `Document` instance
- * (from `Document.fromMarkdown(...)`), not the old `ParsedDocument` interface.
- * Quiver keeps the arg typed as `unknown` so consumers of either shape (and
- * test doubles) satisfy the contract structurally.
+ * The first arg to `render`/`open` is a `Document` instance (from
+ * `Document.fromMarkdown(...)`). Quiver keeps the arg typed as `unknown` so
+ * consumers (and test doubles) satisfy the contract structurally without
+ * importing from @quillmark/wasm.
  *
- * These types are INTERNAL — never re-exported from index.ts. They exist so
- * quiver.ts never imports from @quillmark/wasm directly and so test doubles
- * can satisfy the contract without pulling the real WASM module.
+ * These types are re-exported from `index.ts` so consumers can type their
+ * own engine wrappers / test doubles against them. Quiver itself never
+ * imports from @quillmark/wasm directly.
  *
  * Call-site note: Quiver never invokes `render` or `open` itself; consumers do
  * after `getQuill()`. The loose `unknown` parameter typing is intentional.

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.d.ts

@@ -9,7 +9,7 @@
  *
  *   import { Quillmark } from "@quillmark/wasm";
  *   import { runQuiverTests } from "@quillmark/quiver/testing";
- *   const engine = await Quillmark.load();
+ *   const engine = new Quillmark();
  *   runQuiverTests(import.meta.url, engine);
  *
  * Run with `node --test`.

package/dist/testing.js

@@ -9,13 +9,16 @@
  *
  *   import { Quillmark } from "@quillmark/wasm";
  *   import { runQuiverTests } from "@quillmark/quiver/testing";
- *   const engine = await Quillmark.load();
+ *   const engine = new Quillmark();
  *   runQuiverTests(import.meta.url, engine);
  *
  * 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.0",
+  "version": "0.5.0",
   "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`);
-    }
-}