Construire des canvases HTML

Certains canvases sont des documents ou des programmes graphiques, pas des applications : un rapport écrit, un diagramme, une œuvre d'art générative, une scène WebGL. Pour ceux-ci, le HTML sémantique, le CSS et les API du navigateur directes sont les bons outils — ne forcez pas les composants Quill ou l'état React sur une page statique.

Le wrapper que le runtime actuel nécessite

Chaque canvas conserve src/canvas.tsx comme son composant React d'entrée monté (export par défaut, sans props). Gardez la couche React comme une fine enveloppe et écrivez l'expérience en HTML/CSS/API du navigateur à l'intérieur :

• Un document est du JSX qui est effectivement du HTML sémantique — <article>, titres, listes, tableaux, figures — avec un bloc <style> pour la typographie et la mise en page. Écrivez du contenu vrai et spécifique.
• Un programme de dessin/WebGL rend un élément <canvas> et le pilote de manière impérative depuis un useEffect via une ref : obtenez le contexte 2D/WebGL, exécutez la boucle de configuration et de rendu là-bas.
• Nettoyez dans le return de l'effet : annulez les boucles requestAnimationFrame, supprimez les listeners et libérez les contextes, pour que les changements de thème et les remontages ne fuient pas ou ne s'exécutent pas en double.
• Mélanger les niveaux est acceptable : une page surtout statique peut monter une île interactive, et un tableau de données peut confier le <canvas> d'un graphique au code impératif tandis que React possède la chrome.

La liste d'autorisation d'importation s'applique toujours (react, react-dom, @posthog/quill, recharts, lucide-react, dayjs) — les globals du navigateur (document, CanvasRenderingContext2D, WebGLRenderingContext, requestAnimationFrame, IntersectionObserver, Web Audio, etc.) n'ont besoin d'aucune importation. Three.js et les autres bibliothèques graphiques npm ne sont pas encore chargeables ; écrivez contre le WebGL brut ou le canvas 2D jusqu'à ce que l'admission des dépendances du pipeline de build soit livrée.

Style et thème sans Quill

• Dimensionnez l'élément JSX/HTML le plus externe à la viewport de l'iframe avec h-screen ou height: 100vh. N'utilisez pas h-full ou height: 100% sur cette racine : la shell d'artefact d'un canvas publié ne donne à ses éléments html, body et #root aucune hauteur explicite, donc la hauteur en pourcentage s'effondre à la hauteur du contenu. Les descendants peuvent utiliser la hauteur en pourcentage après que l'élément le plus externe établisse la hauteur de la viewport.
• Utilisez les utilitaires Tailwind et/ou un bloc <style> (les keyframes et les sélecteurs complexes conviennent).
• L'hôte bascule une classe .dark sur la racine du document lorsque le thème PostHog de l'utilisateur change. Définissez vos couleurs en tant que variables CSS sous :root { … } avec les remplacements sous html.dark { … }, ou utilisez les utilitaires de token de thème (bg-background, text-foreground, border-border) — jamais une couleur codée en dur en mode clair uniquement.
• Pour les couleurs de dessin canvas/WebGL, lisez le token résolu à l'exécution (getComputedStyle(document.documentElement).getPropertyValue("--primary")) ou vos propres variables CSS, et relisez au changement de thème si la scène est longue.

Les règles qui s'appliquent toujours

• Les données PostHog ne proviennent que du bridge ph (voir querying-canvas-data), y compris ph.capture pour l'analytique d'interaction. Les autres requêtes et styles externes, images, polices, médias ou frames nécessitent leurs origines HTTPS publiques exactes dans capabilities.network.origins et ne fonctionnent qu'après publication. Les scripts distants et les importations dynamiques restent bloqués.
• Un document qui énonce des chiffres PostHog doit rendre chacun vérifiable : un chiffre adossé à un insight relie son insight sauvegardé via ph.openExternal (URL de l'outil MCP generate-app-url, à partir d'un clic) ; un chiffre ph.query ad-hoc divulgue la requête exacte qui a été exécutée dans un élément <details> à côté de l'affirmation — voir « Verifiability » dans querying-canvas-data.
• Les liens externes vont via ph.openExternal(url) (origines posthog.com uniquement), à partir d'une interaction utilisateur.
• Validez et publiez via les outils canvas comme décrit dans validating-and-publishing-canvases.