gis-view-webgl2 0.1.7 → 0.1.8

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/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()`，
 引擎只负责「告诉你点到了什么」，不替你决定界面长什么样。
 
 

package/docs/manual/02-/345/235/220/346/240/207/344/270/216/346/225/260/346/215/256.md

@@ -5,7 +5,7 @@
 ## 坐标、相机与像素
 
 - **世界坐标**：`x` / `y` 就是数据里的数值（经纬度、平面坐标都行），组件不做投影、不做坐标轴翻转。数据范围由节点与线路顶点共同决定（`getBounds()`）。
-- **相机**：`{ center: [x, y], scale }`，`scale` 的单位是**屏幕 CSS 像素 / 世界单位**（`getCamera()` / `setCamera()`）。`fitView(padding)` 适应整份数据，`zoomToBounds(bounds, padding)` 适应一段范围，`zoomTo(scale, origin)` 直接设比例，`zoomBy(factor, origin)` 按锚点缩放，`focusOn(target, { center: true })` 只挪中心。
+- **相机**：`{ center: [x, y], scale }`，`scale` 的单位是**屏幕 CSS 像素 / 世界单位**（`getCamera()` / `setCamera()`）。`fitView(padding)` 适应整份数据，`zoomToBounds(bounds, padding)` 适应一段范围，`zoomTo(scale, origin)` 直接设比例，`zoomBy(factor, origin)` 按锚点缩放，`focusOn(target)` 缺省只挪中心。
 - **滚轮缩放**：以光标为锚点，`deltaY` 100 对应 1.12 倍 —— 缩放量按 `deltaY` 的大小算（`deltaMode` 是行 / 页时先折算成像素），触摸板的连续小位移因此是平滑的小步长，鼠标滚轮的一格仍是原来那一步，一次甩得再大也有上限（`deltaY` 夹在 ±240，免得某个设备一次甩出十倍）。**缩放缺省是关的**（`interactive` / `zoom` 都没写时滚轮完全不接），写 `interactive: true` 或 `features: { zoom: true }` / `features: 'view'` 才接；接着的时候一律 `preventDefault()`（含 Ctrl + 滚轮的浏览器缩放）。
 - **三档坐标口径**（`world` 不多余：数据 `x` / `y` 就是世界坐标，事件载荷里叫 `world` 只是标口径；三档之间是「客户端坐标 ↔ 画布 CSS 像素 ↔ 世界坐标」的换算链）：
   - **世界坐标（`x` / `y`）**：数据、相机、几何读数、`focusOn` 与拖拽落点用的都是这一套，没有第二套；

package/docs/manual/04-/344/272/213/344/273/266/344/270/216/345/233/236/350/260/203.md

@@ -7,20 +7,20 @@
 | 字段 | 载荷 | 说明 |
 | --- | --- | --- |
 | `onReady` | `{ canvas, gl }` | WebGL2 上下文与缓冲区就绪 |
-| `onSelect` | `GisViewSelectPayload \| null` | 选中操作回调：回答「这一下选了什么」。真实单击 / Ctrl / `multiSelect` 取反 / 框选 / `selectAt()` 每次成功操作都发（清空与「取反取没了」的载荷是 `null`）；`selectFeatures()` / `deselect()` / `focusOn({ select })` 等按引用接口只在选中集实际变化时发。载荷带 `items` / `box` / `originalEvent` / `mode`；单通道时顶层还有 `channelId` / `channelIndex` / `channel` / `groupId` / `groupIndex` / `group` / `groups`，多通道看 `channelContexts`，`items[]` 里的回线只带 `channelId` / `channelIndex` / `groupId` / `groupIndex` 标量归属，不重复挂 `group` / `groups` |
-| `onClick` | `GisViewClickPayload \| null` | 单击要素或空白处（空白处为 `null`）：`type` / `item` / `index` / `screen` / `coordinate` / `button` / `selection` / `originalEvent` 之外还有 `action`（`type` 是 `select` / `toggleSelect` / `clearSelection` / `click`，`double` 说明这一下是不是双击里的第二下，`press` / `duration` / `longPress` 说明这一次按下想做什么、按了多久、算不算长按），见「指针事件」。`selectTrigger: 'dblClick'` 时第一下只发 `action.type: 'click'`，第二下才应用选中并带 `double: true` |
-| `onClusterClick` | `GisViewClusterClickPayload` | 点中多成员聚合圆：带 `id` / `count` / `pointIndexes` / `pointIds` / `bounds` / `radius` / `coordinate` / `screen` / `selection` / `action`（`action.type` 恒为 `clusterClick`、`action.target` 为 `cluster`）。这一条**不会同时发 `onClick`**，也不会改动选中集；聚合圆内部的原始节点不参与普通点击 |
+| `onSelect` | `GisViewSelectPayload \| null` | 选中操作回调：回答「这一下选了什么」。真实单击 / Ctrl / `multiSelect` 取反 / 框选 / `selectAt()` 每次成功操作都发（清空与「取反取没了」的载荷是 `null`）；`selectFeatures()` / `deselect()` / `focusOn({ select })` 等按引用接口只在选中集实际变化时发。载荷带 `items` / `box` / `originalEvent` / `mode`；单通道时顶层还有 `channelId` / `channelIndex` / `channel` / `groupId` / `groupIndex` / `group` / `groups` / `lineIndexes` / `lineIds`，多通道看 `channelContexts`。`items[]` 里的回线不挂任何通道字段，归属统一从外层映射或 `getLineChannel()` 取 |
+| `onClick` | `GisViewClickPayload \| null` | 单击要素或空白处（空白处为 `null`）：命中数据读 `type` / `index` / `item` / `screen` / `coordinate`，`selected` / `wasSelected` 是点完之后 / 点之前的选中态快照；按键、修饰键与指针位置读 `originalEvent`，整份选中集读数用 `view.getSelectionInfo()`（回调里就是 `payload.item` 所在视图的那一份）。另有 `action`（`type` 是 `select` / `toggleSelect` / `clearSelection` / `click`，`double` 说明这一下是不是双击里的第二下，`press` / `duration` / `longPress` 说明这一次按下想做什么、按了多久、算不算长按），见「指针事件」。`selectTrigger: 'dblClick'` 时第一下只发 `action.type: 'click'`，第二下才应用选中并带 `double: true` |
+| `onClusterClick` | `GisViewClusterClickPayload` | 点中多成员聚合圆：带 `id` / `count` / `pointIndexes` / `pointIds` / `bounds` / `radius` / `coordinate` / `screen` / `originalEvent` / `action`（`action.type` 恒为 `clusterClick`、`action.target` 为 `cluster`）。这一条**不会同时发 `onClick`**，也不会改动选中集；聚合圆内部的原始节点不参与普通点击。选中集读数用 `getSelectionInfo()` |
 | `onDblClick` | `GisViewClickPayload \| null` | 双击要素或空白处（320ms / 6px 内连续两次单击）：`action.type` 是 `dblClick`、`action.double` 为 `true`。普通双击在两种 `selectTrigger` 下都会于第二下派发；`dblClick` 模式下选中 / 清空 / 多选取反也在这一下应用，`click` 模式下第一下已经应用过。`click` 模式的 Ctrl / `multiSelect` 取反快捷路保持原口径，不额外发 `onClick` / `onDblClick` |
-| `onPointerDown` | `GisViewPointerPayload` | 左键 / 中键 / 右键按下：命中的要素、`button` / `buttons` 与光标位置；`action.type` 是这一次按下的**意图**（`dragPoint` / `dragWaypoint` / `boxSelect` / `pan` / `copy` / `channelDraft` / `contextMenu`…），`action.target` 说明点的是什么、`action.data` 直接给到那份数据，见「指针事件」 |
+| `onPointerDown` | `GisViewPointerPayload` | 左键 / 中键 / 右键按下：命中的要素与光标位置在载荷顶层；`action.type` 是这一次按下的**意图**（`dragPoint` / `dragWaypoint` / `boxSelect` / `pan` / `copy` / `channelDraft` / `contextMenu`…），`action.target` 说明点的是什么。点 / 线读 `item`，通道回线读 `channel` / `channelContext`，鼠标键、修饰键与 clientX / clientY 读 `originalEvent`，见「指针事件」 |
 | `onPointerUp` | `GisViewPointerPayload` | 左键 / 中键 / 右键抬起，与 `onPointerDown` 成对：`action.type` 是**刚做完的那件事**（拖过就是 `dragPoint` / `dragWaypoint` / `boxSelect` / `pan`，没拖就是 `click`），`action.moved` 说明这一次是拖还是点，另带 `action.press`（按下时的意图）/ `duration`（按了多久）/ `longPress`（长按） |
 | `onContextMenu` | `GisViewPointerPayload` | 每一次右键：点、线、通道、空白都只发这一条（要素信息在载荷里）；`action.type` 固定是 `contextMenu`、`action.target` 说明点的是点 / 线 / 通道 / 空白。命中通道回线时，同一载荷另带 `channelContext`（几组 / 当前哪组 / 可用交互），不再有单独的通道右键回调。要自己弹菜单就在回调里渲染。**右键回调缺省关**（`contextMenu` / `interactive` 都没写时组件不接右键），写 `interactive: true` / `contextMenu: true` 或 `features: 'view'` 才发；接住右键时系统菜单默认已被收掉（`preventContextMenu` 缺省 `true`），想看系统菜单写 `preventContextMenu: false` |
 | `onCascadeHighlight` | `GisViewCascadeHighlightInfo \| null` | 点击级联高亮变了：载荷带来源 `origin`（节点 / 线路 / 通道回线）、范围 `scope` 与亮着的 `points` / `lines` / `pointIndexes` / `lineIndexes`，与 `getCascadeHighlight()` 同一份；点空白或关掉开关时是 `null`。这条高亮不改选中集，事件总线名为 `cascadeHighlight` |
-| `onHover` | `GisViewHoverPayload \| null` | 悬停要素变化（空白处 / 移出画布是 `null`）：与拾取结果同一份读数（`type` / `index` / `item` + 通道字段，另有光标位置 `x` / `y` / `world` / `clientX` / `clientY`、选中集 `selection` 与 `lngLat`）+ `action`（`type` 恒为 `hover`、`target` 说明停在什么上面、`button` 是 `none`、`modifiers` 是当下的修饰键）；程序化悬停 `hoverAt()` 也走同一条 |
+| `onHover` | `GisViewHoverPayload \| null` | 悬停要素变化（空白处 / 移出画布是 `null`）：与拾取结果同一份读数（`type` / `index` / `item` + 通道字段，另有光标位置 `x` / `y` / `world` 与 `lngLat`）+ `action`（`type` 恒为 `hover`、`target` 说明停在什么上面）；指针正好停在最近一次指针事件上时 `originalEvent` 是那一次事件，按键、修饰键与 clientX / clientY 从它读。选中集总读数用 `getSelectionInfo()`；程序化悬停 `hoverAt()` 也走同一条 |
 | `onFilter` | `GisViewFilterResult` | 筛选完成（含 Worker 异步返回）：隐藏的点 / 线下标、剩余可见数量、是否用了 Worker 与计算耗时。`filter.mode: 'remove'` 时删除完成后只发最终一次，`hiddenPoints` / `hiddenLines` 为空 |
 | `onCursor` | `[number, number] \| null` | 光标世界坐标，移出画布时为 `null` |
 | `onPointer` | `GisViewPointerState` | 光标每次移动（含移出画布）都发：`{ inside, screen, world, lngLat }`，屏幕坐标是画布 CSS 像素、`lngLat` 要有 GeoJSON 背景才有；`getPointer()` 随时能读同一份，移出时 `inside: false` |
 | `onPointDrag` | `GisViewPointDragPayload` | 拖拽点：`phase` 为 `start` / `drag` / `end`，载荷带最新坐标、本次移动的全部节点 `points` 与跟随移动的线路 `lines` |
-| `onPointCopy` | `GisViewPointCopyPayload \| GisViewBatchCopyPayload` | 复制节点：`phase` 为 `start` / `move` / `commit` / `end` / `cancel`（复制到剪贴板另有 `clipboard`，批量复制 / 整组粘贴是 `batch`），`commit` 阶段可以 `payload.cancel()` 取消、`payload.update()` / `setItem()` 改数据；`clipboard` 载荷带整组 `sources` / `items` / `lines` / `channels` / `count` / `anchor`，`batch` 载荷另带 `indexes` / `lineSources` / `channelSources` / `revert()`，见「节点复制」 |
+| `onPointCopy` | `GisViewPointCopyPayload \| GisViewBatchCopyPayload` | 复制节点：`phase` 为 `start` / `move` / `commit` / `end` / `cancel`（复制到剪贴板另有 `clipboard`，批量复制 / 整组粘贴是 `batch`），`commit` 阶段可以 `payload.cancel()` 取消、`payload.update()` 改数据；落点与最新节点都读 `payload.item`（批量看 `items[0]`），不再另挂 `point` / `coordinate`。`clipboard` 载荷带整组 `sources` / `items` / `lines` / `channels` / `count` / `anchor`，`batch` 载荷另带 `indexes` / `lineSources` / `channelSources` / `revert()`，见「节点复制」 |
 | `onPointMerge` | `GisViewPointMergePayload \| GisViewMergeResult \| GisViewMergeFailure \| GisViewMergeSelectedPayload` | 合并节点：拖到另一个节点上时先发 `pending`（组件不弹任何界面，在回调里调 `payload.confirm()` / `cancel()` 裁决，或存下来自己接界面），之后发 `confirm`（载荷里的 `item` 是合并结果，可改 / 可取消）、`cancel`，数据并完 / 并失败再发一条 `merge`（`ok: true` / `ok: false`）；拖拽入口的载荷带 `trigger`（`'collision'` / `'center'`），说明这一次按哪种时机命中；框选 / 多选之后调 `mergeSelectedPoints()` 时**逐对发 `merge`**，收尾再发一条 `phase: 'mergeSelected'` 的汇总（`merged` 逐对列出、`skipped` 说明谁没并进去），见「节点合并」 |
 | `onRemove` | `GisViewRemovePayload` | 删除请求（Delete 键 / `requestRemove()`）：`pending` 时给一份载荷说明要删什么、连带什么、能按哪些范围删（`points` / `lines` / `waypoints` / `groups` / `channels` / `actions` / `counts`），确认之后发 `phase: 'remove'`（`result` 是结果）、取消发 `phase: 'cancel'`；组件不弹任何界面，弹不弹、怎么弹都由使用方决定（在回调里调 `payload.confirm(scope)` / `payload.cancel()`，或存下来自己接界面），见「删除（remove）」 |
 | `onWaypointChange` | `GisViewWaypointPayload` | 拐点新增 / 选中 / 删除与拖动，`phase` 为 `add` / `select` / `remove` 或拖动时的 `start` / `move` / `end`，载荷带最新线路数据与所属集合的 `group_id`；通道内的回线共用骨架，载荷是**被操作的那条回线**的推导结果。同步后端只接改变数据的 `add` / `remove` / `end`，并用 `getChannelGroupWaypoints().path` 提交整份骨架，见「通道与多回线」 |
@@ -30,7 +30,7 @@
 | `onChannelGroupChange` | `GisViewChannelGroupChangePayload` | 分组变化：拆分 / 合并 / 挪线 / 新建组（`action.type` 为 `splitGroups` / `mergeGroups` / `moveLine` / `addGroup`）与整份声明跟着补丁换（`setGroups`，`updateChannel` 写 `groups` / `lineIds`）；`action` 带这一笔的 `groupId` / `groupIds` / `lineIds`（`updateLine` 顺带挪组时 `action.via` 为 `'updateLine'`），`item` / `groups` 是与 `dataChange('channelGroups')` 同一份的最新读数。同步后端时用 `getChannelGroups(channelId)` 提交整份声明，不按 action 猜 delta，见「通道分组」 |
 | `onLabelDrag` | `GisViewLabelDragPayload` | 标签被拖走（`draggable`）：`phase` 为 `start` / `move` / `end`，载荷带 `kind`（`point` / `line`）、`index` / `id` / `item`、当前偏移 `offset`、起手时的 `startOffset` 与本次位移 `delta`（CSS 像素），见「标签的拖动与编辑」 |
 | `onLabelClick` | `GisViewLabelClickPayload` | 点了一下标签（`editable`，位移小于 3 px 才算点选）：载荷带 `kind` / `index` / `id` / `item`、当前 `offset` 与这一条的状态读数 `state`，使用方按它选中这一条 |
-| `onLabelContextMenu` | `GisViewLabelPointerPayload` | 在标签上按右键（`draggable` / `editable` 任开一个）：载荷与 `onLabelClick` 同一份读数，另带 `clientX` / `clientY`（菜单按它定位）与原始 `contextmenu` 事件；系统菜单按 `preventContextMenu` 收（缺省收），要弹自己的菜单就接这一条 |
+| `onLabelContextMenu` | `GisViewLabelPointerPayload` | 在标签上按右键（`draggable` / `editable` 任开一个）：载荷与 `onLabelClick` 同一份读数，菜单定位与按键读 `payload.originalEvent.clientX` / `clientY`；系统菜单按 `preventContextMenu` 收（缺省收），要弹自己的菜单就接这一条 |
 | `onLabelDblClick` | `GisViewLabelPointerPayload` | 双击标签（开关同上）：载荷与 `onLabelContextMenu` 一致（原始事件是 `dblclick`），用它开自己的编辑框 |
 | `onLabelChange` | `GisViewLabelChangePayload` | 标签状态变了：`action` 为 `update`（`updateLabel`）/ `reset`（`resetLabel`）/ `resetAll`（`resetLabels`）/ `add`（`addLabel`）/ `remove`（`removeLabel`）/ `restore`（`setLabelStates`），批量的三条各发 `addAll` / `updateAll` / `removeAll`；载荷带 `kind` / `index` / `id` 与 `patch` / `state` / `removed`，批量那三条另带 `count` 与 `added` / `updated` / `items` / `skipped`；面板按它回显 |
 | `onCameraChange` | `GisViewCamera` | 平移或缩放后触发 |
@@ -108,19 +108,24 @@ const view = createGisView('#map', {
 | `selectTrigger: 'dblClick'` 的第二下 | `onClick → onSelect → onSelectChange`（有变化时）`→ onDblClick` |
 
 `onSelect` 与 `onSelectChange` 带同一份通道上下文：选中集只涉及**一条通道**时，载荷顶层平铺
-`channelId` / `channelIndex` / `channel` / `groupId` / `groupIndex` / `group` / `groups`；`group` 是当前组
-（真实单击 / `selectAt` 是命中的那一组，框选与按引用接口是选中集里第一条通道回线所在的组），`groups`
-是整条通道的全部分组。选中集涉及**多条通道**时顶层不再摊平，改看 `channelContexts`（每项带这组字段与
-本次选中的 `lineIndexes` / `lineIds`）。单通道不会再额外造一份 `channelContexts`。两个事件共享同一批
-`items` 与分组数组引用，不会深拷贝；`items[]` 里每条回线只保留标量归属字段，需要分组读数从顶层
-或 `channelContexts` 查，不再给每条回线重复挂 `group` / `groups`。纯节点或空选中没有这些通道字段。
+`channelId` / `channelIndex` / `channel` / `groupId` / `groupIndex` / `group` / `groups` 与本次选中的
+`lineIndexes` / `lineIds`；`group` 是当前组（真实单击 / `selectAt` 是命中的那一组，框选与按引用接口是
+选中集里第一条通道回线所在的组），`groups` 是整条通道的全部分组。选中集涉及**多条通道**时顶层不再摊平，
+改看 `channelContexts`（每项带这组字段与本次选中的 `lineIndexes` / `lineIds`）。单通道不会再额外造一份
+`channelContexts`。两个事件共享同一批 `items`、分组对象与数组引用，不会深拷贝。
+
+`items[]` 里的通道回线**不再挂任何通道字段**（`channelId` / `channelIndex` / `channel` / `groupId` /
+`groupIndex` / `group` / `groups` / `lineIndexes` / `lineIds`）。要用 `items` 反查归属，按选中的线路下标
+查外层的 `lineIndexes` / `lineIds`，再对应顶层上下文或 `channelContexts`；只问一条线路时也可以直接调
+`getLineChannel(index)`。`groups[].lineIds` 是整组成员，外层 `lineIndexes` / `lineIds` 是本次选中子集，
+两者语义不同。纯节点或空选中没有这些通道字段。
 
 `cause` 取 `click`（指针点击）/ `boxSelect`（框选）/ `keyboard`（Esc 清空）/ `api`（接口调用）。
 
 `action` 是更细的一份判读（与指针事件同一套写法）：`action.type` 是 `select`（点中一个或接口选中）/
 `toggleSelect`（Ctrl 点击取反，取反取没了也是它）/ `boxSelect`（框选，没框到东西也是它）/
-`clearSelection`（点空白、Esc 或接口清空），`action.target` 是 `selection` / `empty`，`action.data` 就是
-这一批 `items`，`action.modifiers` 是这一次的修饰键。单击触发模式下，Ctrl 取反与框选这两条路**不经过 `onClick`**；
+`clearSelection`（点空白、Esc 或接口清空），`action.target` 是 `selection` / `empty`；这一批数据直接读载荷的
+`items`，修饰键读 `originalEvent`。单击触发模式下，Ctrl 取反与框选这两条路**不经过 `onClick`**；
 点空白仍会发 `onClick`（载荷为 `null`），顺序同样是 `onClick → onSelect → onSelectChange（有变化时）`。`selectTrigger: 'dblClick'`
 时第一下仍会发 `onClick`，第二下应用选中 / 取反 / 清空后按 `onClick → onSelect → onSelectChange（有变化时）→ onDblClick` 派发。
 要按操作分支的面板认这一个字段：
@@ -184,7 +189,7 @@ view.off('*')  // 不传 handler = 摘掉这个事件的全部订阅，返回摘
 | 约定 | 说明 |
 | --- | --- |
 | 事件名与回调一一对应 | `dataChange` 就是 `onDataChange`、`selectChange` 就是 `onSelectChange`，载荷完全同一份；`GisViewEventMap` 是事件名到载荷的类型表，`EVENT_NAMES` 是运行时的名字数组 |
-| 要 DOM 事件的三个 | `pointerDown` / `pointerUp` / `contextMenu` 的载荷是 `{ payload, event }`（与回调的两个参数一一对应），其余事件的载荷与回调相同 |
+| 指针类事件只有一个参数 | `pointerDown` / `pointerUp` / `contextMenu` 的回调收一份载荷，事件总线订阅时也是同一份直接载荷；原始 DOM 事件读 `payload.originalEvent`，不再额外包 `{ payload, event }` |
 | 回调抛错不扩散 | 订阅者抛错只走 `onError`：不打断其它订阅者，也不影响组件自己的流程 |
 | 高频事件不白算 | 组件内部按「有没有人订阅」短路（`count(name) \|\| count('*')`）：没人听的时候不构造载荷，`pointer` / `hover` / `render` 这些每帧级别的事件也可以直接订阅 |
 | 订阅时机 | 创建时的 `ready` 与首次 `dataChange` 发生在 `createGisView` 返回之前，这两条要在 options 里写回调（`onReady` 等） |

package/docs/manual/06-/346/225/260/346/215/256/344/270/216/345/234/272/346/231/257/346/233/264/346/226/260.md

@@ -44,7 +44,7 @@ view.updateData({ channels: nextChannels })
 view.addPoint({ id: 's-1', x: 116.4, y: 39.9, name: '甲站' })
 view.addPoints(stations)                     // 返回 { ok, count, indexes, items }
 
-// 通道（新签名：通道信息 + 线路数组 line_data，见「新增通道」；旧写法 { from, to, circuits } 照样认）
+// 通道（通道信息 + 线路数组 lineData，见「新增通道」）
 view.addChannel({ from: 's-1', to: 's-2', name: '甲通道' }, [{ id: 'c-1' }, { id: 'c-2' }])
 view.addChannels(channelDeclarations)        // 批量版：逐条落地，只重排一次、只记一步历史、只发一条 addChannels
 ```
@@ -52,7 +52,7 @@ view.addChannels(channelDeclarations)        // 批量版：逐条落地，只
 两条新增路线的分工：`addPoint` / `addPoints` / `addLines` 追加的是「现成的数据对象」；
 `addChannel` / `addChannels` / `addLine` 是按两端节点新建（通道声明一起改）。`addChannels` 的返回里
 `results` 与传入顺序一一对应（失败的条目也在里面，按各自的 `reason` 读），`lineIds` / `channelIds`
-只列成功那几条；批量落地后新回线整批选中，与单条 `addChannel` 的手感一致。十万级数据下批量新增只付
+只列成功那几条；新增类方法缺省都不改选中集，需要选中时显式传 `options.select: true`。十万级数据下批量新增只付
 一次场景重排，比逐条 `addChannel` 少几十上百次整份重建。新增类方法的完整清单（节点 / 线路 / 通道 / **分组** / **拐点**）与返回口径见「按方法新增要素」。
 
 补点 / 补线的代价与「场景铺到哪一步」无关：发散渲染还没铺完时又来一批（「刚删完紧接着补」这种最常见的
@@ -321,12 +321,11 @@ const geometryOnly = view.getChangedLines({ reasons: ['path'] })
 | --- | --- | --- | --- |
 | 节点（一条 / 一批） | `addPoint(item, options?)` / `addPoints(items, options?)` | 与数据里的 `points[]` 同一份字段（`id` / `x` / `y` / 样式 / 业务字段） | 单条是 `{ ok, count, indexes, items, index, item }`、批量去掉 `index` / `item`；追加进 `points`，走引擎的增量追加（见「动态换数据与加载完成」） |
 | 线路（现成数据，一条 / 一批） | `addLines(items, options?)` | 与数据里的 `lines[]` 同一份字段（`id` / `from` / `to` / `path`…），**不挂通道** | `{ ok, count, indexes, items }`；追加进 `lines` |
-| 独立线路（按两端节点新建） | `addLine(input, lineData?)` | `from` / `to` 必填，`circuits` 一次几回，`lineProps` / `lineId` / `name`…；第二段与 `addChannel` 的线路数组同一份写法（每项可以只写一个 id：裸字符串 / 数字按 `{ id }` 收） | 与 `addChannel` 同一份结果（`kind: 'line'`），落地后新回线自动选中 |
-| 通道（新签名，只新建） | `addChannel(spec, lineData?, group?)` | 第一段 `{ from, to, name?, id?, …通道字段 }`；第二段线路数组 line_data（一条或一批，字符串 / 数字按 id 认，对象浅拷）—— **按每项 id 建 `lineIds`**；第三段可选分组信息 `{ id?, lineIds?, path? }`（单个 / 一组一个）；两个节点之间已有通道时整条失败（**第二段 / 第三段显式给了**才算新签名，只写 `{ from, to }` 的照旧按方案表分流），见「新增通道」 | 与下面旧写法同一份结果（`channelLineIds` 是落地后通道的完整成员表）；通道声明与回线一起落地，自动选中 |
-| 通道（旧写法：按方案表） | `addChannel(input)` | `from` / `to` 必填；`circuits`、`resolution`（`'newChannel'` / `{ type: 'newGroup' }` / `{ type: 'joinGroup', groupId }`）或顶层简写 `channelId` / `groupId` / `groupIndex`（并进已有通道，见「新增通道」）、`channelProps` / `lineProps` / `linePropsByMember` / `name` / `path` | `{ ok, reason?, plan, resolution, kind, circuits, line, lineId, lineIds, lines, lineIndex, channelId, groupId, channelLineIds, channelIndex }`（`channelLineIds` 是落地后通道的完整成员表 —— 并进已有通道时就是更新过的 `lineIds`）；通道声明与回线一起落地，自动选中 |
-| 通道（已有通道：新加一组 / 并进某一组） | `addChannelGroupLines(channelId, lineData, groupInfo?)` / `joinChannelGroupLines(channelId, groupId, lineData)` | 第二段都是线路数组 line_data（按每项 id 建回线）；新加一组可用 `groupInfo` 给组 id 与骨架，并进某一组用 `groupId`（认分组 id 也认序号，从 0 起，不传就挑第一个还能并的） | 与 `addChannel` 同一份结果；`channelLineIds` 是更新后的完整成员表 |
-| 通道（一批） | `addChannels(items, options?)` | 每一项与 `addChannel` 同一套写法 | `{ ok, count, results, lineIds, channelIds, items }`：`results` 与传入顺序一一对应，失败的在各自 `reason` 里；只重排一次、只记一步历史 |
-| 通道（已有通道：一次加多组） | `addChannelGroups(channelId, groups, options?)` | `groups` 每项 `{ id?, path?, lineData \| lines \| lineItems }`，线路数据与 `addChannel` 第二段同一份写法 | `{ ok, count, results, lineIds, groupIds, groups }`：逐组落地但只记一步历史、只发一条 `addChannelGroups` 数据变更；`options.emit: false` 只落地不通知 |
+| 独立线路（按两端节点新建） | `addLine(spec, lineData?, options?)` | `from` / `to` 必填；`spec` 可写 `name?` / `id?` / `lineProps?` / `path?` / `routing?` / `lineData?`，第二段 `lineData` 一条或一批（每项可以只写一个 id：裸字符串 / 数字按 `{ id }` 收）；`options?: { emit?, select? }` | 与 `addChannel` 同一份结果结构（`kind: 'line'`）；缺省不改变选中集，`select: true` 才选中新回线 |
+| 通道（只新建） | `addChannel(spec, lineData?, group?, options?)` | 第一段 `{ from, to, name?, id?, channelProps?, path?, routing?, lineData?, group? }`；第二段线路数组 lineData（一条或一批）—— **按每项 id 建 `lineIds`**；第三段可选分组信息 `{ id?, lineIds?, path? }`；`options?: { emit?, select? }`。两个节点之间已有通道时整条失败，见「新增通道」 | `{ ok, reason?, plan, resolution, kind, circuits, line, lineId, lineIds, lines, lineIndex, channelId, groupId, channelLineIds, channelIndex }`；缺省不改变选中集，`select: true` 才选中新回线 |
+| 通道（已有通道：新加一组 / 并进某一组） | `addChannelGroupLines(channelId, lineData?, groupInfo?, options?)` / `joinChannelGroupLines(channelId, groupId?, lineData?, options?)` | 第二段都是线路数组 lineData（按每项 id 建回线）；新加一组可用 `groupInfo` 给组 id 与骨架，并进某一组用 `groupId`（认分组 id 也认序号，从 0 起，不传就挑第一个还能并的）；`options?: { emit?, select? }` | 与 `addChannel` 同一份结果；`channelLineIds` 是更新后的完整成员表；缺省不选中，`select: true` 才选中新回线 |
+| 通道（一批） | `addChannels(items, options?)` | 每一项与 `addChannel` 第一段同一套写法，可在项内写 `lineData` / `group`；`options?: { emit?, select? }` | `{ ok, count, results, lineIds, channelIds, items }`：`results` 与传入顺序一一对应，失败的在各自 `reason` 里；只重排一次、只记一步历史；缺省不选中，`select: true` 才选中全部成功的新回线 |
+| 通道（已有通道：一次加多组） | `addChannelGroups(channelId, groups, options?)` | `groups` 每项 `{ id?, groupId?, path?, lineData? \| lines? }`，线路数据与 `addChannel` 第二段同一份写法；`lineItems` 已移除；`options?: { emit?, label?, select? }` | `{ ok, count, results, lineIds, groupIds, groups }`：逐组落地但只记一步历史、只发一条 `addChannelGroups` 数据变更；缺省不选中，`select: true` 才选中新回线 |
 | 分组（把回线拆成新组） | `addChannelGroup(channelId, lineIds, options?)` | 要拆出去的回线 `lineIds`；`options.path` 给新组骨架（缺省沿用来源组、`path: []` 要一条直连）；`options.id` 指定组 id，撞上这条通道已有分组时拒绝（不会写出两个同名分组） | `{ ok, reason, channelId, lineIds, groupId, groupIndex, groups, skipped }`；到组数 / 回数上限时 `ok: false` + `reason`，显式 `id` 重名同样 `ok: false` + `reason` |
 | 分组（整份重拆 / 合并 / 单条改派） | `splitChannelGroups(channelId, [{ id, lineIds, path? }…])` / `mergeChannelGroups(channelId, groupIds, targetGroupId)` / `moveChannelLine(channelId, lineId, { type: 'newGroup' } \| { type: 'joinGroup', groupId })` | 前两个整份换分组声明（第一个组沿用当前拐点）；`moveChannelLine` 挪一条回线，也接受 `'newGroup'` 或直接给分组 id | 都把最终声明写回数据副本、记一条「通道分组」历史；`moveChannelLine` 返回 `{ ok, channelId, lineId, groupId, groupIndex, groups }` |
 | 分组（删一个：把一组并进相邻组） | `removeChannelGroup(channelId, groupId, options?)` | `channelId` / `groupId` 目标通道与要删的组；`options.targetGroupId` 指名并到哪一组（缺省前一组，第一组并后一组） | `{ ok, reason, channelId, groupId, targetGroupId, lineIds, groups }`；骨架 / 拐点沿用目标组，并完只剩一组时声明回到「整条通道一组」；单组通道 `ok: false`（删整条用 `removeChannel`） |
@@ -352,7 +351,7 @@ const added = view.addChannel({ from: 's-1', to: 's-2', path: [[116.7, 40.0]] },
 console.log(added.channelId, added.lineIds, added.groupId)
 // 多条通道一次建：每项与 addChannel 同一套写法，只重排一次、只记一步历史
 const many = view.addChannels([
-  { from: 's-2', to: 's-3', lineItems: [{ id: 'line-c' }, { id: 'line-d' }] },
+  { from: 's-2', to: 's-3', lineData: [{ id: 'line-c' }, { id: 'line-d' }] },
   { from: 's-3', to: 's-4', name: '三号通道', lineData: [{ id: 'line-e' }] }
 ])
 
@@ -380,7 +379,7 @@ view.getParallelGroups()
 ```
 
 四条口径：
-- **新增时的线路 / 通道 `path` 口径**：`addLine` / `addChannel(..., kind: 'line')` 的 `routing: 'orthogonal'` 会自动补一个先横后纵的 90° 拐点；输入里的 `path` 一律按**中间拐点**解释，独立线路落地成 `[起点, ...中间拐点, 终点]` 的完整 `path`，新建通道 / 分组只把中间拐点写进骨架。`beginAddChannel` 草稿用同一份解析，预览与落地一致。
+- **新增时的线路 / 通道 `path` 口径**：`addLine` / `addChannel` 的 `routing: 'orthogonal'` 会自动补一个先横后纵的 90° 拐点；输入里的 `path` 一律按**中间拐点**解释，独立线路落地成 `[起点, ...中间拐点, 终点]` 的完整 `path`，新建通道 / 分组只把中间拐点写进骨架。`beginAddChannel` / `beginAddLine` 草稿用同一份解析，预览与落地一致。
 
 - **返回里带下标**：`addPoint` / `addPoints` / `addLines` 的 `indexes` 是追加后在数组里的位置（老数据一个都不动），后续 `updatePoint` / `updateLine` 直接拿它当 id 用；`addChannel` 给的是 `lineIndex` / `channelIndex` / `groupId`。
 - **事件与历史**：新增发 `dataChange`（`addPoints` / `addLines` / `addLine` / `addChannel` / `addChannels` / `addChannelGroups`），分组改动另发 `channelGroups`（`onChannelGroupChange`，见「通道分组」）；`addPoints` / `addLines` / `addChannels` / `addChannelGroups` / `addWaypoints` 的批量写法都只记一步历史、只发一条数据变更，`options.emit: false` 只落地不通知。开着历史时每一步都可撤销。