Compose Preview Catalogs

Compose Preview Server

compose-preview serve を支えるサーバーです。カタログのホスティング、ライブレンダリングセッション、プレイグラウンド、ブラウザービューアーの各機能を提供します。その履歴は yschimke/compose-ai-tools から切り出されました。CLI は引き続きそちらにあり、このリポジトリの配布物を起動します。

このリポジトリが配布するもの

各 GitHub リリースのアーカイブのみで、Maven Central には何も公開しません。

アセット	内容
compose-preview-server-<v>.tar.gz	サーバーです。カタログのホスティング、HTTP ルート、プレイグラウンド、ビューアーの各機能を提供します。compose-preview serve、browse、ui-builder が起動するものです
compose-preview-viewer.html	ポータブルな MCP App ビューアーです。yschimke/compose-preview-mcp が、ローカル MCP サーバーとともに再公開します
compose-preview-mcp-<v>.tar.gz	このリポジトリのビルド成果物ではなく、ブリッジです。compose-preview-mcp の最新の配布物を、このリリース名で再添付したもので、compose-ai-tools#5929 より前のバージョンの CLI が引き続きここから取得できるようにするためのものです

Compose/Wasm フロントエンドは、これらのリリースのアセットではありません。 yschimke/compose-ui-builder が、同リポジトリ独自のリリースで compose-preview-ui-builder-web-<v>.zip としてビルド、リリースします。このビルドはそこから取得します。サーバーアーカイブには、いずれにしても展開済みのコピーが含まれます。単体の zip は、エディターを自分で配信する場合、または既存の serve に --ui-builder-dir を指定する場合に使います。

ここには Maven の座標はありません。以前は 6 つのモジュールを公開していました。compose-preview-serve、compose-preview-mcp、そして最初のモジュールの POM に記載されていたため Maven Central にだけ存在していた 4 つのモジュールです。しかし、この構成は得られるものよりもコストのほうが大きいものでした。プロジェクトの依存関係は座標を通じて公開済みの POM に到達するため、:server に依存関係を追加するには、その依存関係も公開する必要がありました。これを誤った結果、3.1.0 では compose-preview-server:ui-builder-export-jvm:unspecified が配布され、3.3.0 から 3.8.0 までは解決できない compose-preview-serve が配布されました。誰も必要としていない推移的依存関係のために、誰も解決できないリリースが 6 回続きました。

唯一のライブラリ利用者は compose-ai-tools の :cli でした。compose-preview-serve に対して、ワイヤーの差異を検出するテストを 2 つコンパイルしていました。現在、そのテストは配布物を起動します （compose-ai-tools#5436）。serve が実際に実行するアーティファクトなので、実際に配布されるワイヤーを検証できます。3.24.0 までの公開済みの座標は引き続き Maven Central で解決できますが、今後新たに公開することはありません。

render-host が存在するのは、パックされたバンドルのレンダリングと Git からのプレビュータイムラインの読み込みではソケットを開かないためです。その処理だけを行う呼び出し元が、実行のためだけに ktor-server-*、jmdns、kotlin-reflect をリンクする必要はありません。これはここではなく、compose-ai-tools から公開されます。依存するすべてのものがそこにあり、オフライン動作もそのレイヤーに属するためです （#180）。以前はこのリポジトリの :render-host モジュールで、compose-preview-render-host として公開されていました。この座標は、それに固定している利用者向けに最終版の 2.x で引き続き解決できます。新しい座標は compose-ai-tools のバージョン系列に属します。実測した変更前後の値と、意図的に削除できない推移的依存関係は、そちらのビルドファイルに記録されています。また、checkRenderHostIsServerFree もそちらに移動しました。 UI ビルダーは別のリポジトリ、yschimke/compose-ui-builder にあり、:server はリリース版としてこれを利用します。:ui-builder-runtime は、そこでの信頼できる永続的なデザイン状態、厳密なカタログ検証、リビジョン固定のエクスポートオーケストレーションを管理します。:server は HTTP／認証を提供し、その限定的なレンダーリクエストをレンダーホストに橋渡しします。そのため、ランタイムは Ktor、デーモン／レンダーホスト、MCP、Compose UI に依存せず、オフラインのレンダーホストには UI ビルダーのプロトコルやサービスとの接続がありません。3 つの jar と BOM は、gradle/libs.versions.toml の composeai-ui-builder として Maven Central から取得し、エディターのアーカイブはそのリポジトリの GitHub リリースから取得します。両方を同時に開発する場合は、-PcomposeUiBuilderDir ですべてをチェックアウトに差し替えられます。

ビルドは意図的にリポジトリに依存しない構成です。Compose Preview の実装アーティファクトは、gradle/libs.versions.toml に記載されたバージョンで Maven Central から解決されます。ワイヤーコントラクトは、compose-preview-contracts から個別に解決されます。mavenLocal() リポジトリはなく、このリポジトリの外部に共有バージョンカタログもありません。コンポジットビルドは明示的に有効にした場合のみ使用されます。上流リポジトリには -PlocalBuilds=tools,daemon,contracts を、UI ビルダーには -PcomposeUiBuilderDir を指定します。また、未リリースのコントラクトやジェネレーターの変更を使う場合は、明示的なローカル依存関係マニフェストで、ローカルのチェックアウトからコンパイルしたアーティファクトを選択します。これらのオプションを設定しなければ、リリース済みの依存関係グラフが維持されます。

Java

配布物の実行には Java 17 以降が必要です。UI ビルダーの PNG／SVG エクスポートには Java 21 が必要です。

この 2 つのバージョン要件は異なります。ビルドファイルから推測させず、明確に述べておく価値があります。サーバー本体、mcp serve、およびこのリポジトリが公開するすべてのアーティファクトは Java 17 をターゲットにしています。これは、compose-ai-tools の CLI が Java 17 のツールチェーンでこれらをコンパイルし、その serve／mcp serve コマンドがこの配布物の起動スクリプトを別プロセスとして実行し、JAVA_HOME／PATH から java を解決するためです。この要件を上回るのは UI ビルダーのレンダラーだけです。ラスタライズするデザインは、Java 21 向けにコンパイルされた Compose Preview で描画され、レンダーバンドルにパッケージ化された後、サーバー自身の JVM 上で動作するデーモンに展開されます。

古い JVM でもサーバーは起動し、それ以外の機能はすべて動作します。ただし、UI ビルダーでは PNG および SVG のエクスポートが無効になり、起動時に検出したバージョンと必要なバージョンが表示されます。利用を再開するには JAVA_HOME を Java 21 の JDK に設定するか、--ui-builder-state-dir none を渡して UI ビルダーを完全に無効にしてください。公開されているコンテナーイメージ（deploy/image/Dockerfile）は Temurin 21 をベースにビルドされているため、どちらの要件も満たしています。

両方の最低バージョンは、gradle/libs.versions.toml の java-server と java-ui-builder として一元的に宣言されており、その理由もここに記載されています。:server:checkServerJvmFloor は、java-server を超えるものが配布物のクラスパスに含まれるとビルドを失敗させます。また、レンダーバンドルには java-ui-builder がデータとして含まれているため、起動メッセージが説明対象のバイト列と食い違うことはありません。

Renovate は Java 17／21 の各系列と Temurin 21 のイメージを、選択されたメジャーバージョンに維持しながら、メンテナンス更新を許可します。その理由、Java 25 提案の根拠、および新しいランタイムを採用するための要件については、Java バージョンポリシーに記載されています。

ビルド

./gradlew check に必要な JDK は 17 です。UI ビルダーのフロントエンドレーンは、独自のリポジトリで 21 を使ってコンパイルされます。ここで両方の JDK が引き続き必要なのは、チェックアウトからそのリポジトリの Wasm ディストリビューションをビルドする visual-harness レーンだけです。Gradle は、すでに検索対象としている場所（/usr/lib/jvm、SDKMAN、asdf、jabba）にインストールされた 21 を検出します。見つからない場合は No matching toolchains found for requested specification: {languageVersion=21} というエラーになり、対処方法はターゲットを下げることではなく、JDK 21 をインストールすることです。

./gradlew check ktfmtCheckAll
npm --prefix serve-web ci
npm --prefix serve-web run verify

単独でインストールできるビジュアルハーネスは preview-harness/ にあります。実験的な Compose/Wasm フロントエンドは wasm-ui/ にあります。UI ビルダー本体（エディター、レンダラー、アートワーク、Jetcaster フィクスチャ）は yschimke/compose-ui-builder にあります。このビルドでは、そのリポジトリのリリースからエディターアーカイブ、ランタイム、エクスポートを解決し、ハーネスはそのリポジトリのチェックアウトからレンダラーとフィクスチャのディストリビューションをビルドします。サーバーのディストリビューションはエディターを /ui-builder/ にパッケージします。既存のカタログスコープの /wasm/<system>/ プレビューアプリケーションは、独立した機能およびルートとして維持されます。エディタールートでは、固定された Jetcaster デザインを囲むインタラクティブな Wasm エディターが開きます。独立したビジュアルハーネスでは、クリーンなベンチマークモードも引き続き利用できます。エディターは、サンドボックス化された iframe 内の /ui-builder/runtime/<runtimeId>/ に、保持された正確なレンダラーランタイムをマウントします。また、エディターのオーバーレイを Compose ツリーに配置せずに、計測したノード／スロットのジオメトリを受け取ります。カタログのランタイムは、カタログの世代が破棄された後も、コミットが固定された小さなソース記述子を保持します。そのため、古いデザインリビジョンでも再起動後に正確なランタイムを復元できます。圧縮アーカイブは上限付きのカタログ BLOB プールを共有します。展開済みの過去のツリーは、無制限の第 2 アーティファクトストアではなく、非アクティブ時のタイムアウトと厳格な件数上限を備えたプロセス内リースとして保持されます。

Remote Compose オーサリング拡張機能は、デフォルトで無効のコンパイル時オプション -PuiBuilderRemoteCompose=true の背後にあります。2 つのリポジトリにまたがっており、MCP アダプター側はここで生成され、サーバー側は UI ビルダーのエクスポートにそのビルド時点で組み込まれます。そのため、サーバー側を有効にするには、このオプションを指定して UI ビルダーのチェックアウトを使ってビルドする必要があります（-PcomposeUiBuilderDir=…）。機能の範囲と検証方法を参照してください。

再起動後、設定済みのカタログは読み込み中もホームページのカードを表示し続けます。永続ボリュームに --catalog-cache-dir を指定すると、各カードに最後に成功したヒーローサムネイルを、小さな「カタログを読み込み中…」ラベルとともに表示できます。サムネイルの対象は、カタログに設定されたリポジトリとブランチに限定されます。読み込み待ちのカタログを開くと、残りの起動時フェッチより優先されます。すでに実行中のフェッチは先に完了します。カタログが利用可能になるまで、読み込みページは自動的に再試行します。

エージェントプラグイン

yschimke/compose-agent-plugins から、ローカル MCP プラグイン compose-preview、またはホスト型カタログと UI ビルダープラグイン compose-catalogs をインストールしてください。このガイドでは、サポート対象の各エージェントホスト、yschimke/skills の正規スキルバンドル、以前のマーケットプレイスからの移行について説明しています。

リモートカタログ MCP

サーバーでは、ホスト型カタログすべてを、/mcp にある単一の集約型 Streamable HTTP MCP エンドポイントを通じて公開できます。--agent-grants --catalog-mcp で有効にしてください。公開済みリソースには有効期間の短い preview グラントが必要です。一方、注文に応じて生成されるレンダリングと構造化データ製品には live グラントが必要です。このエンドポイントは、状態を持つ UI ビルダーのオーサリング MCP サーフェスとは別ですが、どちらも同じ認証済みユーザー承認・取り消しフローを使用します。カタログ MCP の設計とセットアップガイドを参照してください。

ローカルデーモン MCP

エージェントやエディタープラグインが使用するローカルの stdio MCP サーバー compose-preview-mcp は、履歴とリリースを独自のバージョン系列で管理する形で yschimke/compose-preview-mcp に移動しました。compose-preview mcp serve は、そのリポジトリのリリースから取得します。ツール、エディターアプリ design_open、.rc ビューアーについては、そちらに記載されています（docs/LOCAL_MCP.md）。このリポジトリでは、ホストされた /mcp が提供する MCP App ページ（mcp-app/compose-preview-viewer.html、mcp-app/preview-library.html）を引き続き管理します。compose-preview-mcp は各リリースからタグを使ってこれらをコピーします。

スマートフォンでの利用

ページはスマートフォンで動作し、サイトは共有先を備えたアプリとしてインストールできます。スクリーンショットを共有すると、画像が添付されたバグレポートが開きます。serve --lan は、スマートフォンでノートパソコンのサーバーを開くための QR コードを表示します。平文 HTTP の LAN アドレスはセキュアコンテキストではないため、アプリのインストール、Web Share、クリップボードには HTTPS または adb reverse が必要です。 スマートフォンでの Compose Previewを参照してください。

空間および WebXR プレビュー

ポータブルバンドルでは、XR プレビューをバージョン 1 の SpatialScene ドキュメントとそのパネルテクスチャとして公開できます。

previews/<preview-id>.spatial/scene.json
previews/<preview-id>.spatial/<panel>.png

ビューアーはこれらのシーンを、軌道操作が可能な Three.js/WebGL ステージで開き、ブラウザーが immersive-vr WebXR セッションを提供している場合は Enter VR を表示します。WebXR にはセキュアコンテキストが必要なため、ヘッドセットからサーバーに HTTPS 経由でアクセスする必要があります（localhost はデスクトップでの WebGL 開発に引き続き適しています）。アップロードするバンドルに含められるのは、JSON シーン文書と PNG/JPEG/WebP テクスチャのみです。すべてのアセットは、シーンと同じオリジンの /spatial/ ルートから提供されます。

スタンドアロンディストリビューションのビルドと実行方法：

./gradlew :server:distTar
tar -xzf server/build/distributions/compose-preview-server-*.tar.gz
./compose-preview-server-*/bin/compose-preview-server help

バイナリには 5 つのコマンドがあり、help で一覧を表示できます。

コマンド	動作
serve	プレビューをホストします。取得したバンドル、公開済みカタログ、または --module / --discover を指定したローカルモジュールの @Preview 関数が対象です。
ui	このプロジェクトのプレビューをビルドし、それらを使って Compose UI ビルダーを開きます。
playground	スニペットのコンパイルレーンを許可した serve です。
design	起動済みのサーバーから UI ビルダーのデザインをレンダリング、エクスポート、または読み込みます。サーバーを起動しない唯一のコマンドです。
help [command]	コマンド一覧、または指定したコマンドのオプションを表示します。

コマンドを指定せずにフラグを渡すこともできます。compose-preview-server --module app は compose-preview-server serve --module app とまったく同じで、引き続きサポートされています。

ローカルモジュールのページ（serve --module / --discover、および compose-preview browse）には再ビルドボタンがあります。編集後にビルドホストへ :<module>:composePreviewCompile を要求し、サーバーを再起動せずに結果を表示します。変更されたのがクラスのみの場合は、実行中のデーモンがクラスを入れ替え、キャッシュ済みレンダリングを破棄します。デーモンのクラスパスまたはプレビューセットが変更された場合は、新しいビルドでセッションを再起動します。ビルドに失敗しても、最後に成功したレンダリングが画面に残ります。同じ POST /{session}/rebuild は Bazel ワークスペースにも対応し、ビルドホストはコンパイル要求に対してモジュールのターゲットを再ビルドします。

browse は保存時にも再ビルドします（--no-watch で無効になり、serve は --watch で有効になります）。Gradle モジュールではプロジェクトディレクトリを監視し、build/ とツールの状態を除外します。Bazel モジュールではソースディレクトリを監視します。保存が連続した後、しばらく静かになってから再ビルドします。開いているページはロングポーリングの GET /{session}/reload を使います。新しいレンダリングは画像をその場で置き換え、再起動時はページを再読み込みします。ビルドに失敗すると、最後に成功したレンダリングを表示したまま、理由とともに stale: を表示します。モジュール外部（兄弟モジュールや共通ビルドスクリプト）の Gradle 編集は監視されないため、再ビルドを実行してください。 ui にはビルドホスト、つまり compose-preview バイナリが必要です。ローカルの Gradle プロジェクトの検出とビルドは、このサーバーが自ら行うのではなく、パイプ経由で依頼する処理だからです。ビルダーのパレットには、パッケージ化されたデザインシステムのカタログが含まれます。ui が追加するのはプロジェクトです。--ui-builder-components にモジュールで検出された components.json を指定すると、Compose エクスポートによってコンポーザブルの呼び出し箇所が生成されます。CLI をインストール済みのチェックアウトから、次を実行します。

compose-preview-server ui --module app

design はこの系統のクライアント側で、ここでサーバーを起動しない唯一のコマンドです。すでに起動しているローカルの serve またはデプロイ済みのサーバーに接続し、デザインのピクセルデータまたは生成されたソースをファイルに書き出します。これにより、セッションごとに curl で /mcp にアクセスし、jq でエンベロープを展開して base64 -d を実行し直す必要がなくなります （#529）。

export COMPOSE_PREVIEW_TOKEN=...          # or let the command ask a human to approve a grant
compose-preview-server design list --server https://preview.example.com
compose-preview-server design status --workspace . --summary
compose-preview-server design render spotify-wear-widget -o cover.png
compose-preview-server design export spotify-wear-widget -o Widget.kt
compose-preview-server design get spotify-wear-widget > design.json

認証情報は $COMPOSE_PREVIEW_TOKEN（または以前の $COMPOSE_PREVIEW_UI_BUILDER_TOKEN。こちらは scripts/ui-builder/design-sync.mjs が読み込みます）から読み取られ、フラグからは読み取られません。どちらも設定されていない場合、または再起動後に権限が失われている場合、このコマンドはサーバー独自のデバイスコードフローを実行します。承認リンクとコードを表示して、人の操作を待ってから処理を続けます。エクスポートが拒否された場合は、ジェネレーター独自の診断を stderr に出力して、何も書き込まずにゼロ以外の終了コードを返すため、CI でも利用できます。

design status は範囲を限定した SessionStart プローブです。チェックアウト内の ui-builder/designs/index.json を読み込み、サーバー側のデザインのうち未確認のコメント数を合計し、追跡対象の一時コピーをそれぞれサーバー上の最新ドキュメントと比較します。認証フローは開始せず、追跡対象のサーバー URL をたどって別のオリジンに接続することもありません。--summary は、対応が必要なものがある場合に、内容を秘匿した 1 行を出力します（なければ何も出力しません）。--json は、バージョン付きのステータスエンベロープを出力します。

--local は、このコマンドのうちサーバーをまったく必要としない部分です。サーバーが実行するのと同じジェネレーター、コンパイラー、レンダーデーモンを ここで 実行し、ディスク上のカタログバンドルを使います。また、フレームがない場合、その事実だけでなく理由も示します。ワイヤー応答からはその情報を得られません （#551）。これにより、壊れたホストをデバッグできます。design get でドキュメントを取得すれば（これはレンダーレーンの問題を疑う場合でも、単なる読み取りです）、そのファイルをどこでも再生できます。

compose-preview-server design get spotify-wear-widget --server https://preview.example.com > doc.json
compose-preview-server design render --document doc.json --local \
  --catalog wear-m3.bundle --assets ./assets -o replay.png
compose-preview-server design export --document doc.json --local   # the generated Kotlin, no server

ローカルレンダリングでは、解決されたクラスパス、構築されたデーモンオープナー、コンパイラー独自の診断が出力されます。--components <catalog>=<components.json> は、レコード駆動型カタログの呼び出し箇所がどのレコードに基づいているかを指定します。これは serve --ui-builder-components と同じ動作です。

ブラウザーのクライアントは、GET /api/ui-builder/v1/catalogs/{system}/templates で、カタログに公開されている初期ドキュメントを取得できます。UI-builder の読み取りアクセスが必要で、ホストのカタログ制限が適用されます。共有レスポンス CatalogTemplateDocumentsV1 には、スキーマバージョン、完全な catalogPin（システム、リビジョン、機能ダイジェスト、ランタイム）、テンプレート ID をキーとする templates マップが含まれます。選択画面での順序は、ドキュメントマップではなく、カタログの順序付きメタデータに基づきます。カタログの更新後、ドキュメントが提供中の機能にまだ一致していない場合は 409 が返されます。クライアントは再試行し、最後に一致したセットを保持してください。レスポンスには Cache-Control: no-store が設定されます。オフラインエディターは、検証済みドキュメントを完全なカタログピンとともに、ブラウザーのストアに明示的に保存します。

サインイン済みのユーザーは、サービスが読み取りを許可するすべてのデザインを /ui-builder/designs で閲覧できます。ページでは、自分が所有するデザインと他のユーザーが共有したデザインが分けて表示され、開けない場合はサービスから返される正確な理由が示されます。また、所有者はページ内で共有設定を管理できます。このページの範囲はユーザーごとに限定されており、すべてのデザインを扱う運用者向け画面 /admin/ui-builder とは連携していません。 /ui-builder/projects は、複数のデザインファイル、共有 JSON リソース、コラボレーターをアプリのワークスペースにまとめます。プロジェクトでは GitHub からコミットに固定された .uid ファイルを読み込み、レビュー済みの編集をプルリクエストとして提案できます。また、各デザインの正式なホームを表示します。詳しくは UI_BUILDER_HOSTED_PROJECTS.md をご覧ください。

配信カタログ独自のコンポーザブルは、コンポーネントパック（--ui-builder-packs confetti-mobile=mobile,confetti-wear=wear）としてビルダーのカタログ内で提供することもできます。作成者はエディターの設定からこれを有効にできます。詳しくは docs/design/UI_BUILDER_COMPONENT_PACKS.md をご覧ください。

リリースでは、その配布物を GitHub リリースに添付し、再利用可能な ghcr.io/yschimke/compose-preview-host イメージを公開します。独自のインスタンスは、永続状態とオプションの HTTPS に対応した独立した Compose の例である deploy/example から起動できます。ロールアウト、自動更新、大規模なホストが必要な場合は、deploy/image のフル機能スタックに移行できます。独自環境へのデプロイでは、このリポジトリが提供するものと、独自のデプロイ設定に含めるものについて説明しています。

リリース

release.yml の 1 つのレーンで、compose-preview-server-<v>.tar.gz をビルドして compose-preview-viewer.html とともに GitHub リリースに添付し、その後 compose-preview-host イメージをビルドします。

このレーンが成功するまで GitHub リリースはドラフトのままです。そのため、ビルドに失敗しても、アセットが存在しないタグが残ることはありません。

以前はスキップ可能な Maven レーンが別にあり、release:no-maven ラベルと、それを無効にする publish_maven ワークフロー入力が用意されていました。公開の終了に伴い、どちらもなくなりました。今後のすべてのリリースは、このラベルがかつて要求していた内容となります。

リポジトリの境界

checkServeModuleBoundary は、推移的依存関係も含めて、解決済みの実行時クラスパスを調べます。プロジェクト依存関係、レンダラーやデーモンの実装、Gradle プラグイン、未登録の ee.schimke.composeai 座標を拒否します。承認済みの許可リストを更新するのは、依存関係の最低バージョンの変更を意図的にレビューした場合に限ってください。

バイナリとソースの互換性を維持するため、ソースパッケージは引き続き ee.schimke.composeai.cli.serve です。パッケージ名の変更はリポジトリの所有権とは無関係であり、抽出の対象ではありません。