web-browser

Web Browser

使用する場面

• 実際のウェブサイトを閲覧したり操作したりする場合。
• ボタンをクリックしたり、フォームに入力したり、ページのコンテンツを抽出したりする場合。
• 実際のブラウザー環境で JavaScript を評価する場合。
• デバッグやレビューのためにスクリーンショットを撮影する場合。
• 実際のブラウザー環境で UI の検証やスモークテストを行う場合。
• ローカルのベンチマークスクリプトを使って、ウェブブラウザーツールのレイテンシーの回帰を測定し、基準を適用する場合。

要件

• codex/skills/web-browser/ からコマンドを実行します（./tools/*.js が解決されるようにするため）。
• Node.js（ESM とトップレベルの await）がインストールされており、リポジトリの依存関係（特に puppeteer-core）がインストールされていること。
• Chrome/Chromium がインストールされていること、または CODEX_CHROME_PATH を設定すること。

クイックスタート

# Start Chrome with CDP on :9222
./tools/start.js

# Safer (recommended on your laptop): avoid killing an existing Chrome session
./tools/start.js --no-kill

# Open a deterministic tab, then operate on it
./tools/nav.js https://example.com --new
./tools/eval.js 'document.title'
./tools/screenshot.js

手順：小さなステップで進める → 状態を確認する（eval.js / screenshot.js）→ 繰り返す。

パフォーマンス検証（$lift）

ウェブブラウザーツールのレイテンシーを最適化または検証する場合に使用します。

./tools/start.js --no-kill
./tools/nav.js https://example.com --new

cd tools
npm run -s bench:all -- --warmup 5 --samples 30 --screenshot-samples 20

より厳格な CI スタイルの基準を適用するには、p95 の予算を追加します。

cd tools
npm run -s bench:all -- \
  --warmup 5 \
  --samples 30 \
  --screenshot-samples 20 \
  --budget-nav-p95-ms 310 \
  --budget-eval-p95-ms 220 \
  --budget-screenshot-p95-ms 320 \
  --budget-start-p95-ms 140

設定

• フラグ
  • start.js：--port、--user-data-dir、--chrome-path、--profile、--no-kill
  • nav.js / eval.js / screenshot.js / pick.js：--port、--browser-url
• 環境
  • CODEX_BROWSER_URL：CDP URL（CLI の --port / --browser-url が指定されていない場合に使用）
  • CODEX_BROWSER_PORT（別名：CODEX_CDP_PORT）：localhost の CDP ポート
  • CODEX_BROWSER_USER_DATA_DIR：Chrome のユーザーデータディレクトリ（start.js で使用）
  • CODEX_CHROME_PATH（別名：CHROME_PATH、PUPPETEER_EXECUTABLE_PATH）：Chrome/Chromium の実行ファイル

対象指定（アクティブタブ）

すべてのツールは「アクティブタブ」を操作します。これは puppeteer.pages() が最後に返すページ（おおむね、最後に開いたタブ）として定義されています。

• 対象を確実に指定したい場合は、./tools/nav.js <url> --new を優先してください。
• 操作が「別の」タブに適用される場合は、余分なタブを閉じるか、新しいタブを開いてください。

よく使うコマンド

# See all options (safe; does not start/kill Chrome)
./tools/start.js --help

# Use a non-default port
./tools/start.js --port 9223 --no-kill
./tools/nav.js --port 9223 https://example.com --new

# Or configure once via env
export CODEX_BROWSER_URL=http://localhost:9223
./tools/eval.js 'document.title'

# Wait for a selector (polling with timeout; good for SPAs)
./tools/eval.js '(async () => { for (let i = 0; i < 50; i++) { const el = document.querySelector("button[type=submit]"); if (el) return true; await new Promise(r => setTimeout(r, 100)); } return false; })()'

# Screenshot current viewport
# Prints a PNG filepath in your system temp dir
./tools/screenshot.js

# Pick elements interactively
# Prints tag/id/class/text/html/parents for one element (or many via Cmd/Ctrl+click)
./tools/pick.js "Click the submit button"

ヒント：pick.js で属性やテキストを確認してから、eval.js 用のセレクターを作成してください。

レシピ

# Scrape structured data (return an array of objects for readable output)
./tools/eval.js 'Array.from(document.querySelectorAll("a"), a => ({ href: a.href, text: a.textContent?.trim() }))'

• ログインフロー
  • 専用の自動化プロファイル：./tools/start.js を実行し、一度ログインした後、ユーザーデータディレクトリ（デフォルト：~/.cache/scraping）に保存されたプロファイルを再利用します。
  • デフォルトプロファイルの初期設定：既存の Cookie やログイン情報が本当に必要な場合は、./tools/start.js --profile を実行します。

セキュリティとプライバシー

• ./tools/start.js --profile は rsync -a --delete を使い、デフォルトの Chrome プロファイルをユーザーデータディレクトリにコピーします（Cookie／セッション／個人を特定できる情報）。
• ユーザーデータディレクトリ（デフォルト：~/.cache/scraping）は機密情報として扱ってください。共有マシンでは使用を避け、必要に応じて使用後に削除してください。

トラブルシューティング

• ✗ Failed to connect to Chrome via CDP：./tools/start.js を実行するか、Chrome の設定に合わせて CODEX_BROWSER_URL / --port を設定してください。
• ✗ No active tab found：最初にページを開いてください（例：./tools/nav.js https://example.com --new）。
• ポート 9222 が使用中の場合は、新しいポートを選んでください（./tools/start.js --port 9223）。
• セレクターが不安定な場合：上記のポーリングパターンを使ってください。SPA では domcontentloaded の後に待機が必要になることがよくあります。
• Chrome のパスが見つからない場合：CODEX_CHROME_PATH を設定するか、--chrome-path を指定してください。

注意点

• ./tools/start.js はデフォルトで Chrome プロセスを終了します（これを避けるには --no-kill を使用してください）。
• シェルのエスケープに関する問題を避けるため、JavaScript はシングルクォートで囲んでください。

$lift が Zig を使用していることを証明する

ローカルの $lift ツールが Zig ベースであることを客観的に証明する必要がある場合：

bench_stats --help 2>&1 | sed -n '1,6p'
perf_report --help 2>&1 | sed -n '1,6p'
brew cat tkersey/tap/lift | rg -n 'depends_on \"zig\" => :build|build-exe|bench_stats.zig|perf_report.zig'

参考資料

• codex/skills/web-browser/tools/start.js
• codex/skills/web-browser/tools/nav.js
• codex/skills/web-browser/tools/eval.js
• codex/skills/web-browser/tools/screenshot.js
• codex/skills/web-browser/tools/pick.js
• codex/skills/web-browser/tools/bench-eval.js
• codex/skills/web-browser/tools/bench-all.js