@uniweb/press 0.3.1 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/press",
-  "version": "0.3.1",
+  "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": {

package/src/adapters/dispatch.js

@@ -40,9 +40,10 @@ const ADAPTERS = {
     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 also targeted by future
-    // HTML-string adapters (EPUB). Foundations register once under 'html'.
+    // 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 },
 }
 
 /**
@@ -79,6 +80,7 @@ export async function runCompile(format, compiledInput, documentOptions = {}) {
         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
@@ -838,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
 }

package/src/adapters/epub.js

@@ -0,0 +1,624 @@
+/**
+ * Internal EPUB3 format adapter.
+ *
+ * Consumes the 'html' passthrough shape shared with the Paged.js adapter —
+ * `{ sections: string[], metadata }` — and produces a valid, reflowable
+ * EPUB3 Blob. Each registered section becomes one chapter XHTML file in
+ * the EPUB spine.
+ *
+ * Input-shape sharing: a foundation that wired `useDocumentOutput(block,
+ * 'html', fragment)` for Paged.js gets EPUB for free — the adapter
+ * descriptor declares `consumes: 'html', ir: false` (see
+ * src/adapters/dispatch.js).
+ *
+ * Three EPUB envelope invariants this adapter upholds — the analogues of
+ * the three docx image invariants. All three must hold or e-readers reject
+ * the file:
+ *
+ *   1. `mimetype` is the FIRST entry in the ZIP and stored uncompressed
+ *      (compression method 0). Readers sniff the first ~60 bytes.
+ *   2. Every item in `<spine>` appears in `<manifest>` and vice versa.
+ *      Mismatches trigger reader errors ("malformed package").
+ *   3. Image paths in XHTML exactly match manifest paths including
+ *      extension and case (XHTML paths are relative to `OEBPS/`).
+ *
+ * This module is internal. It is NOT listed in package.json's exports
+ * field; consumers reach it only via the dynamic import inside
+ * adapters/dispatch.js, which keeps jszip + the emitter out of the main
+ * bundle until compile('epub') runs.
+ */
+
+import JSZip from 'jszip'
+import { parseFragment } from 'parse5'
+import { fetchAssets } from '../assets/fetch.js'
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Compile passthrough HTML output into an EPUB3 Blob.
+ *
+ * @param {Object} input - Output of compileOutputs(store, 'epub').
+ * @param {string[]} input.sections - Rendered HTML strings in registration
+ *   order, one per body fragment. Each becomes one spine chapter.
+ * @param {Object|null} [input.metadata] - Plain data object from the
+ *   `role: 'metadata'` registration (title, author, language, isbn, …).
+ * @param {Object} [options]
+ * @param {Object} [options.meta] - Additional metadata merged over the
+ *   `metadata` registration (options.meta wins).
+ * @param {string} [options.stylesheet] - Foundation-supplied CSS string
+ *   written to `OEBPS/styles.css`. When omitted, DEFAULT_STYLESHEET is used.
+ * @param {string} [options.identifier] - EPUB `dc:identifier`. When omitted,
+ *   a UUID is generated at compile time.
+ * @param {string} [options.cover] - URL of the cover image. When set, the
+ *   fetched bytes are embedded in OEBPS/images/, referenced in the manifest
+ *   with `properties="cover-image"` (EPUB3) and pointed at by a legacy
+ *   `<meta name="cover">` hint (Kindle KF8 compatibility).
+ * @returns {Promise<Blob>}
+ */
+export async function compileEpub(input, options = {}) {
+    const { sections = [], metadata = null } = input || {}
+    const { meta = {}, stylesheet, identifier, cover } = options
+
+    const resolvedMeta = { ...(metadata || {}), ...meta }
+    const css = stylesheet || DEFAULT_STYLESHEET
+    const id = identifier || resolvedMeta.identifier || generateUuid()
+    const coverUrl = cover || resolvedMeta.cover || resolvedMeta.coverImage
+
+    // Walk each HTML fragment, collect image URLs, capture a chapter title.
+    // The parsed tree is kept so we can re-serialize as XHTML after
+    // rewriting <img src> to manifest-relative paths.
+    const chapters = sections.map((html, i) => buildChapter(html, i))
+
+    // Deduplicate image URLs across all chapters — and the cover, if any —
+    // and fetch them in parallel. Failed fetches are logged and the original
+    // URL is left in place; the EPUB still opens but may show broken images.
+    const imageUrls = new Set()
+    for (const ch of chapters) {
+        for (const url of ch.images) imageUrls.add(url)
+    }
+    if (coverUrl) imageUrls.add(coverUrl)
+    const fetched = imageUrls.size
+        ? await fetchAssets(imageUrls)
+        : new Map()
+
+    // Assign a manifest-relative path to every successfully-fetched image,
+    // keyed by URL. Hash-based filenames dedupe identical images byte-for-byte.
+    const imagesManifest = []
+    const urlToPath = new Map()
+    const seenPaths = new Set()
+    let coverImageId = null
+    for (const [url, result] of fetched) {
+        if (result.error) {
+            console.warn(`@uniweb/press epub: failed to fetch image ${url}: ${result.error.message}`)
+            continue
+        }
+        const filename = `${result.hash}.${result.ext}`
+        const path = `images/${filename}`
+        urlToPath.set(url, path)
+        const imgId = `img-${result.hash}`
+        if (!seenPaths.has(path)) {
+            seenPaths.add(path)
+            imagesManifest.push({
+                id: imgId,
+                path,
+                mime: result.mime || 'application/octet-stream',
+                bytes: result.bytes,
+                isCover: url === coverUrl,
+            })
+        }
+        if (url === coverUrl) coverImageId = imgId
+    }
+
+    // Second pass over chapters — rewrite <img src> to manifest paths and
+    // serialize each as XHTML. Chapter paths live under `OEBPS/chapters/`
+    // so images (under `OEBPS/images/`) resolve via `../images/...`.
+    const chapterManifest = chapters.map((ch, i) => {
+        rewriteImageSrcs(ch.tree, urlToPath, '../')
+        const xhtml = wrapChapterXhtml({
+            title: ch.title || resolvedMeta.title || `Chapter ${i + 1}`,
+            language: resolvedMeta.language || 'en',
+            body: serializeXhtml(ch.tree),
+            stylesheetHref: '../styles.css',
+        })
+        return {
+            id: `ch-${pad(i + 1)}`,
+            path: `chapters/ch-${pad(i + 1)}.xhtml`,
+            title: ch.title || `Chapter ${i + 1}`,
+            xhtml,
+        }
+    })
+
+    // When a cover image was provided and fetched successfully, synthesize a
+    // cover-page XHTML (epub:type="cover") that precedes all content chapters
+    // in the spine. Some readers (iBooks, Kobo) show the manifest cover-image
+    // only on the shelf; an in-book cover page guarantees readers that don't
+    // render a shelf cover still see one when they open the book.
+    const coverImage = coverImageId
+        ? imagesManifest.find((img) => img.id === coverImageId)
+        : null
+    const coverChapter = coverImage
+        ? {
+              id: 'cover-page',
+              path: 'chapters/cover.xhtml',
+              title: resolvedMeta.coverTitle || 'Cover',
+              xhtml: buildCoverXhtml({
+                  language: resolvedMeta.language || 'en',
+                  title: resolvedMeta.title || 'Cover',
+                  imagePath: `../${coverImage.path}`,
+                  alt: resolvedMeta.coverAlt || resolvedMeta.title || 'Cover',
+              }),
+              isCover: true,
+          }
+        : null
+    const spineChapters = coverChapter
+        ? [coverChapter, ...chapterManifest]
+        : chapterManifest
+
+    // Assemble the ZIP. mimetype must be first and STORED uncompressed —
+    // invariant #1. Everything else is DEFLATEd for size; a 200–400KB book
+    // typically halves when XHTML/OPF/NCX are deflated. JSZip's default
+    // when generateAsync is called without per-file overrides is STORE, so
+    // pass compression at the generate level AND keep the per-file STORE
+    // on mimetype.
+    const zip = new JSZip()
+    zip.file('mimetype', 'application/epub+zip', { compression: 'STORE' })
+    zip.file('META-INF/container.xml', buildContainerXml())
+
+    const oebps = zip.folder('OEBPS')
+    oebps.file('content.opf', buildOpf({
+        id,
+        meta: resolvedMeta,
+        chapters: spineChapters,
+        images: imagesManifest,
+        coverImageId,
+        coverPageId: coverChapter ? coverChapter.id : null,
+    }))
+    oebps.file('nav.xhtml', buildNav({
+        language: resolvedMeta.language || 'en',
+        title: resolvedMeta.title || 'Contents',
+        chapters: chapterManifest,
+        coverPage: coverChapter,
+    }))
+    oebps.file('toc.ncx', buildNcx({
+        id,
+        title: resolvedMeta.title || 'Book',
+        chapters: spineChapters,
+    }))
+    oebps.file('styles.css', css)
+
+    for (const ch of spineChapters) {
+        oebps.file(ch.path, ch.xhtml)
+    }
+    for (const img of imagesManifest) {
+        oebps.file(img.path, img.bytes)
+    }
+
+    const blob = await zip.generateAsync({
+        type: 'blob',
+        mimeType: 'application/epub+zip',
+        compression: 'DEFLATE',
+        compressionOptions: { level: 6 },
+    })
+    return blob
+}
+
+// ============================================================================
+// Chapter parsing
+// ============================================================================
+
+/**
+ * Parse one registered HTML string into a chapter descriptor:
+ *   - tree:   parse5 fragment root (we re-serialize it as XHTML later)
+ *   - title:  first heading text, used for nav + <title>
+ *   - images: set of <img src> URLs found while walking
+ */
+function buildChapter(html, index) {
+    const tree = parseFragment(html || '')
+    const state = { title: '', images: new Set() }
+    walkForChapterMeta(tree, state)
+    return {
+        tree,
+        title: state.title,
+        images: state.images,
+        index,
+    }
+}
+
+function walkForChapterMeta(node, state) {
+    const children = node.childNodes || []
+    for (const child of children) {
+        if (child.nodeName === '#text') continue
+        const tag = (child.tagName || '').toLowerCase()
+        if (!state.title && (tag === 'h1' || tag === 'h2' || tag === 'h3')) {
+            state.title = collectText(child).trim()
+        }
+        if (tag === 'img') {
+            const src = getAttr(child, 'src')
+            if (src && !/^data:/i.test(src)) state.images.add(src)
+        }
+        if (child.childNodes) walkForChapterMeta(child, state)
+    }
+}
+
+function rewriteImageSrcs(node, urlToPath, pathPrefix) {
+    const children = node.childNodes || []
+    for (const child of children) {
+        if (child.nodeName === '#text') continue
+        const tag = (child.tagName || '').toLowerCase()
+        if (tag === 'img') {
+            const src = getAttr(child, 'src')
+            const rewritten = src && urlToPath.get(src)
+            if (rewritten) setAttr(child, 'src', pathPrefix + rewritten)
+        }
+        if (child.childNodes) rewriteImageSrcs(child, urlToPath, pathPrefix)
+    }
+}
+
+function collectText(node) {
+    if (node.nodeName === '#text') return node.value || ''
+    let out = ''
+    for (const child of node.childNodes || []) out += collectText(child)
+    return out
+}
+
+function getAttr(node, name) {
+    for (const attr of node.attrs || []) {
+        if (attr.name === name) return attr.value
+    }
+    return null
+}
+
+function setAttr(node, name, value) {
+    if (!node.attrs) node.attrs = []
+    for (const attr of node.attrs) {
+        if (attr.name === name) {
+            attr.value = value
+            return
+        }
+    }
+    node.attrs.push({ name, value })
+}
+
+// ============================================================================
+// XHTML serializer
+// ============================================================================
+
+/**
+ * EPUB3 readers parse chapters as XML, not tag-soup HTML. The serializer
+ * emits well-formed XHTML: void elements self-close, attributes are always
+ * quoted, text content is entity-escaped, and tag names are lowercase.
+ *
+ * parse5's built-in serializer emits HTML (`<br>`, not `<br/>`), so we
+ * walk the tree manually instead.
+ */
+const VOID_ELEMENTS = new Set([
+    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+    'link', 'meta', 'param', 'source', 'track', 'wbr',
+])
+
+export function serializeXhtml(node) {
+    if (node.nodeName === '#text') return escapeXmlText(node.value || '')
+    if (node.nodeName === '#document-fragment') {
+        return (node.childNodes || []).map(serializeXhtml).join('')
+    }
+    const tag = (node.tagName || '').toLowerCase()
+    if (!tag) {
+        // Unknown container: spread children.
+        return (node.childNodes || []).map(serializeXhtml).join('')
+    }
+    const attrs = serializeAttrs(node.attrs || [])
+    if (VOID_ELEMENTS.has(tag)) {
+        return `<${tag}${attrs}/>`
+    }
+    const inner = (node.childNodes || []).map(serializeXhtml).join('')
+    return `<${tag}${attrs}>${inner}</${tag}>`
+}
+
+function serializeAttrs(attrs) {
+    if (!attrs.length) return ''
+    let out = ''
+    for (const attr of attrs) {
+        const name = attr.name
+        const value = attr.value == null ? '' : String(attr.value)
+        out += ` ${name}="${escapeXmlAttr(value)}"`
+    }
+    return out
+}
+
+function escapeXmlText(s) {
+    return String(s)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+}
+
+function escapeXmlAttr(s) {
+    return String(s)
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+}
+
+// ============================================================================
+// EPUB envelope builders
+// ============================================================================
+
+function buildContainerXml() {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
+  <rootfiles>
+    <rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/>
+  </rootfiles>
+</container>
+`
+}
+
+/**
+ * EPUB3 package document. Declares metadata, manifest (every file under
+ * OEBPS), and spine (ordered reading sequence).
+ *
+ * Cover handling is intentionally dual: EPUB3 readers pick up the cover
+ * from `properties="cover-image"` on the manifest item; Amazon's KF8
+ * converter (used by "Send to Kindle" and older kindlegen) still wants a
+ * legacy `<meta name="cover" content="<image-id>"/>` hint in metadata.
+ * Emitting both is cheap and covers the whole ecosystem.
+ */
+export function buildOpf({ id, meta, chapters, images, coverImageId, coverPageId }) {
+    const title = meta.title || 'Untitled'
+    const language = meta.language || 'en'
+    const author = meta.author
+    const publisher = meta.publisher
+    const description = meta.description
+    const subject = meta.subject
+    const rights = meta.rights
+    const modified = meta.date || new Date().toISOString().slice(0, 19) + 'Z'
+
+    const metaLines = [
+        `    <dc:identifier id="pub-id">${escapeXmlText(id)}</dc:identifier>`,
+        `    <dc:title>${escapeXmlText(title)}</dc:title>`,
+        `    <dc:language>${escapeXmlText(language)}</dc:language>`,
+    ]
+    if (author) metaLines.push(`    <dc:creator>${escapeXmlText(author)}</dc:creator>`)
+    if (publisher) metaLines.push(`    <dc:publisher>${escapeXmlText(publisher)}</dc:publisher>`)
+    if (description) metaLines.push(`    <dc:description>${escapeXmlText(description)}</dc:description>`)
+    if (subject) metaLines.push(`    <dc:subject>${escapeXmlText(subject)}</dc:subject>`)
+    if (rights) metaLines.push(`    <dc:rights>${escapeXmlText(rights)}</dc:rights>`)
+    metaLines.push(`    <meta property="dcterms:modified">${escapeXmlText(modified)}</meta>`)
+    // Legacy Kindle/KF8 cover hint — Amazon's converter still reads this.
+    if (coverImageId) {
+        metaLines.push(
+            `    <meta name="cover" content="${escapeXmlAttr(coverImageId)}"/>`,
+        )
+    }
+
+    const manifestLines = [
+        `    <item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>`,
+        `    <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>`,
+        `    <item id="css" href="styles.css" media-type="text/css"/>`,
+    ]
+    for (const ch of chapters) {
+        manifestLines.push(
+            `    <item id="${escapeXmlAttr(ch.id)}" href="${escapeXmlAttr(ch.path)}" media-type="application/xhtml+xml"/>`,
+        )
+    }
+    for (const img of images) {
+        // EPUB3 cover hint — readers use this to pick the shelf thumbnail.
+        const coverProp = img.id === coverImageId ? ' properties="cover-image"' : ''
+        manifestLines.push(
+            `    <item id="${escapeXmlAttr(img.id)}" href="${escapeXmlAttr(img.path)}" media-type="${escapeXmlAttr(img.mime)}"${coverProp}/>`,
+        )
+    }
+
+    const spineLines = chapters.map((ch) => {
+        // Cover page should not linger in the reading flow for left-to-right
+        // navigation — `linear="no"` lets readers jump straight to content.
+        const attrs = ch.id === coverPageId
+            ? ` idref="${escapeXmlAttr(ch.id)}" linear="no"`
+            : ` idref="${escapeXmlAttr(ch.id)}"`
+        return `    <itemref${attrs}/>`
+    })
+
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="pub-id" xml:lang="${escapeXmlAttr(language)}">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+${metaLines.join('\n')}
+  </metadata>
+  <manifest>
+${manifestLines.join('\n')}
+  </manifest>
+  <spine toc="ncx">
+${spineLines.join('\n')}
+  </spine>
+</package>
+`
+}
+
+/**
+ * EPUB3 navigation document. Primary TOC — replaces the NCX for EPUB3
+ * readers but NCX is still emitted for EPUB2 compatibility.
+ *
+ * Two nav elements are emitted:
+ *   - `epub:type="toc"`: the reading-order chapter list (required).
+ *   - `epub:type="landmarks"`: quick-jump entries for cover, TOC, and
+ *     bodymatter start (optional, but assistive-tech readers and many
+ *     e-readers use it to offer "Go to cover" / "Go to beginning").
+ */
+export function buildNav({ language, title, chapters, coverPage }) {
+    const items = chapters
+        .map(
+            (ch) =>
+                `        <li><a href="${escapeXmlAttr(ch.path)}">${escapeXmlText(ch.title)}</a></li>`,
+        )
+        .join('\n')
+
+    const landmarkLines = []
+    if (coverPage) {
+        landmarkLines.push(
+            `        <li><a epub:type="cover" href="${escapeXmlAttr(coverPage.path)}">Cover</a></li>`,
+        )
+    }
+    landmarkLines.push(`        <li><a epub:type="toc" href="nav.xhtml#toc">Table of Contents</a></li>`)
+    if (chapters.length) {
+        landmarkLines.push(
+            `        <li><a epub:type="bodymatter" href="${escapeXmlAttr(chapters[0].path)}">Start of Content</a></li>`,
+        )
+    }
+    const landmarks = `    <nav epub:type="landmarks" id="landmarks" hidden="hidden">
+      <h2>Landmarks</h2>
+      <ol>
+${landmarkLines.join('\n')}
+      </ol>
+    </nav>`
+
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xml:lang="${escapeXmlAttr(language)}">
+  <head>
+    <meta charset="utf-8"/>
+    <title>${escapeXmlText(title)}</title>
+  </head>
+  <body>
+    <nav epub:type="toc" id="toc">
+      <h1>${escapeXmlText(title)}</h1>
+      <ol>
+${items}
+      </ol>
+    </nav>
+${landmarks}
+  </body>
+</html>
+`
+}
+
+/**
+ * EPUB2 NCX navigation. Optional in EPUB3 but helpful for older e-readers.
+ */
+export function buildNcx({ id, title, chapters }) {
+    const navPoints = chapters
+        .map(
+            (ch, i) => `    <navPoint id="${escapeXmlAttr(ch.id)}" playOrder="${i + 1}">
+      <navLabel><text>${escapeXmlText(ch.title)}</text></navLabel>
+      <content src="${escapeXmlAttr(ch.path)}"/>
+    </navPoint>`,
+        )
+        .join('\n')
+
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1">
+  <head>
+    <meta name="dtb:uid" content="${escapeXmlAttr(id)}"/>
+    <meta name="dtb:depth" content="1"/>
+  </head>
+  <docTitle><text>${escapeXmlText(title)}</text></docTitle>
+  <navMap>
+${navPoints}
+  </navMap>
+</ncx>
+`
+}
+
+/**
+ * Build the cover-page XHTML. Uses `epub:type="cover"` so assistive tech
+ * and the landmarks nav can identify it. The image scales to the viewport
+ * via inline SVG-style CSS so it works on both phone-sized readers and
+ * tablet-sized ones without the foundation needing to override styles.
+ */
+export function buildCoverXhtml({ language, title, imagePath, alt }) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xml:lang="${escapeXmlAttr(language)}">
+  <head>
+    <meta charset="utf-8"/>
+    <title>${escapeXmlText(title)}</title>
+    <style type="text/css">
+      body { margin: 0; padding: 0; text-align: center; }
+      img { max-width: 100%; max-height: 100vh; height: auto; }
+    </style>
+  </head>
+  <body epub:type="cover">
+    <div><img src="${escapeXmlAttr(imagePath)}" alt="${escapeXmlAttr(alt)}"/></div>
+  </body>
+</html>
+`
+}
+
+/**
+ * Wrap chapter body HTML in a valid XHTML document.
+ */
+export function wrapChapterXhtml({ title, language, body, stylesheetHref }) {
+    const css = stylesheetHref
+        ? `    <link rel="stylesheet" type="text/css" href="${escapeXmlAttr(stylesheetHref)}"/>\n`
+        : ''
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xml:lang="${escapeXmlAttr(language)}">
+  <head>
+    <meta charset="utf-8"/>
+    <title>${escapeXmlText(title)}</title>
+${css}  </head>
+  <body>
+${body}
+  </body>
+</html>
+`
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function pad(n) {
+    return String(n).padStart(2, '0')
+}
+
+function generateUuid() {
+    if (globalThis.crypto?.randomUUID) {
+        return 'urn:uuid:' + globalThis.crypto.randomUUID()
+    }
+    // RFC 4122 v4-ish fallback — 32 hex chars with dashes at the right places.
+    const rand = () => Math.floor(Math.random() * 0x10000).toString(16).padStart(4, '0')
+    return `urn:uuid:${rand()}${rand()}-${rand()}-4${rand().slice(1)}-a${rand().slice(1)}-${rand()}${rand()}${rand()}`
+}
+
+// ============================================================================
+// Defaults
+// ============================================================================
+
+export const DEFAULT_STYLESHEET = `/* Minimal EPUB3 stylesheet — foundations can override via options.stylesheet. */
+body {
+  font-family: Georgia, "Times New Roman", serif;
+  line-height: 1.5;
+  margin: 0 5%;
+}
+h1, h2, h3, h4, h5, h6 {
+  font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
+  line-height: 1.2;
+  page-break-after: avoid;
+}
+h1 { font-size: 1.8em; margin-top: 2em; }
+h2 { font-size: 1.4em; margin-top: 1.5em; }
+h3 { font-size: 1.15em; margin-top: 1em; }
+p { margin: 0 0 0.8em; text-indent: 1.25em; }
+p:first-child, p.lead { text-indent: 0; }
+img { max-width: 100%; height: auto; }
+figure { margin: 1em 0; text-align: center; }
+figcaption { font-size: 0.9em; color: #555; }
+blockquote {
+  margin: 1em 1.5em;
+  padding-left: 1em;
+  border-left: 3px solid #ccc;
+  color: #444;
+}
+code { font-family: ui-monospace, Menlo, Consolas, monospace; font-size: 0.92em; }
+pre {
+  font-family: ui-monospace, Menlo, Consolas, monospace;
+  font-size: 0.9em;
+  background: #f5f5f5;
+  padding: 0.75em;
+  overflow: auto;
+  white-space: pre-wrap;
+}
+`

package/src/assets/fetch.js

@@ -0,0 +1,155 @@
+/**
+ * Asset fetching for format adapters — internal.
+ *
+ * Adapters that embed binary assets (images today; fonts, audio in the
+ * future) share this helper rather than each inlining a `fetch()` call.
+ * Extracted when the second adapter (EPUB) needed asset bytes — principle
+ * 6 in docs/architecture/principles.md. The shape is deliberately minimal:
+ * docx embeds one image at a time, EPUB collects many URLs and writes them
+ * into the ZIP keyed by hash, and both paths flow through the same API.
+ *
+ * Internal: not in package.json exports. Reach it via adapter imports.
+ *
+ * Two entry points:
+ *   fetchAsset(url, options)  — one URL, returns { bytes, mime, hash, ext }.
+ *                               Throws on network/HTTP failure; callers that
+ *                               want soft failure wrap in try/catch.
+ *   fetchAssets(urls, options) — many URLs, Promise.allSettled so one
+ *                                failure doesn't kill the batch. Returns
+ *                                Map<url, { bytes, mime, hash, ext } | { error }>.
+ */
+
+/**
+ * Fetch a single asset URL and return normalized bytes + metadata.
+ *
+ * @param {string} url
+ * @param {Object} [options]
+ * @param {typeof fetch} [options.fetch] - override for tests / node-fetch.
+ * @returns {Promise<{ bytes: Uint8Array, mime: string, hash: string, ext: string }>}
+ */
+export async function fetchAsset(url, options = {}) {
+    const fetchImpl = options.fetch || globalThis.fetch
+    if (typeof fetchImpl !== 'function') {
+        throw new Error(
+            'fetchAsset: no fetch() available. Pass options.fetch or run in an environment that provides globalThis.fetch.',
+        )
+    }
+    const res = await fetchImpl(url)
+    if (!res.ok) {
+        throw new Error(`fetchAsset: HTTP ${res.status} ${res.statusText || ''} for ${url}`.trim())
+    }
+    const buf = await res.arrayBuffer()
+    const bytes = new Uint8Array(buf)
+    const headerMime = typeof res.headers?.get === 'function'
+        ? (res.headers.get('content-type') || '').split(';')[0].trim()
+        : ''
+    const mime = headerMime || detectMime(url, bytes)
+    const ext = extForMime(mime) || extFromUrl(url) || 'bin'
+    const hash = await hashContent(bytes)
+    return { bytes, mime, hash, ext }
+}
+
+/**
+ * Fetch many URLs at once. Deduplicates by URL. Uses Promise.allSettled
+ * so a single failure doesn't abort the rest — failed entries carry an
+ * `error` field instead of bytes.
+ *
+ * @param {Iterable<string>} urls
+ * @param {Object} [options] - forwarded to fetchAsset.
+ * @returns {Promise<Map<string, { bytes: Uint8Array, mime: string, hash: string, ext: string } | { error: Error }>>}
+ */
+export async function fetchAssets(urls, options = {}) {
+    const unique = Array.from(new Set(urls))
+    const results = await Promise.allSettled(
+        unique.map((url) => fetchAsset(url, options)),
+    )
+    const out = new Map()
+    unique.forEach((url, i) => {
+        const r = results[i]
+        if (r.status === 'fulfilled') {
+            out.set(url, r.value)
+        } else {
+            out.set(url, { error: r.reason instanceof Error ? r.reason : new Error(String(r.reason)) })
+        }
+    })
+    return out
+}
+
+/**
+ * Detect the MIME type of a byte buffer by magic bytes. Falls back to
+ * extension sniffing on the URL. Returns an empty string when neither
+ * path yields an answer.
+ */
+export function detectMime(url, bytes) {
+    if (bytes && bytes.length >= 4) {
+        if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) return 'image/png'
+        if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'image/jpeg'
+        if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46) return 'image/gif'
+        if (bytes[0] === 0x42 && bytes[1] === 0x4d) return 'image/bmp'
+        // SVG detection: "<?xml" or "<svg" after trimming BOM/whitespace.
+        const head = String.fromCharCode(...bytes.slice(0, Math.min(256, bytes.length))).trimStart()
+        if (head.startsWith('<?xml') || head.startsWith('<svg')) return 'image/svg+xml'
+    }
+    const ext = extFromUrl(url)
+    return ext ? mimeForExt(ext) : ''
+}
+
+/**
+ * SHA-256 hex digest of a byte buffer. Uses SubtleCrypto when available
+ * (browsers, modern Node), falls back to a short FNV-1a hash otherwise —
+ * good enough for de-duplicating asset filenames inside one compile.
+ */
+export async function hashContent(bytes) {
+    const subtle = globalThis.crypto?.subtle
+    if (subtle && typeof subtle.digest === 'function') {
+        const buf = await subtle.digest('SHA-256', bytes)
+        return bytesToHex(new Uint8Array(buf)).slice(0, 16)
+    }
+    // FNV-1a fallback.
+    let h = 0x811c9dc5
+    for (let i = 0; i < bytes.length; i++) {
+        h ^= bytes[i]
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0
+    }
+    return h.toString(16).padStart(8, '0')
+}
+
+function bytesToHex(bytes) {
+    let s = ''
+    for (let i = 0; i < bytes.length; i++) s += bytes[i].toString(16).padStart(2, '0')
+    return s
+}
+
+function extFromUrl(url) {
+    if (!url) return ''
+    const path = String(url).split(/[?#]/)[0]
+    const m = path.match(/\.([a-zA-Z0-9]+)$/)
+    return m ? m[1].toLowerCase() : ''
+}
+
+const EXT_MIME = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    bmp: 'image/bmp',
+    svg: 'image/svg+xml',
+    webp: 'image/webp',
+}
+
+const MIME_EXT = {
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/gif': 'gif',
+    'image/bmp': 'bmp',
+    'image/svg+xml': 'svg',
+    'image/webp': 'webp',
+}
+
+function mimeForExt(ext) {
+    return EXT_MIME[ext] || ''
+}
+
+function extForMime(mime) {
+    return MIME_EXT[mime] || ''
+}

package/src/compileRegistrations.js

@@ -142,3 +142,252 @@ export async function compileSubtree(elements, format, options = {}) {
     const compiled = compileRegistrations(elements, format, { basePath })
     return runCompile(format, compiled, adapterOptions)
 }
+
+/**
+ * Full-document compile via a foundation's declared outputs.
+ *
+ * Where `compileSubtree` is the low-level "I already decided the tree,
+ * give me bytes" primitive, `compileDocument` is the high-level "this
+ * website, compiled as a <format> document through this foundation"
+ * convenience. It handles three concerns compileSubtree doesn't:
+ *
+ *   1. Block selection — defaults to every page's bodyBlocks; a host
+ *      can narrow the scope with `rootPath` (only pages under that
+ *      route prefix).
+ *   2. Foundation-supplied adapter options — looks up
+ *      `foundation.outputs[format].getOptions(website, ...)` and
+ *      merges its return into the options passed to compileSubtree.
+ *      That's how a book foundation supplies preamble, template, meta,
+ *      and asset bytes without the host knowing anything about them.
+ *   3. Format aliasing — an output can declare `via: '<press-format>'`
+ *      to route compile through a different Press adapter. A foundation
+ *      can expose `outputs.pdf = { via: 'typst', ... }` so hosts ask
+ *      for 'pdf' while Press produces a typst source bundle; the host
+ *      (e.g., unipress) finishes the compile with the typst binary.
+ *
+ * Two call shapes:
+ *
+ *   - Tree mode: `compileDocument(<tree>, { format, ... })`.
+ *     The first argument is a React element. Treated as a direct
+ *     passthrough to compileSubtree — for hosts that already decided
+ *     which blocks to include and assembled the tree themselves. The
+ *     outputs lookup is skipped in this mode (no foundation needed).
+ *
+ *   - Website mode: `compileDocument(website, { format, foundation, rootPath, ... })`.
+ *     The first argument is a Website instance (or any object with a
+ *     `pages` array — we duck-type). Gathers blocks, builds the tree
+ *     via `globalThis.uniweb.childBlockRenderer({ blocks })`, looks up
+ *     `outputs[format]` on the foundation, calls its `getOptions`, and
+ *     routes through compileSubtree with the resulting adapterOptions
+ *     and basePath.
+ *
+ * The foundation argument accepts either the raw source shape (an
+ * object with `.outputs`) or the built-module shape (`.default.capabilities.outputs`).
+ * Browser Download buttons typically pass the source shape via a local
+ * relative import; headless hosts like unipress pass the built module
+ * they imported via URL.
+ *
+ * @param {import('react').ReactElement | Object} treeOrWebsite
+ * @param {Object} [options]
+ * @param {string} options.format - Output format name as declared on
+ *   the foundation (e.g. 'typst', 'pdf', 'epub', 'pagedjs').
+ * @param {Object} [options.foundation] - Foundation module, source or
+ *   built. Required for website mode; ignored in tree mode.
+ * @param {string} [options.rootPath] - Limit block gathering to pages
+ *   whose route is or lives under this prefix. Only meaningful in
+ *   website mode.
+ * @param {Object} [options.adapterOptions] - Caller-supplied adapter
+ *   options. Merged on top of whatever the foundation's getOptions
+ *   returns, so hosts can override.
+ * @param {string} [options.basePath] - DocumentProvider basePath. In
+ *   website mode, defaults to `website.basePath` if unset.
+ * @param {(src: string) => Promise<Uint8Array>} [options.loadAsset] -
+ *   Host-supplied byte loader for config-level asset paths (cover
+ *   images, banners, logos referenced from document.yml/site.yml).
+ *   Called by foundation getOptions implementations to fetch bytes
+ *   without environment branching. Hosts running in Node (unipress)
+ *   should pass an fs-based implementation; the default uses fetch
+ *   (browser only).
+ * @returns {Promise<Blob>}
+ */
+export async function compileDocument(treeOrWebsite, options = {}) {
+    const isElement =
+        treeOrWebsite !== null &&
+        typeof treeOrWebsite === 'object' &&
+        // React elements have a $$typeof symbol; duck-typing avoids needing
+        // `import { isValidElement } from 'react'` (minor, but keeps this
+        // file free of React imports it doesn't otherwise need).
+        Boolean(treeOrWebsite.$$typeof)
+
+    if (isElement) {
+        const { format, ...rest } = options
+        if (!format) {
+            throw new Error(
+                "compileDocument: 'format' is required (tree mode).",
+            )
+        }
+        return compileSubtree(treeOrWebsite, format, rest)
+    }
+
+    const website = treeOrWebsite
+    const {
+        format,
+        foundation,
+        rootPath,
+        adapterOptions: overrideAdapterOptions = {},
+        basePath: basePathOverride,
+        loadAsset: hostLoadAsset,
+        ...rest
+    } = options
+
+    // Host-supplied loadAsset takes precedence; otherwise default to a
+    // browser-fetch implementation that uses website.assets[src].url when
+    // available and falls back to fetching the original src. Hosts running
+    // in Node (unipress) supply their own fs-based loader.
+    const loadAsset = hostLoadAsset ?? createDefaultLoadAsset(website)
+
+    if (!format) {
+        throw new Error(
+            "compileDocument: 'format' is required (website mode).",
+        )
+    }
+    if (!website || !Array.isArray(website.pages)) {
+        throw new Error(
+            'compileDocument: first argument must be either a React element ' +
+                '(tree mode) or a Website (website mode: expected object with ' +
+                'a pages array).',
+        )
+    }
+
+    const outputs = resolveFoundationOutputs(foundation)
+    const outputSpec = outputs?.[format]
+    if (!outputSpec) {
+        const declared = outputs ? Object.keys(outputs).join(', ') || '(none)' : '(no outputs declaration)'
+        throw new Error(
+            `compileDocument: foundation has no outputs.${format} declaration. ` +
+                `Declared outputs: ${declared}. ` +
+                "Add outputs[format] = { getOptions, extension?, via? } to the foundation's default export.",
+        )
+    }
+
+    const pressFormat = outputSpec.via ?? format
+    const foundationAdapterOptions = outputSpec.getOptions
+        ? await outputSpec.getOptions(website, { format, rootPath, loadAsset, ...rest })
+        : {}
+
+    const mergedAdapterOptions = {
+        ...foundationAdapterOptions.adapterOptions,
+        ...overrideAdapterOptions,
+    }
+
+    const blocks = gatherBlocks(website, rootPath)
+    const renderer = globalThis.uniweb?.childBlockRenderer
+    if (typeof renderer !== 'function') {
+        throw new Error(
+            'compileDocument: globalThis.uniweb.childBlockRenderer is not ' +
+                'installed. Either call initPrerender (headless) or mount a ' +
+                'Uniweb runtime (browser) before compileDocument, or pass a ' +
+                'pre-built tree (tree mode).',
+        )
+    }
+    const tree = renderer({ blocks })
+
+    return compileSubtree(tree, pressFormat, {
+        basePath: basePathOverride ?? website?.basePath,
+        ...foundationAdapterOptions,
+        adapterOptions: mergedAdapterOptions,
+    })
+}
+
+function resolveFoundationOutputs(foundation) {
+    if (!foundation) return null
+    if (foundation.outputs) return foundation.outputs
+    if (foundation.default?.capabilities?.outputs)
+        return foundation.default.capabilities.outputs
+    if (foundation.default?.outputs) return foundation.default.outputs
+    return null
+}
+
+/**
+ * Default loadAsset for the browser. Resolves a config-time asset
+ * reference (the original `src` string as it appears in document.yml /
+ * site.yml — e.g. `assets/front.png`) into a `Uint8Array` of bytes.
+ *
+ * Hosts running in Node (unipress) should pass their own loadAsset via
+ * compileDocument({ loadAsset }) — this default uses `fetch`, which in a
+ * Node-side compile has no server to reach.
+ *
+ * Lookup order:
+ *   1. data: URL → decode in place.
+ *   2. Asset manifest hit (`website.assets[src]`) — fetch the resolved
+ *      URL form. The framework's content-collector populates this for
+ *      config-level asset paths.
+ *   3. Fall back to fetching the original src directly. Works when src
+ *      is already a URL or a server-relative path.
+ */
+function createDefaultLoadAsset(website) {
+    return async function loadAsset(src) {
+        if (!src) return null
+        if (typeof src !== 'string') return null
+
+        // data: URL — decode in place
+        if (src.startsWith('data:')) {
+            const comma = src.indexOf(',')
+            if (comma === -1) return null
+            const meta = src.slice(5, comma)
+            const data = src.slice(comma + 1)
+            if (meta.includes(';base64')) {
+                const bin = atob(data)
+                const buf = new Uint8Array(bin.length)
+                for (let i = 0; i < bin.length; i++) buf[i] = bin.charCodeAt(i)
+                return buf
+            }
+            return new TextEncoder().encode(decodeURIComponent(data))
+        }
+
+        if (typeof fetch !== 'function') {
+            throw new Error(
+                "loadAsset: cannot load '" +
+                    src +
+                    "' — no fetch available in this environment. " +
+                    'Pass a host-supplied loadAsset via compileDocument({ loadAsset }).',
+            )
+        }
+
+        // Construct a URL from manifest-resolved info or the original src.
+        // External URLs and absolute paths pass through; relative paths get
+        // a leading slash + basePath prefix so they hit the dev/prod server.
+        let url = src
+        if (!/^https?:\/\//i.test(url) && !url.startsWith('data:')) {
+            const prefixed =
+                (website?.basePath || '') +
+                (url.startsWith('/') ? url : '/' + url)
+            url =
+                typeof window !== 'undefined' && window.location?.origin
+                    ? window.location.origin + prefixed
+                    : prefixed
+        }
+
+        const res = await fetch(url)
+        if (!res.ok) {
+            throw new Error(
+                'loadAsset: fetch failed for ' + url + ' (' + res.status + ')',
+            )
+        }
+        return new Uint8Array(await res.arrayBuffer())
+    }
+}
+
+function gatherBlocks(website, rootPath) {
+    const pages = website.pages || []
+    const scoped =
+        rootPath && typeof rootPath === 'string'
+            ? pages.filter(
+                  (p) =>
+                      p.route === rootPath ||
+                      (typeof p.route === 'string' &&
+                          p.route.startsWith(rootPath + '/')),
+              )
+            : pages
+    return scoped.flatMap((page) => page.bodyBlocks || [])
+}

package/src/index.js

@@ -15,4 +15,5 @@ export { triggerDownload } from './triggerDownload.js'
 export {
     compileRegistrations,
     compileSubtree,
+    compileDocument,
 } from './compileRegistrations.js'