gis-view-webgl2 0.1.2 → 0.1.4

package/docs/steps/selftest-features.html

@@ -1592,6 +1592,293 @@
 					cwView.destroy()
 					cwHost.remove()
 
+					/* 问题 3（本轮）：setFilter 只让节点不画，不该改变仍显示的通道宽度 ——
+					   从前锚点被筛掉就不在 pointByIndex 里，通道退回默认宽度；只筛掉一端时还会改按另一端尺寸算 */
+					const cwfHost = document.createElement('div')
+					cwfHost.style.cssText = 'width:320px;height:200px'
+					document.body.appendChild(cwfHost)
+					const cwfView = createGisView(cwfHost, {
+						points: [
+							{ id: 'cwf-a', x: -30, y: 0, size: 8, symbol: 'square', level: 1 },
+							{ id: 'cwf-b', x: 30, y: 0, size: 24, symbol: 'square', level: 2 }
+						],
+						lines: [
+							{ id: 'cwf-l1', from: 'cwf-a', to: 'cwf-b', width: 1 },
+							{ id: 'cwf-l2', from: 'cwf-a', to: 'cwf-b', width: 1 }
+						],
+						channels: [{ id: 'cwf-ch', from: 'cwf-a', to: 'cwf-b', lineIds: ['cwf-l1', 'cwf-l2'], tangentInset: 0 }],
+						initialView: { center: [0, 0], scale: 1 },
+						showGrid: false
+					})
+					await settle(150)
+					const cwfGap = () => {
+						const tops = cwfView.listLines().filter(line => String(line.item.id).startsWith('cwf-')).map(line => line.path[0][1])
+						return tops.length === 2 ? Math.abs(tops[0] - tops[1]) : 0
+					}
+					const cwfBase = cwfGap()
+					check('筛选前通道宽度基线：两端取小的尺寸 8（tangentInset: 0）', Math.abs(cwfBase - 8) < 0.01, `间距 ${cwfBase}`)
+					cwfView.setFilter({ points: { level: 2 }, cascade: false })
+					await settle(100)
+					check('setFilter 只筛掉小尺寸锚点：回线仍按两端较小值取宽，不跳到大节点尺寸', Math.abs(cwfGap() - cwfBase) < 0.01, `${cwfBase} → ${cwfGap()}`)
+					cwfView.setFilter({ points: { level: 0 }, cascade: false })
+					await settle(100)
+					check('setFilter 把两端锚点都筛掉：通道回线仍显示，宽度不退到默认 channelWidth', cwfView.listLines().filter(line => String(line.item.id).startsWith('cwf-')).length === 2 && Math.abs(cwfGap() - cwfBase) < 0.01, `间距 ${cwfBase} → ${cwfGap()}`)
+					cwfView.setFilter(null)
+					await settle(100)
+					check('清除筛选：通道宽度与筛选前完全一致', Math.abs(cwfGap() - cwfBase) < 0.01, `间距 ${cwfBase} → ${cwfGap()}`)
+					// 可见锚点若按选中 / 悬停后的尺寸算，筛掉另一端时它会变成唯一锚点，通道宽度就会跳
+					cwfView.updateOptions({ pointSelectStyle: { sizeScale: 2 } })
+					cwfView.selectFeatures('cwf-b')
+					await settle(80)
+					cwfView.setFilter({ points: { level: 1 }, cascade: false })
+					await settle(100)
+					check('筛选叠加选中样式：锚点宽度仍按中性尺寸取，不随选中放大而跳', Math.abs(cwfGap() - cwfBase) < 0.01, `间距 ${cwfBase} → ${cwfGap()}`)
+					cwfView.setFilter({ points: { level: 0 }, cascade: false })
+					await settle(100)
+					check('选中状态下把两端都筛掉：通道宽度仍保持原值', Math.abs(cwfGap() - cwfBase) < 0.01, `间距 ${cwfBase} → ${cwfGap()}`)
+					cwfView.setFilter(null)
+					await settle(80)
+					cwfView.destroy()
+					cwfHost.remove()
+
+					/* 分组通道 + 成员回线被筛：筛选只影响可见性，保留下来的回线仍按原来的车道与宽度走 */
+					const gfwHost = document.createElement('div')
+					gfwHost.style.cssText = 'width:340px;height:220px'
+					document.body.appendChild(gfwHost)
+					const gfwView = createGisView(gfwHost, {
+						points: [
+							{ id: 'gfw-a', x: -30, y: 0, size: 8, symbol: 'square', level: 1 },
+							{ id: 'gfw-b', x: 30, y: 0, size: 24, symbol: 'square', level: 2 }
+						],
+						lines: [
+							{ id: 'gfw-l1', from: 'gfw-a', to: 'gfw-b', color: '#ff0000' },
+							{ id: 'gfw-l2', from: 'gfw-a', to: 'gfw-b', color: '#ff0000' },
+							{ id: 'gfw-l3', from: 'gfw-a', to: 'gfw-b', color: '#0000ff' },
+							{ id: 'gfw-l4', from: 'gfw-a', to: 'gfw-b', color: '#0000ff' }
+						],
+						channels: [{
+							id: 'gfw-ch', from: 'gfw-a', to: 'gfw-b', lineIds: ['gfw-l1', 'gfw-l2', 'gfw-l3', 'gfw-l4'],
+							tangentInset: 0, offsetMode: 'inset', inset: 0.1,
+							groups: [
+								{ id: 'gfw-top', lineIds: ['gfw-l1', 'gfw-l2'], path: [[0, 24]] },
+								{ id: 'gfw-bot', lineIds: ['gfw-l3', 'gfw-l4'], path: [[0, -24]] }
+							]
+						}],
+						initialView: { center: [0, 0], scale: 1 },
+						showGrid: false
+					})
+					await settle(150)
+					const gfwPaths = () => Object.fromEntries(gfwView.listLines()
+						.filter(line => String(line.item.id).startsWith('gfw-'))
+						.map(line => [String(line.item.id), JSON.stringify(line.path)]))
+					const gfwBase = gfwPaths()
+					const gfwGeometry = () => JSON.stringify({
+						channels: gfwView.getChannels(),
+						groups: gfwView.getChannelGroups('gfw-ch')
+					})
+					const gfwGeometryBase = gfwGeometry()
+					gfwView.setFilter({ points: { level: 0 }, cascade: false })
+					await settle(100)
+					const gfwNoPoints = gfwPaths()
+					check('分组通道：两端节点被筛掉时四条回线仍在原车道', Object.keys(gfwNoPoints).length === 4 && Object.keys(gfwBase).every(id => gfwNoPoints[id] === gfwBase[id]), JSON.stringify({ base: gfwBase, current: gfwNoPoints }))
+					gfwView.setFilter({ lines: { color: '#ff0000' }, cascade: false })
+					await settle(100)
+					const gfwFiltered = gfwPaths()
+					check('分组通道：筛掉一半成员回线后，保留回线的几何与筛选前完全一致', Object.keys(gfwFiltered).length === 2 && gfwFiltered['gfw-l1'] === gfwBase['gfw-l1'] && gfwFiltered['gfw-l2'] === gfwBase['gfw-l2'], JSON.stringify({ base: [gfwBase['gfw-l1'], gfwBase['gfw-l2']], current: gfwFiltered }))
+					gfwView.setFilter(null)
+					await settle(80)
+					const gfwRestored = gfwPaths()
+					check('分组通道：清除筛选后四条回线逐顶点回到筛选前的几何', Object.keys(gfwRestored).length === 4 && Object.keys(gfwBase).every(id => gfwRestored[id] === gfwBase[id]), JSON.stringify({ base: gfwBase, current: gfwRestored }))
+					gfwView.setFilter({ lines: { color: '#ff0000' }, cascade: false })
+					await settle(80)
+					gfwView.setFilter(null)
+					await settle(80)
+					const gfwRestoredAgain = gfwPaths()
+					check('分组通道：连续隐藏 / 恢复成员回线后仍按原车道与骨架绘制', Object.keys(gfwRestoredAgain).length === 4 && Object.keys(gfwBase).every(id => gfwRestoredAgain[id] === gfwBase[id]), JSON.stringify({ base: gfwBase, current: gfwRestoredAgain }))
+					// 默认 binding 级联会把两端节点、绑定回线与整条通道一起收起；恢复时引擎必须按当前锚点重新接上，
+					// 不能沿用「隐藏期间没有骨架」的通道状态。这里连通道 / 分组读数一起对，避免只看 listLines 漏掉串线。
+					gfwView.setFilter({ points: { level: 0 } })
+					await settle(100)
+					check('分组通道：默认 binding 级联筛掉两端节点时回线一起收起', gfwView.listLines().filter(line => String(line.item.id).startsWith('gfw-')).length === 0, JSON.stringify({ lines: gfwPaths() }))
+					gfwView.setFilter(null)
+					await settle(100)
+					check('分组通道：默认级联恢复后回线、通道骨架与分组骨架逐项回到原值', Object.keys(gfwPaths()).length === 4 && Object.keys(gfwBase).every(id => gfwPaths()[id] === gfwBase[id]) && gfwGeometry() === gfwGeometryBase, JSON.stringify({ base: gfwGeometryBase, current: gfwGeometry() }))
+					gfwView.hideFeatures('point', ['gfw-a', 'gfw-b'])
+					await settle(100)
+					gfwView.showFeatures('point', ['gfw-a', 'gfw-b'])
+					await settle(100)
+					check('分组通道：visible 隐藏 / 显示两端节点后几何仍逐项回到原值', Object.keys(gfwPaths()).length === 4 && Object.keys(gfwBase).every(id => gfwPaths()[id] === gfwBase[id]) && gfwGeometry() === gfwGeometryBase, JSON.stringify({ base: gfwGeometryBase, current: gfwGeometry() }))
+					gfwView.destroy()
+					gfwHost.remove()
+
+					/* 焦点类型消歧 + 分组选中 + 拐点选中 */
+					const faHost = document.createElement('div')
+					faHost.style.cssText = 'width:420px;height:260px'
+					document.body.appendChild(faHost)
+					const faView = createGisView(faHost, {
+						points: [
+							{ id: 'same', x: 0, y: 0 },
+							{ id: 'fa-low-a', x: -50, y: -40 },
+							{ id: 'fa-low-b', x: 50, y: -40 },
+							{ id: 'fa-high-a', x: -50, y: 40 },
+							{ id: 'fa-high-b', x: 50, y: 40 }
+						],
+						lines: [
+							{ id: 'same', path: [[-100, 0], [-80, 0]] },
+							{ id: 'fa-l1', from: 'fa-low-a', to: 'fa-low-b' },
+							{ id: 'fa-l2', from: 'fa-low-a', to: 'fa-low-b' },
+							{ id: 'fa-l3', from: 'fa-high-a', to: 'fa-high-b' },
+							{ id: 'fa-l4', from: 'fa-high-a', to: 'fa-high-b' },
+							{ id: 'fa-around', path: [[0, 80], [50, 100], [100, 80]] }
+						],
+						channels: [
+							{ id: 'fa-low-ch', from: 'fa-low-a', to: 'fa-low-b', lineIds: ['fa-l1', 'fa-l2'], groups: [{ id: 'fa-low', lineIds: ['fa-l1', 'fa-l2'] }] },
+							{ id: 'fa-high-ch', from: 'fa-high-a', to: 'fa-high-b', lineIds: ['fa-l3', 'fa-l4'], groups: [{ id: 'fa-high', lineIds: ['fa-l3', 'fa-l4'] }] }
+						],
+						initialView: { center: [0, 0], scale: 1 },
+						waypointEditable: true,
+						showGrid: false
+					})
+					await settle(100)
+					faView.focusOn('same')
+					const faStringCenter = faView.getCamera().center
+					faView.focusOn({ type: 'line', id: 'same' })
+					const faLineCenter = faView.getCamera().center
+					faView.focusOn({ type: 'point', id: 'same' })
+					const faPointCenter = faView.getCamera().center
+					faView.focusOn({ type: 'channel', id: 'fa-low-ch' })
+					const faChannelCenter = faView.getCamera().center
+					faView.focusOn({ type: 'group', groupId: 'fa-high' })
+					const faHighCenter = faView.getCamera().center
+					faView.focusOn({ type: 'group', channelId: 'fa-low-ch', groupId: 'fa-low' })
+					const faLowCenter = faView.getCamera().center
+					check('focusOn：字符串同 id 先聚焦节点，显式 type 可聚焦同名线路', Math.abs(faStringCenter[0]) < 0.01 && Math.abs(faPointCenter[0]) < 0.01 && Math.abs(faLineCenter[0] + 90) < 0.01, JSON.stringify({ string: faStringCenter, point: faPointCenter, line: faLineCenter }))
+					check('focusOn：显式通道 / 分组类型按各自范围居中（groupId 唯一时可不写 channelId）', Math.abs(faChannelCenter[0]) < 0.01 && Math.abs(faHighCenter[1] - 40) < 0.01 && Math.abs(faLowCenter[1] + 40) < 0.01, JSON.stringify({ channel: faChannelCenter, high: faHighCenter, low: faLowCenter }))
+					faView.selectFeatures({ type: 'group', channelId: 'fa-low-ch', groupId: 'fa-low' })
+					const faSelectedGroup = faView.getSelections().filter(item => item.type === 'line').map(item => item.item.id).sort()
+					faView.selectFeatures({ type: 'group', groupId: 'fa-high' })
+					const faSelectedUnique = faView.getSelections().filter(item => item.type === 'line').map(item => item.item.id).sort()
+					check('selectFeatures：type=group 与唯一 groupId 都只选中该分组', faSelectedGroup.join(',') === 'fa-l1,fa-l2' && faSelectedUnique.join(',') === 'fa-l3,fa-l4', JSON.stringify({ low: faSelectedGroup, high: faSelectedUnique }))
+					faView.selectWaypoint('fa-around', 1)
+					const faWaypointSelected = faView.getWaypoints().some(item => item.itemId === undefined && item.lineIndex === 5 && item.pathIndex === 1 && item.selected)
+					const faWaypointLineSelected = faView.getSelections().some(item => item.type === 'line' && item.item.id === 'fa-around')
+					faView.selectFeatures('fa-around')
+					const faWaypointCleared = faView.getWaypoints().filter(item => item.lineIndex === 5).every(item => !item.selected)
+					check('selectWaypoint：按线路 + 下标选中拐点并带选线路，selectFeatures 会清掉拐点选中', faWaypointSelected && faWaypointLineSelected && faWaypointCleared, JSON.stringify({ selected: faWaypointSelected, line: faWaypointLineSelected, cleared: faWaypointCleared, all: faView.getWaypoints(), lines: faView.getData().lines }))
+					// search 也认 focusOn 的四种目标；分组命中可以直接交给 focusOn / selectFeatures
+					const faGroupSearch = faView.search({ keyword: 'fa-high', scope: 'group', limit: 10 })
+					const faGroupHit = faGroupSearch.groups[0]
+					faView.focusOn(faGroupHit)
+					const faGroupSearchCenter = faView.getCamera().center
+					faView.selectFeatures(faGroupHit)
+					const faGroupHitSelected = faView.getSelections().filter(item => item.type === 'line').map(item => item.item.id).sort()
+					const faDefaultGroupSearch = await faView.searchAsync({ keyword: 'fa-high', limit: 10 })
+					check('search：单数 group 范围返回分组命中，命中可直接 focusOn / selectFeatures', faGroupSearch.scope.length === 1 && faGroupSearch.scope[0] === 'groups' && faGroupHit?.kind === 'group' && faGroupHit.channelIndex === 1 && faGroupHit.groupId === 'fa-high' && faGroupHit.groupIndex === 0 && Math.abs(faGroupSearchCenter[1] - 40) < 0.01 && faGroupHitSelected.join(',') === 'fa-l3,fa-l4', JSON.stringify({ scope: faGroupSearch.scope, hit: faGroupHit, center: faGroupSearchCenter, selected: faGroupHitSelected }))
+					check('searchAsync：缺省范围包含 groups，Worker / 同步回落都带 groups 结果', faDefaultGroupSearch.groups.length === 1 && faDefaultGroupSearch.hits.some(hit => hit.kind === 'group' && hit.groupId === 'fa-high'), JSON.stringify({ scope: faDefaultGroupSearch.scope, groups: faDefaultGroupSearch.groups.length, worker: faDefaultGroupSearch.worker }))
+					// 线路 / 通道 / 分组都只在 zoom: true 时适配：与显式 zoomToBounds 的比例逐位一致，没有类型专属放大倍率
+					const faLineHit = faView.search({ keyword: 'fa-around', scope: 'line', limit: 1 }).lines[0]
+					const faChannelHit = faView.search({ keyword: 'fa-low-ch', scope: 'channel', limit: 1 }).channels[0]
+					const faFocusScales = [faLineHit, faChannelHit, faGroupHit].map((hit) => {
+						faView.zoomToBounds(hit.bounds)
+						const expected = faView.getCamera().scale
+						faView.focusOn(hit, { zoom: true })
+						return [expected, faView.getCamera().scale]
+					})
+					check('focusOn({ zoom: true })：线路 / 通道 / 分组适配后的比例与同一份 bounds 的 zoomToBounds 完全一致', faFocusScales.every(([expected, actual]) => Math.abs(expected - actual) < 1e-9), JSON.stringify(faFocusScales))
+					faView.destroy()
+					faHost.remove()
+
+					/* 筛选是隐藏、不是删除：选中的要素被筛掉时保留在选中集里，条件清空后原样恢复 */
+					const fsHost = document.createElement('div')
+					fsHost.style.cssText = 'width:320px;height:200px'
+					document.body.appendChild(fsHost)
+					const fsChanges = []
+					const fsView = createGisView(fsHost, {
+						points: [
+							{ id: 'fs-a', x: -30, y: 0, level: 0 },
+							{ id: 'fs-b', x: 30, y: 0, level: 1 }
+						],
+						lines: [{ id: 'fs-l1', from: 'fs-a', to: 'fs-b' }],
+						initialView: { center: [0, 0], scale: 1 },
+						showGrid: false,
+						onSelectChange: payload => fsChanges.push(payload)
+					})
+					await settle(100)
+					fsView.selectFeatures(['fs-a', 'fs-l1'])
+					const fsChangesBeforeFilter = fsChanges.length
+					fsView.setFilter({ points: { level: 1 }, cascade: false })
+					await settle(100)
+					const fsHiddenIds = fsView.getSelections().map(item => String(item.item.id)).sort().join(',')
+					const fsHiddenVisible = fsView.getVisibleData().points.some(point => point.id === 'fs-a')
+					const fsChangesAfterFilter = fsChanges.length
+					fsView.setFilter(null)
+					await settle(100)
+					const fsRestoredIds = fsView.getSelections().map(item => String(item.item.id)).sort().join(',')
+					check('setFilter 只隐藏要素：选中项保留，条件清空后仍选中且不额外发选中变更', fsHiddenIds === 'fs-a,fs-l1' && fsHiddenVisible === false && fsChangesAfterFilter === fsChangesBeforeFilter && fsRestoredIds === 'fs-a,fs-l1', JSON.stringify({ hidden: fsHiddenIds, visible: fsHiddenVisible, changes: [fsChangesBeforeFilter, fsChangesAfterFilter], restored: fsRestoredIds }))
+					fsView.destroy()
+					fsHost.remove()
+
+					/* lineFollowsNode: false：隐藏 / 筛选 / 删除只动节点，回线与通道停在最后坐标 */
+					const lfHost = document.createElement('div')
+					lfHost.style.cssText = 'width:360px;height:220px'
+					document.body.appendChild(lfHost)
+					const lfView = createGisView(lfHost, {
+						points: [
+							{ id: 'lf-a', x: -30, y: 0, size: 16, level: 0 },
+							{ id: 'lf-b', x: 30, y: 0, size: 16, level: 1 }
+						],
+						lines: [
+							{ id: 'lf-l1', from: 'lf-a', to: 'lf-b', color: '#d9480f' },
+							{ id: 'lf-l2', from: 'lf-a', to: 'lf-b', color: '#d9480f' }
+						],
+						channels: [{
+							id: 'lf-ch', from: 'lf-a', to: 'lf-b', lineIds: ['lf-l1', 'lf-l2'],
+							tangentInset: 0, offsetMode: 'inset', inset: 0.12,
+							groups: [{ id: 'lf-g', lineIds: ['lf-l1', 'lf-l2'], path: [[0, 18]] }]
+						}],
+						lineFollowsNode: false,
+						history: true,
+						initialView: { center: [0, 0], scale: 1 },
+						showGrid: false
+					})
+					await settle(120)
+					const lfPaths = () => Object.fromEntries(lfView.listLines()
+						.filter(line => String(line.item.id).startsWith('lf-'))
+						.map(line => [String(line.item.id), JSON.stringify(line.path)]))
+					const lfBase = lfPaths()
+					lfView.setFilter({ points: { level: 0 } })
+					await settle(120)
+					const lfFiltered = lfPaths()
+					check('lineFollowsNode:false：筛选未写 cascade 时只隐藏节点，回线几何不变', lfView.getVisibleData().points.length === 1 && lfView.listLines().filter(line => String(line.item.id).startsWith('lf-')).length === 2 && Object.keys(lfBase).every(id => lfFiltered[id] === lfBase[id]), JSON.stringify({ base: lfBase, current: lfFiltered }))
+					lfView.updateOptions({ lineFollowsNode: true })
+					await settle(120)
+					check('lineFollowsNode：动态切到 true 后按默认 cascade 收起回线', lfView.listLines().filter(line => String(line.item.id).startsWith('lf-')).length === 0, JSON.stringify(lfPaths()))
+					lfView.updateOptions({ lineFollowsNode: false })
+					await settle(120)
+					const lfToggledBack = lfPaths()
+					check('lineFollowsNode：动态切回 false 后按节点最后坐标恢复回线', lfView.getVisibleData().points.length === 1 && Object.keys(lfBase).every(id => lfToggledBack[id] === lfBase[id]), JSON.stringify({ base: lfBase, current: lfToggledBack }))
+					lfView.setFilter({ points: { level: 0 }, cascade: 'binding' })
+					await settle(120)
+					check('lineFollowsNode:false：筛选显式 cascade 仍然优先', lfView.listLines().filter(line => String(line.item.id).startsWith('lf-')).length === 0, JSON.stringify(lfPaths()))
+					lfView.setFilter(null)
+					await settle(120)
+					lfView.hideFeatures('point', 'lf-a')
+					await settle(120)
+					const lfHidden = lfPaths()
+					check('lineFollowsNode:false：visible:false 隐藏节点后回线停在最后坐标', lfView.listLines().filter(line => String(line.item.id).startsWith('lf-')).length === 2 && Object.keys(lfBase).every(id => lfHidden[id] === lfBase[id]), JSON.stringify({ base: lfBase, current: lfHidden }))
+					lfView.showFeatures('point', 'lf-a')
+					await settle(120)
+					const lfRemoved = lfView.removePoints('lf-a')
+					await settle(120)
+					const lfAfterRemove = lfPaths()
+					const lfChannelCount = lfView.getData().channels?.length ?? lfView.getChannels().length
+					check('lineFollowsNode:false：删除节点不删回线 / 通道，几何继续停在最后坐标', lfRemoved.ok && lfRemoved.removedLines === 0 && lfRemoved.removedChannels === 0 && lfView.getData().points.length === 1 && lfView.getData().lines.length === 2 && lfChannelCount === 1 && Object.keys(lfBase).every(id => lfAfterRemove[id] === lfBase[id]), JSON.stringify({ removed: lfRemoved, paths: lfAfterRemove }))
+					lfView.undo()
+					await settle(120)
+					check('lineFollowsNode:false：撤销删除后节点与原有几何一起回来', lfView.getData().points.length === 2 && lfView.getData().lines.length === 2 && Object.keys(lfBase).every(id => lfPaths()[id] === lfBase[id]), JSON.stringify({ base: lfBase, current: lfPaths(), points: lfView.getData().points }))
+					lfView.destroy()
+					lfHost.remove()
+
 					/* 问题 2（续）：图标节点走的永远是「整份重排」那一支 —— 跟随几何与宽度重排从前欠在分支之后，
 					   节点换了大小 / 图标之后回线还铺在旧宽度上，要再点一下画布才追齐（同一份问题.txt 的再一轮）。
 					   这两条用贴图符号（SVG，size 8 / 24）+ tangentInset: 0：间距就是节点外框本身 */
@@ -2767,13 +3054,12 @@
 					busView.destroy()
 					busHost.remove()
 
-					/* 右键优先级：节点压在通道回线上时，右键给的是节点，而不是通道菜单 */
+					/* 右键统一入口：节点 / 线路 / 通道都只走 onContextMenu，通道上下文挂在同一份载荷上 */
 					const rcHost = document.createElement('div')
 					rcHost.style.cssText = 'width:420px;height:300px'
 					document.body.appendChild(rcHost)
 					const rcBuilt = createChannels([{ id: 'ch-rc', from: 'rc-n1', to: 'rc-n2', lineIds: ['rc-1', 'rc-2'] }])
 					const rcHits = []
-					const rcChannels = []
 					const rcView = createGisView(rcHost, {
 						points: [
 							{ id: 'rc-n1', x: 0, y: 0, name: '甲站', size: 20 },
@@ -2783,11 +3069,9 @@
 						channels: rcBuilt.channels,
 						fitPadding: 60,
 						showGrid: false,
-						// 这一节验的是通道右键菜单：channelMenu 缺省关，这里显式打开
-						// （右键回调本体是 contextMenu，也一并打开）
-						features: { channelMenu: true, contextMenu: true },
-						onContextMenu: payload => rcHits.push(payload),
-						onChannelContextMenu: payload => rcChannels.push(payload)
+						// 右键回调本体是 contextMenu；通道不再需要第二个功能开关
+						features: { contextMenu: true },
+						onContextMenu: payload => rcHits.push(payload)
 					})
 					await settle(140)
 					const rcRightClick = async (screen) => {
@@ -2802,20 +3086,195 @@
 						}))
 						await settle(60)
 					}
-					// 端点上右键：这个位置同时压着节点与回线，拾取按「点高于线」给节点，通道上下文给 null
+					// 端点上右键：这个位置同时压着节点与回线，拾取按「点高于线」给节点，不附通道上下文
 					await rcRightClick(rcView.project(0, 0))
 					check('右键落在通道端点（节点压着回线）：onContextMenu 给的是节点', rcHits[0]?.type === 'point' && rcHits[0]?.item?.id === 'rc-n1', JSON.stringify({ type: rcHits[0]?.type, id: rcHits[0]?.item?.id }))
-					check('右键落在节点上：onChannelContextMenu 收到 null，不弹通道菜单', rcChannels.length === 1 && rcChannels[0] === null, JSON.stringify(rcChannels[0] ?? null))
+					check('右键落在节点上：只发一条 onContextMenu，且没有 channelContext', rcHits.length === 1 && rcHits[0]?.channelContext === undefined, JSON.stringify({ count: rcHits.length, channelContext: rcHits[0]?.channelContext ?? null }))
 					// 回线中段（离两端节点都远）：这里才是「通道右键」
 					const rcLine = rcView.getData().lines.find(item => String(item.id) === 'rc-1')
 					const rcMidWorld = Array.isArray(rcLine?.path) && rcLine.path.length > 1 ? rcLine.path[Math.floor(rcLine.path.length / 2)] : [60, 0]
 					diag('右键回线中段', `世界 ${rcMidWorld.map(value => Number(value).toFixed(2)).join(',')} · 回线折点 ${Array.isArray(rcLine?.path) ? rcLine.path.length : 0}`)
 					await rcRightClick(rcView.project(rcMidWorld[0], rcMidWorld[1]))
-					check('右键落在回线中段：给出通道上下文（组数 / 当前分组 / 可用交互）', rcChannels[1]?.channelId === 'ch-rc' && rcChannels[1]?.lineId === 'rc-1' && rcChannels[1]?.groupCount === 1 && (rcChannels[1]?.actions ?? []).length > 0, JSON.stringify({ channel: rcChannels[1]?.channelId, line: rcChannels[1]?.lineId, groups: rcChannels[1]?.groupCount }))
-					check('右键通道时通用回调照旧发一条（点 / 线 / 空白都有载荷）', rcHits.length === 2 && rcHits[1]?.type === 'line' && rcHits[1]?.channelId === 'ch-rc', JSON.stringify({ count: rcHits.length, type: rcHits[1]?.type }))
+					const rcContext = rcHits[1]?.channelContext
+					check('右键落在回线中段：同一份 onContextMenu 载荷里带 channelContext（组数 / 当前分组 / 可用交互）', rcHits.length === 2 && rcContext?.channelId === 'ch-rc' && rcHits[1]?.lineId === 'rc-1' && rcContext?.groupCount === 1 && (rcContext?.actions ?? []).length > 0, JSON.stringify({ count: rcHits.length, channel: rcContext?.channelId, line: rcHits[1]?.lineId, groups: rcContext?.groupCount }))
+					check('右键通道只发这一条（不再额外发 onChannelContextMenu），线路下标 / id 也在载荷上', rcHits[1]?.type === 'line' && rcHits[1]?.channelId === 'ch-rc' && rcHits[1]?.lineId === 'rc-1' && Number.isInteger(rcHits[1]?.lineIndex) && rcHits[1]?.action?.target === 'channel', JSON.stringify({ count: rcHits.length, type: rcHits[1]?.type, lineIndex: rcHits[1]?.lineIndex, target: rcHits[1]?.action?.target }))
 					rcView.destroy()
 					rcHost.remove()
 
+					/* 点击级联高亮：节点亮自身 + 直连线路 / 节点，线路 / 通道亮两端；与选中集完全分开 */
+					const casHost = document.createElement('div')
+					casHost.style.cssText = 'width:520px;height:320px'
+					document.body.appendChild(casHost)
+					const casBuilt = createChannels([{ id: 'cas-ch', from: 'cas-b', to: 'cas-c', circuits: 2, lineIds: ['cas-c1', 'cas-c2'] }])
+					const casEvents = []
+					const casBusEvents = []
+					const casView = createGisView(casHost, {
+						points: [
+							{ id: 'cas-a', x: 0, y: 0, size: 14 },
+							{ id: 'cas-b', x: 120, y: 0, size: 14 },
+							{ id: 'cas-c', x: 240, y: 0, size: 14 },
+							{ id: 'cas-d', x: 60, y: 90, size: 14 }
+						],
+						lines: [
+							{ id: 'cas-ab', from: 'cas-a', to: 'cas-b', path: [[0, 0], [120, 0]] },
+							...casBuilt.lines
+						],
+						channels: casBuilt.channels,
+						fitPadding: 60,
+						showGrid: false,
+						cascadeHighlight: true,
+						// 级联高亮本身不依赖 select；这里打开选中，用来验证两套状态互不污染
+						features: { select: true, contextMenu: true },
+						onCascadeHighlight: payload => casEvents.push(payload)
+					})
+					casView.on('cascadeHighlight', payload => casBusEvents.push(payload))
+					await settle(140)
+					const casClick = async (screen, extra = {}) => {
+						cmSend(casView, 'pointerdown', screen, { buttons: 1, ...extra })
+						cmSend(casView, 'pointerup', screen, { buttons: 0, button: 0, ...extra })
+						await settle(60)
+					}
+					await casClick(casView.project(0, 0))
+					const casPointInfo = casView.getCascadeHighlight()
+					check('级联高亮：点节点亮自身与直连线路 / 另一端节点（默认 both）',
+						casPointInfo?.origin?.target === 'point' && casPointInfo?.origin?.item?.id === 'cas-a' &&
+						casPointInfo.points.map(entry => entry.item.id).sort().join(',') === 'cas-a,cas-b' &&
+						casPointInfo.lines.map(entry => entry.item.id).join(',') === 'cas-ab',
+						JSON.stringify({ origin: casPointInfo?.origin?.item?.id, points: casPointInfo?.points?.map(entry => entry.item.id), lines: casPointInfo?.lines?.map(entry => entry.item.id) }))
+					check('级联高亮不写选中集：亮两个节点与一条线路时选中集仍只是这次点中的节点',
+						casPointInfo?.pointIndexes?.length === 2 && casPointInfo?.lineIndexes?.length === 1 && casView.getSelectionData().count === 1,
+						JSON.stringify({ cascade: [casPointInfo?.pointIndexes, casPointInfo?.lineIndexes], selected: casView.getSelectionData().count }))
+					check('级联高亮：onCascadeHighlight 与 cascadeHighlight 事件都收到同一份读数',
+						casEvents.length === 1 && casBusEvents.length === 1 && casEvents[0]?.origin?.item?.id === 'cas-a' && casBusEvents[0]?.pointIndexes?.length === 2,
+						JSON.stringify({ callback: casEvents.length, event: casBusEvents.length }))
+
+					casEvents.length = 0
+					casBusEvents.length = 0
+					await casClick(casView.project(60, 0))
+					const casLineInfo = casView.getCascadeHighlight()
+					check('级联高亮：点线路只亮两端节点（不把线路自身算进去）',
+						casLineInfo?.origin?.target === 'line' && casLineInfo?.origin?.item?.id === 'cas-ab' &&
+						casLineInfo.points.map(entry => entry.item.id).sort().join(',') === 'cas-a,cas-b' && casLineInfo.lines.length === 0 && casEvents.length === 1,
+						JSON.stringify({ origin: casLineInfo?.origin?.item?.id, points: casLineInfo?.points?.map(entry => entry.item.id), lines: casLineInfo?.lines?.length }))
+
+					casEvents.length = 0
+					const casChannelGeometry = casView.getLine('cas-c1')?.path ?? [[120, 0], [240, 0]]
+					const casChannelStart = casChannelGeometry[0]
+					const casChannelEnd = casChannelGeometry[casChannelGeometry.length - 1]
+					await casClick(casView.project((casChannelStart[0] + casChannelEnd[0]) / 2, (casChannelStart[1] + casChannelEnd[1]) / 2))
+					const casChannelInfo = casView.getCascadeHighlight()
+					check('级联高亮：点通道回线亮两端节点，origin 记通道 / 分组（target 为 channel）',
+						casChannelInfo?.origin?.target === 'channel' && casChannelInfo?.origin?.channelId === 'cas-ch' &&
+						casChannelInfo.points.map(entry => entry.item.id).sort().join(',') === 'cas-b,cas-c' && casChannelInfo.lines.length === 0 && casEvents.length === 1,
+						JSON.stringify({ origin: casChannelInfo?.origin, points: casChannelInfo?.points?.map(entry => entry.item.id) }))
+
+					casEvents.length = 0
+					await casClick([4, 4])
+					check('级联高亮：点空白处收掉，getCascadeHighlight 返回 null 并发一条 null',
+						casView.getCascadeHighlight() === null && casEvents.length === 1 && casEvents[0] === null,
+						JSON.stringify({ info: casView.getCascadeHighlight(), events: casEvents.length }))
+
+					casView.updateOptions({ cascadeHighlight: { scope: 'points' } })
+					await settle(60)
+					casEvents.length = 0
+					await casClick(casView.project(240, 0))
+					const casPointsOnly = casView.getCascadeHighlight()
+					check('级联高亮 scope: points：点节点只亮节点，不亮直连线路',
+						casPointsOnly?.scope === 'points' && casPointsOnly.points.map(entry => entry.item.id).sort().join(',') === 'cas-b,cas-c' && casPointsOnly.lines.length === 0,
+						JSON.stringify({ scope: casPointsOnly?.scope, points: casPointsOnly?.points?.map(entry => entry.item.id), lines: casPointsOnly?.lines?.length }))
+
+					casView.updateOptions({
+						pointSelectStyle: { color: '#00cc44', strokeColor: '#006622', strokeWidth: 1, sizeScale: 1 },
+						cascadeHighlight: {
+							scope: 'both',
+							pointStyle: { color: '#112233', strokeColor: '#445566', strokeWidth: 3, sizeScale: 1.4 },
+							lineStyle: { color: '#778899', width: 7, opacity: 1 }
+						}
+					})
+					await settle(60)
+					const casPointPaint = (snapshot, id) => {
+						const item = casView.getData().points.find(point => point.id === id)
+						const [x, y] = casView.project(item.x, item.y)
+						return [...snapshot.points, ...snapshot.raised].find(point => Math.hypot(point.x - x, point.y - y) < 3)
+					}
+					casEvents.length = 0
+					await casClick(casView.project(0, 0))
+					const casStyledSnapshot = casView.snapshotScene({ background: false })
+					const casSelectedPaint = casPointPaint(casStyledSnapshot, 'cas-a')
+					const casCascadePaint = casPointPaint(casStyledSnapshot, 'cas-b')
+					check('级联高亮样式可单独配置：邻接节点与线路按 pointStyle / lineStyle 解析到画面',
+						casCascadePaint?.fill === 'rgba(17,34,51,1)' &&
+						casStyledSnapshot.lines.some(line => line.color === 'rgba(119,136,153,1)' && Math.abs(line.width - 7) < 0.2),
+						JSON.stringify({ points: [...casStyledSnapshot.points, ...casStyledSnapshot.raised].map(point => point.fill), lines: casStyledSnapshot.lines.map(line => [line.color, line.width]) }))
+					check('级联高亮：直接选中的节点仍走 pointSelectStyle，不套级联样式',
+						casSelectedPaint?.fill === 'rgba(0,204,68,1)' && casCascadePaint?.fill !== casSelectedPaint?.fill,
+						JSON.stringify({ selected: casSelectedPaint, cascade: casCascadePaint }))
+
+					casView.updateOptions({ pointSelectStyle: null })
+					await settle(40)
+					await casClick(casView.project(240, 0))
+					const casNoSelectPaint = casPointPaint(casView.snapshotScene({ background: false }), 'cas-c')
+					check('没配选中样式时直接选中项也不回落到级联样式（保持普通外观）',
+						casNoSelectPaint?.fill !== 'rgba(17,34,51,1)' && JSON.stringify(casView.getSelectionData().ids) === JSON.stringify(['cas-c']),
+						JSON.stringify({ paint: casNoSelectPaint, selected: casView.getSelectionData().ids }))
+
+					// 普通单击 / 多选分开控制：关闭的那一路只改选中，并把旧级联收掉；另一路照常触发
+					casView.updateOptions({ cascadeHighlight: { scope: 'both', triggerOnClick: false, triggerOnMultiSelect: true } })
+					await settle(40)
+					await casClick(casView.project(0, 0))
+					check('triggerOnClick: false：普通单击不触发级联', casView.getCascadeHighlight() === null, JSON.stringify(casView.getCascadeHighlight()))
+					await casClick(casView.project(240, 0), { ctrlKey: true })
+					check('triggerOnMultiSelect: true：Ctrl 多选仍触发级联', casView.getCascadeHighlight()?.origin?.item?.id === 'cas-c' && casView.getCascadeHighlight()?.pointIndexes?.length === 2, JSON.stringify({ origin: casView.getCascadeHighlight()?.origin?.item?.id, points: casView.getCascadeHighlight()?.pointIndexes }))
+					casView.updateOptions({ cascadeHighlight: { scope: 'both', triggerOnClick: true, triggerOnMultiSelect: false } })
+					await settle(40)
+					await casClick(casView.project(120, 0))
+					const casClickOn = casView.getCascadeHighlight()
+					await casClick(casView.project(60, 90), { ctrlKey: true })
+					check('triggerOnMultiSelect: false：普通单击照常触发，Ctrl 多选不再更新而是收掉旧级联',
+						casClickOn?.origin?.item?.id === 'cas-b' && casView.getCascadeHighlight() === null,
+						JSON.stringify({ click: casClickOn?.origin?.item?.id, multi: casView.getCascadeHighlight() }))
+
+					// 框选：默认不触发；打开后整框邻接并集参与级联，直接框中的节点仍走 boxSelectStyle
+					casView.updateOptions({
+						pointBoxSelectStyle: { color: '#00ccff', strokeColor: '#005577', strokeWidth: 1, sizeScale: 1 },
+						cascadeHighlight: { scope: 'both', triggerOnBoxSelect: true }
+					})
+					await settle(40)
+					const casBoxA = casView.project(0, 0)
+					const casBoxB = casView.project(120, 0)
+					const casBox = {
+						x: Math.min(casBoxA[0], casBoxB[0]) - 30,
+						y: Math.min(casBoxA[1], casBoxB[1]) - 30,
+						width: Math.abs(casBoxA[0] - casBoxB[0]) + 60,
+						height: Math.abs(casBoxA[1] - casBoxB[1]) + 60
+					}
+					casView.selectInBox(casBox, { selectionKinds: ['point'] })
+					await settle(40)
+					const casBoxInfo = casView.getCascadeHighlight()
+					const casBoxSnapshot = casView.snapshotScene({ background: false })
+					const casBoxPaint = casPointPaint(casBoxSnapshot, 'cas-a')
+					const casBoxNeighborPaint = casPointPaint(casBoxSnapshot, 'cas-c')
+					check('triggerOnBoxSelect: true：框内所有命中项一起算邻接并集',
+						casBoxInfo?.pointIndexes?.length === 3 && casBoxInfo?.origin?.item?.id === 'cas-a' && casBoxInfo.lineIndexes.length >= 3,
+						JSON.stringify({ origin: casBoxInfo?.origin?.item?.id, points: casBoxInfo?.pointIndexes, lines: casBoxInfo?.lineIndexes }))
+					check('框选直接命中的节点走 boxSelectStyle，只有框外邻接节点套级联样式',
+						casBoxPaint?.fill === 'rgba(0,204,255,1)' && casBoxNeighborPaint?.fill === 'rgba(255,247,237,1)',
+						JSON.stringify({ boxed: casBoxPaint, neighbor: casBoxNeighborPaint }))
+					casView.updateOptions({ cascadeHighlight: { scope: 'both', triggerOnBoxSelect: false } })
+					await settle(40)
+					const casBoxD = casView.project(60, 90)
+					casView.selectInBox({ x: casBoxD[0] - 30, y: casBoxD[1] - 30, width: 60, height: 60 }, { selectionKinds: ['point'] })
+					check('triggerOnBoxSelect: false（缺省）：框选只改选中集并收掉旧级联', casView.getCascadeHighlight() === null, JSON.stringify(casView.getCascadeHighlight()))
+
+					casEvents.length = 0
+					casView.updateOptions({ cascadeHighlight: false })
+					await settle(60)
+					check('关掉级联高亮：当前读数与事件都收成 null',
+						casView.getCascadeHighlight() === null && casEvents.length === 1 && casEvents[0] === null,
+						JSON.stringify({ info: casView.getCascadeHighlight(), events: casEvents.length }))
+					casView.destroy()
+					casHost.remove()
+
 					/* 导出选中的节点：图片 / 数据二选一，线路按「两端都在选中集里」决定带不带 */
 					const exHost = document.createElement('div')
 					exHost.style.cssText = 'width:420px;height:300px'
@@ -2925,6 +3384,67 @@
 					svgView.destroy()
 					svgHost.remove()
 
+					/* exportImage 的范围：viewport 只导当前可视区域；all 临时适应全部内容，出完恢复相机 */
+					const scopeHost = document.createElement('div')
+					scopeHost.style.cssText = 'width:360px;height:240px'
+					document.body.appendChild(scopeHost)
+					const scopeView = createGisView(scopeHost, {
+						points: [
+							{ id: 'scope-a', x: 0, y: 0, size: 40, color: '#ff0000' },
+							{ id: 'scope-b', x: 1000, y: 0, size: 40, color: '#0000ff' }
+						],
+						background: { color: '#ffffff' },
+						showGrid: false
+					})
+					await settle(140)
+					scopeView.setCamera({ center: [0, 0], scale: 6 })
+					await settle(60)
+					const scopeCamera = scopeView.getCamera()
+					const scopeColorCounts = async (url) => {
+						const image = new Image()
+						await new Promise((resolve, reject) => {
+							image.onload = resolve
+							image.onerror = () => reject(new Error('导出图片加载失败'))
+							image.src = url
+						})
+						const buffer = document.createElement('canvas')
+						buffer.width = image.width
+						buffer.height = image.height
+						const context = buffer.getContext('2d')
+						context.drawImage(image, 0, 0)
+						const data = context.getImageData(0, 0, buffer.width, buffer.height).data
+						let red = 0
+						let blue = 0
+						for (let index = 0; index < data.length; index += 4) {
+							if (data[index] > 180 && data[index + 1] < 90 && data[index + 2] < 90) {
+								red += 1
+							}
+							if (data[index + 2] > 180 && data[index] < 90 && data[index + 1] < 90) {
+								blue += 1
+							}
+						}
+						return { red, blue, width: buffer.width, height: buffer.height }
+					}
+					const scopeViewport = await scopeColorCounts(await scopeView.exportImage({ scope: 'viewport', scale: 1, includeLabels: false }))
+					const scopeAll = await scopeColorCounts(await scopeView.exportImage({ scope: 'all', padding: 16, scale: 1, includeLabels: false }))
+					const scopeAfter = scopeView.getCamera()
+					check('exportImage scope: viewport 只含当前视口内容', scopeViewport.red > 50 && scopeViewport.blue === 0, JSON.stringify(scopeViewport))
+					check('exportImage scope: all 临时适应全部内容（两个节点都进画面）', scopeAll.red > 50 && scopeAll.blue > 50, JSON.stringify(scopeAll))
+					check('exportImage scope: all 出图后相机原样恢复', scopeAfter.scale === scopeCamera.scale && scopeAfter.center[0] === scopeCamera.center[0] && scopeAfter.center[1] === scopeCamera.center[1], JSON.stringify({ before: scopeCamera, after: scopeAfter }))
+					const scopeSvg = decodeSvgUrl(await scopeView.exportImage({ type: 'svg', scope: 'all', padding: 12, includeLabels: false }))
+					const scopeSvgAfter = scopeView.getCamera()
+					check('exportImage scope: all 在 SVG 分支同样生效并恢复相机', (scopeSvg.match(/<circle/g) || []).length >= 2 && scopeSvgAfter.scale === scopeCamera.scale, JSON.stringify({ circles: (scopeSvg.match(/<circle/g) || []).length, camera: scopeSvgAfter }))
+					let scopeError = ''
+					try {
+						await scopeView.exportImage({ scope: 'window' })
+					}
+					catch (error) {
+						scopeError = String(error?.message ?? error)
+					}
+					check('exportImage scope 写错直接抛异常（不静默按 viewport 导）', scopeError.includes('viewport') && scopeError.includes('all'), scopeError)
+					scopeView.destroy()
+					scopeHost.remove()
+
 					/* 适应视图的留白：padding 比画布还大时，扣完留白的可用尺寸不能被钳到 1px（那会把整幅图缩成一个点） */
 					const fitHost = document.createElement('div')
 					fitHost.style.cssText = 'width:220px;height:140px'
@@ -2935,13 +3455,13 @@
 						showGrid: false
 					})
 					await settle(160)
-					fitView.focusOn('fl1', { padding: 220 })
+					fitView.focusOn('fl1', { zoom: true, padding: 220 })
 					await settle(80)
 					const fitStart = fitView.project(0, 0)
 					const fitEnd = fitView.project(300, 200)
 					const fitSpan = Math.hypot(fitStart[0] - fitEnd[0], fitStart[1] - fitEnd[1])
 					check('适应视图的留白比画布还大时：内容不会被挤成一个点（至少留给它 48px）', fitSpan > 40, `跨度 ${fitSpan.toFixed(1)}px / 画布 ${fitView.getStats().cssWidth}×${fitView.getStats().cssHeight}`)
-					fitView.focusOn('fl1', { padding: 20 })
+					fitView.focusOn('fl1', { zoom: true, padding: 20 })
 					await settle(80)
 					const fitPadStart = fitView.project(0, 0)
 					const fitPadEnd = fitView.project(300, 200)
@@ -3451,13 +3971,17 @@
 					apiSend('pointerup', [apiRight, apiBottom], { button: 0, buttons: 0, shiftKey: true })
 					await settle()
 					check('框选的结果用同一份读数读回来（Shift + 拖动）', apiIds() === 'api-a,api-b,api-c' && apiView.getSelectionData().count === 3, apiIds())
-					// focusOn 一批目标：数组取整体包围盒 —— 这三个点的中心（200, 20）当屏幕中心、按这一批的范围适配
+					// focusOn 一批目标：缺省只居中；显式 zoom: true 才按整体包围盒适配
+					const apiDefaultScale = apiView.getCamera().scale
 					apiView.focusOn(['api-a', 'api-b', 'api-c'])
+					const apiCenteredBatch = apiView.getCamera()
+					check('focusOn(一批目标)：缺省只把中心挪到 (200, 20)，比例一点不动', Math.abs(apiCenteredBatch.center[0] - 200) < 1e-6 && Math.abs(apiCenteredBatch.center[1] - 20) < 1e-6 && apiCenteredBatch.scale === apiDefaultScale, JSON.stringify({ scale: [apiDefaultScale, apiCenteredBatch.scale], center: apiCenteredBatch.center }))
+					apiView.focusOn(['api-a', 'api-b', 'api-c'], { zoom: true })
 					const apiBatch = apiView.getCamera()
 					const apiStats = apiView.getStats()
 					const apiCorners = [[0, 0], [400, 40]].map(spot => apiView.project(spot[0], spot[1]))
 					const apiInside = apiCorners.every(spot => spot[0] >= 0 && spot[0] <= apiStats.cssWidth && spot[1] >= 0 && spot[1] <= apiStats.cssHeight)
-					check('focusOn(一批目标)：整体包围盒居中（三个点的中心当屏幕中心，三个点都在视口里）', Math.abs(apiBatch.center[0] - 200) < 1e-6 && Math.abs(apiBatch.center[1] - 20) < 1e-6 && apiBatch.scale > 0 && apiInside, JSON.stringify({ center: apiBatch.center, corners: apiCorners }))
+					check('focusOn(一批目标, { zoom: true })：整体包围盒居中，三个点都在视口里', Math.abs(apiBatch.center[0] - 200) < 1e-6 && Math.abs(apiBatch.center[1] - 20) < 1e-6 && apiBatch.scale > 0 && apiInside, JSON.stringify({ center: apiBatch.center, corners: apiCorners }))
 					// center: true 是原来 centerOn 的语义：只挪中心，比例一点不动
 					apiView.focusOn(['api-a', 'api-b'], { center: true })
 					const apiCenter1 = apiView.getCamera()
@@ -3468,9 +3992,11 @@
 					apiView.focusOn('api-b', { center: true })
 					const apiCenter3 = apiView.getCamera().center
 					check('focusOn(id, { center: true })：中心挪到这个要素上', Math.abs(apiCenter3[0] - 200) < 1e-6 && Math.abs(apiCenter3[1] - 40) < 1e-6, JSON.stringify(apiCenter3))
-					apiView.focusOn({ type: 'channel', channelId: 'api-ch' }, { center: true })
-					const apiCenter4 = apiView.getCamera().center
-					check('focusOn(通道写法, { center: true })：取这条通道范围的中心', Math.abs(apiCenter4[0] - 100) < 5 && Math.abs(apiCenter4[1] - 20) < 5, JSON.stringify(apiCenter4))
+					const apiChannelScale = apiView.getCamera().scale
+					apiView.focusOn({ type: 'channel', channelId: 'api-ch' })
+					const apiChannelCamera = apiView.getCamera()
+					const apiCenter4 = apiChannelCamera.center
+					check('focusOn(通道写法) 缺省只居中，线路 / 通道不再自动放大', Math.abs(apiCenter4[0] - 100) < 5 && Math.abs(apiCenter4[1] - 20) < 5 && apiChannelCamera.scale === apiChannelScale, JSON.stringify({ center: apiCenter4, scale: [apiChannelScale, apiChannelCamera.scale] }))
 					apiView.focusOn('没有这个 id', { center: true })
 					const apiCenter5 = apiView.getCamera().center
 					check('focusOn：认不出来的目标什么都不做（视角停在原处）', apiCenter5[0] === apiCenter4[0] && apiCenter5[1] === apiCenter4[1], JSON.stringify(apiCenter5))
@@ -3479,16 +4005,41 @@
 					check('focusOn(一段范围, { center: true })：取中心', Math.abs(apiCenter6[0] - 200) < 1e-6 && Math.abs(apiCenter6[1] - 20) < 1e-6, JSON.stringify(apiCenter6))
 					// select: true：被聚焦的要素同时变成选中状态（与接口选中同一份 state）；mode 决定怎么并进当前选中集
 					const apiBeforeFocusSelect = apiView.getSelectionData().ids.join(',')
-					apiView.focusOn(['api-a', 'api-b', 'api-c'], { select: true, padding: 20 })
+					apiView.focusOn(['api-a', 'api-b', 'api-c'], { select: true, zoom: true, padding: 20 })
 					check('focusOn(一批, { select: true })：被聚焦的这一批同时选中（整份选中集换成这三个）', apiView.getSelectionData().ids.join(',') === 'api-a,api-b,api-c' && apiBeforeFocusSelect === 'api-a,api-b,api-c' && apiView.getSelectionData().count === 3, `${apiBeforeFocusSelect} -> ${apiView.getSelectionData().ids.join(',')}`)
 					apiView.focusOn('api-a', { select: true, mode: 'remove' })
 					check("focusOn(..., { select: true, mode: 'remove' })：只把聚焦的这个从选中集里去掉", apiView.getSelectionData().ids.join(',') === 'api-b,api-c', apiView.getSelectionData().ids.join(','))
 					apiView.selectFeatures(null)
 					const apiAreaScale = apiView.getCamera().scale
-					apiView.focusOn('api-b', { maxZoom: 12 })
+					apiView.focusOn('api-b', { zoom: true, maxZoom: 12 })
 					const apiZoomCamera = apiView.getCamera()
-					check('focusOn(单个节点, { maxZoom })：零面积目标撑出最小范围，放大并居中', apiZoomCamera.scale > apiAreaScale && Math.abs(apiZoomCamera.center[0] - 200) < 1e-6 && Math.abs(apiZoomCamera.center[1] - 40) < 1e-6, JSON.stringify({ scale: apiZoomCamera.scale, center: apiZoomCamera.center }))
+					check('focusOn(单个节点, { zoom: true, maxZoom })：零面积目标撑出最小范围，放大并居中', apiZoomCamera.scale > apiAreaScale && Math.abs(apiZoomCamera.center[0] - 200) < 1e-6 && Math.abs(apiZoomCamera.center[1] - 40) < 1e-6, JSON.stringify({ scale: apiZoomCamera.scale, center: apiZoomCamera.center }))
+					// 实例命令：注册 / 执行 / 同名覆盖 / 幂等卸载；名字与 handler 非法时只提醒、不动注册表
+					let commandPayload = null
+					let commandContext = null
+					const disposeEcho = apiView.registerCommand('  demo:echo  ', (payload, context) => {
+						commandPayload = payload
+						commandContext = context
+						return { doubled: Number(payload?.value ?? 0) * 2 }
+					})
+					const echoResult = apiView.executeCommand('demo:echo', { value: 21 })
+					check('registerCommand / executeCommand：名字规范化、payload 与冻结上下文可用，handler 的返回值原样带回', apiView.listCommands().join(',') === 'demo:echo' && echoResult.ok === true && echoResult.name === 'demo:echo' && echoResult.value?.doubled === 42 && commandPayload?.value === 21 && commandContext?.view === apiView && commandContext?.name === 'demo:echo' && Object.isFrozen(commandContext), JSON.stringify({ commands: apiView.listCommands(), result: echoResult, context: commandContext?.name }))
+					const disposeReplacement = apiView.registerCommand('demo:echo', payload => `replacement:${payload}`)
+					disposeEcho()
+					const replacementResult = apiView.executeCommand('demo:echo', 'still-here')
+					check('registerCommand：同名后注册覆盖先生效，旧卸载函数不会误删新命令', apiView.listCommands().join(',') === 'demo:echo' && replacementResult.ok === true && replacementResult.value === 'replacement:still-here', JSON.stringify({ commands: apiView.listCommands(), result: replacementResult }))
+					disposeReplacement()
+					const invalidDispose = apiView.registerCommand('   ', () => 'never')
+					const invalidResult = apiView.executeCommand('', {})
+					const missingResult = apiView.executeCommand('demo:missing', {})
+					check('实例命令：非法名 / 未注册 / 空名字都返回 ok: false，注册表不受影响', typeof invalidDispose === 'function' && invalidResult.ok === false && missingResult.ok === false && apiView.listCommands().length === 0, JSON.stringify({ invalid: invalidResult, missing: missingResult, commands: apiView.listCommands() }))
+					apiView.registerCommand('demo:throw', () => { throw new Error('命令执行失败') })
+					const thrownResult = apiView.executeCommand('demo:throw', null)
+					check('实例命令：handler 抛错收成 ok: false + reason，不把异常甩给调用方', thrownResult.ok === false && thrownResult.name === 'demo:throw' && thrownResult.reason === '命令执行失败', JSON.stringify(thrownResult))
+					apiView.registerCommand('demo:destroyed', () => 'never')
 					apiView.destroy()
+					const afterDestroy = apiView.executeCommand('demo:destroyed', null)
+					check('destroy：实例命令表清空，销毁后执行返回 ok: false', apiView.listCommands().length === 0 && afterDestroy.ok === false, JSON.stringify({ commands: apiView.listCommands(), result: afterDestroy }))
 					apiHost.remove()
 				}
 				/* ---------------- 线路 zIndex：电压高的线压在上面（见 15.47） ---------------- */
@@ -4294,6 +4845,37 @@
 				nwView.cancelAddChannel()
 				await settle(30)
 				check('提前结束：cancelAddChannel 收掉草稿并补一条 cancel（不新建）', nwView.getAddChannelDraft() === null && nwEvents.some(payload => payload.phase === 'cancel') && nwEvents.every(payload => payload.phase !== 'commit'), JSON.stringify(nwEvents.map(payload => payload.phase)))
+
+				// ⑩b 预指定起点：beginAddChannel({ from }) 直接进入「等终点」，下一次点击就是 ready
+				nwEvents.length = 0
+				nwSelectChanges.length = 0
+				nwView.beginAddChannel({ from: 'na', select: true })
+				await settle(40)
+				const nwPresetFrom = nwView.getAddChannelDraft()
+				check('beginAddChannel({ from })：草稿直接以该节点为起点进入 from 相位',
+					nwPresetFrom?.phase === 'from' && nwPresetFrom.from?.id === 'na' && nwPresetFrom.to === null && nwEvents[0]?.phase === 'from',
+					JSON.stringify({ phase: nwPresetFrom?.phase, from: nwPresetFrom?.from?.id, events: nwEvents.map(payload => payload.phase) }))
+				check('beginAddChannel({ from, select: true })：预指定起点当场进选中集', JSON.stringify(nwView.getSelectionData().ids) === JSON.stringify(['na']), JSON.stringify(nwView.getSelectionData().ids))
+				nwClick(nwScreenOf('nb'))
+				await settle(60)
+				const nwPresetReady = nwEvents.find(payload => payload.phase === 'ready')
+				check('预指定起点后只需再选终点：一次点击得到 from=na / to=nb 的 ready',
+					nwPresetReady?.from?.id === 'na' && nwPresetReady?.to?.id === 'nb' && nwView.getAddChannelDraft()?.phase === 'ready',
+					JSON.stringify({ from: nwPresetReady?.from?.id, to: nwPresetReady?.to?.id, phases: nwEvents.map(payload => payload.phase) }))
+				nwView.cancelAddChannel()
+				await settle(20)
+				nwView.continueAddChannel({ from: { id: 'nc' } })
+				await settle(30)
+				check('continueAddChannel({ from })：没有草稿时也按预指定起点重新进入', nwView.getAddChannelDraft()?.phase === 'from' && nwView.getAddChannelDraft()?.from?.id === 'nc', JSON.stringify(nwView.getAddChannelDraft()))
+				nwView.cancelAddChannel()
+				await settle(20)
+				const nwWarnings = []
+				nwView.updateOptions({ onWarning: message => nwWarnings.push(message) })
+				nwView.beginAddChannel({ from: '不存在的起点' })
+				await settle(20)
+				check('beginAddChannel({ from }) 找不到节点：草稿不开始并报 warning',
+					nwView.getAddChannelDraft() === null && nwWarnings.some(message => message.includes('找不到起点')),
+					JSON.stringify({ draft: nwView.getAddChannelDraft(), warnings: nwWarnings }))
 				nwView.updateOptions({ onChannelDraft: null })
 				// ⑪ getChannelBetween：两个节点之间的通道读数（只读，与方案表同一份）
 				const cbPair = nwView.getChannelBetween('na', 'nb')