gutterpress 0.10.5 → 0.10.6-beta.2

package/dist/lib/pdf-inspect.d.ts

@@ -77,7 +77,21 @@ export declare function getPageLabels(doc: PDFDocumentProxy): Promise<string[] |
  * for the boolean "are there any links?" question (TOC-links check).
  */
 export declare function countLinkAnnotations(doc: PDFDocumentProxy, stopAtFirst?: boolean): Promise<number>;
-interface TextPass {
+/** One non-whitespace text run's exact string plus its extents, in PDF points. */
+export interface TextRun {
+    /** Verbatim run string (never normalized/rounded) — pdf.js item `str`. */
+    s: string;
+    /** Baseline origin x — item `transform[4]`. */
+    x: number;
+    /** Baseline origin y — item `transform[5]`. */
+    y: number;
+    /** Advance width, "in device space" per pdf.js (points, at the unscaled
+     *  viewport this module always reads at — see getPageSize). */
+    w: number;
+    /** Glyph height, same space as `w`. */
+    h: number;
+}
+export interface TextPass {
     /** Non-whitespace-stripped text per page (index 0 = page 1). */
     textByPage: string[];
     /** Every text run's baseline origin, for layout-variance analysis. */
@@ -85,22 +99,37 @@ interface TextPass {
         x: number;
         y: number;
     }>;
+    /**
+     * Every non-whitespace text run's exact string + extents, per page (index
+     * 0 = page 1) — same filter as `positions` above (whitespace-only items
+     * excluded), plus the run's width/height. Added for the render-parity gate
+     * (render-parity.ts's `extractReport`); `textByPage`/`positions` are
+     * untouched and still hold their original values.
+     */
+    runsByPage: TextRun[][];
 }
 export declare function getTextPass(doc: PDFDocumentProxy): Promise<TextPass>;
-interface ImageRef {
+export interface ImageRef {
     /** XObject resource name (or "(inline)" for inline images). */
     name: string;
     /** Rendered width/height on the page, in points (from the CTM). */
     placedW: number;
     placedH: number;
+    /**
+     * Placed origin, in points — the CTM's translation components (`ctm[4]`,
+     * `ctm[5]`). Added for the render-parity gate (render-parity.ts); `name`/
+     * `placedW`/`placedH`/`page` are untouched.
+     */
+    x: number;
+    y: number;
     /** 1-based page number. */
     page: number;
 }
-interface FontRef {
+export interface FontRef {
     name: string;
     embedded: boolean;
 }
-interface OpPass {
+export interface OpPass {
     imagesByPage: Map<number, ImageRef[]>;
     fonts: FontRef[];
 }
@@ -120,4 +149,3 @@ export declare function getImageResolutions(doc: PDFDocumentProxy): Promise<Arra
  * catches PDFs that are actually broken/unparseable (ADR 0002).
  */
 export declare function isLoadable(doc: PDFDocumentProxy): Promise<boolean>;
-export {};

package/dist/lib/render-parity.d.ts

@@ -0,0 +1,108 @@
+/** Bumped only if the canonical report shape changes in a way old reports
+ *  cannot be compared against (e.g. a committed baseline in the book repo). */
+export declare const REPORT_VERSION = 1;
+export interface TextRunReport {
+    s: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface ImageReport {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface PageReport {
+    w: number;
+    h: number;
+    text: TextRunReport[];
+    images: ImageReport[];
+}
+export interface Report {
+    version: 1;
+    pageCount: number;
+    pages: PageReport[];
+}
+/**
+ * Extract the canonical parity report for one PDF. Keys are always written in
+ * the same order (`version`, `pageCount`, `pages`; each page `w`, `h`,
+ * `text`, `images`; each run/image field in the order declared above) so
+ * `serializeReport` produces byte-identical output for byte-identical input,
+ * and so a committed baseline report diffs sanely in git.
+ */
+export declare function extractReport(pdfPath: string): Promise<Report>;
+/**
+ * Fixed layout serialization: `JSON.stringify(report, null, 1)` plus a
+ * trailing newline. Two extractions of the same PDF are byte-identical
+ * strings — the acceptance test for this whole gate — because `extractReport`
+ * always builds the object in the same key order and every number is already
+ * rounded to 3 decimals before it gets here.
+ */
+export declare function serializeReport(report: Report): string;
+export type WaiverKind = "page-count" | "page-size" | "text" | "image";
+export interface Waiver {
+    /** 1-based page number. Omit for kind "page-count" (there is no page). */
+    page?: number;
+    kind: WaiverKind;
+    /** Optional substring the text run's string must contain. Only meaningful
+     *  for kind "text"; ignored for the other kinds. */
+    match?: string;
+    /** Non-empty, one line: why this diff is expected/acceptable. Required —
+     *  a waiver with no reason is a usage error, not a silent pass. */
+    reason: string;
+}
+export interface Diff {
+    /** 1-based page number. Absent for kind "page-count". */
+    page?: number;
+    kind: WaiverKind;
+    /** Index within the page's text/image array, when the diff is about one
+     *  run/image rather than the array's length. */
+    index?: number;
+    before: string;
+    after: string;
+    /** The base run's string, for kind "text" — what a waiver's `match` tests
+     *  against, and what a human reads to find the run in the source. */
+    text?: string;
+}
+export interface CompareOptions {
+    /** Points. Applies to text run and image extents (x/y/w/h). Default 0.5. */
+    tolerance?: number;
+    waivers?: Waiver[];
+}
+export interface CompareResult {
+    /** Diffs NOT excused by any waiver — non-empty means the gate fails. */
+    diffs: Diff[];
+    /** Diffs that were found but matched a waiver. */
+    waived: Diff[];
+    /** Waivers that matched nothing this run — stale, should be deleted. */
+    unusedWaivers: Waiver[];
+}
+/** A waiver failed validation (currently: missing/empty `reason`). The CLI
+ *  treats this as a usage error (exit 2), distinct from a real diff (exit 1). */
+export declare class WaiverValidationError extends Error {
+}
+/**
+ * Compare two reports. Throws {@link WaiverValidationError} (a usage error,
+ * not a diff) if any waiver is missing its reason — validated up front, before
+ * any comparison work, so a malformed waivers file never silently passes.
+ *
+ * Every waiver is matched against the FULL diff set (not a display-truncated
+ * one — see `formatDiffs` for the printed-output cap) so an unwaived diff
+ * past the cap still fails the gate, and a waiver is reported unused only
+ * when it genuinely excused nothing.
+ */
+export declare function compareReports(base: Report, cand: Report, options?: CompareOptions): CompareResult;
+/**
+ * Render a `CompareResult` as the lines the CLI prints: every unwaived diff
+ * (capped per page — see `MAX_LINES_PER_PAGE`), every waived diff (marked, so
+ * a reviewer can see what was excused without it counting as a failure),
+ * every unused waiver as a warning, and a final one-line summary — `CLEAN: N
+ * pages` or `DIFF: B vs C pages, N diff(s) (W waived), tolerance Tpt`.
+ */
+export declare function formatDiffs(result: CompareResult, info: {
+    basePageCount: number;
+    candPageCount: number;
+    tolerance: number;
+}): string[];

package/dist/{lint-wweg6pf0.js → lint-p5m5gn2f.js}

@@ -1,16 +1,16 @@
 import {
   MANIFEST_FILENAMES,
   runLint
-} from "./cli-chkwtg9m.js";
+} from "./cli-nde3d8wk.js";
 import {
   log
-} from "./cli-5pq315qe.js";
+} from "./cli-vntks53w.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-v031r2h6.js";
-import"./cli-0t4zfevc.js";
+} from "./cli-980t4qp9.js";
+import"./cli-bwbs3qm4.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/{new-yf8emyp3.js → new-cgnm1vz6.js}

@@ -5,16 +5,16 @@ import {
   TARGETS,
   TARGET_IDS,
   scaffoldProject
-} from "./cli-chkwtg9m.js";
+} from "./cli-nde3d8wk.js";
 import {
   resolveGhostscript
-} from "./cli-5pq315qe.js";
+} from "./cli-vntks53w.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-v031r2h6.js";
-import"./cli-0t4zfevc.js";
+} from "./cli-980t4qp9.js";
+import"./cli-bwbs3qm4.js";
 import {
   isToolAvailable
 } from "./cli-c41yr7he.js";

package/dist/{plugin-dj6crat4.js → plugin-2zwx1tex.js}

@@ -1,14 +1,14 @@
 import {
   addNpmPlugin,
   parseNpmPluginSpec
-} from "./cli-chkwtg9m.js";
-import"./cli-5pq315qe.js";
+} from "./cli-nde3d8wk.js";
+import"./cli-vntks53w.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-v031r2h6.js";
-import"./cli-0t4zfevc.js";
+} from "./cli-980t4qp9.js";
+import"./cli-bwbs3qm4.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/{preflight-d34pzgr6.js → preflight-gypyj54v.js}

@@ -2,16 +2,16 @@ import {
   executeValidation,
   publishTargetFor,
   reportMissingTools
-} from "./cli-chkwtg9m.js";
+} from "./cli-nde3d8wk.js";
 import {
   log
-} from "./cli-5pq315qe.js";
+} from "./cli-vntks53w.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-v031r2h6.js";
-import"./cli-0t4zfevc.js";
+} from "./cli-980t4qp9.js";
+import"./cli-bwbs3qm4.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/{preview-g2f5982y.js → preview-670h69jp.js}

@@ -6,10 +6,10 @@ import {
   runBuild,
   splitOutPath,
   startPreviewServer
-} from "./cli-chkwtg9m.js";
+} from "./cli-nde3d8wk.js";
 import {
   log
-} from "./cli-5pq315qe.js";
+} from "./cli-vntks53w.js";
 import {
   UsageError,
   parseEngine,
@@ -18,8 +18,8 @@ import {
   rejectExtraPositionals,
   rejectUnknownFlags,
   resolvePort
-} from "./cli-v031r2h6.js";
-import"./cli-0t4zfevc.js";
+} from "./cli-980t4qp9.js";
+import"./cli-bwbs3qm4.js";
 import"./cli-c41yr7he.js";
 import {
   BuildError

package/dist/{publish-6vt6yqm4.js → publish-zw39dmgm.js}

@@ -11,17 +11,17 @@ import {
   publishProviderFor,
   resolvePublishFormat,
   runPublish
-} from "./cli-chkwtg9m.js";
+} from "./cli-nde3d8wk.js";
 import {
   FileTokenStore,
   log
-} from "./cli-5pq315qe.js";
+} from "./cli-vntks53w.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-v031r2h6.js";
-import"./cli-0t4zfevc.js";
+} from "./cli-980t4qp9.js";
+import"./cli-bwbs3qm4.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/render.js

@@ -596,6 +596,8 @@ body { margin: 0; }
 :where(h1,h2,h3,h4,h5,h6) { break-after: avoid; }
 :where(img, svg, video) { max-width: 100%; }
 :where(p > img:only-child, figure > img) { width: fit-content; max-width: 100%; height: auto; vertical-align: bottom; }
+:where(p) > :where(img:not([class])) { max-height: calc(var(--gp-content-h) - 4px); object-fit: contain; }
+:where(figure) { break-inside: avoid; }
 :where(.section, figure) > :where(:first-child) { break-before: avoid; }
 
 `;
@@ -674,6 +676,32 @@ var GUTTERPRESS_CSS = `
 .gp-columns-2 { columns: 2; column-gap: var(--gp-column-gap, 1.5em); }
 .gp-columns-3 { columns: 3; column-gap: var(--gp-column-gap, 1.5em); }
 
+/* the per-shape decisions the paragraph above deliberately leaves to the
+   author, named instead of left as raw CSS every book was reinventing
+   (2026-09-01 CSS architecture review, findings C1/C7 — CLAUDE.md §0:
+   "behavior broadly useful to non-technical authors belongs in core").
+   Permanent vocabulary, standard properties verbatim — same rationale as
+   the column/grid runs above. One name each, no aliases:
+     .gp-columns-all       column-span: all      a heading or block that
+                                                  spans every column in the
+                                                  run it sits inside.
+     .gp-columns-flow      column-fill: auto     a run that FRAGMENTS across
+                                                  pages — every page's
+                                                  columns fill instead of
+                                                  only the last one
+                                                  balancing (the dead-column
+                                                  collapse the build's
+                                                  engine.multicol.dead-column
+                                                  warning names this fix
+                                                  for).
+     .gp-columns-balanced  column-fill: balance  a run that fits on ONE
+                                                  page (the CSS initial
+                                                  value — ragged columns
+                                                  would be wrong here). */
+.gp-columns-all { column-span: all; }
+.gp-columns-flow { column-fill: auto; }
+.gp-columns-balanced { column-fill: balance; }
+
 /* grid runs — the SLOTTED counterpart to the column runs above. Grid places
    each child into the next cell, across then down (deterministic slots: card
    layouts, stat blocks, image-plus-caption pairs); columns FLOW one text run
@@ -694,6 +722,15 @@ var GUTTERPRESS_CSS = `
 .gp-grid-2 { display: grid; grid-template-columns: repeat(2, 1fr); gap: var(--gp-grid-gap, 1.5em); }
 .gp-grid-3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--gp-grid-gap, 1.5em); }
 
+/* fragmentation controls — generic pagination utilities for any element,
+   independent of the column/grid vocabulary above (a book reached for
+   these just as often outside a multicol run: keeping a card whole,
+   forcing a section to start a fresh page). Standard properties only —
+   this project is Chromium-only (CLAUDE.md), so there are no legacy
+   page-break-* twins to also emit. One name each. */
+.gp-no-break { break-inside: avoid; }
+.gp-break-before { break-before: page; }
+
 /* shape wrap — text follows the image's alpha silhouette instead of its
    rectangular box. shape-outside only applies to floats, so this is inert
    without .gp-left/.gp-right (and under .gp-pin, which un-floats). The
@@ -778,6 +815,39 @@ img.gp-shape {
 .gp-raised { z-index: var(--gp-z-raised); }
 .gp-front  { z-index: var(--gp-z-front); }
 `;
+var GP_CLASSES = new Set([
+  "gp-left",
+  "gp-right",
+  "gp-center",
+  "gp-full",
+  "gp-bleed",
+  "gp-small",
+  "gp-medium",
+  "gp-large",
+  "gp-tight",
+  "gp-loose",
+  "gp-columns-2",
+  "gp-columns-3",
+  "gp-columns-all",
+  "gp-columns-flow",
+  "gp-columns-balanced",
+  "gp-no-break",
+  "gp-break-before",
+  "gp-grid-2",
+  "gp-grid-3",
+  "gp-shape",
+  "gp-pin",
+  "gp-top",
+  "gp-bottom",
+  "gp-behind",
+  "gp-base",
+  "gp-raised",
+  "gp-front",
+  "gp-page-break",
+  "gp-column-break",
+  "gp-continued",
+  "gp-flush"
+]);
 
 // src/lib/markdown/chapter-id.ts
 function canonicalChapterId(p) {
@@ -831,12 +901,70 @@ function warn2(env, line, type, message, marker) {
     env.layoutWarnings = [];
   env.layoutWarnings.push({ line, type, message, marker });
 }
+function editDistance2(a, b) {
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1;i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1;j <= b.length; j++) {
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = cur;
+  }
+  return prev[b.length];
+}
+function nearestGpClass(cls) {
+  const threshold = Math.max(2, Math.floor(cls.length / 3));
+  let best = null;
+  let bestDistance = Infinity;
+  for (const known of GP_CLASSES) {
+    const d = editDistance2(cls, known);
+    if (d < bestDistance) {
+      bestDistance = d;
+      best = known;
+    }
+  }
+  return best !== null && bestDistance > 0 && bestDistance <= threshold ? best : null;
+}
+function hasPinClass(token) {
+  const cls = token.attrGet && token.attrGet("class");
+  return typeof cls === "string" && cls.split(/\s+/).includes("gp-pin");
+}
+function elementNameFor(token) {
+  switch (token.type) {
+    case "layout_chapter_open":
+      return "@chapter";
+    case "layout_spread_open":
+      return "@spread";
+    case "layout_page_open":
+      return "@page";
+    case "layout_section_open":
+      return "@section";
+    case "image":
+      return "an image";
+    case "heading_open":
+      return "a heading";
+    case "paragraph_open":
+      return "a paragraph";
+    case "link_open":
+      return "a link";
+    default:
+      return token.tag ? `a <${token.tag}>` : "an element";
+  }
+}
+function checkUnknownGpClasses(token, env, line) {
+  const cls = token.attrGet && token.attrGet("class");
+  if (typeof cls !== "string" || !cls)
+    return;
+  for (const c of cls.split(/\s+/)) {
+    if (!c.startsWith("gp-") || GP_CLASSES.has(c))
+      continue;
+    const suggestion = nearestGpClass(c);
+    const base = `Unknown class "${c}" on ${elementNameFor(token)}.`;
+    warn2(env, line, "unknown_gp_class", suggestion ? `${base} Did you mean "${suggestion}"?` : base);
+  }
+}
 function gpPinScope(md) {
   const PIN_OUTSIDE_PAGE_MSG = "A .gp-pin element is not inside any @page or @spread, so it is pinned to the whole document instead of the page it sits on — it can print on a completely different sheet. Move it inside an @page or @spread block, or remove .gp-pin.";
-  function hasPinClass(token) {
-    const cls = token.attrGet && token.attrGet("class");
-    return typeof cls === "string" && cls.split(/\s+/).includes("gp-pin");
-  }
   md.core.ruler.push("gp_pin_scope_check", function(state) {
     let depth = 0;
     for (const token of state.tokens) {
@@ -855,6 +983,13 @@ function gpPinScope(md) {
           warn2(state.env, (token.map?.[0] ?? 0) + 1, "pin_outside_page", PIN_OUTSIDE_PAGE_MSG);
         }
       }
+      const line = (token.map?.[0] ?? 0) + 1;
+      checkUnknownGpClasses(token, state.env, line);
+      if (token.type === "inline" && token.children) {
+        for (const child of token.children) {
+          checkUnknownGpClasses(child, state.env, line);
+        }
+      }
     }
   });
 }
@@ -1378,10 +1513,15 @@ ${rendered}
     opts.onImageRefs([...imageRefs]);
   }
   const inlineCss = [
+    "@layer gp.marker, gp.vocab;",
     `/* gutterpress markers */
-${MARKER_CSS.trim()}`,
+@layer gp.marker {
+${MARKER_CSS.trim()}
+}`,
     `/* gutterpress */
-${GUTTERPRESS_CSS.trim()}`,
+@layer gp.vocab {
+${GUTTERPRESS_CSS.trim()}
+}`,
     pluginCss ? `/* user plugin css */
 ${pluginCss.trim()}` : null,
     projectCss ? `/* project css */

package/dist/{validate-vjwgxswp.js → validate-2fnfyyx8.js}

@@ -1,15 +1,15 @@
 import {
   executeAndReport
-} from "./cli-chkwtg9m.js";
+} from "./cli-nde3d8wk.js";
 import {
   log
-} from "./cli-5pq315qe.js";
+} from "./cli-vntks53w.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-v031r2h6.js";
-import"./cli-0t4zfevc.js";
+} from "./cli-980t4qp9.js";
+import"./cli-bwbs3qm4.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gutterpress",
-  "version": "0.10.5",
+  "version": "0.10.6-beta.2",
   "description": "Markdown-to-PDF converter for professional print layout using a native Chromium print engine and Ghostscript.",
   "author": "itlackey",
   "license": "MPL-2.0",