iPolloWork 视频组件开发规范

交付的是能放进视频、通过共用表单调整、跟随项目主题、可由 AI 加工的组件。不要为一个组件另做编辑器、参数面板、渲染器或宿主插件。

1. 开始前：以当前代码契约为准

在 iPolloWork 仓库根目录阅读 AGENTS.md 和维护性规范。先找同类组件，再选择扩展还是新增。以下路径均相对仓库根目录：

• vendor/hyperframes/registry/blocks/world-map/：地图、主题继承、结构化数据的参考。
• vendor/hyperframes/registry/blocks/media-hero/：可编辑内容与动画配方的参考。
• vendor/hyperframes/packages/core/src/registry/types.ts：组件分类及 manifest 契约。
• vendor/hyperframes/packages/core/src/registry/componentData.ts：共用数据结构及解析规则。
• vendor/hyperframes/packages/core/schemas/registry-item.json、packages/types/src/hyperframes.ts：注册项和宿主校验契约。
• vendor/hyperframes/packages/studio/src/utils/blockInstaller.ts：真实安装、主题与变量接入方式。

不要复制这些 schema 或创建另一套数据协议。规范与代码不一致时，先核对当前消费者，不用旧示例猜测接口。

2. 最小交付结构

通常只需在 vendor/hyperframes/registry/blocks/<slug>/ 放置：

registry-item.json       # 元信息、变量、分类、文件和能力声明
<slug>.html              # 画面与动画

确有需要再加本地图片、字体、数据或预览文件；安装所需文件必须在 files 中声明，路径保持包内相对路径。注册到现有 vendor/hyperframes/registry/registry.json，不另建组件目录服务。

产品里统称“组件”，但底层类型要准确：有独立画布和时长的地图、排行榜等通常是 hyperframes:block；注入已有画面的片段才是 hyperframes:component。完整项目模板属于另一种交付，不混用。

3. 变量：少而有用，表单共用

• 在 manifest 的 variables 声明稳定的 id、可理解的 label、类型及默认值，与 HTML 的 data-composition-variables 保持一致。
• 沿用现有 string / number / color / boolean / enum 类型；数字给合理范围，枚举给选项，长文本给长度约束。不要擅自增加对象类型。
• 只暴露内容、数据、高亮、必要的布局等用户决策；不要把每个 CSS 数值都变成参数。颜色默认来自主题，不能靠用户逐项配色才能使用。
• update: live 仅用于能即时更新的参数；改变结构或动画时按现有机制使用 rebuild / reload，声明必须与实际行为一致。
• 接入现有变量更新机制，更新后 DOM 和动画都应反映新值，并保持宿主当前播放位置。不得只更改文本而让时间线仍指向旧元素。
• 使用共用变量表单和数据表格，不给单个组件新写一套面板。motionCueTimes、motionStyle 等系统控制字段不当作普通用户参数。

4. 数据：给 AI 结构，给用户表格

地图、路线、图表、排行榜等数据组件使用 visualComponent.data，声明列、语义、行标识、行数限制和绑定。沿用已有 category-value / region-value / point-value / route-value / series-value，选择真正匹配数据的类型。

AI 面向的标准数据是：

{
  "version": 1,
  "kind": "region-value",
  "rows": [
    { "region": "China", "value": 96 },
    { "region": "Japan", "value": 77 }
  ]
}