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

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;

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/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,
+  });
+}

package/src/renderer.js

@@ -50,6 +50,7 @@ export async function renderDocument(input, opts) {
   fit();
   // レイアウトを確定させる
   void doc.body.offsetHeight;
+  warnIfTooWide(doc, opts.widthPx, opts.warn ?? (() => {}));
 
   return {
     iframe,
@@ -68,7 +69,9 @@ export async function renderDocument(input, opts) {
 function buildHtml(input, opts) {
   const baseUrl = opts.baseUrl ?? document.baseURI;
   const base = `<base href="${escapeAttr(baseUrl)}">`;
-  const reset = `<style data-rhtp-reset>html,body{margin:0;padding:0;background:transparent}html{-webkit-text-size-adjust:100%}</style>`;
+  // 親文書の body マージンが PDF に持ち込まれると内容が右へずれて右端が切れるので、
+  // !important で確実に打ち消す（用紙の余白は options.page.margin が受け持つ）。
+  const reset = `<style data-rhtp-reset>html,body{margin:0 !important;padding:0 !important;background:transparent}html{-webkit-text-size-adjust:100%}</style>`;
 
   if (typeof input === 'string') {
     // 完全な HTML 文書ならそのまま。<head> の直後に base とリセットを差し込む。
@@ -151,6 +154,29 @@ function shadowHostStyles(input, stylesheets, mediaPrint) {
   return parts.map((css) => `<style>${mediaPrint ? expandPrintMediaCss(css) : css}</style>`).join('');
 }
 
+/**
+ * 内容が本文領域より横に広いと、右側が切れたまま気づかれにくいので警告する。
+ * 固定幅 + `box-sizing: content-box` や、畳めない表が原因になりやすい。
+ *
+ * @param {Document} doc
+ * @param {number} widthPx  本文領域の幅（px）
+ * @param {(w: import('./index.js').ConversionWarning) => void} warn
+ */
+function warnIfTooWide(doc, widthPx, warn) {
+  const width = Math.max(doc.documentElement.scrollWidth, doc.body.scrollWidth);
+  const over = width - widthPx;
+  // 1px 未満は丸め誤差とみなす
+  if (over < 1) return;
+  const mm = (/** @type {number} */ px) => Math.round((px / 96) * 25.4 * 10) / 10;
+  warn({
+    code: 'other',
+    message:
+      `Content is ${Math.round(over)}px (${mm(over)}mm) wider than the page content area ` +
+      `(${Math.round(width)}px vs ${Math.round(widthPx)}px); the right side will be clipped. ` +
+      'Common causes: a fixed width plus padding/border without box-sizing: border-box, or a table that cannot shrink.',
+  });
+}
+
 /** シャドウルートを持てない要素（void 要素）。outerHTML にフォールバックする。 */
 const VOID_TAGS = new Set(['AREA', 'BASE', 'BR', 'COL', 'EMBED', 'HR', 'IMG', 'INPUT', 'LINK', 'META', 'SOURCE', 'TRACK', 'WBR']);
 

package/src/walker/gradient.js

@@ -0,0 +1,193 @@
+// @ts-check
+/**
+ * CSS の linear-gradient を PDF の軸シェーディング（ShadingType 2）に落とすための解析。
+ *
+ * 入力は computed style の値なので、色は rgb()/rgba() に、角度は deg に正規化済み。
+ * 出力は箱のローカル座標（左上原点・y 下向き・CSS px）でのグラデーション線と、
+ * 0〜1 に正規化した色止め。
+ */
+import { parseColor } from '../units.js';
+
+/**
+ * @typedef {{t: number, color: import('../units.js').Rgba}} GradientStop
+ * @typedef {{x0: number, y0: number, x1: number, y1: number, stops: GradientStop[]}} LinearGradient
+ */
+
+/**
+ * computed の background-image が単一の linear-gradient ならそれを解析する。
+ * 対応しない書式（repeating / radial / conic / 複数レイヤー）は null。
+ *
+ * @param {string} value  computed の background-image
+ * @param {number} width  箱の幅（px）
+ * @param {number} height 箱の高さ（px）
+ * @returns {LinearGradient|null}
+ */
+export function parseLinearGradient(value, width, height) {
+  const m = /^linear-gradient\((.*)\)$/s.exec(value.trim());
+  if (!m) return null;
+  const args = splitTopLevelCommas(/** @type {string} */ (m[1]));
+  if (args.length < 2) return null;
+
+  let i = 0;
+  let angle = 180; // 既定は「to bottom」
+  const first = /** @type {string} */ (args[0]).trim();
+  // `in oklab` などの補間指定は無視して sRGB で近似する
+  const head = first.replace(/^in\s+\S+(\s+\S+\s+hue)?\s*/i, '').trim();
+  const dir = parseDirection(head);
+  if (dir !== null) {
+    angle = dir;
+    i = 1;
+  } else if (/^in\s/i.test(first) && head === '') {
+    i = 1;
+  }
+
+  const rawStops = args.slice(i).map((s) => s.trim());
+  if (rawStops.length < 2) return null;
+
+  // グラデーション線の長さ（CSS 仕様: |W·sin θ| + |H·cos θ|）
+  const rad = (angle * Math.PI) / 180;
+  const sin = Math.sin(rad);
+  const cos = Math.cos(rad);
+  const length = Math.abs(width * sin) + Math.abs(height * cos);
+  if (!(length > 0)) return null;
+
+  /** @type {GradientStop[]} */
+  const stops = [];
+  for (const raw of rawStops) {
+    // "rgb(255, 0, 0) 30%" / "rgba(0, 0, 0, 0.5)" / "red 10px 20px"（二重指定）
+    const sp = splitColorAndPositions(raw);
+    if (!sp) return null;
+    const color = parseColor(sp.color);
+    if (!color) return null;
+    if (!sp.positions.length) {
+      stops.push({ t: NaN, color });
+      continue;
+    }
+    for (const pos of sp.positions) {
+      const t = resolvePosition(pos, length);
+      if (t === null) return null;
+      stops.push({ t, color });
+    }
+  }
+  if (stops.length < 2) return null;
+
+  fillMissingPositions(stops);
+
+  // 中心を通る線分。CSS の角度は 0deg = 上向き、時計回り。y は下向きなので cos を反転する。
+  const cx = width / 2;
+  const cy = height / 2;
+  const dx = sin;
+  const dy = -cos;
+  return {
+    x0: cx - (dx * length) / 2,
+    y0: cy - (dy * length) / 2,
+    x1: cx + (dx * length) / 2,
+    y1: cy + (dy * length) / 2,
+    stops,
+  };
+}
+
+/**
+ * `45deg` / `to right` / `to right bottom` を CSS 角度（0 = 上、時計回り）にする。
+ * 方向指定でなければ null。
+ * @param {string} s
+ * @returns {number|null}
+ */
+function parseDirection(s) {
+  const deg = /^(-?[\d.]+)deg$/.exec(s);
+  if (deg) return ((parseFloat(/** @type {string} */ (deg[1])) % 360) + 360) % 360;
+  const to = /^to\s+(.+)$/.exec(s);
+  if (!to) return null;
+  const words = /** @type {string} */ (to[1]).trim().split(/\s+/).sort().join(' ');
+  /** @type {Record<string, number>} */
+  const table = {
+    top: 0,
+    right: 90,
+    bottom: 180,
+    left: 270,
+    'right top': 45,
+    'bottom right': 135,
+    'bottom left': 225,
+    'left top': 315,
+  };
+  return table[words] ?? null;
+}
+
+/**
+ * 色止めを「色」と「位置（0〜2 個）」に分ける。
+ * @param {string} s
+ * @returns {{color: string, positions: string[]}|null}
+ */
+function splitColorAndPositions(s) {
+  // 関数記法（rgb(...)）を先に切り出す
+  const fn = /^([a-z-]+\([^()]*\))\s*(.*)$/i.exec(s);
+  if (fn) return { color: /** @type {string} */ (fn[1]), positions: splitWords(/** @type {string} */ (fn[2])) };
+  const kw = /^(\S+)\s*(.*)$/.exec(s);
+  if (!kw) return null;
+  return { color: /** @type {string} */ (kw[1]), positions: splitWords(/** @type {string} */ (kw[2])) };
+}
+
+/** @param {string} s */
+function splitWords(s) {
+  const t = s.trim();
+  return t ? t.split(/\s+/) : [];
+}
+
+/**
+ * 位置指定（30% / 10px）をグラデーション線上の 0〜1 にする。
+ * @param {string} pos
+ * @param {number} length
+ * @returns {number|null}
+ */
+function resolvePosition(pos, length) {
+  const pct = /^(-?[\d.]+)%$/.exec(pos);
+  if (pct) return parseFloat(/** @type {string} */ (pct[1])) / 100;
+  const px = /^(-?[\d.]+)px$/.exec(pos);
+  if (px) return parseFloat(/** @type {string} */ (px[1])) / length;
+  return null;
+}
+
+/**
+ * 位置の無い色止めを埋める。両端は 0 と 1、間は等間隔。
+ * さらに前の位置を下回らないよう単調にする（CSS 仕様）。
+ * @param {GradientStop[]} stops
+ */
+function fillMissingPositions(stops) {
+  const last = stops.length - 1;
+  if (Number.isNaN(/** @type {number} */ (stops[0]?.t))) /** @type {GradientStop} */ (stops[0]).t = 0;
+  if (Number.isNaN(/** @type {number} */ (stops[last]?.t))) /** @type {GradientStop} */ (stops[last]).t = 1;
+  for (let i = 1; i < last; i++) {
+    if (!Number.isNaN(/** @type {number} */ (stops[i]?.t))) continue;
+    // 次に位置が決まっている色止めまでを等分する
+    let j = i + 1;
+    while (j < last && Number.isNaN(/** @type {number} */ (stops[j]?.t))) j++;
+    const from = /** @type {number} */ (stops[i - 1]?.t);
+    const to = /** @type {number} */ (stops[j]?.t);
+    for (let k = i; k < j; k++) {
+      /** @type {GradientStop} */ (stops[k]).t = from + ((to - from) * (k - i + 1)) / (j - i + 1);
+    }
+    i = j - 1;
+  }
+  for (let i = 1; i < stops.length; i++) {
+    const prev = /** @type {number} */ (stops[i - 1]?.t);
+    if (/** @type {number} */ (stops[i]?.t) < prev) /** @type {GradientStop} */ (stops[i]).t = prev;
+  }
+}
+
+/** @param {string} s */
+function splitTopLevelCommas(s) {
+  /** @type {string[]} */
+  const out = [];
+  let depth = 0;
+  let cur = '';
+  for (const ch of s) {
+    if (ch === '(') depth++;
+    else if (ch === ')') depth--;
+    if (ch === ',' && depth === 0) {
+      out.push(cur);
+      cur = '';
+    } else cur += ch;
+  }
+  if (cur.trim()) out.push(cur);
+  return out;
+}