gutterpress 0.11.20-alpha.3 → 0.11.20-alpha.5

package/dist/{cli-9k2tb493.js → cli-sc5t7c74.js}

@@ -16,12 +16,12 @@ import {
   stripAnnotations,
   transparentPages,
   warn
-} from "./cli-y9bcya7r.js";
+} from "./cli-6xym15vm.js";
 import {
   DEBOUNCE,
   UsageError,
   resolvePort
-} from "./cli-hn9pk0hp.js";
+} from "./cli-553ce1d4.js";
 import {
   blackTextToGray
 } from "./cli-ht1bcqdd.js";
@@ -30,7 +30,7 @@ import {
   getAssetPath,
   getAssetsDir,
   lastPageMode
-} from "./cli-x4p99w8d.js";
+} from "./cli-cyej3p9v.js";
 import {
   BuildError,
   EXIT_CODES
@@ -147,7 +147,8 @@ var DTRPG_PRESET = {
     tolerance: 0.5,
     bleed: 9,
     safe: 36,
-    artSafe: 18
+    artSafe: 18,
+    gutter: undefined
   },
   ink: {
     maxTac: 240,
@@ -234,7 +235,8 @@ var BOOK_PRESET = {
     tolerance: 0.5,
     bleed: undefined,
     safe: 18,
-    artSafe: undefined
+    artSafe: undefined,
+    gutter: undefined
   },
   ink: {
     maxTac: 400,
@@ -592,7 +594,8 @@ function resolveCustomPage(c, m) {
     tolerance: c.page?.tolerance ?? m.page?.tolerance ?? 0.5,
     bleed: c.page?.bleed ?? m.page?.bleed,
     safe: c.page?.safe ?? m.page?.safe,
-    artSafe: c.page?.artSafe ?? m.page?.artSafe
+    artSafe: c.page?.artSafe ?? m.page?.artSafe,
+    gutter: c.page?.gutter ?? m.page?.gutter
   };
 }
 function resolveWithPreset(cliOverrides, manifest, preset) {
@@ -701,6 +704,7 @@ function resolveDeclaredStyles(rawStyles, baseDir, subject) {
 // src/lib/extension-manifest.ts
 import { readFile as readFile2 } from "node:fs/promises";
 import path from "node:path";
+import { satisfies, validRange } from "semver";
 var EXTENSION_MANIFEST_FILENAME = "package.json";
 var GUTTERPRESS_KEY = "gutterpress";
 function object(value) {
@@ -724,6 +728,7 @@ function metaFromPackageJson(raw) {
     ...str(pkg.description) ? { description: str(pkg.description) } : {},
     ...keywords ? { keywords } : {},
     ...str(pkg.main) ? { main: str(pkg.main) } : {},
+    ...str(object(pkg.engines)?.gutterpress) ? { gutterpressRange: str(object(pkg.engines)?.gutterpress) } : {},
     ..."preview" in gp ? { preview: str(gp.preview) ?? null } : {},
     ...Array.isArray(gp.styles) ? { styles: declaredList(gp.styles) } : {},
     ...str(gp.tokensFile) ? { tokensFile: str(gp.tokensFile) } : {},
@@ -760,6 +765,17 @@ function extensionCarries(meta) {
 function pathEscapesFolder(rel) {
   return path.isAbsolute(rel) || rel.split(/[\\/]/).includes("..");
 }
+function assertSupportsThisGutterpress(meta, ref) {
+  const range = meta.gutterpressRange;
+  if (range === undefined)
+    return;
+  if (!validRange(range)) {
+    throw new Error(`Extension "${ref}" has an invalid engines.gutterpress range "${range}".`);
+  }
+  if (!satisfies(PACKAGE_VERSION, range, { includePrerelease: true })) {
+    throw new Error(`Extension "${ref}" needs Gutterpress ${range} (its package.json engines.gutterpress); ` + `this is Gutterpress ${PACKAGE_VERSION}. Update Gutterpress, or pin an older version of the extension.`);
+  }
+}
 function assertExtensionContained(meta) {
   if (meta.engineStyles !== undefined) {
     throw new Error("The extension's metadata declares `engineStyles`, which was removed — " + "move its entries to the end of `styles`.");
@@ -2029,9 +2045,15 @@ var GUTTERPRESS_CSS = `
 
 /* sizes — AFTER the flow positions so max-width:100% lifts the floats' 50%
    cap at equal specificity */
-.gp-small { width: 25%; max-width: 100%; }
-.gp-medium { width: 50%; max-width: 100%; }
-.gp-large { width: 75%; max-width: 100%; }
+.gp-size-10 { width: 10%; max-width: 100%; }
+.gp-size-20 { width: 20%; max-width: 100%; }
+.gp-size-30 { width: 30%; max-width: 100%; }
+.gp-size-40 { width: 40%; max-width: 100%; }
+.gp-size-50 { width: 50%; max-width: 100%; }
+.gp-size-60 { width: 60%; max-width: 100%; }
+.gp-size-70 { width: 70%; max-width: 100%; }
+.gp-size-80 { width: 80%; max-width: 100%; }
+.gp-size-90 { width: 90%; max-width: 100%; }
 
 /* float clearance presets — consumed by var(--gp-gap) in the float rules
    above and by .gp-shape's shape-margin below; --gp-gap itself is
@@ -2089,10 +2111,16 @@ img.gp-shape {
 }
 
 /* pin — within the nearest positioned ancestor (.page/.spread, rule above).
-   inset:0 and the explicit centers are load-bearing; see doctrine comment. */
+   The four insets are the pin box: 0 (the text block's edge) unless an
+   engine set --gp-pin-<edge> on the page root for an edge a pin uses (the
+   art-safe line). Non-auto insets and the explicit centers are
+   load-bearing; see doctrine comment. */
 .gp-pin {
   position: absolute;
-  inset: 0;
+  top: var(--gp-pin-top, 0px);
+  right: var(--gp-pin-right, 0px);
+  bottom: var(--gp-pin-bottom, 0px);
+  left: var(--gp-pin-left, 0px);
   align-self: center;
   justify-self: center;
   margin: 0;
@@ -2107,6 +2135,16 @@ img.gp-shape {
 .gp-left { justify-self: start; }
 .gp-right { justify-self: end; }
 
+/* the escape hatch — the paper's edge, past the printer's safe area: the
+   pin box loses its art-safe insets. Set on the pin itself, so it beats the
+   values the page root hands down. */
+.gp-pin.gp-flush {
+  --gp-pin-top: 0px;
+  --gp-pin-right: 0px;
+  --gp-pin-bottom: 0px;
+  --gp-pin-left: 0px;
+}
+
 /* wrapper-margin neutralization (same pattern and rationale as the
    .gp-bleed paragraph-margin note in the doctrine comment; for pin, the
    emptied paragraph would otherwise leave a phantom margin gap in flow) */
@@ -2213,9 +2251,15 @@ var GP_CLASSES = new Set([
   "gp-center",
   "gp-full",
   "gp-bleed",
-  "gp-small",
-  "gp-medium",
-  "gp-large",
+  "gp-size-10",
+  "gp-size-20",
+  "gp-size-30",
+  "gp-size-40",
+  "gp-size-50",
+  "gp-size-60",
+  "gp-size-70",
+  "gp-size-80",
+  "gp-size-90",
   "gp-tight",
   "gp-loose",
   "gp-columns",
@@ -2232,6 +2276,7 @@ var GP_CLASSES = new Set([
   "gp-pin",
   "gp-top",
   "gp-bottom",
+  "gp-flush",
   "gp-behind",
   "gp-base",
   "gp-raised",
@@ -2245,15 +2290,14 @@ var GP_CLASSES = new Set([
   "gp-alert-caution",
   "gp-page-break",
   "gp-column-break",
-  "gp-continued",
-  "gp-flush"
+  "gp-continued"
 ]);
 
 // src/lib/markdown/gp-pin-scope.js
-function warn3(env, line, type, message, marker) {
+function warn3(env, line, type, message, severity) {
   if (!env.layoutWarnings)
     env.layoutWarnings = [];
-  env.layoutWarnings.push({ line, type, message, marker });
+  env.layoutWarnings.push(severity ? { line, type, message, severity } : { line, type, message });
 }
 function editDistance2(a, b) {
   let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
@@ -2283,6 +2327,21 @@ function hasPinClass(token) {
   const cls = token.attrGet && token.attrGet("class");
   return typeof cls === "string" && cls.split(/\s+/).includes("gp-pin");
 }
+var PIN_EDGES = ["gp-top", "gp-right", "gp-bottom", "gp-left"];
+var FLUSH_ART_MSG = "`.gp-flush` puts this image on the paper's edge, past the printer's safe area. Printers trim up to 0.125in there, so keep it for art that is meant to bleed off the page.";
+function checkFlushArt(token, env, line) {
+  if (token.type !== "image")
+    return;
+  const cls = token.attrGet && token.attrGet("class");
+  if (typeof cls !== "string")
+    return;
+  const classes = cls.split(/\s+/);
+  if (!classes.includes("gp-pin") || !classes.includes("gp-flush"))
+    return;
+  if (!classes.some((c) => PIN_EDGES.includes(c)))
+    return;
+  warn3(env, line, "flush_art", FLUSH_ART_MSG, "info");
+}
 function elementNameFor(token) {
   switch (token.type) {
     case "layout_chapter_open":
@@ -2342,6 +2401,7 @@ function gpPinScope(md) {
       if (token.type === "inline" && token.children) {
         for (const child of token.children) {
           checkUnknownGpClasses(child, state.env, line);
+          checkFlushArt(child, state.env, line);
         }
       }
     }
@@ -3369,6 +3429,7 @@ This folder still has a ${stale}. Gutterpress no longer reads it — ` + `descri
 async function loadExtensionFromDir(extensionDir, config, pluginRef) {
   const meta = await readExtensionMeta(extensionDir);
   assertExtensionContained(meta);
+  assertSupportsThisGutterpress(meta, pluginRef);
   const resolved = resolveExtension(extensionDir, meta, `Plugin "${pluginRef}"`);
   const extensionStyles = resolved.styles ?? [];
   const name = config.name ?? meta.name ?? pluginRef;
@@ -3443,6 +3504,7 @@ async function loadPlugin(config, baseDir) {
       if (loaded.packageDir) {
         const meta = await readExtensionMeta(loaded.packageDir);
         assertExtensionContained(meta);
+        assertSupportsThisGutterpress(meta, pluginRef);
         const resolved = resolveExtension(loaded.packageDir, { ...meta, main: undefined }, `Plugin "${pluginRef}"`);
         if (resolved.markdown && loaded.entryPath && resolve3(resolved.markdown) !== resolve3(loaded.entryPath)) {
           throw new Error(`its package.json declares gutterpress.markdown "${meta.markdown}" but the package entry is "${relative(loaded.packageDir, loaded.entryPath)}" — an npm extension's ` + "markdown-it plugin is its package entry, so declare that file or drop the field.");
@@ -3566,7 +3628,7 @@ import path3 from "node:path";
 import { Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { createGunzip } from "node:zlib";
-import { maxSatisfying, satisfies, validRange } from "semver";
+import { maxSatisfying, satisfies as satisfies2, validRange as validRange2 } from "semver";
 
 // src/lib/fetch-timeout.ts
 class FetchPassthroughError extends Error {
@@ -3807,7 +3869,7 @@ async function selectPackage(ctx, name, selector) {
     version = selector;
   } else if (typeof tags[selector] === "string") {
     version = tags[selector];
-  } else if (validRange(selector)) {
+  } else if (validRange2(selector)) {
     version = maxSatisfying(Object.keys(versions), selector) ?? undefined;
   }
   if (!version || !isExactNpmVersion(version)) {
@@ -4025,7 +4087,7 @@ async function installPackage(ctx, name, selector, parentPackagePath, ancestors,
     }
     throw error2;
   }
-  const ancestor = ancestors.find((candidate) => candidate.name === name && (candidate.version === selected.version || (selector ? satisfies(candidate.version, selector) : false)));
+  const ancestor = ancestors.find((candidate) => candidate.name === name && (candidate.version === selected.version || (selector ? satisfies2(candidate.version, selector) : false)));
   if (ancestor)
     return { path: ancestor.path };
   if (ctx.records.length >= ctx.limits.totalPackages) {
@@ -4990,11 +5052,11 @@ var inches = (pt) => `${+(pt / 72).toFixed(2)}in`;
 var check3 = {
   id: "pdf.print.safe-margins",
   name: "Safe margins",
-  description: "Fails when text sits closer to the trim than `page.safe` (DriveThruRPG: 0.5in on every edge). Text only: art is judged in the preview's safe-area overlay, not here. Skipped when `page.safe` is not set",
+  description: "Fails when text sits closer to the trim than `page.safe` (DriveThruRPG: 0.5in on every edge), or than `page.gutter` at the binding edge where one is set. Text only: art is judged in the preview's safe-area overlay, not here. Skipped when `page.safe` is not set",
   category: "pdf",
   phase: "post-build",
   async run(ctx) {
-    const { width, height, bleed = 0, safe = 0 } = ctx.config.page;
+    const { width, height, bleed = 0, safe = 0, gutter = safe } = ctx.config.page;
     if (!ctx.pdfPath || !safe)
       return [];
     const doc = await loadPdf(ctx.pdfPath);
@@ -5032,8 +5094,7 @@ var check3 = {
             ["bottom", Math.min(...ys) - trim.bottom],
             ["top", trim.top - Math.max(...ys)]
           ];
-          const [edge, gap] = gaps.reduce((worst, g) => g[1] < worst[1] ? g : worst);
-          const shortfall = safe - gap;
+          const [edge, shortfall] = gaps.map(([name, gap]) => [name, (name === "binding" ? gutter : safe) - gap]).reduce((worst, g) => g[1] > worst[1] ? g : worst);
           if (shortfall <= TOLERANCE_PT)
             continue;
           const text = item.str.trim();
@@ -5041,7 +5102,7 @@ var check3 = {
             severity: "error",
             message: `Page ${pageNum}: "${text.slice(0, 40)}${text.length > 40 ? "…" : ""}" is ${inches(shortfall)} too close to the ${edge} edge.`,
             file: ctx.pdfPath,
-            detail: `${rule}: text must stay at least ${inches(safe)} inside the trim on every edge.`,
+            detail: gutter === safe ? `${rule}: text must stay at least ${inches(safe)} inside the trim on every edge.` : `${rule}: text must stay at least ${inches(safe)} inside the trim, ${inches(gutter)} at the binding.`,
             code: "text-outside-safe-margin",
             data: { page: pageNum, edge, shortfallPt: +shortfall.toFixed(2) }
           }));
@@ -8885,6 +8946,21 @@ function canonicalChapterId(p) {
   return s;
 }
 
+// src/engine/shared/print-area.ts
+function printAreaMeta(page) {
+  const area = JSON.stringify({
+    width: page.width,
+    height: page.height,
+    bleed: page.bleed ?? 0,
+    safe: page.safe ?? 0,
+    artSafe: page.artSafe,
+    gutter: page.gutter,
+    preset: page.preset,
+    spec: page.spec
+  });
+  return `<meta name="gp-print-area" content='${area.replace(/&/g, "&amp;").replace(/'/g, "&#39;")}'>`;
+}
+
 // src/lib/markdown/assemble.ts
 async function assembleBookHtml(opts) {
   const title = opts.title ?? "Document";
@@ -8950,7 +9026,8 @@ ${projectCss.trim()}` : null
 <html lang="en"${printAttrs}>
 <head>
   <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">${opts.printArea ? `
+  ${printAreaMeta(opts.printArea)}` : ""}
   <title>${title}</title>${preloadTags}
   <style data-project-css>
 ${inlineCss}
@@ -9010,6 +9087,7 @@ ${css.trim()}
     preloadImages: cssAssetCopies.map((c) => c.to),
     title: opts.title,
     print: opts.print,
+    printArea: opts.printArea,
     plugins: opts.plugins,
     pluginCss,
     annotateSourceChapters: opts.annotateSourceChapters,
@@ -9022,6 +9100,7 @@ async function renderChaptersToFile(inputDir, outDir, opts = {}) {
   const html = await renderChapters(inputDir, {
     title: opts.title,
     print: opts.print,
+    printArea: opts.printArea,
     styles: opts.styles,
     files: opts.files,
     plugins: opts.plugins,
@@ -9899,6 +9978,7 @@ async function renderBook(ctx) {
   const htmlFile = await renderChaptersToFile(renderDir, workDir, {
     title: config.title,
     print: config.print,
+    printArea: { ...config.page, preset: config.preset, spec: config.spec },
     styles: config.styles,
     files: config.source.files,
     plugins,
@@ -10051,7 +10131,7 @@ class PdfOutput {
       const rawPdf = pdfxMode ? path13.join(stage, "raw.pdf") : path13.resolve(pdfFile);
       await fsp2.mkdir(path13.dirname(path13.resolve(pdfFile)), { recursive: true });
       log.info("Rendering HTML to PDF via the Gutterpress engine (native Chromium pagination)");
-      const { buildNativePdf } = await import("./engine-yxnnp3hx.js");
+      const { buildNativePdf } = await import("./engine-4rkhv5ga.js");
       const engineDiagnostics = await buildNativePdf(htmlFile, rawPdf, {
         title: config.title,
         author: config.authors.length > 0 ? config.authors.join(", ") : undefined,
@@ -10354,6 +10434,7 @@ async function renderPreviewBook(inputPath, config, opts) {
   return renderChapters(inputPath, {
     title: config.title ?? "Document",
     print: config.print,
+    printArea: config.printArea,
     styles: config.styles,
     files: opts.files,
     plugins,
@@ -10368,19 +10449,8 @@ async function renderPreviewBook(inputPath, config, opts) {
     }
   });
 }
-function injectPreviewScripts(html, page) {
-  const area = page ? JSON.stringify({
-    width: page.width,
-    height: page.height,
-    bleed: page.bleed ?? 0,
-    safe: page.safe ?? 0,
-    artSafe: page.artSafe,
-    preset: page.preset,
-    spec: page.spec
-  }) : "";
-  const meta = area ? `  <meta name="gp-print-area" content='${area.replace(/&/g, "&amp;").replace(/'/g, "&#39;")}'>
-` : "";
-  const scripts = meta + `  <script src="/engine/gutterpress-viewer.js"></script>
+function injectPreviewScripts(html) {
+  const scripts = `  <script src="/engine/gutterpress-viewer.js"></script>
   ` + `<script src="/preview/scripts/preview-interface.js"></script>
   ` + `<script src="/preview/scripts/preview-bridge.js"></script>
 `;
@@ -10395,7 +10465,10 @@ async function generateAndWriteHtml(inputPath, tempDir, config, cssAssets, image
   }
   const nextAssets = new Map;
   const nextImageRefs = new Set;
-  const html = await renderPreviewBook(inputPath, config, {
+  const html = await renderPreviewBook(inputPath, {
+    ...config,
+    printArea: config.page && { ...config.page, preset: config.preset, spec: config.spec }
+  }, {
     files: config.source?.files ?? null,
     onCssAssets: (copies) => {
       for (const copy of copies)
@@ -10414,7 +10487,7 @@ async function generateAndWriteHtml(inputPath, tempDir, config, cssAssets, image
     for (const ref of nextImageRefs)
       imageRefs.add(ref);
   }
-  await fsp3.writeFile(path15.join(tempDir, BOOK_HTML_FILENAME), injectPreviewScripts(html, config.page && { ...config.page, preset: config.preset, spec: config.spec }), "utf-8");
+  await fsp3.writeFile(path15.join(tempDir, BOOK_HTML_FILENAME), injectPreviewScripts(html), "utf-8");
 }
 function isDotPathUnderRoot(candidatePath, root) {
   const normalizedRoot = root.replace(/\\/g, "/").replace(/\/+$/, "");

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   UsageError,
   package_default,
   rejectUnknownFlags
-} from "./cli-hn9pk0hp.js";
+} from "./cli-553ce1d4.js";
 import {
   EXIT_CODES
 } from "./cli-46ycxe6r.js";
@@ -18,14 +18,14 @@ import {
 import { defineCommand, parseArgs, runMain } from "citty";
 import { statSync } from "node:fs";
 var SUBCOMMANDS = {
-  new: () => import("./new-8yah8z91.js").then((m) => m.default),
-  preview: () => import("./preview-w7v9w36q.js").then((m) => m.default),
-  build: () => import("./build-a8ycsg80.js").then((m) => m.default),
-  publish: () => import("./publish-g5nh5myh.js").then((m) => m.default),
-  validate: () => import("./validate-1yh59x0x.js").then((m) => m.default),
-  preflight: () => import("./preflight-8ccx4kdc.js").then((m) => m.default),
-  doctor: () => import("./doctor-wbjkrcpc.js").then((m) => m.default),
-  ext: () => import("./ext-pesyrs68.js").then((m) => m.default)
+  new: () => import("./new-87dqcxtn.js").then((m) => m.default),
+  preview: () => import("./preview-7bcr5j2p.js").then((m) => m.default),
+  build: () => import("./build-8ffhvydf.js").then((m) => m.default),
+  publish: () => import("./publish-4qfm5ch9.js").then((m) => m.default),
+  validate: () => import("./validate-dzht9qxk.js").then((m) => m.default),
+  preflight: () => import("./preflight-nb4wndqf.js").then((m) => m.default),
+  doctor: () => import("./doctor-gyes0hxt.js").then((m) => m.default),
+  ext: () => import("./ext-x61yptd1.js").then((m) => m.default)
 };
 var VERSION = package_default.version;
 var main = defineCommand({
@@ -50,7 +50,7 @@ async function preflightRequiredInvocations(rawArgs) {
   const [command, ...commandArgs] = rawArgs;
   try {
     if (command === "new") {
-      const { newArgs } = await import("./new-8yah8z91.js");
+      const { newArgs } = await import("./new-87dqcxtn.js");
       rejectUnknownFlags(commandArgs, newArgs, "new");
       const parsed = parseArgs(commandArgs, {
         ...newArgs,
@@ -62,7 +62,7 @@ async function preflightRequiredInvocations(rawArgs) {
       return;
     }
     if (command === "preflight") {
-      const { preflightArgs } = await import("./preflight-8ccx4kdc.js");
+      const { preflightArgs } = await import("./preflight-nb4wndqf.js");
       rejectUnknownFlags(commandArgs, preflightArgs, "preflight");
       const parsed = parseArgs(commandArgs, {
         ...preflightArgs,
@@ -82,7 +82,7 @@ async function preflightRequiredInvocations(rawArgs) {
       }
       if (subcommand.startsWith("-"))
         return;
-      const { EXT_SUBCOMMANDS, extAddArgs, extRemoveArgs, extEnableArgs, extDisableArgs } = await import("./ext-pesyrs68.js");
+      const { EXT_SUBCOMMANDS, extAddArgs, extRemoveArgs, extEnableArgs, extDisableArgs } = await import("./ext-x61yptd1.js");
       if (!EXT_SUBCOMMANDS.includes(subcommand)) {
         throw new UsageError(`gutterpress ext: unknown command "${subcommand}"`);
       }

package/dist/{doctor-wbjkrcpc.js → doctor-gyes0hxt.js}

@@ -1,12 +1,12 @@
 import {
   getSystemDiagnostics,
   log
-} from "./cli-y9bcya7r.js";
+} from "./cli-6xym15vm.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-hn9pk0hp.js";
+} from "./cli-553ce1d4.js";
 import"./cli-46ycxe6r.js";
 import"./cli-asap4t1z.js";
 import"./cli-37x76zdn.js";

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

@@ -8,7 +8,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" | "engine.page-background.unreferenced" | "engine.hyphenation.unsupported";
+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.pin.margin-box" | "engine.page-background.unreferenced" | "engine.hyphenation.unsupported";
 export declare const BUILD_DIAGNOSTIC_CODES: readonly BuildDiagnosticCode[];
 export interface BuildDiagnostic {
     code: BuildDiagnosticCode;

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

@@ -31,8 +31,8 @@ export declare function isIgnoredMarginBoxProperty(property: string): boolean;
  * Geometry of each of the 16 margin boxes, per CSS Paged Media §5.3, in pt
  * SHEET coordinates (origin at the sheet's top-left). One implementation for
  * both furniture painters: the viewer's `drawMarginBoxes` overlays and the
- * compiler's `.gp-flush` furniture relocation must place a box at the same
- * spot or preview and print disagree about where the folio sits.
+ * compiler's relocation of a pinned edge's furniture must place a box at the
+ * same spot or preview and print disagree about where the folio sits.
  */
 export declare function marginBoxRectPt(name: string, g: {
     width: number;

package/dist/engine/shared/pin-edges.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Pinned-art policy — shared by the compiler and the viewer, like every rule
+ * that DECIDES something (see synthesis.ts's header).
+ *
+ * THE MODEL: a pin box the text never shares. A `.gp-pin` with an edge word
+ * (`.gp-top`, `.gp-right`, `.gp-bottom`, `.gp-left`) positions itself inside
+ * its page root (`.page`/`.spread`, `position: relative` in MARKER_CSS), and
+ * where it sits has no effect on the text:
+ *
+ *  1. The page MARGIN on each pinned edge is freed. Chromium's printable area
+ *     IS the page area — MEASURED, a pinned box pulled into the margin with
+ *     negative insets fragments onto the NEXT sheet, one moved there with a
+ *     transform is clipped away entirely, and a margin box in a ~zero margin
+ *     (1px, with padding/height compensation) simply does not render. So the
+ *     only way art reaches the paper is page GEOMETRY, per page:
+ *       - the COMPILER aliases the root's own page context under a generated
+ *         name (verbatim rule copies — never a resolved flatten, which is the
+ *         "re-implement the @page cascade" trap tier2's history records),
+ *         zeroes the pinned margins on the alias, and assigns the root to it;
+ *       - the VIEWER keeps the author's page context and frees the margins in
+ *         the run's strip geometry, from these same functions.
+ *  2. The root gets that same margin back as PADDING (`box-decoration-break:
+ *     clone`, so every fragment of a root that spans pages keeps it), added
+ *     to any padding the root has of its own. Its content box is therefore
+ *     the author's content box — same width, same height, same place, same
+ *     line and page breaks — whatever is pinned where. That is the whole
+ *     point: freeing the margin once let the text grow into it. (What the
+ *     root paints itself — a background, a border — does grow with it: the
+ *     root's box is the page area, and that area reaches the paper.)
+ *  3. The pin box is the root's padding box — which now reaches the paper on
+ *     the pinned edges — inset by the printer's ART-SAFE line: `--gp-pin-<edge>`
+ *     on the root, read by `.gp-pin`'s four insets (GUTTERPRESS_CSS). On the
+ *     top, bottom and outside edge that is the bleed plus `page.artSafe`; at
+ *     the binding edge `page.gutter` (no bleed there) — the manifest's print
+ *     area (print-area.ts), so a book with none sets 0, the paper's edge.
+ *  4. `.gp-flush` on the pin zeroes the four properties in plain CSS: the
+ *     opt-in escape hatch to the paper's edge (the markdown pipeline notes it).
+ *     Nothing else here knows about it.
+ *
+ * Sides. Recto values are the defaults (`@page :right`'s margins, the
+ * binding on the left). Mirrored `:left`/`:right` margins agree on the content
+ * SIZE, so the viewer paginates identically either way; each engine corrects a
+ * verso root once it knows the side — the viewer after it measures its
+ * strips, the compiler in its synthesis step (`setPinGeometry`).
+ *
+ * Margin boxes live IN the margin, so a freed edge's furniture (folio, running
+ * head) cannot render natively there — MEASURED, no compensation trick
+ * survives. Both renderers therefore keep painting that furniture themselves
+ * at its ORIGINAL coordinates: the viewer already synthesizes all furniture as
+ * DOM; the compiler injects the freed edge's boxes into the page root as
+ * positioned elements with engine-resolved text. Nothing the author declared
+ * is lost — that is the contract this module's box map exists to keep.
+ *
+ * Everything the author's document gets is standard CSS: a padding, a custom
+ * property per edge, absolute insets, and (print only) a named page.
+ */
+import type { PageGeometry } from "./gcpm-extract.ts";
+import type { PageSide, PrintArea } from "./print-area.ts";
+export declare const PIN_EDGES: readonly ["top", "right", "bottom", "left"];
+export type PinEdge = (typeof PIN_EDGES)[number];
+/** Every pin that names an edge. */
+export declare const EDGE_PIN_SELECTOR: string;
+/** Minimal DOM shapes `pinEdgesIn` needs — keeps this module node-safe. */
+interface PinElement {
+    /** an HTML element's containing block for abspos (`HTMLElement.offsetParent`) */
+    readonly offsetParent?: unknown;
+    readonly classList: {
+        contains(token: string): boolean;
+    };
+}
+interface QueryRoot {
+    querySelectorAll(selector: string): ArrayLike<PinElement>;
+}
+/**
+ * The edges the pins of page root `root` use, in canonical t/r/b/l order — a
+ * pin counts when `root` is its containing block (its `offsetParent`): a pin
+ * in a nested page root belongs to that root, and one a positioned card
+ * frames belongs to the card, so neither frees this root's margins. A pin
+ * without an edge word frees nothing and centres in the text block.
+ */
+export declare function pinEdgesIn(root: QueryRoot): PinEdge[];
+/** Canonical short key for an edge set: "b", "rb", "trbl"… (t/r/b/l order). */
+export declare function pinKey(edges: readonly PinEdge[]): string;
+/**
+ * Generated page name for (author page context, edge set). The `gp--` double
+ * dash marks an engine-generated page (the `gp--blank` convention); these
+ * exist only in builds that actually contain an edge pin, which is why the
+ * width check may treat them as real author contexts.
+ */
+export declare function pinPageName(authorPage: string | undefined, edges: readonly PinEdge[]): string;
+/** The page's margins with the pinned edges freed. */
+export declare function flushMargins(margin: PageGeometry["margin"], edges: readonly PinEdge[]): PageGeometry["margin"];
+/**
+ * The art-safe line's distance from the sheet edge on each pinned edge, in pt:
+ * the bleed plus `artSafe` on the top, bottom and outside edge, `gutter` on the
+ * binding edge (the left of a recto, the right of a verso), 0 on an edge the
+ * pins do not use (the pin box's edge is the text block's there). No print
+ * area means 0 everywhere: the paper's edge.
+ */
+export declare function pinInsets(area: Pick<PrintArea, "bleed" | "artSafe" | "gutter"> | null, side: PageSide, edges: readonly PinEdge[]): Record<PinEdge, number>;
+/** No padding of the root's own. */
+export declare const NO_PADDING: Readonly<Record<PinEdge, number>>;
+/**
+ * A pin root's own declarations for one side, in px (pt × 96/72, like the
+ * strip variables): the freed margins back as padding, cloned onto every
+ * fragment, and the four inset properties. `margin` is the ORIGINAL margin of
+ * the page context the root lands on; `padding` is the root's own (author)
+ * padding in px, which the freed margin is added to rather than replacing,
+ * so a padded root's text stays put too. All four properties are set, so a
+ * pin never reads another root's values.
+ */
+export declare function pinRootStyle(margin: PageGeometry["margin"], area: Pick<PrintArea, "bleed" | "artSafe" | "gutter"> | null, side: PageSide, edges: readonly PinEdge[], padding?: Readonly<Record<PinEdge, number>>): Record<string, string>;
+/** A computed style's four paddings, in px. */
+export declare function paddingOf(cs: {
+    paddingTop: string;
+    paddingRight: string;
+    paddingBottom: string;
+    paddingLeft: string;
+}): Record<PinEdge, number>;
+/**
+ * Margin boxes that live (wholly or partly) in a freed edge's margin area —
+ * the set both renderers must keep painting themselves. A corner box belongs
+ * to BOTH of its edges: `bottom-left-corner` dies when either the bottom or
+ * the left margin is freed.
+ */
+export declare function marginBoxesOnEdges(edges: readonly PinEdge[]): string[];
+export {};