@uniweb/unipress 0.4.27 → 0.4.29

package/docs/publishing/size-and-layout.md

@@ -0,0 +1,152 @@
+# Size and layout
+
+The physical shape of your book — its **trim size**, margins, and typography — is
+set in `document.yml` under `book:`. Pick it once; every build uses it. This page
+explains the choices and how to make them.
+
+> Full field reference: [`book` template](../templates/book.md). This page is the
+> *why* behind the settings.
+
+## Trim size
+
+The trim size is the finished page dimensions after the printer cuts the sheet.
+It's the single most defining physical choice — it sets how your book feels in the
+hand and constrains everything else. Set it with `book.trim`:
+
+```yaml
+book:
+  trim: trade-6x9
+```
+
+### Built-in presets
+
+| Preset | Size | Good for |
+|---|---|---|
+| `trade-6x9` *(default)* | 6 × 9 in | The safe default. Most trade fiction and nonfiction. |
+| `trade-7x10` | 7 × 10 in | Technical books, workbooks, anything with code or wide images. |
+| `crown-octavo` | 7.44 × 9.69 in (189 × 246 mm) | Common UK trade hardcover. |
+| `royal-octavo` | 6.14 × 9.21 in (156 × 234 mm) | Academic and scholarly hardcover. |
+| `a5` | 148 × 210 mm | Compact European paperback; pocket guides. |
+
+Two more sizes exist for the **article** genre — full-size paper for documents and
+proofing copies rather than bound books:
+
+| Preset | Size | Good for |
+|---|---|---|
+| `a4` | 210 × 297 mm | The world's standard paper. A roomy proofing copy. |
+| `letter` | 8.5 × 11 in | US/Canada paper. A roomy proofing copy. |
+
+### A custom size
+
+Any trim your printer supports. Give a width and height (and, if you like,
+margins) instead of a preset name:
+
+```yaml
+book:
+  trim:
+    width: 5in       # a common "mass-market"-ish trade size
+    height: 8in
+    margins: { inside: 0.75in, outside: 0.5in, top: 0.75in, bottom: 0.75in }
+```
+
+You can also start from a preset and nudge one value:
+
+```yaml
+book:
+  trim:
+    preset: trade-6x9
+    margins: { inside: 0.9in }   # more gutter for a thick book
+```
+
+**Pick a size your print-on-demand service offers.** Each service lists its
+supported trim sizes; matching one avoids a custom-size surcharge. Check
+[KDP's list](https://kdp.amazon.com/help/topic/G201834180) or
+[IngramSpark's](https://help.ingramspark.com/hc/en-us/articles/360010301911).
+
+## Margins and the gutter
+
+A bound book needs an **asymmetric** margin: the **inside** (gutter) edge — where
+the pages meet the spine — must be wider than the **outside**, or text disappears
+into the binding. The presets already do this. The four margins:
+
+```yaml
+book:
+  trim:
+    preset: trade-6x9
+    margins: { inside: 0.75in, outside: 0.5in, top: 0.75in, bottom: 0.75in }
+```
+
+**The more pages, the more gutter you need** — a thick book's spine "steals" more
+of the inside margin. Print-on-demand services publish a minimum inside margin by
+page count; a ~300-page 6×9 usually wants at least 0.75–0.875 in inside. Confirm
+against your service's table before you finalize, and widen `inside` if needed.
+
+## Bleed
+
+**Bleed** is art that runs off the edge of the page. Because printers can't cut
+perfectly, anything meant to reach the edge must extend ~0.125 in *past* the trim,
+so the cut never leaves a white sliver.
+
+- **Text interiors need no bleed.** Your words sit inside the margins; unipress
+  emits pages at the exact trim size, which is exactly what print-on-demand wants
+  for a text interior. This is the common case — you don't have to think about it.
+- **Full-bleed interior *images*** (a photo running to the paper edge) are the
+  exception. unipress emits trim-size pages, so it isn't set up for edge-to-edge
+  interior art. Keep interior images within the text block, or ask your printer how
+  they want full-bleed interior pages supplied.
+- **Your cover is where bleed really matters**, and that's handled separately by
+  your print service's cover template — see [covers-and-images.md](./covers-and-images.md#covers).
+
+## Front matter
+
+The pages before Chapter 1 — title, copyright, contents. Toggle them under
+`book.structure`:
+
+```yaml
+book:
+  structure:
+    titlePage: true
+    copyrightPage: true
+    toc: true
+    tocDepth: 2                 # how many heading levels the contents lists
+    frontMatterNumbering: roman # none | roman | arabic
+```
+
+- **`titlePage`** — the title, subtitle, and author, typeset. If your cover art
+  already carries the title (many do), you may want this **off** to avoid repeating
+  it: `titlePage: false`.
+- **`copyrightPage`** — the copyright/imprint page. Pulls from `book.rights`,
+  `book.publisher`, `book.isbn` (see [isbn-and-metadata.md](./isbn-and-metadata.md)).
+- **`toc`** — a generated table of contents from your chapter titles.
+- **`frontMatterNumbering: roman`** is the traditional convention: front matter is
+  numbered i, ii, iii…; Chapter 1 resets to page 1. Use `none` to leave front
+  matter unnumbered, or `arabic` to number straight through.
+
+## Typography
+
+The defaults produce a clean, readable book — you can ship without touching them.
+When you want control, set it under `book.typography`:
+
+```yaml
+book:
+  typography:
+    bodySize: 11pt
+    leading: 0.72em          # line spacing
+    firstLineIndent: 1.4em   # paragraph indent
+    bodyFont: ["EB Garamond", "Georgia"]   # first available wins
+    headingFont: ["EB Garamond", "Georgia"]
+```
+
+- **Fonts are tried in order**; the first one installed on the machine running the
+  compile is used, and unipress embeds it in the PDF. Leave them unset to use the
+  compiler's clean built-in defaults. If you name a font, make sure it's installed
+  where you build.
+- **Body size and leading** are the levers for page count and comfort. 10.5–11 pt
+  with roomy leading reads well in a 6×9.
+- For a classical look with these choices preconfigured, scaffold the **monograph**
+  template instead of tuning by hand: `unipress create my-book --template monograph`.
+
+## Next
+
+- Add your [covers and images](./covers-and-images.md).
+- Produce your [ebook](./ebooks.md) or go to [print](./print.md).

package/docs/troubleshooting.md

@@ -53,7 +53,7 @@ with `paths: { pages: . }`. It's an ordinary config file; edit it freely.
 To write one by hand instead:
 
 ```yaml
-foundation: "@uniweb/book@0.4.1"
+foundation: "@uniweb/book@0.4.2"
 format: pdf
 paths:
   pages: .          # only needed when sections live at the root (no content/ folder)
@@ -200,6 +200,23 @@ The config file's default export is a string, number, array, or something else.
 export default { format: 'pdf' }
 ```
 
+## Cover image (or other config asset) doesn't appear in the output
+
+Not an error — a silent drop. The book compiles, but the front/back cover (or a
+banner/logo declared in config) is missing from the PDF/EPUB.
+
+Config-declared asset paths — `book.covers.front`, `book.covers.back`, and the like —
+are resolved from the top-level config unipress **reads for content collection**: the
+default `document.yml`, or the file you pass to `--document`. They are *not* scanned from
+a `unipress.config.js` supplied via `--config` (that file layers build settings — `out`,
+`format`, `typst` — over the compile, after content is collected).
+
+So if your covers live in `document-book.yml`, build it with `--variant document-book`
+— not `--config document-book.yml`. Confirm with `--verbose`: the `Found N asset references`
+line should count your covers (e.g. 2 more than the body images), and the source-bundle
+`blob:` size should grow by roughly the covers' byte size. Also confirm the files exist at
+the declared path relative to the content directory (e.g. `assets/front.png`).
+
 ## Internal error (exit code 2)
 
 Something unexpected threw — typically a library error or a code path unipress didn't wrap. Re-run with `--verbose` for a stack trace, then open an issue with the trace and a description of the content directory + foundation you're compiling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/unipress",
-  "version": "0.4.27",
+  "version": "0.4.29",
   "description": "Compile a content directory into a document (PDF, EPUB, Paged.js HTML, Typst source bundle, DOCX, XLSX) using a Uniweb foundation. Five built-in templates: book, monograph, report, data-report, directory.",
   "type": "module",
   "publishConfig": {
@@ -50,9 +50,9 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "@uniweb/runtime": "0.8.20",
+    "@uniweb/build": "0.14.21",
     "@uniweb/core": "0.7.14",
     "@uniweb/content-reader": "1.1.12",
-    "@uniweb/build": "0.14.20",
     "@uniweb/semantic-parser": "1.1.17"
   },
   "devDependencies": {

package/src/cli.js

@@ -25,6 +25,9 @@ Commands:
                                                  latex emits a LaTeX source bundle (run latexmk yourself)
                            --foundation <ref>  override document.yml's foundation: field
                            --out <path>        output file (default: ./<dir>.<ext>)
+                           --variant <name>    build an alternate config <name>.yml in <dir>
+                                                 (e.g. --variant document-book) instead of
+                                                 document.yml — several cuts of one manuscript
                            --config <path>     explicit config file (default: <dir>/unipress.config.js)
                            --typst-binary <p>  path to a typst binary (skips managed download)
                            --keep-temp         keep the typst temp dir on failure (for debugging)
@@ -86,6 +89,7 @@ async function main(argv) {
       format: { type: 'string' },
       out: { type: 'string' },
       config: { type: 'string' },
+      variant: { type: 'string' },
       title: { type: 'string' },
       author: { type: 'string' },
       force: { type: 'boolean' },
@@ -131,6 +135,7 @@ async function main(argv) {
           foundation: values.foundation ?? null,
           out: values.out ?? null,
           config: values.config ?? null,
+          variant: values.variant ?? null,
           typstBinary: values['typst-binary'] ?? null,
           keepTemp: !!values['keep-temp'],
           yes: !!values.yes,

package/src/commands/compile.js

@@ -17,10 +17,18 @@ import { detectConfigFile, CONFIG_FILE_NAMES } from '../document-yml.js'
 import { detectBareContent, materializeDocumentYml } from '../materialize.js'
 import { findCatalogEntry } from '../catalog.js'
 
+// `--variant book` → `book.yml`; `--variant print.yaml` → `print.yaml`.
+// The name is used verbatim — no `document-` prefixing — with a `.yml`
+// extension assumed when none is given. Returns null when unset.
+export function variantToConfigFile(variant) {
+  if (!variant) return null
+  return /\.ya?ml$/i.test(variant) ? variant : `${variant}.yml`
+}
+
 // Bare-folder default: the book foundation's `article` genre — a clean
 // single-column A4 paper, the natural shape for a loose folder of markdown.
 const DEFAULT_FOUNDATION =
-  findCatalogEntry('article')?.foundation?.ref ?? '@uniweb/book@0.4.1'
+  findCatalogEntry('article')?.foundation?.ref ?? '@uniweb/book@0.4.2'
 
 // "durable-structured-systems" → "Durable Structured Systems"
 function titleize(slug) {
@@ -98,7 +106,7 @@ async function offerToMaterialize({ sitePath, format, foundation, yes }) {
   return true
 }
 
-export async function compileCommand({ dir, format = null, foundation = null, out = null, config = null, typstBinary = null, keepTemp = false, yes = false, verbose = false } = {}) {
+export async function compileCommand({ dir, format = null, foundation = null, out = null, config = null, variant = null, typstBinary = null, keepTemp = false, yes = false, verbose = false } = {}) {
   if (!dir) {
     process.stderr.write('error: `compile` requires a directory argument\n')
     process.stderr.write('usage: unipress compile <dir> [--format <fmt>] [--foundation <ref>] [--out <path>] [--config <path>] [--typst-binary <path>] [--keep-temp] [--yes] [--verbose]\n')
@@ -106,7 +114,9 @@ export async function compileCommand({ dir, format = null, foundation = null, ou
   }
 
   const sitePath = resolve(dir)
-  if (existsSync(sitePath) && !detectConfigFile(sitePath)) {
+  // `--variant <name>` names an explicit config; don't offer to generate
+  // one (loadContent throws a clear error if the named file is missing).
+  if (!variant && existsSync(sitePath) && !detectConfigFile(sitePath)) {
     const proceed = await offerToMaterialize({ sitePath, format, foundation, yes })
     if (!proceed) process.exit(1)
   }
@@ -121,6 +131,7 @@ export async function compileCommand({ dir, format = null, foundation = null, ou
     foundationRef: foundation,
     outPath: out,
     configPath: config,
+    documentConfig: variantToConfigFile(variant),
     typstBinaryPath: typstBinary,
     keepTemp,
     onProgress

package/src/compile.js

@@ -52,10 +52,13 @@ export async function compile({
   typstBinaryPath: cliTypstBinaryPath = null,
   keepTemp = false,
   configPath: cliConfigPath = null,
+  documentConfig = null,
   onProgress = () => {}
 } = {}) {
   onProgress('loading content...')
-  const { content, sitePath, configFile } = await loadContent(dir)
+  const { content, sitePath, configFile } = await loadContent(dir, {
+    configFile: documentConfig
+  })
   onProgress(`  ${content.pages.length} page(s) from ${sitePath} (${configFile})`)
 
   // A config exists but nothing was collected — almost always the markdown

package/src/content-loader.js

@@ -8,8 +8,8 @@
 // image asset-processor (which eagerly loads sharp's native binding and
 // blows up in a `bun build --compile` binary).
 
-import { existsSync } from 'node:fs'
-import { resolve, join } from 'node:path'
+import { existsSync, readdirSync } from 'node:fs'
+import { resolve, join, basename } from 'node:path'
 import { collectSiteContent, processCollections } from '@uniweb/build/content'
 import { detectConfigFile, CONFIG_FILE_NAMES } from './document-yml.js'
 import { ContentDirectoryError, DocumentYmlError } from './errors.js'
@@ -121,6 +121,21 @@ async function resolveLocalCollections(siteContent, sitePath) {
   }
 }
 
+// Discoverability aid: when a named `--variant` config is missing, list the
+// YAML configs that ARE present so a typo (or a forgotten `.yml`) is easy to
+// spot and fix.
+function listConfigsHint(sitePath) {
+  try {
+    const ymls = readdirSync(sitePath).filter(
+      (f) => f.endsWith('.yml') || f.endsWith('.yaml'),
+    )
+    if (!ymls.length) return ''
+    return `\navailable configs here: ${ymls.join(', ')}`
+  } catch {
+    return ''
+  }
+}
+
 export async function loadContent(dir, options = {}) {
   const sitePath = resolve(dir)
 
@@ -128,17 +143,39 @@ export async function loadContent(dir, options = {}) {
     throw new ContentDirectoryError(`content directory does not exist: ${sitePath}`)
   }
 
-  const configFile = detectConfigFile(sitePath)
-  if (!configFile) {
-    throw new DocumentYmlError(
-      `no ${CONFIG_FILE_NAMES.PRIMARY} (or ${CONFIG_FILE_NAMES.FALLBACK}) found in ${sitePath}`
-    )
+  // An explicit config name (from `--variant`) selects an alternate
+  // top-level config inside the content dir — e.g. a `document-book.yml`
+  // beside the default `document.yml`. It must exist; we don't fall back
+  // to auto-detection when the user named one. Otherwise auto-detect
+  // `document.yml` / `site.yml`.
+  let configFile
+  if (options.configFile) {
+    configFile = options.configFile
+    if (!existsSync(join(sitePath, configFile))) {
+      throw new DocumentYmlError(
+        `variant config not found: ${join(sitePath, configFile)}${listConfigsHint(sitePath)}`
+      )
+    }
+  } else {
+    configFile = detectConfigFile(sitePath)
+    if (!configFile) {
+      throw new DocumentYmlError(
+        `no ${CONFIG_FILE_NAMES.PRIMARY} (or ${CONFIG_FILE_NAMES.FALLBACK}) found in ${sitePath}`
+      )
+    }
   }
 
+  // unipress is a document tool: read any config that isn't the `site.yml`
+  // dogfood fallback with the document profile (content/ + folder mode +
+  // `content:` ordering), regardless of the file's name. So a variant can
+  // be named freely (book.yml, print.yml) and still build as a document.
+  const profile = basename(configFile).startsWith('site') ? 'site' : 'document'
+
   let content
   try {
     content = await collectSiteContent(sitePath, {
       configFile,
+      profile,
       foundationPath: options.foundationPath
     })
   } catch (err) {

package/src/foundation-fetch.js

@@ -31,27 +31,11 @@
 // field and this module will verify bytes before caching.
 
 import { existsSync } from 'node:fs'
-import { mkdir, writeFile, symlink } from 'node:fs/promises'
-import { dirname, join, posix, resolve as pathResolve } from 'node:path'
-import { createRequire } from 'node:module'
-import { fileURLToPath } from 'node:url'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname, join, posix } from 'node:path'
 import { FoundationFetchError } from './errors.js'
 import { getCacheDir } from './typst/binary-manager.js'
-
-const require = createRequire(import.meta.url)
-
-// Bare specifiers that the foundation expects to resolve externally
-// (matches DEFAULT_EXTERNALS in @uniweb/build). At import time, Node
-// walks up from the cache dir looking for a node_modules/<name>. The
-// cache dir isn't inside any package tree, so we link unipress's own
-// installations into a co-located node_modules.
-const EXTERNAL_PACKAGES = [
-  'react',
-  'react-dom',
-  'react/jsx-runtime',
-  'react/jsx-dev-runtime',
-  '@uniweb/core',
-]
+import { externalShimPackages } from './runtime-externals.js'
 
 // Match `./chunk.js` only in actual ESM import positions — `from './x'`,
 // `import './x'`, or `import('./x')`. A broad "match any quoted ./x.js"
@@ -100,6 +84,10 @@ export async function fetchFoundationToCache(url, { onProgress = () => {} } = {}
     const cached = join(cacheDir, name)
     if (existsSync(cached)) {
       onProgress(`using cached foundation: ${cached}`)
+      // Refresh the external shims even on a cache hit: it's a handful of tiny
+      // files, and it self-heals a cache populated by an older unipress (which
+      // left an empty node_modules or dead symlinks that no longer resolve).
+      await writeExternalShims(cacheDir, onProgress)
       return cached
     }
   }
@@ -138,7 +126,7 @@ export async function fetchFoundationToCache(url, { onProgress = () => {} } = {}
       if (!fetched.has(discovered)) queue.push(discovered)
     }
   }
-  await linkExternals(cacheDir, onProgress)
+  await writeExternalShims(cacheDir, onProgress)
   const entryPath = join(cacheDir, entryName)
   onProgress(`foundation cached at ${cacheDir} (${fetched.size} file(s))`)
   return entryPath
@@ -171,63 +159,32 @@ async function pickRemoteEntry(baseUrl, onProgress) {
   )
 }
 
-// Make unipress's own copies of the externalized packages reachable
-// from the cache dir. Node's ESM loader walks up from the importing
-// file looking for `node_modules/<name>` — by placing a node_modules
-// directory next to the cached entry with symlinks to each
-// external's package directory, bare imports inside the foundation
-// resolve to unipress's already-installed copies. This keeps a single
-// React instance (unipress's) across host and foundation.
-async function linkExternals(cacheDir, onProgress) {
+// Lay shim modules for the foundation's externalized peer deps into a
+// node_modules beside the cached entry, so the dynamically imported foundation
+// resolves react / react-dom / @uniweb/core to unipress's own bundled instances
+// (via the globalThis bridge in runtime-externals.js) rather than hunting for a
+// node_modules that isn't there.
+//
+// Replaces the old symlink-to-local-copies approach, which couldn't locate
+// on-disk copies inside the `bun --compile` binary: the deps are bundled into
+// the binary, and require.resolve resolves relative to the CWD, so it found
+// nothing when unipress ran from a project with no react up its tree. The shims
+// read the bridge instead of resolving a real package, so they work from any
+// directory and in any distribution. See runtime-externals.js for the full
+// rationale and the single-instance guarantee.
+//
+// Idempotent and overwriting: cheap (a handful of tiny files), and self-heals a
+// cache left in a bad state by an older unipress.
+async function writeExternalShims(cacheDir, onProgress) {
   const nmDir = join(cacheDir, 'node_modules')
-  await mkdir(nmDir, { recursive: true })
-  // Collapse subpath specifiers (react/jsx-runtime → react) to the
-  // package-root specifier we actually link. Deduped.
-  const rootSpecs = new Set()
-  for (const spec of EXTERNAL_PACKAGES) {
-    rootSpecs.add(spec.startsWith('@')
-      ? spec.split('/').slice(0, 2).join('/')  // '@scope/name'
-      : spec.split('/')[0])                     // 'name'
-  }
-  for (const name of rootSpecs) {
-    const dest = name.startsWith('@')
-      ? join(nmDir, ...name.split('/'))         // node_modules/@scope/name
-      : join(nmDir, name)                       // node_modules/name
-    if (existsSync(dest)) continue
-    try {
-      const pkgDir = findPackageRoot(name)
-      if (!pkgDir) {
-        onProgress(`  warn: cannot find '${name}' in unipress deps — foundation may fail to import`)
-        continue
-      }
-      await mkdir(dirname(dest), { recursive: true })
-      await symlink(pkgDir, dest, 'dir')
-      onProgress(`  linked ${name} → ${pkgDir}`)
-    } catch (err) {
-      onProgress(`  warn: linking ${name} failed: ${err.message}`)
+  for (const pkg of externalShimPackages()) {
+    const pkgDir = join(nmDir, ...pkg.dir.split('/'))
+    await mkdir(pkgDir, { recursive: true })
+    await writeFile(join(pkgDir, 'package.json'), pkg.packageJson)
+    for (const [rel, source] of Object.entries(pkg.files)) {
+      await writeFile(join(pkgDir, rel), source)
     }
-  }
-}
-
-function findPackageRoot(name) {
-  try {
-    // Resolve the package's `package.json` to find its root.
-    const pkgJson = require.resolve(`${name}/package.json`)
-    return dirname(pkgJson)
-  } catch {
-    // Fallback: resolve a default export and strip back.
-    try {
-      const entry = require.resolve(name)
-      let dir = dirname(entry)
-      while (dir !== dirname(dir)) {
-        if (existsSync(join(dir, 'package.json'))) {
-          const pkg = JSON.parse(require('fs').readFileSync(join(dir, 'package.json'), 'utf8'))
-          if (pkg.name === name || pkg.name === name.split('/')[0]) return dir
-        }
-        dir = dirname(dir)
-      }
-    } catch {}
-    return null
+    onProgress(`  shimmed ${pkg.dir} → unipress's bundled copy`)
   }
 }
 

package/src/foundations-data.js

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

package/src/orchestrator.js

@@ -21,14 +21,23 @@
 //
 // React-instance note (gotcha #2): @uniweb/runtime/ssr (built bundle) imports
 // React as an external; the foundation does the same. Both must resolve to the
-// same React instance, otherwise hooks in foundation components throw "Invalid
-// hook call". Inside this monorepo react is hoisted; in a real npm install of
-// unipress, both also resolve from unipress's node_modules.
+// SAME React instance, otherwise hooks in foundation components throw "Invalid
+// hook call" — and the foundation must see the SAME @uniweb/core unipress built
+// the Website graph with. Importing runtime-externals.js (below) publishes
+// unipress's own bundled react / react-dom / @uniweb/core on a globalThis
+// bridge and drives the cache-side shim modules that the fetched foundation
+// resolves against, guaranteeing one shared instance regardless of how unipress
+// is run (source, npm install, or the bun --compile binary). See
+// runtime-externals.js for the full rationale.
 
 import { pathToFileURL } from 'node:url'
 import { readFile } from 'node:fs/promises'
 import { initPrerender } from '@uniweb/runtime/ssr'
 import { FoundationResolutionError, CompileError } from './errors.js'
+// Side-effect import: sets the globalThis bridges before any foundation is
+// dynamically imported. ESM evaluates it once (foundation-fetch.js imports it
+// too, to generate the matching shims).
+import './runtime-externals.js'
 
 export async function importFoundation(resolvedPath) {
   try {