gutterpress 0.11.20-alpha.2 → 0.11.20-alpha.3

package/dist/{index-3nr5rzzp.js → index-zagagnwq.js}

@@ -148,7 +148,7 @@ import { fileURLToPath } from "node:url";
 var favicon_default = "./favicon-272ga6y0.ico";
 
 // src/assets/manifest.schema.json
-var manifest_schema_default = "./manifest.schema-74s1ykyv.json";
+var manifest_schema_default = "./manifest.schema-c9x8912a.json";
 
 // src/assets/preview/scripts/preview-interface.js
 var preview_interface_default = "./preview-interface-nnmrxyqm.js";
@@ -163,7 +163,7 @@ var preview_shell_default = "./preview-shell-wk9k3gcd.js";
 var CGATS21_CRPC1_default = "./CGATS21_CRPC1-g0e3k7kr.icc";
 
 // src/assets/engine/gutterpress-viewer.js
-var gutterpress_viewer_default = "./gutterpress-viewer-retj6ym2.js";
+var gutterpress_viewer_default = "./gutterpress-viewer-1yse8cx3.js";
 
 // src/assets/engine/gutterpress-agent.js
 var gutterpress_agent_default = "./gutterpress-agent-cazqstr1.js";

package/dist/index.js

@@ -154,14 +154,15 @@ import {
   testRemoteAccess,
   updateExtensions,
   validateProjectExtensions
-} from "./index-razpty47.js";
+} from "./index-tjvrchxj.js";
 import"./index-ht1bcqdd.js";
 import {
   BUILD_DIAGNOSTIC_CODES
-} from "./index-6xwtb7cw.js";
+} from "./index-r87y7wzw.js";
 import {
   BuildError
-} from "./index-3nr5rzzp.js";
+} from "./index-zagagnwq.js";
+import"./index-sth219v1.js";
 import {
   DEFAULT_PRINT_OPTS,
   assertMilestone,

package/dist/lib/build-fingerprint.d.ts

@@ -5,6 +5,14 @@ type PdfxFingerprintConfig = {
     stripAnnotations: boolean | null;
     /** How near-black text was separated (#331); null when no PDF/X pass ran. Provenance only. */
     blackText?: "icc" | "k-only" | null;
+    /**
+     * How pages with transparency were handled (#385): `pdfx.transparency`,
+     * `pdfx.flattenPages` and `pdfx.rasterDpi`. null when no PDF/X pass ran
+     * (and, for rasterDpi, when unset). Provenance only.
+     */
+    transparency?: "flatten-page" | "preserve-text" | null;
+    flattenPages?: number[] | null;
+    rasterDpi?: number | null;
 };
 export type BuildFingerprintInput = {
     command: "build";

package/dist/lib/ghostscript.d.ts

@@ -1,3 +1,4 @@
+import type { UnsplittableReason } from "./pdf-inspect";
 /**
  * Resolve the Ghostscript command on every supported platform.
  *
@@ -8,38 +9,39 @@
  */
 export declare function resolveGhostscript(targetPlatform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): Promise<string | undefined>;
 /**
- * Whether `pdfBytes` uses any live PDF transparency — the PDF 1.4 imaging
- * feature, in ALL the forms Chromium emits it, not just alpha-channel images:
+ * The 1-based page numbers of `pdfBytes` that use live PDF transparency — the
+ * PDF 1.4 imaging feature, in ALL the forms Chromium emits it, not just
+ * alpha-channel images:
  *
  *  - a transparency **group** (`/Group << /S /Transparency >>`), which is what
  *    CSS `opacity`, `mix-blend-mode` and friends compile down to;
  *  - an **image soft mask** (`/SMask` on an image XObject, pointing at a real
  *    mask rather than the literal `/None` an opaque image also carries) — an
  *    RGBA source image;
- *  - a **graphics-state** soft mask or constant alpha (`/SMask`, `/ca`, `/CA`
- *    on an `/ExtGState`).
+ *  - a **graphics-state** soft mask, constant alpha (`/ca`, `/CA` below 1) or
+ *    non-Normal blend mode (`/BM`) on an `/ExtGState` — soft `rgba()`
+ *    shadows and fills.
  *
  * PDF/X-1a and PDF/X-3 (as this codebase generates them, `-dCompatibilityLevel=1.3`
  * in {@link convertToPdfxCmyk}) are both based on PDF 1.3, which predates the
  * PDF 1.4 transparency model entirely — live transparency has nothing a
  * PDF-1.3 file can represent it with. Ghostscript's only PDF/X-compliant
  * option is to flatten the page it appears ON down to a single raster image
- * (B.10, measured: a book with alpha-channel artwork loses every embedded
- * font and all searchable text in its PDF/X output, identically on both
- * engines — this is a Ghostscript/PDF-1.3 property, not an engine bug).
- * Detecting it lets the build warn the author PRECISELY, instead of them
- * discovering a fontless PDF/X file after the fact.
+ * (B.10, measured: text and fonts on that page are lost, identically on both
+ * engines — a Ghostscript/PDF-1.3 property, not an engine bug).
+ * {@link flattenTransparentPages} (opt-in, `pdfx.transparency: preserve-text`)
+ * can instead keep the text live on the pages this returns.
  *
- * This walks the parsed object graph rather than scanning raw bytes. A byte
- * scan is NOT sufficient and produced a false "all clear" in review: image
+ * This walks each page's parsed object graph rather than scanning raw bytes. A
+ * byte scan is NOT sufficient and produced a false "all clear" in review: image
  * XObjects are streams, so their dicts do sit uncompressed at top level, but
  * `/ExtGState` and `/Group` dicts are plain objects that Chromium packs into
  * **object streams** (`/Type /ObjStm`, deflate-compressed), where no regex can
- * see them. Measured on four books with known Ghostscript outcomes, this
- * predicate is exactly right on all four; the byte scan silently missed the
- * CSS-`opacity` book, which rasterizes to zero embedded fonts.
+ * see them. Fonts, `/Parent` (which leads to every other page) and `/Annots`
+ * are not followed: an annotation's appearance stream is not page content, and
+ * PDF/X builds strip annotations before conversion.
  */
-export declare function hasLiveTransparency(pdfBytes: Uint8Array): Promise<boolean>;
+export declare function transparentPages(pdfBytes: Uint8Array): Promise<number[]>;
 /**
  * 1-based numbers of the pages that paint a `/ShadingType 1` shading whose
  * function is `/FunctionType 4` (a PostScript calculator function).
@@ -56,7 +58,7 @@ export declare function hasLiveTransparency(pdfBytes: Uint8Array): Promise<boole
  *
  * Walks page resources (and form XObjects they draw) rather than every
  * object, so only shadings a page can actually paint are reported. Like
- * {@link hasLiveTransparency}, it never fails a build: an unparseable PDF
+ * {@link transparentPages}, it never fails a build: an unparseable PDF
  * reports no pages.
  */
 export declare function findPostScriptShadingPages(pdfBytes: Uint8Array): Promise<number[]>;
@@ -81,6 +83,58 @@ export declare function findPostScriptShadingPages(pdfBytes: Uint8Array): Promis
  *     directly (pdf-lib, in-process, no second external tool).
  */
 export declare function stripAnnotations(pdfPath: string, stagingDir: string): Promise<void>;
+/** Why a transparent page is flattened whole under `preserve-text` instead of split. */
+export type FallbackCause = Exclude<UnsplittableReason, "no-text"> | "listed" | "gradient";
+/**
+ * Sort each page that uses transparency (1-based, from {@link transparentPages})
+ * for `pdfx.transparency: preserve-text`:
+ * - `split`: its artwork is flattened and its text kept live
+ *   ({@link flattenTransparentPages});
+ * - `artOnly`: it shows no text, so there is nothing to keep and Ghostscript
+ *   flattens it whole, which is as good;
+ * - `kept`: it has text but is flattened whole anyway, with the cause the
+ *   build reports. The author's `pdfx.flattenPages` list wins, then the
+ *   text's own reason (`unsplittableTextReasons`), then a repeating or conic
+ *   gradient (#386), whose PostScript-function shading the artwork pass
+ *   distorts.
+ * Every transparent page lands in exactly one group.
+ */
+export declare function planTransparentPages(transparent: number[], reasons: Map<number, UnsplittableReason>, flattenPages: number[], gradientPages: number[]): {
+    split: number[];
+    artOnly: number[];
+    kept: Map<number, FallbackCause>;
+};
+/**
+ * Make the pages in `pages` (1-based; the `split` group of
+ * {@link planTransparentPages}) free of transparency while keeping
+ * their text live, so PDF/X (PDF 1.3) conversion has nothing left to flatten
+ * into a single bitmap. Opt-in: `pdfx.transparency: preserve-text`.
+ *
+ * Per affected page, two Ghostscript passes split it in two and pdf-lib
+ * stacks the halves back on the ORIGINAL page object:
+ *
+ *  1. ARTWORK — `pdfimage24 -dFILTERTEXT -r<dpi>` drops the glyphs and
+ *     composites everything left (soft shadows, alpha images, opacity) into
+ *     one opaque image (300 DPI unless `pdfx.rasterDpi` says otherwise),
+ *     straight from the source;
+ *  2. TEXT — `-dFILTERIMAGE -dFILTERVECTOR` keeps only the glyphs. It needs
+ *     `-dNOTRANSPARENCY`: without it Chromium's transparency groups and
+ *     `/ca`/`/SMask` ExtGStates survive in the text-only file and the next
+ *     step flattens the page anyway. That is only faithful for text with no
+ *     transparency of its own, which is why callers leave other pages out;
+ *  3. the page's content is replaced by the artwork with the text drawn on
+ *     top. Editing the original page keeps its boxes (Media/Crop/Trim/Bleed),
+ *     annotations, the document's metadata, outlines and labels exactly as
+ *     they were; only its `/Contents`, `/Resources` and `/Group` change.
+ *
+ * Pages not listed are never touched. Known limits, both consequences of
+ * splitting a page into "picture" and "text": the page's vector chrome
+ * (rules, backgrounds, shapes) becomes the picture, and text is always the
+ * top layer, so text another element covers shows through.
+ */
+export declare function flattenTransparentPages(pdfPath: string, pageNumbers: number[], stagingDir: string, 
+/** artwork resolution (`pdfx.rasterDpi`) */
+dpi?: number): Promise<void>;
 type PdfxFlavor = "x1a" | "x3";
 /**
  * Stamp the Creator metadata field on an existing PDF.

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

@@ -134,6 +134,51 @@ export interface OpPass {
     fonts: FontRef[];
 }
 export declare function getOpPass(doc: PDFDocumentProxy): Promise<OpPass>;
+/**
+ * Why a page is not split from its artwork: its text cannot be (the first
+ * three), or it shows no text at all, so there is none to keep (`no-text`).
+ */
+export type UnsplittableReason = "text-transparency" | "type3-font" | "text-pattern-or-clip" | "no-text";
+/**
+ * For each 1-based page that `pdfx.transparency: preserve-text` must not split,
+ * the first reason found; pages absent from the map can be split. `pages`
+ * limits the scan to those pages (the build passes the transparent ones only,
+ * so the rest of the book is never decoded).
+ *
+ * A page's text cannot be split when text SHOWS while transparency is in effect: constant alpha
+ * (`ca`/`CA` < 1), a non-Normal blend mode, an active soft mask, or any
+ * enclosing transparency group that is composited translucent, blended or
+ * masked, or is a knockout group. (Chromium draws `opacity` and
+ * `mix-blend-mode` content as a group form XObject under such a state, and
+ * resets the state INSIDE the group, so the state at the point the group
+ * begins is what counts.) Such text cannot be lifted out of its page and drawn
+ * opaque on top of a flattened picture without changing how it looks, so
+ * `pdfx.transparency: preserve-text` leaves those pages alone.
+ *
+ * Also flagged: any page that sets a Type 3 font. Chromium (Skia) emits Type 3
+ * for glyphs it can only draw as paths, e.g. the synthetic bold of a
+ * single-weight webfont. Their glyph procedures are vector paths, which the
+ * text pass's `-dFILTERVECTOR` strips, so the text would print nothing.
+ *
+ * Also flagged: text painted with a pattern (`scn`/`SCN` to a tiling pattern
+ * or shading), as Chromium emits for SVG `<text fill="url(#…)">` and gradient
+ * text fills, and text used as a clip (render modes 4-7, `background-clip:
+ * text`). The artwork pass removes the glyphs and the text pass's
+ * `-dFILTERIMAGE`/`-dFILTERVECTOR` removes their paint, so they would vanish.
+ *
+ * A plain isolated group composited at alpha 1 / Normal / no mask is NOT
+ * counted: painting it is the same as painting its content inline, and
+ * Chromium wraps the content of EVERY page in one as soon as any element of
+ * the document uses a blend mode (measured on Chromium 141), which would
+ * otherwise rule out every page of such a book. The page's OWN `/Group` is
+ * likewise ignored.
+ *
+ * Walks PDF.js's operator list, which has already inlined form XObjects
+ * between `paintFormXObjectBegin/End` and reports their `/Group` as
+ * `beginGroup/endGroup`. Graphics state is tracked per save/restore (a form
+ * XObject is an implicit save/restore).
+ */
+export declare function unsplittableTextReasons(pdfBytes: Uint8Array, pages?: number[]): Promise<Map<number, UnsplittableReason>>;
 /**
  * Does page `pageNum` (1-based) paint anything at all? False for a page with
  * no content and for one whose operators only set state or clip. A path op

package/dist/{manifest.schema-74s1ykyv.json → manifest.schema-c9x8912a.json}

@@ -155,9 +155,21 @@
           "enum": ["icc", "k-only"],
           "default": "icc"
         },
+        "transparency": {
+          "type": "string",
+          "description": "What a PDF/X build does with a page that uses transparency (an alpha-channel image, a soft `rgba()` shadow, CSS `opacity` or `mix-blend-mode`), which PDF/X (PDF 1.3) cannot represent. `flatten-page` leaves the page to Ghostscript, which rasterizes the WHOLE page: it looks right but loses the page's text and fonts. `preserve-text` flattens only the artwork to a picture (300 DPI, or `rasterDpi`) and draws the text live on top, so the page stays searchable. Text is then always the top layer (text another element covers shows through). A page whose text is translucent or blended, set in a Type 3 font (e.g. a synthetic bold or a text stroke), filled with a pattern or used as a clip, or that has a repeating or conic gradient, falls back to `flatten-page`, and so does any page listed in `flattenPages`. Set `validate.assets.allowAlpha: true` to use alpha-channel images. Same for every preset: `flatten-page`.",
+          "enum": ["flatten-page", "preserve-text"],
+          "default": "flatten-page"
+        },
+        "flattenPages": {
+          "type": "array",
+          "description": "With `transparency: preserve-text`: pages (1-based, the numbers the build reports) left to Ghostscript's whole-page flattening even if they could be split, e.g. a page whose look depends on a cover or tint painted over its text. Page numbers move when the book reflows. Default: none.",
+          "items": { "type": "integer", "minimum": 1 },
+          "examples": [[4, 13]]
+        },
         "rasterDpi": {
           "type": "integer",
-          "description": "Resolution (DPI) of the picture Ghostscript makes of a page it flattens in a PDF/X build because the page uses transparency (PDF/X-1a and X-3 cannot hold it). Lower is smaller and softer; vector content on other pages and the book's own images are not resampled. Unset: Ghostscript's default, 720.",
+          "description": "Resolution (DPI) of every picture made from a page that uses transparency: the whole pages Ghostscript flattens and the `preserve-text` artwork. Vector content and the book's own images are not resampled. Unset: Ghostscript's default (720) for whole pages, 300 for `preserve-text` artwork.",
           "minimum": 72,
           "maximum": 1200,
           "examples": [300]

package/dist/{new-ftd4fec4.js → new-8yah8z91.js}

@@ -7,20 +7,21 @@ import {
   TARGET_IDS,
   scaffoldExtension,
   scaffoldProject
-} from "./cli-zacevwcy.js";
+} from "./cli-9k2tb493.js";
 import {
   resolveGhostscript
-} from "./cli-gh0ym80r.js";
+} from "./cli-y9bcya7r.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-7z29z4wz.js";
+} from "./cli-hn9pk0hp.js";
 import"./cli-ht1bcqdd.js";
-import"./cli-j802s31j.js";
+import"./cli-x4p99w8d.js";
 import {
   EXIT_CODES
 } from "./cli-46ycxe6r.js";
+import"./cli-sth219v1.js";
 import"./cli-eyyggect.js";
 import {
   isToolAvailable

package/dist/pdf-inspect-zdmy7qca.js

@@ -0,0 +1,35 @@
+import {
+  DOC_CACHE_MAX,
+  clearPdfCache,
+  countLinkAnnotations,
+  getImageResolutions,
+  getOpPass,
+  getOutlineCount,
+  getPageLabels,
+  getPageSize,
+  getTextPass,
+  isLoadable,
+  loadPdf,
+  pageHasMarks,
+  pendingGraceDestroyCount,
+  retainPdfCache,
+  unsplittableTextReasons
+} from "./cli-sth219v1.js";
+import"./cli-37x76zdn.js";
+export {
+  unsplittableTextReasons,
+  retainPdfCache,
+  pendingGraceDestroyCount,
+  pageHasMarks,
+  loadPdf,
+  isLoadable,
+  getTextPass,
+  getPageSize,
+  getPageLabels,
+  getOutlineCount,
+  getOpPass,
+  getImageResolutions,
+  countLinkAnnotations,
+  clearPdfCache,
+  DOC_CACHE_MAX
+};

package/dist/{preflight-8sqarcsr.js → preflight-8ccx4kdc.js}

@@ -2,21 +2,22 @@ import {
   executeValidation,
   publishTargetFor,
   reportMissingTools
-} from "./cli-zacevwcy.js";
+} from "./cli-9k2tb493.js";
 import {
   log
-} from "./cli-gh0ym80r.js";
+} from "./cli-y9bcya7r.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-7z29z4wz.js";
+} from "./cli-hn9pk0hp.js";
 import"./cli-ht1bcqdd.js";
-import"./cli-j802s31j.js";
+import"./cli-x4p99w8d.js";
 import {
   BuildError,
   EXIT_CODES
 } from "./cli-46ycxe6r.js";
+import"./cli-sth219v1.js";
 import"./cli-eyyggect.js";
 import"./cli-asap4t1z.js";
 import"./cli-5qr3z0qa.js";

package/dist/{preview-q76xn95h.js → preview-w7v9w36q.js}

@@ -6,10 +6,10 @@ import {
   runBuild,
   splitOutPath,
   startPreviewServer
-} from "./cli-zacevwcy.js";
+} from "./cli-9k2tb493.js";
 import {
   log
-} from "./cli-gh0ym80r.js";
+} from "./cli-y9bcya7r.js";
 import {
   UsageError,
   parseFormat,
@@ -17,12 +17,13 @@ import {
   rejectExtraPositionals,
   rejectUnknownFlags,
   resolvePort
-} from "./cli-7z29z4wz.js";
+} from "./cli-hn9pk0hp.js";
 import"./cli-ht1bcqdd.js";
-import"./cli-j802s31j.js";
+import"./cli-x4p99w8d.js";
 import {
   BuildError
 } from "./cli-46ycxe6r.js";
+import"./cli-sth219v1.js";
 import"./cli-eyyggect.js";
 import"./cli-asap4t1z.js";
 import"./cli-5qr3z0qa.js";

package/dist/{publish-7gdy6gbf.js → publish-g5nh5myh.js}

@@ -11,21 +11,22 @@ import {
   publishProviderFor,
   resolvePublishFormat,
   runPublish
-} from "./cli-zacevwcy.js";
+} from "./cli-9k2tb493.js";
 import {
   FileTokenStore,
   log
-} from "./cli-gh0ym80r.js";
+} from "./cli-y9bcya7r.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-7z29z4wz.js";
+} from "./cli-hn9pk0hp.js";
 import"./cli-ht1bcqdd.js";
-import"./cli-j802s31j.js";
+import"./cli-x4p99w8d.js";
 import {
   EXIT_CODES
 } from "./cli-46ycxe6r.js";
+import"./cli-sth219v1.js";
 import"./cli-eyyggect.js";
 import"./cli-asap4t1z.js";
 import"./cli-5qr3z0qa.js";

package/dist/schema/manifest.types.d.ts

@@ -119,8 +119,24 @@ export interface GutterpressManifest {
         /** `k-only` prints near-black text on the black plate alone (#331). */
         blackText?: "icc" | "k-only";
         /**
-         * Resolution (DPI) of the picture Ghostscript makes of a page it flattens
-         * because the page uses transparency. Unset: Ghostscript's default (720).
+         * A page that uses transparency, which PDF/X cannot hold (#385).
+         * `flatten-page` (default): Ghostscript rasterizes the whole page, text
+         * included. `preserve-text`: flatten the artwork only and keep the text
+         * live on top; a page whose text cannot be split (translucent or blended,
+         * Type 3, pattern-filled or a clip) or that has a repeating or conic
+         * gradient falls back to the whole-page flattening.
+         */
+        transparency?: "flatten-page" | "preserve-text";
+        /**
+         * `preserve-text` only: pages (1-based, as the build reports them) left to
+         * Ghostscript's whole-page flattening, e.g. a page whose look depends on a
+         * cover or tint painted over its text.
+         */
+        flattenPages?: number[];
+        /**
+         * Resolution (DPI) of every picture made from a transparent page: the
+         * whole page Ghostscript flattens, and the `preserve-text` artwork.
+         * Unset: Ghostscript's default (720) and 300 for `preserve-text` artwork.
          */
         rasterDpi?: number;
     };
@@ -290,6 +306,8 @@ export interface ResolvedConfig {
         icc: string;
         stripAnnotations: boolean;
         blackText: "icc" | "k-only";
+        transparency: "flatten-page" | "preserve-text";
+        flattenPages: number[];
         rasterDpi?: number;
     };
     print: {

package/dist/test-helpers/testkit.d.ts

@@ -106,8 +106,8 @@ export interface GrayRaster {
 }
 /** Ghostscript's path, or `null`. Callers self-skip, as the PDF/X suites do. */
 export declare function resolveRasterizer(): Promise<string | null>;
-/** Page 1 of `pdfPath` as an 8-bit grayscale raster at 100 dpi. */
-export declare function rasterizePdfPage(gsBin: string, pdfPath: string, outDir: string, tag: string): GrayRaster;
+/** Page `page` (default 1) of `pdfPath` as an 8-bit grayscale raster at 100 dpi. */
+export declare function rasterizePdfPage(gsBin: string, pdfPath: string, outDir: string, tag: string, page?: number): GrayRaster;
 /**
  * Mean absolute per-pixel difference. `0` means the two prints are identical —
  * i.e. the declaration under test changed nothing at all.

package/dist/{validate-e3ryegce.js → validate-1yh59x0x.js}

@@ -1,20 +1,21 @@
 import {
   executeAndReport
-} from "./cli-zacevwcy.js";
+} from "./cli-9k2tb493.js";
 import {
   log
-} from "./cli-gh0ym80r.js";
+} from "./cli-y9bcya7r.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-7z29z4wz.js";
+} from "./cli-hn9pk0hp.js";
 import"./cli-ht1bcqdd.js";
-import"./cli-j802s31j.js";
+import"./cli-x4p99w8d.js";
 import {
   BuildError,
   EXIT_CODES
 } from "./cli-46ycxe6r.js";
+import"./cli-sth219v1.js";
 import"./cli-eyyggect.js";
 import"./cli-asap4t1z.js";
 import"./cli-5qr3z0qa.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gutterpress",
-  "version": "0.11.20-alpha.2",
+  "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",