@uniweb/unipress 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## Unreleased
+
+### Changed
+
+- **Release binaries are now signed.** macOS binaries are signed with
+  Apple Developer ID Application + Apple-notarized; Windows binaries
+  are signed via Azure Trusted Signing. macOS users no longer see a
+  Gatekeeper warning on first run. The 0.2.3 release assets were
+  re-signed in place — re-download from the release page if you
+  grabbed an unsigned copy before this change landed.
+
+### Removed
+
+- `.github/workflows/release.yml`. Binaries are no longer built in
+  this public repo — they're built and signed in a private Proximify
+  pipeline. Pushing a `unipress@<version>` tag no longer triggers a
+  binary build; the maintainer dispatches the signed pipeline manually
+  after each tag, and the resulting binaries are uploaded to the same
+  GitHub Release on this repo. Source code, docs, npm publishing, and
+  the foundation-deploy workflow are unchanged.
+
+## 0.2.3
+
+The first complete-out-of-the-box release. `npm i -g @uniweb/unipress`
++ `unipress create my-book --template book` + `unipress compile my-book`
+produces a real PDF on the first try, no setup, no auth, no local
+servers, no `--foundation` overrides.
+
+### Added
+
+- **GitHub Pages distribution for bundled foundations.**
+  `https://uniweb.github.io/unipress/foundations/<name>/<version>/foundation.js`
+  serves every published foundation. A new workflow
+  (`.github/workflows/deploy-foundations.yml`) builds each
+  `foundations/<name>/` on every push to main and accumulates versions
+  on the `gh-pages` branch — older versions stay reachable indefinitely.
+  No registry namespace claim, no Cloudflare worker, no platform
+  authorization needed for the open-source foundations.
+- **`scripts/ci-flip-workspace-deps.js`** — pre-install rewrite that
+  translates `workspace:*` deps to npm version ranges in CI. Both
+  workflows (foundation deploy, binary release) call it as the first
+  step. Closes the standalone-install gap that the workspace:*
+  resolution introduced.
+- **`prepublishOnly` regenerates `templates-data.js`.** `pnpm publish`
+  now refreshes the bundled template data from `documents/<name>/`
+  before packing, so a stale generated file can't ship even if a
+  developer forgot to regenerate before commit.
+
+### Fixed
+
+- **EPUB cover image no longer skipped.** The foundation's
+  `buildEpubOptions` was using a `fetch`-based URL resolver that
+  silently 404'd in unipress's Node compile context. Replaced with
+  the same `loadAsset` abstraction the typst path uses. Cover image
+  now embeds at `OEBPS/images/<hash>.jpg` alongside a synthesized
+  `cover.xhtml` page.
+- **DOCX inline-image path threaded through `loadAsset`.**
+  `framework/press`'s docx adapter walker now plumbs the host-supplied
+  byte loader from `buildDocument` → `convertChildren` →
+  `irToImageParagraph` → `fetchImageData` → `fetchAsset`. Future
+  docx-emitting templates with inline images compile cleanly in
+  unipress.
+- **Cover round-trip in scaffolded projects** — front + back JPGs
+  ship via the binary-asset support added to the template generator.
+  EPUB readers + most PDF viewers now show the book's thumbnail
+  without the user adding any artwork.
+
+### Changed
+
+- Catalog URLs in `src/foundations-data.js` flipped from local-registry
+  (`http://localhost:4001/...`) to GH Pages
+  (`https://uniweb.github.io/unipress/foundations/...`). The 0.2.0
+  caveat in the changelog is resolved.
+- `foundation-loader.js`'s `DEFAULT_REGISTRY_BASE` flipped to
+  `https://uniweb.github.io/unipress`. `UNIWEB_REGISTRY_URL` env var
+  remains the override for local dev / private alternatives.
+- `@uniweb/*` deps in `package.json` are `workspace:*` again (dev
+  resolves local siblings); `pnpm publish` translates them to real
+  version specs in the published tarball.
+
+### Notes
+
+- Binary downloads (darwin-arm64, linux-x64, windows-x64) ship via
+  the existing `unipress@<version>` tag-driven release workflow. The
+  npm path is now equivalent for users with Node 20+.
+- See `RELEASING.md` for the framework-publish + workspace:* flip-back
+  dance the next maintainer release follows.
+
 ## 0.2.0
 
 The credibility-shifting release. Two production-shaped foundations

package/README.md

@@ -34,9 +34,17 @@ Foundations consume [@uniweb/press](https://github.com/uniweb/press) for the byt
 
 ## Install
 
-**Standalone binary (recommended for most users).** No Node, no npm. Download the asset for your platform from [the releases page](https://github.com/uniweb/unipress/releases), make it executable, and put it somewhere on your `PATH` — `/usr/local/bin/unipress` is a common choice on macOS and Linux. Then you can run `unipress` from any directory.
+**Homebrew (macOS and Linux — recommended).** No Node, no manual download:
 
-**npm.** If you already have Node:
+```bash
+brew install uniweb/unipress/unipress
+```
+
+Updates land via `brew upgrade unipress`. The macOS binary is signed with the Proximify Inc. Developer ID and Apple-notarized — no Gatekeeper warnings.
+
+**Manual download (Windows, or any platform without Homebrew).** Grab the asset for your platform from [the releases page](https://github.com/uniweb/unipress/releases), make it executable (Unix), and put it somewhere on your `PATH`. On macOS and Linux, `/usr/local/bin/unipress` is a common location.
+
+**npm.** If you already have Node ≥ 20.19:
 
 ```bash
 npm i -g @uniweb/unipress

package/docs/templates/book.md

@@ -15,8 +15,7 @@ unipress compile . --format pdf --out my-book.pdf
 ```
 my-book/
 ├── document.yml          pinned to @uniweb/book@<version>
-├── pages/
-│   ├── folder.yml        activates folder mode
+├── content/
 │   ├── 01-preface.md     type: BackMatter — unnumbered front matter
 │   ├── 02-chapter-one.md
 │   └── 03-chapter-two.md
@@ -42,7 +41,7 @@ my-book/
 
 ## Add chapters
 
-Drop a markdown file under `pages/` and add its base name (without `.md`) to `document.yml`'s `pages:` list in the order you want it to appear. Chapters need no frontmatter — the foundation's `Chapter` section handles them by default. For non-chapter pages (acknowledgments, colophon, appendices), use `type: BackMatter` in frontmatter to skip chapter numbering.
+Drop a markdown file under `content/` and add its base name (without `.md`) to `document.yml`'s `content:` list in the order you want it to appear. Chapters need no frontmatter — the foundation's `Chapter` section handles them by default. For non-chapter pages (acknowledgments, colophon, appendices), use `type: BackMatter` in frontmatter to skip chapter numbering.
 
 ## Common customizations
 

package/docs/templates/data-report.md

@@ -20,7 +20,7 @@ q3-metrics/
 ├── collections/
 │   ├── members/          three sample records (19th-century naturalists)
 │   └── queries/          saved query examples for the Population dropdown
-└── pages/
+└── content/
     └── report/           cover, members, publications-by-{type,journal,year},
                           publications-list, funding, supervisions
 ```
@@ -33,7 +33,7 @@ The starter ships three sample members so the first compile produces a non-empty
 |----------------------------|--------------------------------------------------------|
 | `name`, `author`, `year`   | Workbook metadata (shown in the file's properties).    |
 | `format`                   | `xlsx` (default) or `docx`. Override on the CLI.       |
-| `index`                    | Routes `/` → `pages/<index>` (here: `report`).         |
+| `index`                    | Routes `/` → `content/<index>` (here: `report`).         |
 | `collections.members.path` | Where the records live (default `collections/members`).|
 | `collections.members.queryable` | Filterable surface — drives the FilterPanel UI.   |
 | `collections.queries.path` | Saved-view dropdown (Population selector).             |

package/docs/templates/directory.md

@@ -17,7 +17,7 @@ faculty/
 ├── document.yml          pinned to @uniweb/data@<version>; one queryable collection
 ├── collections/
 │   └── members/          three sample records
-└── pages/
+└── content/
     └── directory/        cover (Loom-rendered count) + listing
 ```
 
@@ -27,7 +27,7 @@ faculty/
 |-----------------------------|--------------------------------------------------------|
 | `name`                      | Workbook title.                                        |
 | `format`                    | `xlsx` (default) or `docx`.                            |
-| `index`                     | Routes `/` → `pages/directory`.                        |
+| `index`                     | Routes `/` → `content/directory`.                        |
 | `collections.members.path`  | Where the records live (`collections/members`).        |
 | `collections.members.queryable` | Filterable fields — drives the FilterPanel UI.    |
 
@@ -58,7 +58,7 @@ Add a `joined_year:` range field, for example, if filtering by start year matter
 
 ## Hand-pick the displayed columns
 
-The Members section reads every key from each record by default. To restrict the columns shown in the web preview and the xlsx export, set `columns:` on the section frontmatter in `pages/directory/members.md`.
+The Members section reads every key from each record by default. To restrict the columns shown in the web preview and the xlsx export, set `columns:` on the section frontmatter in `content/directory/members.md`.
 
 ## When to pick `directory` over `data-report`
 

package/docs/templates/monograph.md

@@ -1,6 +1,6 @@
 # `monograph`
 
-A scholarly monograph — sustained, single-author argument on a focused topic. Royal-octavo trim, classical typography (EB Garamond by default with Garamond and Georgia fall-backs), three-deep TOC, roman-numeralled front matter. Same `@uniweb/book` foundation as the `book` and `report` templates, configured for academic press conventions.
+A scholarly monograph — sustained, single-author argument on a focused topic with a working citation system. Royal-octavo trim, classical typography (EB Garamond by default with Garamond and Georgia fall-backs), three-deep TOC, roman-numeralled front matter, inline `[@key]` cites, and a back-matter bibliography formatted by [citestyle](https://github.com/uniweb/csl) in any of nine styles. Same `@uniweb/book` foundation as the `book` and `report` templates, configured for academic press conventions.
 
 ## Scaffold
 
@@ -10,41 +10,192 @@ cd my-monograph
 unipress compile . --format pdf --out my-monograph.pdf
 ```
 
+The starter ships a small Victorian-naturalist bibliography (nine entries — Darwin, Wallace, Lyell, Mendel, Huxley, Hooker, Spencer) and a chapter that exercises every inline-cite shape. Compile out of the box and read the result alongside the markdown source to see what each shape produces.
+
 ## What you get
 
 ```
 my-monograph/
-├── document.yml          pinned to @uniweb/book@<version>; royal-octavo, EB Garamond, tocDepth: 3
-├── pages/
-│   ├── folder.yml
-│   ├── 01-preface.md     type: BackMatter
-│   ├── 02-introduction.md
-│   └── 03-chapter-one.md
+├── document.yml              pinned to @uniweb/book@<version>; royal-octavo, EB Garamond
+├── collections/
+│   └── bibliography/
+│       └── refs.bib          BibTeX file — every @entry is one record
+├── content/
+│   ├── 01-preface.md         type: BackMatter
+│   ├── 02-introduction.md    type: Chapter
+│   ├── 03-chapter-one.md     type: Chapter (worked cite example)
+│   └── 99-bibliography.md    type: Bibliography (back-matter list)
 └── README.md
 ```
 
 ## When to pick `monograph` over `book`
 
+- You need cited bibliographic references in your prose.
 - You want section numbering deeper than two levels (default `tocDepth: 3`).
 - You want classical book typography (EB Garamond) rather than the foundation's default sans/serif fall-back.
 - You want a slightly larger page (royal-octavo, 6.14×9.21in) common in academic hardcovers.
 
 For trade-paperback fiction or non-fiction prose, use `book` instead. For a technical report with tables and code, use `report`.
 
+## Citations
+
+The citation system has three pieces: a **style** declared in `document.yml`, a **collection** of bibliography records, and **inline cites** in the prose that reference those records by key.
+
+### Pick a style
+
+Set `book.citationStyle:` in `document.yml`. Nine styles ship statically wired — switch the document's whole bibliographic apparatus by changing one value:
+
+| Style                  | Inline shape       | Use case                                        |
+|------------------------|--------------------|-------------------------------------------------|
+| `chicago-author-date`  | (Darwin 1859, 42)  | Humanities, history, social sciences (default) |
+| `apa`                  | (Darwin, 1859)     | Psychology, education, social sciences          |
+| `mla`                  | (Darwin 42)        | Literature, modern languages                    |
+| `harvard`              | (Darwin 1859: 42)  | UK humanities, business                         |
+| `ieee`                 | [1, p. 42]         | Engineering, computer science                   |
+| `vancouver`            | (1)                | Medicine, biomedicine                           |
+| `ama`                  | ¹                  | Medical journals                                |
+| `nature`               | ¹                  | Nature journals                                 |
+| `science`              | (1)                | Science journals                                |
+
+Numbered styles (IEEE, Vancouver, Nature, Science, AMA) reuse the same numbering across inline cites and the back-matter list — `[1]` inline matches `[1]` in the back-matter.
+
+Optional sort: `book.bibliography.sortBy:` — `author` (default), `year`, or `collection-order`.
+
+### Author bibliography entries
+
+Drop a `.bib` file into `collections/bibliography/`. Every `@entry{key, ...}` becomes one record; the BibTeX cite key is the entry id you reference from prose with `[@key]`. Standard BibTeX entry types work (`@article`, `@book`, `@incollection`, `@inproceedings`, `@phdthesis`, `@techreport`, `@misc`, etc.); LaTeX accents (`\"u`, `\'e`, `\v{c}`) are converted to Unicode automatically.
+
+```bibtex
+% collections/bibliography/refs.bib
+
+@book{darwin1859,
+  author    = {Darwin, Charles},
+  title     = {On the Origin of Species},
+  publisher = {John Murray},
+  address   = {London},
+  year      = {1859}
+}
+
+@article{wallace1858,
+  author  = {Wallace, Alfred Russel},
+  title   = {On the Tendency of Varieties to Depart Indefinitely from the Original Type},
+  journal = {Journal of the Proceedings of the Linnean Society of London. Zoology},
+  volume  = {3},
+  number  = {9},
+  pages   = {53--62},
+  year    = {1858}
+}
+```
+
+If a record needs a CSL field BibTeX can't carry — multi-script titles, fine-grained date parts, fielded notes — drop a hand-written YAML file (CSL-JSON shape) into the same folder. The loader merges every `.bib`, `.yml`, and `.json` it finds, so authors can mix the format their reference manager exports with one-off hand-edited entries.
+
+```yaml
+# collections/bibliography/wallace1858.yml — full CSL-JSON, overrides if a duplicate
+# cite key exists in any .bib file in the same folder.
+id: wallace1858
+type: article-journal
+author:
+  - family: Wallace
+    given: Alfred Russel
+title: "On the Tendency of Varieties to Depart Indefinitely from the Original Type"
+container-title: "Journal of the Proceedings of the Linnean Society of London. Zoology"
+volume: 3
+issue: 9
+page: 53-62
+issued:
+  date-parts: [[1858]]
+```
+
+#### Common entry types
+
+| `type:` value           | What it is                                                            |
+|-------------------------|-----------------------------------------------------------------------|
+| `book`                  | Single-volume monograph (Darwin's *Origin*).                          |
+| `article-journal`       | Journal article (Mendel's *Versuche*).                                |
+| `article-magazine`      | Magazine article.                                                     |
+| `article-newspaper`     | Newspaper article.                                                    |
+| `chapter`               | Chapter in an edited volume — set `editor:` and `container-title:`.   |
+| `paper-conference`      | Conference proceedings.                                               |
+| `thesis`                | Dissertation or thesis — set `genre: PhD` / `Master's` if relevant.   |
+| `report`                | Technical or institutional report.                                    |
+| `webpage`               | Web page, blog post, or any URL-only source.                          |
+| `personal_communication`| Letter, email, interview.                                             |
+
+The full CSL 1.0.2 type list is at [docs.citationstyles.org](https://docs.citationstyles.org/en/stable/specification.html#appendix-iii-types). The foundation passes `type:` through to citestyle unchanged; any valid CSL type works.
+
+#### Common fields
+
+| Field                                                | Purpose                                                              |
+|------------------------------------------------------|----------------------------------------------------------------------|
+| `id`                                                 | Cite key (defaults to the filename stem).                            |
+| `type`                                               | One of the CSL types above.                                          |
+| `author`                                             | String (`"Last, First"`) or array of name objects (`[{family, given}]`). |
+| `editor`, `translator`, `container-author`           | Same shape as `author`.                                              |
+| `title`                                              | The work's title.                                                    |
+| `container-title`                                    | Journal name, edited-volume title, magazine.                         |
+| `publisher`, `publisher-place`                       | Publisher and city.                                                  |
+| `volume`, `issue`, `page`                            | Journal locators (string or number).                                 |
+| `year` (shorthand) or `issued: { date-parts: [[YYYY]] }` | Publication date.                                                |
+| `DOI`, `URL`, `ISBN`, `ISSN`, `PMID`                 | Identifiers — citestyle auto-links DOIs.                             |
+| `edition`, `genre`, `note`, `language`               | Misc fields most styles consume.                                     |
+
+### Cite in prose
+
+Inline citations use a Pandoc-style sugar that compiles to an inline inset. Five shapes cover the full range:
+
+| Markdown                          | Renders as (chicago-author-date)                          |
+|-----------------------------------|-----------------------------------------------------------|
+| `[@darwin1859]`                   | (Darwin 1859)                                             |
+| `[@darwin1859]{page=42}`          | (Darwin 1859, 42)                                         |
+| `[@darwin1859; @wallace1858]`     | (Darwin 1859; Wallace 1858)                               |
+| `[@darwin1859]{suppress-author}`  | (1859) — when "Darwin" already appears in the prose       |
+| `[@nope]`                         | [?] — visible placeholder, no compile failure             |
+
+The locator can be `page=42`, `chapter=3`, `section=2.1`, `paragraph=12`, etc. Set `label=<kind>` to label it explicitly: `[@darwin1859]{locator=2 label=chapter}` renders as `(Darwin 1859, chap. 2)` in styles that abbreviate the label.
+
+Multi-cite clusters collapse per the active style's rules. In chicago-author-date, two cites by the same author share the author and join their years with a comma: `[@darwin1859; @darwin1871]` renders as `(Darwin 1859, 1871)`.
+
+The `[@key]` shorthand desugars to `[@key](@Cite){k=v}` — the framework's textual inline-inset form. You can also call other inline insets directly with the same `[text](@Component){k=v}` syntax (see the foundation README).
+
+### The back-matter bibliography
+
+`content/99-bibliography.md` is a one-line back-matter section that lists every record from the collection in style-correct order:
+
+```markdown
+---
+type: Bibliography
+title: References
+data: bibliography
+---
+```
+
+The `data: bibliography` shorthand fetches from the collection of that name declared in `document.yml`. For numbered styles the entries appear in citation-encounter order; for author-date styles they're alphabetical by author then year.
+
+For collections of references that don't all need to ride together — say, a list of "further reading" separate from the main bibliography — declare a second collection in `document.yml` and reference it from a second `Bibliography` section with `data: <other-name>` and an optional `style: <override>`.
+
 ## `document.yml` fields
 
-Same shape as `book` (see [book.md](./book.md)). The differences are defaults:
+Same shape as `book` (see [book.md](./book.md)). The defaults differ:
+
+| Field                                | `monograph` default                                 |
+|--------------------------------------|------------------------------------------------------|
+| `book.trim`                          | `royal-octavo`                                       |
+| `book.typography.bodyFont`           | `["EB Garamond", "Garamond", "Georgia"]`             |
+| `book.typography.headingFont`        | `["EB Garamond", "Garamond", "Georgia"]`             |
+| `book.typography.bodySize`           | `10.5pt`                                             |
+| `book.typography.leading`            | `0.68em`                                             |
+| `book.structure.tocDepth`            | `3`                                                  |
+| `book.structure.frontMatterNumbering`| `roman`                                              |
+| `book.citationStyle`                 | `chicago-author-date`                                |
+| `book.bibliography.sortBy`           | `author`                                             |
+| `collections.bibliography.path`      | `collections/bibliography`                           |
+
+## Common customizations
 
-| Field                       | `monograph` default                                 |
-|-----------------------------|------------------------------------------------------|
-| `book.trim`                 | `royal-octavo`                                       |
-| `book.typography.bodyFont`  | `["EB Garamond", "Garamond", "Georgia"]`             |
-| `book.typography.headingFont`| `["EB Garamond", "Garamond", "Georgia"]`            |
-| `book.typography.bodySize`  | `10.5pt`                                             |
-| `book.typography.leading`   | `0.68em`                                             |
-| `book.structure.tocDepth`   | `3`                                                  |
-| `book.structure.frontMatterNumbering` | `roman`                                    |
+- **Switch citation style** by changing one line: `book.citationStyle: ieee` (or any of the nine styles above). Re-compile; every cite and the back-matter list re-formats to match.
+- **Add a "further reading" section** by declaring a second collection in `document.yml` (`collections.further-reading.path: collections/further-reading`) and a second `Bibliography` content file with `data: further-reading`.
+- **Drop the citations entirely** by deleting `99-bibliography.md`, the `collections/` directory, and the `book.citationStyle:` block. The remaining template behaves like a citation-free `book` with monograph typography.
 
 ## Foundation reference
 
-`@uniweb/book` — see the foundation's README: `framework/unipress/foundations/book/README.md`.
+`@uniweb/book` — see [foundations/book/README.md](https://github.com/uniweb/unipress/blob/main/foundations/book/README.md) for the full list of foundation knobs and `foundations/book/CHANGELOG.md` for the version history.

package/docs/templates/report.md

@@ -15,8 +15,7 @@ unipress compile . --format pdf --out q3-report.pdf
 ```
 q3-report/
 ├── document.yml          pinned to @uniweb/book@<version>; trade-7x10, block paragraphs
-├── pages/
-│   ├── folder.yml
+├── content/
 │   ├── 01-summary.md     executive summary + recommendations table
 │   ├── 02-findings.md    body, with code listing and pull-quote
 │   └── 03-methodology.md
@@ -46,7 +45,7 @@ Same shape as `book` (see [book.md](./book.md)). The differences are defaults:
 
 ## Common customizations
 
-- **Add an appendix**: a new markdown file with `type: BackMatter` in frontmatter, listed in `pages:`.
+- **Add an appendix**: a new markdown file with `type: BackMatter` in frontmatter, listed in `content:`.
 - **Wider code blocks**: bump `book.typography.codeMarginRelief` to `0.5in` (code extends 0.5in past each side of the body column).
 - **No TOC** for short reports: set `book.structure.toc: false`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/unipress",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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/build": "0.11.2",
-    "@uniweb/runtime": "0.8.4",
-    "@uniweb/core": "0.7.3",
-    "@uniweb/content-reader": "1.1.5",
-    "@uniweb/semantic-parser": "1.1.11"
+    "@uniweb/build": "0.11.4",
+    "@uniweb/runtime": "0.8.6",
+    "@uniweb/semantic-parser": "1.1.13",
+    "@uniweb/core": "0.7.5",
+    "@uniweb/content-reader": "1.1.7"
   },
   "scripts": {
     "test": "echo \"no tests yet\" && exit 0",

package/src/content-loader.js

@@ -10,10 +10,108 @@
 
 import { existsSync } from 'node:fs'
 import { resolve, join } from 'node:path'
-import { collectSiteContent } from '@uniweb/build/content'
+import { collectSiteContent, processCollections } from '@uniweb/build/content'
 import { detectConfigFile, CONFIG_FILE_NAMES } from './document-yml.js'
 import { ContentDirectoryError, DocumentYmlError } from './errors.js'
 
+// Match a parsed collection-backed fetch path. parseFetchConfig (in
+// @uniweb/build) normalises `{ collection: <name> }` into
+// `{ path: '/data/<name>.json', schema: <name>, ... }` — so this regex is
+// the inverse: pull the collection name back out of the resolved path.
+const COLLECTION_PATH_RE = /^\/data\/(.+)\.json$/
+
+function attachData(section, schema, data) {
+  if (!section || !schema) return
+  if (!section.parsedContent) section.parsedContent = {}
+  if (!section.parsedContent.data) section.parsedContent.data = {}
+  // Don't clobber a section-level value with a cascaded page-level one.
+  // The Block constructor will spread parsedContent.data through, so the
+  // first writer wins for a given schema.
+  if (section.parsedContent.data[schema] === undefined) {
+    section.parsedContent.data[schema] = data
+  }
+}
+
+function findCollectionRecords(fetchConfig, resolved) {
+  if (!fetchConfig?.path || !fetchConfig?.schema) return null
+  const m = COLLECTION_PATH_RE.exec(fetchConfig.path)
+  if (!m) return null
+  const records = resolved[m[1]]
+  if (!Array.isArray(records)) return null
+  return records
+}
+
+function attachSectionFetches(sections, resolved) {
+  if (!Array.isArray(sections)) return
+  for (const section of sections) {
+    const records = findCollectionRecords(section.fetch, resolved)
+    if (records) attachData(section, section.fetch.schema, records)
+    if (Array.isArray(section.subsections) && section.subsections.length) {
+      attachSectionFetches(section.subsections, resolved)
+    }
+  }
+}
+
+/**
+ * Materialize file-based collections into each section's
+ * `parsedContent.data` so the SSR render pipeline reads populated data
+ * synchronously (no `useFetched` round-trip; no `public/` directory).
+ *
+ * In a regular Uniweb site build, the Vite plugin runs `processCollections`
+ * + `writeCollectionFiles` and the runtime resolves `fetch:` declarations
+ * over HTTP at render time. Under `unipress compile` neither of those
+ * happens — there's no public dir, and SSR skips effects. We close the
+ * gap by resolving collections in-memory and attaching the records
+ * directly to each block's `parsedContent.data.<schema>`. The Block
+ * constructor (framework/core/src/block.js) preserves that field, and
+ * `prepareProps` then surfaces it as `content.data.<schema>` to the
+ * component — same shape the runtime would produce.
+ *
+ * Page-level fetch cascades to every section on the page; section-level
+ * fetch overrides on a per-section basis. Only collection-backed fetches
+ * (parsed `path: '/data/<name>.json'`) are resolved here — remote URL
+ * fetches, refine configs, and array-form `fetch: [...]` declarations
+ * are left untouched (those have their own gaps; out of scope here).
+ */
+async function resolveLocalCollections(siteContent, sitePath) {
+  const collectionsConfig = siteContent?.config?.collections
+  if (!collectionsConfig || typeof collectionsConfig !== 'object') return
+  if (Object.keys(collectionsConfig).length === 0) return
+
+  const resolved = await processCollections(
+    sitePath,
+    collectionsConfig,
+    sitePath,
+    '/',
+  )
+
+  for (const page of siteContent.pages || []) {
+    const pageRecords = findCollectionRecords(page.fetch, resolved)
+    if (pageRecords) {
+      for (const section of page.sections || []) {
+        attachData(section, page.fetch.schema, pageRecords)
+      }
+    }
+    attachSectionFetches(page.sections, resolved)
+  }
+
+  // Stash the resolved arrays on the website config too, so any section
+  // (regardless of its own page's fetch declaration) can self-bootstrap
+  // — e.g., a Cite inset rendering inside a Chapter on page A needs the
+  // bibliography records that the Bibliography section declared on page
+  // B. Foundations read this via `block.website.config.collections.<name>.records`
+  // as a synchronous fallback.
+  if (!siteContent.config) siteContent.config = {}
+  if (!siteContent.config.collections) siteContent.config.collections = {}
+  for (const name of Object.keys(resolved)) {
+    const existing = siteContent.config.collections[name]
+    siteContent.config.collections[name] = {
+      ...(existing && typeof existing === 'object' ? existing : {}),
+      records: resolved[name],
+    }
+  }
+}
+
 export async function loadContent(dir, options = {}) {
   const sitePath = resolve(dir)
 
@@ -52,5 +150,11 @@ export async function loadContent(dir, options = {}) {
     throw err
   }
 
+  await resolveLocalCollections(content, sitePath)
+
+  // Cross-reference registry is built AFTER the foundation loads, in
+  // orchestrator.loadAndInit, so foundation-declared `xref.kinds`
+  // contribute to the kind inference at id-collection time.
+
   return { content, configFile, sitePath }
 }

package/src/foundations-data.js

@@ -72,8 +72,8 @@ function publicUrl(name, version) {
 }
 
 const BOOK_FOUNDATION = {
-  ref: '@uniweb/book@0.1.1',
-  source: { url: publicUrl('book', '0.1.1') },
+  ref: '@uniweb/book@0.2.0',
+  source: { url: publicUrl('book', '0.2.0') },
 }
 
 const DATA_FOUNDATION = {

package/src/orchestrator.js

@@ -30,6 +30,26 @@ import { readFile } from 'node:fs/promises'
 import { initPrerender } from '@uniweb/runtime/ssr'
 import { FoundationResolutionError, CompileError } from './errors.js'
 
+// `buildXrefRegistry` is a recent addition to @uniweb/build/content
+// (cross-references milestone). Older published versions don't expose
+// it; the dynamic resolver below falls back to a no-op registry so the
+// pipeline keeps working against any installed version. Once the build
+// package republishes with the new export, the real registry kicks in
+// automatically — no code change required.
+let _buildXrefRegistry = null
+async function getBuildXrefRegistry() {
+  if (_buildXrefRegistry !== null) return _buildXrefRegistry
+  try {
+    const mod = await import('@uniweb/build/content')
+    _buildXrefRegistry = typeof mod.buildXrefRegistry === 'function'
+      ? mod.buildXrefRegistry
+      : () => ({ entries: {} })
+  } catch {
+    _buildXrefRegistry = () => ({ entries: {} })
+  }
+  return _buildXrefRegistry
+}
+
 export async function importFoundation(resolvedPath) {
   try {
     return await import(pathToFileURL(resolvedPath).href)
@@ -49,8 +69,22 @@ export function initOrchestrator({ content, foundation, extensions = [], onProgr
 // Convenience: import + init in one step. Returns the uniweb instance,
 // or throws (the caller decides whether to surface as fatal or attached
 // to the inspect dump).
+//
+// Cross-reference registry is built here, after the foundation imports
+// so any foundation-declared `xref.kinds` participate in id-collection.
+// Built-in kinds (figure / equation / section / table) work without
+// foundation cooperation; foundation extensions land alongside.
 export async function loadAndInit({ content, resolvedPath, extensions = [], onProgress } = {}) {
   const foundation = await importFoundation(resolvedPath)
+
+  const foundationKinds =
+    foundation?.default?.capabilities?.xref?.kinds ||
+    foundation?.default?.xref?.kinds ||
+    foundation?.xref?.kinds ||
+    {}
+  const buildXrefRegistry = await getBuildXrefRegistry()
+  content.xref = buildXrefRegistry(content, { foundationKinds })
+
   const uniweb = initOrchestrator({ content, foundation, extensions, onProgress })
   return { foundation, uniweb }
 }