gutterpress 0.10.1 → 0.10.2-alpha.1

package/dist/api/index.js

@@ -95,12 +95,12 @@ import {
   syncProject,
   testRemoteAccess,
   validateProjectPlugins
-} from "../index-j6b6cees.js";
+} from "../index-ahzftp35.js";
 import {
   BuildError,
   DEFAULT_PRINT_OPTS,
   readyProbeExpr
-} from "../index-7hrvksrb.js";
+} from "../index-y7jbczsb.js";
 import {
   AUTO_SNAPSHOT_MESSAGE,
   HISTORY_PAGE_LIMIT,

package/dist/{audit-p4e7v2m7.js → audit-e3xvt6vj.js}

@@ -1,15 +1,15 @@
 import {
   executeAndReport
-} from "./cli-bq7vkea9.js";
+} from "./cli-wrt39m23.js";
 import {
   log
-} from "./cli-n79ghfhs.js";
+} from "./cli-mnekrb8s.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-4n1p25df.js";
-import"./cli-eewynen9.js";
+} from "./cli-nrv3gzz9.js";
+import"./cli-6qhw9v08.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/{build-h0x2w036.js → build-epz7zqcc.js}

@@ -1,10 +1,10 @@
 import {
   runBuild,
   splitOutPath
-} from "./cli-bq7vkea9.js";
+} from "./cli-wrt39m23.js";
 import {
   log
-} from "./cli-n79ghfhs.js";
+} from "./cli-mnekrb8s.js";
 import {
   UsageError,
   parseEngine,
@@ -12,8 +12,8 @@ import {
   parsePdfxFlavor,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-4n1p25df.js";
-import"./cli-eewynen9.js";
+} from "./cli-nrv3gzz9.js";
+import"./cli-6qhw9v08.js";
 import"./cli-c41yr7he.js";
 import {
   BuildError

package/dist/{cli-eewynen9.js → cli-6qhw9v08.js}

@@ -936,7 +936,18 @@ var MARGIN_BOX_IGNORED_PROPERTIES = new Set([
   "rotate",
   "translate",
   "scale",
-  "box-shadow"
+  "perspective",
+  "box-shadow",
+  "opacity",
+  "outline",
+  "outline-color",
+  "outline-style",
+  "outline-width",
+  "outline-offset",
+  "filter",
+  "backdrop-filter",
+  "mix-blend-mode",
+  "clip-path"
 ]);
 function isIgnoredMarginBoxProperty(property) {
   return MARGIN_BOX_IGNORED_PROPERTIES.has(property.toLowerCase());
@@ -1434,7 +1445,7 @@ var preview_shell_default = "./preview-shell-kyjq59d9.js";
 var CGATS21_CRPC1_default = "./CGATS21_CRPC1-g0e3k7kr.icc";
 
 // src/assets/engine/gutterpress-viewer.js
-var gutterpress_viewer_default = "./gutterpress-viewer-tma1qwz2.js";
+var gutterpress_viewer_default = "./gutterpress-viewer-mfeccbys.js";
 
 // src/assets/engine/gutterpress-agent.js
 var gutterpress_agent_default = "./gutterpress-agent-cazqstr1.js";
@@ -1885,6 +1896,7 @@ async function build(opts) {
       deviceScaleFactor: 1,
       mobile: false
     };
+    await page.send("Emulation.setScrollbarsHidden", { hidden: true });
     await page.send("Emulation.setDeviceMetricsOverride", sheetViewport);
     await page.send("Emulation.setEmulatedMedia", { media: "print" });
     log(`print media emulated for audits and measurement`);
@@ -2255,13 +2267,77 @@ ${mapCss}`;
         log(`audit: ${audit.length} print-quality warning(s)`);
     }
     {
-      const { leaks, multicol, layerTraps } = JSON.parse(await page.evaluate(`(() => {
+      const { leaks, multicol, layerTraps, pageBackgrounds } = JSON.parse(await page.evaluate(`(() => {
           const desc = ${DESC_JS};
           const leaks = [];
           const multicol = [];
           const layerTraps = [];
           const seenLayerTraps = new Set();
 
+          // Images referenced ONLY from inside an @page rule. Chromium fetches
+          // them and then paints nothing — see the pass comment above.
+          const pageBackgrounds = (() => {
+            const absolute = (u) => {
+              try { return new URL(u, document.baseURI).href } catch { return u }
+            };
+            const urlsIn = (text) => {
+              const out = [];
+              const re = /url\\(\\s*(['"]?)([^'")]*)\\1\\s*\\)/g;
+              let m;
+              while ((m = re.exec(text))) if (m[2]) out.push(m[2]);
+              return out;
+            };
+            const owned = new Map();
+            // Resolved by something OTHER than an @page rule — a CSS rule
+            // outside @page, or an element's inline style. Unconditionally
+            // protective: the image is a StyleImage the load already resolved.
+            const cssReferenced = new Set();
+            // Named by a <link rel="preload">. Protective, unless an element
+            // src names the same URL (see srcNamed).
+            const preloaded = new Set();
+            // Named by an element's src. NEVER protective — measured, this is
+            // the one reference type that BREAKS the page box, and it breaks
+            // it whether or not a preload is present (12/12, either document
+            // order). An element reference is evidence of the failure, not of
+            // safety.
+            const srcNamed = new Set();
+            for (const el of document.querySelectorAll("[src]"))
+              srcNamed.add(absolute(el.getAttribute("src")));
+            for (const el of document.querySelectorAll("link[rel~=preload][href]"))
+              preloaded.add(absolute(el.getAttribute("href")));
+            for (const el of document.querySelectorAll("[style]"))
+              for (const u of urlsIn(el.getAttribute("style"))) cssReferenced.add(absolute(u));
+            const walk = (rules, owner) => {
+              for (const rule of rules) {
+                let own = owner;
+                if (rule.constructor.name === "CSSPageRule")
+                  own = "@page" + (rule.selectorText ? " " + rule.selectorText : "");
+                else if (owner && rule.name) own = owner + " { @" + rule.name + " }";
+                for (const u of urlsIn(rule.style ? rule.style.cssText : "")) {
+                  if (!own) cssReferenced.add(absolute(u));
+                  else if (!owned.has(absolute(u))) owned.set(absolute(u), { url: u, where: own });
+                }
+                if (rule.cssRules) walk(rule.cssRules, own);
+              }
+            };
+            for (const sheet of document.styleSheets) {
+              let rules;
+              try { rules = sheet.cssRules } catch { continue }
+              walk(rules, null);
+            }
+            // PROTECTED iff another CSS rule resolves it, OR a preload names
+            // it and no element src names it too. "Something else mentions
+            // this URL" is NOT the test — that inference is inverted for
+            // [src], the very reference type that breaks the page box.
+            return [...owned]
+              .filter(([abs, hit]) =>
+                !/^data:/i.test(hit.url) &&
+                !cssReferenced.has(abs) &&
+                !(preloaded.has(abs) && !srcNamed.has(abs)))
+              .map(([, hit]) => hit)
+              .slice(0, 20);
+          })();
+
           const stackingReasons = (el, cs) => {
             const reasons = [];
             const positioned = cs.position !== "static";
@@ -2382,7 +2458,7 @@ ${mapCss}`;
               }
             }
           }
-          return JSON.stringify({ leaks, multicol, layerTraps });
+          return JSON.stringify({ leaks, multicol, layerTraps, pageBackgrounds });
         })()`));
       for (const d of leaks)
         diagnose("engine.abspos.leak", `${d} uses position: absolute with nothing positioned around it, so it is placed against the whole document rather than the page it sits on in your markdown — it can print on a completely different page.`);
@@ -2392,6 +2468,10 @@ ${mapCss}`;
         diagnose("engine.layer.trapped", `${trap.behind} cannot paint behind the page as intended because ancestor ${trap.ancestor} ${trap.detail}. Remove or narrowly scope that containment style around the .gp-behind element.`);
       if (layerTraps.length)
         log(`audit: ${layerTraps.length} trapped layer warning(s)`);
+      for (const hit of pageBackgrounds)
+        diagnose("engine.page-background.unreferenced", `"${hit.url}" is only referenced from "${hit.where}", and Chromium will not print an image referenced nowhere else — the page prints with its background colour alone, with no error. Gutterpress stages and preloads every image your project stylesheets reference, so this one is outside that: it is remote (a url(https://...), which is never staged), or it comes from CSS that does not pass through your stylesheets, or an element in the document uses the same URL as its src, which drops it on its own. Use a local image, referenced from one of your project stylesheets, and not also used as an <img>.`);
+      if (pageBackgrounds.length)
+        log(`audit: ${pageBackgrounds.length} unreferenced @page background image(s)`);
       for (const d of multicol)
         diagnose("engine.multicol.dead-column", `${d} runs over more than one page in columns, and only the last page's columns get balanced — earlier pages are left with an empty column. Add column-fill: auto to ${d}.`);
       if (multicol.length)
@@ -2544,6 +2624,7 @@ async function predictPageMap(browser, url, agentScript, viewerScript, args, she
   let page;
   try {
     page = await browser.newPage();
+    await page.send("Emulation.setScrollbarsHidden", { hidden: true });
     await page.send("Emulation.setDeviceMetricsOverride", sheetViewport);
     await page.navigate(url);
     await page.evaluate(agentScript);

package/dist/{cli-n79ghfhs.js → cli-mnekrb8s.js}

@@ -1,6 +1,6 @@
 import {
   package_default
-} from "./cli-4n1p25df.js";
+} from "./cli-nrv3gzz9.js";
 import {
   execCapture,
   findTool,

package/dist/{cli-4n1p25df.js → cli-nrv3gzz9.js}

@@ -4,7 +4,7 @@ import {
 // package.json
 var package_default = {
   name: "gutterpress",
-  version: "0.10.1",
+  version: "0.10.2-alpha.1",
   description: "Markdown-to-PDF converter for professional print layout using a native Chromium print engine and Ghostscript.",
   author: "itlackey",
   license: "MPL-2.0",

package/dist/{cli-bq7vkea9.js → cli-wrt39m23.js}

@@ -13,12 +13,12 @@ import {
   stampCreator,
   stripAnnotations,
   warn
-} from "./cli-n79ghfhs.js";
+} from "./cli-mnekrb8s.js";
 import {
   DEBOUNCE,
   UsageError,
   resolvePort
-} from "./cli-4n1p25df.js";
+} from "./cli-nrv3gzz9.js";
 import {
   MARGIN_BOX_IGNORED_PROPERTIES,
   RENDER_TIMEOUT_MS,
@@ -27,7 +27,7 @@ import {
   getAssetPath,
   getBrowser,
   prewarmBrowser
-} from "./cli-eewynen9.js";
+} from "./cli-6qhw9v08.js";
 import {
   INSTALL_HINTS,
   execCapture,
@@ -1126,6 +1126,18 @@ var marginBoxAtRuleNames = new Set([
   "right-bottom"
 ]);
 var marginBoxIgnoredProperties = MARGIN_BOX_IGNORED_PROPERTIES;
+function isInPageBox(decl) {
+  const page = decl.parent;
+  return !!page && page.type === "atrule" && page.name.toLowerCase() === "page";
+}
+function isDroppedPageGradient(decl) {
+  const prop = decl.prop.toLowerCase();
+  if (prop !== "background" && prop !== "background-image")
+    return false;
+  if (!/(^|[\s,(])[\w-]*gradient\(/i.test(decl.value))
+    return false;
+  return isInPageBox(decl);
+}
 function isInPageMarginBox(decl) {
   const box = decl.parent;
   if (!box || box.type !== "atrule")
@@ -1226,7 +1238,14 @@ function checkCss(css, from) {
   root.walkAtRules((at) => reportRemoteUrls(at.params || "", at));
   root.walkDecls((decl) => {
     const prop = decl.prop.toLowerCase();
-    if (prop === "filter") {
+    if (marginBoxIgnoredProperties.has(prop) && isInPageMarginBox(decl)) {
+      warnings.push({
+        rule: ruleRiskyProps,
+        severity: "warning",
+        message: `Property "${decl.prop}" is not supported in Chromium @page margin boxes and is silently ignored — the chrome renders square/unshadowed. Anything that would paint outside the box (box-shadow, outline, filter) or make it a stacking context (transform, opacity, mix-blend-mode) is dropped; text-shadow, border, border-radius, padding and background gradients all work inside the box.`,
+        ...nodeLoc(decl)
+      });
+    } else if (prop === "filter") {
       warnings.push({
         rule: ruleRiskyProps,
         severity: "warning",
@@ -1240,11 +1259,11 @@ function checkCss(css, from) {
         message: `Property is high-risk for print/PDF (can force rasterization): ${decl.prop}`,
         ...nodeLoc(decl)
       });
-    } else if (marginBoxIgnoredProperties.has(prop) && isInPageMarginBox(decl)) {
+    } else if (isDroppedPageGradient(decl)) {
       warnings.push({
         rule: ruleRiskyProps,
         severity: "warning",
-        message: `Property "${decl.prop}" is not supported in Chromium @page margin boxes and is silently ignored — the chrome renders square/unshadowed.`,
+        message: `"${decl.prop}: ${decl.value}" on @page paints nothing in print — Chromium drops a gradient in the @page box's own background, with no error and a valid-looking PDF. A solid colour there paints the whole sheet; the same gradient also works on "html" (it covers the content area, not the sheet) or in a margin box.`,
         ...nodeLoc(decl)
       });
     } else if (isUnpairedFitContentWidth(decl)) {
@@ -2776,7 +2795,6 @@ import { readFile as readFile9 } from "node:fs/promises";
 import path3 from "node:path";
 import postcss2 from "postcss";
 var FONT_EXTS = new Set([".woff2", ".woff", ".ttf", ".otf"]);
-var IMAGE_INLINE_MAX_BYTES = 512 * 1024;
 var HASHED_ASSET_DIR = "assets";
 var MIME_BY_EXT = {
   ".woff2": "font/woff2",
@@ -2896,7 +2914,7 @@ function importTarget(atRule) {
     return null;
   return target;
 }
-async function inlineOne(cssPath, projectDir, copies, warnings, seen) {
+async function inlineOne(cssPath, copies, warnings, seen) {
   const abs = path3.resolve(cssPath);
   if (seen.has(abs))
     return "";
@@ -2931,11 +2949,7 @@ async function inlineOne(cssPath, projectDir, copies, warnings, seen) {
         return dataUri(bytes2, ext);
       }
       const bytes = await readOrThrow(absAsset, "asset", abs);
-      if (bytes.byteLength <= IMAGE_INLINE_MAX_BYTES) {
-        return dataUri(bytes, ext);
-      }
-      const projectRel = path3.relative(projectDir, absAsset);
-      const dest = projectRel && !escapesProjectRoot(projectDir, absAsset) ? toPosix(projectRel) : `${HASHED_ASSET_DIR}/${contentHash(bytes)}${ext}`;
+      const dest = `${HASHED_ASSET_DIR}/${contentHash(bytes)}${ext}`;
       copies.set(dest, { from: absAsset, to: dest });
       return dest;
     });
@@ -2948,7 +2962,7 @@ async function inlineOne(cssPath, projectDir, copies, warnings, seen) {
   });
   for (const { node, target } of imports) {
     const importedAbs = path3.resolve(cssDir, stripUrlSuffix(decodeRef(target)));
-    const inlined = await inlineOne(importedAbs, projectDir, copies, warnings, seen);
+    const inlined = await inlineOne(importedAbs, copies, warnings, seen);
     node.replaceWith(wrapImportConditions(node, postcss2.parse(inlined, { from: importedAbs })));
   }
   return root.toString();
@@ -2960,7 +2974,7 @@ async function inlineStyles(projectDir, stylePaths) {
   const parts = [];
   for (const rel of stylePaths) {
     const abs = path3.resolve(projectDir, rel);
-    const css = await inlineOne(abs, projectDir, copies, warnings, seen);
+    const css = await inlineOne(abs, copies, warnings, seen);
     if (css.trim().length > 0) {
       parts.push(`/* ${toPosix(path3.relative(projectDir, abs))} */
 ${css.trim()}`);
@@ -6287,12 +6301,14 @@ ${projectCss.trim()}` : null
   ].filter(Boolean).join(`
 
 `);
+  const preloadTags = (opts.preloadImages ?? []).map((href) => `
+  <link rel="preload" as="image" href="${href}">`).join("");
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${title}</title>
+  <title>${title}</title>${preloadTags}
   <style data-project-css>
 ${inlineCss}
 </style>
@@ -6324,6 +6340,7 @@ async function renderChapters(inputDir, opts = {}) {
     files,
     readText: (relPath) => readFile18(join2(inputDir, canonicalChapterId(relPath)), "utf-8"),
     projectCss: inlined.css,
+    preloadImages: inlined.copies.map((c) => c.to),
     title: opts.title,
     plugins: opts.plugins,
     pluginCss: opts.pluginCss,
@@ -7521,7 +7538,7 @@ class PdfOutput {
       const rawPdf = pdfxMode ? path8.join(stage, "raw.pdf") : path8.resolve(pdfFile);
       await fsp2.mkdir(path8.dirname(path8.resolve(pdfFile)), { recursive: true });
       log.info("Rendering HTML to PDF via the Gutterpress engine (native Chromium pagination)");
-      const { buildNativePdf } = await import("./engine-57vw8zpd.js");
+      const { buildNativePdf } = await import("./engine-9m8k1mfz.js");
       const engineDiagnostics = await buildNativePdf(htmlFile, rawPdf, {
         title: config.title,
         author: config.authors.length > 0 ? config.authors.join(", ") : undefined,

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   UsageError,
   package_default,
   rejectUnknownFlags
-} from "./cli-4n1p25df.js";
+} from "./cli-nrv3gzz9.js";
 import {
   EXIT_CODES
 } from "./cli-46ycxe6r.js";
@@ -18,16 +18,16 @@ import {
 import { defineCommand, parseArgs, runMain } from "citty";
 import { statSync } from "node:fs";
 var SUBCOMMANDS = {
-  new: () => import("./new-6gz60bbx.js").then((m) => m.default),
-  preview: () => import("./preview-7a35z1v1.js").then((m) => m.default),
-  build: () => import("./build-h0x2w036.js").then((m) => m.default),
-  publish: () => import("./publish-dpx2cebg.js").then((m) => m.default),
-  lint: () => import("./lint-7wss5p35.js").then((m) => m.default),
-  validate: () => import("./validate-hbe05b26.js").then((m) => m.default),
-  audit: () => import("./audit-p4e7v2m7.js").then((m) => m.default),
-  preflight: () => import("./preflight-3tb7stqb.js").then((m) => m.default),
-  doctor: () => import("./doctor-y2w1kcqf.js").then((m) => m.default),
-  plugin: () => import("./plugin-7awkmgq0.js").then((m) => m.default)
+  new: () => import("./new-8jhvnqzp.js").then((m) => m.default),
+  preview: () => import("./preview-37g504pr.js").then((m) => m.default),
+  build: () => import("./build-epz7zqcc.js").then((m) => m.default),
+  publish: () => import("./publish-v1gc8zm4.js").then((m) => m.default),
+  lint: () => import("./lint-e36t5jz3.js").then((m) => m.default),
+  validate: () => import("./validate-5yzb2qzq.js").then((m) => m.default),
+  audit: () => import("./audit-e3xvt6vj.js").then((m) => m.default),
+  preflight: () => import("./preflight-bvtf28e4.js").then((m) => m.default),
+  doctor: () => import("./doctor-236cwssq.js").then((m) => m.default),
+  plugin: () => import("./plugin-2390rtn1.js").then((m) => m.default)
 };
 var VERSION = package_default.version;
 var main = defineCommand({
@@ -52,7 +52,7 @@ async function preflightRequiredInvocations(rawArgs) {
   const [command, ...commandArgs] = rawArgs;
   try {
     if (command === "new") {
-      const { newArgs } = await import("./new-6gz60bbx.js");
+      const { newArgs } = await import("./new-8jhvnqzp.js");
       rejectUnknownFlags(commandArgs, newArgs, "new");
       const parsed2 = parseArgs(commandArgs, {
         ...newArgs,
@@ -64,7 +64,7 @@ async function preflightRequiredInvocations(rawArgs) {
       return;
     }
     if (command === "preflight") {
-      const { preflightArgs } = await import("./preflight-3tb7stqb.js");
+      const { preflightArgs } = await import("./preflight-bvtf28e4.js");
       rejectUnknownFlags(commandArgs, preflightArgs, "preflight");
       const parsed2 = parseArgs(commandArgs, {
         ...preflightArgs,
@@ -88,7 +88,7 @@ async function preflightRequiredInvocations(rawArgs) {
     if (subcommand !== "add") {
       throw new UsageError(`gutterpress plugin: unknown command "${subcommand}"`);
     }
-    const { pluginAddArgs } = await import("./plugin-7awkmgq0.js");
+    const { pluginAddArgs } = await import("./plugin-2390rtn1.js");
     rejectUnknownFlags(subcommandArgs, pluginAddArgs, "plugin add");
     const parsed = parseArgs(subcommandArgs, {
       ...pluginAddArgs,

package/dist/{doctor-y2w1kcqf.js → doctor-236cwssq.js}

@@ -1,12 +1,12 @@
 import {
   getSystemDiagnostics,
   log
-} from "./cli-n79ghfhs.js";
+} from "./cli-mnekrb8s.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-4n1p25df.js";
+} from "./cli-nrv3gzz9.js";
 import"./cli-c41yr7he.js";
 import"./cli-46ycxe6r.js";
 import"./cli-37x76zdn.js";

package/dist/engine/compiler/build.d.ts

@@ -7,7 +7,7 @@ import { type PostprocessResult } from "./postprocess.ts";
  * set is closed here so a surface's label table can be asserted complete
  * against it rather than drifting silently as checks are added.
  */
-export type BuildDiagnosticCode = "engine.width.overflow" | "engine.width.intrinsic" | "engine.xref.broken" | "engine.abspos.leak" | "engine.layer.trapped" | "engine.multicol.dead-column" | "engine.content.overheight" | "engine.image.low-dpi" | "engine.flush.margin-box";
+export type BuildDiagnosticCode = "engine.width.overflow" | "engine.width.intrinsic" | "engine.xref.broken" | "engine.abspos.leak" | "engine.layer.trapped" | "engine.multicol.dead-column" | "engine.content.overheight" | "engine.image.low-dpi" | "engine.flush.margin-box" | "engine.page-background.unreferenced";
 export declare const BUILD_DIAGNOSTIC_CODES: readonly BuildDiagnosticCode[];
 export interface BuildDiagnostic {
     code: BuildDiagnosticCode;

package/dist/engine/shared/margin-box-support.d.ts

@@ -2,7 +2,24 @@
  * Declarations Chromium accepts syntactically in `@page` margin boxes but
  * silently drops in native print. These were measured with deliberately
  * visible values (`rotate(-12deg)`, `6px 6px 0 #c00`) and are documented in
- * docs/engine-history/ENGINE.md §8.
+ * docs/engine-history/ENGINE.md §8 and docs/known-limitations.md §2.
+ *
+ * The line is what the property PAINTS, not the property family: everything
+ * that establishes a stacking context or paints outside the border box is
+ * dropped, everything that paints inside it is honoured. `text-shadow` beside
+ * `box-shadow` is the clearest pair. Re-measured on Chrome 151.0.7922.75,
+ * 96dpi raster, mean absolute pixel difference against the same box without
+ * the declaration (control: removing the box entirely, 2.6485):
+ *
+ *   dropped, all 0.0000   box-shadow · transform (rotate/scale/translate) ·
+ *                         rotate/scale/translate · opacity · outline (and its
+ *                         longhands) · filter · mix-blend-mode ·
+ *                         backdrop-filter · clip-path · perspective
+ *   honoured              text-shadow 0.1375 · border-radius 0.3397 ·
+ *                         background gradient 11.2260 · writing-mode 0.3200 ·
+ *                         padding-left 0.2927 · font-size 0.7864 ·
+ *                         color 0.1063 · letter-spacing 0.2781 ·
+ *                         text-transform 0.1804 · visibility 2.6485
  *
  * Keep the viewer and print-safety linter on this one contract: preview must
  * omit the same effects native PDF omits, while every other declaration is

package/dist/{engine-57vw8zpd.js → engine-9m8k1mfz.js}

@@ -4,7 +4,7 @@ import {
   build,
   connectChromium,
   getBrowser
-} from "./cli-eewynen9.js";
+} from "./cli-6qhw9v08.js";
 import"./cli-c41yr7he.js";
 import {
   BuildError

package/dist/{engine-8kdwy0jz.js → engine-e1ycm5p9.js}

@@ -1,13 +1,13 @@
 import {
   build
-} from "./index-p0ebr7dh.js";
+} from "./index-n252zv7d.js";
 import {
   BuildError,
   RENDER_TIMEOUT_MS,
   assertMilestone,
   connectChromium,
   getBrowser
-} from "./index-7hrvksrb.js";
+} from "./index-y7jbczsb.js";
 import"./index-37x76zdn.js";
 
 // src/lib/engine.ts

package/dist/{gutterpress-viewer-tma1qwz2.js → gutterpress-viewer-mfeccbys.js}

@@ -2012,7 +2012,18 @@
     "rotate",
     "translate",
     "scale",
-    "box-shadow"
+    "perspective",
+    "box-shadow",
+    "opacity",
+    "outline",
+    "outline-color",
+    "outline-style",
+    "outline-width",
+    "outline-offset",
+    "filter",
+    "backdrop-filter",
+    "mix-blend-mode",
+    "clip-path"
   ]);
   function isIgnoredMarginBoxProperty(property) {
     return MARGIN_BOX_IGNORED_PROPERTIES.has(property.toLowerCase());

package/dist/{index-j6b6cees.js → index-ahzftp35.js}

@@ -17,7 +17,7 @@ import {
   resolveChromiumExecutable,
   run,
   spawnCapture
-} from "./index-7hrvksrb.js";
+} from "./index-y7jbczsb.js";
 import {
   gitFs,
   gitScopeFor,
@@ -2002,12 +2002,14 @@ ${projectCss.trim()}` : null
   ].filter(Boolean).join(`
 
 `);
+  const preloadTags = (opts.preloadImages ?? []).map((href) => `
+  <link rel="preload" as="image" href="${href}">`).join("");
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${title}</title>
+  <title>${title}</title>${preloadTags}
   <style data-project-css>
 ${inlineCss}
 </style>
@@ -2127,7 +2129,6 @@ import { readFile as readFile2 } from "node:fs/promises";
 import path2 from "node:path";
 import postcss from "postcss";
 var FONT_EXTS = new Set([".woff2", ".woff", ".ttf", ".otf"]);
-var IMAGE_INLINE_MAX_BYTES = 512 * 1024;
 var HASHED_ASSET_DIR = "assets";
 var MIME_BY_EXT = {
   ".woff2": "font/woff2",
@@ -2247,7 +2248,7 @@ function importTarget(atRule) {
     return null;
   return target;
 }
-async function inlineOne(cssPath, projectDir, copies, warnings, seen) {
+async function inlineOne(cssPath, copies, warnings, seen) {
   const abs = path2.resolve(cssPath);
   if (seen.has(abs))
     return "";
@@ -2282,11 +2283,7 @@ async function inlineOne(cssPath, projectDir, copies, warnings, seen) {
         return dataUri(bytes2, ext);
       }
       const bytes = await readOrThrow(absAsset, "asset", abs);
-      if (bytes.byteLength <= IMAGE_INLINE_MAX_BYTES) {
-        return dataUri(bytes, ext);
-      }
-      const projectRel = path2.relative(projectDir, absAsset);
-      const dest = projectRel && !escapesProjectRoot(projectDir, absAsset) ? toPosix(projectRel) : `${HASHED_ASSET_DIR}/${contentHash(bytes)}${ext}`;
+      const dest = `${HASHED_ASSET_DIR}/${contentHash(bytes)}${ext}`;
       copies.set(dest, { from: absAsset, to: dest });
       return dest;
     });
@@ -2299,7 +2296,7 @@ async function inlineOne(cssPath, projectDir, copies, warnings, seen) {
   });
   for (const { node, target } of imports) {
     const importedAbs = path2.resolve(cssDir, stripUrlSuffix(decodeRef(target)));
-    const inlined = await inlineOne(importedAbs, projectDir, copies, warnings, seen);
+    const inlined = await inlineOne(importedAbs, copies, warnings, seen);
     node.replaceWith(wrapImportConditions(node, postcss.parse(inlined, { from: importedAbs })));
   }
   return root.toString();
@@ -2311,7 +2308,7 @@ async function inlineStyles(projectDir, stylePaths) {
   const parts = [];
   for (const rel of stylePaths) {
     const abs = path2.resolve(projectDir, rel);
-    const css = await inlineOne(abs, projectDir, copies, warnings, seen);
+    const css = await inlineOne(abs, copies, warnings, seen);
     if (css.trim().length > 0) {
       parts.push(`/* ${toPosix(path2.relative(projectDir, abs))} */
 ${css.trim()}`);
@@ -2451,6 +2448,7 @@ async function renderChapters(inputDir, opts = {}) {
     files,
     readText: (relPath) => readFile3(join(inputDir, canonicalChapterId(relPath)), "utf-8"),
     projectCss: inlined.css,
+    preloadImages: inlined.copies.map((c) => c.to),
     title: opts.title,
     plugins: opts.plugins,
     pluginCss: opts.pluginCss,
@@ -3980,7 +3978,7 @@ import git from "isomorphic-git";
 // package.json
 var package_default = {
   name: "gutterpress",
-  version: "0.10.1",
+  version: "0.10.2-alpha.1",
   description: "Markdown-to-PDF converter for professional print layout using a native Chromium print engine and Ghostscript.",
   author: "itlackey",
   license: "MPL-2.0",
@@ -4302,6 +4300,18 @@ var marginBoxAtRuleNames = new Set([
   "right-bottom"
 ]);
 var marginBoxIgnoredProperties = MARGIN_BOX_IGNORED_PROPERTIES;
+function isInPageBox(decl) {
+  const page = decl.parent;
+  return !!page && page.type === "atrule" && page.name.toLowerCase() === "page";
+}
+function isDroppedPageGradient(decl) {
+  const prop = decl.prop.toLowerCase();
+  if (prop !== "background" && prop !== "background-image")
+    return false;
+  if (!/(^|[\s,(])[\w-]*gradient\(/i.test(decl.value))
+    return false;
+  return isInPageBox(decl);
+}
 function isInPageMarginBox(decl) {
   const box = decl.parent;
   if (!box || box.type !== "atrule")
@@ -4402,7 +4412,14 @@ function checkCss(css, from) {
   root.walkAtRules((at) => reportRemoteUrls(at.params || "", at));
   root.walkDecls((decl) => {
     const prop = decl.prop.toLowerCase();
-    if (prop === "filter") {
+    if (marginBoxIgnoredProperties.has(prop) && isInPageMarginBox(decl)) {
+      warnings.push({
+        rule: ruleRiskyProps,
+        severity: "warning",
+        message: `Property "${decl.prop}" is not supported in Chromium @page margin boxes and is silently ignored — the chrome renders square/unshadowed. Anything that would paint outside the box (box-shadow, outline, filter) or make it a stacking context (transform, opacity, mix-blend-mode) is dropped; text-shadow, border, border-radius, padding and background gradients all work inside the box.`,
+        ...nodeLoc(decl)
+      });
+    } else if (prop === "filter") {
       warnings.push({
         rule: ruleRiskyProps,
         severity: "warning",
@@ -4416,11 +4433,11 @@ function checkCss(css, from) {
         message: `Property is high-risk for print/PDF (can force rasterization): ${decl.prop}`,
         ...nodeLoc(decl)
       });
-    } else if (marginBoxIgnoredProperties.has(prop) && isInPageMarginBox(decl)) {
+    } else if (isDroppedPageGradient(decl)) {
       warnings.push({
         rule: ruleRiskyProps,
         severity: "warning",
-        message: `Property "${decl.prop}" is not supported in Chromium @page margin boxes and is silently ignored — the chrome renders square/unshadowed.`,
+        message: `"${decl.prop}: ${decl.value}" on @page paints nothing in print — Chromium drops a gradient in the @page box's own background, with no error and a valid-looking PDF. A solid colour there paints the whole sheet; the same gradient also works on "html" (it covers the content area, not the sheet) or in a margin box.`,
         ...nodeLoc(decl)
       });
     } else if (isUnpairedFitContentWidth(decl)) {
@@ -8016,7 +8033,7 @@ class PdfOutput {
       const rawPdf = pdfxMode ? path8.join(stage, "raw.pdf") : path8.resolve(pdfFile);
       await fsp2.mkdir(path8.dirname(path8.resolve(pdfFile)), { recursive: true });
       log.info("Rendering HTML to PDF via the Gutterpress engine (native Chromium pagination)");
-      const { buildNativePdf } = await import("./engine-8kdwy0jz.js");
+      const { buildNativePdf } = await import("./engine-e1ycm5p9.js");
       const engineDiagnostics = await buildNativePdf(htmlFile, rawPdf, {
         title: config.title,
         author: config.authors.length > 0 ? config.authors.join(", ") : undefined,

package/dist/{index-p0ebr7dh.js → index-n252zv7d.js}

@@ -4,7 +4,7 @@ import {
   launchChromium,
   marginBoxAlign,
   marginBoxRectPt
-} from "./index-7hrvksrb.js";
+} from "./index-y7jbczsb.js";
 
 // src/engine/compiler/build.ts
 import { readFile } from "node:fs/promises";
@@ -1383,7 +1383,8 @@ var BUILD_DIAGNOSTIC_CODES = [
   "engine.multicol.dead-column",
   "engine.content.overheight",
   "engine.image.low-dpi",
-  "engine.flush.margin-box"
+  "engine.flush.margin-box",
+  "engine.page-background.unreferenced"
 ];
 async function build(opts) {
   const log = opts.onProgress ?? (() => {});
@@ -1410,6 +1411,7 @@ async function build(opts) {
       deviceScaleFactor: 1,
       mobile: false
     };
+    await page.send("Emulation.setScrollbarsHidden", { hidden: true });
     await page.send("Emulation.setDeviceMetricsOverride", sheetViewport);
     await page.send("Emulation.setEmulatedMedia", { media: "print" });
     log(`print media emulated for audits and measurement`);
@@ -1780,13 +1782,77 @@ ${mapCss}`;
         log(`audit: ${audit.length} print-quality warning(s)`);
     }
     {
-      const { leaks, multicol, layerTraps } = JSON.parse(await page.evaluate(`(() => {
+      const { leaks, multicol, layerTraps, pageBackgrounds } = JSON.parse(await page.evaluate(`(() => {
           const desc = ${DESC_JS};
           const leaks = [];
           const multicol = [];
           const layerTraps = [];
           const seenLayerTraps = new Set();
 
+          // Images referenced ONLY from inside an @page rule. Chromium fetches
+          // them and then paints nothing — see the pass comment above.
+          const pageBackgrounds = (() => {
+            const absolute = (u) => {
+              try { return new URL(u, document.baseURI).href } catch { return u }
+            };
+            const urlsIn = (text) => {
+              const out = [];
+              const re = /url\\(\\s*(['"]?)([^'")]*)\\1\\s*\\)/g;
+              let m;
+              while ((m = re.exec(text))) if (m[2]) out.push(m[2]);
+              return out;
+            };
+            const owned = new Map();
+            // Resolved by something OTHER than an @page rule — a CSS rule
+            // outside @page, or an element's inline style. Unconditionally
+            // protective: the image is a StyleImage the load already resolved.
+            const cssReferenced = new Set();
+            // Named by a <link rel="preload">. Protective, unless an element
+            // src names the same URL (see srcNamed).
+            const preloaded = new Set();
+            // Named by an element's src. NEVER protective — measured, this is
+            // the one reference type that BREAKS the page box, and it breaks
+            // it whether or not a preload is present (12/12, either document
+            // order). An element reference is evidence of the failure, not of
+            // safety.
+            const srcNamed = new Set();
+            for (const el of document.querySelectorAll("[src]"))
+              srcNamed.add(absolute(el.getAttribute("src")));
+            for (const el of document.querySelectorAll("link[rel~=preload][href]"))
+              preloaded.add(absolute(el.getAttribute("href")));
+            for (const el of document.querySelectorAll("[style]"))
+              for (const u of urlsIn(el.getAttribute("style"))) cssReferenced.add(absolute(u));
+            const walk = (rules, owner) => {
+              for (const rule of rules) {
+                let own = owner;
+                if (rule.constructor.name === "CSSPageRule")
+                  own = "@page" + (rule.selectorText ? " " + rule.selectorText : "");
+                else if (owner && rule.name) own = owner + " { @" + rule.name + " }";
+                for (const u of urlsIn(rule.style ? rule.style.cssText : "")) {
+                  if (!own) cssReferenced.add(absolute(u));
+                  else if (!owned.has(absolute(u))) owned.set(absolute(u), { url: u, where: own });
+                }
+                if (rule.cssRules) walk(rule.cssRules, own);
+              }
+            };
+            for (const sheet of document.styleSheets) {
+              let rules;
+              try { rules = sheet.cssRules } catch { continue }
+              walk(rules, null);
+            }
+            // PROTECTED iff another CSS rule resolves it, OR a preload names
+            // it and no element src names it too. "Something else mentions
+            // this URL" is NOT the test — that inference is inverted for
+            // [src], the very reference type that breaks the page box.
+            return [...owned]
+              .filter(([abs, hit]) =>
+                !/^data:/i.test(hit.url) &&
+                !cssReferenced.has(abs) &&
+                !(preloaded.has(abs) && !srcNamed.has(abs)))
+              .map(([, hit]) => hit)
+              .slice(0, 20);
+          })();
+
           const stackingReasons = (el, cs) => {
             const reasons = [];
             const positioned = cs.position !== "static";
@@ -1907,7 +1973,7 @@ ${mapCss}`;
               }
             }
           }
-          return JSON.stringify({ leaks, multicol, layerTraps });
+          return JSON.stringify({ leaks, multicol, layerTraps, pageBackgrounds });
         })()`));
       for (const d of leaks)
         diagnose("engine.abspos.leak", `${d} uses position: absolute with nothing positioned around it, so it is placed against the whole document rather than the page it sits on in your markdown — it can print on a completely different page.`);
@@ -1917,6 +1983,10 @@ ${mapCss}`;
         diagnose("engine.layer.trapped", `${trap.behind} cannot paint behind the page as intended because ancestor ${trap.ancestor} ${trap.detail}. Remove or narrowly scope that containment style around the .gp-behind element.`);
       if (layerTraps.length)
         log(`audit: ${layerTraps.length} trapped layer warning(s)`);
+      for (const hit of pageBackgrounds)
+        diagnose("engine.page-background.unreferenced", `"${hit.url}" is only referenced from "${hit.where}", and Chromium will not print an image referenced nowhere else — the page prints with its background colour alone, with no error. Gutterpress stages and preloads every image your project stylesheets reference, so this one is outside that: it is remote (a url(https://...), which is never staged), or it comes from CSS that does not pass through your stylesheets, or an element in the document uses the same URL as its src, which drops it on its own. Use a local image, referenced from one of your project stylesheets, and not also used as an <img>.`);
+      if (pageBackgrounds.length)
+        log(`audit: ${pageBackgrounds.length} unreferenced @page background image(s)`);
       for (const d of multicol)
         diagnose("engine.multicol.dead-column", `${d} runs over more than one page in columns, and only the last page's columns get balanced — earlier pages are left with an empty column. Add column-fill: auto to ${d}.`);
       if (multicol.length)
@@ -2069,6 +2139,7 @@ async function predictPageMap(browser, url, agentScript, viewerScript, args, she
   let page;
   try {
     page = await browser.newPage();
+    await page.send("Emulation.setScrollbarsHidden", { hidden: true });
     await page.send("Emulation.setDeviceMetricsOverride", sheetViewport);
     await page.navigate(url);
     await page.evaluate(agentScript);

package/dist/{index-7hrvksrb.js → index-y7jbczsb.js}

@@ -608,7 +608,7 @@ var preview_shell_default = "./preview-shell-kyjq59d9.js";
 var CGATS21_CRPC1_default = "./CGATS21_CRPC1-g0e3k7kr.icc";
 
 // src/assets/engine/gutterpress-viewer.js
-var gutterpress_viewer_default = "./gutterpress-viewer-tma1qwz2.js";
+var gutterpress_viewer_default = "./gutterpress-viewer-mfeccbys.js";
 
 // src/assets/engine/gutterpress-agent.js
 var gutterpress_agent_default = "./gutterpress-agent-cazqstr1.js";
@@ -711,7 +711,18 @@ var MARGIN_BOX_IGNORED_PROPERTIES = new Set([
   "rotate",
   "translate",
   "scale",
-  "box-shadow"
+  "perspective",
+  "box-shadow",
+  "opacity",
+  "outline",
+  "outline-color",
+  "outline-style",
+  "outline-width",
+  "outline-offset",
+  "filter",
+  "backdrop-filter",
+  "mix-blend-mode",
+  "clip-path"
 ]);
 function isIgnoredMarginBoxProperty(property) {
   return MARGIN_BOX_IGNORED_PROPERTIES.has(property.toLowerCase());

package/dist/index.js

@@ -113,15 +113,15 @@ import {
   syncProject,
   testRemoteAccess,
   validateProjectPlugins
-} from "./index-j6b6cees.js";
+} from "./index-ahzftp35.js";
 import {
   BUILD_DIAGNOSTIC_CODES
-} from "./index-p0ebr7dh.js";
+} from "./index-n252zv7d.js";
 import {
   BuildError,
   DEFAULT_PRINT_OPTS,
   readyProbeExpr
-} from "./index-7hrvksrb.js";
+} from "./index-y7jbczsb.js";
 import {
   AUTO_SNAPSHOT_MESSAGE,
   HISTORY_PAGE_LIMIT,

package/dist/lib/asset-inline.d.ts

@@ -6,7 +6,8 @@
  * local `@import` closure) is inlined, so a stylesheet's location is irrelevant
  * to the output and themes/shared design systems need no copying. Fonts become
  * `data:` URIs — which is what guarantees the byte-identical face reaches
- * Chromium, and therefore the PDF. Small images inline; large ones are copied.
+ * Chromium, and therefore the PDF. Images are files: every CSS image is copied
+ * under a content-addressed name, whatever it weighs.
  *
  * A missing stylesheet or font is a build error here, at read time, rather than
  * a 404 during pagination that Paged.js parsed as CSS or silently replaced with
@@ -14,8 +15,6 @@
  *
  * Bundle-safe (CLAUDE.md §1/§3): postcss only.
  */
-/** Inline images up to this size; copy larger ones (full-bleed page art). */
-export declare const IMAGE_INLINE_MAX_BYTES: number;
 /** One file the build must copy into the output directory. */
 export interface AssetCopy {
     /** Absolute path of the source file. */
@@ -92,8 +91,11 @@ export declare function inlineStyles(projectDir: string, stylePaths: string[]):
  */
 export declare function collectStyleDependencies(projectDir: string, stylePaths: string[]): Promise<string[]>;
 /**
- * Turn the renderer's recorded image references into a copy plan. Images keep
- * their authored relative path, so the author's folder layout is what ships.
+ * Turn the renderer's recorded image references into a copy plan. PROSE images
+ * keep their authored relative path, so the author's folder layout is what
+ * ships for them. CSS images do NOT — `inlineOne` content-addresses every one,
+ * deliberately, so a CSS URL and a prose URL can never coincide (see the
+ * comment there). A file used both ways therefore ships twice under two names.
  * A `../` reference is rejected rather than silently relocated — it has no
  * representable path under the output root.
  */

package/dist/lib/markdown/assemble.d.ts

@@ -39,6 +39,43 @@ export interface AssembleBookHtmlOptions {
      * relocate or lose during staging.
      */
     projectCss?: string;
+    /**
+     * SHIM — spec gap #152. Output-relative hrefs of the images the project's
+     * stylesheets staged (`inlineStyles`'s copy plan, verbatim), each emitted as
+     * one `<link rel="preload" as="image">`.
+     *
+     * Chromium reaches an `@page`-only `url()` lazily, during the print, and the
+     * print path CDP drives never waits for a pending resource — so the sheet
+     * comes back with its background colour alone, no error, a valid PDF of
+     * blank paper (docs/known-limitations.md §3; mechanism in
+     * PR #187's `docs/analysis/why-page-background-drops.md`).
+     *
+     * What the preload buys is that the fetch STARTS during document load
+     * instead of during the print. That is not a timing guarantee: a response
+     * slow enough still loses (measured — held 1500 ms server-side, the preload
+     * row drops too). On the PDF path the asset is a local file staged beside
+     * `book.html`, so there is no server to be slow; a published `--format html`
+     * bundle read over a slow network can still lose the race.
+     *
+     * A second ELEMENT reference is not an alternative. Any `[src]` naming the
+     * URL drops the page box (measured 12/12, with or without a preload, in
+     * either document order) — which is why `asset-inline.ts` content-addresses
+     * every CSS image so no element can name one.
+     *
+     * WHAT PROVES IT IS STILL NEEDED: the expiry canary,
+     * `engine/compiler/page-background-chromium-bug.canary.test.ts`. The day it
+     * goes red, Chromium has fixed the bug — delete this option, the `.map()`
+     * that feeds it in `markdown/index.ts`, and the canary.
+     *
+     * The copy plan is the source, NOT a scan of the assembled CSS: `pluginCss`
+     * never passes through `inlineStyles`, so a `url()` inside it is never
+     * staged and a scan would emit a `<link>` to a file that does not exist.
+     * The plan is already deduped (keyed by destination), already excludes fonts
+     * (inlined) and remote urls (left alone), and already covers the
+     * `--paper: url()` + `var(--paper)` shape, because `walkDecls` sees custom
+     * properties like any other declaration.
+     */
+    preloadImages?: string[];
     title?: string;
     plugins?: LoadedPlugin[];
     pluginCss?: string;

package/dist/lib/static-serve.d.ts

@@ -14,8 +14,7 @@ import http from "node:http";
  * answering a separate question, "what Content-Type does a data: URI need
  * when embedding this file inline," vs. this table's "what Content-Type does
  * an HTTP response need" — had drifted again, missing `.webp`/`.avif` here.
- * A large (>512KB, over the inliner's threshold) WebP/AVIF image was copied
- * as a real file and then served as `application/octet-stream` by both
+ * A copied WebP/AVIF image was served as `application/octet-stream` by both
  * servers above. Added below; if a third image format shows up, add it to
  * BOTH tables in the same commit (asset-inline.ts is out of scope for this
  * PR — see docs/reviews/duplication-audit-2026-07-28.md).

package/dist/{lint-7wss5p35.js → lint-e36t5jz3.js}

@@ -1,16 +1,16 @@
 import {
   MANIFEST_FILENAMES,
   runLint
-} from "./cli-bq7vkea9.js";
+} from "./cli-wrt39m23.js";
 import {
   log
-} from "./cli-n79ghfhs.js";
+} from "./cli-mnekrb8s.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-4n1p25df.js";
-import"./cli-eewynen9.js";
+} from "./cli-nrv3gzz9.js";
+import"./cli-6qhw9v08.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/{new-6gz60bbx.js → new-8jhvnqzp.js}

@@ -5,16 +5,16 @@ import {
   TARGETS,
   TARGET_IDS,
   scaffoldProject
-} from "./cli-bq7vkea9.js";
+} from "./cli-wrt39m23.js";
 import {
   resolveGhostscript
-} from "./cli-n79ghfhs.js";
+} from "./cli-mnekrb8s.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-4n1p25df.js";
-import"./cli-eewynen9.js";
+} from "./cli-nrv3gzz9.js";
+import"./cli-6qhw9v08.js";
 import {
   isToolAvailable
 } from "./cli-c41yr7he.js";

package/dist/{plugin-7awkmgq0.js → plugin-2390rtn1.js}

@@ -1,14 +1,14 @@
 import {
   addNpmPlugin,
   parseNpmPluginSpec
-} from "./cli-bq7vkea9.js";
-import"./cli-n79ghfhs.js";
+} from "./cli-wrt39m23.js";
+import"./cli-mnekrb8s.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-4n1p25df.js";
-import"./cli-eewynen9.js";
+} from "./cli-nrv3gzz9.js";
+import"./cli-6qhw9v08.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/{preflight-3tb7stqb.js → preflight-bvtf28e4.js}

@@ -2,16 +2,16 @@ import {
   executeValidation,
   publishTargetFor,
   reportMissingTools
-} from "./cli-bq7vkea9.js";
+} from "./cli-wrt39m23.js";
 import {
   log
-} from "./cli-n79ghfhs.js";
+} from "./cli-mnekrb8s.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-4n1p25df.js";
-import"./cli-eewynen9.js";
+} from "./cli-nrv3gzz9.js";
+import"./cli-6qhw9v08.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/preview/server-context.d.ts

@@ -35,12 +35,12 @@ export interface ServerState {
      * Files the inlined CSS references but could not embed, as
      * `book.html`-relative URL path → absolute source path.
      *
-     * `asset-inline.ts` embeds fonts and images up to
-     * `IMAGE_INLINE_MAX_BYTES`; anything larger keeps its project-relative path
-     * (if it lives in the book) or becomes `assets/<contentHash><ext>` (if it
-     * does not — e.g. art referenced from a repo-root shared stylesheet, the
-     * normative multi-book layout). Either way the inliner returns a COPY PLAN,
-     * which the build executes into its output dir.
+     * `asset-inline.ts` embeds fonts; every image becomes
+     * `assets/<contentHash><ext>`, wherever it lives — in the book, or in a
+     * repo-root shared stylesheet's art folder (the normative multi-book
+     * layout). The inliner returns a COPY PLAN, which the build executes into
+     * its output dir. Content-addressing is what keeps a CSS image's URL
+     * distinct from a prose image's; see `inlineOne`.
      *
      * The preview serves the project in place and has no output dir, so a
      * rewritten `assets/<hash>` URL had nothing behind it and shared art

package/dist/{preview-7a35z1v1.js → preview-37g504pr.js}

@@ -6,10 +6,10 @@ import {
   runBuild,
   splitOutPath,
   startPreviewServer
-} from "./cli-bq7vkea9.js";
+} from "./cli-wrt39m23.js";
 import {
   log
-} from "./cli-n79ghfhs.js";
+} from "./cli-mnekrb8s.js";
 import {
   UsageError,
   parseEngine,
@@ -18,8 +18,8 @@ import {
   rejectExtraPositionals,
   rejectUnknownFlags,
   resolvePort
-} from "./cli-4n1p25df.js";
-import"./cli-eewynen9.js";
+} from "./cli-nrv3gzz9.js";
+import"./cli-6qhw9v08.js";
 import"./cli-c41yr7he.js";
 import {
   BuildError

package/dist/{publish-dpx2cebg.js → publish-v1gc8zm4.js}

@@ -7,17 +7,17 @@ import {
   publishCredentialKey,
   publishProviderFor,
   runPublish
-} from "./cli-bq7vkea9.js";
+} from "./cli-wrt39m23.js";
 import {
   FileTokenStore,
   log
-} from "./cli-n79ghfhs.js";
+} from "./cli-mnekrb8s.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-4n1p25df.js";
-import"./cli-eewynen9.js";
+} from "./cli-nrv3gzz9.js";
+import"./cli-6qhw9v08.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/render.js

@@ -1389,12 +1389,14 @@ ${projectCss.trim()}` : null
   ].filter(Boolean).join(`
 
 `);
+  const preloadTags = (opts.preloadImages ?? []).map((href) => `
+  <link rel="preload" as="image" href="${href}">`).join("");
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${title}</title>
+  <title>${title}</title>${preloadTags}
   <style data-project-css>
 ${inlineCss}
 </style>

package/dist/test-helpers/testkit.d.ts

@@ -89,3 +89,34 @@ export declare class ProcessExitSignal extends Error {
  * `build-runner.browser-lifecycle.test.ts`.
  */
 export declare function stubProcessExit(): ReturnType<typeof spyOn<typeof process, "exit">>;
+/**
+ * "Did this declaration paint anything?" is not answerable from a PDF's
+ * structure — Chromium fetches an unreferenced `@page` background image and
+ * then paints nothing, with no error and no missing object
+ * (docs/known-limitations.md §3, #152). The only honest answer is pixels, so
+ * these helpers rasterize page 1 and diff it against a control.
+ *
+ * Ghostscript rather than poppler's `pdftoppm`: `gs` is what CI installs, and
+ * one rasterizer keeps the two page-background suites measuring the same way.
+ */
+export interface GrayRaster {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+/** Ghostscript's path, or `null`. Callers self-skip, as the PDF/X suites do. */
+export declare function resolveRasterizer(): Promise<string | null>;
+/** Page 1 of `pdfPath` as an 8-bit grayscale raster at 100 dpi. */
+export declare function rasterizePdfPage(gsBin: string, pdfPath: string, outDir: string, tag: string): GrayRaster;
+/**
+ * Mean absolute per-pixel difference. `0` means the two prints are identical —
+ * i.e. the declaration under test changed nothing at all.
+ */
+export declare function meanAbsDiff(a: GrayRaster, b: GrayRaster): number;
+/**
+ * A minimal RGB PNG encoder, so page-background fixtures can generate the
+ * exact image they need — a solid tile that is unmistakable when it paints, or
+ * an incompressible one that is genuinely large — instead of carrying opaque
+ * base64 blobs whose size and contrast nobody can check by reading them.
+ */
+export declare function pngRgb(width: number, height: number, pixel: (x: number, y: number) => [number, number, number]): Buffer;

package/dist/{validate-hbe05b26.js → validate-5yzb2qzq.js}

@@ -1,15 +1,15 @@
 import {
   executeAndReport
-} from "./cli-bq7vkea9.js";
+} from "./cli-wrt39m23.js";
 import {
   log
-} from "./cli-n79ghfhs.js";
+} from "./cli-mnekrb8s.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-4n1p25df.js";
-import"./cli-eewynen9.js";
+} from "./cli-nrv3gzz9.js";
+import"./cli-6qhw9v08.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gutterpress",
-  "version": "0.10.1",
+  "version": "0.10.2-alpha.1",
   "description": "Markdown-to-PDF converter for professional print layout using a native Chromium print engine and Ghostscript.",
   "author": "itlackey",
   "license": "MPL-2.0",