@uniweb/press 0.3.0 → 0.4.1

package/src/compileRegistrations.js

@@ -26,7 +26,7 @@ import { createElement } from 'react'
 import { renderToStaticMarkup } from 'react-dom/server'
 import DocumentProvider, { createStore } from './DocumentProvider.jsx'
 import { compileOutputs } from './ir/compile.js'
-import { runCompile } from './adapters/dispatch.js'
+import { runCompile, getAdapterDescriptor } from './adapters/dispatch.js'
 
 /**
  * @param {any} elements - React element or array of elements. Whatever you
@@ -67,9 +67,48 @@ export function compileRegistrations(elements, format, options = {}) {
         ),
     )
 
+    warnIfEmptyRegistrations(store, format)
     return compileOutputs(store, format)
 }
 
+/**
+ * Emit a one-time console warning when a compile finds no registrations
+ * under the adapter's `consumes` key. Catches the commonest cause of an
+ * "empty body" compile: foundation section components registered for a
+ * different input shape than the one the selected format reads from.
+ *
+ * The warning names the input-shape key (what the foundation should
+ * register under) rather than the output format, because that's where the
+ * fix lives. Silent when at least one output is present. Guarded with a
+ * Set so the same missed key only warns once per page.
+ *
+ * Unknown formats skip the warning — runCompile's "Unsupported document
+ * format" error is the right signal, not a misleading "0 sections" note.
+ */
+const _emptyKeyWarned = new Set()
+function warnIfEmptyRegistrations(store, format) {
+    const desc = getAdapterDescriptor(format)
+    if (!desc) return
+    const key = desc.consumes
+    if (_emptyKeyWarned.has(key)) return
+    const outputs = (store.getOutputs && store.getOutputs(key)) || []
+    if (outputs.length > 0) return
+    _emptyKeyWarned.add(key)
+    if (typeof console !== 'undefined' && console.warn) {
+        const note =
+            key === format
+                ? `compileSubtree('${format}') found 0 registered sections. ` +
+                  `Did any section component call useDocumentOutput(block, '${format}', ...)?`
+                : `compileSubtree('${format}') found 0 sections registered under input key '${key}'. ` +
+                  `Sections should call useDocumentOutput(block, '${key}', ...) ` +
+                  `(the output format '${format}' reads fragments registered under '${key}').`
+        console.warn(
+            `@uniweb/press: ${note} ` +
+                `Sections registered for a different input key do not cross-register.`,
+        )
+    }
+}
+
 /**
  * Convenience: aggregate + dispatch the adapter in one call. Mirrors
  * `useDocumentCompile().compile(format, options)` but for off-screen
@@ -103,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'

package/src/ir/attributes.js

@@ -30,6 +30,22 @@ const asEmptyObject = () => ({})
 /** Transform used by boolean presence attributes like data-page-break-before. */
 const asTrue = () => true
 
+/**
+ * Coerce a numeric attribute value to an integer.
+ *
+ * HTML attributes are always strings; numeric docx-library options that
+ * flow through IR (e.g. EMU offsets on floating anchors) must be numbers,
+ * or the library's type guards silently fall back to a different code
+ * path — floating positioning, for example, treats a string `offset` as
+ * missing and reverts to `align` instead. Unparseable values pass through
+ * unchanged so non-numeric strings still reach the adapter's own
+ * conversion layer.
+ */
+const toInt = (v) => {
+    const n = parseInt(v, 10)
+    return Number.isFinite(n) ? n : v
+}
+
 /**
  * Explicit attribute → IR path mapping. Entries are listed in the same
  * order as the legacy switch for ease of cross-reference.
@@ -88,6 +104,7 @@ export const attributeMap = {
     },
     'data-floating-horizontalposition-offset': {
         path: ['floating', 'horizontalPosition', 'offset'],
+        transform: toInt,
     },
     'data-floating-verticalposition-relative': {
         path: ['floating', 'verticalPosition', 'relative'],
@@ -97,6 +114,7 @@ export const attributeMap = {
     },
     'data-floating-verticalposition-offset': {
         path: ['floating', 'verticalPosition', 'offset'],
+        transform: toInt,
     },
 
     // Page breaks — maps to DocxParagraph({ pageBreakBefore: true })

package/src/ir/compile.js

@@ -1,12 +1,18 @@
 /**
  * Bridge between the React registration layer (DocumentProvider +
- * useDocumentOutput) and the format adapters (docx, xlsx, pdf).
+ * useDocumentOutput) and the format adapters (docx, xlsx, typst, pagedjs).
  *
- * For docx (and any HTML-based format): registered JSX fragments are
- * statically rendered to HTML, parsed to IR, and grouped into
- * { header, footer, sections }.
+ * Dispatch is table-driven via the adapter descriptor in
+ * src/adapters/dispatch.js — each adapter declares:
  *
- * For xlsx: registered data objects are collected as-is (no IR conversion).
+ *   consumes — the store key whose fragments feed this adapter.
+ *              Foundations register under this key. Multiple adapters can
+ *              share the same key (e.g. pagedjs and future EPUB both read
+ *              'html'), so a foundation writes one registration and gets
+ *              both formats.
+ *   ir       — whether fragments are walked to IR (true: docx/typst) or
+ *              passed through as-is (false: xlsx data objects, pagedjs
+ *              HTML strings).
  *
  * useDocumentCompile is the typical caller; custom adapter authors can
  * invoke compileOutputs() directly via the @uniweb/press/ir subpath.
@@ -14,31 +20,51 @@
 
 import { renderToStaticMarkup } from 'react-dom/server'
 import { htmlToIR } from './parser.js'
+import { getAdapterDescriptor } from '../adapters/dispatch.js'
 
 /**
  * Compile all registered outputs for a given format into the shape the
  * format adapter's compile function expects.
  *
  * @param {Object} store - The DocumentProvider store (from DocumentContext).
- * @param {string} format - Format identifier ('docx', 'xlsx', etc.).
- * @returns {Object} Adapter input shape:
- *   For docx: { sections: IR[][], header: IR[]|null, footer: IR[]|null }
- *   For xlsx: { sections: Object[] } (raw data objects)
+ * @param {string} format - Format identifier ('docx', 'xlsx', 'typst', 'pagedjs', …).
+ * @returns {Object} Adapter input shape. Two shapes today:
+ *   - IR-based (docx/typst):  { sections: IR[][], header, footer, metadata,
+ *                               headerFirstPageOnly, footerFirstPageOnly }
+ *   - Passthrough (xlsx):     { sections: Object[] }
+ *   - Passthrough (pagedjs):  { sections: string[], metadata }
  */
 export function compileOutputs(store, format) {
-    const outputs = store.getOutputs(format)
+    const desc = getAdapterDescriptor(format)
+    // Unknown format: surface the empty shape and let runCompile throw the
+    // descriptive error. Callers that bypass runCompile (IR-subpath users)
+    // get an empty IR-shape output — safe default.
+    if (!desc) {
+        return { sections: [], header: null, footer: null, metadata: null }
+    }
+
+    const outputs = store.getOutputs(desc.consumes) || []
 
-    if (format === 'xlsx') {
-        return compileXlsx(outputs)
+    if (desc.ir) {
+        return compileToIR(outputs, store)
     }
 
-    // Default: HTML-based formats (docx, pdf)
-    return compileHtmlBased(outputs, store)
+    // Passthrough branch — differs only in whether body fragments are
+    // rendered through React first.
+    //
+    // - 'html' input shape: fragments are JSX; render each one to a static
+    //   HTML string (preserves semantic HTML + data-* attributes the
+    //   target adapter may pick up, e.g. CSS Paged Media selectors).
+    // - Any other non-IR shape (xlsx, future data exports): fragments are
+    //   plain values; keep them as-is.
+    if (desc.consumes === 'html') {
+        return compileHtmlPassthrough(outputs, store)
+    }
+    return compileDataPassthrough(outputs)
 }
 
 /**
- * Compile HTML-based format outputs (docx, pdf, typst).
- * JSX fragments → renderToStaticMarkup → htmlToIR → grouped by role.
+ * IR branch — JSX → renderToStaticMarkup → htmlToIR → grouped by role.
  *
  * Four roles:
  *   - body (default): IR appended to `sections`.
@@ -47,6 +73,12 @@ export function compileOutputs(store, format) {
  *     consume this for document-level properties (title, author, isbn, …).
  *     Fragments for the metadata role are plain data objects, not JSX.
  *
+ * Header and footer registrations accept an `applyTo` option. When set
+ * to `'first'`, the output carries `headerFirstPageOnly` /
+ * `footerFirstPageOnly` booleans so format adapters can emit a
+ * different-first-page section layout. Other `applyTo` values (`'all'`
+ * default, `'odd'`, `'even'`) produce no flag.
+ *
  * Registered fragments are React element trees captured during the live
  * page render. renderToStaticMarkup renders them afresh here, outside
  * the React tree the page rendered in — so any context the builders
@@ -57,10 +89,12 @@ export function compileOutputs(store, format) {
  * builders fall back to context defaults and emit, for example,
  * un-prefixed URLs that the docx adapter's fetch() then 404s on.
  */
-function compileHtmlBased(outputs, store) {
+function compileToIR(outputs, store) {
     let metadata = null
     let header = null
     let footer = null
+    let headerFirstPageOnly = false
+    let footerFirstPageOnly = false
     const sections = []
 
     const wrap = store.wrapWithProviders || ((x) => x)
@@ -81,11 +115,12 @@ function compileHtmlBased(outputs, store) {
 
         switch (role) {
             case 'header':
-                // Last header wins (or merge — for now, last wins).
                 header = ir
+                if (options.applyTo === 'first') headerFirstPageOnly = true
                 break
             case 'footer':
                 footer = ir
+                if (options.applyTo === 'first') footerFirstPageOnly = true
                 break
             default:
                 sections.push(ir)
@@ -93,17 +128,50 @@ function compileHtmlBased(outputs, store) {
         }
     }
 
-    return { sections, header, footer, metadata }
+    return {
+        sections,
+        header,
+        footer,
+        metadata,
+        headerFirstPageOnly,
+        footerFirstPageOnly,
+    }
 }
 
 /**
- * Compile xlsx format outputs. Fragments are plain data objects
- * (no HTML/IR conversion needed).
+ * HTML passthrough branch — JSX → renderToStaticMarkup → HTML string.
+ * Consumed by Paged.js and any future HTML-string adapter (EPUB, etc.).
+ *
+ * Only `body` and `metadata` roles are consumed. Header/footer for
+ * HTML-string adapters are typically handled by the adapter's own
+ * wrapping mechanism (for Paged.js: CSS `@page` margin boxes declared in
+ * the stylesheet, e.g. `@top-right { content: string(chapter); }`), not
+ * as registered fragments.
  */
-function compileXlsx(outputs) {
-    const sections = outputs
-        .map(({ fragment }) => fragment)
-        .filter(Boolean)
+function compileHtmlPassthrough(outputs, store) {
+    const wrap = store.wrapWithProviders || ((x) => x)
+    let metadata = null
+    const sections = []
+
+    for (const { fragment, options } of outputs) {
+        const role = options.role || 'body'
+        if (role === 'metadata') {
+            metadata = fragment
+            continue
+        }
+        if (role !== 'body') continue
+        const html = renderToStaticMarkup(wrap(fragment))
+        sections.push(html)
+    }
+
+    return { sections, metadata }
+}
 
+/**
+ * Plain-data passthrough (xlsx, future JSON exports). Fragments are not
+ * JSX — they're domain objects the adapter defines. Collect in order.
+ */
+function compileDataPassthrough(outputs) {
+    const sections = outputs.map(({ fragment }) => fragment).filter(Boolean)
     return { sections }
 }

package/src/useDocumentCompile.js

@@ -20,7 +20,36 @@
 import { useCallback, useContext, useState } from 'react'
 import { DocumentContext } from './DocumentContext.js'
 import { compileOutputs } from './ir/compile.js'
-import { runCompile } from './adapters/dispatch.js'
+import { runCompile, getAdapterDescriptor } from './adapters/dispatch.js'
+
+// One-time per-input-key warning guard, shared across every
+// useDocumentCompile call in a page. Same behaviour as the off-screen
+// compileSubtree pathway — keyed on the adapter's `consumes` input shape,
+// not the output format, so a missed 'html' registration warns once total
+// even across multiple output formats (pagedjs + future epub) that share it.
+const _emptyKeyWarned = new Set()
+function warnIfEmptyRegistrations(store, format) {
+    const desc = getAdapterDescriptor(format)
+    if (!desc) return
+    const key = desc.consumes
+    if (_emptyKeyWarned.has(key)) return
+    const outputs = (store.getOutputs && store.getOutputs(key)) || []
+    if (outputs.length > 0) return
+    _emptyKeyWarned.add(key)
+    if (typeof console !== 'undefined' && console.warn) {
+        const note =
+            key === format
+                ? `compile('${format}') found 0 registered sections. ` +
+                  `Did any section component call useDocumentOutput(block, '${format}', ...)?`
+                : `compile('${format}') found 0 sections registered under input key '${key}'. ` +
+                  `Sections should call useDocumentOutput(block, '${key}', ...) ` +
+                  `(the output format '${format}' reads fragments registered under '${key}').`
+        console.warn(
+            `@uniweb/press: ${note} ` +
+                `Sections registered for a different input key do not cross-register.`,
+        )
+    }
+}
 
 /**
  * @returns {{ compile: (format: string, documentOptions?: Object) => Promise<Blob>, isCompiling: boolean }}
@@ -38,6 +67,7 @@ export function useDocumentCompile() {
             }
             setIsCompiling(true)
             try {
+                warnIfEmptyRegistrations(store, format)
                 const compiled = compileOutputs(store, format)
                 return await runCompile(format, compiled, documentOptions)
             } finally {

package/src/vite-plugin-typst.js

@@ -26,9 +26,9 @@
  */
 
 import { spawn } from 'node:child_process'
-import { mkdtemp, writeFile, readFile, rm } from 'node:fs/promises'
+import { mkdtemp, writeFile, readFile, rm, mkdir } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { join, dirname } from 'node:path'
 import { Readable } from 'node:stream'
 
 const DEFAULT_PATH = '/__press/typst/compile'
@@ -142,7 +142,11 @@ async function compileBundleWithTypst(files, { binary, extraArgs }) {
                 typeof contents === 'string'
                     ? Buffer.from(contents, 'utf8')
                     : Buffer.from(contents.buffer, contents.byteOffset, contents.byteLength)
-            await writeFile(join(dir, name), buf)
+            const filePath = join(dir, name)
+            // Support nested paths like `covers/front.png` — ensure the
+            // parent directory exists before writing.
+            await mkdir(dirname(filePath), { recursive: true })
+            await writeFile(filePath, buf)
         }
 
         const inputPath = join(dir, 'main.typ')