gutterpress 0.11.20-alpha.2 → 0.11.20-alpha.4

package/dist/cli-sth219v1.js

@@ -0,0 +1,418 @@
+// src/lib/pdf-inspect.ts
+import { stat, readFile } from "node:fs/promises";
+import { getDocumentProxy } from "unpdf";
+import * as pdfjs from "unpdf/pdfjs";
+function getOps(mod) {
+  if ("OPS" in mod && mod.OPS && typeof mod.OPS === "object") {
+    return mod.OPS;
+  }
+  throw new Error("unpdf/pdfjs missing OPS export");
+}
+var OPS = getOps(pdfjs);
+var docCache = new Map;
+var DOC_CACHE_MAX = 8;
+function destroyEntry(entry) {
+  entry.doc.then((d) => d.destroy()).catch(() => {});
+}
+var EVICT_DESTROY_GRACE_MS = 60000;
+var gracePending = new Map;
+function destroyEntryAfterGrace(entry) {
+  const t = setTimeout(() => {
+    gracePending.delete(t);
+    destroyEntry(entry);
+  }, EVICT_DESTROY_GRACE_MS);
+  t.unref?.();
+  gracePending.set(t, entry);
+}
+function evictLru() {
+  while (docCache.size > DOC_CACHE_MAX) {
+    const oldestKey = docCache.keys().next().value;
+    if (oldestKey === undefined)
+      break;
+    const evicted = docCache.get(oldestKey);
+    docCache.delete(oldestKey);
+    if (evicted)
+      destroyEntryAfterGrace(evicted);
+  }
+}
+async function loadPdf(path) {
+  let st;
+  try {
+    st = await stat(path);
+  } catch {
+    return null;
+  }
+  const hit = docCache.get(path);
+  if (hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size) {
+    docCache.delete(path);
+    docCache.set(path, hit);
+    try {
+      return await hit.doc;
+    } catch {
+      return null;
+    }
+  }
+  if (hit)
+    destroyEntry(hit);
+  const docPromise = readFile(path).then((buf) => getDocumentProxy(new Uint8Array(buf)));
+  docCache.delete(path);
+  docCache.set(path, { mtimeMs: st.mtimeMs, size: st.size, doc: docPromise });
+  evictLru();
+  try {
+    return await docPromise;
+  } catch {
+    if (docCache.get(path)?.doc === docPromise)
+      docCache.delete(path);
+    return null;
+  }
+}
+var activeRetains = 0;
+function retainPdfCache() {
+  activeRetains++;
+  let released = false;
+  return () => {
+    if (released)
+      return;
+    released = true;
+    activeRetains--;
+    if (activeRetains === 0)
+      clearPdfCache();
+  };
+}
+function clearPdfCache() {
+  for (const [t, entry] of gracePending) {
+    clearTimeout(t);
+    destroyEntry(entry);
+  }
+  gracePending.clear();
+  for (const entry of docCache.values())
+    destroyEntry(entry);
+  docCache.clear();
+}
+function pendingGraceDestroyCount() {
+  return gracePending.size;
+}
+function getPageSize(page) {
+  const vp = page.getViewport({ scale: 1 });
+  return { w: vp.width, h: vp.height };
+}
+async function getOutlineCount(doc) {
+  try {
+    const outline = await doc.getOutline();
+    return outline ? outline.length : 0;
+  } catch {
+    return 0;
+  }
+}
+async function getPageLabels(doc) {
+  try {
+    return await doc.getPageLabels();
+  } catch {
+    return null;
+  }
+}
+async function countLinkAnnotations(doc, stopAtFirst = false) {
+  let count = 0;
+  for (let i = 1;i <= doc.numPages; i++) {
+    try {
+      const page = await doc.getPage(i);
+      const annots = await page.getAnnotations();
+      for (const a of annots) {
+        if (a.subtype === "Link") {
+          count++;
+          if (stopAtFirst)
+            return count;
+        }
+      }
+    } catch {}
+  }
+  return count;
+}
+var textCache = new WeakMap;
+function getTextPass(doc) {
+  let p = textCache.get(doc);
+  if (!p) {
+    p = (async () => {
+      const textByPage = [];
+      const positions = [];
+      const runsByPage = [];
+      for (let i = 1;i <= doc.numPages; i++) {
+        try {
+          const page = await doc.getPage(i);
+          const tc = await page.getTextContent();
+          let pageText = "";
+          const runs = [];
+          for (const item of tc.items) {
+            const it = item;
+            if (typeof it.str !== "string")
+              continue;
+            pageText += it.str;
+            if (it.transform && it.str.trim().length > 0) {
+              const x = it.transform[4];
+              const y = it.transform[5];
+              positions.push({ x, y });
+              runs.push({ s: it.str, x, y, w: it.width ?? 0, h: it.height ?? 0 });
+            }
+          }
+          textByPage.push(pageText);
+          runsByPage.push(runs);
+        } catch {
+          textByPage.push("");
+          runsByPage.push([]);
+        }
+      }
+      return { textByPage, positions, runsByPage };
+    })();
+    textCache.set(doc, p);
+  }
+  return p;
+}
+var opCache = new WeakMap;
+function multiply(m1, m2) {
+  return [
+    m1[0] * m2[0] + m1[2] * m2[1],
+    m1[1] * m2[0] + m1[3] * m2[1],
+    m1[0] * m2[2] + m1[2] * m2[3],
+    m1[1] * m2[2] + m1[3] * m2[3],
+    m1[0] * m2[4] + m1[2] * m2[5] + m1[4],
+    m1[1] * m2[4] + m1[3] * m2[5] + m1[5]
+  ];
+}
+function fontIsEmbedded(f) {
+  if (f.isType3Font)
+    return true;
+  if (f.missingFile === true)
+    return false;
+  if (f.isStandardFont === true)
+    return false;
+  return true;
+}
+function getOpPass(doc) {
+  let p = opCache.get(doc);
+  if (!p) {
+    p = (async () => {
+      const imagesByPage = new Map;
+      const fonts = [];
+      const seenFonts = new Set;
+      for (let i = 1;i <= doc.numPages; i++) {
+        let page;
+        try {
+          page = await doc.getPage(i);
+        } catch {
+          continue;
+        }
+        let ops;
+        try {
+          ops = await page.getOperatorList();
+        } catch {
+          continue;
+        }
+        let ctm = [1, 0, 0, 1, 0, 0];
+        const stack = [];
+        const pageImages = [];
+        for (let j = 0;j < ops.fnArray.length; j++) {
+          const fn = ops.fnArray[j];
+          const args = ops.argsArray[j];
+          if (fn === OPS.save) {
+            stack.push(ctm.slice());
+          } else if (fn === OPS.restore) {
+            ctm = stack.pop() ?? ctm;
+          } else if (fn === OPS.transform) {
+            ctm = multiply(ctm, args);
+          } else if (fn === OPS.paintImageXObject || fn === OPS.paintImageXObjectRepeat || fn === OPS.paintInlineImageXObject) {
+            const name = typeof args[0] === "string" ? args[0] : "(inline)";
+            pageImages.push({
+              name,
+              placedW: Math.hypot(ctm[0], ctm[1]),
+              placedH: Math.hypot(ctm[2], ctm[3]),
+              x: ctm[4],
+              y: ctm[5],
+              page: i
+            });
+          } else if (fn === OPS.setFont) {
+            const ref = args[0];
+            if (typeof ref === "string" && !seenFonts.has(ref)) {
+              seenFonts.add(ref);
+              try {
+                if (page.commonObjs.has(ref)) {
+                  const f = page.commonObjs.get(ref);
+                  fonts.push({
+                    name: f?.name ?? ref,
+                    embedded: fontIsEmbedded(f ?? {})
+                  });
+                }
+              } catch {}
+            }
+          }
+        }
+        if (pageImages.length > 0)
+          imagesByPage.set(i, pageImages);
+      }
+      return { imagesByPage, fonts };
+    })();
+    opCache.set(doc, p);
+  }
+  return p;
+}
+var opSet = (names) => new Set(names.map((name) => OPS[name]).filter((op) => op !== undefined));
+var FILL_COLOR_OPS = opSet(["setFillGray", "setFillRGBColor", "setFillCMYKColor", "setFillColor"]);
+var STROKE_COLOR_OPS = opSet(["setStrokeGray", "setStrokeRGBColor", "setStrokeCMYKColor", "setStrokeColor"]);
+var SHOW_TEXT_OPS = opSet(["showText", "showSpacedText", "nextLineShowText", "nextLineSetSpacingShowText"]);
+async function unsplittableTextReasons(pdfBytes, pages) {
+  const GSTATE_BIT = { ca: 1, CA: 2, BM: 4, SMask: 8 };
+  const COMPOSITING = 15;
+  const FILL_PATTERN = 16;
+  const STROKE_PATTERN = 32;
+  const CLIP_TEXT = 64;
+  const doc = await getDocumentProxy(new Uint8Array(pdfBytes));
+  const reasons = new Map;
+  try {
+    const scan = pages ?? Array.from({ length: doc.numPages }, (_, i) => i + 1);
+    for (const i of scan) {
+      const page = await doc.getPage(i);
+      const ops = await page.getOperatorList();
+      let state = 0;
+      const groups = [];
+      const stack = [];
+      let showsText = false;
+      for (let j = 0;j < ops.fnArray.length; j++) {
+        const fn = ops.fnArray[j];
+        if (fn === OPS.save || fn === OPS.paintFormXObjectBegin)
+          stack.push(state);
+        else if (fn === OPS.restore || fn === OPS.paintFormXObjectEnd)
+          state = stack.pop() ?? 0;
+        else if (fn === OPS.beginGroup) {
+          const group = ops.argsArray[j][0];
+          groups.push((state & COMPOSITING) !== 0 || !!(group.smask || group.knockout));
+        } else if (fn === OPS.endGroup)
+          groups.pop();
+        else if (fn === OPS.setFont) {
+          const ref = ops.argsArray[j][0];
+          const font = typeof ref === "string" && page.commonObjs.has(ref) ? page.commonObjs.get(ref) : undefined;
+          if (font?.isType3Font) {
+            reasons.set(i, "type3-font");
+            break;
+          }
+        } else if (fn === OPS.setFillColorN || fn === OPS.setStrokeColorN) {
+          const bit = fn === OPS.setFillColorN ? FILL_PATTERN : STROKE_PATTERN;
+          const kind = ops.argsArray[j][0];
+          state = kind === "TilingPattern" || kind === "Shading" ? state | bit : state & ~bit;
+        } else if (FILL_COLOR_OPS.has(fn))
+          state &= ~FILL_PATTERN;
+        else if (STROKE_COLOR_OPS.has(fn))
+          state &= ~STROKE_PATTERN;
+        else if (fn === OPS.setTextRenderingMode) {
+          state = ops.argsArray[j][0] >= 4 ? state | CLIP_TEXT : state & ~CLIP_TEXT;
+        } else if (fn === OPS.setGState) {
+          for (const [key, value] of ops.argsArray[j][0]) {
+            const bit = GSTATE_BIT[key];
+            if (!bit)
+              continue;
+            const on = key === "BM" ? value !== "source-over" : key === "SMask" ? !!value : value < 1;
+            state = on ? state | bit : state & ~bit;
+          }
+        } else if (SHOW_TEXT_OPS.has(fn)) {
+          showsText = true;
+          if (state || groups.includes(true)) {
+            const paint = state & (FILL_PATTERN | STROKE_PATTERN | CLIP_TEXT);
+            reasons.set(i, paint ? "text-pattern-or-clip" : "text-transparency");
+            break;
+          }
+        }
+      }
+      if (!showsText && !reasons.has(i))
+        reasons.set(i, "no-text");
+    }
+  } finally {
+    await doc.destroy();
+  }
+  return reasons;
+}
+function getImagePixelSize(page, name, timeoutMs = 2000) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (v) => {
+      if (!done) {
+        done = true;
+        resolve(v);
+      }
+    };
+    const t = setTimeout(() => finish(null), timeoutMs);
+    try {
+      page.objs.get(name, (obj) => {
+        clearTimeout(t);
+        finish(obj && obj.width && obj.height ? { width: obj.width, height: obj.height } : null);
+      });
+    } catch {
+      clearTimeout(t);
+      finish(null);
+    }
+  });
+}
+var PAINT_OPS = new Set([
+  "stroke",
+  "closeStroke",
+  "fill",
+  "eoFill",
+  "fillStroke",
+  "eoFillStroke",
+  "closeFillStroke",
+  "closeEOFillStroke",
+  "shadingFill",
+  "paintImageXObject",
+  "paintInlineImageXObject",
+  "paintImageXObjectRepeat",
+  "paintImageMaskXObject",
+  "paintImageMaskXObjectGroup",
+  "paintImageMaskXObjectRepeat",
+  "paintSolidColorImageMask",
+  "showText",
+  "showSpacedText",
+  "nextLineShowText",
+  "nextLineSetSpacingShowText"
+].map((name) => OPS[name]).filter((op) => op !== undefined));
+async function pageHasMarks(doc, pageNum) {
+  const ops = await (await doc.getPage(pageNum)).getOperatorList();
+  return ops.fnArray.some((fn, i) => fn === OPS.constructPath ? PAINT_OPS.has(ops.argsArray[i][0]) : PAINT_OPS.has(fn));
+}
+async function getImageResolutions(doc) {
+  const { imagesByPage } = await getOpPass(doc);
+  const out = [];
+  for (const [pageNum, imgs] of imagesByPage) {
+    let page;
+    try {
+      page = await doc.getPage(pageNum);
+    } catch {
+      continue;
+    }
+    for (const img of imgs) {
+      if (img.name === "(inline)")
+        continue;
+      const px = await getImagePixelSize(page, img.name);
+      if (!px)
+        continue;
+      const placedWin = img.placedW / 72;
+      const placedHin = img.placedH / 72;
+      if (placedWin <= 0 || placedHin <= 0)
+        continue;
+      out.push({
+        page: pageNum,
+        xDpi: px.width / placedWin,
+        yDpi: px.height / placedHin
+      });
+    }
+  }
+  return out;
+}
+async function isLoadable(doc) {
+  try {
+    for (let i = 1;i <= doc.numPages; i++) {
+      await doc.getPage(i);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export { DOC_CACHE_MAX, loadPdf, retainPdfCache, clearPdfCache, pendingGraceDestroyCount, getPageSize, getOutlineCount, getPageLabels, countLinkAnnotations, getTextPass, getOpPass, unsplittableTextReasons, pageHasMarks, getImageResolutions, isLoadable };

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   UsageError,
   package_default,
   rejectUnknownFlags
-} from "./cli-7z29z4wz.js";
+} from "./cli-fmksazej.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-ftd4fec4.js").then((m) => m.default),
-  preview: () => import("./preview-q76xn95h.js").then((m) => m.default),
-  build: () => import("./build-qmjg9r2d.js").then((m) => m.default),
-  publish: () => import("./publish-7gdy6gbf.js").then((m) => m.default),
-  validate: () => import("./validate-e3ryegce.js").then((m) => m.default),
-  preflight: () => import("./preflight-8sqarcsr.js").then((m) => m.default),
-  doctor: () => import("./doctor-fe7tcs4v.js").then((m) => m.default),
-  ext: () => import("./ext-ahwxt6gv.js").then((m) => m.default)
+  new: () => import("./new-s4f0tnya.js").then((m) => m.default),
+  preview: () => import("./preview-j91sxadd.js").then((m) => m.default),
+  build: () => import("./build-epdcrm2c.js").then((m) => m.default),
+  publish: () => import("./publish-f12xaenm.js").then((m) => m.default),
+  validate: () => import("./validate-pb5gysvr.js").then((m) => m.default),
+  preflight: () => import("./preflight-7ck4rbsq.js").then((m) => m.default),
+  doctor: () => import("./doctor-78es5scm.js").then((m) => m.default),
+  ext: () => import("./ext-9mc7sr0d.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-ftd4fec4.js");
+      const { newArgs } = await import("./new-s4f0tnya.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-8sqarcsr.js");
+      const { preflightArgs } = await import("./preflight-7ck4rbsq.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-ahwxt6gv.js");
+      const { EXT_SUBCOMMANDS, extAddArgs, extRemoveArgs, extEnableArgs, extDisableArgs } = await import("./ext-9mc7sr0d.js");
       if (!EXT_SUBCOMMANDS.includes(subcommand)) {
         throw new UsageError(`gutterpress ext: unknown command "${subcommand}"`);
       }

package/dist/{doctor-fe7tcs4v.js → doctor-78es5scm.js}

@@ -1,12 +1,12 @@
 import {
   getSystemDiagnostics,
   log
-} from "./cli-gh0ym80r.js";
+} from "./cli-h4tfmpg3.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-7z29z4wz.js";
+} from "./cli-fmksazej.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.safe` (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 warns).
+ *     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, `safe` 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" | "safe" | "artSafe"> | 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" | "safe" | "artSafe"> | 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 {};