zframes

zframes — ダッシュボードを自動生成

zframes CLIを操作してdashboard.jsonの仕様を記述することで、ユーザーのダッシュボードをセットアップして実行します。CLIがランタイムそのものです。単一のファイルを参照するビルド済みダッシュボードアプリを配信し、ブラウザーで編集できます。このタスクではJSONのみを記述します。.tsxファイルは作成も編集もしないでください。

1つのスキルで3つの作業 — 配信、更新、作成。 何よりも先に、依頼がどれに当たるかを判断します（ステップ1）。「ダッシュボードを起動して／開いて／配信して」は、ユーザーがすでに持っているダッシュボードを配信するだけです。ダッシュボードが存在する場合に最もよくある依頼で、ヒアリングとinitは一切行いません。以下の完全な構築手順を実行するのは、作成の場合のみです。

0. CLI

ランタイムはnpmのzframes CLIとして提供されます。必ず**npx --yes zframes@latest <cmd>**で実行してください。npxは実行ごとに公開済みのCLI（ダッシュボードランタイムを含む）を取得するため、クローン、インストール、更新は不要です。以下で使用するコマンドはinit、providers、catalogue、lint、serveです（簡潔にzframes <cmd>と記しますが、必ずnpx経由で実行してください）。

1. 依頼を分類する — 配信、更新、作成

まず依頼を分類してください。以降のすべての作業と、読むべきリファレンスファイルが決まります。 4つの作業のうち、何かを構築するのは1つだけです。ユーザーがまだ持っていないダッシュボードを本当に作成する場合を除き、ヒアリングやinitは実行しないでください。

• 既存のダッシュボードを配信／開く／起動する — 「ダッシュボードを起動して」「ターミナルを開いて」「配信して」、またはユーザーがすでにダッシュボードを持っている場合の単独の/zframes。ダッシュボードが存在する場合によくある依頼です。initもヒアリングも行わず、カタログやリファレンスファイルも読みません。 zframes listを実行して一覧を確認し、ステップ6に進んで配信します。引数なしのzframes serveはデフォルト（一覧の*が付いたもの）を開き、zframes serve <name>は指定したダッシュボードを開きます。これで完了です。
• 既存のダッシュボードを更新する — 「Xを追加」「ティッカーを入れ替え」「テーマを変更」など。zframes listを実行するか（*がデフォルトを示します）、ユーザーが配信しているdashboard.json、または現在のディレクトリにあるものを探します。まず内容を読んでから、依頼された箇所だけを変更します。フレームの追加、サイズ変更、並べ替えを行う場合は、frames配列を編集する前に、カタログ（ステップ2）と**references/design.md**（デザイン手法と、イベント、グループ、source、通貨などのカード単位のフィールド）を読んでください。その後、lintと配信を行います（ステップ5〜6）。再度initを実行しないでください。既存のフレームが消去されます。
• 新しいダッシュボードを作成する — ユーザーがまだ持っていないものを希望している場合（または既存のものに加えて新規作成を明示的に希望している場合）のみです。名前を付けてinitを実行し（以下を参照）、完全な構築手順を進めます。カタログの概要（ステップ2）、ヒアリング（質問する前に**references/interview.mdを読む**）、デザイン（フレームのJSONを記述する前に**references/design.mdを読む**）、その後にlintと配信（ステップ5〜6）を行います。
• 共有ダッシュボードをフォークする — ユーザーがzframesのエクスプローラーリンク（.../dashboard/<id>または.../dashboard/<id>/dashboard.json）を提示する場合、または「フォーク」プロンプトを貼り付ける場合です。共有ダッシュボードを自分のマシンに保存して、引き続き利用・拡張したいという依頼です。ヒアリングも構築も行いません。references/fork.mdを読んで手順に従います。取得し、ストアに配置し、lintと配信を行ってから、カスタマイズを提案します。

成果物は単一のdashboard.jsonのみです。ひな型を作成するアプリはありません。ランタイムはCLIから提供されます。ダッシュボードはグローバルストア（$XDG_CONFIG_HOME/zframes/dashboards、デフォルトは~/.config/zframes/dashboards）に保存されるため、ユーザーはどこからでもzframesを実行でき、短い名前（main、cryptoなど）で識別される複数のダッシュボードを並べて保持できます。zframes listですべて表示され、*は引数なしのzframes serveで開くダッシュボードを示します。

ダッシュボードを作成するには、名前を付けてストア内でinitを実行します。エンベロープを手作業で記述しないでください。

npx --yes zframes@latest init <name> --title "<dashboard title>" --author "<who>"

crypto のような単独のトークンはストア内の <store>/dashboards/crypto/dashboard.json に保存され、まだデフォルトがない場合は デフォルトになります（そのため、後で単独の zframes serve を実行するとこれが開きます。強制的に設定するには --default を渡します）。 これにより、すでに有効なダッシュボードがそのまま作成されます。package.json をモデルにした固定のエンベロープで、version（semver 文字列）、title、author（ユーザーから名前を受け取った場合は --author を渡します。そうでなければ空欄のままです）、続いて12列の grid（ジオメトリ — columns/rowHeight/gap）、ユニコーンの background、theme のカラー（アクセント用の accentHue/accentSat、暗いカード表面の色合い用の baseHue/baseSat、値上がり／値下がり用の upColor/downColor）、typography（sans/mono/serif の fontFamily、proportional/tabular の numericStyle、テキスト全体のサイズを指定する scale）、カード表面の appearance（radius/borderStrength/surfaceOpacity/density/elevation）、表示用の currency（デフォルトは { code: "USD" }）が含まれます。さらに、空の frames 配列も含まれます。この定型部分やジオメトリを手作業で記述する必要はありません。入力するのは frames だけです（手順4）。この1つのファイルがユーザーの所有物です。参照先の関連ファイル（ローカル画像）はダッシュボード専用の dashboards/<name>/ フォルダー内に置かれるため、各ダッシュボードのアセットは分離された状態に保たれます。init は --force を渡さない限り、既存のファイルを上書きしません。

（ストアではなく通常のファイルを使いたい場合は、パスを渡します — init ./my-dir または init ~/dash.json。また、すべてのコマンドでそのパスを指定できます。/ を含むトークン、または .json サフィックスが付いたトークンは常にパスとして扱われ、単独のトークンは常にストア名として扱われます。）

2. カタログを読む — 生成する前に必ず読む

カタログは2段階で読み込みます — JSON Schema 形式のフレーム約270件を含む完全なダンプは約400 KBあり、全体を読むには大きすぎます。また、その大部分は必要ありません。

フェーズ1 — 閲覧。 何かを選ぶ前に：

npx --yes zframes@latest catalogue --summary > /tmp/zframes-summary.txt

このファイルを最後まで読みます（プレーンテキストで約45 KB）。各フレームが name — description の1行でカテゴリごとにまとめられており、カテゴリの分類体系と、デザイン用語 — 書き込むべき正確な仕様値を含む名前付きテーマプリセット、および projectIds を持つ背景シーン — が記載されています。これが手順4でフレームと見た目を選ぶためのメニューです。

フェーズ2 — 実際に使用するスキーマを取得。 デザイン検討でフレームセットを決めたら、対象のフレームに限って、各フレームの設定スキーマに加えて、設計サイズとリサイズ時の下限（layout：w/h/minW/minH/…）を含む完全なエントリーを取得します。

npx --yes zframes@latest catalogue price-liveline price-chart yield-curve ... > /tmp/zframes-frames.json

次に、ファイルリーダーでファイルを読みます — 標準出力をパイプ経由で読むのではなく、ファイルにリダイレクトしてください。そうすれば、内容が途中で切り捨てられません。フレーム名、設定フィールド、列挙値、サイズはすべてここから取得し、記憶に頼らないでください。カタログは増えていきますが、記憶はそうではありません。未知のフレーム名を指定すると、有効な一覧とともにコマンドが終了コード1で終了します — これは lint と同様に、タイプミスを知らせるものです。

3. ユーザーにヒアリングする — まず references/interview.md を読む

作成の手順では、構築を始める前にユーザーへヒアリングします — ただし、質問する前に必ず references/interview.md を読んでください。ここにはヒアリングの全体的な流れが記載されています。3段階で絞り込み（アセットクラス → カテゴリ → 具体的なティッカー3〜5件。途中で任意のテーマプリセットについても質問します）、アセットクラスごとの選択肢メニュー、および各カテゴリを dex が実際に扱うティッカーに対応付ける xyz シンボルリファレンスが含まれています。ヒアリングではシンボルと（任意で）見た目を選びます。フレームは選びません。ボードは手順4で自分で組み立てます。

4. ダッシュボードを設計する — まず references/design.md を読んでください

init でスキャフォールディングされたファイル（更新の場合は既存のファイル）の frames 配列を埋めます。これは設計作業であり、単なるデータの羅列ではありません。references/design.md は設計手法を説明したものです。フレーム JSON を書く前に読んでください。 ここでは、3 つのパス（4a テーマプリセットを 1 つ適用する、4b 必須の骨格をもとにフレームセットを整え、トピックに必要な数のカードを用意し、それぞれを 1 つのアイデアに絞った見出し付きゾーンに配置する、4c レイアウトを構成する — カタログにあるサイズ、12 個に収まる行、見出し付きゾーン、階層、小さなアセットロゴのタイルを装飾や行の余白埋めとして使う）に加え、記述時に必要となるカード単位のフィールド（イベント注釈、group クラスター、source を使ってフレームを 2 つ目の会場に固定する方法、ボード単位／カード単位の表示通貨）について説明しています。

5. リント — フィードバックループ

npx --yes zframes@latest lint <name>   # the store name (or a path to a dashboard.json)

問題が報告された場合は、JSON を修正して、問題がなくなるまでリントを繰り返します。エラーメッセージにはフレームインスタンス名と該当するフィールドが明示されます。不明なフレーム名を指定すると、有効な名前の一覧が返されます。一覧を使ってください。リントでは設計上の最低基準も検証されます。layout の最小値を下回る位置にフレームを配置した場合、カードが重複した場合、グループの子要素がグループ自身の columns／rows の範囲を超えた場合、またはグループをグループ内に配置した場合は、該当する数値とともにエラーになります。

レンダラーで発生するエラー（どのプロバイダーも対応していない機能を持つフレーム）は、実行中のダッシュボードにエラーカードとして表示されます。これらも同様に対処してください。

6. 引き渡し — サーバーを起動してから開く

ダッシュボードを配信し、ユーザーのブラウザーで開いてください。リンクを表示するだけでは引き渡しになりません。serve はブロックするため、バックグラウンドで実行し（バックグラウンドシェルやマルチプレクサーのウィンドウなど、利用できる方法で構いません）、ポートへの応答を待ってから、URL を開きます。

npx --yes zframes@latest serve <name>   # background this; the store name (or a path)
until curl -sf http://localhost:37263 >/dev/null; do sleep 1; done
open http://localhost:37263             # macOS · xdg-open on Linux · start on Windows

URL は必ず http://localhost:37263 として記述して開いてください。IP アドレスだけを使わないでください。CLI が表示するのも、ユーザーがクリックすることを想定しているのも、この URL です。何も考えずにスリープするのではなく、ポートをポーリングしてください。サーバーがバインドする前に開くと、ブラウザーに接続エラーが表示されます。--port <n> を指定した場合は、そのポートを開いてください。

ライブデータは一度だけインストールします。最初からあるものとは考えないでください。 通常のインストールにはデータプロバイダーが含まれていません。ダッシュボードにはシミュレーション用のデモ数値が表示され、ヘッダーに「demo data」バッジが付き、起動時に serve がその旨を知らせます。マシンで初めて serve を実行する前、または serve がデモ通知を表示したときやヘッダーにバッジが表示されたときは、無料のキー不要のフリートをインストールしてください。

npx --yes zframes@latest providers add keyless   # one-time; prints what it contacts + where the terms live

表示されるメッセージは重要です。ユーザーが同意するかどうかを判断する画面なので、抑制せずに表示してください。インストール済みの項目は zframes providers で確認できます。（このコマンドがない古い公開済み CLI では、常にライブデータがストリーミングされます。providers が不明なコマンドとしてエラーになった場合は、そのまま serve を実行してください。）

serve は、ダッシュボードを指定したビルド済みランタイムをホストし、フリートのインストール後はキー不要のライブデータをストリーミングします。名前を指定しない zframes serve はデフォルトのストアダッシュボードを開きます。ストアに複数のダッシュボードがある場合、ヘッダーのタイトルはダッシュボード選択メニューになり、ユーザーが開いて別のダッシュボードを選ぶと、再起動なしでページが再読み込みされます。ユーザーはブラウザーでフレームのドラッグ、サイズ変更、追加、設定ができます。保存すると、変更内容は dashboard.json に直接書き戻されます。ファイルへの編集（あなたが行ったものでもユーザーが行ったものでも）は、再読み込み時に反映されるため、その後の「ダッシュボードに X を追加して」という依頼も、ファイルを編集してページを再読み込みするだけで対応できます。37263 が使用中の場合は --port <n> を指定してください。

単に有効なだけでなく、デザインどおりに表示されることを確認してください。 Lint で JSON の正しさは確認できますが、ピクセルまでは確認できません。新しく作成または再構成したダッシュボードを配信した後、ブラウザーツールがあれば http://localhost:37263 を開き、次の点を一度確認してください。エラーカード（「Invalid configuration」、「Unknown frame」、「missing-capability」）、空のままのカード、隙間のある行、カード内部の表示切れです。問題があれば仕様を修正して再読み込みします。ヘッダーの**「demo data」ピルは不具合ではありません**。データプロバイダーがインストールされていないという意味です。zframes providers add keyless を実行してから、serve を再起動してください。（カードが空かどうか判断する前に、ライブデータが落ち着くまで数秒待ってください。グラフの描画アニメーションは不具合ではありません。）ブラウザーツールがない場合は、何を確認すればよいかをユーザーに具体的に伝え、報告された問題を修正してください。通常の serve や、1 項目だけの更新ではこの確認を省略できます。その場合は差分が証拠になります。

厳守事項

• 見るだけなら、そのまま表示します。 ダッシュボードがすでに存在し、ユーザーが起動／開く／表示するように指示した場合（または /zframes だけを送った場合）は、表示します（ステップ 1 → ステップ 6）。ヒアリングも init も再構築も不要です。新しいダッシュボードを作成するとき、または既存のものを変更するときに限り、構築または再ヒアリングを行います。 表示するとは、serve をバックグラウンドで実行し、ブラウザーで http://localhost:37263 を開くことです。 依頼は「ダッシュボードを開いて」なので、リンクを表示するだけでは完了ではありません。
• ヒアリングで選ぶのはティッカー（および、多くても見た目のテーマ）だけで、フレームは選びません。 オンボーディングの流れ（資産クラス → カテゴリー → 具体的なティッカー）と、任意のテーマプリセットに関する質問は、シンボルと雰囲気を選ぶためだけのものです。ボードの構成はこちらで行います。含めるフレームやウィジェットを尋ねたり、選択肢としてフレーム名を提示したり、読み上げたりしてはいけません。
• 選定と構成――この2つが設計上の不変条件です。 カード数に上限はありませんが、すべてのカードは1つのアイデアを表す見出し付きゾーンに配置し、各ゾーンだけでも内容が理解できるようにします。サイズは各フレームのカタログにある layout を使用し、minW／minH から maxW／maxH の範囲を超えてはいけません。各行は12列すべてにカードを配置し、テーマプリセットは1つだけ、そのまま適用します。ゾーン分けのないカタログの羅列も、内容が乏しいだけの空っぽな構成も失敗です。
• 成果物は dashboard.json だけです。React、CSS、新しいフレームは使いません。 存在しないフレームを求められた場合は、その旨を伝え、利用できるものを一覧表示します。
• データソースは無料のものに限ります。API キー不要のソースが29個あります。Hyperliquid（暗号資産＋HIP-3 株式パーペチュアル）、Nasdaq、CoinGecko、DeFiLlama、Deribit、Cboe、mempool.space、米国財務省、NY Fed、BLS、SEC EDGAR、FRED、LBMA の貴金属などです。すべてのプロバイダーは zframes providers add keyless（ステップ 6）で追加します。設定が必要な API キーはありません。決して API キーを求めてはいけません。
• セッションごとにカタログを読み直してください。記憶しているフレーム名を信用してはいけません。