gis-view-webgl2 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -1157,6 +1157,12 @@ export interface GisViewLine {
 	 * 对象在全局那一份上逐字段覆盖，false / null 关掉这一条；不写就跟随全局（全局没配 = 不画）。
 	 */
 	effect?: GisViewLineEffectInput | null
+	/**
+	 * 这条线的正向是否从 from / path[0] 走向 to / path[last]，默认 true。
+	 * 写 false 时装饰位置与朝向、方向箭头、线路动画都按反方向解释；effect.reverse 与
+	 * direction.reverse 仍各自生效，两者与 forward 是异或关系（反两次等于正一次）。
+	 */
+	forward?: boolean
 	/**
 	 * 这条线的方向箭头（静态，不跑动）：true 用全局那一份（options.lineDirection），
 	 * 对象在全局那一份上逐字段覆盖，false / null 关掉这一条；不写就跟随全局（全局没配 = 不画）。
@@ -1165,6 +1171,70 @@ export interface GisViewLine {
 	direction?: GisViewLineDirectionInput | null
 }
 
+/** 级联高亮的范围：points 只亮节点，both 同时亮直接连接的线路 */
+export type GisViewCascadeHighlightScope = 'points' | 'both'
+
+/**
+ * 点击级联高亮：点击节点时高亮它和直接相连的节点 / 线路，点击线路或通道时高亮这条线的两端。
+ * 它与选中集完全分开 —— 不写 selectionKeys、不改 selected，样式也不走悬停 / 选中那一套。
+ * true 等价于 { enabled: true, scope: 'both' }；不配或 false 都是关闭。
+ */
+export interface GisViewCascadeHighlightOptions {
+	/** 开关，缺省 true（写了对象就表示打开） */
+	enabled?: boolean
+	/** 高亮范围，缺省 'both'：points 只亮节点，both 连直接连接的线路一起亮 */
+	scope?: GisViewCascadeHighlightScope
+	/** 普通单击是否触发 / 更新级联高亮，缺省 true；关闭后这次单击只走选中，并清掉旧级联 */
+	triggerOnClick?: boolean
+	/**
+	 * Ctrl / ⌘ 多选或 options.multiSelect 的累加点击是否触发级联高亮，缺省 true。
+	 * 关闭后多选只改变选中集，不改级联状态（并把旧级联收掉）
+	 */
+	triggerOnMultiSelect?: boolean
+	/**
+	 * 框选是否触发级联高亮，缺省 false（保持框选只改选中集的既有行为）。
+	 * 打开后框内每个命中项都参与邻接计算，直接命中的节点 / 线路仍走框选样式，只有邻接项套级联样式
+	 */
+	triggerOnBoxSelect?: boolean
+	/** 级联节点样式；缺省是琥珀色描边的白心节点。整份替换，不与悬停 / 选中样式叠加 */
+	pointStyle?: GisViewPointStyle
+	/** 级联线路样式；缺省是琥珀色、稍粗的实线。整份替换，不与悬停 / 选中样式叠加 */
+	lineStyle?: GisViewLineStyle
+	/** 点空白处是否收掉级联高亮，缺省 true */
+	clearOnEmptyClick?: boolean
+}
+export type GisViewCascadeHighlightInput = boolean | GisViewCascadeHighlightOptions
+
+/** 级联高亮里的一个节点 / 线路条目 */
+export interface GisViewCascadeHighlightEntry<T = GisViewPoint | GisViewLine> {
+	index: number
+	item: T
+}
+
+/** 级联高亮的来源：这一次点击命中的节点 / 线路 / 通道回线 */
+export interface GisViewCascadeHighlightOrigin {
+	/** 命中的种类：通道回线在这里是 channel，底层数据类型仍是 line */
+	target: 'point' | 'line' | 'channel'
+	type: 'point' | 'line'
+	index: number
+	item: GisViewPoint | GisViewLine
+	channelId?: string | number
+	channelIndex?: number
+	groupId?: string | number
+	groupIndex?: number
+	channel?: GisViewChannel
+}
+
+/** getCascadeHighlight() / onCascadeHighlight 的读数：来源、范围与当前亮着的节点 / 线路 */
+export interface GisViewCascadeHighlightInfo {
+	origin: GisViewCascadeHighlightOrigin | null
+	scope: GisViewCascadeHighlightScope
+	points: Array<GisViewCascadeHighlightEntry<GisViewPoint>>
+	lines: Array<GisViewCascadeHighlightEntry<GisViewLine>>
+	pointIndexes: number[]
+	lineIndexes: number[]
+}
+
 /**
  * updateLine 的补丁：线路自己的字段之外，还可以带一组「分组指令」。
  * groupId / groupIndex 会先把这条回线挪到目标分组（通道内的回线只能进一组），
@@ -1462,24 +1532,6 @@ export interface GisViewChannelContext {
 	actions: GisViewChannelAction[]
 }
 
-/** 右键点中通道回线时的载荷：上下文 + 命中的回线与屏幕 / 世界坐标，点空白处回调收到 null */
-export interface GisViewChannelContextPayload extends GisViewChannelContext {
-	/** 这一次操作的判读：type 为 'contextMenu'、target 为 'channel'（与 onContextMenu 是同一件操作） */
-	action?: GisViewPointerAction
-	/** 命中的回线在 lines 数组里的下标 */
-	lineIndex: number
-	lineId: string | number
-	coordinate: [number, number]
-	/** 鼠标按键：右键固定是 2（与指针载荷同一份口径，组件层按它补出 action.button） */
-	button?: number
-	/** 画布 CSS 像素坐标 */
-	x: number
-	y: number
-	clientX: number
-	clientY: number
-	originalEvent: Event
-}
-
 /** 新增通道时一个节点的读数：下标、id / 数据对象与坐标 */
 export interface GisViewChannelNodeDraft {
 	index: number
@@ -1678,6 +1730,11 @@ export interface GisViewChannelBetween {
 export interface GisViewChannelDraftOptions {
 	/** 两个节点一选完就自动提交，不用再调 commitAddChannel */
 	autoCommit?: boolean
+	/**
+	 * 预指定起点：节点 id / 下标 / `{ id }` / `{ index }`。给了就从「已选好起点」进入草稿，
+	 * 下一次点节点只选终点；不写则仍由第一次点击选起点。找不到节点时草稿不开始并报 warning
+	 */
+	from?: GisViewPointRef
 	/**
 	 * 连续新增：一段线路落地之后自动开下一段草稿，不用再点一次「新增通道」。
 	 * true 每段都从空白开始；'chain' 以上一段的终点当下一段起点（首尾相接）
@@ -2048,9 +2105,7 @@ export interface GisViewAddPointResult extends GisViewAddItemsResult<GisViewPoin
  * coordinate 与通道字段），另加 target（'point' / 'line' / 'channel'）与 lngLat（配了 GeoJSON 底图才有）；
  * 没命中返回 null。只读 —— 不改选中、不动光标。
  */
-export interface GisViewPickAtResult extends GisViewPickResult {
-	target: 'point' | 'line' | 'channel'
-}
+export type GisViewPickAtResult = GisViewHitResult & { target: 'point' | 'line' | 'channel' | 'cluster' }
 
 /**
  * getFeaturesInRect 的结果：points 是框内的节点（与框选同一口径，含 screen / coordinate / 通道上下文），
@@ -2506,6 +2561,14 @@ export interface GisViewWaypointKey {
 	pathIndex: number
 }
 
+/** 拐点定位的对象写法：lineIndex / lineId / id 任给一个，pathIndex 必有 */
+export interface GisViewWaypointRef {
+	lineIndex?: number
+	lineId?: string | number
+	id?: string | number
+	pathIndex: number
+}
+
 /** 拐点信息：坐标与是否处于选中态 */
 export interface GisViewWaypointInfo extends GisViewWaypointKey {
 	coordinate: [number, number]
@@ -2552,6 +2615,72 @@ export interface GisViewPickResult extends GisViewFeatureKey {
 	group?: GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }
 }
 
+/** 点聚合配置：true 等价于开着一份缺省档；对象写法可逐项覆盖。 */
+export interface GisViewPointClusterOptions {
+	/** 缺省 true；写成 false 与不配一样，都是关 */
+	enabled?: boolean
+	/** 聚合半径（CSS 像素），缺省 60，夹在 8 ~ 500 */
+	radius?: number
+	/** 至少多少个点才合成一个聚合圆，缺省 2（最小也是 2） */
+	minPoints?: number
+	/** 相机比例 / 基准比例超过它之后展开原始点；0（缺省）表示不设上限 */
+	maxZoom?: number
+}
+
+/** getPointCluster() 的读数：归一化之后的配置 + 当前缩放档是否仍在聚合。 */
+export interface GisViewPointClusterReadout extends Required<GisViewPointClusterOptions> {
+	active: boolean
+}
+
+/** 一个展示组：count 为 1 是单成员，大于 1 是聚合圆；坐标与包围盒都是世界坐标。 */
+export interface GisViewCluster {
+	id: string
+	count: number
+	pointIndexes: number[]
+	pointIds: Array<string | number>
+	coordinate: [number, number]
+	/** 当前相机下的画布 CSS 像素位置 */
+	screen: [number, number]
+	radius: number
+	bounds: GisViewBounds
+}
+
+/** 多成员聚合圆的拾取结果：item 永远为 null，index 为 -1，不进入普通要素选中集。 */
+export interface GisViewClusterPickResult extends GisViewCluster {
+	type: 'cluster'
+	index: -1
+	item: null
+	distance: number
+	selected: boolean
+	wasSelected: boolean
+	lngLat?: [number, number]
+}
+
+/** pick / pickAt / hover 可能拿到普通要素或聚合圆。 */
+export type GisViewHitResult = GisViewPickResult | GisViewClusterPickResult
+
+/** action.data 里的聚合读数：不带 action 自身，避免载荷循环引用。 */
+export interface GisViewClusterPointerData extends GisViewCluster {
+	type: 'cluster'
+}
+
+/** 聚合数量文字：覆盖层每帧只需要位置、半径与数量。 */
+export interface GisViewClusterLabel {
+	id: string
+	count: number
+	screen: [number, number]
+	radius: number
+}
+
+/** onClusterClick / clusterClick 的载荷：与点击载荷同一套指针字段，但不带普通要素的 item。 */
+export type GisViewClusterClickPayload = GisViewClusterPickResult & {
+	button?: number
+	buttons?: number
+	originalEvent: Event
+	selection: GisViewSelectionInfo
+	action: GisViewPointerAction
+}
+
 /** 选中事件载荷：点击选中为 0 / 1 个要素，Shift 框选为框内全部节点（随 shortcuts.boxSelect 改变） */
 export interface GisViewSelectPayload {
 	items: GisViewPickResult[]
@@ -2589,11 +2718,11 @@ export interface GisViewSelectionInfo {
  *    `{ channelId, lineIds: [...] }` / `{ channelIndex, lineIndexes: [...] }` 只取通道里的某几条回线。
  */
 export interface GisViewSelectionRefObject {
-	/** 要素类型；写 'channel'（或写了 channelId / channelIndex / channel）就是通道写法 */
-	type?: GisViewFeatureType | 'channel'
-	/** 搜索命中的类型（与 type 一个意思，point / line / channel 都认）：搜索命中可以直接丢给 select */
-	kind?: GisViewFeatureType | 'channel'
-	/** 要素 id；type / kind 是通道时它就是这个通道的 id */
+	/** 要素类型；写 'channel'（或写了 channelId / channelIndex / channel）就是通道写法，写 'group' 是分组写法 */
+	type?: GisViewFeatureType | 'channel' | 'group'
+	/** 搜索命中的类型（与 type 一个意思，point / line / channel / group 都认）；type 是 group 时 id 就是分组 id */
+	kind?: GisViewFeatureType | 'channel' | 'group'
+	/** 要素 id；type / kind 是通道时它就是这个通道的 id，是分组时是分组 id */
 	id?: string | number
 	/** 要素在 points / lines 里的下标；通道写法里是通道下标 */
 	index?: number
@@ -2602,8 +2731,12 @@ export interface GisViewSelectionRefObject {
 	channelId?: string | number
 	channelIndex?: number
 	channel?: string | number | GisViewChannel
+	/** 分组上下文（getLineChannel 的 group 可以直接放进来） */
+	group?: string | number | { id?: string | number }
 	/** 只要通道里的某一组 */
 	groupId?: string | number | null
+	/** groupId 的 snake_case 别名 */
+	group_id?: string | number
 	/** 只要通道里的某几组 */
 	groupIds?: Array<string | number>
 	/** 只要通道里的某一条 / 某几条回线（按 id 或 lines 下标） */
@@ -2753,7 +2886,7 @@ export interface GisViewClickPayload extends GisViewPickResult {
 	selection: GisViewSelectionInfo
 	/**
 	 * 这一次点击的判读：type 为 'select'（点中要素、选中已生效）或 'click'（没开选中时的普通点击），
-	 * double 为 true 说明这一下是双击里的第二下。点空白处的载荷是 null，
+	 * 多选取反生效时是 'toggleSelect'；double 为 true 说明这一下是双击里的第二下。点空白处的载荷是 null，
 	 * 「点了空白」这件事看 onPointerDown / onPointerUp 的 action.target（'empty'）与 selectChange。
 	 */
 	action: GisViewPointerAction
@@ -2764,7 +2897,7 @@ export interface GisViewClickPayload extends GisViewPickResult {
  * 'waypoint'（线路拐点）/ 'label'（标签）/ 'selection'（一整批选中集，只有 selectChange 用）/ 'empty'（空白）。
  * 与载荷里的 type 差一层：通道回线的 type 也是 'line'，但按通道处理的多，target 单独给一个 'channel'。
  */
-export type GisViewPointerTarget = 'point' | 'line' | 'channel' | 'waypoint' | 'label' | 'selection' | 'empty'
+export type GisViewPointerTarget = 'point' | 'line' | 'channel' | 'cluster' | 'waypoint' | 'label' | 'selection' | 'empty'
 
 /**
  * 一次指针操作的动作名。同一个名字在「按下 / 松开 / 点击」三条事件里含义略有不同：
@@ -2786,6 +2919,7 @@ export type GisViewPointerActionType =
 	| 'selectWaypoint'
 	| 'dragWaypoint'
 	| 'dragPoint'
+	| 'clusterClick'
 	| 'dragLabel'
 	| 'selectLabel'
 	| 'contextMenu'
@@ -2830,7 +2964,7 @@ export interface GisViewPointerAction {
 	 * 通道回线是通道定义、选中集事件是这一批 items、拐点是「哪条线、第几个顶点、坐标、改完的线」，
 	 * 空白处是 null（拐点那一份见 GisViewWaypointPayload.action.data、标签那一份见 GisViewLabelActionData）。
 	 */
-	data?: GisViewPoint | GisViewLine | GisViewChannel | GisViewPickResult[] | GisViewWaypointActionData | GisViewLabelActionData | null
+	data?: GisViewPoint | GisViewLine | GisViewChannel | GisViewClusterPointerData | GisViewPickResult[] | GisViewWaypointActionData | GisViewLabelActionData | null
 	/** 只在 click 载荷里出现：true 说明这一下是双击里的第二下（单双击要分开做事的界面按它推迟一下） */
 	double?: boolean
 	/**
@@ -2869,8 +3003,8 @@ export interface GisViewPointerPayload {
 	 * target 说明点的是点 / 线 / 通道 / 空白，data 直接给到那一份数据（左键 / 右键都认这一份）
 	 */
 	action: GisViewPointerAction
-	/** 命中的要素类型，空白处为 null */
-	type: GisViewFeatureType | null
+	/** 命中的要素类型，空白处为 null；多成员聚合是 'cluster' */
+	type: GisViewFeatureType | 'cluster' | null
 	/** 命中的要素在数据里的下标，空白处为 -1 */
 	index: number
 	/** 有没有命中要素 */
@@ -2881,6 +3015,9 @@ export interface GisViewPointerPayload {
 	screen?: [number, number]
 	/** 命中的要素自身的世界坐标 */
 	coordinate?: [number, number]
+	/** 命中的是线路（含通道回线）时，线路在 lines 数组里的下标与 id；右键菜单按它找线路 */
+	lineIndex?: number
+	lineId?: string | number
 	/** 命中的是通道内的回线时，回线所属通道与分组 */
 	channelIndex?: number
 	channel?: GisViewChannel
@@ -2888,6 +3025,15 @@ export interface GisViewPointerPayload {
 	groupIndex?: number
 	/** 命中的是通道内的回线时，这一组的读数 */
 	group?: GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }
+	/** 命中通道回线时的分组上下文：action.target 为 channel，按它直接渲染通道菜单 */
+	channelContext?: GisViewChannelContext
+	/** 命中多成员聚合时：聚合 id、成员数、成员下标 / id、包围盒与屏幕半径 */
+	id?: string
+	count?: number
+	pointIndexes?: number[]
+	pointIds?: Array<string | number>
+	bounds?: GisViewBounds
+	radius?: number
 	/**
 	 * 这一刻命中的要素在不在当前选中集里（没有命中就是 false）。
 	 * 左键按下 / 抬起与右键都是当下这一份状态：selected 与 wasSelected 相同
@@ -2918,7 +3064,7 @@ export interface GisViewPointerPayload {
  * 另外带一份 action（type 恒为 'hover'、target 说明停在什么上面、button 恒为 'none'）。
  * 光标正好停在最近一次指针事件的位置上时，originalEvent / clientX / clientY 就是那一次事件（修饰键读得到）。
  */
-export interface GisViewHoverPayload extends GisViewPickResult {
+export type GisViewHoverPayload = GisViewHitResult & {
 	/** 悬停读数一样有：有没有停在某个要素上（空白处是 null，不走这一份） */
 	hit: boolean
 	action: GisViewPointerAction
@@ -3535,6 +3681,8 @@ export type GisViewDataChangeType =
 	| 'addLines'
 	| 'removePoints'
 	| 'removeLines'
+	/** 删除型筛选（filter.mode: 'remove'）把不命中的要素从数据里删掉 */
+	| 'filterRemove'
 	| 'removeSelected'
 	| 'removeLine'
 	| 'removeChannel'
@@ -3558,6 +3706,8 @@ export interface GisViewDataChangePayload {
 	/** 动到 / 删掉的节点下标（单点更新是那一个，删除是删除前的下标升序，新增是它们在数组里的位置） */
 	index?: number
 	indexes?: number[]
+	/** 这一次删掉的节点下标（删除前它们在 points 里的位置，升序；removeSelected / filterRemove 会带上） */
+	pointIndexes?: number[]
 	/** 这一次调用成没成（addPoints / addLines / removePoints 这类批量接口会带上） */
 	ok?: boolean
 	/** 新增这类动作：这批要素是从哪个下标开始接上去的（就是追加前原数组的长度） */
@@ -3607,8 +3757,14 @@ export interface GisViewDataChangePayload {
 	lineIndex?: number
 	channelId?: string | number | null
 	channelIndex?: number
+	/** filterRemove：这次从数据里删掉的节点数据，顺序与 pointIndexes 对应 */
+	removedPoints?: GisViewPoint[]
+	/** filterRemove：这次从数据里删掉的线路数据，顺序与 removedLineIndexes 对应 */
+	removedLineItems?: GisViewLine[]
 	removedLineIds?: Array<string | number>
 	removedLineIndexes?: number[]
+	/** filterRemove：固定为 'remove'，便于按载荷分流 */
+	mode?: GisViewFilterMode
 	/** 通道分组：这条通道最新的分组声明 */
 	groups?: GisViewChannelGroup[]
 	replaced?: boolean
@@ -3655,6 +3811,12 @@ export interface GisViewEngineStats {
 	lineEffectCount: number
 	/** 这一帧铺进去的节点涟漪圈数（一个节点 count 圈算 count；关掉或视野内没有涟漪时为 0） */
 	pointEffectCount: number
+	/** 当前点聚合的多成员圆个数；聚合关闭或超过 maxZoom 时为 0 */
+	clusterCount: number
+	/** 被收进多成员聚合圆的原始点数：展示点数 = pointCount - clusterPointCount + clusterCount */
+	clusterPointCount: number
+	/** 最近一次聚合重算耗时（毫秒）；聚合关闭时为 0 */
+	clusterMs: number
 	/** 动画是否还在排下一帧：静止画面是按需渲染的，这时候是 false */
 	animating: boolean
 	quality: GisViewQualityState
@@ -4734,19 +4896,29 @@ export interface GisViewTooltipOptions {
  */
 export type GisViewFilterCascade = false | 'binding' | 'coordinate' | 'both'
 
-/** 筛选条件：点、线各一个条件，缺省表示该维度不过滤 */
+/** 筛选模式：hide 只隐藏（缺省）；remove 把不命中的要素从数据里删掉（不可恢复，除非撤销） */
+export type GisViewFilterMode = 'hide' | 'remove'
+
+/**
+ * 筛选条件：点、线各一个条件，缺省表示该维度不过滤。
+ * 缺省 mode: 'hide' 只算「隐藏集合」，不改数据；已经选中的要素被隐藏后仍留在选中集里，
+ * 条件放宽 / 清空后会原样恢复高亮。mode: 'remove' 把筛选结果（hiddenPoints / hiddenLines）
+ * 真正从数据里删掉（走 dataChange('filterRemove')，可用撤销恢复；不会额外按节点联级删线路）。
+ */
 export interface GisViewFilter {
 	points?: GisViewConditionInput<GisViewPoint>
 	lines?: GisViewConditionInput<GisViewLine>
 	/** 联动隐藏，默认 binding */
 	cascade?: GisViewFilterCascade
+	/** 不命中的要素怎么处理：'hide' 只隐藏（默认），'remove' 从数据里删除 */
+	mode?: GisViewFilterMode
 	/** 是否用 Worker 计算，缺省跟随 options.filterWorker */
 	worker?: boolean
 }
 
 /**
  * 筛选条件的简写：只筛节点时可以直接给节点条件，等价于 `{ points: 条件 }`：
- * `view.setFilter({ vn_kv: { gte: 525 } })`。顶层出现 points / lines / cascade / worker
+ * `view.setFilter({ vn_kv: { gte: 525 } })`。顶层出现 points / lines / cascade / mode / worker
  * 任一键时按完整格式解释，因此简写里可以放心使用业务字段名。
  */
 export type GisViewFilterShorthand = GisViewConditionInput<GisViewPoint>
@@ -4754,7 +4926,7 @@ export type GisViewFilterShorthand = GisViewConditionInput<GisViewPoint>
 /** setFilter / options.filter 接受的条件：完整格式，或只筛节点的简写 */
 export type GisViewFilterInput = GisViewFilter | GisViewFilterShorthand
 
-/** 筛选结果：hiddenPoints / hiddenLines 是当前被隐藏的要素下标 */
+/** 筛选结果：hiddenPoints / hiddenLines 是当前被隐藏的要素下标；remove 模式删除完会回到空数组 */
 export interface GisViewFilterResult {
 	filter: GisViewFilter | null
 	hiddenPoints: number[]
@@ -5041,6 +5213,18 @@ export interface GisViewInitialView {
 	padding?: number
 }
 
+/**
+ * 适应视图的节点间距兜底：普通「铺满数据范围」让最近节点在屏幕上挤在一起时，
+ * 按 minDistance 反推一个更高的相机比例。放大时以最近节点对的中点为中心，
+ * 远处孤立点可以把包围盒撑大，但不再把主体节点压成一团，也允许落到视口外。
+ */
+export interface GisViewFitSpacingOptions {
+	/** 可见节点中心之间的最小屏幕距离（CSS 像素），默认 24；写 0 或负数关闭 */
+	minDistance?: number
+	/** 相对普通适应比例的最大放大倍数，默认 0（不限，只受 maxScale 约束）；正数表示上限 */
+	maxZoom?: number
+}
+
 /**
  * 插件：视图建好之后调用一次，拿到实例本身与带 apiVersion 的上下文；返回 { destroy } 时会挂进实例的 destroy。
  * 写一次插件，之后换项目直接复用，不必把「URL 同步 / 自建图例 / 业务操作」再抄一遍。
@@ -5054,6 +5238,24 @@ export interface GisViewPluginContext {
 
 export type GisViewPlugin = (view: GisViewInstance, context: GisViewPluginContext) => void | { destroy?: () => void }
 
+/** 实例命令的上下文：注册表属于这个视图，handler 里拿它就能继续调实例方法 */
+export interface GisViewCommandContext {
+	readonly view: GisViewInstance
+	/** 这次执行注册时用的命令名（已去掉首尾空白） */
+	readonly name: string
+}
+
+/** 实例命令：同步执行；返回值原样放进 GisViewCommandResult.value */
+export type GisViewCommandHandler<Payload = unknown, Value = unknown> = (payload: Payload, context: GisViewCommandContext) => Value
+
+/** executeCommand 的读数：拿到命令并执行成功时 ok: true；没注册 / 名字非法 / handler 抛错时 ok: false 并给原因 */
+export interface GisViewCommandResult<Value = unknown> {
+	readonly ok: boolean
+	readonly name: string
+	readonly value?: Value
+	readonly reason?: string
+}
+
 /**
  * 快捷键写法（大小写不敏感，多个用 + 连接）：
  * - 纯修饰键：`ctrl` / `meta` / `shift` / `alt` / `mod`（`ctrl` 同时认 macOS 的 ⌘），按住 + 操作；
@@ -5501,8 +5703,6 @@ export type GisViewFeatureName =
 	| 'remove'
 	/** 新增通道：进入草稿、点两个节点、落地 */
 	| 'channelDraft'
-	/** 通道右键交互框（onChannelContextMenu） */
-	| 'channelMenu'
 	/** 右键回调 onContextMenu（关掉之后组件不再拦右键，浏览器菜单照常） */
 	| 'contextMenu'
 	/** 悬停提示（tooltip）：关掉只影响提示，悬停样式与 onHover 还在 */
@@ -5678,7 +5878,7 @@ export interface GisViewBatchOptions {
 /**
  * 全部可订阅事件（与 EVENT_NAMES 一致）：事件名与 options 里的回调一一对应（`dataChange` 就是 `onDataChange`），
  * 载荷也是同一份 —— 区别只在写法：`on` 可以挂多条、可以运行时订阅、返回的函数就是取消订阅。
- * 需要原样带回 DOM 事件的那四个（pointerDown / pointerUp / contextMenu / channelContextMenu）载荷是
+ * 需要原样带回 DOM 事件的那三个（pointerDown / pointerUp / contextMenu）载荷是
  * `{ payload, event }`，与回调的两个参数一一对应。
  */
 export interface GisViewEventMap {
@@ -5698,6 +5898,8 @@ export interface GisViewEventMap {
 	pointerUp: { payload: GisViewPointerPayload; event: PointerEvent }
 	contextMenu: { payload: GisViewPointerPayload; event: MouseEvent }
 	click: GisViewClickPayload
+	/** 点中多成员聚合圆：不选中内部节点，普通 click 不会同时触发 */
+	clusterClick: GisViewClusterClickPayload
 	dblClick: GisViewClickPayload
 	/** 点了一下标签（label.editable / lineLabel.editable 打开时）：用它选中要编辑的那一条 */
 	labelClick: GisViewLabelClickPayload
@@ -5711,13 +5913,14 @@ export interface GisViewEventMap {
 	labelDblClick: GisViewLabelPointerPayload
 	select: GisViewSelectPayload | null
 	selectChange: GisViewSelectChangePayload
+	/** 点击级联高亮变了：载荷与 getCascadeHighlight() 同一份，收掉时是 null */
+	cascadeHighlight: GisViewCascadeHighlightInfo | null
 	pointDrag: GisViewPointDragPayload
 	pointCopy: GisViewPointCopyPayload | GisViewBatchCopyPayload
 	pointMerge: GisViewPointMergePayload | GisViewMergeResult | GisViewMergeFailure | GisViewMergeSelectedPayload
 	/** 删除：pending（要删什么 / 连带什么 / 能按哪些范围删）→ remove（已删，result 是结果）/ cancel */
 	remove: GisViewRemovePayload
 	waypointChange: GisViewWaypointPayload
-	channelContextMenu: { payload: GisViewChannelContextPayload | null; event: MouseEvent }
 	channelDraft: GisViewChannelDraftPayload
 	channelDraftClick: GisViewChannelDraftPayload
 	/** 动态装饰器草稿：start / hover / leave / ready / update / commit / cancel */
@@ -5860,6 +6063,12 @@ export interface GisViewWebGLLayer {
 	draw(context: GisViewWebGLLayerDrawContext): void
 }
 
+/**
+ * 选中触发方式：'click'（缺省）在第一次单击时改选中集；'dblClick' 等到双击的第二下才改，
+ * 第一下仍照常派发 onClick。两种方式下 onDblClick 都会在双击第二下派发。
+ */
+export type GisViewSelectTrigger = 'click' | 'dblClick'
+
 export interface GisViewOptions {
 	/**
 	 * 功能开关：预设名（'edit' / 'view' / 'static'）、开关表或布尔值 ——
@@ -5984,10 +6193,12 @@ export interface GisViewOptions {
 	 * 纯文本标签的渲染方式，缺省 `auto`：
 	 * - `auto`：强制显示档下，视口里的纯文本标签达到 1024 条时自动改画到单张 Canvas；
 	 *   需要 DOM 的标签（`html: true`、函数返回元素、可拖拽 / 可编辑）仍逐条建节点。
+	 * - `canvas`：纯文本标签始终改画到单张 Canvas，不受 1024 条阈值限制，`labelOptimize: true` 时
+	 *   也按画布尺寸参与避让 / 换落点；需要 DOM 的标签仍逐条建节点。
 	 * - `dom`：始终逐条建 `.gis-view__label`，保持旧行为。
 	 * 画布档不改变标签内容、锚点与显隐，只减少高密度场景的 DOM 数量。
 	 */
-	labelRender?: 'auto' | 'dom'
+	labelRender?: 'auto' | 'canvas' | 'dom'
 	/**
 	 * 标签的运行时状态（`getLabelStates()` 的那一份：拖过的偏移、改过的内容与样式、运行时加的标签、隐藏覆盖）：
 	 * 创建 / `updateOptions` 时喂回来就回显，与 `setLabelStates(states)` 同一条路。
@@ -6004,6 +6215,12 @@ export interface GisViewOptions {
 	tooltip?: GisViewTooltipOptions
 	/** 初始筛选条件，等价于创建之后调用 setFilter；可以写完整格式，也可以只给节点条件 */
 	filter?: GisViewFilterInput | null
+	/**
+	 * 线路是否跟随节点，默认 true。开启时隐藏 / 删除 / 筛选节点会连带绑定线路与通道；
+	 * 关闭后这些操作只影响节点，线路与通道继续停在节点最后一次坐标，筛选未显式写 cascade 时默认不级联。
+	 * 筛选里显式写了 cascade 时始终以筛选自己的写法为准。
+	 */
+	lineFollowsNode?: boolean
 	/** 内置鹰眼图：不配就不显示，配了默认开 */
 	minimap?: GisViewMinimapOptions | null
 	/** 筛选是否用 Worker 计算：默认在数据量超过阈值时自动启用，false 表示始终同步计算 */
@@ -6028,6 +6245,12 @@ export interface GisViewOptions {
 	lineSelectStyle?: GisViewLineStyle
 	/** Ctrl 点击累加多选时的线样式：缺省沿用 lineSelectStyle，单条线可用 multiSelectStyle 覆盖 */
 	lineMultiSelectStyle?: GisViewLineStyle
+	/**
+	 * 点击级联高亮（默认关）：点击节点时亮起它和直接相连的节点；scope 为 both 时连线路一起亮，
+	 * 点击线路 / 通道回线时亮起两端节点。它不进选中集，样式与悬停 / 选中分开配置，
+	 * 当前亮起的清单用 getCascadeHighlight() 读。
+	 */
+	cascadeHighlight?: GisViewCascadeHighlightInput
 	/** 没有配置状态样式时，是否仍用尺寸 / 宽度增幅画出内置强调；默认 false（不配样式就不改变外观） */
 	defaultHighlight?: boolean
 	/** 节点整体放大系数（常数倍数，与地图缩放无关，屏幕上的大小因此恒定）：与点自身 size、缩放联动一起相乘，默认 1 */
@@ -6048,17 +6271,18 @@ export interface GisViewOptions {
 	lineZoomScale?: number
 	/** 缩放联动的基准比例：等于它时放大系数为 1，缺省用首次适应视图时的 camera.scale */
 	zoomBaseScale?: number
-	/**
-	 * 自适应比例开关（默认 false）：打开后没写联动指数的 pointZoomScale / lineZoomScale 按 1 算 ——
-	 * 要素与地图同倍率，包围盒变大（相机比例变小）时节点 / 线宽跟着一起小，
-	 * 节点大小与通道间距的比例不再被带跑；显式写过指数（哪怕写 0）以显式值为准。
-	 */
-	zoomScaleAuto?: boolean
 	/**
 	 * 大数据初始化是否从视图中心向外发散渲染（默认开）。
 	 * 开启后首屏只排中心附近的那一批，剩下的分帧往外补；关了就一次性排完。
 	 */
 	progressiveInit?: boolean
+	/**
+	 * 点聚合：true 用缺省档（半径 60px、至少 2 点、不限缩放），对象写法见 GisViewPointClusterOptions。
+	 * 只影响展示、拾取、快照与导出；原始 points、选中集与 getData() 不变，
+	 * listPoints({ visibleOnly: true }) 会跳过被聚合圆收起的成员，传 false 仍可列全。
+	 * 聚合期间发散初始化暂停；缩放超过 maxZoom 后恢复逐点显示。
+	 */
+	pointCluster?: boolean | GisViewPointClusterOptions
 	/** 是否绘制网格：与其它功能开关同一条口径，**缺省关**，写 showGrid: true 才画 */
 	showGrid?: boolean
 	gridColor?: string
@@ -6108,6 +6332,12 @@ export interface GisViewOptions {
 	 * 关着时多选仍走框选（boxSelect）与按住多选快捷键（默认 Ctrl / ⌘）。
 	 */
 	multiSelect?: boolean
+	/**
+	 * 选中触发方式：缺省 'click'（单击选中）；写 'dblClick' 后第一次点击只派发 onClick，
+	 * 第二次（双击判定命中）才更新选中集，并同时派发 onClick 与 onDblClick。
+	 * Ctrl / ⌘ 多选与 multiSelect 在双击模式下同样等到第二下才取反。运行时走 updateOptions({ selectTrigger })。
+	 */
+	selectTrigger?: GisViewSelectTrigger
 	/**
 	 * 框选 / Ctrl 多选允许收哪几类要素：'point' 节点、'line' 独立线路、'channel' 通道回线，
 	 * 可写数组任意组合，'all' / true 全开，false / null 全关。
@@ -6169,6 +6399,11 @@ export interface GisViewOptions {
 	 * zoom 是相对「适应视图」的倍数（2 = 比适应近一倍），scale 是绝对的 像素 / 世界单位。
 	 */
 	initialView?: GisViewInitialView | null
+	/**
+	 * 适应视图时按可见节点间距兜底（默认关）：true 用 minDistance 24 / maxZoom 不限，
+	 * 对象可改两个参数。只在首次默认适应与 fitView() 生效，显式 initialView.scale / zoom 优先。
+	 */
+	fitSpacing?: boolean | GisViewFitSpacingOptions
 	/**
 	 * onStats 的最小间隔（毫秒），默认 250，0 表示每帧都发。
 	 * 读数不需要 60Hz，节流能省下每帧一次的回调与对象分配（拖拽时尤其明显）。
@@ -6212,6 +6447,8 @@ export interface GisViewOptions {
 	onSelect?: (payload: GisViewSelectPayload | null) => void
 	/** 单击要素或空白处 */
 	onClick?: (payload: GisViewClickPayload | null) => void
+	/** 点中多成员聚合圆：载荷带 count / pointIds / bounds；不会同时触发 onClick，也不改选中集 */
+	onClusterClick?: (payload: GisViewClusterClickPayload, event: Event) => void
 	/** 双击要素或空白处 */
 	onDblClick?: (payload: GisViewClickPayload | null) => void
 	/** 点了一下标签（label.editable / lineLabel.editable 打开时）：载荷里是这一条标签的类型、下标与当前覆盖 */
@@ -6231,8 +6468,13 @@ export interface GisViewOptions {
 	onPointerDown?: (payload: GisViewPointerPayload, event: PointerEvent) => void
 	/** 左键 / 中键 / 右键抬起：与 onPointerDown 成对 */
 	onPointerUp?: (payload: GisViewPointerPayload, event: PointerEvent) => void
-	/** 右键：点、线、空白都会发（要素信息在载荷里，要自己弹菜单就在这里 preventDefault） */
+	/**
+	 * 右键：点、线、通道、空白都会发这一条。命中通道回线时 action.target 为 'channel'，
+	 * 载荷另带 channelContext；要自己弹菜单就在这里 preventDefault()。
+	 */
 	onContextMenu?: (payload: GisViewPointerPayload, event: MouseEvent) => void
+	/** 点击级联高亮变了：载荷与 getCascadeHighlight() 同一份，收掉时是 null */
+	onCascadeHighlight?: (payload: GisViewCascadeHighlightInfo | null) => void
 	onHover?: (payload: GisViewHoverPayload) => void
 	onCursor?: (payload: GisViewCursorPayload) => void
 	/** 光标移动 / 移出画布：屏幕坐标、世界坐标与经纬度（配了 GeoJSON 底图才有 lngLat） */
@@ -6258,8 +6500,6 @@ export interface GisViewOptions {
 	onRemove?: (payload: GisViewRemovePayload) => void
 	/** 拐点新增、选中、删除与拖动 */
 	onWaypointChange?: (payload: GisViewWaypointPayload) => void
-	/** 右键点中通道回线：给出分组上下文（几组 / 当前哪组 / 有哪些交互），点空白处给 null */
-	onChannelContextMenu?: (payload: GisViewChannelContextPayload | null, event: MouseEvent) => void
 	/** 新增通道草稿：start / from / to / ready / cancel / commit / blocked，两个节点的信息与方案都在载荷里 */
 	onChannelDraft?: (payload: GisViewChannelDraftPayload) => void
 	/** 草稿里每点一次发一条：step 1 拿到起点、step 2 拿到终点（线路结束），载荷与 onChannelDraft 相同 */
@@ -6320,37 +6560,63 @@ export interface GisViewOptions {
 	onError?: (message: string) => void
 }
 
-/** 搜索范围：节点 / 线路 / 通道（通道会连成员回线一起搜） */
-export type GisViewSearchScope = 'points' | 'lines' | 'channels'
+/** 搜索范围（规范化后的键）：节点 / 线路 / 通道 / 通道分组（通道会连成员回线一起搜） */
+export type GisViewSearchScope = 'points' | 'lines' | 'channels' | 'groups'
+
+/** scope 的入参写法：复数的规范化键，或与 focusOn 目标一致的 point / line / channel / group 单数别名 */
+export type GisViewSearchScopeInput = GisViewSearchScope | 'point' | 'line' | 'channel' | 'group'
 
 export interface GisViewSearchOptions {
 	/** 关键字：空格分隔多个词时要在同一个字段里全部出现才命中，不区分大小写 */
 	keyword?: string
-	/** 搜索范围，缺省三类都搜 */
-	scope?: GisViewSearchScope | GisViewSearchScope[]
+	/**
+	 * 搜索范围，缺省四类都搜。复数的 points / lines / channels / groups 与单数别名
+	 * point / line / channel / group 都收；写错或空数组会回落到四类全搜。
+	 */
+	scope?: GisViewSearchScopeInput | GisViewSearchScopeInput[]
 	/** 限定参与匹配的字段路径（如 ['name', 'props.vn_kv']），缺省用要素的全部字段 */
 	fields?: string[]
 	/** 每类要素的命中上限，缺省 200，0 表示不限 */
 	limit?: number
 }
 
+/**
+ * 分组搜索命中里的 item：与 getChannelGroups() 的读数同源，但只保留搜索与定位需要的轻量字段
+ * （不带骨架 / 回线几何）。groupIndex 是这一组在所属通道里的序号（从 0 起）。
+ */
+export interface GisViewSearchGroupItem {
+	channelId: string | number
+	channelIndex: number
+	id: string | number
+	groupIndex: number
+	lineIndexes: number[]
+	lineIds: Array<string | number>
+	lineCount: number
+	anchored: boolean
+	edited: boolean
+}
+
 /** 一条搜索命中：field / value 是命中的那一项，bounds 用来居中或适应视图 */
 export interface GisViewSearchHit {
-	kind: 'point' | 'line' | 'channel'
-	/** 点 / 线在数据里的下标；通道是通道下标 */
+	kind: 'point' | 'line' | 'channel' | 'group'
+	/** 点 / 线在数据里的下标；通道是通道下标；分组是 groups 结果里的下标 */
 	index: number
 	id?: string | number
-	item: GisViewPoint | GisViewLine | GisViewChannel
+	item: GisViewPoint | GisViewLine | GisViewChannel | GisViewSearchGroupItem
 	field: string
 	value: string
 	bounds: GisViewBounds
-	/** 要素属于某条通道时给出通道下标（线路命中，或通道命中自身字段） */
+	/** 要素属于某条通道时给出通道下标（线路 / 分组命中，或通道命中自身字段） */
 	channelIndex?: number
 	/** 通道内第几条回线（0 开始） */
 	memberIndex?: number
 	/** 通道命中来自回线时，该回线在 lines 里的下标与 id */
 	memberLineIndex?: number
 	memberLineId?: string | number
+	/** 分组命中：分组 id（与 focusOn / selectFeatures 的 groupId 同一口径） */
+	groupId?: string | number
+	/** 分组命中：这一组在所属通道里的序号（从 0 起） */
+	groupIndex?: number
 }
 
 export interface GisViewSearchResult {
@@ -6359,7 +6625,8 @@ export interface GisViewSearchResult {
 	points: GisViewSearchHit[]
 	lines: GisViewSearchHit[]
 	channels: GisViewSearchHit[]
-	/** 三类命中的合集，顺序是节点、线路、通道 */
+	groups: GisViewSearchHit[]
+	/** 四类命中的合集，顺序是节点、线路、通道、分组 */
 	hits: GisViewSearchHit[]
 	total: number
 	/** 命中数达到上限被截断 */
@@ -6374,7 +6641,10 @@ export interface GisViewSearchResult {
 /**
  * focusOn 的目标（一个）：搜索命中、要素写法、世界坐标（两个数 / `[x, y]` / `{ x, y }`）、
  * 一段世界坐标范围、通道写法（取通道范围）、`{ center: [x, y] }` 或 `{ lngLat: [经度, 纬度] }`
- * （配了 GeoJSON 底图才有意义）。
+ * （配了 GeoJSON 底图才有意义）。要素 / 通道 / 分组可以用 `type` 明确消歧：
+ * `{ type: 'point' | 'line' | 'channel', id | index }`、`{ type: 'group', channelId, groupId }`
+ * （group 的 channelId 可省略，只要 groupId 全局唯一）。字符串 / 数字仍按「先节点 id、再线路 id」兼容；
+ * 同 id 时显式写 `type` 即可；裸字符串不表示通道，通道请写 `{ channelId }` 或显式 `type: 'channel'`。
  */
 export type GisViewFocusTarget = GisViewSearchHit | GisViewFeatureKey | GisViewSelectionRefObject | string | number | GisViewCoordinate | GisViewBounds | { x: number, y: number } | { center: GisViewCoordinate } | { lngLat: GisViewCoordinate } | { longitude: number, latitude: number }
 
@@ -6382,13 +6652,15 @@ export type GisViewFocusTarget = GisViewSearchHit | GisViewFeatureKey | GisViewS
 export type GisViewFocusTargets = GisViewFocusTarget | GisViewFocusTarget[]
 
 export interface GisViewFocusOptions {
-	/** 直接设成这个比例（像素 / 世界单位）；不给就按目标范围适应视图 */
+	/** 直接设成这个比例（像素 / 世界单位）；优先级高于 zoom */
 	scale?: number
-	/** 只把中心挪到目标上、比例一点不动（聚焦一个点又不想改缩放时用） */
+	/** 显式要求按目标范围适应视图；**缺省不缩放**，只把中心移到目标上 */
+	zoom?: boolean
+	/** 显式只居中、比例一点不动（与缺省行为一致，保留旧写法） */
 	center?: boolean
-	/** 按范围适应视图时四周的留白（CSS 像素），缺省 40 */
+	/** 按范围适应视图（zoom: true）时四周的留白（CSS 像素），缺省 40 */
 	padding?: number
-	/** 适应视图时最多放大到多少比例：单个节点 / 一条直线没有面积，靠它决定要不要放大 */
+	/** 适应视图（zoom: true）时最多放大到多少比例：单个节点 / 一条直线没有面积，靠它决定要不要放大 */
 	maxZoom?: number
 	/**
 	 * 顺手把这些被聚焦的要素变成选中状态：`true` 选中这次聚焦的这批（通常配合搜索命中），
@@ -6411,6 +6683,13 @@ export interface GisViewExportImageOptions {
 	quality?: number
 	/** 导出倍率：位图相对画布 CSS 尺寸，缺省按设备像素比导（与屏幕一致）；SVG 只影响宽高属性，缺省 1 */
 	scale?: number
+	/**
+	 * 导出范围：'viewport'（缺省）只导当前可视区域；'all' 临时适应全部数据范围，导完恢复原相机。
+	 * 筛选 / visible: false 隐藏的要素仍不会出现；'all' 指当前场景里全部可见内容
+	 */
+	scope?: 'viewport' | 'all'
+	/** scope: 'all' 时四周留白（CSS 像素，缺省 24）；scope: 'viewport' 时忽略 */
+	padding?: number
 	/**
 	 * 背景：缺省 = 带背景（背景色 / 底图 / GeoJSON 区域填充与网格，与屏幕上一致）；
 	 * false / 'none' / 'transparent' = 不带背景（透明底，上面那些都不画）；
@@ -6961,6 +7240,20 @@ export interface GisViewSceneGraphic {
 	preserveAspectRatio: string
 }
 
+/** 矢量快照里的多成员聚合圆（数量文字也在这里；单成员不画圆） */
+export interface GisViewSceneCluster {
+	id: string
+	count: number
+	x: number
+	y: number
+	radius: number
+	fill: string
+	stroke: string
+	strokeWidth: number
+	textColor: string
+	fontSize: number
+}
+
 export interface GisViewSceneSnapshot {
 	width: number
 	height: number
@@ -6974,6 +7267,7 @@ export interface GisViewSceneSnapshot {
 	/** 数据线路与节点装饰连接线（连接线也画在节点 / 装饰之前） */
 	lines: GisViewSceneLine[]
 	points: GisViewSceneNode[]
+	clusters: GisViewSceneCluster[]
 	backgroundPoints: GisViewSceneNode[]
 	decorations: GisViewSceneNode[]
 	waypoints: GisViewSceneNode[]
@@ -7194,7 +7488,7 @@ export interface GisViewInstance {
 	setCamera(camera: Partial<GisViewCamera>): GisViewInstance
 	getCamera(): GisViewCamera
 	getBounds(): GisViewBounds
-	/** 缩放联动的基准比例（pointZoomScale / lineZoomScale / zoomScaleAuto 共用那一份）：缺省是首次适应视图时的 camera.scale */
+	/** 缩放联动的基准比例（pointZoomScale / lineZoomScale 共用那一份）：缺省是首次适应视图时的 camera.scale */
 	getZoomBaseScale(): number
 	/** 重定缩放联动的基准比例：不传就取当下相机的比例（把现在这一屏当成「原样大小」），之后放大缩小都从它算倍数，返回 this */
 	setZoomBaseScale(scale?: number): GisViewInstance
@@ -7279,7 +7573,7 @@ export interface GisViewInstance {
 	createGeoMapper(options?: GisViewGeoMapperOptions): GisViewGeoMapper | null
 	/** 直接把一份点 / 线 / 通道数据映射到 GeoJSON 坐标上（复制，不改原数据）；没有 GeoJSON 底图时是 null */
 	mapDataToGeoJson<T extends { points?: GisViewPoint[]; lines?: GisViewLine[]; channels?: GisViewChannel[] }>(data: T, options?: GisViewGeoMapperOptions): T | null
-	pick(x: number, y: number): GisViewPickResult | null
+	pick(x: number, y: number): GisViewHitResult | null
 	/**
 	 * 按浏览器客户端坐标拾取（鼠标事件里的 clientX / clientY）：与指针事件载荷同一份读数，另加 target
 	 * （'point' / 'line' / 'channel'）与 lngLat（配了 GeoJSON 底图才有）；没命中返回 null。
@@ -7315,11 +7609,19 @@ export interface GisViewInstance {
 	 * getSelectionData 立刻就能读回来。认这些写法（见 GisViewSelectionRef）：
 	 * ① 节点：id、`{ type: 'point', index: 3 }`、一批 id 与对象混着写；
 	 * ② 通道：`{ type: 'channel', channelId: 'channel-a' }` 选整条通道的回线，
-	 *    `{ channelId, groupId }` 选某一组，`{ channelId, lineIds: [...] }` 选通道里的某几条回线；
+	 *    `{ channelId, groupId }` / `{ type: 'group', channelId, groupId }` 选某一组
+	 *    （只给全局唯一的 groupId 也可以），`{ channelId, lineIds: [...] }` 选通道里的某几条回线；
 	 * ③ 线路：id 或 `{ type: 'line', index: 3 }`。
 	 * options.mode 给 'add' / 'toggle' / 'remove' 就在当前选中集上做加 / 取反 / 减
 	 */
 	selectFeatures(refs: GisViewSelectionRefs, options?: GisViewSelectOptions): GisViewInstance
+	/**
+	 * 选中一个拐点：`selectWaypoint('line-1', 2)` / `selectWaypoint({ lineIndex: 3, pathIndex: 1 })` /
+	 * `selectWaypoint({ lineId: 'line-1', pathIndex: 2 })`。同时把拐点所在线路选上（缺省
+	 * `waypointVisibility: 'selected'` 下拐点才可见）；`selectWaypoint(null)` 只取消拐点选中，
+	 * 不改要素选中集。`pathIndex` 只认 `getWaypoints()` 给出的可编辑拐点，无效时不会猜位置。
+	 */
+	selectWaypoint(waypoint: GisViewWaypointKey | GisViewWaypointRef | string | number | null, pathIndex?: number, options?: GisViewSelectOptions): GisViewInstance
 	/**
 	 * 取消选中：写法与 selectFeatures 完全一样（节点 / 通道 / 线路，一批可以混着写），
 	 * 把这些从当前选中集里去掉，其余选中原样留着 —— `deselect('p-1')` 取消一个节点、
@@ -7345,6 +7647,11 @@ export interface GisViewInstance {
 	 * bounds 走一次 getElementBounds（十万级选中下约 5 ms），只想问「选了哪几个」用 getSelections() 更省
 	 */
 	getSelectionData(): GisViewSelectionData
+	/**
+	 * 当前点击级联高亮的读数：来源、scope 与亮着的节点 / 线路；没有级联高亮（或功能关着）时是 null。
+	 * 它只读，不改变选中集；点空白处、换数据或关掉 cascadeHighlight 会收掉。
+	 */
+	getCascadeHighlight(): GisViewCascadeHighlightInfo | null
 	/** 按画布 CSS 像素矩形框选；options.selectionKinds 可临时覆盖全局类型过滤 */
 	selectInBox(box: GisViewRect, options?: GisViewSelectInBoxOptions): GisViewInstance
 	/**
@@ -7530,7 +7837,8 @@ export interface GisViewInstance {
 	/** 执行右键交互框里的动作，返回执行之后的上下文 */
 	runChannelAction(actionId: GisViewChannelActionId, options?: { channelId?: string | number; groupId?: string | number; coordinate?: GisViewCoordinate; pathIndex?: number; size?: number }): GisViewChannelContext | null
 	/**
-	 * 进入「新增通道」：点第一个节点当起点，一条线跟随光标，点第二个节点发结束事件
+	 * 进入「新增通道」：缺省点第一个节点当起点，一条线跟随光标，点第二个节点发结束事件；
+	 * options.from 可以预指定起点，此后只需要再选终点
 	 * （phase: 'ready'，载荷里带两个节点、hasChannel / hasGroup / groups / channel 与可选方案）。
 	 * 它只负责这条可视化示例路径 —— 真正的落地必须用 addChannel（或 addChannelGroupLines /
 	 * joinChannelGroupLines / addLine），不在事件里落地就用 endAddChannel / cancelAddChannel 收掉假通道。
@@ -7798,6 +8106,10 @@ export interface GisViewInstance {
 	getChannel(ref: GisViewFeatureRef): GisViewChannelSnapshot | null
 	/** 按条件列节点快照（indexes / inView / limit / withScreen / visibleOnly）：可见点读数的通用入口 */
 	listPoints(options?: GisViewListOptions): GisViewListedPoint[]
+	/** 当前点聚合的展示组（含 count: 1 的单成员）：只读，原始 points / getData() 不变 */
+	getClusters(): GisViewCluster[]
+	/** 当前点聚合配置与运行时开关（缩放超过 maxZoom 后 active 为 false） */
+	getPointCluster(): GisViewPointClusterReadout | null
 	/** 按条件列线路快照（与 listPoints 同一套选项）：通道回线带通道读数，另有 color / width */
 	listLines(options?: GisViewListOptions): GisViewListedLine[]
 	/** 一批要素的世界包围盒；一个都没对上（数据已经换过）返回 null */
@@ -7850,6 +8162,16 @@ export interface GisViewInstance {
 	 * 调它就把这个插件返回的 `destroy` 清掉（重复调用只清一次；实例销毁之后再调也安全）
 	 */
 	use(plugin: GisViewPlugin): () => void
+	/**
+	 * 注册一个实例命令：`handler(payload, context)` 同步执行，`context.view` 就是这个视图。
+	 * 同名覆盖（后注册的生效）；返回幂等的注销函数，同名被后注册覆盖后旧卸载函数不会误删新命令。
+	 * 名字空 / handler 不是函数只报一条 onWarning；实例销毁后注册不生效。
+	 */
+	registerCommand<Payload = unknown, Value = unknown>(name: string, handler: GisViewCommandHandler<Payload, Value>): () => void
+	/** 执行一个实例命令：成功给 `{ ok: true, name, value }`；没注册 / 名字非法 / handler 抛错给 `{ ok: false, name, reason }` */
+	executeCommand<Value = unknown>(name: string, payload?: unknown): GisViewCommandResult<Value>
+	/** 当前注册着哪些实例命令（按注册顺序；同名覆盖不改变原来的位置） */
+	listCommands(): string[]
 	/**
 	 * 注册一个自定义图元：名字写进数据的 `symbol` 字段（`symbol: '三角'`），画法交给一支画笔
 	 * （`painter(context, info)`，读数见 `GisViewSymbolPainterInfo`）。注册完（或换一支画笔之后）
@@ -7958,6 +8280,8 @@ export interface GisViewEngineOptions {
 	lineSelectStyle?: GisViewLineStyle | null
 	/** Ctrl 点击累加多选时的线样式：缺省沿用 lineSelectStyle */
 	lineMultiSelectStyle?: GisViewLineStyle | null
+	/** 点击级联高亮：true / 对象打开，false / null 关闭；详细写法见 GisViewOptions.cascadeHighlight */
+	cascadeHighlight?: GisViewCascadeHighlightInput | null
 	/** 没有配置状态样式时是否仍画内置强调（尺寸 / 宽度增幅与强调环）；默认 false */
 	defaultHighlight?: boolean
 	/** 节点整体放大系数，默认 1 */
@@ -7970,12 +8294,14 @@ export interface GisViewEngineOptions {
 	lineZoomScale?: number
 	/** 缩放联动的基准比例，缺省用首次适应视图时的 camera.scale */
 	zoomBaseScale?: number
-	/** 自适应比例开关：没写联动指数的那几项按 1（与地图同倍率）算，默认 false */
-	zoomScaleAuto?: boolean
 	/** 大数据初始化是否从视图中心向外发散渲染，默认开 */
 	progressiveInit?: boolean
+	/** 点聚合：true 用缺省档，对象写法见 GisViewPointClusterOptions（只改展示 / 拾取 / 快照） */
+	pointCluster?: boolean | GisViewPointClusterOptions
 	/** 初始视图：首次拿到数据时相机落在哪里（缺省适应数据范围），结构见 GisViewInitialView */
 	initialView?: GisViewInitialView | null
+	/** 适应视图的节点间距兜底：true 用缺省档，对象可改 minDistance / maxZoom，默认关 */
+	fitSpacing?: boolean | GisViewFitSpacingOptions
 	/** onStats 的最小间隔（毫秒），默认 250，0 表示每帧都发 */
 	statsInterval?: number
 	/** 画质：档位名或 `{ mode, budgetMs, minScale }`（见 GisViewQualityOptions），只影响画哪些批次与分辨率 */
@@ -7997,10 +8323,12 @@ export interface GisViewEngineOptions {
 	zoom?: boolean
 	hover?: boolean
 	select?: boolean
+	/** 选中触发方式：'click'（缺省）或 'dblClick'，见 GisViewSelectTrigger */
+	selectTrigger?: GisViewSelectTrigger
 	contextMenu?: boolean
 	/**
 	 * 右键默认把浏览器的系统菜单收掉（组件接住右键时 preventDefault contextmenu）。
-	 * 写 false 保留系统菜单：onContextMenu / onChannelContextMenu 照常发，只是不再挡浏览器自己弹菜单。
+	 * 写 false 保留系统菜单：onContextMenu 照常发，只是不再挡浏览器自己弹菜单。
 	 */
 	preventContextMenu?: boolean
 	/** 悬停拾取的移动阈值（CSS 像素）：指针移动不超过它时不重算拾取，0 表示每次指针事件都重算；默认 2 */
@@ -8028,6 +8356,8 @@ export interface GisViewEngineOptions {
 	channelSelectMode?: GisViewChannelSelectMode
 	/** 分组拐点拖动模式：'parallel'（缺省）/ 'vertex'，见 GisViewOptions.channelWaypointDragMode */
 	channelWaypointDragMode?: GisViewChannelWaypointDragMode
+	/** 线路是否跟随节点，缺省 true；关闭后节点退场时线路 / 通道停在最后一份坐标与解析尺寸 */
+	lineFollowsNode?: boolean
 
 	/** 快捷键：动作 -> 写法（框选、多选、加点、复制、粘贴、取消、删除、适应视图），没写的沿用默认值 */
 	shortcuts?: GisViewShortcuts
@@ -8058,12 +8388,19 @@ export interface GisViewEngineOptions {
 	 */
 	onSelect?: (payload: GisViewSelectPayload | null, detail?: { mode?: 'single' | 'multi' | 'box'; originalEvent?: Event | null }) => void
 	onClick?: (payload: GisViewClickPayload | null) => void
+	/** 点中多成员聚合圆（引擎不选中成员，普通点击回调不会同时触发） */
+	onClusterClick?: (payload: GisViewClusterClickPayload, event: Event) => void
 	onDblClick?: (payload: GisViewClickPayload | null) => void
 	/** 左键 / 中键 / 右键按下与抬起：命中的要素、按钮与光标位置都在载荷里 */
 	onPointerDown?: (payload: GisViewPointerPayload, event: PointerEvent) => void
 	onPointerUp?: (payload: GisViewPointerPayload, event: PointerEvent) => void
-	/** 右键：点、线、空白都会发 */
+	/**
+	 * 右键：点、线、通道、空白都会发这一条。命中通道回线时 action.target 为 'channel'，
+	 * 载荷另带 channelContext（几组 / 当前哪组 / 能做什么），不再有单独的通道路由。
+	 */
 	onContextMenu?: (payload: GisViewPointerPayload, event: MouseEvent) => void
+	/** 点击级联高亮变了：载荷与 getCascadeHighlight() 同一份，收掉时是 null */
+	onCascadeHighlight?: (payload: GisViewCascadeHighlightInfo | null) => void
 	onPointDrag?: (payload: GisViewPointDragPayload) => void
 	/** 复制节点：start / move / commit / end / cancel（剪贴板另有 clipboard） */
 	onPointCopy?: (payload: GisViewPointCopyPayload | GisViewBatchCopyPayload) => void
@@ -8071,8 +8408,6 @@ export interface GisViewEngineOptions {
 	onPointMerge?: (payload: GisViewPointMergePayload | GisViewMergeResult | GisViewMergeFailure | GisViewMergeSelectedPayload) => void
 
 	onWaypointChange?: (payload: GisViewWaypointPayload) => void
-	/** 右键点中通道回线：给出分组上下文（几组 / 当前哪组 / 有哪些交互），点空白处给 null */
-	onChannelContextMenu?: (payload: GisViewChannelContextPayload | null, event: MouseEvent) => void
 	/** 新增通道草稿：start / from / ready / cancel / commit / blocked / restart / pick */
 	onChannelDraft?: (payload: GisViewChannelDraftPayload) => void
 	/** 草稿里每点一次发一条：step 1 拿到起点、step 2 拿到终点（线路结束） */
@@ -8135,6 +8470,10 @@ export interface GisViewEngine {
 	getChannels(): GisViewChannelInfo[]
 	/** 单条通道运行时状态：只复制这一组；channelId 找不到时可按 channels 下标兜底 */
 	getChannel(channelId?: string | number | null, channelIndex?: number): GisViewChannelInfo | null
+	/** 单条通道的范围：按当前骨架与每条回线的折线计算，不复制几何；channelId 找不到时可按 channels 下标兜底 */
+	getChannelBounds(channelId?: string | number | null, channelIndex?: number): GisViewBounds | null
+	/** 一个分组的范围：按这一组当前骨架与回线折线计算，不复制几何；没有 channelId 时按通道下标兜底 */
+	getChannelGroupBounds(channelId: string | number | null | undefined, groupId: string | number, channelIndex?: number): GisViewBounds | null
 	/** 通道成员表：成员回线下标与各自的横向偏移，不复制几何（自建覆盖层按通道分流绘制用它） */
 	getChannelMembers(): GisViewChannelMembers[]
 	/** 通道分组现状：不传 channelId 返回所有分组 */
@@ -8249,7 +8588,7 @@ export interface GisViewEngine {
 	applyInitialView(): void
 	resetView(): void
 	getBounds(): GisViewBounds
-	/** 缩放联动的基准比例（pointZoomScale / lineZoomScale / zoomScaleAuto 共用那一份）：缺省是首次适应视图时的 camera.scale */
+	/** 缩放联动的基准比例（pointZoomScale / lineZoomScale 共用那一份）：缺省是首次适应视图时的 camera.scale */
 	getZoomBaseScale(): number
 	/** 重定缩放联动的基准比例：不传就取当下相机的比例（把现在这一屏当成「原样大小」），返回落定的基准 */
 	setZoomBaseScale(scale?: number): number
@@ -8261,6 +8600,12 @@ export interface GisViewEngine {
 	getViewRect(): GisViewBounds
 	/** 按条件列节点（只读快照，见 GisViewListOptions）：面板读数 / 导出 / 校验用，十万级下别逐帧调 */
 	listPoints(options?: GisViewListOptions): GisViewListedPoint[]
+	/** 当前展示组（含 count: 1 的单成员）：原始 points 不受影响 */
+	getClusters(): GisViewCluster[]
+	/** 覆盖层每帧同步数量文字用的轻量读数：只含多成员聚合圆 */
+	getClusterLabels(): GisViewClusterLabel[]
+	/** 当前点聚合配置与运行时开关 */
+	getPointCluster(): GisViewPointClusterReadout
 	/** 按条件列线路（只读快照）：通道内的回线给的是骨架推导出来的折线，另带 color / width 与通道读数 */
 	listLines(options?: GisViewListOptions): GisViewListedLine[]
 	/** 一批要素的世界包围盒；一个都没对上返回 null */
@@ -8303,9 +8648,9 @@ export interface GisViewEngine {
 	clientToWorld(clientX: number, clientY: number): [number, number]
 	/** 世界坐标 → 客户端坐标（摆 DOM 浮层 / 菜单用） */
 	worldToClient(x: number, y: number): [number, number]
-	pick(x: number, y: number): GisViewPickResult | null
+	pick(x: number, y: number): GisViewHitResult | null
 	/** 与组件实例的 pickAt 同一份：按浏览器客户端坐标拾取（引擎不等 DOM 事件，直接给 clientX / clientY） */
-	pickAtClient(clientX: number, clientY: number): GisViewPickResult | null
+	pickAtClient(clientX: number, clientY: number): GisViewHitResult | null
 	/** 程序化悬停（客户端坐标）：让指针「停」在这儿，悬停高亮 / 光标 / onHover 一起更新，返回这一次的读数 */
 	hoverAtClient(clientX: number, clientY: number): GisViewHoverPayload | null
 	/** 取消程序化悬停：清掉高亮与读数并补发 onHover(null) */