标准相机事件

共同平面/球面相机支持 MapLibre 风格的即时移动、缩放、旋转与倾角生命周期事件。使用方可据此刷新比例尺、缩放按钮、指北针及覆盖物；绘制与界面由使用方自行实现。原有 sqs.viewchange 保留兼容。

// @gis-api 0.5-session
// @permissions ["project.read", "map.write"]
import {map} from 'sqsmap';
export const sessionMode = 'persistent';
map.on('move', event => {
  const {camera, projection, viewport} = event.cameraState;
  // camera: WGS84 center, zoom, bearing, padding; viewport uses CSS pixels.
  // Send these values to your own UI through your host integration.
});
map.jumpTo({center:[110,20],zoom:4,bearing:30});
await map.sqs.flush({render:true});
export default {ready:true};

event.cameraState 与 await map.sqs.cameraState() 使用同一结构，中心为 [lng,lat]，缩放采用 512 像素约定。快照深度冻结，不读取未来状态；连续修改分别保留已应用结果，不用最后一帧覆盖历史。target 是当前脚本地图对象，身份和递增安全整数序号沿宿主事件域；取消监听、停止、重置后的旧事件不会转发到新会话。

无变化和失败命令不发送 move。事件表示相机已应用，绘制可以尚未完成；需要显示新帧时仍调用 await map.sqs.flush({render:true})。命令确认不等待事件回调完成；应在修改前建立 map.once('move')，显式等待该 Promise。不要用 move 推断网络图源已就绪、动画结束或 idle。

独立 SDK 使用 view.on('move', event => ...) 或 view.onCameraMove(listener)，返回取消订阅函数。地图主线程和严格渲染 Worker 使用同一消息；SDK 每类最多 32 个监听，128 项待发送相机通知修改前预留，观察者异常不会把已应用修改改判失败。

桌面共同相机和外部二维手势、原生 C 轮询、原生持续 QuickJS、浏览器脚本都接通。原生一次性入口当前明确拒绝监听，改用持续入口。球面倾角事件见地球仪 API；非共同 GIS 坐标系和移动宿主仍单独验收。球面动画事件已接通，完整渲染/空闲事件继续交付，当前不宣称完整 MapLibre Evented 兼容。

完整共同脚本 · 网页宿主 · 命令与生命周期。官网分发需部署，本机使用匹配预览地址。

即时命令的开始与结束

共同支持 movestart/move/moveend、zoomstart/zoom/zoomend、rotatestart/rotate/rotateend。单次相机命令的顺序固定如下，仅发送发生变化的通道：

movestart → zoomstart? → rotatestart? → move → zoom? → rotate?
          → zoomend? → rotateend? → moveend

start 的 event.cameraState 是这次更新前的权威快照，其余为更新后的权威快照，都深度冻结。连续命令各自保留完整历史，不用之后的状态覆盖早先事件。无变化、失败和只读调用不产生生命周期通知。中心、边距、视口或投影的有效变化也产生移动周期，只有实际 zoom/bearing 变化才产生相应通道。

异步宿主的 start 回调不是同步修改前钩子：回调中另行查询相机可能已看到后续更新，应使用事件快照。当前每个即时命令自成周期；桌面外部手势按每帧观察到的变化通知，不能把它理解成整个鼠标拖动/惯性/动画的开始和结束。moveend 表示即时变更的通知周期结束，不保证网络加载、渲染、动画完成或idle。

// @gis-api 0.5-session
// @permissions ["project.read", "map.write"]
import {map} from 'sqsmap';
if (!map.sqs.events().includes('moveend')) throw Error('当前宿主尚未接通相机生命周期');
const ended = map.once('moveend');
map.jumpTo({center:[110,20],zoom:4,bearing:30});
await map.sqs.flush({render:true});
const event = await ended;
export default {camera:event.cameraState};

独立 SDK 使用 view.on('zoomend',handler) 等，或 view.onCameraLifecycle((type,event)=>{}) 一次订阅九种事件，返回幂等取消函数。监听预算为每个SDK事件32个、脚本会话共32个；SDK按实际通知数量占用128项队列，写入前保守预留最多9项。原生公共事件队列最多128项，提前预留包含兼容通知的最多10项；C宿主须持续轮询。观察者错误与成功修改分离，订阅溢出明确报告，不能静默丢失离散事件。

浏览器 capabilities.cameraLifecycle 与实际辅助函数识别支持，C先检查 SQSM_MAP_CAMERA_LIFECYCLE（512）。共同脚本查询 map.sqs.events()；旧宿主和原生一次性入口不承诺这些监听。UI移除、脚本停止和宿主重置必须取消订阅，旧域事件不进入新会话。

完整共同生命周期脚本 · 完整 C 示例 · 自定义工具。

原生持续入口和网页运行器在让等待命令的脚本继续之前，先送达该命令已排队的事件信封；初始化完成后注册的监听不会收到初始化前的旧事件。它们不等待异步回调完成，回调可以继续请求地图。原生每次推进最多一个宿主请求，max_events 控制单次事件数量；小批次也保持顺序。

球面增加 pitchstart/pitch/pitchend，共12类相机事件；SDK修改前保守预留13条槽位。原生独立订阅可选择1–64类事件，仍保留订阅个数、事件条数和字节预算，32个用户监听的限制不变。

独立SDK的规范图源/图层名称、兼容别名和回调策略见事件名称。