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

package/examples/cdn.html

@@ -61,11 +61,11 @@
 
 <!--
   ここが CDN からの読み込み。type="module" が要る。
-  バージョン（@0.2.1）は必ず固定する。外すと最新版が読み込まれ、更新のたびに挙動が変わりうる。
+  バージョン（@0.3.0）は必ず固定する。外すと最新版が読み込まれ、更新のたびに挙動が変わりうる。
 -->
 <script type="module">
   import * as ReceiptHtmlToPdf
-    from 'https://cdn.jsdelivr.net/npm/@hidemikimura/receipt-html-to-pdf@0.2.1/dist/receipt-html-to-pdf.min.js';
+    from 'https://cdn.jsdelivr.net/npm/@hidemikimura/receipt-html-to-pdf@0.3.0/dist/receipt-html-to-pdf.min.js';
 
   // type="module" でない普通のスクリプトからも使えるようにグローバルへ載せる
   window.ReceiptHtmlToPdf = ReceiptHtmlToPdf;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hidemikimura/receipt-html-to-pdf",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Receipt html to pdf — ブラウザ内で HTML/CSS をテキスト選択可能なベクター PDF に変換するライブラリ（日本の領収証・適格請求書向け）",
   "license": "MIT",
   "author": "Hidemi Kimura",

package/skills/receipt-html-to-pdf/SKILL.md

@@ -45,7 +45,7 @@ npm を使わない場合は CDN の URL をそのまま `import` できる（`d
 ```html
 <script type="module">
   import { registerFont, htmlToPdf, downloadPdf }
-    from 'https://cdn.jsdelivr.net/npm/@hidemikimura/receipt-html-to-pdf@0.2.1/dist/receipt-html-to-pdf.min.js';
+    from 'https://cdn.jsdelivr.net/npm/@hidemikimura/receipt-html-to-pdf@0.3.0/dist/receipt-html-to-pdf.min.js';
 </script>
 ```
 
@@ -92,16 +92,21 @@ npm を使わない場合は CDN の URL をそのまま `import` できる（`d
 | `baseUrl` | 現在の文書 | 相対 URL（フォント・画像）の基準 |
 | `output` | `'blob'` | `'uint8array'` `'dataurl'` |
 | `onWarning` | — | 未対応 CSS・欠落グリフ・画像失敗の通知。**必ず配線する** |
+| `onProgress` | — | `render` → `walk` → `layout`（`totalPages` 確定）→ `page`（1 ページずつ）→ `done`。長い文書の進捗表示に使う |
 
 ## 対応している CSS の要点
 
 レイアウト系（`display` 全般・Flexbox・Grid・テーブル・`position`・`margin`・`padding`・`white-space`・`word-break`・`text-align`・`line-height`・`letter-spacing`）は**ブラウザの計算結果をそのまま使うので全部そのとおりに出る**。追加実装は不要。
 
-描画系で対応しているもの: `color`、`background-color`、`background-image: url()`（単一・`no-repeat`）、`border-*`（辺ごと、solid / dashed / dotted）、`border-collapse: collapse`、`border-radius`、`opacity`、`text-decoration`（underline / line-through）、`overflow: hidden` のクリップ、`<img>`（PNG 透過・JPEG・`object-fit`）、2D `transform`、`::before` / `::after`（引用文字列の `content` のみ）。
+描画系で対応しているもの: `color`、`background-color`、`background-image: url()`（単一。`background-repeat` は `repeat` / `-x` / `-y` / `space` / `round` に対応）、`background-image: linear-gradient()`（ベクター。色止めごとのアルファも可）、`border-*`（辺ごと、solid / dashed / dotted）、`border-collapse: collapse`、`border-radius`、`opacity`、`text-decoration`（underline / line-through）、`overflow: hidden` のクリップ、`<img>`（PNG 透過・JPEG・`object-fit`）、インライン `<svg>`（パス・基本図形をベクター変換）、2D `transform`、`::before` / `::after`（引用文字列の `content` のみ）。
 
-**出力されないもの**（`onWarning` に `unsupported-css` が届く）: `box-shadow`、`text-shadow`、グラデーション、`filter`、`clip-path`、`outline`、縦書き、3D transform、`counter()` の content、インライン `<svg>` / `<canvas>` / `<video>`。
+GSUB の**単一置換**（`zero`・`jp90` などの異体字・`fwid` / `hwid`・`smcp`）は `font-variant-*` / `font-feature-settings` の指定どおりに再現する。**合字（`liga` / `dlig`）は未対応**。
 
-代替の指針: 影 → ボーダーか薄い背景色。グラデーション → 単色か画像。インライン SVG → `<img src="x.svg">`（ラスタライズされて埋め込まれる）。
+**数字の桁を揃えたいとき**: `tabular-nums` は日本語フォントでは効かないことが多い（BIZ UDPGothic・Noto Sans JP などに `tnum` 機能が無く、ブラウザ側でも何も起きない）。数字の送り幅がもともと揃っているフォント（BIZ UD**G**othic など）を選ぶか、表のセルを右揃え + 列幅固定にする。
+
+**出力されないもの**（`onWarning` に `unsupported-css` が届く）: `box-shadow`、`text-shadow`、`repeating-linear-gradient` / `radial-gradient` / `conic-gradient`、`filter`、`clip-path`、`outline`、縦書き、3D transform、`counter()` の content、`<canvas>` / `<video>`、SVG の `<text>` / `<use>` / paint server（`fill="url(#id)"`）。
+
+代替の指針: 影 → ボーダーか薄い背景色。放射・円錐グラデーション → `linear-gradient` か単色、画像。SVG の文字 → 事前にパス化しておく（`<text>` は飛ばされる）。`<img src="x.svg">` はラスタライズされるので、ベクターにしたいならインラインで置く。
 
 全プロパティの詳細表は `docs/css-support.md`。
 
@@ -112,6 +117,8 @@ npm を使わない場合は CDN の URL をそのまま `import` できる（`d
 - テキストの行、`<tr>`、`<thead>`、`<tfoot>`、`<img>`
 - `break-inside: avoid`（`page-break-inside: avoid`）を指定した要素
 
+`break-after: avoid` / `break-before: avoid` を書くと、隣の箱と同じページに保つ（見出しがページ末尾に取り残されるのを防ぐ）。兄弟が無ければ親をさかのぼるので、`<section>` の最後の見出しに書いても次の `<section>` と結びつく。結んだ範囲が 1 ページに収まらない場合は諦めて普通に分割する。
+
 強制改ページは `break-before: page` / `break-after: page`（`page-break-*: always` も可）。表が次ページへ続くときは **`<thead>` が各ページ先頭に、`<tfoot>` がそのページ最後の行の直下に**自動で繰り返される。
 
 ページ番号を入れるなら:
@@ -120,7 +127,17 @@ npm を使わない場合は CDN の URL をそのまま `import` できる（`d
 footer: '<div style="text-align:center;font-size:8pt">{{pageNumber}} / {{totalPages}}</div>'
 ```
 
-`orphans` / `widows` / `break-*: avoid` / `@page` は未対応。用紙サイズと余白は `options.page` で指定する。
+`orphans` / `widows` / `@page` は未対応。用紙サイズと余白は `options.page` で指定する。
+
+## 長い文書
+
+変換は途中でイベントループへ戻すので、数百ページでも画面は固まらない（所要時間は 1 割ほど増える）。進捗表示を出すなら `onProgress` を配線する。
+
+```js
+onProgress: (p) => { if (p.phase === 'page') bar.value = p.page / p.totalPages; }
+```
+
+デコード済みの画像データは PDF へ埋め込んだ時点で解放される。同じ画像を次の変換でも使う場合は読み直しになる（速度よりメモリを優先している）。
 
 ## 変換対象の要素についての決まり
 

package/skills/receipt-html-to-pdf/references/receipt-format.md

@@ -51,6 +51,8 @@ taxable8  =  4,200  →  tax8  = floor(4200 * 0.08)  =   336
 ## このライブラリで組むときの注意
 
 - 金額欄の右寄せ（`text-align: right`）はブラウザの計算どおりに出るので追加実装は不要
-- `font-variant-numeric: tabular-nums` は GSUB 依存で**効かない**。数字が元から等幅のフォント（BIZ UDPGothic は等幅）を使う
+- **金額の桁揃え**: `font-variant-numeric: tabular-nums` は日本語フォントでは効かないことが多い。BIZ UDPGothic・Noto Sans JP・M PLUS 1p・IBM Plex Sans JP・Zen Kaku Gothic New のいずれにも `tnum` 機能が無く、ブラウザ側でも何も起きない。しかも **BIZ UDPGothic はプロポーショナル体で、数字の `1` だけ幅が狭い**（送り幅 1290、他は 1556 / unitsPerEm 2048）ため、そのままでは縦に揃わない
+  - 対策 1: 数字の送り幅がもともと揃っているフォントを使う（BIZ UD**G**othic は全数字 1024、Noto Sans JP も一定）
+  - 対策 2: 金額は表のセルに入れて右揃え + 列幅固定にする（この方法は今のままで正しく出る）
 - 明細が長くなる帳票では、集計ブロックと発行者ブロックに `break-inside: avoid` を付けるとページ境界で割れない
 - `<thead>` に見出し行、`<tfoot>` に合計行を置くと、複数ページ時に各ページへ自動で繰り返される

package/src/font/gsub.js

@@ -0,0 +1,229 @@
+// @ts-check
+/**
+ * GSUB（グリフ置換）の単一置換だけを読む。
+ *
+ * ブラウザが `font-variant-*` / `font-feature-settings` で有効にした機能を、
+ * 同じ結果になるように gid → gid の置換として再現する。
+ * 置換は埋め込み前に解決するので、PDF に GSUB テーブル自体は入らない。
+ *
+ * 対応するのは Lookup タイプ 1（単一置換、フォーマット 1 / 2）と、
+ * それを包むタイプ 7（拡張）だけ。タイプ 4（合字）はグリフ数が変わるため、
+ * 1 文字ずつ位置を実測する走査モデルでは扱えない。
+ */
+
+/**
+ * @typedef {object} GsubTable
+ * @property {Map<string, number[]>} features  機能タグ → Lookup 番号
+ * @property {(index: number) => Map<number, number>|null} lookup  単一置換の Lookup を読む（対応外なら null）
+ */
+
+/**
+ * GSUB を読む。無い・壊れている場合は null。
+ * @param {import('./parse.js').ParsedFont} font
+ * @returns {GsubTable|null}
+ */
+export function parseGsub(font) {
+  const t = font.tables.get('GSUB');
+  if (!t || t.length < 10) return null;
+  const dv = new DataView(font.data.buffer, font.data.byteOffset, font.data.byteLength);
+  const base = t.offset;
+  try {
+    const featureListOff = base + dv.getUint16(base + 6);
+    const lookupListOff = base + dv.getUint16(base + 8);
+
+    /** @type {Map<string, number[]>} */
+    const features = new Map();
+    const featureCount = dv.getUint16(featureListOff);
+    for (let i = 0; i < featureCount; i++) {
+      const rec = featureListOff + 2 + i * 6;
+      const tag = String.fromCharCode(dv.getUint8(rec), dv.getUint8(rec + 1), dv.getUint8(rec + 2), dv.getUint8(rec + 3));
+      const featureOff = featureListOff + dv.getUint16(rec + 4);
+      const count = dv.getUint16(featureOff + 2);
+      const list = features.get(tag) ?? [];
+      for (let j = 0; j < count; j++) list.push(dv.getUint16(featureOff + 4 + j * 2));
+      features.set(tag, list);
+    }
+
+    const lookupCount = dv.getUint16(lookupListOff);
+    /** @type {Map<number, Map<number, number>|null>} */
+    const cache = new Map();
+    /** @param {number} index */
+    const lookup = (index) => {
+      if (cache.has(index)) return /** @type {Map<number, number>|null} */ (cache.get(index) ?? null);
+      let result = null;
+      if (index >= 0 && index < lookupCount) {
+        const off = lookupListOff + dv.getUint16(lookupListOff + 2 + index * 2);
+        result = readLookup(dv, off, dv.getUint16(off), dv.getUint16(off + 4), off + 6);
+      }
+      cache.set(index, result);
+      return result;
+    };
+
+    return { features, lookup };
+  } catch {
+    return null; // 壊れた GSUB は無いものとして扱う
+  }
+}
+
+/**
+ * @param {DataView} dv
+ * @param {number} lookupOff
+ * @param {number} type
+ * @param {number} subTableCount
+ * @param {number} offsetsAt  サブテーブルオフセット配列の位置
+ * @returns {Map<number, number>|null}
+ */
+function readLookup(dv, lookupOff, type, subTableCount, offsetsAt) {
+  if (type !== 1 && type !== 7) return null;
+  /** @type {Map<number, number>} */
+  const map = new Map();
+  for (let i = 0; i < subTableCount; i++) {
+    let sub = lookupOff + dv.getUint16(offsetsAt + i * 2);
+    if (type === 7) {
+      // 拡張: 実体の型とオフセットを読み直す
+      if (dv.getUint16(sub) !== 1) continue;
+      if (dv.getUint16(sub + 2) !== 1) continue; // 単一置換以外は対象外
+      sub += dv.getUint32(sub + 4);
+    }
+    readSingleSubst(dv, sub, map);
+  }
+  return map.size ? map : null;
+}
+
+/**
+ * SingleSubst（フォーマット 1 / 2）を map に読み込む。
+ * @param {DataView} dv
+ * @param {number} off
+ * @param {Map<number, number>} map
+ */
+function readSingleSubst(dv, off, map) {
+  const format = dv.getUint16(off);
+  const coverage = readCoverage(dv, off + dv.getUint16(off + 2));
+  if (format === 1) {
+    const delta = dv.getInt16(off + 4);
+    for (const gid of coverage) map.set(gid, (gid + delta) & 0xffff);
+  } else if (format === 2) {
+    const count = dv.getUint16(off + 4);
+    for (let i = 0; i < coverage.length && i < count; i++) {
+      map.set(/** @type {number} */ (coverage[i]), dv.getUint16(off + 6 + i * 2));
+    }
+  }
+}
+
+/**
+ * Coverage テーブルを、カバレッジ番号順のグリフ配列として読む。
+ * @param {DataView} dv
+ * @param {number} off
+ * @returns {number[]}
+ */
+function readCoverage(dv, off) {
+  const format = dv.getUint16(off);
+  /** @type {number[]} */
+  const out = [];
+  if (format === 1) {
+    const count = dv.getUint16(off + 2);
+    for (let i = 0; i < count; i++) out.push(dv.getUint16(off + 4 + i * 2));
+  } else if (format === 2) {
+    const count = dv.getUint16(off + 2);
+    for (let i = 0; i < count; i++) {
+      const rec = off + 4 + i * 6;
+      const start = dv.getUint16(rec);
+      const end = dv.getUint16(rec + 2);
+      const startIndex = dv.getUint16(rec + 4);
+      for (let g = start; g <= end; g++) out[startIndex + (g - start)] = g;
+    }
+  }
+  return out;
+}
+
+/**
+ * 機能タグの集合から置換関数を作る。Lookup 番号の小さい順に適用する。
+ * @param {import('./parse.js').ParsedFont} font
+ * @param {string[]} tags
+ * @returns {((gid: number) => number)|null}  置換が 1 つも無ければ null
+ */
+export function buildSubstitution(font, tags) {
+  const gsub = parseGsub(font);
+  if (!gsub) return null;
+  /** @type {number[]} */
+  const indices = [];
+  for (const tag of tags) for (const i of gsub.features.get(tag) ?? []) if (!indices.includes(i)) indices.push(i);
+  if (!indices.length) return null;
+  indices.sort((a, b) => a - b);
+  /** @type {Map<number, number>[]} */
+  const maps = [];
+  for (const i of indices) {
+    const m = gsub.lookup(i);
+    if (m) maps.push(m);
+  }
+  if (!maps.length) return null;
+  /** @type {Map<number, number>} */
+  const memo = new Map();
+  return (gid) => {
+    const hit = memo.get(gid);
+    if (hit !== undefined) return hit;
+    let g = gid;
+    for (const m of maps) g = m.get(g) ?? g;
+    memo.set(gid, g);
+    return g;
+  };
+}
+
+/** CSS のキーワード → OpenType の機能タグ */
+const VARIANT_TAGS = /** @type {Record<string, string>} */ ({
+  // font-variant-numeric
+  'lining-nums': 'lnum',
+  'oldstyle-nums': 'onum',
+  'proportional-nums': 'pnum',
+  'tabular-nums': 'tnum',
+  'diagonal-fractions': 'frac',
+  'stacked-fractions': 'afrc',
+  ordinal: 'ordn',
+  'slashed-zero': 'zero',
+  // font-variant-caps
+  'small-caps': 'smcp',
+  'all-small-caps': 'c2sc',
+  'petite-caps': 'pcap',
+  'all-petite-caps': 'c2pc',
+  unicase: 'unic',
+  'titling-caps': 'titl',
+  // font-variant-east-asian
+  jis78: 'jp78',
+  jis83: 'jp83',
+  jis90: 'jp90',
+  jis04: 'jp04',
+  simplified: 'smpl',
+  traditional: 'trad',
+  'full-width': 'fwid',
+  'proportional-width': 'pwid',
+  ruby: 'ruby',
+});
+
+/**
+ * computed style から、ブラウザが有効にしている機能タグを集める。
+ * 既定で有効な機能（ccmp / liga / calt）は含めない（合字は扱えないため）。
+ *
+ * @param {CSSStyleDeclaration} style
+ * @returns {string[]}
+ */
+export function featureTagsOf(style) {
+  /** @type {Set<string>} */
+  const tags = new Set();
+  const words = `${style.fontVariantNumeric ?? ''} ${style.fontVariantCaps ?? ''} ${style.fontVariantEastAsian ?? ''}`.split(/\s+/);
+  for (const w of words) {
+    const tag = VARIANT_TAGS[w];
+    if (tag) tags.add(tag);
+  }
+  // font-feature-settings: "zero" 1, "jp90"
+  const ffs = style.fontFeatureSettings ?? '';
+  if (ffs && ffs !== 'normal') {
+    for (const part of ffs.split(',')) {
+      const m = /^\s*["']([A-Za-z0-9]{4})["']\s*(.*)$/.exec(part);
+      if (!m) continue;
+      const value = /** @type {string} */ (m[2]).trim();
+      if (value === '0' || value === 'off') continue;
+      tags.add(/** @type {string} */ (m[1]));
+    }
+  }
+  return [...tags];
+}

package/src/index.js

@@ -10,6 +10,7 @@ import { renderDocument } from './renderer.js';
 import { walk } from './walker/walk.js';
 import { resolvePage, buildPdf } from './page.js';
 import { PX_TO_PT } from './units.js';
+import { createPacer } from './pacer.js';
 
 export { expandPrintMediaCss } from './renderer.js';
 
@@ -58,6 +59,15 @@ export { expandPrintMediaCss } from './renderer.js';
  * @property {string} [text]       missing-glyph のときの該当文字
  */
 
+/**
+ * 変換の進み具合。長い文書で進捗表示を出すために使う。
+ *
+ * @typedef {object} ConversionProgress
+ * @property {'render'|'walk'|'layout'|'page'|'done'} phase
+ * @property {number} [page]        phase が 'page' のときの 1 始まりのページ番号
+ * @property {number} [totalPages]  phase が 'layout' 以降で確定する総ページ数
+ */
+
 /**
  * @typedef {object} ConvertOptions
  * @property {PageOptions} [page]
@@ -72,6 +82,7 @@ export { expandPrintMediaCss } from './renderer.js';
  * @property {'blob'|'uint8array'|'dataurl'} [output='blob']
  * @property {string} [baseUrl]                  相対 URL（フォント・画像）の基準。既定は現在の文書
  * @property {(warning: ConversionWarning) => void} [onWarning]
+ * @property {(progress: ConversionProgress) => void} [onProgress]  進捗通知。長い文書では途中でイベントループへ戻すので、UI を更新できる
  */
 
 /**
@@ -80,7 +91,7 @@ export { expandPrintMediaCss } from './renderer.js';
  */
 
 /** ライブラリのバージョン（package.json と同期） */
-export const version = '0.2.1';
+export const version = '0.3.0';
 
 /** モジュール共有のフォントレジストリ */
 const registry = new FontRegistry();
@@ -124,9 +135,13 @@ export async function htmlToPdf(input, options = {}) {
     throw new Error('htmlToPdf: no fonts registered. Call registerFont() with at least one TrueType font first.');
   }
   const warn = options.onWarning ?? (() => {});
+  const progress = options.onProgress ?? (() => {});
+  // 長い変換でメインスレッドを占有しないよう、一定時間ごとにイベントループへ戻す
+  const pacer = createPacer();
   const geo = resolvePage(options.page);
   const widthPx = (geo.width - geo.left - geo.right) / PX_TO_PT;
 
+  progress({ phase: 'render' });
   const rendered = await renderDocument(input, {
     widthPx,
     stylesheets: options.stylesheets ?? 'inherit',
@@ -141,6 +156,7 @@ export async function htmlToPdf(input, options = {}) {
     fontFallback: options.fontFallback ?? [],
     warn,
     textMeasure: options.textMeasure ?? 'auto',
+    pacer,
   };
   const renderOpts = {
     widthPx,
@@ -151,6 +167,7 @@ export async function htmlToPdf(input, options = {}) {
   };
 
   try {
+    progress({ phase: 'walk' });
     const body = await walk(rendered.root, walkCtx);
     const header = options.header ? await makeDecoration(options.header, renderOpts, walkCtx) : null;
     const footer = options.footer ? await makeDecoration(options.footer, renderOpts, walkCtx) : null;
@@ -159,7 +176,11 @@ export async function htmlToPdf(input, options = {}) {
       metadata: options.metadata,
       header,
       footer,
+      pacer,
+      progress,
+      warn,
     });
+    progress({ phase: 'done' });
     return toOutput(bytes, options.output ?? 'blob');
   } finally {
     rendered.destroy();

package/src/pacer.js

@@ -0,0 +1,50 @@
+// @ts-check
+/**
+ * 長い変換でメインスレッドを占有しないための、時間ベースの譲渡。
+ *
+ * 一定時間（既定 12ms）を超えて動き続けていたら 1 回だけイベントループへ戻す。
+ * 小さな文書ではほとんど発火せず、大きな文書では画面が固まらなくなる。
+ */
+
+/**
+ * マクロタスクへ譲る。`setTimeout(0)` はネストすると 4ms にクランプされるので、
+ * `scheduler.yield()` か MessageChannel を使う。
+ * @returns {Promise<void>}
+ */
+function yieldToEventLoop() {
+  const sched = /** @type {{yield?: () => Promise<void>}|undefined} */ (/** @type {any} */ (globalThis).scheduler);
+  if (sched && typeof sched.yield === 'function') return sched.yield();
+  return new Promise((resolve) => {
+    if (typeof MessageChannel === 'function') {
+      const ch = new MessageChannel();
+      ch.port1.onmessage = () => {
+        ch.port1.close();
+        resolve();
+      };
+      ch.port2.postMessage(0);
+    } else {
+      setTimeout(resolve, 0);
+    }
+  });
+}
+
+/**
+ * @typedef {() => Promise<void>} Pacer
+ */
+
+/**
+ * @param {number} [intervalMs]  この時間を超えて動き続けていたら譲る
+ * @returns {Pacer}
+ */
+export function createPacer(intervalMs = 12) {
+  const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+  let last = now();
+  return async () => {
+    if (now() - last < intervalMs) return;
+    await yieldToEventLoop();
+    last = now();
+  };
+}
+
+/** 何もしない Pacer（テストや同期実行したい場合に使う） */
+export const noPacer = /** @type {Pacer} */ (async () => {});

package/src/page.js

@@ -9,6 +9,8 @@ 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';
 
 /**
  * @typedef {object} PageGeometry
@@ -56,7 +58,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}} opts
  * @returns {Promise<Uint8Array>}
  */
 export async function buildPdf(body, geo, opts) {
@@ -113,33 +115,77 @@ 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 = [];
 
   // 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;
@@ -200,6 +246,7 @@ export async function buildPdf(body, geo, opts) {
           Font: fontDict,
           XObject: xobjDict,
           ExtGState: gstateDict,
+          Shading: shadingDict,
           ProcSet: [new Name('PDF'), new Name('Text'), new Name('ImageC')],
         },
         Contents: contentRef,
@@ -252,14 +299,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 +388,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 +504,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 +514,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;