gutterpress 0.10.0-alpha.4 → 0.10.0

package/dist/{index-xxg4zfrg.js → index-wq3r5pj7.js}

@@ -1,7 +1,10 @@
 import {
   getAssetPath,
-  launchChromium
-} from "./index-9tyq9kks.js";
+  isIgnoredMarginBoxProperty,
+  launchChromium,
+  marginBoxAlign,
+  marginBoxRectPt
+} from "./index-ycpvr0am.js";
 
 // src/engine/compiler/build.ts
 import { readFile } from "node:fs/promises";
@@ -568,6 +571,45 @@ function specificity(r) {
   return (r.name ? 2 : 0) + r.pseudos.length;
 }
 
+// src/engine/shared/flush.ts
+var FLUSH_EDGES = ["top", "right", "bottom", "left"];
+function flushKey(edges) {
+  return FLUSH_EDGES.filter((e) => edges.includes(e)).map((e) => e[0]).join("");
+}
+function flushPageName(authorPage, edges) {
+  const safe = authorPage ? authorPage.replace(/[^A-Za-z0-9_-]/g, "_") : "";
+  return `gp--flush${safe ? `-${safe}` : ""}-${flushKey(edges)}`;
+}
+function flushMargins(margin, edges) {
+  return {
+    top: edges.includes("top") ? 0 : margin.top,
+    right: edges.includes("right") ? 0 : margin.right,
+    bottom: edges.includes("bottom") ? 0 : margin.bottom,
+    left: edges.includes("left") ? 0 : margin.left
+  };
+}
+function marginBoxesOnEdges(edges) {
+  const owners = {
+    "top-left-corner": ["top", "left"],
+    "top-left": ["top"],
+    "top-center": ["top"],
+    "top-right": ["top"],
+    "top-right-corner": ["top", "right"],
+    "bottom-left-corner": ["bottom", "left"],
+    "bottom-left": ["bottom"],
+    "bottom-center": ["bottom"],
+    "bottom-right": ["bottom"],
+    "bottom-right-corner": ["bottom", "right"],
+    "left-top": ["left"],
+    "left-middle": ["left"],
+    "left-bottom": ["left"],
+    "right-top": ["right"],
+    "right-middle": ["right"],
+    "right-bottom": ["right"]
+  };
+  return Object.entries(owners).filter(([, own]) => own.some((e) => edges.includes(e))).map(([name]) => name);
+}
+
 // src/engine/shared/synthesis.ts
 var RECTO_VERSO_VALUES = /^(right|recto|left|verso)$/;
 function isRectoVersoBreak(decl) {
@@ -1284,7 +1326,8 @@ var BUILD_DIAGNOSTIC_CODES = [
   "engine.layer.trapped",
   "engine.multicol.dead-column",
   "engine.content.overheight",
-  "engine.image.low-dpi"
+  "engine.image.low-dpi",
+  "engine.flush.margin-box"
 ];
 async function build(opts) {
   const log = opts.onProgress ?? (() => {});
@@ -1303,8 +1346,7 @@ async function build(opts) {
     await page.evaluate(AGENT);
     await page.waitForReady();
     const cssText = await page.evaluate(`window.__gp.collectCss()`);
-    const model = extract(cssText);
-    const { tier3Reasons } = classify(model);
+    let model = extract(cssText);
     const baseGeom = resolvePage(model).geometry;
     const sheetViewport = {
       width: Math.max(1, Math.round(baseGeom.width * 96 / 72)),
@@ -1315,6 +1357,97 @@ async function build(opts) {
     await page.send("Emulation.setDeviceMetricsOverride", sheetViewport);
     await page.send("Emulation.setEmulatedMedia", { media: "print" });
     log(`print media emulated for audits and measurement`);
+    const flushRoots = await page.evaluate(`window.__gp.flushRoots()`);
+    const flushGroups = new Map;
+    for (const root of flushRoots) {
+      if (flushGroups.has(root.key))
+        continue;
+      const authorPage = root.page === "auto" ? undefined : root.page;
+      flushGroups.set(root.key, {
+        authorPage,
+        edges: root.edges,
+        genName: flushPageName(authorPage, root.edges),
+        key: root.key
+      });
+    }
+    if (flushGroups.size) {
+      const lines = [];
+      for (const group of flushGroups.values()) {
+        const relocated = new Set(marginBoxesOnEdges(group.edges));
+        const pseudoSets = [[]];
+        if (group.authorPage) {
+          for (const rule of model.pageRules) {
+            if (rule.name !== group.authorPage)
+              continue;
+            const pseudo = rule.pseudos.length ? `:${rule.pseudos.join(":")}` : "";
+            if (rule.pseudos.length && !pseudoSets.some((ps) => ps.length === rule.pseudos.length && rule.pseudos.every((x) => ps.includes(x))))
+              pseudoSets.push(rule.pseudos);
+            const body = [];
+            for (const [prop, value] of Object.entries(rule.decls))
+              body.push(`  ${prop}: ${value};`);
+            for (const [box, decls] of Object.entries(rule.marginBoxes)) {
+              if (relocated.has(box.slice(1)))
+                continue;
+              body.push(`  ${box} {`);
+              for (const [prop, value] of Object.entries(decls))
+                body.push(`    ${prop}: ${value};`);
+              body.push(`  }`);
+            }
+            lines.push(`@page ${group.genName}${pseudo} {
+${body.join(`
+`)}
+}`);
+          }
+        }
+        for (const pseudos of pseudoSets) {
+          const pseudo = pseudos.length ? `:${pseudos.join(":")}` : "";
+          const body = [];
+          for (const edge of group.edges)
+            body.push(`  margin-${edge}: 0;`);
+          for (const box of relocated)
+            body.push(`  @${box} { content: none; }`);
+          lines.push(`@page ${group.genName}${pseudo} {
+${body.join(`
+`)}
+}`);
+        }
+        lines.push(`:where(.page, .spread)[data-gp-flush="${group.key}"][data-gp-flush][data-gp-flush][data-gp-flush] { page: ${group.genName}; }`);
+      }
+      const flushCss = lines.join(`
+`);
+      await page.evaluate(`window.__gp.addCss("gp-flush-css", ${JSON.stringify(flushCss)})`);
+      model = extract(`${cssText}
+${flushCss}`);
+      log(`.gp-flush: ${flushRoots.length} pinned root(s) -> ${flushGroups.size} generated page context(s)`);
+    }
+    const { tier3Reasons } = classify(model);
+    const pseudoContexts = pagePseudoContexts(model);
+    const contentHeightPt = (name) => Math.min(...pseudoContexts.map((pseudos) => {
+      const geometry = resolvePage(model, { name, pseudos }).geometry;
+      return geometry.height - geometry.margin.top - geometry.margin.bottom;
+    }));
+    const contentHeightPx = contentHeightPt() * 96 / 72;
+    const namedContentHeightsPx = Object.fromEntries(model.pageNames.map((name) => [name, contentHeightPt(name) * 96 / 72]));
+    const minContentHeightPx = Math.min(contentHeightPt(), ...model.pageNames.map((name) => contentHeightPt(name))) * 96 / 72;
+    const pageVarsCss = [
+      `:root { --gp-content-h: ${contentHeightPx}px; }`,
+      ...model.pageAssignments.map((a) => `${a.selector} { --gp-content-h: ${namedContentHeightsPx[a.page] ?? contentHeightPx}px; }`)
+    ].join(`
+`);
+    await page.evaluate(`window.__gp.addCss("gp-page-vars", ${JSON.stringify(pageVarsCss)})`);
+    log(`page geometry published (--gp-content-h: ${Math.round(contentHeightPx)}px)`);
+    const relocationBoxes = (group, pseudos) => {
+      const ctx = resolvePage(model, { name: group.authorPage, pseudos });
+      return marginBoxesOnEdges(group.edges).map((name) => [name, ctx.marginBoxes[`@${name}`]]).filter((pair) => {
+        const c = pair[1]?.content?.trim();
+        return !!c && c !== "none" && c !== "normal";
+      });
+    };
+    const furnitureRoots = flushRoots.filter((root) => {
+      const group = flushGroups.get(root.key);
+      return pseudoContexts.some((pseudos) => relocationBoxes(group, pseudos).length > 0);
+    });
+    const flushDiagnosed = new Set;
     const tier2 = synthesize({
       model,
       marks: opts.marks,
@@ -1334,11 +1467,15 @@ async function build(opts) {
     }).join(`
 `);
     if (widthOffenders.boxes.length) {
-      const msg = `content wider than the page content box triggers Chromium print ` + `shrink-to-fit (the WHOLE book scales down, silently):
+      const scale = shrinkScale(widthOffenders.boxes, widthOffenders.limitPx);
+      const headline = scale === null ? `content outside the page content box risks Chromium print ` + `shrink-to-fit (the WHOLE book scales down, silently)` : `content wider than the page content box: Chromium print shrink-to-fit ` + `scales the WHOLE document — every page, every measurement — to about ` + `${scale.toFixed(2)}x its declared size (12pt type prints at ` + `${(12 * scale).toFixed(1)}pt). The page size and page count do not ` + `change, so the shrink is invisible in the PDF`;
+      const msg = `${headline}:
 ${describe(widthOffenders.boxes)}`;
       if (opts.allowShrink) {
+        if (scale !== null)
+          diagnose("engine.width.overflow", `${headline}.`);
         for (const o of widthOffenders.boxes)
-          diagnose("engine.width.overflow", `${o.desc} is wider than the page — Chromium shrinks the WHOLE book to fit it. ${o.left < -1 ? "Keep it inside the page content box." : "Give it an explicit width that fits."}`);
+          diagnose("engine.width.overflow", `${o.desc} is ${Math.round(o.px)}px wide, past the ${Math.round(widthOffenders.limitPx)}px page content box. ${o.left < -1 ? "Keep it inside the page content box." : "Give it an explicit width that fits."}`);
         log(`WARNING: ${msg}`);
       } else {
         throw new Error(`${msg}
@@ -1353,7 +1490,7 @@ ${describe(widthOffenders.intrinsics)}`;
       log(`WARNING: ${msg}`);
     }
     const rectoDecls = model.breaks.filter(isRectoVersoBreak);
-    const needsMeasure = tier3Reasons.length > 0 || consumedStrings(model).size > 0 || rectoDecls.length > 0 || model.counterResets.length > 0;
+    const needsMeasure = tier3Reasons.length > 0 || consumedStrings(model).size > 0 || rectoDecls.length > 0 || model.counterResets.length > 0 || furnitureRoots.length > 0;
     let tier = tier2.geometry.bleed > 0 || tier2.geometry.slug > 0 ? 2 : 1;
     let passes = 1;
     let pageMap = {};
@@ -1381,6 +1518,8 @@ ${describe(widthOffenders.intrinsics)}`;
         targets.add(s.id);
       for (const s of resetSites)
         targets.add(s.id);
+      for (const r of furnitureRoots)
+        targets.add(r.id);
       await page.evaluate(`window.__gp.instrument(${JSON.stringify([...targets])})`);
       const targetText = await page.evaluate(`window.__gp.targetTexts(${JSON.stringify([...targets])})`);
       const brokenXrefs = findBrokenXrefRefs(sites, targetText);
@@ -1465,6 +1604,73 @@ ${describe(widthOffenders.intrinsics)}`;
 /* Tier 3 */
 ${mapCss}`;
         }
+        if (furnitureRoots.length) {
+          const pageAt = (id) => map[id] ?? predictedForResult?.pageMap[id];
+          const byName = new Map;
+          for (const s of sources) {
+            const p = pageAt(s.id);
+            if (!p)
+              continue;
+            const list = byName.get(s.name) ?? [];
+            list.push({ page: p, value: s.text });
+            byName.set(s.name, list);
+          }
+          for (const entries of byName.values())
+            entries.sort((a, b) => a.page - b.page);
+          const PXPT = 96 / 72;
+          const items = [];
+          for (const root of furnitureRoots) {
+            const physical = pageAt(root.id);
+            if (!physical)
+              continue;
+            const group = flushGroups.get(root.key);
+            const pseudos = [physical % 2 === 1 ? "right" : "left"];
+            if (physical === 1)
+              pseudos.push("first");
+            const ctx = resolvePage(model, { name: group.authorPage, pseudos });
+            const g = ctx.geometry;
+            const eff = flushMargins(g.margin, group.edges);
+            const boxes = [];
+            for (const [name, decls] of relocationBoxes(group, pseudos)) {
+              const text = evaluate(decls.content, {
+                page: toFolioPage(physical, pageValues),
+                pages: pageCount,
+                strings: (n, w) => stringValueAt(byName.get(n) ?? [], physical, parseWhich(w)),
+                targetPage: (u) => {
+                  const p = pageAt(u.replace(/^#/, ""));
+                  return p === undefined ? undefined : toFolioPage(p, pageValues);
+                }
+              });
+              if (!text) {
+                if (!flushDiagnosed.has(name)) {
+                  flushDiagnosed.add(name);
+                  diagnose("engine.flush.margin-box", `@${name} sits on an edge a .gp-flush pin frees, and its content could not be ` + `re-homed into the page (unsupported content value: ${decls.content}). It will ` + `not print on that page — simplify the box's content, or drop .gp-flush there.`);
+                }
+                continue;
+              }
+              const r = marginBoxRectPt(name, g);
+              const outDecls = {};
+              for (const [prop, value] of Object.entries(decls)) {
+                if (prop.toLowerCase() === "content" || isIgnoredMarginBoxProperty(prop))
+                  continue;
+                outDecls[prop] = value;
+              }
+              boxes.push({
+                box: name,
+                x: (r.x - eff.left) * PXPT,
+                y: (r.y - eff.top) * PXPT,
+                w: r.w * PXPT,
+                h: r.h * PXPT,
+                align: marginBoxAlign(name),
+                text,
+                decls: outDecls
+              });
+            }
+            items.push({ id: root.id, boxes });
+          }
+          if (items.length)
+            await page.evaluate(`window.__gp.setFlushFurniture(${JSON.stringify(items)})`);
+        }
       };
       const predicted = await predictPageMap(browser, url, AGENT, VIEWER, {
         stringSets: model.stringSets.map((s) => ({ selector: s.selector, name: s.name, value: s.value })),
@@ -1503,14 +1709,6 @@ ${mapCss}`;
         log(`tier 3: NOT converged after ${passes} passes`);
       }
     }
-    const pseudoContexts = pagePseudoContexts(model);
-    const contentHeightPt = (name) => Math.min(...pseudoContexts.map((pseudos) => {
-      const geometry = resolvePage(model, { name, pseudos }).geometry;
-      return geometry.height - geometry.margin.top - geometry.margin.bottom;
-    }));
-    const contentHeightPx = contentHeightPt() * 96 / 72;
-    const namedContentHeightsPx = Object.fromEntries(model.pageNames.map((name) => [name, contentHeightPt(name) * 96 / 72]));
-    const minContentHeightPx = Math.min(contentHeightPt(), ...model.pageNames.map((name) => contentHeightPt(name))) * 96 / 72;
     {
       const audit = await page.evaluate(`window.__gp.auditContent(${JSON.stringify({
         default: contentHeightPx,
@@ -1564,6 +1762,26 @@ ${mapCss}`;
             return reasons;
           };
 
+          // Does this box establish the containing block for an absolutely
+          // positioned descendant? Overflow clipping binds an abspos
+          // .gp-pin only from its containing block outward — MEASURED: a
+          // pin whose box lay entirely outside a STATIC overflow:hidden
+          // (and overflow:clip) wrapper printed complete and still behind
+          // the page text; the wrapper's clip never touched it.
+          const establishesAbsContainingBlock = (cs) => {
+            if (cs.position !== "static") return true;
+            for (const prop of [
+              "transform", "translate", "rotate", "scale", "perspective",
+              "filter", "backdropFilter",
+            ]) {
+              const value = cs[prop];
+              if (value && value !== "none") return true;
+            }
+            if (/\\b(layout|paint|strict|content)\\b/.test(cs.contain)) return true;
+            if (cs.containerType && cs.containerType !== "normal") return true;
+            return /\\b(transform|translate|rotate|scale|perspective|filter)\\b/.test(cs.willChange);
+          };
+
           for (const el of document.querySelectorAll("*")) {
             const cs = getComputedStyle(el);
             if (leaks.length < 20) {
@@ -1604,20 +1822,58 @@ ${mapCss}`;
             ) {
               const boundary = el.closest(".page, .spread");
               if (boundary) {
+                const elRect = el.getBoundingClientRect();
+                // Clip binding: an in-flow .gp-behind is bound by every
+                // ancestor's overflow, but an abspos one only from its
+                // containing block outward — static wrappers in between
+                // never clip it (measured; see the pass comment above).
+                let clipBinds = cs.position !== "absolute" && cs.position !== "fixed";
                 for (let ancestor = el.parentElement; ancestor; ancestor = ancestor.parentElement) {
                   const ancestorStyle = getComputedStyle(ancestor);
+                  if (!clipBinds && establishesAbsContainingBlock(ancestorStyle)) clipBinds = true;
                   const reasons = stackingReasons(ancestor, ancestorStyle);
-                  const clips = ancestorStyle.overflowX !== "visible" ||
-                    ancestorStyle.overflowY !== "visible";
-                  if ((reasons.length || clips) && !seenLayerTraps.has(ancestor)) {
+                  // Clipping never reorders layers — it can only CUT the
+                  // art (measured, pass comment above): warn only where the
+                  // border box crosses a binding ancestor's clip edge on an
+                  // axis whose overflow is not \`visible\`. The clip edge is
+                  // the padding box, grown by overflow-clip-margin where
+                  // that axis's value is \`clip\` (px values only; keyword
+                  // forms parse NaN -> 0, i.e. the ungrown padding box).
+                  // 1px epsilon: the measured cut lands exactly at the
+                  // edge, and sub-pixel layout rounding is not an overhang.
+                  const cuts = [];
+                  if (clipBinds && (ancestorStyle.overflowX !== "visible" || ancestorStyle.overflowY !== "visible")) {
+                    const r = ancestor.getBoundingClientRect();
+                    const clipMargin = parseFloat(ancestorStyle.overflowClipMargin) || 0;
+                    if (ancestorStyle.overflowX !== "visible") {
+                      const grow = ancestorStyle.overflowX === "clip" ? clipMargin : 0;
+                      const left = r.left + parseFloat(ancestorStyle.borderLeftWidth) - grow;
+                      const right = r.right - parseFloat(ancestorStyle.borderRightWidth) + grow;
+                      if (elRect.left < left - 1)
+                        cuts.push(Math.round(left - elRect.left) + "px past its left clip edge");
+                      if (elRect.right > right + 1)
+                        cuts.push(Math.round(elRect.right - right) + "px past its right clip edge");
+                    }
+                    if (ancestorStyle.overflowY !== "visible") {
+                      const grow = ancestorStyle.overflowY === "clip" ? clipMargin : 0;
+                      const top = r.top + parseFloat(ancestorStyle.borderTopWidth) - grow;
+                      const bottom = r.bottom - parseFloat(ancestorStyle.borderBottomWidth) + grow;
+                      if (elRect.top < top - 1)
+                        cuts.push(Math.round(top - elRect.top) + "px past its top clip edge");
+                      if (elRect.bottom > bottom + 1)
+                        cuts.push(Math.round(elRect.bottom - bottom) + "px past its bottom clip edge");
+                    }
+                  }
+                  if ((reasons.length || cuts.length) && !seenLayerTraps.has(ancestor)) {
                     seenLayerTraps.add(ancestor);
                     const effects = [];
                     if (reasons.length)
                       effects.push("creates a stacking context (" + reasons.join(", ") + ")");
-                    if (clips)
+                    if (cuts.length)
                       effects.push(
-                        "clips descendants (overflow-x: " + ancestorStyle.overflowX +
-                        ", overflow-y: " + ancestorStyle.overflowY + ")"
+                        "clips it (overflow-x: " + ancestorStyle.overflowX +
+                        ", overflow-y: " + ancestorStyle.overflowY +
+                        ") — the art extends " + cuts.join(" and ") + " and is cut off there"
                       );
                     layerTraps.push({
                       behind: desc(el),
@@ -1685,10 +1941,17 @@ async function printPdf(page) {
   await page.waitForReady();
   return page.printToPDF();
 }
+var MAX_SHRINK = 1.5;
+function shrinkScale(boxes, limitPx) {
+  const maxRight = Math.max(...boxes.map((o) => o.px + Math.min(0, o.left)));
+  if (!(maxRight > limitPx))
+    return null;
+  return Math.max(1 / MAX_SHRINK, limitPx / maxRight);
+}
 async function findWidthOffenders(page, model, bleedSlugExtensionPt, restoreViewport) {
   const contexts = [
     resolvePage(model),
-    ...model.pageNames.filter((n) => !n.startsWith("gp-")).map((n) => resolvePage(model, { name: n }))
+    ...model.pageNames.filter((n) => !n.startsWith("gp-") || n.startsWith("gp--flush-")).map((n) => resolvePage(model, { name: n }))
   ];
   const maxContentPt = Math.max(...contexts.map((c) => c.geometry.width - c.geometry.margin.left - c.geometry.margin.right)) + bleedSlugExtensionPt;
   const limitPx = maxContentPt * 96 / 72;
@@ -1775,6 +2038,7 @@ async function predictPageMap(browser, url, agentScript, viewerScript, args, she
     await page.waitForReady();
     await page.evaluate(`window.__GP_MANUAL__ = true;`);
     await page.evaluate(viewerScript);
+    await page.evaluate(`window.__gp.flushRoots()`);
     await page.evaluate(`window.__gp.stringSources(${JSON.stringify(args.stringSets)})`);
     if (args.rectoDecls.length)
       await page.evaluate(`window.__gp.forcedBreakSites(${JSON.stringify(args.rectoDecls)})`);

package/dist/{index-9tyq9kks.js → index-ycpvr0am.js}

@@ -596,7 +596,7 @@ var favicon_default = "./favicon-wkbm9cjn.ico";
 var manifest_schema_default = "./manifest.schema-zxgxnbg7.json";
 
 // src/assets/preview/scripts/preview-interface.js
-var preview_interface_default = "./preview-interface-435cczt5.js";
+var preview_interface_default = "./preview-interface-0ssk8bmm.js";
 
 // src/assets/preview/scripts/preview-bridge.js
 var preview_bridge_default = "./preview-bridge-fz7vpk8m.js";
@@ -608,10 +608,10 @@ var preview_shell_default = "./preview-shell-c5mfa3q0.js";
 var CGATS21_CRPC1_default = "./CGATS21_CRPC1-g0e3k7kr.icc";
 
 // src/assets/engine/gutterpress-viewer.js
-var gutterpress_viewer_default = "./gutterpress-viewer-cem7dmr5.js";
+var gutterpress_viewer_default = "./gutterpress-viewer-te8g5grx.js";
 
 // src/assets/engine/gutterpress-agent.js
-var gutterpress_agent_default = "./gutterpress-agent-1ctgfz92.js";
+var gutterpress_agent_default = "./gutterpress-agent-cazqstr1.js";
 
 // src/assets/templates/book/manifest.yaml
 var manifest_default = "./manifest-n1gh3qw5.yaml";
@@ -705,4 +705,47 @@ async function getAssetPath(relPath) {
   return join3(root, relPath);
 }
 
-export { EXIT_CODES, BuildError, run, spawnCapture, execCapture, isToolAvailable, findTool, INSTALL_HINTS, fullInstallHint, resolveChromiumExecutable, requireChromiumExecutable, RENDER_TIMEOUT_MS, prewarmBrowser, getBrowser, closeBrowser, getAssetPath, REQUIRED_MILESTONE, assertMilestone, readyProbeExpr, DEFAULT_PRINT_OPTS, launchChromium, connectChromium };
+// src/engine/shared/margin-box-support.ts
+var MARGIN_BOX_IGNORED_PROPERTIES = new Set([
+  "transform",
+  "rotate",
+  "translate",
+  "scale",
+  "box-shadow"
+]);
+function isIgnoredMarginBoxProperty(property) {
+  return MARGIN_BOX_IGNORED_PROPERTIES.has(property.toLowerCase());
+}
+function marginBoxRectPt(name, g) {
+  const { top, right, bottom, left } = g.margin;
+  const cw = g.width - left - right;
+  const ch = g.height - top - bottom;
+  const third = (n) => n / 3;
+  const T = {
+    "top-left-corner": [0, 0, left, top],
+    "top-left": [left, 0, third(cw), top],
+    "top-center": [left + third(cw), 0, third(cw), top],
+    "top-right": [left + 2 * third(cw), 0, third(cw), top],
+    "top-right-corner": [g.width - right, 0, right, top],
+    "bottom-left-corner": [0, g.height - bottom, left, bottom],
+    "bottom-left": [left, g.height - bottom, third(cw), bottom],
+    "bottom-center": [left + third(cw), g.height - bottom, third(cw), bottom],
+    "bottom-right": [left + 2 * third(cw), g.height - bottom, third(cw), bottom],
+    "bottom-right-corner": [g.width - right, g.height - bottom, right, bottom],
+    "left-top": [0, top, left, third(ch)],
+    "left-middle": [0, top + third(ch), left, third(ch)],
+    "left-bottom": [0, top + 2 * third(ch), left, third(ch)],
+    "right-top": [g.width - right, top, right, third(ch)],
+    "right-middle": [g.width - right, top + third(ch), right, third(ch)],
+    "right-bottom": [g.width - right, top + 2 * third(ch), right, third(ch)]
+  };
+  const [x, y, w, h] = T[name] ?? [0, 0, 0, 0];
+  return { x, y, w, h };
+}
+function marginBoxAlign(name) {
+  if (name.includes("center") || name.includes("middle"))
+    return "center";
+  return /right/.test(name) ? "end" : "start";
+}
+
+export { EXIT_CODES, BuildError, run, spawnCapture, execCapture, isToolAvailable, findTool, INSTALL_HINTS, fullInstallHint, resolveChromiumExecutable, requireChromiumExecutable, RENDER_TIMEOUT_MS, prewarmBrowser, getBrowser, closeBrowser, getAssetPath, MARGIN_BOX_IGNORED_PROPERTIES, isIgnoredMarginBoxProperty, marginBoxRectPt, marginBoxAlign, REQUIRED_MILESTONE, assertMilestone, readyProbeExpr, DEFAULT_PRINT_OPTS, launchChromium, connectChromium };

package/dist/index.js

@@ -140,15 +140,15 @@ import {
   validateProjectPlugins,
   verifyRepoReadable,
   writeAppHeartbeat
-} from "./index-05y3dnxq.js";
+} from "./index-ge7q9xj3.js";
 import {
   BUILD_DIAGNOSTIC_CODES
-} from "./index-xxg4zfrg.js";
+} from "./index-wq3r5pj7.js";
 import {
   BuildError,
   DEFAULT_PRINT_OPTS,
   readyProbeExpr
-} from "./index-9tyq9kks.js";
+} from "./index-ycpvr0am.js";
 import {
   AUTO_SNAPSHOT_MESSAGE,
   HISTORY_PAGE_LIMIT,

package/dist/lib/build-runner.d.ts

@@ -22,6 +22,13 @@ export interface BuildRunnerOptions {
     skipLint?: boolean;
     skipPreValidate?: boolean;
     skipPostValidate?: boolean;
+    /**
+     * Proceed past the engine's over-wide-content check (pdf/pdfx only), which
+     * otherwise hard-errors because Chromium silently scales the WHOLE book down
+     * to fit the offending box. Each offender is still reported as a warning +
+     * diagnostic — this buys an eyes-open build, not a clean one.
+     */
+    allowShrink?: boolean;
     /**
      * Keep the pooled headless browser alive after the build returns. A one-shot
      * CLI build leaves this false so the process can exit; a long-lived

package/dist/lib/build-staging.d.ts

@@ -1,3 +1,4 @@
+import { type AssetCopy } from "./asset-inline";
 /**
  * `--format html`: ship the self-contained `book.html` (already fully
  * inlined — see `lib/asset-inline.ts`) alongside a copy of the native engine's
@@ -8,6 +9,56 @@
  * in the migration plan).
  */
 export declare function shipViewerHtml(htmlFile: string, outDir: string): Promise<void>;
+/** The copy plan, handed to `onPlan` before a single byte is written. */
+export interface StagingPlan {
+    /** Refs that name no in-project file at all (absolute, or outside the book). */
+    unresolved: string[];
+    /** How many files the staging is about to copy. */
+    copyCount: number;
+}
+/** What `stageBookAssets` could not stage, for the caller to report. */
+export interface StagedAssets {
+    /** Output-relative paths whose source file does not exist; a placeholder shipped. */
+    missing: string[];
+}
+/**
+ * Turn a freshly rendered `book.html` plus its reported asset references into a
+ * COMPLETE, self-contained staged book in `outDir` — the exact document both
+ * renderers must paginate.
+ *
+ * THE one implementation: `renderBook` (every real build/export) and the
+ * preview/print parity gate both call this, so the gate can never measure a
+ * document the build would not have produced. It previously hand-rolled a bare
+ * `copyFile` loop, which (a) hard-crashed with a raw `ENOENT` on any book
+ * carrying a stale image path — i.e. the tool that enforces preview↔print
+ * parity could not run on the real books that need it — and (b) skipped
+ * `inlineShapeUrls`, so `.gp-shape` wrapping silently differed from the build.
+ *
+ * A missing image is NOT fatal: the same magenta placeholder the build ships
+ * (see missing-asset-placeholder.ts) is substituted and every reference
+ * rewritten to it, so the staged layout matches the build's. What could not be
+ * staged is returned, never swallowed — callers decide how loud to be.
+ *
+ * A ref that resolves to no in-project file at all is a different matter, and
+ * the two callers disagree about it: a real build refuses to ship (it throws
+ * from `onPlan`, before any bytes are copied), while the gate reports it and
+ * measures the book anyway. That is why the plan is handed out rather than
+ * judged here.
+ */
+export declare function stageBookAssets(options: {
+    /** Project dir every image ref resolves against. */
+    renderDir: string;
+    /** Directory the staged book is being assembled in. */
+    outDir: string;
+    /** The rendered `book.html`, rewritten in place. */
+    htmlFile: string;
+    /** Image `src` values the render reported. */
+    imageRefs: Iterable<string>;
+    /** CSS images too large to inline, already planned by the render. */
+    cssAssets: AssetCopy[];
+    /** Called once with the copy plan; throw here to abort before copying. */
+    onPlan?: (plan: StagingPlan) => void;
+}): Promise<StagedAssets>;
 /**
  * Create a unique scratch directory under the OS temp dir. Used only for
  * PDF/X intermediates (`raw.pdf`, Ghostscript work files) — never for staging

package/dist/lib/engine.d.ts

@@ -6,6 +6,15 @@ export interface NativePdfOptions {
     title?: string;
     author?: string;
     signature?: number;
+    /**
+     * Downgrade the engine's over-wide-content hard error to a warning +
+     * diagnostic. The engine's message tells the author to "pass allowShrink to
+     * build anyway"; without this the advice is unreachable from every product
+     * path (only a test and the parity gate could set it). The book still prints
+     * at Chromium's mystery shrink scale, which is why this is opt-in per build
+     * and never a config default.
+     */
+    allowShrink?: boolean;
 }
 /**
  * Render `htmlFile` to `outPdf` via the Gutterpress engine. No HTTP staging,

package/dist/lib/markdown/gutterpress-css.d.ts

@@ -41,6 +41,14 @@
  *   .gp-pin       — pins within the nearest @page/@spread container;
  *                   centered on both axes unless combined with the edge
  *                   modifiers .gp-top/.gp-bottom/.gp-left/.gp-right.
+ *   .gp-flush     — with .gp-pin + an edge, the art sits on the PAPER's
+ *                   edge rather than on the text block's. No CSS rule here:
+ *                   the class is a marker both ENGINES implement (see
+ *                   engine/shared/flush.ts), because reaching the paper
+ *                   requires freeing that page's margin — per page — and
+ *                   relocating the furniture that lived in it, neither of
+ *                   which a stylesheet can do. Inert without .gp-pin + an
+ *                   edge word, and inert under plain markdown-it.
  *   .gp-bleed     — forces its own page (break-before) and spans it
  *                   edge-to-edge horizontally. This does NOT cancel the
  *                   top/bottom margins, extend past the trim into printer
@@ -122,4 +130,4 @@
  * carrying gp-left could start shifting; that is standards-tracking per
  * CLAUDE.md ("Chrome wins once it ships"), not a bug in the author's book.
  */
-export declare const GUTTERPRESS_CSS = "\n/* gp-* author image/block vocabulary. One vocabulary, gp-* only \u2014 the\n   pre-vocabulary utility names (.center/.float-left/.float-right/\n   .full-width/.full-bleed) were REMOVED when gp-* shipped; books rename\n   the classes in their markdown (see the migration note). Source ORDER is\n   the contract \u2014 see the doctrine comment above. */\n\n/* flow positions */\n.gp-left {\n  float: left;\n  margin: 0 var(--gp-gap, 1em) var(--gp-gap, 1em) 0;\n  max-width: 50%;\n}\n.gp-right {\n  float: right;\n  margin: 0 0 var(--gp-gap, 1em) var(--gp-gap, 1em);\n  max-width: 50%;\n}\n.gp-center {\n  display: block;\n  float: none;\n  margin-left: auto;\n  margin-right: auto;\n  max-width: 100%;\n}\n.gp-full {\n  display: block;\n  float: none;\n  width: 100%;\n  max-width: 100%;\n}\n@page gp-full-bleed { margin-left: 0; margin-right: 0; }\n.gp-bleed {\n  display: block;\n  float: none;\n  break-before: page;\n  page: gp-full-bleed;\n  max-width: none;\n  width: 100%;\n  margin-left: 0;\n  margin-right: 0;\n}\n\n/* sizes \u2014 AFTER the flow positions so max-width:100% lifts the floats' 50%\n   cap at equal specificity */\n.gp-small { width: 25%; max-width: 100%; }\n.gp-medium { width: 50%; max-width: 100%; }\n.gp-large { width: 75%; max-width: 100%; }\n\n/* float clearance presets \u2014 consumed by var(--gp-gap) in the float rules\n   above and by .gp-shape's shape-margin below; --gp-gap itself is\n   author-settable CSS */\n.gp-tight { --gp-gap: 0.5em; }\n.gp-loose { --gp-gap: 2em; }\n\n/* column runs \u2014 plain CSS Multi-column, exposed as author vocabulary so\n   \"put this in two columns\" does not require borrowing a styled container\n   from the book's own component layer. That borrowing is what this exists\n   to prevent: a book whose theme paints .section chrome by default gives\n   every author who opens a section just to start a column run a panel they\n   did not ask for, and the book then needs a reset rule to take it back.\n   With a neutral primitive the author opts into columns and nothing else.\n\n   Permanent vocabulary, not a shim: Chromium implements multicol natively\n   and these rules are the standard properties verbatim, so there is no\n   spec gap here to remove later. Deliberately minimal \u2014 column-fill is\n   NOT set, because the correct value depends on whether the run fragments\n   across pages (auto packs each page's columns; the CSS initial balance is\n   right for a run that fits on one page) and only the author knows which.\n   --gp-column-gap is author-settable. */\n.gp-columns-2 { columns: 2; column-gap: var(--gp-column-gap, 1.5em); }\n.gp-columns-3 { columns: 3; column-gap: var(--gp-column-gap, 1.5em); }\n\n/* shape wrap \u2014 text follows the image's alpha silhouette instead of its\n   rectangular box. shape-outside only applies to floats, so this is inert\n   without .gp-left/.gp-right (and under .gp-pin, which un-floats). The\n   shape URL cannot be written in CSS (url() contexts can't read attr()),\n   so the image renderer rule (images.ts) mirrors the src into an inline\n   --gp-shape:url(...) custom property whenever it sees this class --\n   authors only ever type the class. threshold 0.2 ignores near-transparent\n   anti-aliasing halos; shape-margin shares the float-gap vocabulary. */\nimg.gp-shape {\n  shape-outside: var(--gp-shape);\n  shape-image-threshold: 0.2;\n  shape-margin: var(--gp-gap, 1em);\n}\n\n/* pin \u2014 within the nearest positioned ancestor (.page/.spread, rule above).\n   inset:0 and the explicit centers are load-bearing; see doctrine comment. */\n.gp-pin {\n  position: absolute;\n  inset: 0;\n  align-self: center;\n  justify-self: center;\n  margin: 0;\n  max-width: 100%;\n}\n\n/* pin edge modifiers \u2014 AFTER .gp-pin to beat its center defaults;\n   justify-self is inert on in-flow floats, so gp-left/gp-right safely do\n   double duty as flow float + pin edge */\n.gp-top { align-self: start; }\n.gp-bottom { align-self: end; }\n.gp-left { justify-self: start; }\n.gp-right { justify-self: end; }\n\n/* wrapper-margin neutralization (same pattern and rationale as the\n   .gp-bleed paragraph-margin note in the doctrine comment; for pin, the\n   emptied paragraph would otherwise leave a phantom margin gap in flow) */\n:where(p:has(> img.gp-bleed:only-child)) { margin: 0; }\n:where(p:has(> img.gp-pin:only-child)) { margin: 0; }\n\n/* depth \u2014 a named ladder for z-index, so books stop hand-tuning bare\n   integers. A real book measured 21 z-index declarations using only four\n   distinct values (-1, 0, 1, 2), each written literally at its use site.\n   The custom properties are the author-settable surface (a book needing a\n   deeper stack raises them once); the classes are the shorthand.\n\n   NOT named \"layer\": CSS Paged Media 3 \u00A73.1 already defines \"page layers\"\n   (page background, canvas, borders, contents, margin boxes) and those are\n   parts of the PAGE BOX, not a z-ladder for content. Reusing the word for a\n   different concept would collide with the spec vocabulary this project\n   tracks. The pin EDGE modifiers already own .gp-top/.gp-bottom, so the\n   ladder avoids those words too.\n\n   .gp-behind is the one that earns its place: it puts a pinned image UNDER\n   the page's text, which is otherwise impossible to express without a bare\n   negative z-index. \"Above\" needs no class \u2014 an out-of-flow pin already\n   paints above in-flow content.\n\n   Two things silently defeat .gp-behind, neither visible at the use site:\n     - a stacking context on the .page/.spread ancestor (z-index, isolation,\n       opacity, filter, transform on it traps the negative layer inside).\n       Core keeps .page/.spread at 'position: relative; z-index: auto'\n       precisely so they are not stacking contexts.\n     - a clipping ancestor (overflow other than visible), the same mechanism\n       that clips a .gp-bleed plate back to the wrapper's width.\n   The build-time engine.layer.trapped audit reports both against the live\n   ancestor chain. printsafe/page-containment is only an early source hint for\n   declarations written directly on .page/.spread. */\n:root {\n  --gp-z-behind: -1;\n  --gp-z-base: 0;\n  --gp-z-raised: 1;\n  --gp-z-front: 2;\n}\n.gp-behind { z-index: var(--gp-z-behind); }\n.gp-base   { z-index: var(--gp-z-base); }\n.gp-raised { z-index: var(--gp-z-raised); }\n.gp-front  { z-index: var(--gp-z-front); }\n";
+export declare const GUTTERPRESS_CSS = "\n/* gp-* author image/block vocabulary. One vocabulary, gp-* only \u2014 the\n   pre-vocabulary utility names (.center/.float-left/.float-right/\n   .full-width/.full-bleed) were REMOVED when gp-* shipped; books rename\n   the classes in their markdown (see the migration note). Source ORDER is\n   the contract \u2014 see the doctrine comment above. */\n\n/* flow positions */\n.gp-left {\n  float: left;\n  margin: 0 var(--gp-gap, 1em) var(--gp-gap, 1em) 0;\n  max-width: 50%;\n}\n.gp-right {\n  float: right;\n  margin: 0 0 var(--gp-gap, 1em) var(--gp-gap, 1em);\n  max-width: 50%;\n}\n.gp-center {\n  display: block;\n  float: none;\n  margin-left: auto;\n  margin-right: auto;\n  max-width: 100%;\n}\n.gp-full {\n  display: block;\n  float: none;\n  width: 100%;\n  max-width: 100%;\n}\n@page gp-full-bleed { margin-left: 0; margin-right: 0; }\n.gp-bleed {\n  display: block;\n  float: none;\n  break-before: page;\n  page: gp-full-bleed;\n  max-width: none;\n  width: 100%;\n  margin-left: 0;\n  margin-right: 0;\n}\n\n/* sizes \u2014 AFTER the flow positions so max-width:100% lifts the floats' 50%\n   cap at equal specificity */\n.gp-small { width: 25%; max-width: 100%; }\n.gp-medium { width: 50%; max-width: 100%; }\n.gp-large { width: 75%; max-width: 100%; }\n\n/* float clearance presets \u2014 consumed by var(--gp-gap) in the float rules\n   above and by .gp-shape's shape-margin below; --gp-gap itself is\n   author-settable CSS */\n.gp-tight { --gp-gap: 0.5em; }\n.gp-loose { --gp-gap: 2em; }\n\n/* column runs \u2014 plain CSS Multi-column, exposed as author vocabulary so\n   \"put this in two columns\" does not require borrowing a styled container\n   from the book's own component layer. That borrowing is what this exists\n   to prevent: a book whose theme paints .section chrome by default gives\n   every author who opens a section just to start a column run a panel they\n   did not ask for, and the book then needs a reset rule to take it back.\n   With a neutral primitive the author opts into columns and nothing else.\n\n   Permanent vocabulary, not a shim: Chromium implements multicol natively\n   and these rules are the standard properties verbatim, so there is no\n   spec gap here to remove later. Deliberately minimal \u2014 column-fill is\n   NOT set, because the correct value depends on whether the run fragments\n   across pages (auto packs each page's columns; the CSS initial balance is\n   right for a run that fits on one page) and only the author knows which.\n   --gp-column-gap is author-settable. */\n.gp-columns-2 { columns: 2; column-gap: var(--gp-column-gap, 1.5em); }\n.gp-columns-3 { columns: 3; column-gap: var(--gp-column-gap, 1.5em); }\n\n/* grid runs \u2014 the SLOTTED counterpart to the column runs above. Grid places\n   each child into the next cell, across then down (deterministic slots: card\n   layouts, stat blocks, image-plus-caption pairs); columns FLOW one text run\n   down then across. Same neutral-primitive rationale as .gp-columns-*, and\n   permanent vocabulary for the same reason: standard CSS Grid verbatim, no\n   spec gap to remove later. MEASURED (Chromium 151, gp-grid evidence pack):\n   grid rows fragment across sheets with EXACT print/viewer parity \u2014 2- and\n   3-col, unequal item heights, mid-row cuts, multi-sheet overflow,\n   break-inside:avoid, gap geometry \u2014 so a grid taller than the page is safe,\n   no fit-one-page constraint. Two things to know, not fix:\n     - on a min-height page root (MARKER_CSS), default align-content\n       stretches rows apart to fill the page \u2014 identically in both engines.\n       Authors wanting packed rows set align-content: start.\n     - a @page-break / @column-break marker DIRECTLY inside a grid container\n       becomes a grid item and corrupts placement (the one measured parity\n       break); markers.js diagnoses it (break_inside_grid).\n   --gp-grid-gap is author-settable. */\n.gp-grid-2 { display: grid; grid-template-columns: repeat(2, 1fr); gap: var(--gp-grid-gap, 1.5em); }\n.gp-grid-3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--gp-grid-gap, 1.5em); }\n\n/* shape wrap \u2014 text follows the image's alpha silhouette instead of its\n   rectangular box. shape-outside only applies to floats, so this is inert\n   without .gp-left/.gp-right (and under .gp-pin, which un-floats). The\n   shape URL cannot be written in CSS (url() contexts can't read attr()),\n   so the image renderer rule (images.ts) mirrors the src into an inline\n   --gp-shape:url(...) custom property whenever it sees this class --\n   authors only ever type the class. threshold 0.2 ignores near-transparent\n   anti-aliasing halos; shape-margin shares the float-gap vocabulary. */\nimg.gp-shape {\n  shape-outside: var(--gp-shape);\n  shape-image-threshold: 0.2;\n  shape-margin: var(--gp-gap, 1em);\n}\n\n/* pin \u2014 within the nearest positioned ancestor (.page/.spread, rule above).\n   inset:0 and the explicit centers are load-bearing; see doctrine comment. */\n.gp-pin {\n  position: absolute;\n  inset: 0;\n  align-self: center;\n  justify-self: center;\n  margin: 0;\n  max-width: 100%;\n}\n\n/* pin edge modifiers \u2014 AFTER .gp-pin to beat its center defaults;\n   justify-self is inert on in-flow floats, so gp-left/gp-right safely do\n   double duty as flow float + pin edge */\n.gp-top { align-self: start; }\n.gp-bottom { align-self: end; }\n.gp-left { justify-self: start; }\n.gp-right { justify-self: end; }\n\n/* wrapper-margin neutralization (same pattern and rationale as the\n   .gp-bleed paragraph-margin note in the doctrine comment; for pin, the\n   emptied paragraph would otherwise leave a phantom margin gap in flow) */\n:where(p:has(> img.gp-bleed:only-child)) { margin: 0; }\n:where(p:has(> img.gp-pin:only-child)) { margin: 0; }\n\n/* depth \u2014 a named ladder for z-index, so books stop hand-tuning bare\n   integers. A real book measured 21 z-index declarations using only four\n   distinct values (-1, 0, 1, 2), each written literally at its use site.\n   The custom properties are the author-settable surface (a book needing a\n   deeper stack raises them once); the classes are the shorthand.\n\n   NOT named \"layer\": CSS Paged Media 3 \u00A73.1 already defines \"page layers\"\n   (page background, canvas, borders, contents, margin boxes) and those are\n   parts of the PAGE BOX, not a z-ladder for content. Reusing the word for a\n   different concept would collide with the spec vocabulary this project\n   tracks. The pin EDGE modifiers already own .gp-top/.gp-bottom, so the\n   ladder avoids those words too.\n\n   .gp-behind is the one that earns its place: it puts a pinned image UNDER\n   the page's text, which is otherwise impossible to express without a bare\n   negative z-index. \"Above\" needs no class \u2014 an out-of-flow pin already\n   paints above in-flow content.\n\n   Two things silently defeat .gp-behind, neither visible at the use site:\n     - a stacking context on the .page/.spread ancestor (z-index, isolation,\n       opacity, filter, transform on it traps the negative layer inside).\n       Core keeps .page/.spread at 'position: relative; z-index: auto'\n       precisely so they are not stacking contexts.\n     - a clipping ancestor (overflow other than visible) \u2014 but only where\n       the art actually overhangs that ancestor's clip box on a clipped\n       axis: the overhang is cut off, the same mechanism that clips a\n       .gp-bleed plate back to the wrapper's width. Clipping never reorders\n       layers \u2014 within-bounds art under a clipping .page prints whole and\n       still behind (measured; see the build audit's comment in\n       engine/compiler/build.ts), and a static wrapper's overflow never\n       binds an abspos .gp-pin at all.\n   The build-time engine.layer.trapped audit reports both against the live\n   ancestor chain. printsafe/page-containment is only an early source hint for\n   declarations written directly on .page/.spread. */\n:root {\n  --gp-z-behind: -1;\n  --gp-z-base: 0;\n  --gp-z-raised: 1;\n  --gp-z-front: 2;\n}\n.gp-behind { z-index: var(--gp-z-behind); }\n.gp-base   { z-index: var(--gp-z-base); }\n.gp-raised { z-index: var(--gp-z-raised); }\n.gp-front  { z-index: var(--gp-z-front); }\n";