experience-lwc-runtime-observe

LWC Runtime のプレビュー — ローカル開発と DOM の検査

通常はまとめて実行される、次の2つの連続した作業をエージェントに案内します。

1. Salesforce CLI で Lightning Preview セッションを開始し、LWC アプリまたはコンポーネントをローカル開発環境でレンダリングします。
2. そのプレビュー URL に移動して、実行時の DOM サブツリーを抽出し、エージェント（またはユーザー）が実際にレンダリングされた内容を確認できるようにします。

DOM の検査にはプレビューが必要です。必ずこの順序で実行してください。

このスキルを使用する場面

• デプロイ前に LWC アプリまたはコンポーネントをローカルでプレビューしたい場合（sf lightning dev app ／ sf lightning dev component）。
• 実行時に特定のコンポーネントでレンダリングされた HTML サブツリーが必要な場合（差分の確認、スクリーンショットのパイプライン、シャドウ DOM の検討など）。
• テンプレートの内容が「DOM にない」理由を尋ねられた場合。ほとんどの場合、ステップ 2 で扱うシャドウ DOM の誤解が原因です。

前提条件

• Salesforce CLI（sf）がインストールされていること。sf version で確認します。
• @salesforce/plugin-lightning-dev がインストールされていること。sf plugins で確認します。
• 認証済みの組織があること（sf org list に接続済みの組織が1つ以上表示されること）。
• DOM の抽出には、エージェントのハーネスでブラウザー自動化を利用できること（Playwright、Puppeteer、Chrome DevTools Protocol など、接続されているものを使用します）。

---

ステップ 1 — Lightning Preview を開始する

対象範囲が アプリ か コンポーネント かを、ユーザーに確認するか、リクエストから判断します。

1a. ツールチェーンを確認する

プレビューの対象となる組織エイリアスをユーザーに確認するか、リクエストから判断します。そのエイリアスを指定して同梱の検証スクリプトを実行し、出力されたエラーをユーザーに伝えます。説明文の中で sf version ／ sf plugins ／ sf org display を再実行してはいけません。このスクリプトは CLI の存在、@salesforce/plugin-lightning-dev のインストール、および指定された対象エイリアスが認証済みで Connected であることを確認します。失敗時には、対処方法を示すメッセージを出力してゼロ以外の終了コードを返します。

"<skill_dir>/scripts/verify-toolchain.sh" <orgAlias>

対象エイリアスが認証されていないか、Connected ではないと報告された場合は、ユーザーに ローカル開発を有効にする よう案内し、sf org login web --alias <orgAlias> を実行してもらいます。その後、次に進む前に検証スクリプトを再実行します。

1b. サブコマンドのフラグを確認する

# For app scope
sf lightning dev app --help

# For component scope
sf lightning dev component --help

必須フラグと任意フラグを確認します。必須フラグの意味が曖昧な場合は、実行前にユーザーに確認してください。

1c. プレビューを起動する

すべてのプレビューコマンドの先頭に OPEN_BROWSER=false を付けます。CLI はデフォルトでブラウザーウィンドウを開きますが、エージェントが操作する際には 開きたくありません。（この環境変数は --help に記載されていません。ユーザーが明示的にブラウザーウィンドウを要求した場合を除き、これを使用してください。）

対象範囲	コマンド
app	OPEN_BROWSER=false sf lightning dev app -o <orgAlias> -n <appName> -t desktop
component	OPEN_BROWSER=false sf lightning dev component -o <orgAlias> -n <componentName>

プレビューが起動したら URL を取得し、次の形式で記録します。

Lightning Preview running at URL: <URL>

いずれかのサブステップが失敗した場合は、そこで停止してエラーをユーザーに伝えます。認証やプラグインのインストールに関する問題を取り繕おうとしてはいけません。

---

ステップ 2 — 実行時の DOM を抽出する

ステップ 1 で有効なプレビュー URL が生成された後にのみ、このステップを実行します。

2a. 認証済みのフロントドア URL を取得する — トークンをエージェントのコンテキストに露出させずに

sf org open --url-only --json が返すフロントドア URL には、セッションを認証する短時間有効の OTP が含まれています。sf org open を直接実行しないでください。出力がエージェントのツール出力ストリームに流れ、認証トークンがトランスクリプトに漏洩して、エージェント安全性標準 S1 に違反します。 URL を取得する方法としてサポートされているのは、同梱のヘルパーのみです。ヘルパーは内部で sf org open を実行し、標準出力を chmod 600 の一時ファイルにリダイレクトし、標準エラー出力を抑制するため、URL フラグメントやトークンの一部がエージェントのコンテキストに届くことはありません。

代わりに、URL を chmod 600 の一時ファイルに書き込み、export の代入文だけを出力する（トークン情報は出力しない）同梱のヘルパースクリプトを使用してください。呼び出し元が中断されるよう、まずヘルパーの出力を取得してください。eval "$(...)" だけでは失敗が隠され、エージェントが $FRONTDOOR_URL_FILE が未設定のまま処理を続けてしまいます。

frontdoor_env="$("<skill_dir>/scripts/open-frontdoor.sh" <orgAlias> <previewUrl>)" || exit 1
eval "$frontdoor_env"

ヘルパーは sf と python3 の標準エラー出力だけでなく標準出力も抑制するため、不完全な URL や進行状況のノイズがエージェントのトランスクリプトに届くことはありません。

ブラウザドライバーは次の操作を行う必要があります。

1. $FRONTDOOR_URL_FILE から URL を読み取ります。
2. URL に移動してセッションを確立します。
3. 使用後、ただちに一時ファイルを削除します。
4. ファイルの内容を cat などで出力しないでください。

OTP トークンの有効期限は短時間です。 まずブラウザドライバーを起動し、その後、移動する直前にヘルパーを呼び出してください。そうしないと、トークンが失効します。

2b. 移動して待機する

1. 手順 1 のプレビュー URL を自動化ブラウザーで開きます。
2. ネットワークがアイドル状態になり、初回のレンダリングが完了するまで待機します。
3. 想定した要素が見つからない場合は、失敗と判断する前に少し待ってから再試行します。ローカル開発ページでは、ハイドレーションが 2 段階で行われることがあります。

2c. サブツリーを抽出する

コンポーネント名を c-<kebab> セレクターに変換する処理と、抽出した HTML を正確な DOM_OUTPUT_START ／ DOM_OUTPUT_END マーカーで囲む処理という 2 つの決定的な文字列操作は、<skill_dir>/scripts/extract-dom.sh が処理します。セレクターを自分で導き出したり、マーカーを文章内で組み立てたりしないでください。スクリプトを呼び出してください。

実際の DOM の走査は、ブラウザー自動化ドライバー（Playwright ／ Puppeteer ／ CDP）で実行する必要があります。スクリプトはブラウザーを操作しません。

scope が component の場合

セレクターを決定的に計算します。

selector="$("<skill_dir>/scripts/extract-dom.sh" selector <componentName>)"

次に、ドライバーを使って lwr_dev-preview-container のシャドウルートをたどり、$selector に一致する最初の可視要素を見つけ、そのサブツリーの HTML（element.shadowRoot.innerHTML 経由）を読み取ります。その HTML をラップ処理に渡します。

printf '%s' "$html_subtree" \
  | "<skill_dir>/scripts/extract-dom.sh" wrap component <componentName>

scope が app の場合

ドライバーを使ってアプリの主要ルート（document.documentElement ではなく、document.body またはメインのアプリコンテナーを優先）を特定し、<head> とレンダリングされないノードを除外して、サブツリーの HTML を読み取ります。それをラップ処理に渡します。

printf '%s' "$html_subtree" \
  | "<skill_dir>/scripts/extract-dom.sh" wrap app

スクリプトの標準出力を変更せずに DOM 出力として出力します。

2d. LWC Shadow DOM について（最大の注意点）

Lightning Web Components は Shadow DOM を使用します。テンプレートのコンテンツは、ホスト要素から直接クエリできません。

アクセス方法	取得される内容
element.innerHTML	空、またはスロットに挿入された Light DOM コンテンツのみ
element.outerHTML	子要素を含まないホストタグのみ
element.shadowRoot.innerHTML	実際にレンダリングされたテンプレートコンテンツ

ブラウザードライバーの DOM クエリがデフォルトでシャドウルートをたどらない場合は、shadowRoot を明示的にたどってください。最新の自動化ドライバーのほとんどには、シャドウルートをたどるクエリーヘルパーがあります。これを使用してください。

---

例

エンドツーエンドの実例（コンポーネントのプレビュー、安全なフロントドア URL の取得、DOM の抽出）については、examples/component-preview-and-dom.md を読み込んでください。

---

検証チェックリスト

• 対象エイリアスに対して、<skill_dir>/scripts/verify-toolchain.sh <orgAlias> がゼロで終了しました。
• OPEN_BROWSER=false を指定してプレビューコマンドを実行しました。
• プレビュー URL が Lightning Preview running at URL: <URL> の形式でログに記録されました。
• <skill_dir>/scripts/open-frontdoor.sh を使ってフロントドア URL を取得しました（sf org open を直接実行しないでください）。
• DOM の抽出には shadowRoot のトラバーサルを使用しました（ホストに対する innerHTML は使用していません）。
• DOM 出力は <skill_dir>/scripts/extract-dom.sh wrap … によって生成されました（マーカーはスクリプトが管理します）。

---

トラブルシューティング

• verify-toolchain.sh が「Target org alias is not authenticated or not Connected」と報告する — sf org login web --alias <orgAlias> を実行します（エイリアスは verify-toolchain.sh に渡した値、およびプレビューコマンドが使用する -o の値と一致している必要があります）。
• verify-toolchain.sh がプラグインが見つからないと報告する — sf plugins install @salesforce/plugin-lightning-dev でインストールします。
• プレビューでブラウザーウィンドウが開く — OPEN_BROWSER=false を指定し忘れています。
• 抽出した DOM が空になる — ホストの innerHTML を参照しています。代わりに element.shadowRoot.innerHTML を使用してください。また、lwr_dev-preview-container のシャドウルートを通過していることを確認してください。
• フロントドアトークンが無効になる — 期限切れです。<skill_dir>/scripts/open-frontdoor.sh を再度実行し、約 60 秒以内に移動してください。