@uniweb/press 0.3.0 → 0.4.1

package/README.md

@@ -1,76 +1,53 @@
 # @uniweb/press
 
-**Alternate outputs from Uniweb content.** A Uniweb site is pure content — markdown files, parsed into a guaranteed shape, delivered to React components. Press is a framework that lets foundations turn that content into downloadable files (Word, Excel, PDF, anything else) using the same section components that render the website. One source, many outputs.
+**Downloadable files from Uniweb content.** A Uniweb site is, in a useful sense, a URL that represents a document — titles, paragraphs, tables, lists, tagged data blocks, all already parsed and available to section components. Press lets those same section components turn that content into downloadable files: Word documents, spreadsheets, typeset PDFs, and whatever else a foundation wants to support. One source, many outputs.
 
 ```bash
 npm install @uniweb/press
 ```
 
-## Why
+## What Press is
 
-A Uniweb site is, in a useful sense, a URL that represents a document. Titles, paragraphs, tables, lists, tagged data blocks — all already parsed, all already available to section components. With Loom and dynamic data fetching, that document can be live and hierarchical: a report whose sections instantiate against a CV profile, a publication list that updates automatically, a program whose entries are filtered per department. The content is right there.
+Press is the **output layer of the Uniweb ecosystem**. It's a small registration layer (what section components call into to opt in to a format) plus a set of format adapters (the things that know how to produce `.docx`, `.typ`, `.xlsx` files). The registration layer is format-agnostic; the adapters are format-specific and dynamic-loaded, so a foundation only pays for the formats it actually offers.
 
-Press is the output layer of that system. It gives foundations:
+The core insight that makes Press tractable is that Uniweb has already done the semantic work. Press doesn't parse markdown, resolve Loom expressions, or fetch data — by the time a section component renders, `content.paragraphs`, `content.title`, and everything else are already concrete values. Press just walks what's there and emits.
 
-- A **registration hook** (`useDocumentOutput`) so a section component can say "here is what I produce for this format."
-- A **compile hook** (`useDocumentCompile`) that walks all registered sections in a page and produces a `Blob` for the requested format.
-- A **download utility** (`triggerDownload`) for saving the Blob to a file.
-- A **docx toolkit** — React builder components and a lazy-loaded format adapter — for the most common output format.
+Three properties follow from that design:
 
-The core is **format-agnostic**. Press ships a docx toolkit today, and xlsx and pdf toolkits are on the roadmap. But you can use Press right now to generate any format you want by writing your own adapter against `@uniweb/press/ir`. Press is a framework for alternate outputs; the docx toolkit is one implementation of it.
-
-## Ways to use it
-
-Press doesn't prescribe what the site is *for*. Three shapes are all first-class, and you pick based on what you're building. See [concepts](./docs/concepts.md) for the full discussion.
-
-**1. Interactive report + downloads.** A live web document — navigable, themed, possibly with dynamic data and Loom-instantiated content — that also offers one or more download buttons. Readers browse on screen; those who need a file click Download. This is the flagship case for annual reports, CVs, program guides, and anything else that wants to exist as both a URL and a document.
-
-**2. Multi-format exports.** The same site registers fragments for several formats at once — docx for the narrative, xlsx for the tabular data, a custom JSON export for machine consumers. Each section chooses which formats it contributes to. Compilation is per-format and lazy: a user clicks "Download xlsx" and only the xlsx adapter loads.
-
-**3. Headless export.** Sections register fragments and return `null`. The site has no visible output — it exists purely as a compile target for an automated pipeline, an admin tool, or a generator UI whose only job is to produce files. Press works here because registration is decoupled from rendering; a component that returns `null` still contributes to `compile()`.
-
-For cases 1 and 2, you also choose **how the preview works**:
-
-- **JSX-as-preview (recommended).** Press's `/docx` builder components emit ordinary HTML (`<p>`, `<h1>`, `<span>` with `data-*` attributes). The exact same JSX serves as the browser preview *and* as the source the compile pipeline walks. One tree, zero drift, no extra library. Your section is already rendering JSX — using Press builders costs nothing more. You can also split: Kit components for a richer themed preview, Press builders for the registered docx fragment, mirroring the same structure.
-- **Compiled-blob preview via `docx-preview`.** Instead of previewing the *content*, preview the *compiled file*. Render whatever you want (or nothing) in the component, then feed the Blob from `compile('docx')` into [`docx-preview`](https://github.com/VolodymyrBaydalka/docxjs) inside a sandboxed iframe to see Word's actual formatting. Useful as a cross-check view or when the downloaded file's exact appearance matters more than a browseable web view. Pays the `docx-preview` library cost; see the [preview pattern guide](./docs/guides/preview-pattern.md).
-
-The two strategies compose — a foundation can do JSX-as-preview for normal reading and *also* offer a "Preview compiled file" button that opens the docx-preview iframe.
+- **Same source, many outputs.** The JSX a section renders for the browser can be the *same* JSX Press compiles into a Word doc or a PDF. No duplication, no drift between preview and file.
+- **Frontend-first.** Most formats compile entirely in the browser. When a format needs a backend (Typst PDFs, future LaTeX), it's an escape hatch — not the architecture.
+- **Additive formats.** Adding a new format is a new adapter module plus an entry in a map. Nothing else in Press needs to change.
 
 ## Hello world
 
-A Uniweb section component that renders both a preview and a registered docx fragment from the same JSX:
+A section component that renders as a preview *and* registers itself for docx compilation, using the same JSX for both:
 
 ```jsx
-// src/sections/Cover/index.jsx
 import { useDocumentOutput } from '@uniweb/press'
 import { H1, H2, Paragraphs } from '@uniweb/press/docx'
 
 function Cover({ content, block }) {
-    const { title, subtitle, paragraphs } = content
-
     const body = (
         <>
-            <H1 data={title} />
-            <H2 data={subtitle} />
-            <Paragraphs data={paragraphs} />
+            <H1 data={content.title} />
+            <H2 data={content.subtitle} />
+            <Paragraphs data={content.paragraphs} />
         </>
     )
 
     useDocumentOutput(block, 'docx', body)
 
-    return <div className="max-w-4xl mx-auto">{body}</div>
+    return <div className='max-w-4xl mx-auto'>{body}</div>
 }
-
-export default Cover
 ```
 
-A few things to notice:
+A few things worth noticing:
 
-- **Standard Uniweb section shape.** `{ content, block }` destructured. `content.paragraphs` is a guaranteed array — empty if there are none, never null. No outer `<section>` wrapper, because the Uniweb runtime wraps every section in `<section>` with the right context class and background.
-- **Same JSX, two consumers.** `body` is used twice: registered for docx compilation and rendered into the visible layout. There is no duplication to drift between them.
-- **Any section is opt-in.** Sections that don't call `useDocumentOutput` are never included in the compiled document. The hook is a no-op when called outside a provider, so you can freely mix opt-in and non-opt-in sections in the same page.
+- The `body` variable is used twice — registered for docx compilation and rendered into the visible layout. No duplication to drift between them.
+- `useDocumentOutput` is a no-op outside a `DocumentProvider`, so sections that don't opt into docx simply don't contribute. Mixing opt-in and non-opt-in sections on the same page is fine.
+- The `/docx` builders (`H1`, `H2`, `Paragraphs`, etc.) emit ordinary HTML with `data-*` attributes. The same tree serves as the browser preview and as the source the compile pipeline walks.
 
-Somewhere higher in the tree (a layout, a header, a dedicated "download" section), add a `<DocumentProvider>` and a button that calls `compile`:
+Somewhere higher in the tree — a layout, a header, a dedicated download section — wrap everything in a `DocumentProvider` and wire up a button:
 
 ```jsx
 import {
@@ -83,17 +60,19 @@ function ReportLayout({ children }) {
     return (
         <DocumentProvider>
             {children}
-            <DownloadControls />
+            <DownloadButton />
         </DocumentProvider>
     )
 }
 
-function DownloadControls() {
+function DownloadButton() {
     const { compile, isCompiling } = useDocumentCompile()
+
     const handleDownload = async () => {
         const blob = await compile('docx', { title: 'Annual Report' })
         triggerDownload(blob, 'annual-report.docx')
     }
+
     return (
         <button onClick={handleDownload} disabled={isCompiling}>
             {isCompiling ? 'Generating…' : 'Download'}
@@ -102,75 +81,97 @@ function DownloadControls() {
 }
 ```
 
-Every section between the provider and the button that called `useDocumentOutput` contributes its registered fragment to the compiled document. The rest is ignored. The docx library itself is loaded dynamically on the first `compile('docx')` call, not at page load.
+Every section between the provider and the button that called `useDocumentOutput('docx', ...)` contributes to the compiled document. The docx library itself is loaded dynamically on the first `compile('docx')` call — it's never in the main bundle.
 
-## Documentation
+For a fuller walkthrough, see the [quick start](./docs/quick-start.md).
+
+## What's shipped
 
-Start here:
+Press ships three format adapters today:
 
-- **[Quick start](./docs/quick-start.md)** — Ten minutes from `npm install` to a working Download button, with a live preview.
-- **[Concepts](./docs/concepts.md)** — Why Press exists, the registration pattern, the four ways to combine preview and compiled output, why compile is separate from download, why the docx toolkit is just a toolkit.
+- **docx** — Word documents via the [`docx`](https://docx.js.org) library. Paragraphs, headings, text runs, tables, lists, images, hyperlinks, headers/footers, page numbering. The flagship format.
+- **typst** — Typeset PDFs via the [Typst](https://typst.app) compiler. Same-source preview from `/typst` builders; whole-book compile via `compileSubtree`; `sources` mode (pure frontend, user compiles locally) and `server` mode (via a companion endpoint — see [deployment.md](./docs/architecture/deployment.md)).
+- **xlsx** — Spreadsheets via `exceljs`. Plain `{ title, headers, data }` objects, multi-sheet, preview and compiled output independent (because spreadsheets aren't typography).
 
-API reference:
+For what's next (Paged.js for browser-paginated PDFs, EPUB, slides, and a handful of speculative formats) see the [format roadmap](./docs/architecture/format-roadmap.md). For writing a custom adapter against an unsupported format, see the [custom adapter guide](./docs/guides/custom-adapter.md).
 
-- **[Core](./docs/api/core.md)** — `DocumentProvider`, `useDocumentOutput`, `useDocumentCompile`, `triggerDownload`.
-- **[/docx](./docs/api/docx.md)** — Every builder component with runnable examples.
-- **[/sections](./docs/api/sections.md)** — `Section` and `StandardSection` — higher-level templates intended for non-Uniweb contexts where you need an explicit section wrapper.
-- **[/ir](./docs/api/ir.md)** — IR layer for custom format adapters.
+## Three ways to use Press
 
-Guides:
+Press doesn't prescribe what the site is *for*. Three shapes are all first-class:
 
-- **[Publishing a book](./docs/guides/book-publishing.md)** — Whole-site aggregation, three compile modes (sources / server / wasm roadmap), the Vite dev plugin, and the two web modalities (same-JSX preview vs its-own-medium web UX).
-- **[The preview pattern](./docs/guides/preview-pattern.md)** — Render a compiled `.docx` back into a sandboxed iframe via `docx-preview` as a cross-check view, separate from the per-component React preview.
-- **[Multi-block reports](./docs/guides/multi-block-reports.md)** — How `DocumentProvider` aggregates output across many section components into one document.
-- **[Writing a custom adapter](./docs/guides/custom-adapter.md)** — Build a non-docx format adapter using `@uniweb/press/ir`.
-- **[Citations](./docs/guides/citations.md)** — The `citestyle` + Press pattern for bibliographies in preview and docx.
-- **[Style pack](./docs/guides/style-pack.md)** — Copy-paste `paragraphStyles` and `numbering` definitions for hanging-indent and numbered bibliography entries.
+**Interactive report with downloads.** A live web document — navigable, themed, possibly with dynamic data — that also offers one or more Download buttons. Readers browse on screen; those who need a file click Download. The flagship case: annual reports, CVs, research outputs.
 
-Migration:
+**Multi-format exports.** The same site registers fragments for several formats. A report section might contribute to docx (for the narrative) and xlsx (for the underlying data); a cover might contribute only to docx. Compilation is per-format and lazy — only the adapter you click loads.
 
-- **[Migration from phase 1](./docs/migration-from-phase-1.md)** — For readers holding phase-1 examples with `@uniweb/press/react` and `DownloadButton`.
+**Headless export.** Sections register fragments and return `null`. The site has no visible output and exists purely as a compile target for an automated pipeline, admin tool, or generator UI. Press works here because registration is decoupled from rendering.
 
-There is also a runnable demo at [`examples/preview-iframe/`](./examples/preview-iframe/) — a minimal standalone Vite app exercising the compile + preview + download flow end to end. It's not a Uniweb foundation; it's a plain React app demonstrating that Press works outside Uniweb as well.
+For how these shapes interact with preview strategies (same-source JSX vs compiled-blob), and the fuller mental model, see [concepts](./docs/concepts.md).
+
+## Books and whole-site compilation
+
+The patterns above cover one-page documents. For books — where the download's scope is *every chapter*, not just the current page — Press provides `compileSubtree`:
+
+```js
+await compileSubtree(<ChildBlocks blocks={website.allBlocks} />, 'typst')
+```
+
+This renders the whole content graph off-screen through its own provider, gathers every registration, and compiles. No page routing, no DOM mounts. See the [book publishing guide](./docs/guides/book-publishing.md) for the end-to-end flow.
 
 ## Subpath exports
 
 | Entry point | What's in it |
 |---|---|
-| `@uniweb/press` | `DocumentProvider`, `useDocumentOutput`, `useDocumentCompile`, `triggerDownload`, `createStore`, `compileRegistrations`, `compileSubtree` — the format-agnostic core |
-| `@uniweb/press/docx` | React builder components for docx output (`Paragraph`, `TextRun`, `H1`–`H4`, `Image`, `Link`, `List`, …) |
-| `@uniweb/press/typst` | React builder components for Typst output (`ChapterOpener`, `Heading`, `Paragraph`, `CodeBlock`, `List`, `Table`, `BlockQuote`, `Image`, `Asterism`, `Raw`, `Sequence`, …) |
-| `@uniweb/press/sections` | `Section` and `StandardSection` — register-and-render helpers that include their own `<section>` wrapper (for non-Uniweb React contexts) |
-| `@uniweb/press/ir` | IR utilities (`htmlToIR`, `attributeMap`, `compileOutputs`) for custom-adapter authors |
-| `@uniweb/press/vite-plugin-typst` | Dev-server Vite plugin that answers the Typst `server` compile mode by running `typst compile` locally and streaming back a PDF |
+| `@uniweb/press` | Core: `DocumentProvider`, `useDocumentOutput`, `useDocumentCompile`, `triggerDownload`, `createStore`, `compileRegistrations`, `compileSubtree` |
+| `@uniweb/press/docx` | React builders for docx (`Paragraph`, `TextRun`, `H1`–`H4`, `Image`, `Link`, `List`, …) |
+| `@uniweb/press/typst` | React builders for Typst (`ChapterOpener`, `Heading`, `Paragraph`, `CodeBlock`, `Table`, `BlockQuote`, `Image`, `Asterism`, `Raw`, `Sequence`, …) |
+| `@uniweb/press/sections` | `Section` and `StandardSection` — register-and-render helpers with their own `<section>` wrapper (for non-Uniweb React contexts) |
+| `@uniweb/press/ir` | IR utilities (`htmlToIR`, `attributeMap`, `compileOutputs`) for custom adapter authors |
+| `@uniweb/press/vite-plugin-typst` | Dev-server Vite plugin answering Typst `server` compile mode locally |
+
+Format adapters themselves (`compileDocx`, `compileTypst`, `compileXlsx`, and the libraries they depend on) are deliberately **not** in the `exports` field. They're reached only through the dynamic `import()` inside `useDocumentCompile`, which keeps multi-megabyte libraries out of the main bundle.
+
+## Documentation
+
+**Start here:**
+
+- [Concepts](./docs/concepts.md) — the mental model: why Press exists, the registration pattern, preview strategies, how to think about fragments. Read this if you're deciding how Press fits into a foundation.
+- [Quick start](./docs/quick-start.md) — ten minutes from `npm install` to a working Download button, with a live preview.
+
+**Guides:**
 
-The ~3.4 MB `docx` library is never pulled into the main bundle. It's loaded dynamically the first time `compile('docx')` runs.
+- [Publishing a book](./docs/guides/book-publishing.md) — whole-site aggregation via `compileSubtree`, the Typst pipeline, the two web modalities.
+- [The preview pattern](./docs/guides/preview-pattern.md) — render a compiled `.docx` back into a sandboxed iframe via `docx-preview` for high-fidelity cross-check views.
+- [Multi-block reports](./docs/guides/multi-block-reports.md) — how `DocumentProvider` aggregates output across many section components into one document.
+- [Writing a custom adapter](./docs/guides/custom-adapter.md) — build a non-shipped format adapter using `@uniweb/press/ir`.
+- [Citations](./docs/guides/citations.md) — bibliographies in preview and docx via the `citestyle` + Press pattern.
+- [Style pack](./docs/guides/style-pack.md) — copy-paste `paragraphStyles` and `numbering` definitions for common bibliography patterns.
 
-## Shipped toolkits and roadmap
+**Architecture and design:**
 
-Press separates the **framework** (registration, compile, download) from the **toolkits** (per-format React builders and adapters). The framework is stable and usable today for any format. The toolkits are the shipped conveniences:
+- [Principles](./docs/architecture/principles.md) — the architectural commitments Press is built on. Read before proposing any change that touches the public surface or introduces a new format.
+- [Overview](./docs/architecture/overview.md) — how Press is put together under the hood, for contributors orienting to the codebase.
+- [Adding a format](./docs/architecture/adding-a-format.md) — worked examples (LaTeX, Paged.js) and the general checklist.
+- [Deployment](./docs/architecture/deployment.md) — wire protocol, reference implementations, and operational concerns for formats that need a backend.
+- [Format roadmap](./docs/architecture/format-roadmap.md) — what's shipped, what's next, what's speculative.
 
-| Toolkit | Status | Notes |
-|---|---|---|
-| **docx** | ✅ Shipped | Paragraphs, headings, text runs, tables, borders/margins/widths, bullet/numbered lists, hyperlinks, images with async fetch, page numbering, default headers/footers, `firstPageOnly` semantics. Uses the [`docx`](https://docx.js.org) library. |
-| **typst** | ✅ Shipped | Whole-book compile via `compileSubtree`, two compile modes (`sources` ZIP + `server` PDF via included Vite dev plugin), 12 builders + `Sequence` walker. Produces real PDFs through the [Typst](https://typst.app) compiler. See [Publishing a book](./docs/guides/book-publishing.md). |
-| **xlsx** | 🔜 Roadmap | Plain `{ title, headers, data }` objects, multi-sheet. Different shape from docx because spreadsheets aren't typography. |
-| **pdf** | 🔜 Roadmap | Either docx JSX via Paged.js or `@react-pdf/renderer` for fine control. Decision deferred. |
+**Runnable example:**
 
-Writing a custom adapter (Markdown, RTF, a domain-specific XML, a JSON export) is supported today via `@uniweb/press/ir`. See the [custom adapter guide](./docs/guides/custom-adapter.md).
+- [`examples/preview-iframe/`](./examples/preview-iframe/) — a minimal standalone Vite app demonstrating compile + preview + download end to end. Not a Uniweb foundation; a plain React app demonstrating that Press works outside Uniweb as well.
 
 ## See also
 
-- [`@uniweb/loom`](https://github.com/uniweb/loom) — A small expression language for weaving data into text. The typical Uniweb report foundation uses a content handler that runs Loom's `instantiateContent` over the parsed content tree, resolving placeholders against live data before Press ever sees the section — which means dynamic reports look identical to static ones from Press's point of view.
-- [`@uniweb/kit`](https://github.com/uniweb/kit) — React components and hooks for building Uniweb foundations. The preview side of a Press-aware component typically uses Kit for theme-aware typography (`H1`, `H2`, `P`, `Prose`, `ChildBlocks`, `Visual`, etc.) alongside Press's builder components for the compiled output. See the [concepts doc](./docs/concepts.md) for the "same JSX vs separate preview" discussion.
+- [`@uniweb/loom`](https://github.com/uniweb/loom) — expression language for weaving data into text. A typical Uniweb report foundation runs Loom's `instantiateContent` over the parsed content tree *before* Press sees it, which means dynamic reports look identical to static ones from Press's point of view.
+- [`@uniweb/kit`](https://github.com/uniweb/kit) — React components and hooks for Uniweb foundations. Preview-side typography often uses Kit components alongside Press builders for compiled output.
 
 ## Status
 
-**Pre-1.0, unpublished.** The registration architecture, builder components, section templates, IR layer, and docx adapter are stable and covered by 133 tests. The public surface is expected to hold through 1.0. xlsx and pdf toolkits are on the roadmap.
+**Pre-1.0, published on npm.** The registration architecture, builder components, section templates, IR layer, and the docx, typst, and xlsx adapters are stable; the public surface is expected to hold through 1.0.
+
+Releases go through the workspace publish pipeline. Breaking changes are acceptable when justified, but each release is a published artifact — the `exports` field and documented subpaths stay coherent across versions.
 
 ## Development
 
-Press ships raw source — there is no build step. Edits in `src/` are immediately effective in any linked workspace package.
+Press ships raw source with no build step. Edits in `src/` are immediately effective in any linked workspace package.
 
 ```bash
 pnpm test           # vitest run — full suite
@@ -179,9 +180,7 @@ pnpm test tests/docx/                # one directory
 pnpm test -t 'inline marks'          # by test name
 ```
 
-Test layout mirrors `src/`: `tests/core/`, `tests/docx/`, `tests/sections/`, `tests/ir/`, plus `tests/integration/` for end-to-end cases.
-
-To run the preview-iframe demo:
+To run the `preview-iframe` demo:
 
 ```bash
 cd examples/preview-iframe
@@ -189,10 +188,8 @@ pnpm install
 pnpm dev
 ```
 
-It registers three sections in a `DocumentProvider` and exposes Preview (compiles and renders via `docx-preview` into a sandboxed iframe) and Download (compiles and calls `triggerDownload`) buttons.
-
-**Adding a builder component, format adapter, or section helper:** see `CLAUDE.md` for the runbooks.
+For contributor conventions — adding a builder, format adapter, or section helper; the docx image-emission invariants; testing patterns — see [`CLAUDE.md`](./CLAUDE.md).
 
 ## License
 
-Apache-2.0 — see [LICENSE](./LICENSE).
+Apache-2.0 — see [LICENSE](./LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/press",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Press your React components into downloadable files — Word, Excel, PDF. Registration-based pattern with lazy-loaded format adapters.",
   "type": "module",
   "exports": {
@@ -50,9 +50,7 @@
   "devDependencies": {
     "@testing-library/react": "^16.0.0",
     "jsdom": "^25.0.0",
-    "vitest": "^2.0.0",
-    "@uniweb/semantic-parser": "1.1.9",
-    "@uniweb/content-reader": "1.1.4"
+    "vitest": "^2.0.0"
   },
   "scripts": {
     "test": "vitest run",

package/src/adapters/dispatch.js

@@ -7,35 +7,80 @@
  * package.json's exports field. Callers must go through runCompile(...)
  * so the dynamic-import stays the only path — which is how the ~3.4 MB
  * docx library (and any future WASM runtime) stays out of the main bundle.
+ *
+ * ## Descriptor shape
+ *
+ * Each adapter is described by a triple:
+ *
+ *   { load, consumes, ir }
+ *
+ *   load     — () => import('./<adapter>.js'). Dynamic-imported only.
+ *   consumes — the store key foundations register fragments under. May
+ *              differ from the output format name. Paged.js compiles
+ *              'pagedjs' output but reads fragments registered under
+ *              'html'; future EPUB will do the same. (See principle 6's
+ *              "When the generalization is already earned" carve-out in
+ *              docs/architecture/principles.md — this split was introduced
+ *              with the first HTML-string adapter rather than deferred.)
+ *              When omitted, defaults to the format name (self-aliased).
+ *   ir       — true for HTML-based adapters that walk each fragment into
+ *              the IR tree (docx, typst). false for passthrough adapters
+ *              that consume rendered HTML strings (pagedjs) or plain data
+ *              objects (xlsx). Drives the compile-pipeline branch in
+ *              src/ir/compile.js without per-format if-ladders.
+ *
+ * Output format names (keys of ADAPTERS) are the public contract — what
+ * callers pass to compileSubtree / useDocumentCompile.compile. Input shape
+ * names (values of `consumes`) are the contract between the registration
+ * store and the adapter; foundations register under these.
  */
 
-// Dynamic-import loaders keyed by format. Each loader resolves to a
-// module exporting compile<Format>(compiledInput, documentOptions) → Blob.
+/** @type {Record<string, { load: () => Promise<any>, consumes?: string, ir?: boolean }>} */
 const ADAPTERS = {
-    docx: () => import('./docx.js'),
-    xlsx: () => import('./xlsx.js'),
-    typst: () => import('./typst.js'),
-    // Phase 3: pdf:  () => import('./pdf.js'),
+    docx: { load: () => import('./docx.js'), consumes: 'docx', ir: true },
+    xlsx: { load: () => import('./xlsx.js'), consumes: 'xlsx', ir: false },
+    typst: { load: () => import('./typst.js'), consumes: 'typst', ir: true },
+    // Paged.js consumes 'html' — an input shape shared with EPUB below.
+    // Foundations register once under 'html' and both adapters read it.
+    pagedjs: { load: () => import('./pagedjs.js'), consumes: 'html', ir: false },
+    epub: { load: () => import('./epub.js'), consumes: 'html', ir: false },
+}
+
+/**
+ * Look up an adapter descriptor by output-format name. Returns null when
+ * the format is unknown — callers decide how to surface that (runCompile
+ * throws; compileOutputs warns and returns an empty-shape input).
+ */
+export function getAdapterDescriptor(format) {
+    const desc = ADAPTERS[format]
+    if (!desc) return null
+    return {
+        load: desc.load,
+        consumes: desc.consumes || format,
+        ir: desc.ir !== false, // default to true for safety on under-specified entries
+    }
 }
 
 /**
  * Run the format adapter against already-compiled input.
  *
- * @param {string} format - 'docx' | 'xlsx' | 'typst' | …
+ * @param {string} format - 'docx' | 'xlsx' | 'typst' | 'pagedjs' | …
  * @param {Object} compiledInput - Output of compileOutputs(store, format).
  * @param {Object} [documentOptions] - Adapter-specific options.
  * @returns {Promise<Blob>}
  */
 export async function runCompile(format, compiledInput, documentOptions = {}) {
-    const loader = ADAPTERS[format]
-    if (!loader) {
+    const desc = getAdapterDescriptor(format)
+    if (!desc) {
         throw new Error(`Unsupported document format: "${format}"`)
     }
-    const adapter = await loader()
+    const adapter = await desc.load()
     const compileFn =
         adapter.compileDocx ||
         adapter.compileXlsx ||
         adapter.compileTypst ||
+        adapter.compilePagedjs ||
+        adapter.compileEpub ||
         adapter.compilePdf
     if (!compileFn) {
         throw new Error(

package/src/adapters/docx.js

@@ -44,6 +44,7 @@ import {
     Bookmark,
     FootnoteReferenceRun,
 } from 'docx'
+import { fetchAsset } from '../assets/fetch.js'
 
 // ============================================================================
 // Public API
@@ -84,12 +85,20 @@ export async function compileDocx(input, options = {}) {
  *   - numbering: Array<NumberingConfig> — numbering definitions that
  *     paragraphs can reference via `data-numbering-reference="…"`.
  *     Passed through to `new Document({ numbering: { config } })`.
+ *   - pageMargin: Object — page margin overrides, merged into the
+ *     section's `properties.page.margin`. Shape matches the docx
+ *     library's `IPageMarginAttributes` — all keys are twips (1 inch =
+ *     1440): `top`, `right`, `bottom`, `left`, `header`, `footer`,
+ *     `gutter`, `mirror`. The `header` and `footer` margins define the
+ *     *carrier-paragraph* slot used by registered headers/footers; set
+ *     both to a non-zero value or floating anchors inside those slots
+ *     may be dropped. Omit to keep the docx library's defaults.
  *   - Any other key (title, subject, creator, description, keywords, …)
  *     is forwarded as-is to the Document constructor.
  *
- *   Callers that omit paragraphStyles/numbering pay nothing — the
- *   adapter still produces a valid document, it just has no named
- *   style or numbering definitions for paragraphs to reference.
+ *   Callers that omit paragraphStyles/numbering/pageMargin pay nothing —
+ *   the adapter still produces a valid document, it just has no named
+ *   style, numbering definition, or margin override.
  * @returns {Promise<Document>}
  */
 export async function buildDocument(input, options = {}) {
@@ -104,6 +113,7 @@ export async function buildDocument(input, options = {}) {
     const {
         paragraphStyles,
         numbering,
+        pageMargin,
         ...documentMetadata
     } = options
 
@@ -125,7 +135,10 @@ export async function buildDocument(input, options = {}) {
     const sectionOptions = {
         properties: {
             type: SectionType.CONTINUOUS,
-            page: { pageNumbers: { start: 1, formatType: NumberFormat.DECIMAL } },
+            page: {
+                pageNumbers: { start: 1, formatType: NumberFormat.DECIMAL },
+                ...(pageMargin ? { margin: pageMargin } : {}),
+            },
         },
         children,
     }
@@ -162,6 +175,20 @@ export async function buildDocument(input, options = {}) {
         sectionOptions.footers = { default: createDefaultHeaderFooter(false) }
     }
 
+    // When either side opts in to `applyTo: 'first'`, the section gets
+    // `titlePage = true`, which tells Word to look up `first` variants on
+    // page 1. If the opposite side only registered a `default`, Word leaves
+    // page 1's header or footer blank — the default isn't consulted. Mirror
+    // `default` into `first` so all-pages content still renders on page 1.
+    if (sectionOptions.properties.titlePage) {
+        if (sectionOptions.headers && !sectionOptions.headers.first) {
+            sectionOptions.headers.first = sectionOptions.headers.default
+        }
+        if (sectionOptions.footers && !sectionOptions.footers.first) {
+            sectionOptions.footers.first = sectionOptions.footers.default
+        }
+    }
+
     const docOptions = {
         ...documentMetadata,
         sections: [sectionOptions],
@@ -812,15 +839,15 @@ async function irToImageParagraph(node) {
 }
 
 /**
- * Fetch image data from a URL and return as ArrayBuffer.
- * Works in browser (via fetch + blob) and Node (via fetch + arrayBuffer).
+ * Fetch image bytes for a docx ImageRun.
+ *
+ * Thin wrapper over the shared src/assets/fetch.js helper — docx wants
+ * a raw ArrayBuffer (Uint8Array.buffer works too; the library accepts
+ * either). The shared helper is what EPUB and any future asset-embedding
+ * adapter use; see principle 6 ("Extract shared logic when a second
+ * adapter needs it") in docs/architecture/principles.md.
  */
 async function fetchImageData(url) {
-    const response = await fetch(url)
-
-    if (!response.ok) {
-        throw new Error(`HTTP error fetching image: ${response.status}`)
-    }
-
-    return response.arrayBuffer()
+    const { bytes } = await fetchAsset(url)
+    return bytes
 }