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

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   UsageError,
   package_default,
   rejectUnknownFlags
-} from "./cli-hn9pk0hp.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-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-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-8yah8z91.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-8ccx4kdc.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-pesyrs68.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-wbjkrcpc.js → doctor-78es5scm.js}

@@ -1,12 +1,12 @@
 import {
   getSystemDiagnostics,
   log
-} from "./cli-y9bcya7r.js";
+} from "./cli-h4tfmpg3.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-hn9pk0hp.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 {};

package/dist/engine/shared/print-area.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The project's print area: the manifest's `page` block, carried into every
+ * assembled book (preview, build, publish) as ONE
+ * `<meta name="gp-print-area">` by the markdown assembly
+ * (lib/markdown/assemble.ts) and read back here by everything that needs it:
+ * the preview's print overlays (viewer/overlay.ts) and both engines' pinned
+ * art (pin-edges.ts — a pin sits on the printer's art-safe line).
+ *
+ * Only the manifest feeds it — `page.width` x `page.height` (the sheet),
+ * `page.bleed` (a bleed the sheet already contains on the top, bottom and
+ * OUTER edge; the binding edge has none, as DriveThruRPG cuts it),
+ * `page.safe` (the TEXT rule: its inset from the trim on every edge) and
+ * `page.artSafe` (the ART rule: its inset on the top, bottom and outer edge,
+ * while the binding edge takes `safe`; absent = `safe`) — plus the preset's
+ * id and the printer spec it follows, which only word what the overlay finds.
+ * No book or plugin CSS feeds it: not the `@page` margins (they are where the
+ * author put the TEXT, which is not the printer's safe area), not
+ * `@page { bleed }`.
+ *
+ * The meta is metadata: it changes nothing a browser renders on its own.
+ * Node-safe: the writer is pure, and the reader takes the document it reads.
+ */
+/** The project's page geometry, in pt — the manifest's `page` block. */
+export interface PrintArea {
+    width: number;
+    height: number;
+    /** in-sheet bleed on the top, bottom and outer edge; 0 = none */
+    bleed: number;
+    /** the TEXT rule: inset from the trim on every edge; 0 = none */
+    safe: number;
+    /** the ART rule: inset on the top, bottom and outer edge (the binding edge takes `safe`) */
+    artSafe: number;
+    /** the manifest's preset id, and the printer spec it follows: they only word what is found */
+    preset?: string;
+    spec?: {
+        label: string;
+        url: string;
+    };
+}
+/** Which side of the spread a page is: page 1 is a recto, so every odd page is one. */
+export type PageSide = "recto" | "verso";
+/** What a host knows from its resolved config: the `page` block, the preset and its spec. */
+export interface PrintAreaSource {
+    width: number;
+    height: number;
+    bleed?: number;
+    safe?: number;
+    artSafe?: number;
+    preset?: string;
+    spec?: {
+        label: string;
+        url: string;
+    };
+}
+/**
+ * The `<meta>` tag for one book. An unset bleed or text rule is written as 0,
+ * never left out; an unset art rule stays out (the reader takes it as `safe`).
+ * Anything else the config's `page` block holds (`tolerance`) is not part of it.
+ */
+export declare function printAreaMeta(page: PrintAreaSource): string;
+/** The one DOM call the reader makes: a `Document` satisfies it. */
+export interface MetaDocument {
+    querySelector(selector: string): {
+        getAttribute(name: string): string | null;
+    } | null;
+}
+/** The book's print area from its `<meta name="gp-print-area">`; `null` without one. */
+export declare function printAreaFromMeta(doc: MetaDocument): PrintArea | null;

package/dist/{engine-yxnnp3hx.js → engine-67f68bxs.js}

@@ -1,6 +1,6 @@
 import {
   build
-} from "./cli-x4p99w8d.js";
+} from "./cli-61vd4ews.js";
 import {
   BuildError
 } from "./cli-46ycxe6r.js";

package/dist/{engine-fdtv01a2.js → engine-7ha27n2b.js}

@@ -1,9 +1,9 @@
 import {
   build
-} from "./index-r87y7wzw.js";
+} from "./index-ad95fws8.js";
 import {
   BuildError
-} from "./index-zagagnwq.js";
+} from "./index-gm5xbx5w.js";
 import"./index-bt0qws5c.js";
 import"./index-37x76zdn.js";
 

package/dist/{ext-pesyrs68.js → ext-9mc7sr0d.js}

@@ -12,17 +12,17 @@ import {
   searchNpmExtensions,
   setExtensionEnabled,
   updateExtensions
-} from "./cli-9k2tb493.js";
-import"./cli-y9bcya7r.js";
+} from "./cli-0ey902sx.js";
+import"./cli-h4tfmpg3.js";
 import {
   UsageError,
   exitForUsage,
   rejectExtraPositionals,
   rejectUnknownFlags,
   resolveProjectDir
-} from "./cli-hn9pk0hp.js";
+} from "./cli-fmksazej.js";
 import"./cli-ht1bcqdd.js";
-import"./cli-x4p99w8d.js";
+import"./cli-61vd4ews.js";
 import {
   EXIT_CODES
 } from "./cli-46ycxe6r.js";

package/dist/{gutterpress-agent-cazqstr1.js → gutterpress-agent-mrdnwktc.js}

@@ -43,11 +43,13 @@
     xrefSites: () => xrefSites,
     targetTexts: () => targetTexts,
     stringSources: () => stringSources,
+    setPinGeometry: () => setPinGeometry,
+    setPinFurniture: () => setPinFurniture,
     setGenerated: () => setGenerated,
-    setFlushFurniture: () => setFlushFurniture,
+    printArea: () => printArea,
+    pinRoots: () => pinRoots,
     instrument: () => instrument,
     forcedBreakSites: () => forcedBreakSites,
-    flushRoots: () => flushRoots,
     fillLeaders: () => fillLeaders,
     counterResetSites: () => counterResetSites,
     collectCss: () => collectCss,
@@ -302,6 +304,51 @@
     return evaluateContent(parseContent(value), ctx);
   }
 
+  // src/engine/shared/pin-edges.ts
+  var PIN_EDGES = ["top", "right", "bottom", "left"];
+  var EDGE_PIN_SELECTOR = PIN_EDGES.map((edge) => `.gp-pin.gp-${edge}`).join(", ");
+  function pinEdgesIn(root) {
+    const pins = Array.from(root.querySelectorAll(EDGE_PIN_SELECTOR)).filter((pin) => pin.offsetParent === root);
+    return PIN_EDGES.filter((edge) => pins.some((pin) => pin.classList.contains(`gp-${edge}`)));
+  }
+  function pinKey(edges) {
+    return PIN_EDGES.filter((e) => edges.includes(e)).map((e) => e[0]).join("");
+  }
+  function paddingOf(cs) {
+    return {
+      top: parseFloat(cs.paddingTop) || 0,
+      right: parseFloat(cs.paddingRight) || 0,
+      bottom: parseFloat(cs.paddingBottom) || 0,
+      left: parseFloat(cs.paddingLeft) || 0
+    };
+  }
+
+  // src/engine/shared/print-area.ts
+  function printAreaFromMeta(doc) {
+    const raw = doc.querySelector('meta[name="gp-print-area"]')?.getAttribute("content");
+    if (!raw)
+      return null;
+    try {
+      const v = JSON.parse(raw);
+      const n = (x) => typeof x === "number" && Number.isFinite(x) && x > 0 ? x : 0;
+      if (!n(v.width) || !n(v.height))
+        return null;
+      const safe = n(v.safe);
+      const spec = v.spec && typeof v.spec.label === "string" && typeof v.spec.url === "string" && /^https?:\/\//i.test(v.spec.url) ? v.spec : undefined;
+      return {
+        width: n(v.width),
+        height: n(v.height),
+        bleed: n(v.bleed),
+        safe,
+        artSafe: typeof v.artSafe === "number" ? n(v.artSafe) : safe,
+        preset: typeof v.preset === "string" ? v.preset : undefined,
+        spec
+      };
+    } catch {
+      return null;
+    }
+  }
+
   // src/engine/compiler/agent.ts
   var uid = 0;
   function ensureAnchor(el) {
@@ -559,29 +606,45 @@
     addCss("gp-generated-content", css);
     return entries.length;
   }
-  function flushRoots() {
+  function pinRoots() {
     const out = [];
     for (const root of Array.from(document.querySelectorAll(".page, .spread"))) {
-      const edges = ["top", "right", "bottom", "left"].filter((edge) => root.querySelector(`.gp-pin.gp-flush.gp-${edge}`));
+      const edges = pinEdgesIn(root);
       if (!edges.length)
         continue;
-      const page = getComputedStyle(root).page;
-      const key = `${page === "auto" ? "" : page}|${edges.map((e) => e[0]).join("")}`;
-      root.dataset.gpFlush = key;
-      out.push({ id: ensureAnchor(root), page, edges, key });
+      const cs = getComputedStyle(root);
+      const padding = paddingOf(cs);
+      const key = `${cs.page === "auto" ? "" : cs.page}|${pinKey(edges)}|${edges.map((e) => padding[e]).join(",")}`;
+      root.dataset.gpPin = key;
+      out.push({ id: ensureAnchor(root), page: cs.page, edges, padding, key });
     }
     return out;
   }
-  function setFlushFurniture(items) {
+  function printArea() {
+    return printAreaFromMeta(document);
+  }
+  function setPinGeometry(items) {
+    let set = 0;
+    for (const item of items) {
+      const host = anchorHost(item.id);
+      if (!host)
+        continue;
+      for (const [prop, value] of Object.entries(item.style))
+        host.style.setProperty(prop, value);
+      set++;
+    }
+    return set;
+  }
+  function setPinFurniture(items) {
     let painted = 0;
     for (const item of items) {
       const host = anchorHost(item.id);
       if (!host)
         continue;
-      let layer = host.querySelector(":scope > .gp-flush-furniture");
+      let layer = host.querySelector(":scope > .gp-pin-furniture");
       if (!layer) {
         layer = document.createElement("div");
-        layer.className = "gp-flush-furniture";
+        layer.className = "gp-pin-furniture";
         layer.setAttribute("aria-hidden", "true");
         layer.setAttribute("style", "position:absolute;inset:0;pointer-events:none;z-index:10;");
         host.appendChild(layer);
@@ -616,8 +679,10 @@
     instrument,
     addCss,
     setGenerated,
-    flushRoots,
-    setFlushFurniture
+    pinRoots,
+    printArea,
+    setPinGeometry,
+    setPinFurniture
   };
   if (typeof window !== "undefined")
     window.__gp = api;