building-html-canvases

构建 HTML 画布

有些画布是文档或图形程序，而非应用：书面报告、图表、生成艺术作品、WebGL 场景。对于这些内容，语义化 HTML、CSS 和直接使用浏览器 API 才是合适的工具——不要硬把 Quill 组件或 React 状态用到静态页面上。

当前运行时要求的包装器

每个画布都将 src/canvas.tsx 作为已挂载的 React 入口组件（默认导出，无属性）。让 React 层保持轻量，并在其中使用 HTML/CSS/浏览器 API 构建体验：

• 文档使用 JSX 编写，本质上是语义化 HTML——<article>、标题、列表、表格、图示——并用 <style> 块设置排版和布局。撰写真实、具体的文案。
• 绘图/WebGL 程序渲染一个 <canvas> 元素，并通过 ref 在 useEffect 中以命令式方式驱动它：获取 2D/WebGL 上下文，并在那里运行设置和渲染循环。
• 在 effect 的 return 函数中清理：取消 requestAnimationFrame 循环、移除监听器并释放上下文，以免主题切换和重新挂载造成泄漏或重复运行。
• 可以混合不同层级：以静态页面为主的内容可以挂载一个交互式小组件，数据面板也可以将图表的 <canvas> 交给命令式代码处理，同时由 React 管理界面框架。

导入白名单仍然适用（react、react-dom、@posthog/quill、recharts、lucide-react、dayjs）——浏览器全局对象（document、CanvasRenderingContext2D、WebGLRenderingContext、requestAnimationFrame、IntersectionObserver、Web Audio 等）无需导入。Three.js 和其他 npm 图形库目前还无法加载；在构建管线支持依赖项准入之前，请直接使用原始 WebGL 或 2D canvas 编写。

不使用 Quill 的样式和主题

• 将最外层 JSX/HTML 元素设置为与 iframe 视口同样大小，使用 min-h-screen 或 min-height: 100vh，使其填满视口，并在内容需要时向下延伸。 不要在此处使用 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。
• 对于 canvas/WebGL 绘图颜色，请在运行时读取解析后的令牌（getComputedStyle(document.documentElement).getPropertyValue("--primary")）或自己的 CSS 变量；如果场景会长期运行，还应在主题变化时重新读取。

仍然适用的规则

• PostHog 数据只能通过 ph 桥接层获取（参见 querying-canvas-data），包括用于交互分析的 ph.capture。其他请求以及外部样式、图片、字体、媒体或框架，都需要在 capabilities.network.origins 中指定对应的公开 HTTPS 来源，并且只有发布后才能生效。远程脚本和动态导入仍然会被阻止。
• 声明 PostHog 数据的文档必须确保每个数字都可验证：由洞察支持的数字需通过 ph.openExternal 链接到已保存的洞察（从点击中获取 generate-app-url MCP 工具返回的 URL）；临时 ph.query 得出的数字需在相邻的 <details> 元素中披露实际运行的确切查询——参见 querying-canvas-data 中的“可验证性”。
• 外部链接必须通过 ph.openExternal(url) 打开（仅限 posthog.com 来源），并由用户交互触发。
• 按照 validating-and-publishing-canvases 中的说明，通过画布工具进行验证和发布。