@uniweb/unipress 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -64,15 +64,16 @@ separates create-time templates from runtime foundations.
 - `templates/` directory; `package.json`'s `files:` array now ships
   `documents/`.
 
-### Caveat
-
-Catalog entries currently point at the **local registry**
-(`http://localhost:4001/registry/packages/<ns>/<name>/<ver>/foundation.js`).
-Scaffolded documents will fail to fetch the foundation unless the
-foundations are published locally via `uniweb publish --local` against
-a running unicloud, OR the user passes `--foundation <path>` explicitly.
-A follow-up release switches the catalog URLs to the production
-registry once `@uniweb/book` and `@uniweb/data` publish there.
+### Caveat (resolved in a follow-up release)
+
+Catalog entries in 0.2.0 pointed at a local registry
+(`http://localhost:4001/...`), so scaffolded documents required the
+user to run a registry locally or to pass `--foundation <path>`
+explicitly. A subsequent release switches the catalog URLs to GitHub
+Pages (`https://uniweb.github.io/unipress/foundations/...`); the
+foundations are deployed there by `.github/workflows/deploy-foundations.yml`
+on every push to main, and `unipress create + compile` works end-to-end
+from a fresh npm install.
 
 ## 0.1.0 (unreleased)
 

package/README.md

@@ -26,9 +26,11 @@ Equations work in the standard LaTeX style — `$E = mc^2$` for inline, `$$...$$
 
 **For authors.** unipress is a tool. Pick a template, write markdown, compile. The template knows the conventions for its kind of document — typography, structure, the bits that make a book look like a book and a directory look like a directory. You handle the content; the template handles everything else.
 
-**For developers.** unipress is an engine. A *foundation* is a component system that declares what section types exist (`type: Chapter`, `type: Bibliography`), where data comes from (`data:` declarations), and what output formats it can emit (`outputs: { docx, xlsx, pdf, custom-format }`). Authors write markdown against your vocabulary; unipress runs your foundation against their content. Same content directory, multiple outputs your foundation chooses to support — typeset book, accessible EPUB, regulatory report, structured data feed. The same foundation can also drive a [Uniweb](https://uniweb.io) website, so the work is never single-purpose.
+**For developers.** unipress is an engine. A *foundation* you write declares what section types exist (`type: Chapter`, `type: Bibliography`), where their data comes from (markdown content, file-based or API-backed collections, [Loom](https://github.com/uniweb/loom) expressions templating against hierarchical data), and what output formats it can emit (`outputs: { docx, xlsx, pdf, custom-format }`). Authors mix prose with structured records and computed values in the same document; unipress runs your foundation against their content and produces whatever your foundation declares — typeset book, accessible EPUB, regulatory report, structured data feed. The same foundation can also drive a [Uniweb](https://uniweb.io) website, so the work is never single-purpose.
 
-Foundations consume [`@uniweb/press`](https://github.com/uniweb/press) for the bytes-emitting work. Press is the output layer (Word, Excel, Typst today; more formats shipping); the foundation is your vocabulary.
+Foundations consume [@uniweb/press](https://github.com/uniweb/press) for the bytes-emitting work. Press is the output layer (Word, Excel, Typst today; more formats shipping); the foundation is your vocabulary.
+
+→ For the deeper pitch — mixed prose-and-data, Loom templating, custom output adapters — see [docs/for-developers.md](./docs/for-developers.md).
 
 ## Install
 
@@ -52,7 +54,7 @@ Five built-in templates ship with the binary. Run `unipress list-templates` for
 | `data-report` | `@uniweb/data` | xlsx, docx | Aggregate metrics across structured records |
 | `directory` | `@uniweb/data` | xlsx, docx | Flat records listing with a filterable surface |
 
-Per-template guides: [`docs/templates/`](./docs/templates/).
+Per-template guides: [docs/templates/](./docs/templates/).
 
 More templates land as more foundations ship — `cv`, `resume`, `paper`, `thesis` are on the roadmap for upcoming releases.
 
@@ -200,12 +202,12 @@ unipress is **pre-1.0**. The CLI is stable enough to write real documents with
 
 ## Troubleshooting
 
-See [`docs/troubleshooting.md`](./docs/troubleshooting.md) for common errors and fixes — every named error class maps to a cause and a concrete next step.
+See [docs/troubleshooting.md](./docs/troubleshooting.md) for common errors and fixes — every named error class maps to a cause and a concrete next step.
 
 ## See also
 
-- [`@uniweb/press`](https://github.com/uniweb/press) — the output layer foundations consume to produce Word/Excel/Typst/EPUB. Foundation authors interact with it directly.
-- [`@uniweb/build`](https://github.com/uniweb/build) — the framework's content-collection pipeline. unipress consumes the sharp-free `/content` entry.
+- [@uniweb/press](https://github.com/uniweb/press) — the output layer foundations consume to produce Word/Excel/Typst/EPUB. Foundation authors interact with it directly.
+- [@uniweb/build](https://github.com/uniweb/build) — the framework's content-collection pipeline. unipress consumes the sharp-free `/content` entry.
 - [Uniweb](https://uniweb.io) — the larger framework. Foundations originate here; unipress brings them to the command line.
 
 ## License

package/RELEASING.md

@@ -2,7 +2,9 @@
 
 Notes for cutting a release tag (`unipress@<version>`). The release workflow at `.github/workflows/release.yml` watches for tag pushes matching that pattern, builds three binaries (darwin-arm64, linux-x64, windows-x64), and creates a GitHub Release with the binaries and SHA-256 sidecars attached.
 
-This file mostly exists to flag one thing the release workflow currently can't handle on its own.
+A separate workflow at `.github/workflows/deploy-foundations.yml` builds and deploys the bundled foundations (`foundations/<name>/`) to the unipress repo's GitHub Pages site under `https://uniweb.github.io/unipress/foundations/<name>/<version>/`. It runs on every push to main, accumulating versions on the `gh-pages` branch — older versions stay reachable indefinitely. No tag needed; foundation deployment is decoupled from the binary-release tag cadence.
+
+This file mostly exists to flag one thing the binary-release workflow currently can't handle on its own.
 
 ---
 

package/docs/for-developers.md

@@ -0,0 +1,113 @@
+# unipress for developers
+
+The developer-track companion to the README. Read this if you're considering writing a foundation that compiles to documents — or to documents *and* websites from the same source.
+
+## What you actually get
+
+A foundation is a [Uniweb](https://uniweb.io) component system. unipress is the **headless runtime** for it: run `unipress compile <dir>` and the same foundation that drives a Uniweb website produces a downloadable file from a content directory.
+
+That means everything the framework does for websites, you can do for documents. The visual editor goes away; the compile pipeline stays.
+
+## Section types are the vocabulary
+
+A foundation declares **section types** — addressable React components that content authors reference by name from markdown frontmatter:
+
+```markdown
+---
+type: Chapter
+title: "Chapter One"
+---
+
+Prose body here.
+```
+
+The foundation decides what `Chapter` means: its layout, its typography, what data it expects, how it renders across each output format the foundation declares. Authors don't think in components — they think in *kinds of section*. The component is the foundation developer's responsibility; the content is the author's.
+
+## Mix prose with structured data
+
+A document is rarely just prose. Foundations declare data inputs; authors fill them in. The data can come from any of these surfaces:
+
+- **Markdown content** — the prose body of each `.md` file, parsed into a structured tree (title, paragraphs, items, links, images, code blocks).
+- **Frontmatter params** — declared in each section's YAML frontmatter, typed by the foundation's `meta.js`.
+- **File-based collections** — `collections/publications.json`, `collections/team.yml`, or markdown frontmatter swept into a list at build time. Compile to one `/data/<name>.json` per collection.
+- **API-backed collections** — declare a fetcher in `document.yml`; the build pipeline resolves it at compile time. The foundation reads `content.data` and renders.
+- **Computed values via [Loom](https://github.com/uniweb/loom)** — Loom is an expression language for instantiating templates against hierarchical data. Pull a publications list from a collection, format each entry with a Loom expression, and the result lands typeset in your output.
+
+All of these flow through the same foundation pipeline — same primitives whether the data came from a YAML file, a JSON dump, or an API endpoint.
+
+### Academic writing: bibliographies and citations
+
+For scholarly work specifically, [`citestyle`](https://github.com/uniweb/csl) handles the formatting layer Loom is too general for. CSL-based, lightweight, used directly from foundations: pick from APA, MLA, Chicago author-date, IEEE, Vancouver, Harvard at the section level (`style: chicago-author-date`); citestyle dynamically loads only the styles you reference and formats every entry to spec — the author ordering, journal abbreviations, punctuation, and conventions academic readers expect.
+
+The combination is the powerful part. Loom interpolates ("In {section.title}, we describe…"); citestyle formats bibliographic entries (a complete back-matter `Bibliography`, or inline `[Author Year]` citation marks). A thesis, monograph, or annual research report uses both: Loom for dynamic prose and per-section metadata, citestyle for every bibliographic touch in the document.
+
+Working example: the `data-report` template ships a `PublicationsList` section backed by YAML bib data in `collections/members/*.yml`, with per-section style selection. Run `unipress create my-report --template data-report` to see it. Bibliography support in long-form prose templates (`book`, `monograph`, future `thesis`/`paper`) lands across upcoming releases.
+
+## Outputs are foundation-declared
+
+```js
+// foundation/src/foundation.js
+export default {
+  outputs: {
+    pdf:    { extension: 'pdf', via: 'typst', getOptions: buildTypstOptions },
+    epub:   { extension: 'epub', getOptions: buildEpubOptions },
+    docx:   { getOptions: buildDocxOptions },
+    'tax-form-2024': { getOptions: buildTaxFormOptions },  // your own adapter
+  },
+}
+```
+
+Each entry says: which Press adapter handles the format (`via:`), which file extension to default to (`extension:`), and how to assemble adapter-specific options from the website's resolved content (`getOptions(website, hostHints)`).
+
+Press ships adapters for Word, Excel, Typst (PDF), and HTML-shaped output. For a format Press doesn't ship — a CSV feed, a domain-specific XML, a one-of-a-kind regulatory submission — write a custom adapter using [`@uniweb/press/ir`](https://github.com/uniweb/press) and declare it on the foundation. unipress dispatches by name; nothing in unipress itself needs to know about your format.
+
+## Same foundation, two runtimes
+
+`unipress compile` is one consumer. The Uniweb website pipeline (`uniweb dev`, `uniweb build`) is the other. Same foundation, same content shape, same data declarations — different runtime.
+
+That's the structural payoff: the work of defining section types, theming, and rendering isn't single-purpose. A "regulatory report" foundation can drive both an HTML site that stakeholders browse and a PDF/XLSX/DOCX bundle filed quarterly. A "research output" foundation can drive a public-facing journal site and a print-ready PDF for archival. Authoring once produces every modality.
+
+## A worked example
+
+A research-group annual-report foundation (`@yourorg/annual-report`) might ship:
+
+- **Section types**: `Cover`, `ExecutiveSummary`, `Members`, `PublicationsList`, `FundingTable`, `Charts`, `Appendix`, `Bibliography`.
+- **Data**: a `publications.yml` collection (file-based) with full bibliographic fields per paper; a `funding.json` collection with grant data; an API-backed `metrics:` collection pulling live citation counts.
+- **citestyle for bibliographic precision**: pick a style at the section level (`style: chicago-author-date`) and citestyle formats every entry to spec — author ordering, journal abbreviations, the punctuation that marks the difference between a draft and a polished publication.
+- **Loom templates**: dynamic prose elsewhere — running headers (`{book.title} — Chapter {n}`), section subtitles, the table-of-contents introductions. Loom and citestyle cooperate: citestyle owns bibliographic formatting; Loom owns everything else.
+- **Outputs**: `pdf` (typeset for the dean's office), `xlsx` (one sheet per data block, for finance), `docx` (for collaborators who don't open PDFs), `pagedjs` (HTML for the public site).
+
+A content author writes:
+
+```markdown
+---
+type: PublicationsList
+title: "Publications"
+data: publications
+filter:
+  year: 2024
+---
+
+The group published 47 papers in 2024, a 30% increase over 2023.
+```
+
+`unipress compile annual-2024 --format pdf` walks the content through the foundation, resolves Loom expressions over the filtered collection, runs the typst adapter, ships a typeset PDF. `unipress compile annual-2024 --format xlsx` produces a workbook with one sheet per data section. The same source directory; two file types, both honest.
+
+## Where to go from here
+
+- **Foundation contract** — the `outputs:` map, `meta.js` section-type discovery, the `getOptions(website, hostHints)` signature: see [foundation configuration](https://github.com/uniweb/docs/blob/main/reference/foundation-config.md).
+- **Data fetching** — collections, fetchers, predicates, where-objects, deferred fields: see the [data fetching reference](https://github.com/uniweb/docs/blob/main/reference/data-fetching.md).
+- **Loom** — expression language for instantiating templates against hierarchical data: [`@uniweb/loom`](https://github.com/uniweb/loom).
+- **citestyle** — CSL-based citation and bibliography formatter. Domain-specific complement to Loom: Loom interpolates, citestyle formats academic-style references: [`citestyle`](https://github.com/uniweb/csl).
+- **Press (the output layer)** — [`@uniweb/press`](https://github.com/uniweb/press) docs cover the registration pattern foundations consume, the IR layer for custom adapters, and per-adapter notes (docx invariants, typst conventions, the EPUB pipeline).
+- **Building a foundation from scratch** — [Uniweb framework docs](https://github.com/uniweb/docs) cover the full authoring story; everything written for sites applies to documents.
+
+## A few things worth knowing upfront
+
+**Documents are static at compile time.** unipress produces bytes; once the file is on disk, it doesn't change. "Dynamic data" in a document means *the data backing the document can vary between compiles* (re-run `unipress compile` after the API has new data; get a new PDF). It does not mean the PDF live-updates while someone reads it. That's website territory.
+
+**Foundations stay environment-agnostic.** unipress runs in Node; the Uniweb editor runs in the browser. Foundations should not branch on `typeof window` or do their own asset I/O. The compile pipeline supplies a `loadAsset(src)` helper that hosts implement appropriately for their runtime; foundations just call it. The book foundation in this repo is the reference example.
+
+**Compile failures are debuggable.** `unipress compile <dir> --verbose` streams every step; `unipress inspect <dir>` dumps the parsed content tree as JSON before the foundation runs (useful when output looks wrong and you want to know whether the input was right). Press emits structured warnings when an adapter receives unexpected shapes.
+
+**Pre-1.0.** The contract is settling but not frozen. The foundation `outputs:` map, the `meta.js` discovery model, the `compileDocument` API, the section-type vocabulary — all stable enough to build against, with breaking changes possible (and documented in the CHANGELOG) before 1.0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/unipress",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Compile a content directory into a document (PDF, EPUB, Paged.js HTML, Typst source bundle, DOCX, XLSX) using a Uniweb foundation. Five built-in templates: book, monograph, report, data-report, directory.",
   "type": "module",
   "publishConfig": {
@@ -49,11 +49,11 @@
     "prompts": "^2.4.2",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@uniweb/content-reader": "1.1.5",
-    "@uniweb/semantic-parser": "1.1.11",
+    "@uniweb/build": "0.11.2",
     "@uniweb/runtime": "0.8.4",
     "@uniweb/core": "0.7.3",
-    "@uniweb/build": "0.11.2"
+    "@uniweb/content-reader": "1.1.5",
+    "@uniweb/semantic-parser": "1.1.11"
   },
   "scripts": {
     "test": "echo \"no tests yet\" && exit 0",

package/src/foundation-loader.js

@@ -41,7 +41,17 @@ const PATH_PATTERN = /^(\.\.?[\/\\]|[\/\\]|[A-Za-z]:[\/\\])/
 // Version is anything semver-shaped — exact match isn't enforced here; the
 // registry decides what's valid.
 const REGISTRY_REF_PATTERN = /^@([a-z0-9][a-z0-9._-]*)\/([a-z0-9][a-z0-9._-]*)@([0-9a-z][0-9a-z.\-+]*)$/i
-const DEFAULT_REGISTRY_BASE = 'https://site-router.uniweb-edge.workers.dev'
+
+// unipress's bundled foundations are distributed as static artifacts on
+// the unipress repo's GitHub Pages site. URL pattern:
+//
+//   https://uniweb.github.io/unipress/foundations/<name>/<version>/foundation.js
+//
+// The namespace portion of a registry ref is implicit — every foundation
+// served from this base is under @uniweb/. Set UNIWEB_REGISTRY_URL to
+// override (e.g., for testing against a local http.server during foundation
+// development, or for users with a private alternative).
+const DEFAULT_REGISTRY_BASE = 'https://uniweb.github.io/unipress'
 const DEFAULT_BUILT_ENTRY = 'dist/foundation.js'
 
 function getRegistryBase() {
@@ -49,8 +59,15 @@ function getRegistryBase() {
   return raw.replace(/\/$/, '')
 }
 
+// Build the URL for a registry ref. The namespace is preserved in the
+// returned URL only when the base wants it; for the GH Pages distribution
+// the namespace is implicit and the path is <base>/foundations/<name>/<ver>/.
+// If a custom UNIWEB_REGISTRY_URL needs the namespace in the path, it can
+// hold a path prefix that resolves accordingly (e.g., set
+// `UNIWEB_REGISTRY_URL=https://my.host/by-ns/uniweb` and live without the
+// per-namespace split, or maintain a redirect rule on that host).
 function buildRegistryUrl(namespace, name, version) {
-  return `${getRegistryBase()}/registry/packages/${namespace}/${name}/${version}/foundation.js`
+  return `${getRegistryBase()}/foundations/${name}/${version}/foundation.js`
 }
 
 export async function resolveFoundationRef(ref, { anchorDir, onProgress = () => {} } = {}) {

package/src/foundations-data.js

@@ -10,6 +10,25 @@
  * different `book.structure:` defaults, and different sample chapters.
  *
  * ─────────────────────────────────────────────────────────────────────────
+ * Distribution
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * Foundations are deployed as static artifacts to the unipress repo's
+ * GitHub Pages site. URL pattern:
+ *
+ *   https://uniweb.github.io/unipress/foundations/<name>/<version>/foundation.js
+ *
+ * On every push to main, `.github/workflows/deploy-foundations.yml`
+ * builds each `foundations/<name>/` and layers the resulting `dist/` into
+ * the gh-pages branch under `foundations/<name>/<version>/`. Versions
+ * accumulate; older versions stay reachable indefinitely.
+ *
+ * GH Pages serves `Access-Control-Allow-Origin: *` on static files, so
+ * cross-origin imports work for browser hosts (Uniweb editor preview).
+ * The unipress CLI fetches the URL directly and caches at
+ * `~/.cache/unipress/foundations/...`.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
  * Resolution path
  * ─────────────────────────────────────────────────────────────────────────
  *
@@ -17,15 +36,15 @@
  *   1. catalog lookup (this file) → entry.foundation.ref + entry.scaffold.
  *   2. scaffold copies templates-data.js[entry.scaffold] into my-doc/. The
  *      bundled document.yml has `foundation: <entry.foundation.ref>` (the
- *      registry-ref form, e.g., '@uniweb/book@0.1.0' — rewritten from the
+ *      registry-ref form, e.g., '@uniweb/book@0.1.1' — rewritten from the
  *      committed dev path-ref by scripts/generate-templates-data.js).
  *
  * `unipress compile my-doc`:
- *   1. document.yml `foundation: '@uniweb/book@0.1.0'` is parsed as a
+ *   1. document.yml `foundation: '@uniweb/book@0.1.1'` is parsed as a
  *      registry ref by foundation-loader.js.
  *   2. The loader constructs a URL from the registry base
- *      (UNIWEB_REGISTRY_URL or the production default at
- *      site-router.uniweb-edge.workers.dev) → fetches + caches.
+ *      (UNIWEB_REGISTRY_URL env override or the default GH Pages base) →
+ *      fetches + caches.
  *
  * ─────────────────────────────────────────────────────────────────────────
  * source.url
@@ -33,14 +52,9 @@
  *
  * Each entry's `foundation.source.url` is the human-meaningful "where this
  * foundation lives" pointer shown in `list-templates` output and post-create
- * messages. It does NOT drive resolution under the registry-ref-in-document.yml
- * model — foundation-loader builds its own URL from the ref + base. The
- * URL is included for transparency.
- *
- * v0.2 entries pin local-registry URLs (http://localhost:4001/...) so
- * foundation devs running `uniweb publish --local` can verify resolution
- * end-to-end. TF8 of the unipress-foundations-and-templates plan switches
- * these to the production registry once the foundations publish there.
+ * messages. It mirrors the URL the loader builds at compile time, but does
+ * not itself drive resolution — the loader builds its own URL from
+ * `foundation.ref` + the configured base.
  *
  * ─────────────────────────────────────────────────────────────────────────
  * Storage format
@@ -51,20 +65,20 @@
  * runtime reads.
  */
 
-const LOCAL_REGISTRY_BASE = 'http://localhost:4001/registry/packages'
+const PUBLIC_FOUNDATIONS_BASE = 'https://uniweb.github.io/unipress/foundations'
 
-function localUrl(namespace, name, version) {
-  return `${LOCAL_REGISTRY_BASE}/${namespace}/${name}/${version}/foundation.js`
+function publicUrl(name, version) {
+  return `${PUBLIC_FOUNDATIONS_BASE}/${name}/${version}/foundation.js`
 }
 
 const BOOK_FOUNDATION = {
-  ref: '@uniweb/book@0.1.0',
-  source: { url: localUrl('uniweb', 'book', '0.1.0') },
+  ref: '@uniweb/book@0.1.1',
+  source: { url: publicUrl('book', '0.1.1') },
 }
 
 const DATA_FOUNDATION = {
   ref: '@uniweb/data@0.1.0',
-  source: { url: localUrl('uniweb', 'data', '0.1.0') },
+  source: { url: publicUrl('data', '0.1.0') },
 }
 
 export const FOUNDATIONS = [