pxtree

pxtree

ヘッドレス Chromium でウェブページを読み込み、実際にレンダリングされた内容をコンパクトなテキストツリーとして出力します。スクリーンショットを使わずに、AI コーディングエージェントがレイアウトを確認できます。

3 枚のカードが並ぶ行、3 つのプランが並ぶ行、手順のリスト、統計の行、記事、フォーム、価格の列、タイルの行がある開発サーバーのページです。

$ npx -y pxtree@latest localhost:5173
1280x800 light dpr 1 ltr scroll 0/382 page 1280x1182 painted to 1134
since last run: no changes
summary: 7 findings
  a.button tops 64..136 across siblings: ul.cards
  div.stat tops 0..6 across siblings: div.stats
  input.field starts 0..3 across siblings: form.fields
  12 wider than li.plan: li.plan.featured
  72 taller than li.card: li.card 3 of 3
  20 shorter than div.tile: div.tile.short
  gaps 16 16 24 16 between li.step: ul.steps
body 1280x1182 [pad 24][gaps 24 24 24 24 16 16 …, free 24 at end]
  ul.cards 1232x208 [gaps across 16, free 600 at end][!! a.button tops 64..136 across siblings]
    li.card 200x136 [pad 16][gaps 8][renders background]
      h3 "Starter" 168x24 [text 19/24]
      p "Short text." 168x24 @0,32 [text 16/24]
      a.button "Choose" 168x40 @0,64 [pad 8 16][text 16/24][renders background]
    li.card 200x136 @216,0 [pad 16][gaps 8][renders background]
      h3 "Team" 168x24 [text 19/24]
      p "Short text." 168x24 @0,32 [text 16/24]
      a.button "Choose" 168x40 @0,64 [pad 8 16][text 16/24][renders background]
    li.card 200x208 @432,0 [pad 16][gaps 8][renders background][!! 72 taller than li.card]
      h3 "Business" 168x24 [text 19/24]
      p "A much longer…" 168x96 @0,32 [text 16/24, 4 lines, 444 on one line]
      a.button "Choose" 168x40 @0,136 [pad 8 16][text 16/24][renders background]
  ul.plans 1232x56 @0,232 [gaps across 16, free 588 at end]
    li.plan "Monthly" 200x56 [pad 16][text 16/24][renders background]
    li.plan "Yearly" 200x56 @216,0 [pad 16][text 16/24][renders background]
    li.plan.featured "Lifetime" 212x56 @432,0 [pad 16][text 16/24][renders background][!! 12 wider than li.plan]
  ul.steps 1232x192 @0,312 [gaps 16 16 24 16][!! gaps 16 16 24 16 between li.step]
    li.step "One" 1232x24 [text 16/24]
    li.step "Two" 1232x24 @0,40 [text 16/24]
    li.step.active "Three" 1232x24 @0,80 [text 16/24]
    li.step "Four" 1232x24 @0,128 [text 16/24]
    li.step "Five" 1232x24 @0,168 [text 16/24]
  div.stats 1232x62 @0,528 [gaps across 16, free 456 at end][!! div.stat tops 0..6 across siblings]
    div.stat "Revenue" 182x56 [pad 16][text 16/24][renders background]
    div.stat "Orders" 182x56 @198,0 [pad 16][text 16/24][renders background]
    div.stat.alert "Refunds" 182x56 @396,6 [pad 16][text 16/24][renders background]
    div.stat "Customers" 182x56 @594,0 [pad 16][text 16/24][renders background]
  article 1232x132 @0,614 [gaps 12]
    h2 "First heading" 1232x24 [text 24/24]
    p "First paragraph." 1232x24 @0,36 [text 16/24]
    h2 "Second heading" 1232x24 @0,72 [text 24/24]
    p "Second paragraph." 1232x24 @0,108 [text 16/24]
  p.with-link "Read the first." 1232x24 @0,762 [text 16/24]
    a "guide" 39x17 @69,3 [text 16/24]
  form.fields 1232x108 @0,802 [gaps 8][!! input.field starts 0..3 across siblings]
    input.field "Name" 208x21 [pad 1 2][text 13/15][renders background, border]
    input.field "Email" 208x21 @0,29 [pad 1 2][text 13/15][renders background, border]
    input.field.nudged "Company" 208x21 @3,58 [pad 1 2][text 13/15][renders background, border]
    input.field "Phone" 208x21 @0,87 [pad 1 2][text 13/15][renders background, border]
  div.prices 300x72 @0,934
    span.price "$9" 18x24 @282,0 [text 16/24]
    …×2 similar span.price 36x24..49x24
  div.tiles 1232x80 @0,1030 [gaps across 16, free 900 at end]
    div.tile 100x80 [renders background]
    div.tile.short 100x60 @116,0 [renders background][!! 20 shorter than div.tile]
    div.tile 100x80 @232,0 [renders background]

最初の行はファクト行です。ビューポート、カラースキーム、デバイスピクセル比、方向、最大値に対するスクロール位置、ドキュメントサイズ、そして最も低い位置に描画されたピクセルを示す painted to が表示されます。since last run は、同じ URL と設定、または同じ --diff-key 名での前回の実行と比較します。この履歴はプロジェクト内ではなく ~/.cache/pxtree に保存され、--no-diff を指定すると履歴の比較をスキップします。

ul.cards の行は、3 枚のカードにある「選択」ボタンの上端が、それぞれカードの上端から 64 px から 136 px の位置にあることを示します。li.plan.featured "Lifetime" の行は、そのプランが行内の x 432 の位置に 212x56 で表示され、兄弟要素で共通する幅より 12 px 広いことを示します。検出結果はしきい値に基づく測定値であり、判定ではありません。意図したものかどうかは、エージェントがコードを見て判断します。

スクリーンショットを使わない理由

• モデルが推測する必要のあるピクセルではなく、CSS px 単位で数値を示します。
• エージェントは、検出結果が先頭にまとめられたテキストとして、一度に読み取れます。
• 1 回の呼び出しで、複数のビューポートとカラースキームを確認できます。

インストール

pxtree は Playwright の Chromium を操作します。一度インストールしてください。サイズは約 150 MB です。

npx -y [email protected] install chromium

pxtree 自体は何もダウンロードせず、プロジェクトを編集することもありません。--channel chrome を指定すると、インストール済みの Chrome を使用します。Node 20 以降が必要です。

MCP サーバー

クライアント	インストール	スコープ
Codex	codex mcp add pxtree -- npx -y pxtree@latest mcp	user、~/.codex/config.toml
Claude Code	claude mcp add --scope user pxtree -- npx -y pxtree@latest mcp	user。--scope project を指定すると .mcp.json に書き込みます
Cursor	または ~/.cursor/mcp.json / .cursor/mcp.json	user / project
VS Code Copilot	または code --add-mcp '{"name":"pxtree","command":"npx","args":["-y","pxtree@latest","mcp"]}'	user。プロジェクトでは .vscode/mcp.json。下記を参照
OpenCode	~/.config/opencode/opencode.json または opencode.json。下記を参照	user / project

OpenCode の opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pxtree": { "type": "local", "command": ["npx", "-y", "pxtree@latest", "mcp"], "enabled": true }
  }
}

{
  "mcpServers": {
    "pxtree": { "command": "npx", "args": ["-y", "pxtree@latest", "mcp"] }
  }
}

{
  "servers": {
    "pxtree": { "type": "stdio", "command": "npx", "args": ["-y", "pxtree@latest", "mcp"] }
  }
}

{
  "amp.mcpServers": {
    "pxtree": { "command": "npx", "args": ["-y", "pxtree@latest", "mcp"] }
  }
}

{
  "context_servers": {
    "pxtree": { "command": "npx", "args": ["-y", "pxtree@latest", "mcp"], "env": {} }
  }
}

MCP Registry の名前：io.github.alabsi91/pxtree。このサーバーには 2 つのツールがあります。measure と read_me_first です。read_me_first は、スキルに含まれる内容、つまり pxtree の使い方、報告方法、読み方ガイドを返します。指示では、エージェントにセッションごとに 1 回 read_me_first を呼び出すよう伝えているため、スキルをインストールする必要はありません。

measure は、入力として target と CLI フラグを受け取ります。フラグは viewports、schemes、scroll、element、children、colors、wait、script、screenshot（true にすると、実行ごとに一時ディレクトリに PNG を保存します）、timeout、maxChars（デフォルトは 80000）、diff、diffKey、report（tree、findings、summary、changes、または none）、aria（true にすると aria ツリーを追加します）です。1 回の呼び出しで、レポート、aria ツリー、スクリーンショットをまとめて返せます。入力には上限があります。ビューポートの各辺は 1～10000、ビューポート数は最大 10、timeout は最大 120000 です。ファイルを指定する場合は、サーバーの作業ディレクトリ内に置く必要があります。このルールは誤操作を防ぐためのものであり、セキュリティ境界ではありません。script は信頼されたコードとして、サーバープロセス内で Node として実行されます。

スキル

.agents/skills を通じて Codex を含む Agent Skills を読み込むエージェントの場合：

npx -y skills add alabsi91/pxtree

または、手動でリンクします。~/.agents/skills は Codex、Cursor、Copilot、Gemini CLI、OpenCode、Amp、Devin によって読み込まれます。Claude Code は ~/.claude/skills を読み込みます。

git clone https://github.com/alabsi91/pxtree
mkdir -p ~/.agents/skills ~/.claude/skills
ln -s "$PWD/pxtree/skills/pxtree" ~/.agents/skills/pxtree
ln -s "$PWD/pxtree/skills/pxtree" ~/.claude/skills/pxtree

1 つのプロジェクトだけで使う場合は、<project>/.agents/skills または <project>/.claude/skills を使用してください。

シェル専用エージェント

エージェントに、これを実行するよう指示してください。フラグ、出力の文法、すべてのタグと検出結果、制限事項が表示されます。

npx -y pxtree@latest guide

CLI

npx -y pxtree@latest https://example.com --viewport 390x844,1280x800 --scheme light,dark
npx -y pxtree@latest localhost:5173 --scroll '#pricing' --element '.card'
npx -y pxtree@latest ./dist/index.html
npx -y pxtree@latest localhost:5173 --script "await page.click('text=Menu')" --wait '.menu'
npx -y pxtree@latest localhost:5173 --element '#pricing' --screenshot pricing.png
npx -y pxtree@latest localhost:5173 --viewport 390,1280
npx -y pxtree@latest localhost:5173 --report summary --aria
npx -y pxtree@latest localhost:5173 --report findings
npx -y pxtree@latest localhost:5173 --report changes
npx -y pxtree@latest localhost:5173 --report none --screenshot shot.png

スクリーンショットが --element に一致した要素だけに切り取られるのは、セレクターが要素にちょうど1つだけ一致した場合です。それ以外の場合はビューポート全体が表示され、facts 行に一致した数が示されます。

--report は、出力される測定結果の量を指定します。tree（デフォルト。すべて）、findings（検出結果のある行と、その祖先の名前だけに絞ったツリー）、summary（ツリーなし）、changes（facts 行と前回の実行以降の変更。修正の確認用）、none（facts 行のみ）から選べます。--viewport で幅だけを指定すると、対応する高さが設定されます。390x844、768x1024、820x1180、1024x768、1280x800、1440x900、1920x1080 となり、その他の幅では800です。--aria を指定すると、レポートの後に、ページまたは各 --element の一致要素の Playwright による aria スナップショットが追加されます。スナップショットには、測定時と同じ状態で取得したロール、名前、状態、読み上げ順序が含まれます。これにより、1回の呼び出しで検出結果、アクセシビリティツリー、スクリーンショットをまとめて取得できます。

npx -y pxtree@latest --help でフラグを確認できます。npx -y pxtree@latest guide では、出力の読み方を説明しています。

制限事項

• 対象範囲の確認は、ビューポート内でのみ行われます。
• 宣言的なクローズドシャドウルートは走査されません。
• iframe は走査されません。フレームの URL を個別に測定してください。
• 擬似要素の描画は、要素のボックス上に配置されます。
• クリップパスはボーダーボックスとして扱われます。角丸は無視されます。
• 回転または拡大縮小されたボックスの内部では、重なり、中央揃え、幅に関する検出結果は出ません。軸に沿って整列したボックスだけでは、要素の実際の位置は分かりません。
• 画像やグラデーション上のコントラストは測定されません。この場合、[text] タグには on image と表示されます。また、グラデーションテキストなど、テキストの塗りが透明な場合も測定されず、fill transparent と表示されます。
• WCAG 2.5.8 で認められているように、small target はテキスト行内のリンクと、十分な間隔があるターゲットを除外します。
• pxtree は意図を推測しません。全面表示のセクション、アバターのスタック、開いたポップオーバー、折りたたまれたパネルも、他の要素と同様に数値が出力されます。
• エミュレーションはデスクトップのみです。(hover: hover) と (pointer: fine) が一致します。タッチには対応していません。
• 縦書きモードでは、物理位置が出力されます。
• 読み込みでは load を最大2秒、ネットワークが静かになるまで最大1.5秒待機します。ファイルではこの待機をスキップします。読み込みが遅いページでは --wait が必要です。

API

import { createSession, format } from 'pxtree';

const session = await createSession();
const result = await session.measure('localhost:5173', { viewports: [{ width: 390, height: 844 }] });
console.log(format(result));
await session.close();

ライセンス

MIT