canvas.frame event

当应用可见且绘图面可以接收新内容时，宿主发送 canvas.frame。它是调度提示，不是高精度计时器或逐帧显示承诺。

Event payload

{ canvasId: string, tick: u64, timeMs: f64 }

timeMs 从应用会话启动的 0 开始、非递减并固定向下量化到 1 ms。首个 tick 为 0，合并造成的间隙可观察；它与 canvas.present() 的 guest sequence 无关。

Examples

host.events.on('canvas.frame', async ({ canvasId, tick }) => {
  if (canvasId !== 'main') return;
  const pixels = renderer.render(tick);
  await presentLatestFrame(pixels);
});

回调执行时间过长时，宿主可以合并后续事件；应用应渲染最新状态，不补算每个漏掉的视觉帧。

Delivery rules

• 应用隐藏或暂停时可以停止发送。
• 同一绘图面的 tick 单调递增。
• 事件不携带屏幕刷新率、绝对时间或设备标识。
• 事件队列有界；帧提示允许合并。

Requirements

• 事件声明：canvas.frame
• 来源：passive；只在对应本应用绘图面可见时送达
• 信任档位：继承 canvas 的 green

See also

canvas.draw()、canvas.present()