@quillmark/quiver 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/PROGRAM.md

@@ -0,0 +1,420 @@
+# Program: Quivers Rewrite (`@quillmark/quiver`)
+
+**Status:** Updated for upstream Quillmark Render API overhaul  
+**Audience:** Senior engineer planning and executing V1  
+**Scope:** This document applies only to the **Node/npm** package **`@quillmark/quiver`**: a smaller surface than `@quillmark/registry`, aligned with the **JavaScript/WASM** Quillmark bindings (not Python or other language bindings).
+
+## Summary
+
+V1 still introduces Quivers as the primary runtime abstraction, but one boundary changed materially upstream:
+
+- Quillmark no longer owns a quill registry
+- Rendering lives on `Quill` (`quill.render(...)`), not the engine
+- Engine is now a backend registry + quill factory (`engine.quill(tree)` on the Quillmark WASM binding, typically `@quillmark/wasm`)
+
+This means Quiver must own quill selection and lifecycle entirely. There is no engine `registerQuill`, `hasQuill`, or engine-level render hot path to optimize around.
+
+---
+
+## Core Decisions
+
+### 1) Quiver Shapes and Transports Are Orthogonal
+
+Two on-disk/data shapes:
+
+- **Source Quiver** (authoring shape)
+  - Human-authored, git-friendly
+  - Root `Quiver.yaml`
+  - Quills under `quills/<name>/<version>/Quill.yaml`
+  - Assets in normal source layout
+- **Packed Quiver** (distribution/runtime artifact)
+  - Hashed manifest
+  - Bundle zips
+  - Dehydrated shared font store (`store/<md5>`)
+  - Stable pointer file to current hashed manifest
+
+Transport is a separate axis for **Packed Quiver** loading:
+
+- `http` (browser/runtime delivery)
+- `fs` (packed artifact loaded from local disk)
+- future transports can be added without changing packed format
+
+**Naming decision:** use `pack()` (format operation), not transport-specific names.
+
+### 2) `Quiver.yaml` Is Required in Source Quivers
+
+Source Quivers require root `Quiver.yaml` metadata.
+
+Fields for V1:
+
+- `name` (required) — runtime namespace identity; may differ from npm package name. Charset: alphanumeric only (`[A-Za-z0-9_-]+`).
+- `description` (optional) — tooling-only metadata in V1; not consumed by runtime paths.
+
+Unknown fields in `Quiver.yaml` are a **validation error** (`quiver_invalid`). Strict-by-default keeps forward compatibility explicit: any future field is additive and requires a schema bump.
+
+`package.json.version` remains npm-channel identity; packed artifact identity remains hashed-manifest based.
+
+### 3) `QuillSource` Becomes Quiver-Centric
+
+- Re-express `QuillSource` concepts around Quivers
+- Split old filesystem concept into:
+  - **Source filesystem loader** (reads Source Quiver directly)
+  - **Packed filesystem transport** (loads Packed Quiver artifact from disk)
+- Treat HTTP as a Packed transport, not a separate format concept
+
+### 4) Multi-Quiver Composition with Deterministic Precedence
+
+`QuiverRegistry` accepts multiple quivers with explicit order.
+
+This registry/composition layer lives entirely in `@quillmark/quiver`; it is not a Quillmark engine feature.
+
+Precedence rule:
+
+- **Precedence is a hard filter**
+- Scan quivers in order
+- First quiver with any matching candidate wins
+- Choose highest matching version **within that quiver**
+
+Applies to:
+
+- unqualified refs (e.g. `usaf_memo`)
+- selector refs (e.g. `usaf_memo@1.2`)
+
+No global highest-across-all-quivers behavior.
+
+**Identity collision:** duplicate `Quiver.yaml.name` across composed quivers is an error in V1.
+
+### 5) Semver Selector Rules Are Strict and Small
+
+Supported forms:
+
+- `name` (highest version in first-winning quiver)
+- `name@x.y.z` exact
+- `name@x.y` highest `x.y.*`
+- `name@x` highest `x.*.*`
+
+Not supported in V1:
+
+- ranges (`>=`, `<`, etc.)
+- npm operators (`^`, `~`)
+- wildcards (`*`)
+- prerelease/build metadata
+
+Canonical version format:
+
+- `x.y.z` only
+- applies to quill version directories (`quills/<name>/<version>/`)
+- non-canonical versions on disk are validation errors
+
+Canonicalization:
+
+- resolve selector to canonical ref once per manifest snapshot
+- key internal caches by canonical ref
+
+### 6) Warm/Prefetch Is Purely a Quiver Concern
+
+`warm()` remains a quiver-layer optimization:
+
+- `warm()` warms all by default in V1
+- `resolve()` must work even if nothing is warmed
+
+Warm now means "load/prepare quills and artifacts", not "register in engine". There is no engine registration step anymore.
+
+### 7) Engine Boundary: New Canonical Contract (Node / JS–WASM only)
+
+Quillmark integration for `@quillmark/quiver` is:
+
+1. Initialize engine once (`new Quillmark()` from `@quillmark/wasm`)
+2. When quill bytes are ready, build a render-ready quill with `engine.quill(tree)` (`Map<string, Uint8Array>`)
+3. Render through the returned quill: `quill.render(doc, opts?)` (`Document` — built via `Document.fromMarkdown(...)`)
+
+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`)
+
+For advanced dynamic-asset behavior, defer to Quillmark’s JS/WASM docs; the default integration path here is `engine.quill` + `quill.render`.
+
+### 8) Markdown and Ref Parsing Boundary
+
+- Markdown parsing does not require a quill registry: `Document.fromMarkdown(markdown)`
+- Quiver owns ref parsing and selector resolution for its own API (`resolve`, `warm`, validation)
+- QUILL field is informational at render time; Quiver routes to the intended quill explicitly without mutating the parsed document in V1
+
+Upstream behavior note:
+
+- If rendering a parsed document whose `quill_ref` differs from selected quill name, render proceeds with warning `quill::ref_mismatch`
+- Quiver should surface that warning, not suppress it. In V1, this is an intentional loud footgun detector for ref/selection drift.
+
+### 9) Distribution Strategy
+
+V1 supports:
+
+- npm distribution for Source Quiver projects
+- git/folder-copy consumption of Source Quivers
+- `pack()` output for Packed runtime distribution
+
+Clarification:
+
+- npm/git are developer distribution channels
+- packed artifacts are runtime delivery artifacts
+
+---
+
+## Carryover Matrix (What We Keep)
+
+V1 intentionally retains:
+
+1. Font dehydration as a Packed Quiver property
+2. Consumer validation tooling for Source Quivers (+ optional Packed parity checks)
+3. Manifest pointer resolution for Packed format
+4. HTTP loading as a Packed transport
+5. Source filesystem loading as first-class dev loop
+6. Packed filesystem loading as first-class runtime option
+7. Typed errors (`QuiverError`) with quiver/transport context
+8. Concurrency coalescing for in-flight loads
+9. Preload/fail-fast helpers where they still add value
+
+Removed from carryover assumptions:
+
+- Any engine-registration cache fast path (`register`/`has`) because upstream removed the capability
+
+---
+
+## Explicit Trims (Surface Reduction)
+
+V1 should trim public API where behavior can stay internal:
+
+- Drop internal-only utility exports
+- Keep engine payload and transport internals opaque
+- Consolidate validation exports
+- Avoid duplicate entry points for equivalent validation workflows
+- Do not expose internal quill-object cache mechanisms as public contract
+
+---
+
+## Error Model
+
+Single `QuiverError` class with `code: string` + contextual payload (ref, version, quiver name, underlying cause where applicable). No subclasses. Fail-fast: operations throw on first failure; no aggregate/partial-success results in V1.
+
+V1 code catalog (closed set):
+
+| Code | Fires when |
+|---|---|
+| `invalid_ref` | Malformed ref string at `resolve()`/`warm()` boundary (fails `parseQuillRef`) |
+| `quill_not_found` | Selector did not match any quill in any composed quiver |
+| `quiver_invalid` | `Quiver.yaml` or hashed manifest malformed, unknown field, non-canonical version on disk, or font/bundle hash mismatch |
+| `transport_error` | I/O failure: missing path, HTTP non-2xx, network error, permission error. Wraps underlying cause. |
+| `quiver_collision` | Two composed quivers share `Quiver.yaml.name` at registry construction |
+
+Notes:
+- `quill_not_found` is selector-resolution failure after quiver composition and precedence.
+- `transport_error` is artifact access failure (filesystem/HTTP/network/permissions), including missing packed files and HTTP 404.
+- Legacy categories such as `manifest_invalid`, `quill_load_failed`, and `backend_not_found` are folded into `quiver_invalid` or `transport_error` in V1.
+
+Errors must include offending ref/version/quiver identifiers when available.
+
+---
+
+## Runtime + Packaging Model
+
+V1 runtime loading paths:
+
+1. Source Quiver from filesystem (authoring/dev)
+2. Packed Quiver over HTTP (browser/runtime)
+3. Packed Quiver from filesystem (air-gapped/container/runtime)
+
+V1 packaging behavior:
+
+- `Quiver.pack()` produces Packed Quiver artifact independent of transport
+- packed output includes pointer + hashed manifest + bundles + dehydrated font store
+
+Execution behavior:
+
+- Quiver resolves selector -> canonical ref
+- Quiver loads/creates a render-ready `Quill` via engine factory
+- Quiver reuses loaded quill objects by canonical ref
+- Quiver renders through `quill.render(...)`
+
+Caching scope:
+
+- In V1, loaded-quill object reuse is in scope
+- Cache eviction policy is out of scope for V1 (can be added as an additive lifecycle control later)
+
+---
+
+## Source Quiver Layout (normative)
+
+```
+<root>/
+  Quiver.yaml
+  quills/
+    <name>/
+      <version>/           # canonical x.y.z
+        Quill.yaml
+        ...                # quill-local templates, partials, assets, fonts
+```
+
+- All assets (including fonts) are **quill-local**. No quiver-level shared asset directory in V1.
+- Non-canonical version directories are a validation error (`quiver_invalid`).
+- Dedup of identical fonts across quills happens at pack time (into `store/<md5>`), not at the source layer.
+
+## Packed Quiver Format (normative)
+
+```
+<root>/
+  Quiver.json                              # stable pointer, always this filename
+  manifest.<md5>.json                      # hashed manifest, content-addressed
+  <name>@<version>.<md5>.zip               # one bundle per quill, content-addressed
+  store/
+    <md5>                                  # raw font bytes, no extension
+```
+
+**Hash:** MD5 prefix-6, computed with `node:crypto` at `pack()` time only (dev/tooling; not browser runtime).
+
+**Pointer** `Quiver.json`:
+```json
+{ "manifest": "manifest.abc123.json" }
+```
+
+**Hashed manifest** `manifest.<md5>.json`:
+```json
+{
+  "version": 1,
+  "name": "<quiver-name>",
+  "quills": [
+    {
+      "name": "usaf_memo",
+      "version": "1.2.3",
+      "bundle": "usaf_memo@1.2.3.def456.zip",
+      "fonts": { "fonts/roboto.ttf": "md5abc", "fonts/arial.ttf": "md5def" }
+    }
+  ]
+}
+```
+
+**Bundle zips** contain pure quill content (`Quill.yaml` + templates + partials + non-font assets). Fonts are dehydrated at pack time: their bytes live only in `store/<md5>`; their path→hash mapping lives only in the hashed manifest. Bundles do **not** embed a `fonts.json`.
+
+Rehydration on load: transport fetches the pointer → hashed manifest → required bundle(s) → required `store/<md5>` blobs; library reconstructs the full in-memory tree and builds a render-ready quill via `engine.quill(tree)`.
+
+## API Surface (V1)
+
+Single class, three factories:
+
+```ts
+class Quiver {
+  // Node-only factories (from `@quillmark/quiver/node`). Fail fast in browser.
+  static fromSourceDir(path: string): Promise<Quiver>;
+  static fromPackedDir(path: string): Promise<Quiver>;
+  // Browser-safe factory (from `@quillmark/quiver` main).
+  static fromHttp(url: string): Promise<Quiver>;
+  // Node-only tooling. Writes a Packed Quiver to outDir.
+  static pack(sourceDir: string, outDir: string, opts?: PackOptions): Promise<void>;
+
+  readonly name: string; // from Quiver.yaml
+
+  // Read-only introspection and lazy tree access used by QuiverRegistry
+  // internally; also available for external debugging and tooling.
+  quillNames(): string[];                                              // sorted lex
+  versionsOf(name: string): string[];                                  // sorted desc
+  loadTree(name: string, version: string): Promise<Map<string, Uint8Array>>;
+}
+```
+
+```ts
+class QuiverRegistry {
+  constructor(args: { engine: Quillmark; quivers: Quiver[] });
+
+  // Selector ref -> canonical ref. Throws invalid_ref / quill_not_found.
+  resolve(ref: string): Promise<string>;
+
+  // Canonical ref -> render-ready quill handle (materialized via engine.quill(tree), cached in-process).
+  getQuill(canonicalRef: string): Promise<Quill>;
+
+  // Warms every ref in every composed quiver. Fail-fast. Zero params in V1.
+  warm(): Promise<void>;
+}
+
+class QuiverError extends Error {
+  code: "invalid_ref" | "quill_not_found" | "quiver_invalid" | "transport_error" | "quiver_collision";
+  // plus contextual payload fields
+}
+```
+
+**No render wrapper.** Callers invoke `quill.render(doc, opts?)` (and `quill.open(doc)` when needed) after `resolve()` + `getQuill()`. Quiver never mirrors Quillmark render APIs.
+
+**Internal (not exported):** `QuiverTransport`, `QuiverManifest` (runtime shape), `parseQuillRef`, in-flight coalescing state.
+
+Hot-path flow:
+```ts
+const doc = Document.fromMarkdown(md);
+const canonicalRef = await registry.resolve(doc.quillRef);
+const quill = await registry.getQuill(canonicalRef);
+const result = quill.render(doc, { format: "pdf" });
+```
+
+## Package Structure
+
+**Name:** `@quillmark/quiver`
+
+**Entrypoints:**
+- `@quillmark/quiver` (main, browser-safe): `Quiver` class with only `fromHttp` functional (Node-only factories/pack throw `transport_error` if reached in browser), `QuiverRegistry`, `QuiverError`, shared types.
+- `@quillmark/quiver/node`: adds `Quiver.fromSourceDir`, `Quiver.fromPackedDir`, `Quiver.pack` behaviors. Single `Quiver` class — Node-only factories fail fast outside Node.
+
+**Dependencies:**
+- Peer: `@quillmark/wasm@>=0.59.0-rc.2` 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 `pack()` — never reached at runtime)
+
+---
+
+## Out of Scope for V1
+
+- Non-Node consumers of Quillmark (e.g. Python bindings, Rust CLI) as deliverables of this program — `@quillmark/quiver` is the Node/npm package only
+- Quiver CLI (`quiver init`, etc.)
+- prerelease semver support
+- semver range expression support
+- quiver-declared precedence/priority
+- inter-quiver dependency graph in `Quiver.yaml`
+- marketplace/discovery service
+- advanced warm strategies beyond API-compatible hooks
+- multi-quiver name-collision soft handling (V1 errors on duplicate `Quiver.yaml.name`)
+
+---
+
+## Planner Questions — Resolved
+
+All V1 planner questions resolved; implementation plan can proceed against the spec above.
+
+1. ~~Final `Quiver` interface shape and transport factoring style~~ → Single `Quiver` class, three static factories (`fromHttp`, `fromSourceDir`, `fromPackedDir`). Transport kept internal (no `fromTransport` in V1; YAGNI).
+2. ~~Final `Quiver.yaml` schema and unknown-field policy~~ → See §2: alphanumeric `name` and optional tooling-only `description`. Unknown fields are `quiver_invalid`.
+3. ~~Canonical ref grammar and parser API contract~~ → Internal `parseQuillRef`, not exported. Selector syntax per §5. Throws `invalid_ref`.
+4. ~~Exact warning policy for shadowed refs across quivers~~ → No warnings in V1. Precedence is a hard filter (§4); duplicate quiver names error as `quiver_collision`.
+5. ~~Validation API shape consolidation~~ → No separate validation API. Validation errors surface as `QuiverError('quiver_invalid')` during load or `pack()`.
+6. ~~Pack artifact directory structure~~ → See "Packed Quiver Format (normative)".
+7. ~~Node/browser entrypoint split~~ → See "Package Structure": main + `/node` subpath, single `Quiver` class.
+8. ~~Final exported type names~~ → `Quiver`, `QuiverRegistry`, `QuiverError`. Hot-path entry is `QuiverRegistry.resolve(ref)` + `QuiverRegistry.getQuill(canonicalRef)`.
+
+---
+
+## 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
+- A packed artifact can be loaded via HTTP or local filesystem with equivalent semantics
+- Multi-quiver resolution is deterministic and matches precedence hard-filter rules
+- Selector behavior is predictable and explicitly documented
+- Quiver (Node) integrates via `engine.quill(tree)` + `quill.render(...)` only (no engine quill registration path)
+- Public API surface is smaller and clearer than `@quillmark/registry`

package/README.md

@@ -0,0 +1,96 @@
+# @quillmark/quiver
+
+Quiver registry and packaging for Quillmark — load, compose, and pack collections of quills for rendering with `@quillmark/wasm`.
+
+## Install
+
+```bash
+npm install @quillmark/quiver @quillmark/wasm
+```
+
+## Quick start
+
+```ts
+import { Quillmark, Document } from "@quillmark/wasm";
+import { Quiver, QuiverRegistry } from "@quillmark/quiver/node";
+
+// 1. Load a source quiver from disk (Node.js only)
+const quiver = await Quiver.fromSourceDir("./my-quiver");
+
+// 2. Build a registry with one or more quivers
+const engine = new Quillmark();
+const registry = new QuiverRegistry({ engine, quivers: [quiver] });
+
+// 3. Resolve a ref, obtain a render-ready quill, and render
+const doc = Document.fromMarkdown(markdownString);
+const canonicalRef = await registry.resolve(doc.quillRef);
+const quill = await registry.getQuill(canonicalRef);
+const result = quill.render(doc, { format: "pdf" });
+```
+
+## HTTP (browser / CDN)
+
+```ts
+import { Quiver, QuiverRegistry } from "@quillmark/quiver";
+
+const quiver = await Quiver.fromHttp("https://cdn.example.com/my-quiver");
+const registry = new QuiverRegistry({ engine, quivers: [quiver] });
+```
+
+## Packed directory (Node.js)
+
+```ts
+import { Quiver } from "@quillmark/quiver/node";
+
+const quiver = await Quiver.fromPackedDir("./dist/my-quiver");
+```
+
+## Pack a source quiver
+
+```ts
+import { Quiver } from "@quillmark/quiver/node";
+
+await Quiver.pack("./my-quiver", "./dist/my-quiver");
+```
+
+## Warm (prefetch all quills)
+
+```ts
+await registry.warm();
+```
+
+## Multi-quiver composition
+
+Quivers are scanned in order. The first quiver with any matching candidate wins;
+the highest matching version within that quiver is returned.
+
+```ts
+const registry = new QuiverRegistry({
+  engine,
+  quivers: [primaryQuiver, fallbackQuiver],
+});
+```
+
+## Error handling
+
+All errors are instances of `QuiverError` with a `code` field.
+
+```ts
+import { QuiverError } from "@quillmark/quiver";
+
+try {
+  const canonicalRef = await registry.resolve("unknown_quill");
+} catch (err) {
+  if (err instanceof QuiverError) {
+    console.error(err.code);    // e.g. "quill_not_found"
+    console.error(err.message); // human-readable description
+    console.error(err.ref);     // offending ref, when available
+  }
+}
+```
+
+Error codes: `invalid_ref`, `quill_not_found`, `quiver_invalid`, `transport_error`, `quiver_collision`.
+
+## Full specification
+
+See [PROGRAM.md](./PROGRAM.md) for the complete API surface, packed format specification, and design decisions.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@quillmark/quiver",
+  "version": "0.1.0",
+  "description": "Quiver registry and packaging for Quillmark",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quillmark/quiver"
+  },
+  "keywords": [
+    "quillmark",
+    "quiver",
+    "typst",
+    "markdown"
+  ],
+  "author": "Quillmark Contributors",
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    }
+  },
+  "files": [
+    "dist",
+    "PROGRAM.md",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@quillmark/wasm": ">=0.59.0-rc.2"
+  },
+  "dependencies": {
+    "fflate": "^0.8.2",
+    "yaml": "^2.8.3"
+  },
+  "devDependencies": {
+    "@quillmark/wasm": "0.59.0-rc.2",
+    "@types/node": "^25.3.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "tsc --noEmit"
+  }
+}