composing-grid-canvases

グリッドキャンバスの構成

グリッドキャンバスはアプリではなく、構成です。それぞれが独自のソース、ビルド、配置契約を持つ再利用可能なウィジェットであるコンポーネントキャンバスを描画する配置のグリッドです。ユーザーのホームキャンバスは、個人チャンネルにある通常のグリッドキャンバスです。レイアウトはデータです。公開またはパッチ適用すると、ビルドなしで即座に反映されます。

3 種類のキャンバスは、同じライフサイクルを共有します。

• freeform — スタンドアロンアプリ（これらは building-canvases スキルが担当します）。
• component — 再利用可能なウィジェット。フリーフォームと同じソース／ビルドパイプラインに加えて、配置契約を持ちます。公開範囲はチャンネルに従います。個人チャンネルなら非公開、チームチャンネルなら共有されます。
• grid — コンポーネントを参照する配置のレイアウト。ファイルソースはなく、レイアウトのみです。

解決の手順：設定、フォーク、ビルド

グリッドの配置にコンテンツが必要な場合（「ここに天気ウィジェット」「自分のタスクのカンバン」）、次の順に解決します。既存のコンポーネントを配置するほうが、重複して作成するより優先されます。

1. ストアを検索する：canvas-list に kind=component と search=<what the widget shows> を指定します。component_meta と published_build_id の両方が設定されているコンポーネントは配置できます。その configSchema で依頼内容を表現できる場合（「リスボンの天気」→ 既存の天気コンポーネントに config: {"location": "Lisbon"} を指定）、配置して設定します。コードは書きません。
2. フォークする：コンポーネントは近いものの、設定では依頼内容を表現できない場合は、ソースを読み込み（canvas-source-retrieve）、新しいコンポーネントを作成し（kind=component を指定して canvas-create を実行）、調整して公開します。新しいコンポーネントの説明に、変更点を記載します。
3. 新規作成する：適合するものがない場合は新規作成します。詳しくは、以下の「コンポーネントの作成」を参照してください。

新しいコンポーネントは、作成したチャンネルに追加されます。ユーザーがより広い範囲での共有を希望しない限り、対象のグリッドと同じチャンネルに作成してください。

コンポーネントの構築

コンポーネントは自由形式のキャンバスとまったく同じ方法で作成します。building-react-quill-canvases（または building-html-canvases）に加えて、querying-canvas-data と validating-and-publishing-canvases を読み込みます。 追加される要素は3つです。PostHog データを表示するコンポーネントにも、通常のキャンバスと同じ検証可能性のルールが適用されます。インサイトに基づく数値には、保存済みインサイトへのリンクを付けます。また、アドホッククエリでは、実行された正確なクエリを確認できるようにします（querying-canvas-data の「検証可能性」を参照してください）。 references/component-example.md にある、完全でビルド可能なプロジェクトから始めてください。エンベロープ、配置の契約、機能の宣言、そして防御的な ph.state アクセスは、即興で作ると壊れやすい部分です。

• kind=component で作成し、ストア検索向けの description を記述します。ウィジェットが表示する内容と、設定で制御できる内容を説明してください。このテキストを基に、今後の配置が検索されます。

• プロジェクトのトップレベルの component キーで配置の契約を宣言します。

  {
    "component": {
      "size": { "defaultW": 2, "defaultH": 1, "minW": 1, "minH": 1, "maxW": 4 },
      "configSchema": {
        "type": "object",
        "properties": { "location": { "type": "string", "description": "City to show weather for" } }
      }
    }
  }
  

  サイズの単位はグリッドユニットです（幅は1〜12、高さは1〜40）。minW <= defaultW <= maxW を満たす必要があります。この範囲は参考値です。ユーザーは配置のサイズを任意に変更できるため、この範囲はデフォルト値と警告に反映されますが、変更を拒否することはありません。設定スキーマで使用できる語彙は、許可リストにある次の項目だけです。type、title、description、default、properties、required、additionalProperties、items、enum、const、minimum、maximum、minLength、maxLength、minItems、maxItems、format。$ref と pattern は使用できません。検証で拒否されます。

• レスポンシブに設計します。 コンポーネントのルートに min-h-screen を指定して、配置用 iframe のビューポートを満たし、コンテンツに応じてその高さを超えて伸びるようにします。 ユーザーがドラッグして変更するあらゆるサイズに対応できるよう、レイアウトを調整します。2×1の配置はひと目で把握できるタイルに、6×4の配置はアプリ全体を表示できる画面にします。 ルートに h-screen を使用しないでください。ビューポートの高さが固定されると、flex カラムの高さに上限が設けられます。そのため、高さのある子要素はスクロールせずに縮小・クリップされます。 ルートに h-full も使用しないでください。公開済みコンポーネントのアーティファクトシェルでは、html、body、#root 要素に明示的な高さが設定されないため、height: 100% はコンテンツの高さに縮みます。 minW×minH でも有用に表示されるようにし、配置ごとの入力には config だけを使用します。

通常のキャンバスと同様に公開して、ビルドが完了するまで待ちます。ビルドが完了していないコンポーネントは、グリッド上で公開できません。

キャンバス全体の構成

キャンバス全体に関する依頼（「作業中の内容をまとめるホームキャンバス」など）は、通常、1つではなく複数のウィジェットを意味します。 最初に全体を計画し、懸念事項ごとに1つの配置を用意してから、上記の手順に沿ってそれぞれ解決します。 配置全体をまとめて整えます。重なりがないようにし、各ウィジェットの表示内容に合ったサイズにし、タイルが隅に散らばらないようグリッドを意図的に埋めます。 ウィジェットごとに1回ずつ書き込むのではなく、レイアウトの書き込みはまとめて行います（初期レイアウトでは1回公開し、その後は必要な箇所だけを修正します）。最後に、すべての配置が公開済みまたは失敗済みの状態であることを確認します。「生成中」のままにしないでください。

キャンバスのコメント

ユーザーはキャンバスにコメントスレッドでフィードバックを残します。 まず exec search ^canvas-comments-(list|retrieve)$ を実行します。 両方のツールがある場合は、キャンバスを変更する前と後にスレッドを一覧表示し、未解決のものに対応します。壊れているウィジェットに言及したコメントが、修正の指示になります。 これらのツールは、タスクのないスレッドも含め、キャンバス上のすべてのスレッドを返します。どちらかのツールがない場合は、working-with-task-comments の説明に従い、タスクのコメントツールを使用します。

グリッドの編集

読み取り → パッチのループは、ソースの公開について validating-and-publishing-canvases で説明されているものと同じようにガードします。canvas-source-retrieve の代わりに canvas-layout-get を使い、書き込みには canvas-layout-patch（外科的な操作、ガードが必要）または canvas-layout-publish（初期レイアウトや全面的な再構成向けの完全なドキュメント）を使います。409 が発生したら、レイアウトを再読み込みし、変更を適用し直して、再度パッチを適用します。

操作：

• add_placement — 新しいボックスを追加します：{id, status, x, y, w, h, ...}。プレースメント同士は重ならず、grid.columns の範囲を超えないようにする必要があります。
• update_placement — id が一致するプレースメントに changes をマージします。描画済みのボックスに内容を設定する例：{"op": "update_placement", "id": "p1", "changes": {"status": "live", "component": "<component canvas id>", "config": {...}}}。
• remove_placement、set_grid

プレースメントのライフサイクル

プレースメントの status によって、レンダラーに表示される内容が決まります。

• pending — ユーザーがボックスを描画したものの、まだ説明していない状態です（または、プロンプトのディスパッチ待ちです）。
• generating — エージェントタスクがボックスの内容を生成中です。generationTaskId がタスクに関連付けられ、prompt に依頼内容が記録されます。タスクに基づいてプレースメントの作業を始めるときに設定してください。
• live — version（デフォルトは "latest"。特定のバージョン ID も指定可能）で component をレンダリングします。そのコンポーネントが公開済みで、操作中のユーザーから見える必要があります。
• failed — 生成に失敗した状態です。ユーザーが再試行または説明し直せるよう、prompt は保持してください。

タスクでプレースメントの内容を生成するよう依頼された場合、プレースメントのプロンプトとボックスのサイズが作業指示になります。描画された w×h に合わせ、由来を示すためプレースメントの prompt を変更せずに保持してください。

発生する検証エラー

レイアウトの公開はアトミックに検証され、各エラーには該当するプレースメントが示されます。よくあるエラーは次のとおりです。

• component_not_found — ID が間違っている、削除済み、コンポーネントではない、または操作中のユーザーから見えない状態です（他のユーザーの個人チャンネルにあるコンポーネントは配置できません）。
• component_not_published — コンポーネントのプレースメント契約が一度も公開されていません。
• placement_config_invalid — config がコンポーネントの configSchema と一致しません。
• placement_size_out_of_contract — エラーではなく警告です。ボックスの w／h がコンポーネントの推奨範囲外です。公開は成功しますが、コンポーネントはレスポンシブにレンダリングされる必要があります。
• placements_overlap／invalid_placement — ジオメトリに関するエラーです。他のウィジェットを削除するのではなく、座標を修正してください。

返信の最後に、キャンバスツールが返す url フィールドを使ってグリッドキャンバスへのリンクを記載してください。キャンバス URL を自分で組み立ててはいけません。