gutterpress 0.11.20-alpha.3 → 0.11.20-alpha.4

package/dist/{index-tjvrchxj.js → index-t13p8y08.js}

@@ -9,7 +9,7 @@ import {
   getAssetsDir,
   lastPageMode,
   parseSize
-} from "./index-zagagnwq.js";
+} from "./index-gm5xbx5w.js";
 import {
   countLinkAnnotations,
   getImageResolutions,
@@ -1989,7 +1989,9 @@ var GUTTERPRESS_CSS = `
    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-large { width: 60%; max-width: 100%; }
+.gp-xl { width: 80%; max-width: 100%; }
+.gp-xxl { 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
@@ -2047,10 +2049,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;
@@ -2065,6 +2073,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) */
@@ -2174,6 +2192,8 @@ var GP_CLASSES = new Set([
   "gp-small",
   "gp-medium",
   "gp-large",
+  "gp-xl",
+  "gp-xxl",
   "gp-tight",
   "gp-loose",
   "gp-columns",
@@ -2190,6 +2210,7 @@ var GP_CLASSES = new Set([
   "gp-pin",
   "gp-top",
   "gp-bottom",
+  "gp-flush",
   "gp-behind",
   "gp-base",
   "gp-raised",
@@ -2203,8 +2224,7 @@ var GP_CLASSES = new Set([
   "gp-alert-caution",
   "gp-page-break",
   "gp-column-break",
-  "gp-continued",
-  "gp-flush"
+  "gp-continued"
 ]);
 
 // src/lib/markdown/table-align.ts
@@ -2331,6 +2351,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);
+}
 function elementNameFor(token) {
   switch (token.type) {
     case "layout_chapter_open":
@@ -2390,6 +2425,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);
         }
       }
     }
@@ -3141,6 +3177,20 @@ function layerSlug(name) {
   return /^[a-z]/.test(slug) ? slug : `x${slug}`;
 }
 
+// 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,
+    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";
@@ -3206,7 +3256,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}
@@ -3663,6 +3714,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,
@@ -3675,6 +3727,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,
@@ -3756,6 +3809,118 @@ function resolveDeclaredStyles(rawStyles, baseDir, subject) {
 // src/lib/extension-manifest.ts
 import { readFile as readFile4 } from "node:fs/promises";
 import path3 from "node:path";
+import { satisfies, validRange } from "semver";
+// package.json
+var package_default = {
+  name: "gutterpress",
+  version: "0.11.20-alpha.4",
+  description: "Markdown-to-PDF converter for professional print layout using a native Chromium print engine and Ghostscript.",
+  author: "itlackey",
+  license: "MPL-2.0",
+  keywords: [
+    "markdown",
+    "pdf",
+    "print",
+    "ghostscript",
+    "book",
+    "publishing",
+    "zine"
+  ],
+  repository: {
+    type: "git",
+    url: "https://github.com/dimm-city/gutterpress.git"
+  },
+  homepage: "https://github.com/dimm-city/gutterpress#readme",
+  bugs: {
+    url: "https://github.com/dimm-city/gutterpress/issues"
+  },
+  type: "module",
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  bin: {
+    gutterpress: "./dist/cli.js"
+  },
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      default: "./dist/index.js"
+    },
+    "./api": {
+      types: "./dist/api/index.d.ts",
+      default: "./dist/api/index.js"
+    },
+    "./render": {
+      types: "./dist/render.d.ts",
+      default: "./dist/render.js"
+    }
+  },
+  files: [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  scripts: {
+    "build:library": "bun scripts/build-engine-bundles.mjs && rimraf dist && bun build src/index.ts src/api/index.ts --target=node --packages=external --splitting --outdir=dist && bun build src/render.ts --target=node --packages=external --outdir=dist && node scripts/check-render-pure.mjs && tsc -p tsconfig.build.json",
+    build: "bun run build:library && bun build src/cli.ts --target=node --packages=external --splitting --outdir=dist",
+    prepublishOnly: "bun run build",
+    test: "bun test",
+    typecheck: "tsc --noEmit",
+    "typecheck:engine-browser": "tsc --noEmit -p src/engine/browser.tsconfig.json",
+    "parity:gate": "bun scripts/native-parity-gate.ts"
+  },
+  engines: {
+    bun: ">=1.0.0",
+    node: ">=22.0.0"
+  },
+  dependencies: {
+    chokidar: "^5.0.0",
+    citty: "^0.2.0",
+    diff3: "0.0.3",
+    fflate: "0.8.3",
+    glob: "^13.0.0",
+    htmlhint: "^1.9.2",
+    ignore: "^5.3.2",
+    "isomorphic-git": "^1.38.4",
+    "markdown-it": "^14.3.2",
+    "markdown-it-abbr": "^2.0.0",
+    "markdown-it-attrs": "^4.3.0",
+    "markdown-it-deflist": "^3.0.1",
+    "markdown-it-footnote": "^4.0.0",
+    "markdown-it-mark": "^4.0.0",
+    "markdown-it-source-map": "^0.1.1",
+    "markdown-it-sub": "^2.0.0",
+    "markdown-it-sup": "^2.0.0",
+    markdownlint: "^0.40.0",
+    "pdf-lib": "^1.17.1",
+    postcss: "^8.5.18",
+    "resolve.exports": "2.0.3",
+    semver: "7.8.0",
+    tar: "7.5.22",
+    unpdf: "^1.6.2",
+    ws: "^8.21.0",
+    yaml: "^2.8.2"
+  },
+  devDependencies: {
+    "@types/bun": "1.3.14",
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^22.0.0",
+    "@types/semver": "^7.7.1",
+    "@types/ws": "^8.5.13",
+    playwright: "^1.60.0",
+    rimraf: "^6.0.0",
+    typescript: "^5"
+  }
+};
+
+// src/lib/version.ts
+var PACKAGE_META = {
+  version: package_default.version ?? "unknown",
+  dependencies: package_default.dependencies ?? {},
+  devDependencies: package_default.devDependencies ?? {}
+};
+var PACKAGE_VERSION = PACKAGE_META.version;
+
+// src/lib/extension-manifest.ts
 var EXTENSION_MANIFEST_FILENAME = "package.json";
 var GUTTERPRESS_KEY = "gutterpress";
 function object(value) {
@@ -3779,6 +3944,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) } : {},
@@ -3815,6 +3981,17 @@ function extensionCarries(meta) {
 function pathEscapesFolder(rel) {
   return path3.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`.");
@@ -4103,6 +4280,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;
@@ -4177,6 +4355,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.");
@@ -4307,7 +4486,7 @@ import path5 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/npm-registry.ts
 var DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
@@ -4515,7 +4694,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)) {
@@ -4733,7 +4912,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) {
@@ -6140,117 +6319,6 @@ import { mkdir as mkdir5, readFile as readFile10, writeFile as writeFile4 } from
 import { createHash as createHash3 } from "node:crypto";
 import path10 from "node:path";
 import git from "isomorphic-git";
-// package.json
-var package_default = {
-  name: "gutterpress",
-  version: "0.11.20-alpha.3",
-  description: "Markdown-to-PDF converter for professional print layout using a native Chromium print engine and Ghostscript.",
-  author: "itlackey",
-  license: "MPL-2.0",
-  keywords: [
-    "markdown",
-    "pdf",
-    "print",
-    "ghostscript",
-    "book",
-    "publishing",
-    "zine"
-  ],
-  repository: {
-    type: "git",
-    url: "https://github.com/dimm-city/gutterpress.git"
-  },
-  homepage: "https://github.com/dimm-city/gutterpress#readme",
-  bugs: {
-    url: "https://github.com/dimm-city/gutterpress/issues"
-  },
-  type: "module",
-  main: "./dist/index.js",
-  types: "./dist/index.d.ts",
-  bin: {
-    gutterpress: "./dist/cli.js"
-  },
-  exports: {
-    ".": {
-      types: "./dist/index.d.ts",
-      default: "./dist/index.js"
-    },
-    "./api": {
-      types: "./dist/api/index.d.ts",
-      default: "./dist/api/index.js"
-    },
-    "./render": {
-      types: "./dist/render.d.ts",
-      default: "./dist/render.js"
-    }
-  },
-  files: [
-    "dist/",
-    "README.md",
-    "LICENSE"
-  ],
-  scripts: {
-    "build:library": "bun scripts/build-engine-bundles.mjs && rimraf dist && bun build src/index.ts src/api/index.ts --target=node --packages=external --splitting --outdir=dist && bun build src/render.ts --target=node --packages=external --outdir=dist && node scripts/check-render-pure.mjs && tsc -p tsconfig.build.json",
-    build: "bun run build:library && bun build src/cli.ts --target=node --packages=external --splitting --outdir=dist",
-    prepublishOnly: "bun run build",
-    test: "bun test",
-    typecheck: "tsc --noEmit",
-    "typecheck:engine-browser": "tsc --noEmit -p src/engine/browser.tsconfig.json",
-    "parity:gate": "bun scripts/native-parity-gate.ts"
-  },
-  engines: {
-    bun: ">=1.0.0",
-    node: ">=22.0.0"
-  },
-  dependencies: {
-    chokidar: "^5.0.0",
-    citty: "^0.2.0",
-    diff3: "0.0.3",
-    fflate: "0.8.3",
-    glob: "^13.0.0",
-    htmlhint: "^1.9.2",
-    ignore: "^5.3.2",
-    "isomorphic-git": "^1.38.4",
-    "markdown-it": "^14.3.2",
-    "markdown-it-abbr": "^2.0.0",
-    "markdown-it-attrs": "^4.3.0",
-    "markdown-it-deflist": "^3.0.1",
-    "markdown-it-footnote": "^4.0.0",
-    "markdown-it-mark": "^4.0.0",
-    "markdown-it-source-map": "^0.1.1",
-    "markdown-it-sub": "^2.0.0",
-    "markdown-it-sup": "^2.0.0",
-    markdownlint: "^0.40.0",
-    "pdf-lib": "^1.17.1",
-    postcss: "^8.5.18",
-    "resolve.exports": "2.0.3",
-    semver: "7.8.0",
-    tar: "7.5.22",
-    unpdf: "^1.6.2",
-    ws: "^8.21.0",
-    yaml: "^2.8.2"
-  },
-  devDependencies: {
-    "@types/bun": "1.3.14",
-    "@types/markdown-it": "^14.1.2",
-    "@types/node": "^22.0.0",
-    "@types/semver": "^7.7.1",
-    "@types/ws": "^8.5.13",
-    playwright: "^1.60.0",
-    rimraf: "^6.0.0",
-    typescript: "^5"
-  }
-};
-
-// src/lib/version.ts
-var PACKAGE_META = {
-  version: package_default.version ?? "unknown",
-  dependencies: package_default.dependencies ?? {},
-  devDependencies: package_default.devDependencies ?? {}
-};
-var PACKAGE_VERSION = PACKAGE_META.version;
-
-// src/lib/build-fingerprint.ts
 var FINGERPRINT_FILENAME = "build-fingerprint.json";
 var VERSION_TIMEOUT_MS = 4000;
 function toJsonValue(value) {
@@ -10646,6 +10714,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,
@@ -10798,7 +10867,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-fdtv01a2.js");
+      const { buildNativePdf } = await import("./engine-7ha27n2b.js");
       const engineDiagnostics = await buildNativePdf(htmlFile, rawPdf, {
         title: config.title,
         author: config.authors.length > 0 ? config.authors.join(", ") : undefined,
@@ -11072,6 +11141,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,
@@ -11086,19 +11156,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>
 `;
@@ -11113,7 +11172,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)
@@ -11132,7 +11194,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/index.js

@@ -154,14 +154,14 @@ import {
   testRemoteAccess,
   updateExtensions,
   validateProjectExtensions
-} from "./index-tjvrchxj.js";
+} from "./index-t13p8y08.js";
 import"./index-ht1bcqdd.js";
 import {
   BUILD_DIAGNOSTIC_CODES
-} from "./index-r87y7wzw.js";
+} from "./index-ad95fws8.js";
 import {
   BuildError
-} from "./index-zagagnwq.js";
+} from "./index-gm5xbx5w.js";
 import"./index-sth219v1.js";
 import {
   DEFAULT_PRINT_OPTS,

package/dist/lib/extension-manifest.d.ts

@@ -70,6 +70,12 @@ export interface ExtensionMetadata {
      * does the merge.
      */
     snippets?: string;
+    /**
+     * npm `engines.gutterpress` — the Gutterpress versions the extension works
+     * with, as a semver range (e.g. `">=0.11.20-alpha.3"`). Checked when the
+     * extension loads ({@link assertSupportsThisGutterpress}).
+     */
+    gutterpressRange?: string;
     /**
      * The removed `engineStyles` field (#266), carried through from the
      * `gutterpress` block ONLY so {@link assertExtensionContained} can reject it
@@ -119,6 +125,13 @@ export declare function extensionCarries(meta: ExtensionMetadata): ExtensionCarr
  * doctrine {@link readExtensionMeta}'s tolerant JSON parse already follows).
  */
 export declare function pathEscapesFolder(rel: string): boolean;
+/**
+ * Refuse to load an extension whose `engines.gutterpress` range excludes this
+ * Gutterpress, so a book built with too old a version fails with the fix
+ * instead of quietly printing differently. Prereleases count: 0.12.0-alpha.1
+ * satisfies `>=0.11.20`.
+ */
+export declare function assertSupportsThisGutterpress(meta: ExtensionMetadata, ref: string): void;
 /**
  * Every path an extension declares must live INSIDE its own folder — an
  * extension is self-contained by contract (apply/install copies the whole

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

@@ -1,5 +1,6 @@
 import { type LoadedPlugin } from "./renderer";
 import { type PrintPadding } from "../../engine/shared/synthesis.ts";
+import { type PrintAreaSource } from "../../engine/shared/print-area.ts";
 /** Reader injected by the host: resolve a project-root-relative file → its text. */
 export type ReadText = (relPath: string) => Promise<string>;
 /**
@@ -9,8 +10,8 @@ export type ReadText = (relPath: string) => Promise<string>;
  * `type`s (`ambiguous_marker_token`, `unrecognized_marker_token`,
  * `extra_bare_marker_token`, `unknown_marker`, `nested_spread`,
  * `continue_without_section`, `spread_without_pages`, `spread_eof_close`,
- * `page_outside_spread`, `pin_outside_page`, `unknown_gp_class` — the last
- * emitted by `gp-pin-scope.js`'s `gp_pin_scope_check`, same as
+ * `page_outside_spread`, `pin_outside_page`, `unknown_gp_class`, `flush_art` —
+ * the last two emitted by `gp-pin-scope.js`'s `gp_pin_scope_check`, same as
  * `pin_outside_page`, see #226).
  *
  * #240 (declarative container components) adds three more, all emitted by
@@ -126,6 +127,15 @@ export interface AssembleBookHtmlOptions {
      * engine/shared/synthesis.ts) and the two page counts agree.
      */
     print?: PrintPadding;
+    /**
+     * The project's print area — the resolved manifest's `page` block plus its
+     * preset id and printer spec — written as `<meta name="gp-print-area">`
+     * (engine/shared/print-area.ts) into EVERY assembled book, preview, build
+     * and publish alike: the preview's print overlays judge the ink against it,
+     * and both engines place pinned art on its art-safe line. Metadata only:
+     * nothing renders from it but what reads it.
+     */
+    printArea?: PrintAreaSource;
     plugins?: LoadedPlugin[];
     pluginCss?: string;
     /** Add a layout-neutral source-file id to source-mapped preview blocks. */