gis-view-webgl2 0.1.7 → 0.1.9

package/docs/demos/gis-view-demo/GisViewDemoCardHeader.vue

@@ -21,7 +21,7 @@ const {
 					<p>Ctrl + 点击线路或通道加点之后，拐点不会分散写进每条回线，而是归到一个新的拐点集合里：一个分组一组（没拆分过就是一条通道一组），组里有 member_line_ids（哪些回线共用）与 group_route（两端 + 拐点），结构对齐 test.json 的 parallel_groups；「导出拐点集合」按钮会把这份集合复制到剪贴板，可以直接回写业务数据。</p>
 					<p>这一轮补上三块：① 通道可以分组了——默认一条通道一组，「拆分分组」按每组几条回线把它拆开（第一组沿用当前拐点、新分组的线路不带拐点），「合并分组」把其余分组并进第一组（被并入的线路跟随第一组的拐点，第一组没有拐点就一条都不带），加点 / 拖点只作用于同一分组，分组声明写回 channels[].groups；② 鹰眼图也支持规则——「规则沿用主图」只搬颜色与层级（主图的像素尺寸不会搬过来），「按电压单独配色」给小图自己配一份（半径缩到 1 ~ 2.6px、高电压用方块、zIndex 沿用电压分档），「分层」控制分层叠画、层级下拉只画某几层，「放大节点 / 放大线路」让节点与线路跟着小图自身的倍数放大（滚轮或 － / ＋ 都算）；③ 定向更新——updatePoint / updateLine / updateChannel 改一个节点、线路或通道就重渲染相关的视图，只重解析受影响的那一小片，其余要素与缓存一个字节都不动，鹰眼图与标签覆盖层跟着重画。</p>
 					<p>热力图这一轮把节点那一层补上了：合成数据的节点与线路都按一张「热区场」随机生成 max_loading_rate（在数据范围里撒 4 ~ 6 个热区，节点取自己坐标处的场值、线路取两端中点处的场值 —— 画出来是几团往外化开的色斑，而不是均匀噪点），作用对象因此可以切「节点 + 线路 + 通道」/「只按节点上色」/「线路 + 通道回线」/「只按通道自己的值」四档；面板上的「重新随机一份热力数据」能在任意数据集上现生成一份（换种子、按当前节点范围重建场，只改字段值，坐标与拓扑一动不动），真实数据 new.json 的节点本来没有这一列、线路那一列又恒为 1.5，点一下就能立刻看到热力。作用对象带上节点时图标不再跟着换：图标符号写了 tint（逐实例着色），填充按白色烘焙、由热力色逐实例染上，描边写 currentStrokeColor 不参与染色 —— 形状与描边还是那张图标，只是填充跟着值走；贴图缓存键里因此不再有逐点的热力色，900 节点时绘制调用仍然在 36 上下（以前一个节点一张贴图时会涨到约 1500，10 万级直接把主线程烤住），想看「完全不参与热力图」的效果就把节点从作用对象里去掉 —— 图标本身不会变成内置圆 / 方块。</p>
-					<p>这一轮补上六件事：① <b>节点复制</b>——按住 Alt（面板上可以改成别的键）点一个节点，复制品立刻压在源节点上跟着鼠标走，松开左键（不再看 Alt 什么时候松）或再点一下落地；也可以点面板上的「先点按钮再选节点」再点一个节点（复制品落在它旁边），或者选中节点按 Ctrl+C、把鼠标移到目标位置按 Ctrl+V。复制全程走 <b>onPointCopy</b>：start / move / commit / end / cancel（复制到剪贴板另发一条 clipboard），落地前的 commit 阶段可以 payload.cancel() 撤掉、payload.update() / setItem() 改数据，id 与整份数据由 copy.createId / copy.createItem 定；落地之后的 end 阶段还能 payload.revert() 整份回滚（面板上「复制后模拟接口失败」那个勾就是它）。② <b>节点合并</b>——把一个节点拖到另一个节点上（碰撞按两个节点画在屏幕上的半径之和 + merge.distance 判，整组拖动不参与），<b>组件不弹任何对话框</b>：pending 停在原地等使用方裁决，面板上的「合并确认」三档分别是「停住（由这个自写弹层来确认）」/ false 直接合并 / 函数返回 Promise（先调接口再决定，resolve(false) 取消）；确认会先推进到 confirm 阶段并把合并结果给你（可以改，也可以在这一步因为「接口失败」整份撤掉），确认之后来源节点的数据并进目标（缺省 { ...来源, ...目标 }，可用 merge.createItem 整份接管）、<b>尺寸取双方最大、图标优先目标</b>、绑在它上面的线路改绑、合并出来的自环与零长线删掉；两端因此撞成同一条的通道按 merge.channelGroups 处理（各自保留分组 / 合成一个分组，自环的整条删），读数里会带上改端点的通道数与并掉的通道数。取消或接口失败则把拖动的节点与跟随它的线路还原回原位，并补发一条拖拽结束。③ <b>所有快捷键都能改</b>——options.shortcuts 按动作配（框选 / 多选 / 加点 / 复制 / 复制到剪贴板 / 粘贴 / 取消 / 删除 / 适应视图），写法是纯修饰键（ctrl / meta / shift / alt / mod）、组合键（ctrl+c）、单键（escape / 0）或数组，写 false 表示不绑定；面板「视图 · 交互」里那四个下拉就是改框选 / 多选 / 加点 / 复制的修饰键——比如把框选改成 Shift，之后 Shift + 拖动才出选框，按住 Shift 时连光标变体也跟着走。④ <b>选中抬层</b>——selectionOnTop（缺省开）把选中的节点、拖动中的整组、待确认合并的目标节点与选中线路所在的整条通道画在所有要素之上：选中了就一定看得见，与 zIndex 无关；关掉就完全按 zIndex 与数据顺序画。⑤ <b>删除（Delete）</b>——选中拐点 / 线路 / 节点之后按 Delete（或面板上的「删除选中」）先出一份删除载荷：要删什么、连带什么、能按哪些范围删。<b>组件不弹界面</b>：pending 停在原地等 <b>confirm(scope)</b> / cancel()，Esc 也能取消；范围三档是「只删选中的线路」/「删除整个分组」/「删除整条通道」（后两档只在删的是通道回线、且这条通道分过组时才有），选中的拐点与节点一律一起删 —— <b>删节点会连挂在它身上的线路、以及拿它当端点的整条通道一起删</b>，载荷里的 lineCount / channelCount 就是这份连带读数；确认之后整段合成一条历史，撤销一步全回来；开关是 features.remove，快捷键照样走 shortcuts.remove（可以单独配成 shift+delete 之类）。⑥ <b>通道选中模式</b>——channelSelectMode 决定点中一条通道回线时选中什么：line（缺省，只选这一条）/ group（连它所在分组一起）/ channel（整条通道一起）；在 group / channel 下 Ctrl + 点击是<b>整批取反</b>，通道以外的线路永远只选它自己。它只影响「下一次点选怎么摊开」，切换走 updateOptions，场景一个字节都不用重排。面板「视图 · 复制合并」里那两项就是它们。</p>
+					<p>这一轮补上六件事：① <b>节点复制</b>——按住 Alt（面板上可以改成别的键）点一个节点，复制品立刻压在源节点上跟着鼠标走，松开左键（不再看 Alt 什么时候松）或再点一下落地；也可以点面板上的「先点按钮再选节点」再点一个节点（复制品落在它旁边），或者选中节点按 Ctrl+C、把鼠标移到目标位置按 Ctrl+V。复制全程走 <b>onPointCopy</b>：start / move / commit / end / cancel（复制到剪贴板另发一条 clipboard），落地前的 commit 阶段可以 payload.cancel() 撤掉、payload.update() 改数据，id 与整份数据由 copy.createId / copy.createItem 定；落地之后的 end 阶段还能 payload.revert() 整份回滚（面板上「复制后模拟接口失败」那个勾就是它）。② <b>节点合并</b>——把一个节点拖到另一个节点上（碰撞按两个节点画在屏幕上的半径之和 + merge.distance 判，整组拖动不参与），<b>组件不弹任何对话框</b>：pending 停在原地等使用方裁决，面板上的「合并确认」三档分别是「停住（由这个自写弹层来确认）」/ false 直接合并 / 函数返回 Promise（先调接口再决定，resolve(false) 取消）；确认会先推进到 confirm 阶段并把合并结果给你（可以改，也可以在这一步因为「接口失败」整份撤掉），确认之后来源节点的数据并进目标（缺省 { ...来源, ...目标 }，可用 merge.createItem 整份接管）、<b>尺寸取双方最大、图标优先目标</b>、绑在它上面的线路改绑、合并出来的自环与零长线删掉；两端因此撞成同一条的通道按 merge.channelGroups 处理（各自保留分组 / 合成一个分组，自环的整条删），读数里会带上改端点的通道数与并掉的通道数。取消或接口失败则把拖动的节点与跟随它的线路还原回原位，并补发一条拖拽结束。③ <b>所有快捷键都能改</b>——options.shortcuts 按动作配（框选 / 多选 / 加点 / 复制 / 复制到剪贴板 / 粘贴 / 取消 / 删除 / 适应视图），写法是纯修饰键（ctrl / meta / shift / alt / mod）、组合键（ctrl+c）、单键（escape / 0）或数组，写 false 表示不绑定；面板「视图 · 交互」里那四个下拉就是改框选 / 多选 / 加点 / 复制的修饰键——比如把框选改成 Shift，之后 Shift + 拖动才出选框，按住 Shift 时连光标变体也跟着走。④ <b>选中抬层</b>——selectionOnTop（缺省开）把选中的节点、拖动中的整组、待确认合并的目标节点与选中线路所在的整条通道画在所有要素之上：选中了就一定看得见，与 zIndex 无关；关掉就完全按 zIndex 与数据顺序画。⑤ <b>删除（Delete）</b>——选中拐点 / 线路 / 节点之后按 Delete（或面板上的「删除选中」）先出一份删除载荷：要删什么、连带什么、能按哪些范围删。<b>组件不弹界面</b>：pending 停在原地等 <b>confirm(scope)</b> / cancel()，Esc 也能取消；范围三档是「只删选中的线路」/「删除整个分组」/「删除整条通道」（后两档只在删的是通道回线、且这条通道分过组时才有），选中的拐点与节点一律一起删 —— <b>删节点会连挂在它身上的线路、以及拿它当端点的整条通道一起删</b>，载荷里的 lineCount / channelCount 就是这份连带读数；确认之后整段合成一条历史，撤销一步全回来；开关是 features.remove，快捷键照样走 shortcuts.remove（可以单独配成 shift+delete 之类）。⑥ <b>通道选中模式</b>——channelSelectMode 决定点中一条通道回线时选中什么：line（缺省，只选这一条）/ group（连它所在分组一起）/ channel（整条通道一起）；在 group / channel 下 Ctrl + 点击是<b>整批取反</b>，通道以外的线路永远只选它自己。它只影响「下一次点选怎么摊开」，切换走 updateOptions，场景一个字节都不用重排。面板「视图 · 复制合并」里那两项就是它们。</p>
 					<p>定位口径这一轮统一了：<code>focusOn(target)</code> 缺省只把中心移到目标上，比例一点不动；要按目标范围适配必须显式写 <code>{ zoom: true }</code>，可再配 <code>padding</code> / <code>maxZoom</code>。节点、线路、通道与分组走同一条规则，搜索面板与画布菜单里需要适配的按钮都已经写成显式开启。</p>
 				</div>
 				<span class="demo-badge">WebGL2 · 无内置 GUI</span>

package/docs/demos/gis-view-demo/GisViewDemoStage.vue

@@ -67,7 +67,7 @@ const {
 						<span>world ({{ canvasMenu.world[0].toFixed(2) }}, {{ canvasMenu.world[1].toFixed(2) }}) · 选中 {{ canvasMenu.selection?.count ?? 0 }} 个</span>
 						<button type="button" @click="closeCanvasMenu">×</button>
 					</div>
-					<p class="demo-channel-menu-hint">右键载荷（onContextMenu）里就带着 x / y、world、命中的要素与 selection 读数：这份菜单整个写在 demo 里，组件不带任何界面。每一行都是一个公开方法；落在空白处先 preventDefault 掉浏览器自带菜单。空白处多一行「新增场站」：弹一份 demo 自己的表单，收集字段后走 addPoint，落点默认就是这一下右键的 world 坐标。</p>
+					<p class="demo-channel-menu-hint">右键载荷（onContextMenu）里带着命中的要素、world 与 originalEvent，选中集读数由 view.getSelectionInfo() / getSelectionData() 取：这份菜单整个写在 demo 里，组件不带任何界面。每一行都是一个公开方法；落在空白处先对 originalEvent 调 preventDefault 收掉浏览器自带菜单。空白处多一行「新增场站」：弹一份 demo 自己的表单，收集字段后走 addPoint，落点默认就是这一下右键的 world 坐标。</p>
 					<div class="demo-channel-menu-actions">
 						<button v-for="row in canvasMenuRows" :key="row.id" type="button" :data-demo="'canvas-menu-' + row.id" :disabled="!row.enabled" :title="row.reason" @click="runCanvasMenuAction(row)">{{ row.label }}</button>
 					</div>

package/docs/demos/gis-view-demo/panels/DataPanels.vue

@@ -179,7 +179,7 @@ const {
 				<span class="demo-control-hint">{{ channelDraftReadout }}</span>
 			</div>
 			<div class="demo-controls">
-				<details class="demo-hint-more"><summary>说明</summary><span class="demo-control-hint">新建通道（kind: 'channel'）：两个节点之间没有通道就建一条，已有通道就变成新分组 / 并入某一组；「一次加几回」决定这一次往通道里加几条回线 —— 新通道 / 新分组 / 并入分组的余量都按它算，加不下的方案置灰（上限是 options.channelMaxGroups / channelGroupMaxLines）。新建线路（kind: 'line'）：只加线路、不挂任何通道，两个节点相同才不允许。两者的草稿交互是同一套，onChannelDraft 载荷里的 kind 与 circuits 说明这一段在加什么，「继续新增」时还能换（continueAddChannel({ kind, circuits })）。勾上「交接模式」之后两个节点选完就先收起草稿（假通道消失），由 demo 自己在 onChannelDraft 的 ready 回调里调 addChannel 落地（面板的逐条属性走第二段 lineItems；与「选完两个节点直接落地」同时勾时后者先落地）。选完两个节点后，结束事件（ready）的读数（hasChannel / hasGroup / groupCount / groups / group / channel / existingChannelId）摆到下面「结束事件」那一行；旁边的「收掉假通道不新建」演示 endAddChannel：静默收掉示例假通道、数据不动、不补 cancel 事件</span></details>
+				<details class="demo-hint-more"><summary>说明</summary><span class="demo-control-hint">新建通道（beginAddChannel）：两个节点之间没有通道就建一条，已有通道就变成新分组 / 并入某一组；「一次加几回」决定这一次往通道里加几条回线 —— 新通道 / 新分组 / 并入分组的余量都按它算，加不下的方案置灰（上限是 options.channelMaxGroups / channelGroupMaxLines）。新建线路（beginAddLine）：只加线路、不挂任何通道，两个节点相同才不允许。两个入口各自固定语义，不能靠 continueAddChannel 中途切换；要换入口请点对应的新增按钮。勾上「交接模式」之后两个节点选完就先收起草稿（假通道消失），由 demo 自己在 onChannelDraft 的 ready 回调里调 addChannel 落地（面板的逐条属性走第二段 lineData；与「选完两个节点直接落地」同时勾时后者先落地）。选完两个节点后，结束事件（ready）的读数（hasChannel / hasGroup / groupCount / groups / group / channel / existingChannelId）摆到下面「结束事件」那一行；旁边的「收掉假通道不新建」演示 endAddChannel：静默收掉示例假通道、数据不动、不补 cancel 事件</span></details>
 			</div>
 			<div class="demo-controls">
 				<span class="demo-control-hint">onChannelDraftClick（草稿里每点一次都发）：{{ draftClickText }}</span>

package/docs/demos/gis-view-demo/useGisViewDemo.js

@@ -1426,7 +1426,7 @@ export const useGisViewDemo = () => {
 		if (!payload) {
 			return []
 		}
-		const count = payload.selection?.count ?? 0
+		const count = viewRef.value?.getSelectionInfo().count ?? 0
 		return [
 			{ id: 'addStation', label: `新增场站（addPoint）· 落点 (${payload.world[0].toFixed(1)}, ${payload.world[1].toFixed(1)})`, enabled: !payload.hit, reason: '这一下命中了要素：在空白处右键才能新增场站' },
 			{ id: 'locate', label: `定位并适配选中（focusOn）${count ? ` · ${count} 个` : ''}`, enabled: count > 0, reason: '先在画布上选一个 / 一批要素' },
@@ -2806,7 +2806,7 @@ export const useGisViewDemo = () => {
 		selectionReadout.value = `左键载荷：${describeSelectionPayload(payload)}`
 		const pickedChannel = payload?.channelId === undefined ? '' : ` · 通道 ${String(payload.channelId)}${payload.groupId === undefined ? '' : ` / 分组 ${String(payload.groupId)}`}`
 		lastEvent.value = payload
-			? `单击 ${formatFeature(payload)}${pickedChannel} · 世界 (${payload.coordinate[0].toFixed(4)}, ${payload.coordinate[1].toFixed(4)}) · ${payload.selected ? '已选中' : '未选中'}（点之前${payload.wasSelected ? '已选中' : '未选中'}）· 选中集 ${payload.selection?.count ?? 0} 个`
+			? `单击 ${formatFeature(payload)}${pickedChannel} · 世界 (${payload.coordinate[0].toFixed(4)}, ${payload.coordinate[1].toFixed(4)}) · ${payload.selected ? '已选中' : '未选中'}（点之前${payload.wasSelected ? '已选中' : '未选中'}）· 选中集 ${viewRef.value?.getSelectionInfo().count ?? 0} 个`
 			: '单击空白处，已清空选中。'
 	}
 	const handleDblClick = (payload) => {
@@ -2820,7 +2820,7 @@ export const useGisViewDemo = () => {
 		const target = payload.hit ? formatFeature(payload) : '空白处'
 		const channel = payload.channelId === undefined ? '' : ` · 通道 ${String(payload.channelId)}${payload.groupId === undefined ? '' : ` / 分组 ${String(payload.groupId)}`}`
 		const state = payload.selected === undefined ? '' : ` · ${payload.selected ? '已选中' : '未选中'}`
-		return `${target}${channel}${state} · world (${payload.world[0].toFixed(4)}, ${payload.world[1].toFixed(4)}) · button ${payload.button}`
+		return `${target}${channel}${state} · world (${payload.world[0].toFixed(4)}, ${payload.world[1].toFixed(4)}) · button ${payload.originalEvent?.button ?? '-'}`
 	}
 	const handlePointerDown = (payload) => {
 		writePointerText(`按下 ${describePointer(payload)}`)
@@ -2839,7 +2839,7 @@ export const useGisViewDemo = () => {
 				viewRef.value?.selectFeatures(payload.item.id)
 			}
 			// 选完再取一次选中集读数：面板上的「把选中的 N 个并拢」按的是点下去那一刻的实际选中集
-			pointMenu.value = { ...payload, kept: payload.wasSelected === true, selection: viewRef.value?.getSelectionData() ?? payload.selection }
+			pointMenu.value = { ...payload, kept: payload.wasSelected === true }
 		}
 		else {
 			pointMenu.value = null
@@ -2852,12 +2852,12 @@ export const useGisViewDemo = () => {
 			else {
 				closeChannelMenu()
 				// 空白处与「普通线路」在这里弹画布菜单
-				canvasMenu.value = { ...payload, selection: viewRef.value?.getSelectionData() ?? payload.selection }
+				canvasMenu.value = payload
 			}
 			// 组件只发回调、不碰浏览器默认行为：右键菜单由使用方决定，这里先把自带的那份收掉
 			payload.originalEvent?.preventDefault?.()
 		}
-		lastEvent.value = `右键 ${describePointer(payload)} · ${payload.type === 'point' ? (payload.wasSelected ? '命中已经选中的那一个：保留整份选中集' : '命中的没在选中集里：先把它选上再弹面板') : payload.channelContext ? '命中通道回线：同一份载荷的 channelContext 直接弹通道右键框' : '落在空白处 / 普通线路上：弹画布菜单（每一行都是一个公开方法）'} · 选中集 ${payload.selection?.count ?? 0} 个 · onContextMenu 每个右键都发（点 / 线 / 通道 / 空白），要自己弹菜单就在回调里 event.preventDefault()`
+		lastEvent.value = `右键 ${describePointer(payload)} · ${payload.type === 'point' ? (payload.wasSelected ? '命中已经选中的那一个：保留整份选中集' : '命中的没在选中集里：先把它选上再弹面板') : payload.channelContext ? '命中通道回线：同一份载荷的 channelContext 直接弹通道右键框' : '落在空白处 / 普通线路上：弹画布菜单（每一行都是一个公开方法）'} · 选中集 ${viewRef.value?.getSelectionInfo().count ?? 0} 个 · onContextMenu 每个右键都发（点 / 线 / 通道 / 空白），要自己弹菜单就在回调里 payload.originalEvent.preventDefault()`
 	}
 	const handleDrag = (payload) => {
 		const phase = payload.phase === 'start' ? '开始拖拽' : payload.phase === 'drag' ? '拖拽中' : '拖拽结束'
@@ -5397,8 +5397,8 @@ export const useGisViewDemo = () => {
 	const selectedItemsJson = ref('')
 	/**
 	 * 指针载荷里的选中信息：selected（现在在不在选中集里）/ wasSelected（onClick 给「点之前」的那一份，
-	 * 右键与按下 / 松开就是当下）与整份选中集读数 selection（ids / count / 点 / 线 / 通道条数）。
-	 * 左键右键要自己接一套操作（自建面板、按命中分支）时，看这几项就够了。
+	 * 右键与按下 / 松开就是当下）；整份选中集读数改调 view.getSelectionInfo()。
+	 * 左键右键要自己接一套操作（自建面板、按命中分支）时，看快照 + 这一次读数就够了。
 	 * Ctrl + 点击（多选取反）与 Ctrl + 拖动（框选）不走 onClick，那一下的结果看 onSelectChange。
 	 */
 	const describeSelectionPayload = (payload) => {
@@ -5409,7 +5409,7 @@ export const useGisViewDemo = () => {
 		const target = payload.type ? formatFeature(payload) : '空白处'
 		const state = payload.selected === true ? '现在已选中' : '现在未选中'
 		const before = payload.wasSelected === undefined ? '' : ` · ${payload.wasSelected ? '在这之前已选中' : '在这之前未选中'}`
-		const info = payload.selection
+		const info = viewRef.value?.getSelectionInfo()
 		const bag = info ? ` · 选中集 ${info.count} 个（点 ${info.points} / 线 ${info.lines} / 通道 ${info.channels}）${info.ids.length ? ` · ids ${info.ids.slice(0, 3).map(String).join(', ')}${info.ids.length > 3 ? '…' : ''}` : ''}` : ''
 		return `${target} · ${state}${before}${bag}`
 	}
@@ -5434,11 +5434,11 @@ export const useGisViewDemo = () => {
 			lines: data.lines.slice(0, 3).map((line, slot) => line.name ?? line.id ?? `lines[${data.lineIndexes[slot]}]`),
 			channels: data.channels.slice(0, 3).map(channel => channel.name ?? channel.id ?? '(无 id)')
 		}, null, 1)
-		lastEvent.value = '选中信息：getSelectionData() 一份取全（ids / count / 点线通道条数 / 要素本身 / 下标 / bounds），与指针载荷里的 selection 是同一份 state'
+		lastEvent.value = '选中信息：getSelectionData() 一份取全（ids / count / 点线通道条数 / 要素本身 / 下标 / bounds），指针 / 右键载荷不再挂这份读数，需要时直接调 getSelectionInfo()'
 	}
 	/**
 	 * 节点右键面板：组件本身不弹任何菜单，右键载荷里就已经给全了 ——
-	 * wasSelected（命中前它在不在选中集里）+ selection（整份选中集读数）。
+	 * wasSelected（命中前它在不在选中集里），整份选中集读数调 view.getSelectionInfo()。
 	 * 这里的规矩是常见的那一套：右键已经选中的节点保留整份选中集，右键没选中的节点先把它选上再弹面板；
 	 * 面板上的按钮各走一个公开方法（focusOn / copyPoint / mergeSelectedPoints / removePoints / selectFeatures(null)）。
 	 */
@@ -5507,7 +5507,7 @@ export const useGisViewDemo = () => {
 		if (!payload) {
 			return []
 		}
-		const count = payload.selection?.count ?? 1
+		const count = viewRef.value?.getSelectionInfo().count ?? 0
 		return [
 			{ id: 'focus', label: '聚焦到它（focusOn）', enabled: true, reason: '' },
 			{ id: 'copy', label: '复制一份（copyPoint）', enabled: true, reason: '' },
@@ -5733,13 +5733,13 @@ export const useGisViewDemo = () => {
 		const view = viewRef.value
 		const lineOnly = payload.kind === 'line'
 		// 面板上的逐条属性（一条 / 一批）就是第二段：按每项 id 建回线，这些 id 自动组成通道的 lineIds
-		const members = (payload.lineItems ?? payload.linePropsByMember ?? []).filter(Boolean)
+const members = (payload.lineData ?? payload.linePropsByMember ?? []).filter(Boolean)
 		const baseProps = payload.lineProps ?? {}
 		const lineData = members.length
 			? members.map(item => ({ ...baseProps, ...item }))
 			: Array.from({ length: Math.max(payload.circuits ?? 1, 1) }, () => ({ ...baseProps }))
 		if (lineOnly) {
-			const lineResult = view.addLine({ from: payload.from.id, to: payload.to.id, name: payload.name, lineProps: payload.lineProps }, lineData)
+			const lineResult = view.addLine({ from: payload.from.id, to: payload.to.id, name: payload.name, lineProps: payload.lineProps }, lineData, { select: true })
 			if (lineResult.ok) {
 				lastAddedChannel.value = { lineIds: lineResult.lineIds ?? [], lineId: lineResult.lineId, channelId: null, resolution: lineResult.resolution }
 				syncChannelLabel()
@@ -5750,9 +5750,9 @@ export const useGisViewDemo = () => {
 		}
 		const result = payload.hasChannel && payload.channel
 			? (payload.hasGroup
-				? view.joinChannelGroupLines(payload.channel.id, undefined, lineData)
-				: view.addChannelGroupLines(payload.channel.id, lineData))
-			: view.addChannel({ from: payload.from.id, to: payload.to.id, name: payload.name }, lineData)
+				? view.joinChannelGroupLines(payload.channel.id, undefined, lineData, { select: true })
+				: view.addChannelGroupLines(payload.channel.id, lineData, undefined, { select: true }))
+			: view.addChannel({ from: payload.from.id, to: payload.to.id, name: payload.name }, lineData, undefined, { select: true })
 		if (result.ok) {
 			lastAddedChannel.value = { lineIds: result.lineIds ?? [], lineId: result.lineId, channelId: result.channelId, resolution: result.resolution }
 			syncChannelLabel()
@@ -5828,9 +5828,9 @@ export const useGisViewDemo = () => {
 		channelDraft.value = null
 		draftClickText.value = '—'
 		const lineOnly = kind === 'line'
-		view.beginAddChannel({
-			// kind 为 'line' 时不挂通道（新建线路）；circuits 是新建通道时一次加几回
-			kind: lineOnly ? 'line' : 'channel',
+		const begin = lineOnly ? view.beginAddLine : view.beginAddChannel
+		begin.call(view, {
+			// circuits 是这一段一次加几回
 			circuits: addChannelCircuits.value,
 			autoCommit: addChannelAutoCommit.value,
 			// 连续新增：落地之后自动开下一段；'chain' 再以上一段终点当下一段起点
@@ -5849,16 +5849,15 @@ export const useGisViewDemo = () => {
 			? `新建线路：点两个节点，第二个点完直接落到图上（不挂通道${addChannelCircuits.value > 1 ? `，一次 ${addChannelCircuits.value} 条` : ''}）`
 			: `新建通道（一次 ${addChannelCircuits.value} 回）：点第一个节点当起点，再点第二个节点出方案${addChannelAutoCommit.value ? '，第二个点完直接落地' : '（下面的按钮选怎么加）'}${addChannelContinuous.value ? '；落地之后草稿自动重开，可以接着加下一条' : ''}`
 	}
-	/** 手动开下一段草稿：连续模式落地时是自动的，这里演示「草稿退出之后接着加」，顺便换这一段加什么 */
-	const continueAddChannel = (kind = 'channel') => {
+	/** 手动开下一段草稿：连续模式落地时是自动的，这里演示「草稿退出之后接着加」 */
+	const continueAddChannel = () => {
 		const view = viewRef.value
 		if (!view) {
 			return
 		}
-		const lineOnly = kind === 'line'
+		const lineOnly = channelDraft.value?.kind === 'line'
 		view.continueAddChannel({
-			// 重开这一段时把 kind / circuits 一起传下去：想换成「新建线路」就再点一次上面的按钮
-			kind: lineOnly ? 'line' : 'channel',
+			// 入口语义由本次草稿决定；想切换通道 / 独立线路请点上面的两个新增按钮
 			circuits: addChannelCircuits.value,
 			autoCommit: addChannelAutoCommit.value,
 			continuous: addChannelContinuous.value ? (addChannelChain.value ? 'chain' : true) : false,
@@ -5936,7 +5935,7 @@ export const useGisViewDemo = () => {
 		if (!view || !draft) {
 			return
 		}
-		const result = view.commitAddChannel(option ? { type: option.type, groupId: option.groupId } : undefined)
+		const result = view.commitAddChannel(option ? { resolution: { type: option.type, groupId: option.groupId } } : undefined, { select: true })
 		channelDraft.value = null
 		if (result.ok) {
 			lastAddedChannel.value = { lineIds: result.lineIds ?? [], lineId: result.lineId, channelId: result.channelId, resolution: result.resolution }
@@ -5967,7 +5966,7 @@ export const useGisViewDemo = () => {
 			from: from.id,
 			to: target.id,
 			name: `新增通道 ${String(from.id)} ↔ ${String(target.id)}`
-		}, Array.from({ length: Math.max(Math.trunc(Number(addChannelCircuits.value)) || 1, 1) }, (_item, index) => ({ color: '#f4a259', width: 3, ...(buildLinePropsByMember()?.[index] ?? {}) })))
+		}, Array.from({ length: Math.max(Math.trunc(Number(addChannelCircuits.value)) || 1, 1) }, (_item, index) => ({ color: '#f4a259', width: 3, ...(buildLinePropsByMember()?.[index] ?? {}) })), undefined, { select: true })
 		if (result.ok) {
 			lastAddedChannel.value = { lineIds: result.lineIds ?? [], lineId: result.lineId, channelId: result.channelId, resolution: result.resolution }
 		}
@@ -5978,7 +5977,7 @@ export const useGisViewDemo = () => {
 		syncChannelGroupPanel()
 		syncParallelGroups()
 	}
-	/** 程序化新增独立线路：不挂通道（等价于 kind: 'line'），一次加几回由「一次加几回」下拉决定 */
+	/** 程序化新增独立线路：不挂通道，一次加几回由「一次加几回」下拉决定 */
 	const addLineProgrammatic = () => {
 		const view = viewRef.value
 		if (!view) {
@@ -5991,19 +5990,18 @@ export const useGisViewDemo = () => {
 			lastEvent.value = '程序化新增线路：至少要有两个节点'
 			return
 		}
+		const lineData = Array.from({ length: Math.max(Math.trunc(Number(addChannelCircuits.value)) || 1, 1) }, (_item, index) => ({ ...(buildLinePropsByMember()?.[index] ?? {}) }))
 		const result = view.addLine({
 			from: from.id,
 			to: target.id,
-			circuits: addChannelCircuits.value,
 			name: `独立线路 ${String(from.id)} ↔ ${String(target.id)}`,
-			lineProps: { color: '#25c2a0', width: 2.5 },
-			linePropsByMember: buildLinePropsByMember()
-		})
+			lineProps: { color: '#25c2a0', width: 2.5 }
+		}, lineData, { select: true })
 		if (result.ok) {
 			lastAddedChannel.value = { lineIds: result.lineIds ?? [], lineId: result.lineId, channelId: null, resolution: result.resolution }
 		}
 		lastEvent.value = result.ok
-			? `程序化新增独立线路（一次 ${result.circuits} 条）：${describeChannelAdd(result)}（kind: 'line'，不挂通道，通道声明里不会有它）`
+			? `程序化新增独立线路（一次 ${result.circuits} 条）：${describeChannelAdd(result)}（不挂通道，通道声明里不会有它）`
 			: `没能新增：${result.reason}`
 		syncChannelLabel()
 		syncChannelGroupPanel()

package/docs/format/02-/350/212/202/347/202/271/344/270/216/347/272/277/350/267/257.md

@@ -15,6 +15,7 @@
 | `shadow` | `GisViewShadow` | 无（不画阴影） | 阴影：`{ color, blur, offsetX, offsetY }`，偏移与模糊都是 CSS 像素 |
 | `visible` | `boolean` | `true` | `false` 时这个节点不画（等价于被筛选隐藏，但数据还在）；被它锚定的通道与回线一起消失 |
 | `clickable` / `draggable` / `copyable` / `mergeable` | `boolean` | 前两个跟随 `options.clickable` / `options.draggable`（**`options.draggable` 缺省关**：不写它就没有节点可拖，逐条的 `draggable: true` 也得等这个总开关或者 `features.drag` 打开才生效）；`copyable` / `mergeable` 缺省 `true` | 逐条覆盖 `options` 上的同名开关 |
+| `mergeInfo` | `GisViewMergeInfo \| null` | 无 | `mergePoints` / `mergeSelectedPoints` 写入的合并追溯（版本 `1`）：保留节点保存 `targetPoint`、`sourceIds`、来源 `points` 快照与受影响 `lines` / `channels` 快照；`splitPoint(source)` 省略 `parts` 时据此自动解除合并。可 JSON 序列化，随数据导出；保留字段，业务数据不要占用。字段详解见 [manual 07 的「合并追溯」](../manual/07-%E6%8C%87%E9%92%88%E4%B8%8E%E8%A6%81%E7%B4%A0%E7%BC%96%E8%BE%91.md#%E5%90%88%E5%B9%B6%E8%BF%BD%E6%BA%AFmergeinfo) |
 | `cursor` / `ctrlCursor` | `GisViewCursorValue` | 跟随 `options.cursorStyle.point` / `cursorStyle.ctrl.point` | 悬停这个点时的光标（按住 Ctrl / ⌘ 时用后者），写法见 GisView.md 的「光标」 |
 | `hoverStyle` / `selectStyle` / `multiSelectStyle` / `boxSelectStyle` | `GisViewPointStyle` | 分别跟随 `options.pointHoverStyle` / `pointSelectStyle` / `pointMultiSelectStyle` / `pointBoxSelectStyle`（后两个缺省回落到选中样式） | 逐条覆盖悬停 / 选中 / Ctrl 多选 / 框选样式，按字段覆盖自身样式 |
 | `labels` | `GisViewItemLabel \| GisViewItemLabel[]` | 无（不写且没配 `label` 就不画标签） | 这个点上的标签清单（可以多条），见下文「标签」；`labelVisible` / `labelVisibility` / `labelPosition` / `labelOffset` 是旧式单条写法 |

package/docs/format/04-/351/200/232/351/201/223/344/270/216/346/240/207/347/255/276.md

@@ -11,6 +11,7 @@
 | `from` / `to` | `string \| number` | **必填** | 两端节点 id，节点不存在时整条通道与回线一起不显示；两端都要落在节点上，只声明一端不行 |
 | `circuits` | `number` | `1` | 回线数量（`createChannels` 用它展开回线） |
 | `lineIds` | `Array<string \| number>` | 无（`createChannels` 生成的那一份就是它） | 组成这条通道的线路 id，**顺序即回线顺序**（沿骨架左法线从负到正） |
+| `mergeInfo` | `GisViewMergeInfo \| null` | 无 | 合并后仍存在的受影响通道带轻量追溯：`{ version, targetId, sourceIds, originalIds }`；`originalIds` 是参与合并、被改端点或被并掉的原始通道 id，便于后端对账。可 JSON 序列化；保留字段，业务数据不要占用。完整快照在保留节点的 `mergeInfo` 上 |
 | `path` | `GisViewCoordinate[]` | 无（两端直连） | 骨架的**中间拐点**（不含两端，两端由节点坐标补齐）：与线路的 `path` 相反，这里只写中间 |
 | `groups` | `GisViewChannelGroup[]` | 无（= 一个通道一组） | 分组声明：`[{ id, lineIds, path, waypointOffsets? }]`，一组一条走廊；拆分 / 合并的结果写在这里，见「分组」 |
 | `width` / `offsetMode` / `inset` / `tangentInset` | `number` / `'tangent' \| 'inset'` / `number` / `number \| null` | 分别回落到 `options.channelWidth`（`0.02`）/ `'tangent'` / `options.channelInset`（`0`）/ `options.channelTangentInset`（`null` = 按回线线宽收） | 通道外观：宽度（`tangent` 下是最外侧两条回线的中心距）、偏移方式、内收比例（负数为外收）、两端切点内收 |
@@ -19,6 +20,8 @@
 | `lineProps` / `linePropsByMember` | `Partial<GisViewLine>` / 数组 | 无 | 回线上透传的业务字段（`lineProps` 全体共用、`linePropsByMember[i]` 只作用第 i 回，后者优先） |
 | `channelProps` | `Partial<GisViewChannel>` | 无 | 通道上额外透传的字段（原样带到通道声明里） |
 
+`channelSimplify` 是视图级渲染选项（`options.channelSimplify`），不是通道数据字段：它可以让分组在回线数超过阈值时只画一条代表线，但不写入 `channels`、不改 `lineIds` / `groups`，也不会出现在 `exportData()` 的通道字段里。
+
 ### 通道分组（拐点分组 / parallel_groups）
 
 - **一组**（默认）：`lineIds` 是全部成员、`path` 是这一组的拐点；`getChannelGroups(id)` 返回一组。

package/docs/format/07-/344/272/213/344/273/266/350/275/275/350/215/267/344/270/216/347/244/272/344/276/213/346/225/260/346/215/256.md

@@ -11,17 +11,17 @@
 | `type` | 命中的要素类型：`'point'` / `'line'`（通道回线也是 `'line'`） |
 | `index` / `item` | 在 `points` / `lines` 里的下标与数据对象（空白处没有这两项） |
 | `screen` / `coordinate` / `distance` | 命中点：画布 CSS 像素、世界坐标、拾取距离（像素） |
-| `selection` | 选中集读数 `{ ids, count, points, lines, channels }`（通道回线按通道算一个） |
-| `selected` / `wasSelected` | 这一刻 / 点之前在不在选中集里 |
+| `selected` / `wasSelected` | 这一刻 / 点之前在不在选中集里（事件快照；整份计数用 `getSelectionInfo()`） |
 | `channelIndex` / `channel` / `groupId` / `group` | 命中通道回线时多给的通道读数（`channel` 是通道定义，`group` 是分组读数） |
 | `action` | 这次操作的判读（见下） |
 | `lngLat` | 配了 GeoJSON 底图时的经纬度 |
 
 `action` 是同一套写法：`type` 是动作（`select` / `clearSelection` / `click` / `hover` / `contextMenu` /
 `dragPoint` / `boxSelect` / `pan` / `selectLabel` / `dragLabel` / `dblClick`…）、`target` 是目标
-（`point` / `line` / `channel` / `empty` / `label` / `selection`）、`data` 就是那一份数据
-（点 / 线是数据对象、通道回线是通道定义、标签是 `{ label, parent }`）、`button` / `modifiers` / `moved` /
-`double` / `press` / `duration` 说明按了什么键、拖没拖、是不是双击的第二下。
+（`point` / `line` / `channel` / `empty` / `label` / `selection`）、`moved` / `double` / `press` / `duration`
+说明拖没拖、是不是双击的第二下、按了多久。命中的数据在载荷顶层：点 / 线读 `item`，通道回线读
+`channel` / `channelContext`，标签读 `label` / `parent`，拐点读 `lineIndex` / `pathIndex` / `coordinate` / `line`。
+鼠标键、修饰键与 clientX / clientY 读 `payload.originalEvent`；整份选中集读数用 `view.getSelectionInfo()`。
 
 ### 选中集
 
@@ -41,8 +41,8 @@
 | `onLabelClick` / `onLabelDrag` / `onLabelContextMenu` / `onLabelDblClick` | `kind` / `index` / `id` / `labelId` / `item` / `label`（这一条标签的 id、内容、来源、合并后的样式）/ `parent`（挂在哪条要素上，线路在通道里时带通道 / 分组）/ `state` |
 | `onQualityChange` | `{ mode, name, level, glow, ornament, scale, budgetMs, frameMs }` |
 
-三个事件的总线载荷是 `{ payload, event }`（要原样带回 DOM 事件）：`pointerDown` / `pointerUp` / `contextMenu`，
-回调那一侧仍是 `(payload, event)` 两个参数，`view.on` 订阅时记得拆包；通道回线的右键上下文在同一份
+`pointerDown` / `pointerUp` / `contextMenu` 与其余事件一样是「回调一份载荷、总线同一份载荷」，不再额外包
+`{ payload, event }`；要原始 DOM 事件就读 `payload.originalEvent`。通道回线的右键上下文在同一份
 `contextMenu` 载荷的 `channelContext` 上。
 
 ### 自建面板常用的读数
@@ -53,6 +53,7 @@
 | `listPoints(options)` / `listLines(options)` | 带 `index` / `item` / 几何 / 颜色的快照，`withScreen: true` 直接给屏幕坐标 |
 | `getLineChannel(ref)` | 这条回线属于哪条通道、哪一组（`{ lineIndex, channelId, channelIndex, channel, groupId, group }`） |
 | `isSelected(ref)` | 这个要素在不在选中集里 |
+| `getSelectionInfo()` | 选中集轻量计数：`{ ids, count, points, lines, channels }`；指针 / 点击 / 悬停载荷不再重复挂这一份 |
 | `getSelectionData()` | 选中集一次取全：读数（`ids` / `count` / `pointCount` / `lineCount` / `channelCount`）/ 要素本身（`points` / `lines` / `channels`）/ `items` / 下标 / 世界包围盒 `bounds` |
 
 ## 示例数据

package/docs/from0/05-/347/233/270/346/234/272/344/270/216/344/272/244/344/272/222.md

@@ -152,7 +152,7 @@ export const DEFAULT_SHORTCUTS = {
 
 ② **不能被拾取**。预览跟着鼠标走，光标十有八九正压在它上面；如果 `pick()` 会命中它，鼠标一移过去就会「停在预览上」。所以 `pick` 与 `pickDraggablePoint` 都跳过 `pointCopy.index`，合并的候选里也要排除它。
 
-③ **要能改**。使用方可能想在落地前改复制品的名字、颜色、业务字段 —— 事件载荷里给 `update(patch)` / `setItem(patch)`，内部只重解析这一个节点（`setCopyPreviewItem` 复用 `updatePoint` 那条增量路径），坐标仍以预览落点为准。
+③ **要能改**。使用方可能想在落地前改复制品的名字、颜色、业务字段 —— 事件载荷里给 `update(patch)`，内部只重解析这一个节点（`setCopyPreviewItem` 复用 `updatePoint` 那条增量路径），坐标仍以预览落点为准（`payload.item.x` / `payload.item.y`）。
 
 落地分两步，中间留了一个可以反悔的口子：
 

package/docs/from0/07-/351/200/232/351/201/223/345/210/206/347/273/204/344/270/216/345/244/232/345/233/236/347/272/277.md

@@ -274,24 +274,40 @@ const shift = ordinal * (span + gap)   // 第 1 组原地不动（ordinal 为 0
 - `setCurrentChannelGroup(channelId, groupId)` 记下「当前分组」并把它整组选中，右键框与分组列表共用这一份状态；
 - `runChannelAction(actionId, options)` 把界面的动作转成引擎调用，返回执行之后的新上下文。
 
-新增通道走同一条思路：`beginAddChannel()` 进入草稿态 → 只认节点（点空白继续等）→ 第二个节点点完给方案表
+新增流程走同一条思路，入口按语义拆成 `beginAddChannel()`（新建通道）与 `beginAddLine()`（新建线路）：
+两者都进入草稿态 → 只认节点（点空白继续等）→ 第二个节点点完给方案表
 （`newChannel` / `newGroup` / `joinGroup`，按 `channelMaxGroups` / `channelGroupMaxLines` 标 `enabled`），
 `applyChannelAdd`（实例层）把方案落到数据副本：新回线 id 防撞、`groups` 声明按引擎现状重写、新组不带拐点、
 并入就塞进目标组。草稿期间数据整份换过要在 `validateChannelDraft` 里作废，否则会拿着旧下标去落点。
 
-一次加几回、加不加通道，是同一段代码的两个分支（`kind` / `circuits`）：
+一次加几回、加不加通道，由入口语义与 `circuits` / `lineData` 决定（草稿载荷里的 `kind` 只读）：
 
 - **余量按「这一次加几回」算**：`count` 传进 `buildChannelAddOptions` 之后，`newGroup` 要「还能新分组」且
   `count <= channelGroupMaxLines`，`joinGroup` 要这一组剩下的余量 `>= count`（不可用时 `reason` 写清
   「只剩 R 回余量，本次要加 M 回」）。一条条加的时候这些判断都等价于「还能不能加一条」，所以旧代码不用改，
   只是把「1」换成调用方给的数。
 - **落地一次生成一批**：`applyChannelAdd` 按 `count` 循环，每条 id 都查一次重（`uniqueLineId`）、名字加 `#序号`，
-  `newChannel` 把这一批 `lineIds` 整体写进新通道，`newGroup` / `joinGroup` 整体并进目标分组，落地后整批选中。
+  `newChannel` 把这一批 `lineIds` 整体写进新通道，`newGroup` / `joinGroup` 整体并进目标分组。落地后缺省不改变
+  选中集；需要选中整批新回线时，由 `commitAddChannel(..., { select: true })` 或程序化新增的 `options.select` 打开。
   结果里 `lines` / `lineIds` 是这一批（`line` / `lineId` 是第一条），界面「移除上一条新增」按它整批摘。
-- **新建线路不碰通道**：`kind: 'line'` 时方案表留空（独立线路不挑方案），`applyChannelAdd` 只往 `lines` 里加，
-  `channels` 一个字节都不动；入口上就是 `addLine({ from, to, circuits })`（等价于
-  `addChannel({ ...input, kind: 'line' })`）。草稿里 `kind` / `circuits` 跟着载荷走，
-  `continueAddChannel({ kind, circuits })` 因此能在下一段换一种加法。
+- **新建线路默认不碰通道**：`beginAddLine()` 的 `kind` 恒为 `line`，不写 `existingChannel` 时方案表留空，
+  `applyChannelAdd` 只往 `lines` 里加，`channels` 一个字节都不动；程序化落地就是
+  `addLine({ from, to }, lineData)`（一次多回由 `lineData` 条数决定）。两端已有通道且显式写
+  `existingChannel: 'newGroup' / 'joinGroup' / 'auto'` 时，方案表才会改走通道分组，把这批新回线挂进已有通道。
+  `beginAddChannel({ kind: 'line' })` 已移除；`continueAddChannel(...)` 只续配置，不能在下一段切换通道 / 线路入口。
+
+**已有通道策略**由草稿的 `singleChannel` / `existingChannel` 决定，方案表仍负责计算「能不能加」：
+
+- `singleChannel: true` 只对 `beginAddChannel` 生效，等价于缺省 `existingChannel: 'block'`；两端已有通道时
+  `ready` 载荷带 `blocked: true`，提交返回失败并发 `phase: 'blocked'`，不会自动新建分组。
+- `existingChannel: 'newGroup'` 固定新加一组；`'joinGroup'` 用 `groupId` / `groupIndex`（从 0 起）指定分组；
+  `'auto'` 有新分组余量时优先新分组，否则并进可用分组；`'block'` 直接失败。
+- 没有已有通道时，这些策略不改变「新建通道」；`beginAddLine` 在没有通道时始终落成独立线路。
+- 阻断只影响**缺省提交**：使用方显式传一个可用的 `resolution`，仍可把这次新增改道到新分组 / 指定分组。
+
+解除合并（`splitPoint`）和通道分组共用同一个「成员不能拆散」的约束：`options.autoLines: 'alternate'`
+把同一条通道的成员当成一个分配单位、独立线路各算一个单位，轮流给负载最少的新节点；返回的
+`autoAssignedLines` 与 `lineAssignments` 让界面直接显示每份接到哪些回线、通道是否仍成组。
 
 ### 6.13 每点一次都要能拿到信息：草稿回调与连续新增
 
@@ -315,9 +331,9 @@ const shift = ordinal * (span + gap)   // 第 1 组原地不动（ordinal 为 0
 
 同理，鼠标的每一种动作都应当有一条平行的回调，且载荷里直接带上「当前是哪个元素」：
 `onHover`（悬停）、`onClick`（单击）、`onDblClick`（双击）、`onPointerDown` / `onPointerUp`（左 / 中 / 右键
-按下与抬起）、`onContextMenu`（右键）。后三条统一用 `buildPointerPayload(pick(x, y), point, event)`：
-把拾取结果摊平（`type` / `index` / `item` 与通道字段）、补上 `button` / `buttons`、光标的世界坐标与
-画布像素、以及 `originalEvent`；命中空白处 `hit` 为 false。要自己弹右键菜单就在回调里 `preventDefault()`，
+按下与抬起）、`onContextMenu`（右键）。后三条都只收一个 `payload`，统一由 `buildPointerPayload(pick(x, y), point, event)` 造：
+把拾取结果摊平（`type` / `index` / `item` 与通道字段），光标位置放 `world` / `x` / `y`；按键、修饰键与 `clientX` / `clientY`
+读 `payload.originalEvent`，选中集读数调 `getSelectionInfo()`。命中空白处 `hit` 为 false。要自己弹右键菜单就在回调里 `payload.originalEvent.preventDefault()`，
 引擎只负责「告诉你点到了什么」，不替你决定界面长什么样。