canvas.frame event

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

Event payload

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

timeMs 是相对、非递减并按平台规则粗化的时间。sequence 用于识别合并或跳过的提示。

Examples

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

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

Delivery rules

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

See also

canvas.draw()、canvas.present()