gutterpress 0.10.0-alpha.3 → 0.10.0-beta.1

package/dist/{index-a4kr77td.js → index-wsydvp08.js}

@@ -1,7 +1,10 @@
 import {
   getAssetPath,
-  launchChromium
-} from "./index-mvehxh0e.js";
+  isIgnoredMarginBoxProperty,
+  launchChromium,
+  marginBoxAlign,
+  marginBoxRectPt
+} from "./index-c2b6gyeg.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.js

@@ -140,15 +140,15 @@ import {
   validateProjectPlugins,
   verifyRepoReadable,
   writeAppHeartbeat
-} from "./index-s416qpdv.js";
+} from "./index-052x5fef.js";
 import {
   BUILD_DIAGNOSTIC_CODES
-} from "./index-a4kr77td.js";
+} from "./index-wsydvp08.js";
 import {
   BuildError,
   DEFAULT_PRINT_OPTS,
   readyProbeExpr
-} from "./index-mvehxh0e.js";
+} from "./index-c2b6gyeg.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/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";

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

@@ -10,6 +10,56 @@ export default function plugin(md: any, pluginOptions?: {}): void;
  * on its own page instead of resolving against the document canvas and
  * painting on the last page of the book.
  *
+ * `min-height: var(--gp-content-h)` is the other half of that contract: a
+ * page root that only shrink-wraps its text is a containing block whose
+ * `bottom` edge is the end of the PROSE, so `.gp-pin .gp-bottom` (and every
+ * hand-written `position: absolute; bottom: 0`) lands under the last
+ * paragraph instead of at the page foot. Paged.js used to supply this height
+ * for free — `.pagedjs_pagebox > .pagedjs_area > .pagedjs_page_content > div
+ * { height: inherit; }` stretched the page root to the page area — and
+ * deleting the polyfill (native-only migration, Phase 6) silently took
+ * page-boundary pinning with it. Both renderers now publish the page
+ * CONTENT height as `--gp-content-h` for the page context the element is in
+ * (the viewer on each `.gp-strip`; the compiler on `:root` plus every
+ * `page:` assignment selector), and custom properties inherit, so this one
+ * rule reaches a page root at any wrapper depth. Undefined var (plain
+ * markdown-it use, no engine) falls back to `1px`, which the cushion below
+ * takes back to zero — the rule is inert outside the pipeline, leaving the
+ * page root shrink-wrapped exactly as it is today.
+ *
+ * It is `min-height`, not `height`: a `.page` whose content runs past one
+ * sheet must still fragment normally. The whole rule is `:where()`, so an
+ * author who wants any of it back sets their own value at any specificity.
+ *
+ * `box-sizing` and `display` are what make a page-sized min-height safe, and
+ * both were found by MEASURING a real book (docs/fixtures/css-authoring-spike)
+ * print one extra sheet without them:
+ *
+ *   - `border-box`, because a page root with padding (that fixture's cover
+ *     has `padding-top: 2.5in`) would otherwise be one content box PLUS its
+ *     padding tall, which is one sheet plus 2.5in — the overflow lands on a
+ *     spurious blank sheet.
+ *   - `flow-root`, because a child margin collapsing THROUGH the root's edge
+ *     survives the forced break and eats into the new sheet: that fixture's
+ *     last page opens with an `<h2>` whose 22.4px margin-top pushed a
+ *     719px-tall root down 22.4px on a 720px sheet, spilling it. A page root
+ *     is a page; containing its children's margins is what a page does. The
+ *     viewer already forces `flow-root` on displaced page roots for exactly
+ *     this reason (`stabilizeFullHeightPageRoots`, fragment.ts) — declaring
+ *     it once in core means both renderers start from the same box. Zero
+ *     specificity, so an authored `display: flex`/`grid` page root still
+ *     wins, which is the case that function's comment warns about.
+ *
+ * The `- 1px` is the fragmentation cushion, and it is load-bearing. A box
+ * whose bottom edge lands EXACTLY on the fragmentainer's edge costs an empty
+ * fragment: MEASURED (Chromium 148, 384x480px sheet, 24px margins, one
+ * short page root) `min-height: 432px` prints 2 sheets with the second
+ * blank while `431px` prints 1 — and the viewer's multicol strip does the
+ * same, which is how it first showed up (an 8pp preview of a 7pp book on
+ * the gp-image-positioning fixture). One px at 96dpi is 0.75pt: it moves a
+ * pinned foot up by less than a point and absorbs sub-pixel rounding in the
+ * published value. Do not "clean it up" — the sheet it costs is silent.
+ *
  * The break/orphan rules below (`break-after` on headings, image sizing,
  * first-child glue) are all `:where()` so they carry zero specificity —
  * author CSS at any specificity wins outright, reusing this same
@@ -29,4 +79,4 @@ export default function plugin(md: any, pluginOptions?: {}): void;
  * `text-align: center` still centers it — `display: block` would not).
  *
  */
-export const MARKER_CSS: "\n/* The UA default of 8px body margin is a screen affordance with no meaning\n   in paged media, and engines disagree about it: a polyfill that treats the\n   page div as the page box drops it, native print keeps it. Left in place it\n   insets EVERY page's content by 8px per side, and -- measured, 300dpi,\n   6x4in sheet -- it is what stops a full-width block from reaching the\n   paper: it lands at 0.080..5.917in of a 6in sheet instead of\n   0.000..6.000in, because width:100% resolves against the BODY content box,\n   not the page's. Zeroing it here (first in the cascade) makes the two\n   agree. Authors who want a body margin still just declare one. */\nbody { margin: 0; }\n\n.gp-page-break { break-before: page; }\n.page { break-before: page; }\n.spread { break-before: page; }\n:where(.page, .spread) { position: relative; }\n.gp-column-break { break-after: column; height: 0; font-size: 0; line-height: 0; visibility: hidden; }\n\n:where(h1,h2,h3,h4,h5,h6) { break-after: avoid; }\n:where(img, svg, video) { max-width: 100%; }\n:where(p > img:only-child, figure > img) { width: fit-content; max-width: 100%; height: auto; vertical-align: bottom; }\n:where(.section, figure) > :where(:first-child) { break-before: avoid; }\n\n";
+export const MARKER_CSS: "\n/* The UA default of 8px body margin is a screen affordance with no meaning\n   in paged media, and engines disagree about it: a polyfill that treats the\n   page div as the page box drops it, native print keeps it. Left in place it\n   insets EVERY page's content by 8px per side, and -- measured, 300dpi,\n   6x4in sheet -- it is what stops a full-width block from reaching the\n   paper: it lands at 0.080..5.917in of a 6in sheet instead of\n   0.000..6.000in, because width:100% resolves against the BODY content box,\n   not the page's. Zeroing it here (first in the cascade) makes the two\n   agree. Authors who want a body margin still just declare one. */\nbody { margin: 0; }\n\n.gp-page-break { break-before: page; }\n.page { break-before: page; }\n.spread { break-before: page; }\n:where(.page, .spread) { position: relative; display: flow-root; box-sizing: border-box; min-height: calc(var(--gp-content-h, 1px) - 1px); }\n.gp-column-break { break-after: column; height: 0; font-size: 0; line-height: 0; visibility: hidden; }\n\n:where(h1,h2,h3,h4,h5,h6) { break-after: avoid; }\n:where(img, svg, video) { max-width: 100%; }\n:where(p > img:only-child, figure > img) { width: fit-content; max-width: 100%; height: auto; vertical-align: bottom; }\n:where(.section, figure) > :where(:first-child) { break-before: avoid; }\n\n";

package/dist/{lint-gsh6qwrq.js → lint-17404bsx.js}

@@ -1,16 +1,16 @@
 import {
   MANIFEST_FILENAMES,
   runLint
-} from "./cli-5czby0dd.js";
+} from "./cli-5tffrg48.js";
 import {
   log
-} from "./cli-gk3wsdpb.js";
+} from "./cli-v935c2ws.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-f4rcbt2t.js";
-import"./cli-yp3p0sf2.js";
+} from "./cli-7e79d7se.js";
+import"./cli-afm8pa0h.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/{new-nkhycqy4.js → new-vsgpxzek.js}

@@ -5,16 +5,16 @@ import {
   TARGETS,
   TARGET_IDS,
   scaffoldProject
-} from "./cli-5czby0dd.js";
+} from "./cli-5tffrg48.js";
 import {
   resolveGhostscript
-} from "./cli-gk3wsdpb.js";
+} from "./cli-v935c2ws.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-f4rcbt2t.js";
-import"./cli-yp3p0sf2.js";
+} from "./cli-7e79d7se.js";
+import"./cli-afm8pa0h.js";
 import {
   isToolAvailable
 } from "./cli-c41yr7he.js";

package/dist/{plugin-129wcs93.js → plugin-s4yfpx6p.js}

@@ -1,14 +1,14 @@
 import {
   addNpmPlugin,
   parseNpmPluginSpec
-} from "./cli-5czby0dd.js";
-import"./cli-gk3wsdpb.js";
+} from "./cli-5tffrg48.js";
+import"./cli-v935c2ws.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-f4rcbt2t.js";
-import"./cli-yp3p0sf2.js";
+} from "./cli-7e79d7se.js";
+import"./cli-afm8pa0h.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES