custom-angular-component-creator

カスタム Angular コンポーネントの作成

ブランチ上で、Datex Studio のカスタム Angular コンポーネント（CAC、configurationTypeId: 36）を作成または編集します。CAC は作成者が記述するスタンドアロンの Angular コンポーネントです。宣言的な JSON 設定ではなく、実際の component.ts／.html／.scss を記述します。生成されたアプリ内で、実際のプラットフォームコンテキスト（$datasources、$flows、$shell など）が注入されて動作するため、宣言的なコンポーネント（グリッド／フォーム／ハブ／セレクター／エディター）では表現できない UI（独自のチャート、ダッシュボード、ビジュアライゼーション、カスタムレイアウトなど）を実現できます。

CAC のテンプレートに既存のアプリ設定を埋め込むこともできます。コンポーネント参照として宣言すると（まずはセレクターで対応。契約はコンポーネントの種類に依存しません）、コード生成時に生成済みコンポーネントが CAC のスコープにインポートされるため、実際に生成されたコントロール（セレクターのドロップダウンなど）をカスタム UI 内に表示できます。

埋め込みの手がかり：セレクターは _single と _multi の 2 種類を生成するため、セレクターを参照すれば、単一選択と複数選択の両方のコントロールを選んで使用できます。埋め込まれたコントロールは、設定自体のプロパティをコンポーネントの入力／出力として公開します（たとえばセレクターでは、各データソースパラメーターがパラメーター ID を名前とする入力として公開されるほか、選択値と表示テキストの出力も公開されます）。参照する設定が公開する正確なタグと入力／出力を確認するには、推測するのではなく、マテリアライズされたハーネス内の生成済みコンポーネントを確認してください。@Component のセレクターが使用するタグで、@Input／@Output メンバーがバインドする対象です。

このスキルで使う CLI は、他のすべての作成機能とは異なります。 ここには、手作業で作成する dxs configuration upsert customangularcomponent の手順はありません。CAC の作成には dxs ng コマンドファミリーを使います。このコマンドファミリーは、（サーバーがブランチ用に生成する、コンポーネント 1 つと実際の型付きコンテキスト、スタブサービスを含む）ライトハーネスをマテリアライズします。ローカルで 2 つの作成者用領域を編集でき、編集のたびにスクリーンショットをレンダリングします。dxs ng push を実行するまで、Studio には何も作成されません。

データのパターン（既定で固定 — 質問しないでください）

CAC がデータを表示する場合、そのデータは常に実際の型付きデータソースから取得します。また、その接続方法をユーザーに尋ねてはいけません。実データを使うか、サンプルデータを使うか、@Input を使うか、あるいはデータの取得方法をどうするかを尋ねないでください。すべてのコンポーネントでパターンは固定です。

• 作成ループ（CLI／dxs ng preview）： コンポーネントは型付きの this.$datasources.<ref> スタブを介して読み取りますが、プレビューにはモックデータが表示されます。dxs ng data generate で mocks/harness-mocks.json にデータを生成し、実際の dxs クエリから取得した代表的な値を入力します。作成時のプレビューで実データにアクセスすることはありません。
• push 後（生成された Studio アプリ）： 同じ型付きの $datasources.<ref> 呼び出しが、実行中のアプリで実際のデータソース／実データにアクセスします。コンポーネントは実行時に常にデータソースに依存します。
• ブランチにデータソースがない場合： まず schema-explorer で調査し、datasource-creator を使って実際のスキーマに合ったデータソースを作成してから、ハーネスをマテリアライズする前に upsert します。本文にサンプル行を埋め込んだり、キャスト（$datasources as any）を使ったりして代用してはいけません。

ひとことで言えば、作成時は実際の型付きデータソース＋モックデータ、push 後は実データです。これは質問せず、すべての CAC に適用します。サンプルデータは mocks/harness-mocks.json にのみ保存されます（これは一時的なもので、push されません）。本文は実際の空／読み込み中／エラー状態を適切に扱える、クリーンな状態に保ちます。具体的な手順については、フェーズ 3 を参照してください。

CLI ファースト — 回避策は禁止（厳守）

このスキルで正式に認められている唯一のインターフェイスは dxs CLI です。Studio の状態の読み取りと書き込み、およびオーサリングの各手順（create/pull、data generate、preview、push）はすべて dxs 経由で行います。CLI に不足がある場合は、回避するのではなく、修正すべき CLI の問題として報告してください。「タスクを完了させる」回避策は、後続のセッションでも必ず再発する不具合を隠してしまいます。

• 情報はサイドチャネルではなく、dxs から取得してください。 フィールドの形状、設定の内容、スキーマ、ブランチの状態は、すべて dxs コマンドで確認できます。コマンド出力に対して head/grep を使うのは問題ありませんが、設定 JSON のスクリプトによる解析（jq/python）や、プラットフォームの生の成果物を読み取ることは禁止です。
• サーバーの契約は、CLI で確認できる根拠から導き出してください。 validate/upsert が拒否した場合は、期待されるサーバーの種類が示されます。また、ブランチ上にある既存の有効な設定（dxs configuration get）から、受け入れられる形式が分かります。この2つがあれば十分です。契約をリバースエンジニアリングするために、プラットフォームのソースリポジトリを開いてはいけません。
• 必要な回避策は、手法ではなくバグ報告です。 タスクを完了するには、残存プロセスの強制終了、CLI 出力形式への対応スクリプト、CLI がすでにラップしているツールの直接操作（例：dxs ng preview 以外でのスクリーンショット撮影）、または生成された JSON の手動編集が必要に思われる場合は、作業を止め、CLI の不足やバグをユーザーに伝え、次の手順について合意してください。
• ハングや孤立したプロセスは、報告すべき不具合です。 ターミナルをブロックする、子プロセスがファイルロックを保持したままになる、または一時状態を残す dxs コマンドは、CLI のライフサイクルに関するバグです。症状の正確な連鎖（コマンド、エラーコード、残存プロセス／ファイル）を記録し、修正につなげてください。ブロック解除のための強制終了は、報告した後に行い、日常的な作業として何も言わずに実施してはいけません。

画面ごとに CAC を1つ（厳守）

デザイン／画面は1つの CAC として作成します。複数の CAC に分解して組み合わせてはいけません。組み合わせは、埋め込みプラットフォームコンポーネント（コンポーネント参照：セレクターを最初に使用）と $shell のダイアログオープナーを通じて行い、CAC の中に CAC を入れてはいけません。1つのコンポーネントには大きすぎるデザインに思える場合は、コンポーネント数を増やすのではなく、デザインを縮小してください。

CAC をタブのコンテンツとして使用する

CAC は、ハブ、エディター、カード、またはダッシュボードのタブコンテンツとして使用できます。グリッドやフォームを配置するものと同じスロットです。コンテナのタブデザイナーで、タブのコンテンツタイプとしてカスタム Angular コンポーネントを選び、プッシュした CAC を参照し、タブのパラメーターを通じてその @Inputs をバインドします（タブが接続するのは CAC の inParams/outParams です）。プラットフォームは、すべての CAC にタブコンテンツの契約を生成します。この契約では、refresh、$refreshEvent、outParamsChange の3つのメンバー名が予約されます。これらの名前を持つ outParam や @Output を宣言してはいけません。また、生成された2つの @Output（$refreshEvent、outParamsChange）を本文内で再宣言してはいけません。名前が衝突すると、メンバー重複によるコンパイルエラーになります。例外は、本文の**refresh() メソッド**です。これは正式に認められたオーバーライドです。コンテナの更新時に CAC を再読み込みするには、本文領域に refresh() を実装してください。生成されたデフォルト（ngOnInit() を再実行するもの）が置き換えられます。

参照資料

• ../datex-studio-shared/branch-setup.md — ブランチ／接続の選択（複数のスキルで共通）。ブランチ ID を決めつけないでください。
• references/custom-angular-components.md — CAC の信頼できるリファレンスです。2 つの作成領域、ライトハーネス／プレビューモデル、注入される $ コンテキスト、モックデータ、manifest.json の形式、前提条件、所要時間、注意点について説明しています。
• ../datex-studio-shared/design-system/README.md — Datex デザインシステム（Fluent 2）：テーマトークン、実際の datex-* コンポーネントクラス名、パターン、コンパイル済み CSS に関する注意点を確認できます。CAC にはスタイルが自動で適用されません。作成した UI をネイティブな見た目にするため、必ず読んで適用してください。
• ../datex-studio-runtime/runtime-globals.md — コンポーネントのコンストラクターが受け取るプラットフォームの $ グローバル（$datasources、$flows、$shell、$utils、$settings、…）
• ../datex-studio-runtime/calling-conventions.md — コンポーネントが実行するコードの UI 層の呼び出しルール（生の HTTP ではなく、フロー／データソースを呼び出します）
• ../datex-studio-conventions/naming-conventions.md — 参照名／表示名のルール（dxs ng create に渡す名前は PascalCase、参照名は camelCase です）
• ../datasource-creator/references/datasources.md — コンポーネントが $datasources／$flows を通じて実データを読み取る場合に参照します。

依存関係

• requirements-gathering スキル — 会話のコンテキストにまだない場合、要件の概要（または目標のスクリーンショット）を作成するために呼び出します。CAC の目的はオーダーメイドの UI なので、具体的なビジュアル目標は、ほかのどのコンポーネントよりも重要です。
• schema-explorer スキル — コンポーネントが $datasources を通じて Footprint データを読み取る場合、接続前にエンティティ／フィールドが存在することを確認するために呼び出します。
• datasource-creator スキル — ブランチにまだ存在しないデータソース／フローがコンポーネントで必要な場合に呼び出します（先に作成してから、コンポーネントで参照し、プレビュー用のモックを用意します）。

前提条件（ホスト側で一度だけ設定）

dxs ng のループには到達可能な Datex API が必要です。開始前に以下を確認してください（references/custom-angular-components.md → Prerequisites を参照）。

1. 対象ブランチ用の、到達可能な Datex API。 ハーネスのエンドポイントはコード生成をサーバー側で実行し、環境による制限を受けません。デプロイ済みイメージでは、API が必要に応じてコード生成を実行できるよう、Node と codegen/node_modules がランタイムステージにインストールされています。そのため、create／pull は、CLI が設定されている任意の Datex Application API（dev、qa、prod のいずれでも）に対して動作します。 （アプリの公開と混同しないでください。公開は実際に dev 環境に制限されており、Development 以外では Azure DevOps パイプラインに委任されます。この制限はハーネスのエンドポイントには適用されません。）
2. 認証済みであること — dxs auth status でサインイン済みの ID が表示されること。
3. agent-browser（ヘッドレススクリーンショット用）— スコープなしの npm パッケージからインストールします。npm install -g agent-browser を実行し、続けて agent-browser install を実行してください。（@anthropic-ai/agent-browser ではありません。この名前では 404 になります。）

CLI のライフサイクル — dxs ng ファミリー

コマンド	オンライン？	Studio にアクセス？	処理内容
dxs ng create <Name> -b <branch> [-d <dir>]	はい	いいえ	初期設定を構築 → サーバーがブランチ用のライトハーネスを生成 → <name>/angularapp/… + manifest.json + mocks/ をローカルに配置します。Studio には何も作成されません。
dxs ng pull <name> -b <branch> [-d <dir>] [--force]	はい	いいえ	既存の CAC に対して同じ配置を行うコマンド（既存コンポーネントの編集開始点）です。フォルダーがすでに存在する場合は構造化された DXS-NG-048 エラーになります。--force を指定すると、フォルダー全体を削除し（実行中のプレビューサーバーがあれば、先に停止してから）、サーバー上の最新状態から再配置します。
dxs ng data generate <folder> -b <branch>	はい	いいえ	コンポーネントが使用する $datasources／$flows の型付きプレースホルダーを使って、<folder>/mocks/harness-mocks.json を初期化します。
dxs ng preview <folder> [-o out.png] [--refresh] [--clean]	いいえ（ローカル）	いいえ	ハーネスをローカルで起動し、コンポーネントのスクリーンショットを撮影して <folder>/render.png に保存します。--refresh -b <branch> は、マニフェストや IO の変更後にハーネスを再取得します。--clean は、停止したサーバーとagent-browser セッション（デーモン、Chrome ツリー、古い状態ファイル）をクリーンアップします。
dxs ng push <folder> -b <branch>	はい	はい	2 つの領域 + manifest.json を抽出 → type-36 を upsert します。最初の push で Studio にコンポーネントが作成されます。サーバーは upsert 時に検証を行います（厳格なゲート）。
dxs ng stop <folder>	いいえ（ローカル）	いいえ	フォルダーの常駐プレビュー開発サーバーと、その agent-browser セッションを停止します（識別情報を確認してロック対象のプロセスを終了し、ロックを削除します）。冪等です（実行中のものがない場合は stopped: false）。作業完了時の破棄手順です。ロックを直接読んだり、手動で taskkill を実行したりしないでください。
dxs ng list -b <branch>	はい	いいえ	ブランチの type-36 コンポーネントを一覧表示します。

create に渡す <Name> はパスカルケース（OutboundCommandCenter）です。参照名はキャメルケース（outboundCommandCenter）、セレクターはケバブケース app-outbound-command-center（自動生成されます。create の出力および manifest.json に保存される値です）となり、ファイル名は app.outboundCommandCenter.component.{ts,html,scss} です。

ワークフロー

[Phase 1: Setup + Requirements]
Follow branch-setup.md for branch selection (NEVER assume a branch ID)
Confirm prerequisites (API reachable, auth, agent-browser)
        |
[requirements brief / TARGET SCREENSHOT in context?]
  +-----+-----+
  |            |
 YES          NO -> invoke `requirements-gathering` (capture the visual target)
  +-----+------+
        |
[Phase 2: Materialize the harness]
dxs ng create <Name> -b <branch>        (new component)
   -- or --
dxs ng pull <name> -b <branch>          (edit an existing one)
        |
[Phase 3: Author the two regions]
Edit <name>/angularapp/src/app/app.<ref>.component.ts:
   __COMPONENT_TYPES__  region -> imports / interfaces / types
   __COMPONENT_BODY__   region -> fields / methods / getters / lifecycle
Edit app.<ref>.component.html and .scss.
NEVER touch the wrapper class line, the @Component decorator, the
constructor, or the //#region ... //#endregion sentinels.
        |
[real data?] -> dxs ng data generate <folder> -b <branch>   (seed mocks)
        |
[Phase 4: Preview loop (screenshot-driven)]
dxs ng preview <folder>        -> writes <folder>/render.png
Read render.png. Compare to the target. Edit regions. Re-preview.
Repeat until it matches. (First preview ~15-46s cold; each later ~10s.)
        |
[Phase 5: Push + verify]
dxs ng push <folder> -b <branch>     (creates in Studio; server validates)
dxs ng list -b <branch>              (confirm it landed)
dxs ng pull <name> -b <branch> -d ./roundtrip   (optional round-trip check)

フェーズの詳細

フェーズ 1：セットアップと要件

1. ブランチの選択については、../datex-studio-shared/branch-setup.md に従います。ブランチ ID を決して推測したり、再利用したりしないでください。セッション中に以前表示されていても、ユーザーに確認を求めます。上記の前提条件も確認してください。
2. コンテキストに要件概要があるか確認します。CAC の場合、最も有用な入力は具体的なビジュアル目標です。目標とするスクリーンショット、またはレイアウト、データ、操作についての正確な説明を用意します。ない場合は、requirements-gathering を呼び出します。目標のスクリーンショットがあれば、フェーズ 4 で目標に近づけるための客観的な反復作業ができます。

フェーズ 2：ハーネスを生成する

dxs ng create <Name> -b <branch>（新規）または dxs ng pull <name> -b <branch>（既存）を実行します。-d components を渡すと、作業コピーは現在のディレクトリではなく、共有の components/<Name>/ ディレクトリ（CAC の作業フォルダーでの慣例）に配置されます。これにより、サーバーにブランチ用の軽量ハーネスを生成させ、ローカルに展開します。

<name>/
  angularapp/…       # the runnable light harness (one component + real typed context + stub services)
  manifest.json      # identity + IO (inputs/outputs) + datasource/flow refs + displayModes
  mocks/             # fixtures the harness $datasources/$flows read during preview

この手順では Studio に何も作成されません。references/custom-angular-components.md → 軽量ハーネスを参照してください。

既存コンポーネントの編集（pull）。 pull は既存のものを編集するための入口で、2 つの作成者領域と .html／.scss を Studio と忠実に往復させます。既存のフォルダーに対して実行すると、許可された 2 つの選択肢を示す構造化エラー DXS-NG-048 が発生します。同期方向を明示的に選択してください。

• ローカルの作業を保持して、ハーネスを更新する → dxs ng preview <folder> --refresh -b <branch> — 領域を保持する唯一の同期方法です（作成者領域／テンプレート／スタイル、manifest.json、mocks/、node_modules を保持します）。
• ローカルの変更を破棄して、サーバーの状態を適用する → dxs ng pull <name> -b <branch> -d <dir> --force — フォルダー全体を削除し（dxs report download --force と同様）、再展開します。CLI は ID を検証する serve ロックを使って、実行中のプレビュー開発サーバーを自動で停止します。プロセスを手動で終了しないでください。また、対象が CAC の作業コピーに見えない場合は拒否します（DXS-NG-049）。

サーバーとの往復で保持されないものが 3 つあるため、--force で pull した後に復元してください。(1) manifest.datasources は空で戻ります（永続化される設定には、ID と inParams／outParams のみが保存されます）。エントリーはオブジェクト { "name": "<ref>", "ref": "<ref>" } として再追加してください。文字列だけでは、次の dxs ng コマンドでマニフェストの検証に失敗します。(2) mocks/ は空で戻ります。dxs ng data generate を実行してから内容を入力するか、以前のファイルを復元してください。(3) node_modules は削除されます。次回の preview で npm install が再実行されます（数分かかります）。マニフェストのエントリーを再追加した後、最初の preview で refetched: true と表示されます（マニフェストの編集によって IO シグネチャが変わり、自動再展開が実行されます）。これは想定された動作であり、バグではありません。

フェーズ 3：2 つの領域を作成する

編集するのは <name>/angularapp/src/app/app.<ref>.component.ts 内の 2 つの作成者領域と、同階層の .html および .scss のみです。

//#region __COMPONENT_TYPES__
//   imports, interfaces, type declarations  (spliced verbatim on push)
//#endregion __COMPONENT_TYPES__

// ...generated @Component + class wrapper + constructor (DO NOT EDIT)...

  //#region __COMPONENT_BODY__
  //   fields, methods, getters, lifecycle body  (spliced verbatim on push)
  //#endregion __COMPONENT_BODY__

ラッパーの class 行、@Component デコレーター、コンストラクター、//#region … //#endregion のセンチネル行は、絶対に変更しないでください。push はセンチネルの間から作業内容を抽出するため、これらを損傷すると抽出できなくなります。コンストラクターには、実際のブランチ型を持つ本物のコンテキスト（$datasources、$flows、$shell、$utils、$settings、$reports、$localization、$operations、$userSettings、$frontendFlows）がすでに注入されています。そのため、本文のコードでは this.$datasources.… などを使い、HttpClient を直接使わないでください。SharedModule はインポート済みなので、テンプレートでは Angular ディレクティブ（*ngFor、*ngIf、[ngClass]、[style.*]）と Material／AG-Grid／ApexCharts を使用できます。

Datex デザインシステムに合わせてスタイルを設定する — CAC にはスタイルが自動で適用されないため、適用しないと異質な見た目になります。必須事項は次のとおりです。独自に作らず、既存のものに合わせる（最も近い既存コンポーネントのマークアップとクラスをコピーする）。ハードコードした hex ではなく、var(--…) のテーマトークンを使う（hex はダークモードと、塗りつぶしコントロールシステムの基盤となるトークンを壊します）。独自の CSS ではなく、実際の datex-* クラス名を組み合わせる（datex-button primary、field-container、grid-table-*、card datex-card、widget-container など）。Fluent アイコンは <i> でのみ使用する。文はセンテンスケースにし、画面上の主ボタンは 1 つにします。トークン変数、コンポーネントクラスの一覧、コンパイル済み CSS に関する注意点については、../datex-studio-shared/design-system/ を参照してください（02-tokens、03-components、06-traps から読み始めてください）。 コンポーネントが実データを読み込む場合は、dxs ng data generate <folder> -b <branch> を実行して mocks/harness-mocks.json に初期データを用意し、プレビューが代表的なデータで表示されるよう、現実的な値を入力します。データソースやエンティティが存在するか不明な場合は、まず schema-explorer を呼び出してください。作成する必要がある場合は、datasource-creator を呼び出してください。

マニフェストの IO 変更（新しい @Input／@Output）にはコード生成の設定が必要です。manifest.json を編集してから、--refresh -b <branch> を付けて再度プレビューします。再生成されたハーネスでは this.inParams.<name> が型付けされ、this.<output> を通じて出力されます。リージョン／テンプレート／スタイルの編集は完全にローカルで行われます（--refresh は不要です）。

ライフサイクルフックは本文に記述します。 ngOnInit／ngOnChanges／ngOnDestroy は __COMPONENT_BODY__ に直接実装します（例：データを読み込む async ngOnInit()）。コード生成でスタブが生成されるのは、実装していない フックだけです。そのため、再取得 によってそれらの整合性が取られます。ただし、IO 変更なしで通常の preview を実行しても再取得されず、フックが生成済みのスタブと重複したままになり、コンパイルエラーが発生します。したがって、再取得を発生させる IO 変更と同時にフックを追加するか、追加後に preview --refresh -b <branch> を一度実行してください。@Input ではないコンポーネント内のインタラクティブな状態（例：モード切り替え）には、ngOnInit で入力値を初期値として設定する通常のフィールドを使います。マニフェストの変更は不要なので、プレビューはウォーム状態のままです。

データソース — 先に作成し、型付きアクセスで参照し、フィクスチャは使いません。 データソースは実際のブランチ設定です。ハーネスを生成する前に datasource-creator（dxs datasource generate → validate → dxs configuration upsert datasource）で作成してください。そうすることで、生成されたハーネスで this.$datasources.<ref> のスタブが型付けされます。manifest.datasources は依存関係を 宣言するだけ で、データソースを作成することはありません。型付き アクセス（await this.$datasources.<ref>.getList({…})）で読み込み、キャストは使わないでください。データソースが存在しない場合、その型付き参照はコンパイルエラーになります。まさにこのフェイルファストの動作を利用して、設定を修正してください（作成してアップサートし、その後、再度マテリアライズします）。その場しのぎのキャスト（$datasources as any）や、埋め込みのサンプルデータへのフォールバックはしないでください。マテリアライズ後にデータソースを追加したのにスタブが表示されない場合は、新しく再マテリアライズし（dxs ng pull／preview --refresh -b <branch>）、利用する前に angularapp/src/app/app.datasource.index.ts に記載されていることを確認してください。サンプルデータ／プレビューデータを置くのは mocks/harness-mocks.json のみです（一時的なもので、プッシュされることはありません）。コンポーネント本文には決して置かないでください。本文はそのまま Studio 設定に挿入されるためです。行のマッピングに使うデータソースのフィールド構造を調べるには、CLI を使い、設定 JSON を手作業で解析しないでください。 アップサート後にマテリアライズする手順であれば、正確なフィールド構造（結果の型＋パラメーター＋フラットなフィールドパス＋コレクション）は dxs report datasource-fields <ref> -b <branch> で確認し、ローカルファイルは dxs datasource validate <file> -b <branch> で検証してください（エラーが見つかると終了コードは 1 になります。これは検証で指摘事項が報告されたという意味で、CLI の不具合ではありません。validation_errors を確認して修正し、再実行してください）。outParams／queryOptionsObjectTypeDef からフィールドを jq／python で抽出しないでください。また、dxs ng create の後は this.$datasources.<ref> がすでに型付けされていることを覚えておいてください。詳しくは references/custom-angular-components.md → 実データの読み込み を参照してください。

フェーズ 4：プレビューの反復（スクリーンショット駆動）

dxs ng preview <folder>          # -> <folder>/render.png

render.png を読み込み、ターゲットと比較して、リージョン／テンプレート／スタイルを編集し、preview を再実行します。これが中心となる反復作業であり、エージェントの真価が発揮される場面です。PNG を読み込み、ターゲットのスクリーンショットとの差分を確認し、調整して、合致するまで繰り返します。型やテンプレートのエラーもここで表面化します（ハーネスは実際のコンポーネントをコンパイルします）。所要時間（ローカル）：create 後の初回の preview では、初回のみ npm install（数分）と約 15～46 秒のコンパイルが行われます。その後の preview は毎回約 10 秒で、編集のホットリロードは約 4 秒です。コールドコンパイルの待機は内部で処理されます（タイムアウトの設定項目はありません）。サーバーまたはブラウザーセッションが固まった場合は、--clean を使って、クラッシュした実行から残った古い agent-browser セッションの状態も含め、両方をリセットしてください。

preview はコンポーネントのデフォルトのレンダリング状態をキャプチャします。クリック操作は行いません。コンポーネント内 UI で切り替えるモード／バリアント（@Input による切り替えではないもの）の場合は、それぞれのバリアントをスクリーンショットに撮るため、デフォルトを一時的に設定するか、@Input／モックから切り替えられるようにしてください。クリックによる選択、トグル、パネルなど、実際の操作状態を確認する場合は、代わりに agent-browser で配信中のハーネスを操作します。<folder>/.dxs-serve.lock からポートを読み取り、agent-browser open http://127.0.0.1:<port> → wait '<css>' → click '<css>' → screenshot out.png の順に実行してください。これにより、シミュレートしたデフォルト状態ではなく、実際のハンドラーの接続を検証できます。

フェーズ 5：プッシュと検証

dxs ng push <folder> -b <branch>     # first push CREATES it in Studio; server validates on upsert
dxs ng list -b <branch>              # confirm it appears
dxs ng pull <name> -b <branch> -d ./roundtrip   # optional: confirm the regions round-trip
dxs ng stop <folder>                 # done for now? dispose of the warm dev server + browser session

Studio に書き込むコマンドは push だけです。サーバーは upsert 時に設定バリデーターを実行します（厳格な必須条件であり、CAC 設定を認識します）。ブランチに存在しないデータソースを参照するコンポーネントや、その他の理由で検証に失敗するコンポーネントは拒否されます。報告された問題を修正して、もう一度プッシュしてください。リージョンセンチネルが破損している場合、push はネットワーク呼び出しを行う前にローカルで失敗します。これは「センチネルに触れない」というルールに違反した場合に起こります。

データソース接続の事前チェック（DXS-NG-047）。 upsert の前に、push は CAC が使用するブランチ固有のデータソースすべてについて、manifest.datasources と、コンポーネント本体内の修飾なしの $datasources.<ref> 呼び出しの和集合を対象に検証します（古い manifest によって検証が妨げられないようにするためです）。データソースがブランチに存在し、かつそのブランチで定義された API 接続設定を指定していることを確認します。これは、ハーネスのモックは接続を一切使用しないため重要です。Studio ではデータソースに "Missing API Connection setting <name>" と表示される場合でも、プレビューは問題なく表示されます。また、プッシュが成功しても、実際のコード生成ビルドが動作するとは限りません。DXS-NG-047 が発生した場合は、dxs source branch settings <branch> を確認してください。dxs datasource generate を使い、このブランチに対してデータソースを再生成します（設定は自動的に解決されます）。アプリに API 接続がまったくない場合は、まず Studio で接続を設定してください（CLI では接続を作成できません）。--skip-connection-check を指定すると、接続がまだないアプリで、意図的にモックのみを使って開発する場合にこのチェックを回避できます。パッケージのデータソース（Module/ref、$datasources.<Module>.<ref>）は対象外です。設定は参照の再マッピングによって解決されます。

作業前チェックリスト

1. ブランチをユーザーに確認済み（決めつけないこと）。前提条件が整っている（API に接続可能、認証済み、agent-browser が利用可能）。
2. 編集したのは2つの領域と .html、.scss のみ — ラッパークラスの行、@Component、コンストラクター、//#region のセンチネルは変更していません。
3. 生の HttpClient やバックエンドへの直接呼び出しはなし — データは this.$datasources / this.$flows 経由で取得し、UI 操作は $shell / $flows 経由で行います（calling-conventions を参照）。
4. モックをシード済み（dxs ng data generate）。コンポーネントが $datasources / $flows を読み取る場合は、プレビューに実際のデータらしい内容が表示されるよう、代表的な値を設定します。
5. manifest.json の IO を変更したら、preview --refresh -b <branch> を実行します（新しい @Input / @Output にはコード生成の再配線が必要です）。参照先のデータソースはブランチ上にすでに存在している必要があります（まず datasource-creator で作成してください。できれば materialize の前に作成します）。また、データソースには 型付きの $datasources アクセスで読み取ります — データソースがない場合はコンパイルエラーとして修正し、キャストで回避してはいけません。サンプルデータは mocks/ に保存します。Phase 3 のデータソースに関する注記を参照してください。
6. プレビュー PNG が目標と一致 — 調整を繰り返して一致させ、レンダリングにコンパイルエラーやテンプレートエラーが残っていません。
7. displayName は100文字以内 — 設定の title / description になります（manifest に独立した description フィールドはありません）。
8. プッシュ後に確認済み — dxs ng list -b <branch> に表示されます。必要に応じて dxs ng pull … -d ./roundtrip で領域を往復確認します。

クリーンアップ — 作業コピーは容量を消費します

materialize した作業フォルダーは約700 MBで、その約85％を angularapp/node_modules が占めます。作業フォルダーは成果物ではありません — push 後の成果物は Studio 内の設定です。

push 成功後（dxs ng list -b <branch> で確認済み）、クリーンアップするかどうかをユーザーに尋ねてください — 無断で行ってはいけません。まず、起動中の開発サーバーとその agent-browser セッションを dxs ng stop <folder> で停止します — PID とイメージを検証して対象を特定する終了処理（無差別な強制終了はしません）で、ブラウザーセッション／デーモンとロックファイルも対象です。このコマンドは冪等なので、無条件に実行してください。.dxs-serve.lock を読み取ったり、手動で taskkill を実行したりしてはいけません — stop より前の CLI では、手動操作は回避策であり、推奨される方法ではありません。（dxs ng preview <folder> --clean は別のライフサイクル操作です。停止ではなくリセットであり、同じ終了処理の後に新しいサーバーを起動します。プレビューが応答しなくなった場合に使い、破棄する場合は stop を使います。）次の2段階から選んでディスク容量を確保します。

• 不要ファイルの削除（セッション間のデフォルト）： <folder>/angularapp/node_modules（約600 MB）、<folder>/angularapp/.angular（ビルドキャッシュ、約100 MB）、および <folder>/.dxs-install-ok のセンチネルを削除します。このセンチネルは node_modules と対になっているため、両方が存在しない場合は preview が再インストールします。作成したファイルはすべて再開可能な状態で残り、容量は約16 MBになります。次の preview では npm install（数分）を再実行し、キャッシュなしでコンパイルします。データ損失のリスクはありません。
• 完全削除（コンポーネントの作業を終えた場合）： 設定が Studio にあることを確認した後に限ります（dxs ng list -b <branch>）。作業コピーを新しくしたい場合は、手動で削除せず、dxs ng pull <name> -b <branch> -d <dir> --force を使ってください。これにより、開発サーバーを自動停止し、削除して再度 materialize します。ロックされたファイルが残って削除に失敗した場合は、構造化エラー DXS-NG-049 が表示されます。再プルせずに最終的に破棄する場合は、まず dxs ng stop <folder> を実行してから、フォルダーを削除します。まれに、以前クラッシュしたサーバーが、ロックによる追跡対象外の子プロセス（node.exe、esbuild.exe）を残すことがあります。それでもロックされたファイルが原因で削除に失敗する場合は、コマンドラインにフォルダーへの参照を含むプロセスをすべて終了し、CLI のライフサイクル上のバグとして報告してください。dxs ng pull は2つの領域と .html / .scss を忠実に再度 materialize しますが、mocks/harness-mocks.json、取得した目標／メモのファイル、manifest.datasources / componentRefs は往復で保持されません — 再プル後に再シード／再追加してください。

プッシュしていない作業コピーは絶対に完全削除しないでください — 作成した領域は他の場所に保存されていません。

よくある間違い

間違い	修正方法
コンポーネントがデータをどのように取得するか（実データかサンプルデータか、@Inputかデータソースか）をユーザーに尋ねる	尋ねないでください。データパターンは固定されています。作成時のプレビューには、型付きの実データソースとmocks/データを使用し、push後は実データを使用します。データパターン（固定のデフォルト — 尋ねない）を参照してください。
JSON本文を手作業で作成してdxs configuration upsert customangularcomponentを実行する	CACはdxs ng（regions + harness + preview）で作成します。JSONを往復させる方法ではありません。dxs ng create／preview／pushを使用してください。
2つのregionの外側（ラッパークラス、@Component、コンストラクター、または//#regionセンチネル）を編集する	pushはセンチネルの間にあるコードを抽出します。それ以外の編集はpush時に失われるか、抽出が失敗する原因になります。__COMPONENT_TYPES__、__COMPONENT_BODY__、.html、.scssの範囲内で編集してください。
@anthropic-ai/agent-browserをインストールする（404）	パッケージはスコープなしのagent-browserです。npm i -g agent-browser && agent-browser installを実行してください。
previewでng serve did not become ready（DXS-NG-042）が報告される	通常は初回のコールドコンパイルに時間がかかっています。DXS_NG_SERVE_TIMEOUT（秒）を延長して再実行し、サーバーが応答しなくなった場合は--cleanでリセットしてください。CLI ≤0.4.13では、相対フォルダー引数もこの原因になりました（スクリプトのパス解決に失敗して開発サーバーが即座に終了していました。現在は修正済みです。その場合の回避策として絶対パスを渡してください）。最新のCLIでも続く場合は、実際のコンパイルエラーです。ng buildを調べてください。
previewがDXS-NG-053（agent-browser 'wait' timed out）で失敗し、コンポーネントが壊れていると思い込む	スクリーンショットのタイムアウトはレンダリングの失敗を意味しません。通常、コンポーネントのコンパイルと配信は正常に完了しています（コンパイル失敗を示すDXS-NG-042のng serve did not become readyとは異なります）。ウォームサーブが古い状態になっている場合もあります。--cleanを付けて再実行し、agent-browserで.dxs-serve.lockのポートを開いてapp-<ref>に内容があるか確認し、実際にレンダリングされていることを検証してください。存在しないコードの問題を追わないでください。
ほかのコンポーネント（またはそれらを開く$shellダイアログ）もプレビュー／オープンできると思い込む	ハーネスで実際のコンポーネントになるのは、作成中の候補だけです。ほかのコンポーネントを開く$shell.open<X>Dialog(...)はコンパイル可能なスタブであり、プレビューでは開きません。$datasources／$flows（実際のブランチ）と独自のUIはすべて完全に動作します。
create／preview後にコンポーネントがStudioに表示されると思い込む	create／pull／data generate／previewはすべて一時的な操作です。Studioに書き込むのはpushだけです（初回のpushで作成されます）。
本文でHttpClientまたはfetchを使う	注入される$datasources／$flowsを使用してください。これらは実際のもので、型付けされており、プレビュー用のモックを使用できます。生のHTTPでは、ブランチの認証／コンテキストが適用されません。
コンポーネントがデータソースを使用しているのに、プレビューが空になる	dxs ng data generateを実行し、mocks/harness-mocks.jsonにデータを入力してください。プレビュー中、ハーネスの$datasources／$flowsはバックエンドを使わずにこれらのフィクスチャを読み込みます。
@Input／@Outputを追加したのに、previewに反映されない	IOの変更にはコード生成の再配線が必要です。manifest.jsonを更新してから、dxs ng preview <folder> --refresh -b <branch>を実行してください。
manifest.datasourcesでデータソースが作成または配線されると思い込む	どちらも行いません。まずdatasource-creator（dxs datasource generate／validate／configuration upsert datasource）でデータソースを作成してください。できればマテリアライズの前に作成すると、ハーネスが$datasources.<ref>のスタブに型を付けられます。manifest.datasourcesは依存関係を宣言するだけです。
データソースがないため、$datasources as anyでキャストしたり、フィクスチャにフォールバックしたりする	アンチパターンです。偽のデータをStudioに送り、配線の問題を隠してしまいます。データソースがない場合は、コンパイルエラーになるのが正しい状態です。データソースを作成／アップサートして再マテリアライズ（pull／--refresh）し、型付けされたthis.$datasources.<ref>を使用して修正してください。
サンプル／フィクスチャの行（または「後で実際のデータソースに置き換える」というコメント）を本文に埋め込む	本文はpushされたtype-36設定にそのまま挿入されるため、フィクスチャや作業中のコメントが本番環境に含まれます。本文は簡潔に保ち、型付きデータソースの読み取りと実際の空／読み込み中／エラー状態を記述してください。サンプルデータはmocks/harness-mocks.jsonだけに置きます。
データソース設定JSONを手作業で解析（jq／pythonを使う、またはoutParams／queryOptionsObjectTypeDefを目視する）して、フィールドの形を調べる	CLIを使用してください。先にアップサートします（マテリアライズの前提条件でもあります）。次にdxs report datasource-fields <ref> -b <branch>でフィールド一覧を確認し、ローカルファイルはdxs datasource validate／context <file> -b <branch>で確認します。dxs ng create後はthis.$datasources.<ref>に型が付くため、手作業で行の型を書く必要はほとんどありません。JSONをスクリプトで処理しないでください。
--refreshのレンダリングは正常に見えるのに、後でpreviewを実行するとコンパイルエラーになる	--refreshによる再起動では、再コンパイルエラーのオーバーレイが表示される前にスクリーンショットが撮影される場合があります。通常のpreviewをもう一度実行して確認し、ハーネスのapp.datasource.index.tsをgrepして、実際にどのデータソースが配線されているかを確認してください。
pushがサーバーに拒否される	バリデーターが実行されました（ハードゲート）。報告された内容を修正してください（よくある原因はブランチにデータソースrefがないことです。schema-explorer／datasource-creatorを実行してください）。その後、再度pushしてください。
pushがDXS-NG-047（データソース接続の事前チェック）で失敗する	CACが使用するデータソースがブランチに存在しないか、そのapiSettingNameがブランチに定義されていないAPI接続設定を指定しています。プレビューが正常にレンダリングされても、Studioではエラーになります（モックは接続を使用しません）。このブランチに対してデータソースを再生成する（dxs datasource generateが設定を自動解決します）か、先にStudioで接続を配線してください。--skip-connection-checkは、意図的にモックのみで開発する場合に限って使用してください。Phase 5を参照してください。
previewが緑色であることを、Studioでデータソースの配線が機能する証拠と見なす	プレビューデータはmocks/から取得されます。ハーネスはAPI接続を使用しないため、apiSettingNameの配線が壊れていても、Studio（またはpushの事前チェック）で指摘されるまでわかりません。pushのDXS-NG-047ゲートが正しい確認方法です。安易に回避しないでください。
ネットワーク呼び出しが行われる前に、ローカルでpushが失敗する	regionセンチネルが破損しています。//#region __COMPONENT_TYPES__/__COMPONENT_BODY__マーカーを正確に復元するか、再度pullして編集をやり直してください。
pull後、mocks/が空でmanifest.datasourcesも存在しない（既存のCACを編集している）	想定どおりです。往復処理で維持されないものが3つあります。manifest.datasources、mocks/、node_modulesです。datasourcesを再追加し（文字列ではなくオブジェクト）、mocks/を再作成して（data generateを実行して入力）、previewによる再インストールを行ってください。2つのregionと.html／.scssは正常に往復します。Phase 2を参照してください。
pullの既存フォルダーエラーを回避するため、作業フォルダーを手動で削除する（または開発サーバープロセスを強制終了する）	手動でクリーンアップせず、フラグを使用してください。preview --refreshはローカルの作業を保持し、pull --forceは破棄します。また、実行中の開発サーバー自体も停止します（IDを確認してロック対象を強制終了します）。ロックされたファイルが残って失敗した場合は、生のWinErrorではなく、構造化されたDXS-NG-049が表示されます。
プレビューが終わったとき、.dxs-serve.lockを読み取ってtaskkillで開発サーバーを手動終了する	それはstopが導入される前の回避策です。dxs ng stop <folder>が破棄用のコマンドです。IDを確認してプロセスツリーを強制終了し、agent-browserセッションを終了してロックを削除します。冪等であり、実行中のものがない場合はstopped: falseを返します。ライフサイクル全体はCLIが管理します。置き換え時はpull --forceで破棄し、preview --cleanでリセットし、stopで破棄します。
manifest.datasourcesのエントリーを単なるref文字列として記述する	エントリーはManifestDatasourceRefオブジェクトです。{ "name": "<ref>", "ref": "<ref>" }のように記述してください。単なる文字列では、次のdxs ngコマンド（data generate、preview、push）でマニフェストの検証に失敗します。
pushが.../config/<ref>/lockでDXS-API-TIMEOUT（約600秒）により失敗する	必ずしもハングや古いロックが原因とは限りません。APIをデバッガーで実行している開発者が、ロック／アップサート処理のブレークポイントで停止しているか、呼び出し中にトークンの有効期限が切れた可能性があります。ブレークポイントを通過させるか、dxs auth loginを再実行してから、pushを再試行してください。
dxs ng data generateを実行しても、$frontendFlowsのref、または埋め込みコンポーネントrefセレクターのデータソースにモックキーが生成されない	生成ツールはすべてのキーを作成するわけではありません。$frontendFlowsのrefは一切作成されず、コンポーネントrefセレクターの元データソースは、生成中にブランチ解決に失敗するとエラーなしでスキップされます。生成後にmocks/harness-mocks.jsonを開き、欠けているキーを手動で追加してください。
$frontendFlowsのrefにモック値を設定し、プレビューで使われると思い込む	$frontendFlowsはハーネス内で、クライアント側の実際のコードとして実行され、モックされることはありません。プレビューには常にフローの実際の計算結果が表示されます。frontendFlowキーのモックエントリーは効果がありません。
フルページ／ダッシュボードCACのrender.pngが途中で切れている	プラットフォームシェルによりhtml, body { overflow: hidden }が強制されるため、previewのスクリーンショットは1つのビューポート（通常は約569px）に制限されます。コンテンツの高さにかかわらず、独自の内側のoverflow-y: autoコンテナーを越えて表示できません。これはプラットフォームシェルの制約であり、レイアウトのバグではありません。最初のビューポートより下の内容を確認するには、render.pngだけに頼らず、より高いビューポートを指定してagent-browserからハーネスの配信ポートに直接アクセスしてください。
CACが存在するか確認したり、参照を追跡したりするためにdxs source explore configs／traceを使う	どちらのコマンドもtype-36コンポーネントをインデックス化しません。型フィルターにも出力にも、CAC／customangularcomponentカテゴリはありません。存在確認にはdxs ng list -b <branch>を使用してください。宣言されたデータソース／フロー／componentRefsを追跡するには、dxs configuration get customangularcomponent <id> -b <branch>を使用するか、マニフェスト／ハーネスのソースを直接読んでください。
refresh／$refreshEvent／outParamsChangeという名前のoutParamまたは@Outputを宣言する、あるいは生成される2つの@Outputを本文で再宣言する	これらは予約済みです。プラットフォームはすべてのCACにこれらを生成します（CACをハブ／エディター／カード／ダッシュボードのタブとして使うためのタブコンテンツ契約です）。名前が衝突すると、メンバー重複のコンパイルエラーになります。例外は本文のrefresh()メソッドです。これは認められたオーバーライドであり、生成されるデフォルト（ngOnInitを再実行する処理）を置き換えます。
CAC の価値はオーダーメイドのビジュアルです。プレビューのスクリーンショットを受け入れテストとして扱い、プッシュする前に目標に近づけてください。