開発者向け

const pp = window.__pixelpont;
await pp.connect('<passphrase>');
const report = await pp.measure({ scope: 'viewport' });

await window.__pixelpont.help(topic?)

help() は索引を返します。help("<メソッド名>") は、引数・戻り値の形・例を返します。
help("<メソッド名>", page) は、長い説明を短いページ（900 文字未満）に分けた 1 ページを返します。
戻り値が途中で切れる道具のためのもので、各ページに、次のページの読み方が書かれています。
例: await __pixelpont.help("updateLayer")

await window.__pixelpont.connect(passphrase, options?)

API は、最初は閉じています。利用者が PixelPont のパネルで「AI 用の指示文をコピー」を押し、
コピーした文面を AI に貼ると開きます。その文面に、合言葉が入っています。
passphrase: その文面にある文字列。options: { client?: string } — 呼び出す AI エージェントや
道具の短い名前（省略可。パネルに、自己申告の名前として表示されます）。
利用者が開いているタブを操作できないブラウザ自動化の道具は、同じサイト（同じホストとポート）を
自分のタブで開き、そこで connect() を呼べます。PixelPont は、同じカンプのまま、そのタブへ移ります。
そのために、フォーカスの移動やクリックは要りません。
戻り値は { ok, minutesLeft }。ページを再読み込みすると、ページは合言葉を忘れるので、
同じ合言葉でもう一度 connect() が要ります。
接続は、30 分呼び出しが無いとき、パネルを閉じたとき、ページが別のドメインへ移ったときに閉じます。
その後は、利用者が新しい合言葉をコピーし直す必要があります。
エラー not-connected / invalid-token は、利用者が指示文をコピーして貼り直す必要があることを示します。
例: await __pixelpont.connect("<passphrase>", { client: "my-agent" })

await window.__pixelpont.disconnect()

このページの API を閉じ、ページに描いた枠や色の差を消します。
レイヤーの設定は、そのまま残ります。戻り値は { ok }。
作業の終わりに呼ぶことを想定しています。呼ぶと、パネルに AI の作業が終わったことが表示されます。

await window.__pixelpont.getState()

戻り値は { ok, ready, domain, visible, activeLayerId, layers[], viewport }。
layers[]: { id, name, active, x, y, scale, opacity, blendMode, locked, syncScroll,
  autoCenterX, naturalWidth, naturalHeight, designWidth, renderedWidth }。
ページに描かれるのは、アクティブなレイヤーだけです。x / y / renderedWidth は CSS px。
designWidth は、カンプ画像の幅（カンプ px）。カンプ px は、CSS px を scale で割った値です。
syncScroll が true のとき、y はドキュメント座標。false のときは、ビューポート座標です。
autoCenterX が true のとき、レイヤーは水平方向の中央に置かれ、x は使われません。
viewport: { innerWidth, innerHeight, scrollY, devicePixelRatio }。呼んだ時点の値です。
自動化の道具には、ビューポートを一時的に変えるものがあります（道具をつないでいる間に出る
デバッグ用のバー、スクリーンショットのための大きさの変更など）。そのため、この値は画面に
見えているものと食い違うことがあります。倍率を計算するときは、要素の幅（inspect().rect）を
もとにするほうが安全です。measure() は、実際に使ったビューポートを返します。

await window.__pixelpont.setVisible(visible)

visible: boolean。隠している間も、レイヤーの選択と設定は保たれます。
例: カンプの写らないスクリーンショットを撮る前に await __pixelpont.setVisible(false)

await window.__pixelpont.setActiveLayer(id)

id: getState().layers にあるレイヤーの id。戻り値は { ok, activeLayerId }。

await window.__pixelpont.updateLayer(id, patch)

patch の項目（すべて省略可）: x, y（CSS px、有限の数値）、scale（0 より大きい）、
opacity（0〜1）、blendMode（normal | difference | invert | multiply | overlay）、
locked, syncScroll, autoCenterX（真偽値）。
値は、渡したとおりに保存されます。syncScroll を切り替えても、y は換算されません。
opacity を指定せずに blendMode を変えると、opacity も変わることがあります。合成ごとに
不透明度を覚えているためです（初めて使うとき: difference / multiply / overlay は 1、ほかは 0.5）。
利用者がこの設定を切っているときは、変わりません。
locked は、レイヤーがクリックを通し、パネルで編集できなくなるだけです。このメソッドは止めません。
戻り値は { ok, id, applied, previous }。previous は、patch の項目の、変える前の値です。
updateLayer(id, previous) で、元に戻せます。
例: await __pixelpont.updateLayer(id, { y: 120, blendMode: "difference" })

await window.__pixelpont.alignTo(selector, compY)

selector: CSS セレクタ（最初に一致した要素）。compY: カンプ px での y 座標。
アクティブなレイヤーを縦方向にだけ動かし、{ ok, id, y, previousY } を返します。
長いページでは、小さな差が積み重なり、下のものがすべてずれていきます。先にカンプを
セクションに合わせると、どのずれがそのセクションだけのものかが分かります。その後の
measure() は、積み重なったずれを除いて報告します（commonOffset が 0 に近くなります）。
例: await __pixelpont.alignTo(".pricing", 2480)

await window.__pixelpont.measure(options?)

options: { scope?: "viewport" | "page" | "<CSS セレクタ>", ignore?: string[],
  tolerance?: number, minConfidence?: number, layer?: { x?, y?, scale? },
  format?: "full" | "lines", settle?: number, limit?: number }。
この一覧に無いオプションは、無視せずに断ります（unknown-option）。
limit（1〜30）: 各一覧（mismatches、unmatched、colorMismatches、borderline、groups）が返す
件数の上限。件数そのもの（total など）は変わりません。小さくすると、繰り返し読む結果が
短くなります。
settle（ms、500〜10000）: 計測の前に、ページの変化（DOM、スタイルシート、大きさ）が 300 ms
止まるまで待ちます。ただし、指定した時間より長くは待ちません。保存したばかりの CSS が、
まだ反映されていないかもしれないときに使います。結果に settle { waitedMs, timedOut } が付きます。
timedOut が true のときは、時間切れの時点でページがまだ変化していたので、途中の状態を
測っている可能性があります。呼んでから 300 ms 以内に始まらなかった変化は、待ちません。
format "lines" は、全部の結果の代わりに、短い文の要約を返します（help("getReport") を参照）。
長い戻り値を切ってしまう道具に向いています。
layer は、この計測に限って、レイヤーの位置や倍率を上書きします。利用者がパネルで見ている
設定は変わりません（updateLayer とは違います）。
x と y は、使う倍率でのレイヤーの位置です。scale を上書きすると、保存されている y はたいてい
合わなくなる（ページの幅でヘッダーの高さが変わる、など）ので、y も上書きします。
y の求め方: 要素の上端（syncScroll がオンならドキュメント座標）から、そこに来るはずの
カンプの行 × scale を引きます。カンプの行は、カンプの一番上のセクションなら 0、それ以外は、
カンプ画像の中でのそのセクションの y です。
scale の求め方: カンプが示している範囲の、ページ上での幅（ウィンドウ全体ではなく、主な
カラムのことが多い）を designWidth で割ります。autoCenterX のときは、上書きした倍率でも
レイヤーが中央に置かれるので、x は上書きしなくて構いません。
scope の既定は "viewport"。セレクタを渡すと、その要素の中だけを調べます。
測るのは、いまスクロールして見えている部分だけです。
scope "page" は、ページ全体をスクロールしながら測ります（1 画面あたり約 1 秒）。
すぐに { ok, started: true } を返し、進み具合と結果は getReport() で読みます。
ページ全体の計測の間は、遅延読み込みの画像を読み込み、固定・追従表示の要素を、張り付いて
いる間だけ隠します。レイヤーは syncScroll: true で、ウィンドウ自体がスクロールするページで
ある必要があります（ページの中の領域がスクロールする作りでは、
page-scrolls-inside-element を返します）。ビューポートより背の高い要素は測りません
（tooLarge に数えます）。
ignore: 除外するセレクタ（写真、スライダー、固定ヘッダーなど）。tolerance: CSS px、既定は 1。
minConfidence（0〜1、既定は 0.1）: これ未満のずれは、一覧に載せず uncertain に数えます。
{ tolerance: 0, minConfidence: 0 } にすると、見つかった 0 でないずれをすべて一覧にします。
戻り値は { ok, pass, breakdown, scope, tolerance, ignore, layer?, layerFix?, designWidth,
  scale, viewport, checked, skipped, total,
  mismatches[], borderlineTotal, borderline[], borderlineBand, uncertain, commonOffset,
  commonApplied, commonCount, unmatchedTotal, unmatched[], colorTotal, colorMismatches[],
  groups[], misaligned, outOfView, tooLarge, pinned, truncated, pageCut, notes[] }。
  一覧は、大きい順（unmatched は文書の中での順）で、それぞれ最大 30 件（borderline は 10 件）。
pass が true になるのは、1 つ以上の要素を比べていて、位置のずれ・合わない要素・色の違いが無く、
張り付いた固定・追従表示の下で外した要素が無く、表示範囲の外に残した要素が無く、
上限で打ち切ったものが無く（truncated が 0、pageCut が false）、misaligned でも
commonApplied でもないときだけです。borderline・uncertain・tooLarge は pass を false に
しないので、厳しく確かめるなら breakdown も見ます。
truncated は、1 画面の候補が 200 を超えたために測らなかった要素の数。pageCut は、60 画面より
長いページで、撮れなかった範囲が残ったときに true になります。
breakdown は、候補の要素をすべて数えます: matched, mismatched, unmatched, borderline, uncertain,
notAlignable（合わせる手がかりが無い、またはカンプの外）, outOfView, overLimit, tooLarge, tooSmall,
coveredByFixedOrFrame（最後の 2 つは、scope "page" では null）, pinned。
同じ数が、以前からの名前でも入っています: total は breakdown.mismatched（位置のずれの数。
要素の総数ではありません。総数は checked）、skipped は notAlignable、truncated は overLimit。
unmatched[]: { selector, rect, styles } は、カンプに合う場所が無い要素の一覧です。
描かれている内容が違う（別の文言や画像、要素の抜けや余分）か、ずれが探す範囲を超えています。
これらの要素は、位置も色も比べません。コードを知っている側で、内容が違ってよいもの（その
場合は ignore に渡す）か、要素が誤っているのかを判断します。
pinned { total, selectors[], by[{ selector, position }] }: スクロールの後、固定・追従表示の
要素（by）が張り付いて上に重なっているために、比べなかった要素です。カンプには、その要素が
ページの先頭での位置に描かれています。scrollY が 0 のときは、固定ヘッダーや追従表示の要素も
ふつうに測ります。scope "page" は、本来の位置にあるとき（最初の画面のヘッダー、張り付く前の
見出し）に測り、張り付いている間は隠します。このとき pinned に入るのは、本来の位置に
一度も無かったもの（固定のバナーなど）だけです。
mismatches[] / borderline[]: { selector, rect, delta, deltaDesignPx, moveBy, confidence,
  styles, atLimit?, own? }。
commonOffset { x, y }（CSS px）: 測った要素の半分以上（かつ 3 つ以上）に共通するずれ。
無ければ 0 です。0 でないときは、レイヤーの位置そのもの（または、それより上のすべて）が、
その分ずれています。このとき commonApplied が true になり、commonCount が、同じだけずれている
要素の数を示します。その量だけずれている要素は一覧に載らず、載った要素には own { x, y }
（commonOffset を引いた、その要素だけのずれ）が付きます（delta は、カンプとの差そのままです）。
この値は、tolerance や minConfidence に左右されません。
layerFix { x?, y } は、commonApplied のときに付きます。commonOffset を消す、レイヤーの位置です
（計測に使った位置から commonOffset を引いた値。autoCenterX の間は x を省きます）。
measure({ layer: layerFix }) で 1 回だけ試せ、updateLayer(id, layerFix) で確定できます。
ignore は、除外したセレクタの写しです。layer { x, y, scale } は、options.layer を使って
測ったときに付きます（条件つきで測った結果を、ふつうの結果と読み違えないため）。
borderline[] / borderlineTotal: 許容差を超えているが、その超え方が borderlineBand 以内の要素。
（CSS px。撮った画像の 1 画素ぶんで、デバイスピクセル比 2 なら 0.5、最大 1）。計測のたびに
出たり消えたりするので、mismatches には入れません。許容差 1・幅 0.5 なら、1.5 px はまだ
borderline です。もっと厳しい線は、borderline の一覧そのものから引けます。
groups[]: { parent, moveBy, count, selectors[] } は、一覧のずれのうち、同じ親要素を持ち、
まったく同じだけずれている 2 つ以上の組です（commonApplied のときは own で比べます）。
こうした組は、要素を 1 つずつ直すより、親（の位置・padding・gap）で直すのがふつうです。
uncertain は、合う場所があいまいで、一覧から外したずれの数です。
rect はビューポート座標。scope "page" のときは、ドキュメント座標です。
delta: 描画された要素が、カンプとどう違うか（左上を基準にします）:
  y: 3 は、要素が 3px 上にありすぎる（3px 下げるとカンプに合う）ことを表します。
  delta は CSS px、deltaDesignPx はカンプ px。x / y は、カンプを描画結果の上でずらして、
  最もよく合う位置から求めます（写真の上でも働きます）。width / height は、背景が単色の
  ときだけ返します（width: 4 は、カンプのほうが 4px 広い）。それ以外では 0 です。
16×8px より小さい要素と、固定・追従表示の要素の下にある要素は測りません（breakdown に
数えます）。ビューポートの 40% を超える要素（背景や入れ物）も、1 つずつは測らず、
tooLarge { total, selectors[] } で返します。inspect() なら、そのうちの 1 つを単独で比べられます。
moveBy { x, y } は、描画された要素をどれだけ動かすとカンプに合うかを示します。値は
delta.x / delta.y で、commonApplied が true のときは own です（カンプの重ね位置のずれは、
要素の側で直すものではありません）。
confidence（0〜1）は、写真・繰り返しの模様・込み入った場所では低くなります。目安として、
0.6 以上は当てにでき、0.1〜0.6 は疑わしく（inspect() で確かめる価値があります）、
minConfidence 未満のずれは一覧に載りません（uncertain に数えます）。
約 12 CSS px を超えるずれは見つけられません。atLimit: true は、ずれがその範囲に達したことを
示します。その値は当てになりません（もっと大きなずれか、合う場所が無い）。
notes[] は、結果を読み違えやすい状況を説明します。カンプ全体が大きくずれている
（misaligned: true。このとき、色は比べません）、表示範囲の外にあって測らなかった要素がある
（outOfView { total, selectors[] }。scope が viewport かセレクタのとき）、などです。
colorMismatches[]: { selector, rect, styles, ratio, render, comp } は、位置を合わせたうえで、
塗りがカンプと違う要素の一覧です（色の間違い、グラデーションの抜けなど）。
色は 4px のブロックの平均で比べるので、文字のアンチエイリアスは違いに数えません。
ratio は、違っていたブロックの割合。render / comp は、平均の色（#rrggbb）です。
inspect(selector) は、1 つの要素の主な色を返します。
撮影の間は、オーバーレイを隠し、アニメーションを止めます。終わると元に戻します。
対象のタブは、そのウィンドウのアクティブなタブである必要があります。
例: await __pixelpont.measure({ ignore: [".hero__photo"] })

await window.__pixelpont.getReport(options?)

options: { format?: "full" | "lines", limit?: number }。省略した項目は、その結果を出した
measure() に渡した値を使います（どちらも無ければ "full"、上限なし）。
limit（1〜30）: 各一覧が返す件数の上限。
format "lines" は { ok, status, pass, format, lines[] } を返します。1 要素につき短い 1 行で、
スタイルと長いセレクタを含みません。戻り値を 1000 文字ほどで切る道具や、一部の文字を
通さない道具のためのものです（行には、等号とアンパサンドが入りません）。
最初の行は合計、2 行目は計測の条件（scope、tolerance、ビューポートの幅、除外したセレクタ、
レイヤーの上書き）。続いて、カンプのずれと、測れていない範囲についての注記。その後に、
ずれごとに "1 h2.title in section.hero: move x 0 y 3, confidence 0.8"（move は moveBy と
同じ意味）、色の違いごとに "c1 ..."、組ごとに "g1 parent ..." が並びます。
要素は、セレクタの最後の部分と、その親の部分を "in" でつないで書きます。読みやすい代わりに、
一意とは限りません。n 行目は、full の形式の mismatches[n - 1] で、完全なセレクタはそちらにあります。
実行中: { ok, status: "running", scope, progress: { done, total } }（画面の数）。
完了後: { ok, status: "done", by, measuredAt, ...measure() と同じ項目 }。
by は "ai" か "human"（人がパネルで「計測する」を押した）。
例: measure({ scope: "page" }) の後、1 秒ごとに getReport() を呼んで待ちます。

await window.__pixelpont.showDiff(mode)

mode: "boxes" | "heatmap" | "off"。"boxes" は、直近の measure() でずれていた要素を枠で囲み、
"1 ↓3px"（moveBy と同じ意味）、"u1 ≠"、"c1 color" などのラベルを付けます。番号は、結果の中の
位置です（n は mismatches[n - 1]、u は unmatched、c は colorMismatches。format "lines" の
番号と同じ）。{ ok, mode, boxes } を返します。
"heatmap" は、いまのビューポートを撮り、色がカンプと違う 4px のマスをすべて塗ります
（濃いほど、差が大きい）。{ ok, mode, cells, cellSize } を返し、先に measure() を呼ぶ必要は
ありません。
描いた後に撮ったスクリーンショットは、差分の画像として使えます。
描いたものは、showDiff("off") か、次の撮影（measure、inspect など）で消えます。

await window.__pixelpont.inspect(selector, options?)

selector: CSS セレクタ。最初に一致した要素を使います。比べるのは、画面に見えている部分だけです。
options: { layer?: { x?, y?, scale? } } — measure() と同じ、一時的なレイヤーの上書き。
指定しないと、パネルのレイヤーの設定を使います。measure({ layer }) の後は、ここにも同じ
layer を渡さないと、2 つの結果が合いません。
戻り値は { ok, selector, rect, positionMeasured, unmatched, delta, deltaDesignPx, confidence,
  color: { diffRatio, maxDifference, render[], comp[] }, styles, parent }。
delta の意味は measure() と同じです。positionMeasured は、合わせる手がかりの無い単色の面では
false になります（このとき delta は 0。色は比べます）。
unmatched は、合う場所が見つからなかったときに true になります（内容が違うか、ずれが探す
範囲を超えている）。このとき delta は 0 で、測った値ではありません。
color.render / color.comp: 最も多い 3 色を { hex, share } で返します。ふつうは、背景の色が
最初、文字の色がその次です。diffRatio は、平均の色が違う 4px のブロックの割合（0 は同じ塗り）。
maxDifference は、チャンネルごとの差の最大値です。
styles には、計算済みの値が入ります（color、backgroundColor、backgroundImage、font、box と、
位置を決めることの多い position、top、left、translate、transform、gap）。
parent: { selector, styles } は、親要素と、子の配置を決める値（display、position、gap、
justifyContent、alignItems、paddingTop、paddingLeft）です。
これらは計算済みの値そのままです。どれがずれの原因かは、読む側が判断します。
color は、要素が別オリジンの画像に重なるときは null になります。その色は、決して返しません
（samplePixel では protected-area のエラー、ヒートマップではマスなし）。ページのスクリプト
からは、ふつう読めないものだからです。埋め込みのフレームを含む・接する要素は、measure() と
同じく、比べること自体をしません（protected-area のエラー）。
例: await __pixelpont.inspect(".cta__button")

await window.__pixelpont.samplePixel(x, y, options?)

x, y: ビューポート座標（CSS px）。戻り値は { ok, x, y, render, comp, difference }。
options: { layer?: { x?, y?, scale? } } — measure() と同じ、一時的なレイヤーの上書き。
render / comp は、CSS 1px ぶんを平均した #rrggbb。difference は、チャンネルごとの差の
最大値（0〜255）で、24 以下なら、目には同じ色に見えます。
呼ぶたびにページを撮ります（間隔は約 0.6 秒）。例: グラデーションに沿って数点を調べると、
描画結果でグラデーションが抜けていないかが分かります。