building-html-canvases

HTML キャンバスの構築

キャンバスには、アプリケーションではなく、文書やグラフィックプログラムにあたるものもあります。たとえば、レポート、図、ジェネレーティブアート、WebGL シーンなどです。このような場合は、セマンティック HTML、CSS、ブラウザー API を直接使うのが適切です。静的なページに Quill コンポーネントや React の状態を無理に持ち込まないでください。

現在のランタイムで必要なラッパー

すべてのキャンバスでは、マウントされる React エントリーコンポーネントとして src/canvas.tsx を維持してください（デフォルトエクスポート、props なし）。React レイヤーは薄いシェルに保ち、その内側で HTML/CSS/ブラウザー API を使ってエクスペリエンスを構築します。

• ドキュメントは、実質的にセマンティック HTML となる JSX（<article>、見出し、リスト、表、図など）と、タイポグラフィやレイアウト用の <style> ブロックで構成します。具体的で実用的な文章を書いてください。
• 描画／WebGL プログラムでは、<canvas> 要素をレンダリングし、ref 経由で useEffect から命令的に操作します。そこで 2D/WebGL コンテキストを取得し、セットアップとレンダリングループを実行してください。
• effect の戻り値でクリーンアップします。requestAnimationFrame のループをキャンセルし、リスナーを削除し、コンテキストを解放して、テーマの切り替えや再マウントによるリークや二重実行を防いでください。
• ティアを組み合わせても問題ありません。ほぼ静的なページにインタラクティブな領域を 1 つ配置したり、データボードでチャートの <canvas> を命令的なコードに渡しつつ、React で周囲の UI を管理したりできます。

インポートの許可リストは引き続き適用されます（react、react-dom、@posthog/quill、recharts、lucide-react、dayjs）。ブラウザーのグローバル（document、CanvasRenderingContext2D、WebGLRenderingContext、requestAnimationFrame、IntersectionObserver、Web Audio など）にはインポートは不要です。Three.js やその他の npm グラフィックスライブラリはまだ読み込めません。ビルドパイプラインで依存関係の許可機能が提供されるまでは、raw WebGL または 2D canvas を使ってください。

Quill を使わないスタイル設定とテーマ設定

• 最も外側の JSX/HTML 要素には min-h-screen または min-height: 100vh を設定し、iframe のビューポートに合わせてください。これにより、ビューポート全体を埋め、コンテンツに応じてその先まで伸びます。 ここでは h-screen や height: 100vh を使わないでください。ビューポートの高さを固定すると、flex 列の高さに上限が設けられるため、背の高い子要素が縮んでスクロールせずに切れてしまいます。 そのルート要素に h-full や height: 100% も使わないでください。公開されたキャンバスのアーティファクトシェルでは、html、body、#root 要素に明示的な高さが設定されていないため、パーセント指定の高さはコンテンツの高さに縮みます。 min-height のルート要素は確定した高さではないため、子孫要素のパーセント指定の高さも縮みます。子要素をボックスいっぱいに広げる必要がある場合は、中間のラッパーに明示的な高さを設定してください。
• Tailwind のユーティリティと <style> ブロックを使います（キーフレームや複雑なセレクターも使用できます）。
• ユーザーの PostHog テーマが変更されると、ホストはドキュメントのルートに .dark クラスを切り替えます。:root { … } で CSS 変数として色を定義し、html.dark { … } で上書きするか、テーマトークンのユーティリティ（bg-background、text-foreground、border-border）を使ってください。ライトテーマ専用のハードコード色は使わないでください。
• 独自の CSS 変数にはプレフィックスを付けてください（--doc-bg、--doc-muted）。プラットフォームのトークン名は決して再利用しないでください。バンドルされた Quill スタイルシートは、すべての要素に --background、--border、--card、--chrome、--input、--muted、--primary、--fill-* を設定するため、これらの名前を使った :root や html.dark の値はどの要素にも適用されません。独自の --muted でテキストに色を付けたページでは、淡いページに淡い文字が表示され、読みにくくなります。このような宣言は検証時に platform_token_redeclared として拒否されます。
• キャンバス／WebGL の描画色は、実行時に解決済みのトークン（getComputedStyle(document.documentElement).getPropertyValue("--primary")）または独自の CSS 変数から取得してください。シーンが長時間動作する場合は、テーマ変更時に値を再取得してください。

引き続き適用されるルール

• PostHog のデータは ph ブリッジ経由でのみ取得します（querying-canvas-data を参照）。操作分析用の ph.capture もこれに含まれます。その他のリクエストや外部のスタイル、画像、フォント、メディア、フレームを使用するには、それぞれの公開 HTTPS オリジンを capabilities.network.origins に指定する必要があり、公開後にのみ動作します。リモートスクリプトと動的インポートは引き続きブロックされます。
• PostHog の数値を記載するドキュメントでは、数値をそれぞれ検証可能にする必要があります。インサイトに基づく数値には、保存済みインサイトへのリンクを付けます。このリンクは、クリック操作から ph.openExternal を使って開きます（URL は generate-app-url MCP ツールから取得します）。アドホックな ph.query の数値には、実行したクエリの正確な内容を、主張の横にある <details> 要素内に記載します。詳しくは querying-canvas-data の「検証可能性」を参照してください。
• 外部リンクは、ユーザーの操作から ph.openExternal(url) 経由で開きます（posthog.com のオリジンのみ）。
• validating-and-publishing-canvases に記載されているとおり、キャンバスツールを使って検証し、公開してください。