@hidemikimura/receipt-html-to-pdf 0.2.1 → 0.4.0

package/src/page.js

@@ -9,6 +9,9 @@ import { EmbeddedFont, hex4 } from './font/cid.js';
 import { embedImage } from './pdf/image.js';
 import { PX_TO_PT, PAGE_SIZES, lengthToPt, num } from './units.js';
 import { paginate } from './paginate.js';
+import { releasePixels, loadImage } from './walker/image.js';
+import { buildAxialShading, uniformAlpha, buildAlphaMaskGState } from './pdf/shading.js';
+import { buildLinkAnnot, buildOutline } from './pdf/outline.js';
 
 /**
  * @typedef {object} PageGeometry
@@ -56,7 +59,7 @@ export function resolvePage(page = {}) {
 /**
  * @param {import('./walker/walk.js').WalkResult} body
  * @param {PageGeometry} geo
- * @param {{compress: boolean, metadata?: import('./index.js').PdfMetadata, header?: PageDecoration|null, footer?: PageDecoration|null}} opts
+ * @param {{compress: boolean, metadata?: import('./index.js').PdfMetadata, header?: PageDecoration|null, footer?: PageDecoration|null, pacer?: import('./pacer.js').Pacer, progress?: (p: import('./index.js').ConversionProgress) => void, warn?: (w: import('./index.js').ConversionWarning) => void, links?: boolean, outline?: boolean}} opts
  * @returns {Promise<Uint8Array>}
  */
 export async function buildPdf(body, geo, opts) {
@@ -113,33 +116,97 @@ export async function buildPdf(body, geo, opts) {
   for (const ef of fonts.values()) fontDict[ef.resourceName] = await ef.embed(writer);
   /** @type {{[key: string]: import('./pdf/writer.js').PdfValue}} */
   const xobjDict = {};
-  for (const im of images.values()) xobjDict[im.name] = await embedImage(writer, im.image);
+  for (const im of images.values()) {
+    let img = im.image;
+    // 並行して走る別の変換が先に解放していた場合は読み直す
+    if (!img.jpeg && !img.rgb) {
+      const again = await loadImage(img.key, opts.warn ?? (() => {}));
+      if (!again) continue;
+      img = again;
+    }
+    xobjDict[im.name] = await embedImage(writer, img);
+    // 埋め込みが済めばピクセルデータは不要。大きな文書のピーク使用量を抑える
+    releasePixels(img);
+    if (opts.pacer) await opts.pacer();
+  }
 
   // ExtGState（透明度）
   /** @type {Map<string, string>} */
   const gstates = new Map();
   /** @type {{[key: string]: import('./pdf/writer.js').PdfValue}} */
   const gstateDict = {};
-  const gsName = (/** @type {number} */ a) => {
-    const key = num(a);
+  const gsName = (/** @type {number} */ a, /** @type {number} */ strokeA = a) => {
+    const key = `${num(a)}/${num(strokeA)}`;
     let name = gstates.get(key);
     if (!name) {
       name = `GS${gstates.size + 1}`;
       gstates.set(key, name);
-      gstateDict[name] = writer.add({ Type: 'ExtGState', ca: a, CA: a });
+      gstateDict[name] = writer.add({ Type: 'ExtGState', ca: a, CA: strokeA });
     }
     return name;
   };
 
+  // Shading（linear-gradient）。座標は箱ローカルの CSS px で持ち、描画時に cm で用紙座標へ写す。
+  // こうするとページごとに作り直さずに済む。
+  /** @type {{[key: string]: import('./pdf/writer.js').PdfValue}} */
+  const shadingDict = {};
+  /** @type {Map<import('./walker/walk.js').DisplayItem, {sh: string, gs: string|null}>} */
+  const gradients = new Map();
+  /** @param {import('./walker/walk.js').DisplayItem[]} list */
+  const prepareGradients = async (list) => {
+    for (const it of list) {
+      if (it.type === 'gradient') {
+        const name = `Sh${Object.keys(shadingDict).length + 1}`;
+        shadingDict[name] = buildAxialShading(writer, it.gradient, it.gradient.stops, 'rgb');
+        const alpha = uniformAlpha(it.gradient.stops);
+        let gs = null;
+        if (alpha === null) {
+          // 色止めごとにアルファが変わる → 輝度ソフトマスクで再現する
+          const gsRef = await buildAlphaMaskGState(writer, it.gradient, it.gradient.stops, { x: 0, y: 0, w: it.box.w, h: it.box.h }, it.alpha);
+          gs = `GM${gradients.size + 1}`;
+          gstateDict[gs] = gsRef;
+        }
+        gradients.set(it, { sh: name, gs });
+      } else if (it.type === 'group' || it.type === 'clip') {
+        await prepareGradients(it.items);
+      }
+    }
+  };
+  await prepareGradients(body.items);
+  for (const w of [...headers, ...footers]) if (w) await prepareGradients(w.items);
+
   const pagesRef = writer.reserve();
   /** @type {import('./pdf/writer.js').Ref[]} */
   const pageRefs = [];
+  // リンクの飛び先は前後どちらのページにもなりうるので、ページ参照を先に確保しておく
+  const pageSlots = Array.from({ length: totalPages }, () => writer.reserve());
+  /** @param {number} i @returns {import('./pdf/writer.js').Ref} */
+  const slotOf = (i) => /** @type {import('./pdf/writer.js').Ref} */ (pageSlots[i]);
+
+  /**
+   * ドキュメント y が載るページと、そのページでの PDF 座標を求める。
+   * @param {number} docY
+   * @returns {{page: number, x: number, y: number}|null}
+   */
+  const locate = (docY) => {
+    for (let i = 0; i < totalPages; i++) {
+      const r = /** @type {import('./paginate.js').PageRange} */ (ranges[i]);
+      if (docY >= r.start - 0.01 && (docY < r.end - 0.01 || i === totalPages - 1)) {
+        const top = contentTop - r.headShift * PX_TO_PT;
+        return { page: i, x: geo.left, y: top - (docY - r.start) * PX_TO_PT };
+      }
+    }
+    return null;
+  };
 
   // 4. ページごとに描画
+  opts.progress?.({ phase: 'layout', totalPages });
   for (let p = 0; p < totalPages; p++) {
+    if (opts.pacer) await opts.pacer();
+    opts.progress?.({ phase: 'page', page: p + 1, totalPages });
     const range = /** @type {import('./paginate.js').PageRange} */ (ranges[p]);
     const cs = new ContentStream();
-    const painter = new Painter(cs, geo, fonts, images, gsName);
+    const painter = new Painter(cs, geo, fonts, images, gsName, gradients);
 
     // 本文: ドキュメント y = range.start が本文領域の上端 + 繰り返し thead の高さ に来る
     const bodyShiftPt = range.headShift * PX_TO_PT;
@@ -190,25 +257,85 @@ export async function buildPdf(body, geo, opts) {
       cs.restore();
     }
 
+    // リンク注釈。ページ範囲で切り取ってから用紙座標へ写す
+    /** @type {import('./pdf/writer.js').PdfValue[]} */
+    const annots = [];
+    if (opts.links !== false) {
+      /**
+       * @param {import('./walker/walk.js').LinkRect[]} list
+       * @param {number} pdfTop   この帯の上端（PDF 座標）
+       * @param {number} docTop   その位置に対応するドキュメント y
+       * @param {number} docEnd   この帯に出せるドキュメント y の終わり
+       */
+      const addLinks = (list, pdfTop, docTop, docEnd) => {
+        for (const link of list) {
+          const y0 = Math.max(link.y, docTop);
+          const y1 = Math.min(link.y + link.h, docEnd);
+          if (y1 - y0 <= 0.01) continue;
+          const rect = {
+            x: geo.left + link.x * PX_TO_PT,
+            y: pdfTop - (y1 - docTop) * PX_TO_PT,
+            w: link.w * PX_TO_PT,
+            h: (y1 - y0) * PX_TO_PT,
+          };
+          if (link.fragment === null) {
+            annots.push(buildLinkAnnot(writer, rect, { uri: link.href }));
+            continue;
+          }
+          const targetY = body.anchors?.get(link.fragment);
+          if (targetY === undefined) continue; // 飛び先が無いリンクは注釈にしない
+          const at = locate(targetY);
+          if (!at) continue;
+          annots.push(buildLinkAnnot(writer, rect, { dest: [slotOf(at.page), new Name('XYZ'), at.x, at.y, null] }));
+        }
+      };
+      addLinks(body.links ?? [], contentTop - bodyShiftPt, range.start, range.end);
+      if (header) addLinks(header.links ?? [], geo.height - geo.top, 0, headerPt / PX_TO_PT);
+      if (footer) addLinks(footer.links ?? [], geo.bottom + footerPt, 0, footerPt / PX_TO_PT);
+    }
+
     const contentRef = await writer.addStream({}, cs.toBytes());
-    pageRefs.push(
-      writer.add({
-        Type: 'Page',
-        Parent: pagesRef,
-        MediaBox: [0, 0, geo.width, geo.height],
-        Resources: {
-          Font: fontDict,
-          XObject: xobjDict,
-          ExtGState: gstateDict,
-          ProcSet: [new Name('PDF'), new Name('Text'), new Name('ImageC')],
-        },
-        Contents: contentRef,
+    /** @type {{[key: string]: import('./pdf/writer.js').PdfValue}} */
+    const pageDict = {
+      Type: 'Page',
+      Parent: pagesRef,
+      MediaBox: [0, 0, geo.width, geo.height],
+      Resources: {
+        Font: fontDict,
+        XObject: xobjDict,
+        ExtGState: gstateDict,
+        Shading: shadingDict,
+        ProcSet: [new Name('PDF'), new Name('Text'), new Name('ImageC')],
+      },
+      Contents: contentRef,
+    };
+    if (annots.length) pageDict.Annots = annots;
+    const slot = slotOf(p);
+    writer.set(slot, pageDict);
+    pageRefs.push(slot);
+  }
+
+  writer.set(pagesRef, { Type: 'Pages', Kids: pageRefs, Count: pageRefs.length });
+
+  // しおり: 見出しから木を作る
+  let outlineRef = null;
+  if (opts.outline) {
+    outlineRef = buildOutline(
+      writer,
+      (body.headings ?? []).map((h) => {
+        const at = locate(h.y);
+        return { level: h.level, text: h.text, dest: at ? [slotOf(at.page), new Name('XYZ'), at.x, at.y, null] : null };
       }),
     );
   }
 
-  writer.set(pagesRef, { Type: 'Pages', Kids: pageRefs, Count: pageRefs.length });
-  const catalog = writer.add({ Type: 'Catalog', Pages: pagesRef });
+  /** @type {{[key: string]: import('./pdf/writer.js').PdfValue}} */
+  const catalogDict = { Type: 'Catalog', Pages: pagesRef };
+  if (outlineRef) {
+    catalogDict.Outlines = outlineRef;
+    catalogDict.PageMode = new Name('UseOutlines');
+  }
+  const catalog = writer.add(catalogDict);
 
   const md = opts.metadata ?? {};
   /** @type {{[key: string]: import('./pdf/writer.js').PdfValue}} */
@@ -252,14 +379,16 @@ class Painter {
    * @param {PageGeometry} geo
    * @param {Map<import('./font/registry.js').RegisteredFont, EmbeddedFont>} fonts
    * @param {Map<string, {name: string, image: import('./walker/image.js').DecodedImage}>} images
-   * @param {(alpha: number) => string} gsName
+   * @param {(alpha: number, strokeAlpha?: number) => string} gsName
+   * @param {Map<import('./walker/walk.js').DisplayItem, {sh: string, gs: string|null}>} gradients
    */
-  constructor(cs, geo, fonts, images, gsName) {
+  constructor(cs, geo, fonts, images, gsName, gradients) {
     this.cs = cs;
     this.geo = geo;
     this.fonts = fonts;
     this.images = images;
     this.gsName = gsName;
+    this.gradients = gradients;
     this.pdfTop = geo.height - geo.top;
     this.docTop = 0;
     this.curAlpha = 1;
@@ -339,6 +468,46 @@ class Painter {
         cs.roundedRect(this.X(it.x), this.Y(it.y + it.h), it.w * PX_TO_PT, it.h * PX_TO_PT, this.radiusPt(it.radius)).stroke();
         cs.restore();
         this.curAlpha = 1;
+      } else if (it.type === 'path') {
+        if (!it.segs.length) continue;
+        const [a, b2, c, d, e, f] = it.matrix;
+        // ユーザー単位 → ドキュメント px → PDF pt（y 反転）を 1 つの行列にまとめる
+        const S = PX_TO_PT;
+        const tx = this.geo.left;
+        const ty = this.pdfTop + this.docTop * S;
+        cs.save();
+        cs.transform(S * a, -S * b2, S * c, -S * d, S * e + tx, -S * f + ty);
+        if (it.fill) cs.fillColor(it.fill.r, it.fill.g, it.fill.b);
+        if (it.stroke) {
+          cs.strokeColor(it.stroke.color.r, it.stroke.color.g, it.stroke.color.b);
+          cs.lineWidth(it.stroke.width);
+          cs.lineCap(it.stroke.cap);
+          cs.lineJoin(it.stroke.join);
+          if (it.stroke.join === 0) cs.miterLimit(it.stroke.miter);
+          if (it.stroke.dash) cs.dash(it.stroke.dash, it.stroke.dashOffset);
+        }
+        // 塗りと線でアルファが違うことがあるので ExtGState には両方を渡す
+        const fa = it.fill ? it.fill.a : 1;
+        const sa = it.stroke ? it.stroke.color.a : 1;
+        if (fa !== 1 || sa !== 1) cs.setGState(this.gsName(fa, sa));
+        cs.path(it.segs);
+        if (it.fill && it.stroke) cs.fillAndStroke(it.evenOdd);
+        else if (it.fill) cs.fill(it.evenOdd);
+        else cs.stroke();
+        cs.restore();
+        this.curAlpha = 1;
+      } else if (it.type === 'gradient') {
+        const g = this.gradients.get(it);
+        if (!g || it.box.w <= 0 || it.box.h <= 0) continue;
+        cs.save();
+        this.clipBox(it.clip);
+        // 箱ローカルの CSS px 空間（左上原点・y 下向き）へ写す。シェーディングの座標系もこれ。
+        cs.transform(PX_TO_PT, 0, 0, -PX_TO_PT, this.X(it.box.x), this.Y(it.box.y));
+        if (g.gs) cs.setGState(g.gs);
+        else this.setAlpha(it.alpha);
+        cs.shading(g.sh);
+        cs.restore();
+        this.curAlpha = 1;
       } else if (it.type === 'image') {
         const im = this.images.get(it.image.key);
         if (!im || it.w <= 0 || it.h <= 0) continue;
@@ -415,6 +584,8 @@ function buildTJ(it, ef) {
 /** @param {import('./walker/walk.js').DisplayItem} it */
 function itemTop(it) {
   if (it.type === 'rect' || it.type === 'stroke-rrect' || it.type === 'image') return it.y;
+  if (it.type === 'gradient') return it.clip.y;
+  if (it.type === 'path') return it.top;
   if (it.type === 'line') return Math.min(it.y1, it.y2) - it.width / 2;
   if (it.type === 'group' || it.type === 'clip') return it.top;
   return it.top;
@@ -423,6 +594,8 @@ function itemTop(it) {
 /** @param {import('./walker/walk.js').DisplayItem} it */
 function itemBottom(it) {
   if (it.type === 'rect' || it.type === 'stroke-rrect' || it.type === 'image') return it.y + it.h;
+  if (it.type === 'gradient') return it.clip.y + it.clip.h;
+  if (it.type === 'path') return it.bottom;
   if (it.type === 'line') return Math.max(it.y1, it.y2) + it.width / 2;
   if (it.type === 'group' || it.type === 'clip') return it.bottom;
   return it.bottom;

package/src/paginate.js

@@ -4,6 +4,7 @@
  *
  * 方針: 命令は動かさず、ページごとに「この y 範囲を描く」と決めるだけにする。
  * 境界は、アトム（テキスト行・表の行・画像・break-inside: avoid）を跨がない位置まで上へ戻す。
+ * `break-before/after: avoid` で結ばれた箱の間にも境界を置かず、置きそうなら前の箱の先頭まで戻す。
  * テーブルが次ページへ続くときは thead を各ページ先頭で繰り返し、その高さ分だけ本文を下げる。
  */
 
@@ -27,10 +28,17 @@
  * @returns {PageRange[]}
  */
 export function paginate(walk, pageHeightPx) {
+  const EPS_INIT = 0.01;
   const H = pageHeightPx;
   const total = walk.height;
   const atoms = [...walk.atoms].sort((a, b) => a.top - b.top);
   const breaks = [...new Set(walk.breaks)].sort((a, b) => a - b);
+  // break-before/after: avoid で結ばれた箱。
+  // 境界は次の箱の「先頭」ではなく「最初の行」まで許せない（line-height の半行分だけ箱の上端より下に来るため）。
+  const joins = (walk.joins ?? []).map((j) => {
+    const first = atoms.find((a) => a.top >= j.end - EPS_INIT);
+    return { start: j.start, limit: first ? Math.max(first.top, j.end) : j.end, pullTo: j.pullTo };
+  });
   const EPS = 0.01;
 
   /** @type {PageRange[]} */
@@ -110,6 +118,17 @@ export function paginate(walk, pageHeightPx) {
             moved = true;
           }
         }
+        // break-before/after: avoid — 結ばれた 2 つの箱の間に境界があれば、前の箱の先頭まで戻す
+        for (const j of joins) {
+          // 結んだ範囲がページに収まらないなら諦める（戻しても同じ位置で切ることになる）
+          if (j.limit - j.pullTo > capacity) continue;
+          // 戻し先がページ先頭以前だと空ページになるので諦める
+          if (j.pullTo <= start + EPS) continue;
+          if (end >= j.start - EPS && end <= j.limit + EPS && end > j.pullTo + EPS) {
+            end = j.pullTo;
+            moved = true;
+          }
+        }
       }
       // 上げ過ぎて空ページになる場合（ページより大きいアトム）は容量いっぱいで切る
       if (end <= start + EPS) end = Math.min(start + capacity, total);

package/src/pdf/content.js

@@ -136,8 +136,41 @@ export class ContentStream {
     return this;
   }
 
-  fill() {
-    this.ops.push('f');
+  /** @param {0|1|2} join */
+  lineJoin(join) {
+    this.ops.push(`${join} j`);
+    return this;
+  }
+
+  /** @param {number} limit */
+  miterLimit(limit) {
+    this.ops.push(`${num(limit)} M`);
+    return this;
+  }
+
+  /** @param {boolean} [evenOdd] */
+  fill(evenOdd = false) {
+    this.ops.push(evenOdd ? 'f*' : 'f');
+    return this;
+  }
+
+  /** 塗りと線の両方（B / B*） @param {boolean} [evenOdd] */
+  fillAndStroke(evenOdd = false) {
+    this.ops.push(evenOdd ? 'B*' : 'B');
+    return this;
+  }
+
+  /**
+   * 正規化済みのパス（M / L / C / Z）を出力する。
+   * @param {import('../walker/svg-path.js').PathSeg[]} segs
+   */
+  path(segs) {
+    for (const s of segs) {
+      if (s[0] === 'M') this.moveTo(s[1], s[2]);
+      else if (s[0] === 'L') this.lineTo(s[1], s[2]);
+      else if (s[0] === 'C') this.curveTo(s[1], s[2], s[3], s[4], s[5], s[6]);
+      else this.closePath();
+    }
     return this;
   }
 
@@ -146,6 +179,15 @@ export class ContentStream {
     return this;
   }
 
+  /**
+   * シェーディングを現在のクリップ範囲いっぱいに塗る。
+   * @param {string} name  Shading リソース名
+   */
+  shading(name) {
+    this.ops.push(`/${name} sh`);
+    return this;
+  }
+
   /** 現在のパスでクリップして新しいパスを開始する */
   clip() {
     this.ops.push('W n');

package/src/pdf/outline.js

@@ -0,0 +1,103 @@
+// @ts-check
+/**
+ * しおり（/Outlines）とリンク注釈（/Annots）の組み立て。
+ */
+import { Name, pdfString } from './writer.js';
+
+/**
+ * @typedef {{page: number, x: number, y: number}} DestPoint  飛び先（0 始まりのページ番号と、そのページの PDF 座標）
+ */
+
+/**
+ * リンク注釈を作る。
+ * @param {import('./writer.js').PdfWriter} writer
+ * @param {{x: number, y: number, w: number, h: number}} rect  PDF 座標（左下原点）
+ * @param {{uri: string}|{dest: import('./writer.js').PdfValue}} action
+ * @returns {import('./writer.js').Ref}
+ */
+export function buildLinkAnnot(writer, rect, action) {
+  /** @type {{[key: string]: import('./writer.js').PdfValue}} */
+  const annot = {
+    Type: new Name('Annot'),
+    Subtype: new Name('Link'),
+    Rect: [rect.x, rect.y, rect.x + rect.w, rect.y + rect.h],
+    // 既定の枠線を消す（多くのビューアは描かないが、仕様上は残る）
+    Border: [0, 0, 0],
+    F: 4, // Print
+  };
+  if ('uri' in action) annot.A = { S: new Name('URI'), URI: pdfString(action.uri) };
+  else annot.Dest = action.dest;
+  return writer.add(annot);
+}
+
+/**
+ * 見出しの並びから、レベルに応じた木構造のしおりを作り、カタログに入れる参照を返す。
+ * 飛び先が解決できない見出しは飛ばす。
+ *
+ * @param {import('./writer.js').PdfWriter} writer
+ * @param {{level: number, text: string, dest: import('./writer.js').PdfValue|null}[]} entries
+ * @returns {import('./writer.js').Ref|null}
+ */
+export function buildOutline(writer, entries) {
+  const usable = entries.filter((e) => e.dest !== null);
+  if (!usable.length) return null;
+
+  /**
+   * @typedef {{level: number, text: string, dest: import('./writer.js').PdfValue, children: Node[], ref: import('./writer.js').Ref}} Node
+   */
+  /** @type {Node[]} */
+  const roots = [];
+  /** @type {Node[]} 現在の祖先チェーン */
+  const stack = [];
+  for (const e of usable) {
+    /** @type {Node} */
+    const node = { level: e.level, text: e.text, dest: /** @type {import('./writer.js').PdfValue} */ (e.dest), children: [], ref: writer.reserve() };
+    while (stack.length && /** @type {Node} */ (stack[stack.length - 1]).level >= node.level) stack.pop();
+    const parent = stack[stack.length - 1];
+    if (parent) parent.children.push(node);
+    else roots.push(node);
+    stack.push(node);
+  }
+
+  const outlineRef = writer.reserve();
+
+  /**
+   * 兄弟の並びを書き出し、開いている項目数（Count 用）を返す。
+   * @param {Node[]} nodes
+   * @param {import('./writer.js').Ref} parentRef
+   * @returns {number}
+   */
+  const emit = (nodes, parentRef) => {
+    let total = 0;
+    nodes.forEach((node, i) => {
+      const childCount = emit(node.children, node.ref);
+      /** @type {{[key: string]: import('./writer.js').PdfValue}} */
+      const dict = {
+        Title: pdfString(node.text),
+        Parent: parentRef,
+        Dest: node.dest,
+      };
+      const prev = nodes[i - 1];
+      const next = nodes[i + 1];
+      if (prev) dict.Prev = prev.ref;
+      if (next) dict.Next = next.ref;
+      if (node.children.length) {
+        dict.First = /** @type {Node} */ (node.children[0]).ref;
+        dict.Last = /** @type {Node} */ (node.children[node.children.length - 1]).ref;
+        dict.Count = childCount; // 正の値 = 既定で開いた状態
+      }
+      writer.set(node.ref, dict);
+      total += 1 + childCount;
+    });
+    return total;
+  };
+
+  const count = emit(roots, outlineRef);
+  writer.set(outlineRef, {
+    Type: new Name('Outlines'),
+    First: /** @type {Node} */ (roots[0]).ref,
+    Last: /** @type {Node} */ (roots[roots.length - 1]).ref,
+    Count: count,
+  });
+  return outlineRef;
+}

package/src/pdf/shading.js

@@ -0,0 +1,113 @@
+// @ts-check
+/**
+ * 軸シェーディング（ShadingType 2）の生成。
+ *
+ * 色は Type 2（指数補間）関数を色止めの数だけ作り、Type 3（継ぎ合わせ）でつなぐ。
+ * 色止めごとにアルファが変わる場合は、同じ形のグレースケールシェーディングを
+ * 輝度ソフトマスクにして再現する（PDF には色とアルファを同時に持つシェーディングが無いため）。
+ */
+import { Name } from './writer.js';
+
+/**
+ * @typedef {import('../walker/gradient.js').GradientStop} GradientStop
+ */
+
+/**
+ * 色止めから Type 2/3 関数を作る。
+ * @param {import('./writer.js').PdfWriter} writer
+ * @param {GradientStop[]} stops
+ * @param {(c: import('../units.js').Rgba) => number[]} pick  色から成分配列を取り出す（RGB か グレー）
+ * @returns {import('./writer.js').Ref}
+ */
+function buildFunction(writer, stops, pick) {
+  const first = /** @type {GradientStop} */ (stops[0]);
+  const last = /** @type {GradientStop} */ (stops[stops.length - 1]);
+  const span = last.t - first.t;
+  // 全区間が 1 点に潰れている場合は単色
+  if (!(span > 0)) {
+    return writer.add({ FunctionType: 2, Domain: [0, 1], C0: pick(first.color), C1: pick(last.color), N: 1 });
+  }
+  if (stops.length === 2) {
+    return writer.add({ FunctionType: 2, Domain: [0, 1], C0: pick(first.color), C1: pick(last.color), N: 1 });
+  }
+  /** @type {import('./writer.js').PdfValue[]} */
+  const functions = [];
+  /** @type {number[]} */
+  const bounds = [];
+  /** @type {number[]} */
+  const encode = [];
+  for (let i = 0; i < stops.length - 1; i++) {
+    const a = /** @type {GradientStop} */ (stops[i]);
+    const b = /** @type {GradientStop} */ (stops[i + 1]);
+    functions.push(writer.add({ FunctionType: 2, Domain: [0, 1], C0: pick(a.color), C1: pick(b.color), N: 1 }));
+    encode.push(0, 1);
+    if (i > 0) bounds.push((a.t - first.t) / span);
+  }
+  return writer.add({ FunctionType: 3, Domain: [0, 1], Functions: functions, Bounds: bounds, Encode: encode });
+}
+
+/**
+ * 軸シェーディングの辞書を作る。座標は PDF 座標（pt）。
+ *
+ * @param {import('./writer.js').PdfWriter} writer
+ * @param {{x0: number, y0: number, x1: number, y1: number}} coords
+ * @param {GradientStop[]} stops
+ * @param {'rgb'|'gray'} space
+ * @returns {import('./writer.js').Ref}
+ */
+export function buildAxialShading(writer, coords, stops, space) {
+  const pick =
+    space === 'rgb'
+      ? (/** @type {import('../units.js').Rgba} */ c) => [c.r, c.g, c.b]
+      : (/** @type {import('../units.js').Rgba} */ c) => [c.a];
+  return writer.add({
+    ShadingType: 2,
+    ColorSpace: new Name(space === 'rgb' ? 'DeviceRGB' : 'DeviceGray'),
+    Coords: [coords.x0, coords.y0, coords.x1, coords.y1],
+    Function: buildFunction(writer, stops, pick),
+    Extend: [true, true],
+  });
+}
+
+/**
+ * 色止めのアルファが一定ならその値、そうでなければ null。
+ * @param {GradientStop[]} stops
+ * @returns {number|null}
+ */
+export function uniformAlpha(stops) {
+  const a = /** @type {GradientStop} */ (stops[0]).color.a;
+  return stops.every((s) => Math.abs(s.color.a - a) < 0.002) ? a : null;
+}
+
+/**
+ * アルファが変化するグラデーション用の輝度ソフトマスクを作る。
+ * グレースケールのシェーディングを描くフォーム XObject を /SMask に入れた ExtGState を返す。
+ *
+ * @param {import('./writer.js').PdfWriter} writer
+ * @param {{x0: number, y0: number, x1: number, y1: number}} coords  PDF 座標
+ * @param {GradientStop[]} stops
+ * @param {{x: number, y: number, w: number, h: number}} bbox  マスクを塗る範囲（PDF 座標）
+ * @param {number} groupAlpha  要素から継承した不透明度（グラデーション全体に掛かる）
+ * @returns {Promise<import('./writer.js').Ref>} ExtGState の参照
+ */
+export async function buildAlphaMaskGState(writer, coords, stops, bbox, groupAlpha) {
+  const scaled = groupAlpha === 1 ? stops : stops.map((s) => ({ t: s.t, color: { ...s.color, a: s.color.a * groupAlpha } }));
+  const shading = buildAxialShading(writer, coords, scaled, 'gray');
+  const content = new TextEncoder().encode(`q ${bbox.x} ${bbox.y} ${bbox.w} ${bbox.h} re W n /Sh0 sh Q\n`);
+  const form = await writer.addStream(
+    {
+      Type: new Name('XObject'),
+      Subtype: new Name('Form'),
+      BBox: [bbox.x, bbox.y, bbox.x + bbox.w, bbox.y + bbox.h],
+      Group: { Type: new Name('Group'), S: new Name('Transparency'), CS: new Name('DeviceGray') },
+      Resources: { Shading: { Sh0: shading } },
+    },
+    content,
+  );
+  return writer.add({
+    Type: new Name('ExtGState'),
+    SMask: { Type: new Name('Mask'), S: new Name('Luminosity'), G: form, BC: [0] },
+    ca: 1,
+    CA: 1,
+  });
+}