gis-view-webgl2 0.1.1 → 0.1.3

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 会先把这条回线挪到目标分组（通道内的回线只能进一组），
@@ -1208,6 +1278,11 @@ export interface GisViewChannelGroup {
 	lineIds: Array<string | number>
 	/** 这一组自己的骨架拐点（两端锚定时只写中间拐点）：新拆分出来的分组不带拐点，就是一条直线 */
 	path?: GisViewCoordinate[]
+	/**
+	 * 刚性拐点偏移：键是分组骨架顶点序号（含首尾端点，从 0 起，只认中间拐点），值是这一组所有成员回线在该顶点的世界坐标增量。
+	 * `channelWaypointDragMode: 'vertex'` 拖出来的结果写在这里；不写或空对象就是普通平行骨架
+	 */
+	waypointOffsets?: Record<string, GisViewCoordinate>
 }
 
 /**
@@ -1219,6 +1294,12 @@ export interface GisViewChannel {
 	id?: string | number
 	/** 通道名：仅作业务标识，组件不渲染 */
 	name?: string
+	/**
+	 * 是否显示这条通道：false 时整条通道与成员回线一起隐藏，数据、分组、拐点与编辑状态都保留，
+	 * 改回 true（或 `showFeatures('channel', ref)`）立即恢复；缺省 true。
+	 * 端点节点 `visible: false` 时通道也会整条隐藏，节点恢复后自动回来
+	 */
+	visible?: boolean
 	/** 通道内的线路 id，顺序即回线顺序（沿骨架左法线方向） */
 	lineIds: Array<string | number>
 	/**
@@ -1300,6 +1381,8 @@ export interface GisViewChannelInfo {
 	to?: string | number
 	/** 两端是否都落在节点上：锚定的通道会跟着节点拖动走 */
 	anchored: boolean
+	/** 分组刚性拐点偏移：与 groups[].waypointOffsets 同一份口径，没有偏移时是空对象 */
+	waypointOffsets: Record<string, [number, number]>
 	/** 整条通道相邻回线的中心间距（世界单位），单回线通道为 0；分组之后各组共用这一套间距 */
 	spacing: number
 }
@@ -1352,6 +1435,8 @@ export interface GisViewChannelGroupInfo {
 	skeleton: Array<[number, number]>
 	/** 骨架换算回声明用的中间拐点（两端锚定时不含首尾节点），可以直接写回 groups[].path */
 	path: Array<[number, number]>
+	/** 刚性拐点偏移：与 groups[].waypointOffsets 同一份口径，可以直接写回声明 */
+	waypointOffsets: Record<string, [number, number]>
 }
 
 /** getChannelGroupWaypoints 里的一条成员回线：偏移之后的折线与拐点（与图上画的一致） */
@@ -1386,6 +1471,8 @@ export interface GisViewChannelGroupWaypoints {
 	skeleton: Array<[number, number]>
 	/** 整组共用的中间拐点：给后端的 channel.group.path 就是这一份 */
 	path: Array<[number, number]>
+	/** 刚性拐点偏移：需要把非平行拖动结果一起回传时写回 groups[].waypointOffsets */
+	waypointOffsets: Record<string, [number, number]>
 	/** 组里每条回线偏移后的折线与拐点（同组同步之后「其他线路的拐点」读它） */
 	lines: GisViewChannelGroupLineWaypoints[]
 }
@@ -1445,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
@@ -1661,6 +1730,11 @@ export interface GisViewChannelBetween {
 export interface GisViewChannelDraftOptions {
 	/** 两个节点一选完就自动提交，不用再调 commitAddChannel */
 	autoCommit?: boolean
+	/**
+	 * 预指定起点：节点 id / 下标 / `{ id }` / `{ index }`。给了就从「已选好起点」进入草稿，
+	 * 下一次点节点只选终点；不写则仍由第一次点击选起点。找不到节点时草稿不开始并报 warning
+	 */
+	from?: GisViewPointRef
 	/**
 	 * 连续新增：一段线路落地之后自动开下一段草稿，不用再点一次「新增通道」。
 	 * true 每段都从空白开始；'chain' 以上一段的终点当下一段起点（首尾相接）
@@ -1826,6 +1900,102 @@ export interface GisViewMovedPoint {
 	item: GisViewPoint
 }
 
+/** 可整批隐藏 / 显示的要素类型 */
+export type GisViewVisibilityKind = 'point' | 'line' | 'channel'
+
+/** 隐藏 / 显示的引用：单个 id / 下标 / `{ id }` / `{ index }`，一批，或当前选中集 `'selection'` */
+export type GisViewVisibilityRefs = GisViewFeatureRef | 'selection' | Array<GisViewFeatureRef | 'selection'>
+
+/** 隐藏 / 显示时没认出来的引用 */
+export interface GisViewVisibilitySkip {
+	ref: unknown
+	reason: string
+}
+
+/** setFeatureVisible / hideFeatures / showFeatures 的返回：indexes 与 items 按数据顺序一一对应 */
+export interface GisViewSetVisibilityOutcome {
+	ok: boolean
+	reason: string | null
+	kind: GisViewVisibilityKind
+	visible: boolean
+	/** 实际改到的下标（去重、按传入顺序） */
+	indexes: number[]
+	/** 对应的 id；要素没 id 时退回下标 */
+	ids: Array<string | number>
+	items: Array<GisViewPoint | GisViewLine | GisViewChannel>
+	skipped: GisViewVisibilitySkip[]
+}
+
+/** 通道变化里的一组：成员与骨架都是当次读数的可比较快照 */
+export interface GisViewChangedChannelGroup {
+	id: string | number | null
+	lineIds: string[]
+	path: GisViewCoordinate[] | null
+}
+
+/** 通道变化原因 */
+export type GisViewChangedChannelReason = 'groups' | 'members' | 'waypoints' | 'endpoints' | 'visibility' | 'fields'
+
+/** getChangedChannels 的查询选项 */
+export interface GisViewChangedChannelOptions {
+	/** 只返回带这些原因的变化（空数组 = 不返回任何变化）；不传 = 全部原因 */
+	reasons?: GisViewChangedChannelReason[]
+	/**
+	 * 忽略分组结构的新增 / 删除 / 重排：不报 `groups`，也不把整组增删算成拐点变化；
+	 * 基准与当前都存在、且分组 `path` 真变过的，仍报 `waypoints`
+	 */
+	ignoreGroups?: boolean
+}
+
+/** getChangedChannels 的一项：相对上次通道对账发生了哪些变化 */
+export interface GisViewChangedChannel {
+	index: number
+	id: string | number | null
+	item: GisViewChannel
+	/** 当前分组读数（没写 groups 的通道按「一整组」折算） */
+	groups: GisViewChangedChannelGroup[]
+	groupsChanged: boolean
+	waypointsChanged: boolean
+	membersChanged: boolean
+	endpointsChanged: boolean
+	visibilityChanged: boolean
+	fieldsChanged: boolean
+	/** 除 id / lineIds / groups / path / from / to / visible 之外变过的字段名 */
+	fields: string[]
+	/** 变化原因：groups / members / waypoints / endpoints / visibility / fields */
+	reasons: GisViewChangedChannelReason[]
+}
+
+/** 线路变化原因：path（path / start / end）、端点、可见性、其余字段 */
+export type GisViewChangedLineReason = 'path' | 'endpoints' | 'visibility' | 'fields'
+
+/** getChangedLines 的查询选项 */
+export interface GisViewChangedLineOptions {
+	/** 只返回带这些原因的变化（空数组 = 不返回任何变化）；不传 = 全部原因 */
+	reasons?: GisViewChangedLineReason[]
+}
+
+/** getChangedLines 的一项：相对上次线路对账发生了哪些变化 */
+export interface GisViewChangedLine {
+	index: number
+	id: string | number | null
+	item: GisViewLine
+	/** 当前声明的 path（没有 path 时为 null）；线条几何还会看 start / end */
+	path: GisViewCoordinate[] | null
+	start: GisViewCoordinate | null
+	end: GisViewCoordinate | null
+	from: string | number | null
+	to: string | number | null
+	visible: boolean
+	pathChanged: boolean
+	endpointsChanged: boolean
+	visibilityChanged: boolean
+	fieldsChanged: boolean
+	/** 除 id / start / end / path / from / to / visible 之外变过的字段名 */
+	fields: string[]
+	reasons: GisViewChangedLineReason[]
+}
+
 /**
  * addChannels 的返回：results 与传入顺序一一对应（失败的条目也在里面，按各自的 reason 读），
  * count 是成功落地的条数；lineIds / channelIds 只列成功那几条的（顺序与 results 里成功的一致）。
@@ -1935,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 / 通道上下文），
@@ -2393,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]
@@ -2439,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[]
@@ -2476,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
@@ -2489,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 下标） */
@@ -2651,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'
 
 /**
  * 一次指针操作的动作名。同一个名字在「按下 / 松开 / 点击」三条事件里含义略有不同：
@@ -2673,6 +2919,7 @@ export type GisViewPointerActionType =
 	| 'selectWaypoint'
 	| 'dragWaypoint'
 	| 'dragPoint'
+	| 'clusterClick'
 	| 'dragLabel'
 	| 'selectLabel'
 	| 'contextMenu'
@@ -2717,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
 	/**
@@ -2756,8 +3003,8 @@ export interface GisViewPointerPayload {
 	 * target 说明点的是点 / 线 / 通道 / 空白，data 直接给到那一份数据（左键 / 右键都认这一份）
 	 */
 	action: GisViewPointerAction
-	/** 命中的要素类型，空白处为 null */
-	type: GisViewFeatureType | null
+	/** 命中的要素类型，空白处为 null；多成员聚合是 'cluster' */
+	type: GisViewFeatureType | 'cluster' | null
 	/** 命中的要素在数据里的下标，空白处为 -1 */
 	index: number
 	/** 有没有命中要素 */
@@ -2768,6 +3015,9 @@ export interface GisViewPointerPayload {
 	screen?: [number, number]
 	/** 命中的要素自身的世界坐标 */
 	coordinate?: [number, number]
+	/** 命中的是线路（含通道回线）时，线路在 lines 数组里的下标与 id；右键菜单按它找线路 */
+	lineIndex?: number
+	lineId?: string | number
 	/** 命中的是通道内的回线时，回线所属通道与分组 */
 	channelIndex?: number
 	channel?: GisViewChannel
@@ -2775,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 相同
@@ -2805,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
@@ -3269,6 +3528,71 @@ export interface GisViewMergeSelectedOptions {
 	originalEvent?: Event | null
 }
 
+/**
+ * splitPoint 的一份节点定义：节点字段可直接写在顶层（id / x / y / name / style…），也可以放进 item；
+ * lines / channels / channelFrom / channelTo 是会从节点字段里摘出来的分配指令，不会写进节点数据。
+ */
+export interface GisViewSplitPointPart extends Partial<GisViewPoint> {
+	/** 新节点的字段（与顶层的节点字段合并，顶层优先） */
+	item?: Partial<GisViewPoint>
+	/** 分到这一份的线路（id / 下标 / { id } / { index }）：不写时连在原节点上的线路跟第一份 */
+	lines?: GisViewFeatureRef | GisViewFeatureRef[]
+	/** 两端都分到这一份的受影响通道；把同一条通道写进两份时按 from / to 各去一份 */
+	channels?: GisViewFeatureRef | GisViewFeatureRef[]
+	/** 只把通道的 from 端分到这一份 */
+	channelFrom?: GisViewFeatureRef | GisViewFeatureRef[]
+	/** 只把通道的 to 端分到这一份 */
+	channelTo?: GisViewFeatureRef | GisViewFeatureRef[]
+}
+
+/** splitPoint 的选项 */
+export interface GisViewSplitPointOptions {
+	/** 第一份是否沿用来源节点的 id（缺省 true）；false 时也给第一份生成 `${来源 id}-split-1` */
+	keepSourceId?: boolean
+	/** 这一步历史的标签，缺省「拆分节点」 */
+	label?: string
+}
+
+/** 拆分时没认出来的线路 / 通道引用 */
+export interface GisViewSplitPointSkip {
+	ref: unknown
+	reason: string
+}
+
+/**
+ * 一次拆分的完整变更集：removedPoint 是拆分前的来源节点，points 是拆分后的全部节点，
+ * lines / channels 是仍存在且受影响的最终数据，removedLines / removedChannels 是拆分前被删掉的数据。
+ * 可直接作为后端事务的输入。
+ */
+export interface GisViewSplitPointChangeSet {
+	removedPoint: GisViewPoint
+	points: GisViewPoint[]
+	lines: GisViewLine[]
+	removedLines: GisViewLine[]
+	channels: GisViewChannel[]
+	removedChannels: GisViewChannel[]
+}
+
+/** splitPoint 的返回：ok 为 false 时 reason 说明原因，其余数组为空、changes 为 null */
+export interface GisViewSplitPointOutcome {
+	ok: boolean
+	reason: string | null
+	source: { index: number; id: string | number | null; item: GisViewPoint } | null
+	/** 拆分后的节点，第一份在原下标，其余按 indexes 追加 */
+	items: GisViewPoint[]
+	indexes: number[]
+	pointIds: Array<string | number>
+	linesChanged: number
+	removedLines: number
+	removedLineIds: Array<string | number>
+	removedLineIndexes: number[]
+	channelsChanged: number
+	removedChannels: number
+	removedChannelIds: Array<string | number>
+	skipped: { lines: GisViewSplitPointSkip[]; channels: GisViewSplitPointSkip[] }
+	changes: GisViewSplitPointChangeSet | null
+}
+
 /** 定位一个节点：id、数组下标，或带 id / index 的对象（`{ id: 'a' }` / `{ index: 2 }`） */
 export type GisViewPointRef = string | number | { id: string | number } | { index: number }
 
@@ -3347,6 +3671,7 @@ export type GisViewDataChangeType =
 	| 'copyPoint'
 	| 'copyPoints'
 	| 'mergePoints'
+	| 'splitPoint'
 	| 'waypoint'
 	| 'addChannel'
 	| 'addChannels'
@@ -3476,6 +3801,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
@@ -3706,6 +4037,8 @@ export interface GisViewItemLabel {
 	style?: Record<string, string>
 	/** 线路标签是否与线路方向平行（点的标签忽略这一项） */
 	parallel?: boolean
+	/** 这一条是否参与避让：false 时即使全局开启 labelOptimize / avoidOverlap 也始终按候选落点画出；缺省跟随全局 */
+	avoidOverlap?: boolean
 	/**
 	 * 这一条撞上别的标签之后怎么避让：`shift`（默认）主动换锚点 / 沿线挪，`hide` 直接不显示。
 	 * 只在顶层 `labelOptimize: true` 且这条的 `avoidOverlap` 不为 false 时生效；只和底图区域文字重叠时仍按软冲突照画。
@@ -3715,6 +4048,10 @@ export interface GisViewItemLabel {
 	visibility?: GisViewLabelVisibility
 	/** 整条不画（等于 visibility: 'hidden'）；false 表示撤回隐藏覆盖 */
 	hidden?: boolean
+	/** 这一条标签能不能拖：逐条覆盖 options.label / lineLabel 里的同名开关 */
+	draggable?: boolean
+	/** 这一条标签能不能点选：逐条覆盖 options.label / lineLabel 里的同名开关 */
+	editable?: boolean
 	/** 这条标签是运行时加的（addLabel），导出时带上它便于整份回显 */
 	added?: boolean
 	className?: string
@@ -3954,8 +4291,10 @@ export interface GisViewLabelPatch {
 export interface GisViewLabelInfo {
 	/** 这一条要素上的哪一条标签 */
 	id: string
-	/** 当下画出来的文本（DOM 里的那一份：模板 / 函数算完之后的结果） */
+	/** 当下画出来的内容（DOM 里的那一份：模板 / 函数算完之后的结果；html 时保留标记本身） */
 	content: string
+	/** 这一条当下是否按 HTML 渲染（html: true 才有子节点；false 永远是纯文本） */
+	html: boolean
 	/** 当下生效的锚点（点八向 / 线沿线位置），算不出来时是 null */
 	position: GisViewLabelPosition | GisViewLineLabelPosition | null
 	className: string | null
@@ -4120,12 +4459,12 @@ export interface GisViewLabelListItem {
 	id: string
 	/** 这一条是哪来的：'config' 配置里定义的 / 'data' 数据里写的 / 'runtime' 运行时加的（与事件载荷里的 GisViewLabelInfo.source 同一口径） */
 	source: 'config' | 'data' | 'runtime'
-	/** 这一条声明里的内容（模板 / 函数原样给出），没写是 null */
+	/** 这一条当下生效的内容（运行时覆盖优先，模板 / 函数原样给出），没写是 null */
 	content: GisViewLabelContent | GisViewLineLabelContent | null
 	html: boolean
 	className: string | null
 	position: GisViewLabelPosition | GisViewLineLabelPosition | null
-	/** 声明里的偏移（像素），没写是 [0, 0] */
+	/** 当下生效的偏移（像素）：运行时拖出来的优先，否则用声明里的；都没有是 [0, 0] */
 	offset: [number, number]
 	style: Record<string, string> | null
 	/** 线路标签：这一条是否与线路平行；节点标签恒为 false */
@@ -4854,6 +5193,18 @@ export interface GisViewInitialView {
 	padding?: number
 }
 
+/**
+ * 适应视图的节点间距兜底：普通「铺满数据范围」让最近节点在屏幕上挤在一起时，
+ * 按 minDistance 反推一个更高的相机比例。放大时以最近节点对的中点为中心，
+ * 远处孤立点可以把包围盒撑大，但不再把主体节点压成一团，也允许落到视口外。
+ */
+export interface GisViewFitSpacingOptions {
+	/** 可见节点中心之间的最小屏幕距离（CSS 像素），默认 24；写 0 或负数关闭 */
+	minDistance?: number
+	/** 相对普通适应比例的最大放大倍数，默认 0（不限，只受 maxScale 约束）；正数表示上限 */
+	maxZoom?: number
+}
+
 /**
  * 插件：视图建好之后调用一次，拿到实例本身与带 apiVersion 的上下文；返回 { destroy } 时会挂进实例的 destroy。
  * 写一次插件，之后换项目直接复用，不必把「URL 同步 / 自建图例 / 业务操作」再抄一遍。
@@ -5020,6 +5371,13 @@ export type GisViewChannelSelectMode =
 	/** 整条通道（所有分组的回线）一起选 */
 	| 'channel'
 
+/** 分组拐点拖动模式：普通线路永远只动自己，这里只影响通道里的一组回线 */
+export type GisViewChannelWaypointDragMode =
+	/** 缺省：改共用骨架，组内回线按平行偏移重算；拐角处相邻顶点可能随 miter 微调 */
+	| 'parallel'
+	/** 只把同组同一 pathIndex 的拐点按相同世界增量平移，其他拐点（含相邻顶点）保持不动 */
+	| 'vertex'
+
 /**
  * 框选 / Ctrl 多选允许收哪几类要素：节点、独立线路、通道回线。
  * 通道回线只归 channel 这一档管；通道之外的普通线路归 line，两者可以任意组合。
@@ -5307,8 +5665,6 @@ export type GisViewFeatureName =
 	| 'remove'
 	/** 新增通道：进入草稿、点两个节点、落地 */
 	| 'channelDraft'
-	/** 通道右键交互框（onChannelContextMenu） */
-	| 'channelMenu'
 	/** 右键回调 onContextMenu（关掉之后组件不再拦右键，浏览器菜单照常） */
 	| 'contextMenu'
 	/** 悬停提示（tooltip）：关掉只影响提示，悬停样式与 onHover 还在 */
@@ -5484,7 +5840,7 @@ export interface GisViewBatchOptions {
 /**
  * 全部可订阅事件（与 EVENT_NAMES 一致）：事件名与 options 里的回调一一对应（`dataChange` 就是 `onDataChange`），
  * 载荷也是同一份 —— 区别只在写法：`on` 可以挂多条、可以运行时订阅、返回的函数就是取消订阅。
- * 需要原样带回 DOM 事件的那四个（pointerDown / pointerUp / contextMenu / channelContextMenu）载荷是
+ * 需要原样带回 DOM 事件的那三个（pointerDown / pointerUp / contextMenu）载荷是
  * `{ payload, event }`，与回调的两个参数一一对应。
  */
 export interface GisViewEventMap {
@@ -5504,6 +5860,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
@@ -5517,13 +5875,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 */
@@ -5786,6 +6145,16 @@ export interface GisViewOptions {
 	 * 只管「画不画、画哪几条」：`visibility` / `when` / 拖拽 / 编辑 / 样式与动画都不受影响
 	 */
 	labelOptimize?: boolean
+	/**
+	 * 纯文本标签的渲染方式，缺省 `auto`：
+	 * - `auto`：强制显示档下，视口里的纯文本标签达到 1024 条时自动改画到单张 Canvas；
+	 *   需要 DOM 的标签（`html: true`、函数返回元素、可拖拽 / 可编辑）仍逐条建节点。
+	 * - `canvas`：纯文本标签始终改画到单张 Canvas，不受 1024 条阈值限制，`labelOptimize: true` 时
+	 *   也按画布尺寸参与避让 / 换落点；需要 DOM 的标签仍逐条建节点。
+	 * - `dom`：始终逐条建 `.gis-view__label`，保持旧行为。
+	 * 画布档不改变标签内容、锚点与显隐，只减少高密度场景的 DOM 数量。
+	 */
+	labelRender?: 'auto' | 'canvas' | 'dom'
 	/**
 	 * 标签的运行时状态（`getLabelStates()` 的那一份：拖过的偏移、改过的内容与样式、运行时加的标签、隐藏覆盖）：
 	 * 创建 / `updateOptions` 时喂回来就回显，与 `setLabelStates(states)` 同一条路。
@@ -5802,6 +6171,12 @@ export interface GisViewOptions {
 	tooltip?: GisViewTooltipOptions
 	/** 初始筛选条件，等价于创建之后调用 setFilter；可以写完整格式，也可以只给节点条件 */
 	filter?: GisViewFilterInput | null
+	/**
+	 * 线路是否跟随节点，默认 true。开启时隐藏 / 删除 / 筛选节点会连带绑定线路与通道；
+	 * 关闭后这些操作只影响节点，线路与通道继续停在节点最后一次坐标，筛选未显式写 cascade 时默认不级联。
+	 * 筛选里显式写了 cascade 时始终以筛选自己的写法为准。
+	 */
+	lineFollowsNode?: boolean
 	/** 内置鹰眼图：不配就不显示，配了默认开 */
 	minimap?: GisViewMinimapOptions | null
 	/** 筛选是否用 Worker 计算：默认在数据量超过阈值时自动启用，false 表示始终同步计算 */
@@ -5826,6 +6201,12 @@ export interface GisViewOptions {
 	lineSelectStyle?: GisViewLineStyle
 	/** Ctrl 点击累加多选时的线样式：缺省沿用 lineSelectStyle，单条线可用 multiSelectStyle 覆盖 */
 	lineMultiSelectStyle?: GisViewLineStyle
+	/**
+	 * 点击级联高亮（默认关）：点击节点时亮起它和直接相连的节点；scope 为 both 时连线路一起亮，
+	 * 点击线路 / 通道回线时亮起两端节点。它不进选中集，样式与悬停 / 选中分开配置，
+	 * 当前亮起的清单用 getCascadeHighlight() 读。
+	 */
+	cascadeHighlight?: GisViewCascadeHighlightInput
 	/** 没有配置状态样式时，是否仍用尺寸 / 宽度增幅画出内置强调；默认 false（不配样式就不改变外观） */
 	defaultHighlight?: boolean
 	/** 节点整体放大系数（常数倍数，与地图缩放无关，屏幕上的大小因此恒定）：与点自身 size、缩放联动一起相乘，默认 1 */
@@ -5846,17 +6227,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
@@ -5928,6 +6310,12 @@ export interface GisViewOptions {
 	 * Ctrl + 点击在 group / channel 下是整批取反，切换走 updateOptions 不用重排场景
 	 */
 	channelSelectMode?: GisViewChannelSelectMode
+	/**
+	 * 分组拐点拖动模式：'parallel'（缺省）沿用共用骨架 + 平行偏移，拐角相邻顶点可能随 miter 微调；
+	 * 'vertex' 只移动当前分组同一 pathIndex 的拐点（组内所有回线按相同世界增量），其他拐点保持不动。
+	 * 普通线路不受影响；切换走 updateOptions({ channelWaypointDragMode })，下一次拖动生效
+	 */
+	channelWaypointDragMode?: GisViewChannelWaypointDragMode
 
 	/**
 	 * 快捷键：框选、多选、加点、复制、粘贴、取消、删除、适应视图都可以在这里改
@@ -5961,6 +6349,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，节流能省下每帧一次的回调与对象分配（拖拽时尤其明显）。
@@ -6004,6 +6397,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 打开时）：载荷里是这一条标签的类型、下标与当前覆盖 */
@@ -6023,8 +6418,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） */
@@ -6050,8 +6450,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 相同 */
@@ -6166,7 +6564,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 }
 
@@ -6203,6 +6604,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' = 不带背景（透明底，上面那些都不画）；
@@ -6753,6 +7161,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
@@ -6766,6 +7188,7 @@ export interface GisViewSceneSnapshot {
 	/** 数据线路与节点装饰连接线（连接线也画在节点 / 装饰之前） */
 	lines: GisViewSceneLine[]
 	points: GisViewSceneNode[]
+	clusters: GisViewSceneCluster[]
 	backgroundPoints: GisViewSceneNode[]
 	decorations: GisViewSceneNode[]
 	waypoints: GisViewSceneNode[]
@@ -6986,7 +7409,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
@@ -7071,7 +7494,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。
@@ -7107,11 +7530,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')` 取消一个节点、
@@ -7137,6 +7568,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
 	/**
@@ -7188,6 +7624,14 @@ export interface GisViewInstance {
 	 * 并不了返回 ok: false 并另发一条 `phase: 'merge', ok: false` 的事件
 	 */
 	mergePoints(source: GisViewPointRef, target: GisViewPointRef, options?: { originalEvent?: Event | null; item?: GisViewPoint }): GisViewMergeOutcome
+	/**
+	 * 把一个节点拆成多份（mergePoints 的逆操作）：第一份复用原下标与 id，其余追加到 points 末尾。
+	 * 每份可直接写节点字段或放进 item；lines 分配线路（不写时连在原节点上的线路跟第一份），
+	 * channels / channelFrom / channelTo 分配受影响通道的端点。没显式分配的通道跟随它第一条被分配过的成员线路。
+	 * 拆分后自环 / 零长度线路与两端相同的通道删掉；整次调用只记一条历史、只发一条 `splitPoint` 数据变更。
+	 * 返回 `{ ok, items, indexes, pointIds, linesChanged, removedLines, channelsChanged, removedChannels, changes, skipped }`
+	 */
+	splitPoint(source: GisViewPointRef, parts: GisViewSplitPointPart[], options?: GisViewSplitPointOptions): GisViewSplitPointOutcome
 	/**
 	 * 框选 / 多选之后一步把选中的节点并到一个目标上（接口调用）：不指定 target 就自动挑「绑定线路最多」的那一个
 	 * （一样多取画得大的、再一样取下标小的）；来源默认是除目标之外的选中节点，也可以直接用 options.sources 给定，
@@ -7314,7 +7758,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 收掉假通道。
@@ -7518,6 +7963,40 @@ export interface GisViewInstance {
 	 * （写法与 removePoints 一致：id / 下标 / { id } / { index }）；空数组无操作，返回实例本身。
 	 */
 	clearMovedPoints(refs?: GisViewFeatureRef | GisViewFeatureRef[]): GisViewInstance
+	/**
+	 * 相对上一次对账，成员 / 分组 / 拐点 / 端点 / 可见性或其余声明字段变过的通道。
+	 * 新加通道只补账不报变化，删掉的通道从账本清掉；整份换通道数据（updateData / updateOptions / applyChannels）
+	 * 之后以新数据为基准。返回项带 groups / 各 changed 标记 / fields / reasons。
+	 * options.reasons 只返回指定原因；options.ignoreGroups 忽略分组增删，只比较已有分组的拐点。
+	 */
+	getChangedChannels(options?: GisViewChangedChannelOptions): GisViewChangedChannel[]
+	/**
+	 * 通道变化对账：不传 / 传 null 全部对账，传一个或一批引用只对账这些（写法与 removePoints 一致）；
+	 * 返回实例本身，认不出来的引用跳过并报一句提醒。
+	 */
+	clearChangedChannels(refs?: GisViewFeatureRef | GisViewFeatureRef[]): GisViewInstance
+	/**
+	 * 相对上一次对账，path / start / end、from / to、可见性或其余声明字段变过的线路。
+	 * 新加线路只补账不报变化，删掉的线路从账本同步清掉；整份换线路后以新数据为基准。
+	 * 通道里的回线只比较自己的声明；通道骨架变化由 getChangedChannels 负责。
+	 * options.reasons 只返回指定原因。
+	 */
+	getChangedLines(options?: GisViewChangedLineOptions): GisViewChangedLine[]
+	/**
+	 * 线路变化对账：不传 / 传 null 全部对账，传一个或一批引用只对账这些（写法与 removePoints 一致）；
+	 * 返回实例本身，认不出来的引用跳过并报一句提醒。
+	 */
+	clearChangedLines(refs?: GisViewFeatureRef | GisViewFeatureRef[]): GisViewInstance
+	/**
+	 * 统一隐藏 / 显示节点、线路或通道：只改数据里的 visible，不删要素，分组 / 拐点 / 编辑状态都保留。
+	 * refs 收单个或一批（id / 下标 / { id } / { index }），也认 'selection'；整次调用一条历史、一条 batch 数据变更。
+	 * 返回 `{ ok, kind, visible, indexes, ids, items, skipped }`
+	 */
+	setFeatureVisible(kind: GisViewVisibilityKind, refs: GisViewVisibilityRefs, visible: boolean): GisViewSetVisibilityOutcome
+	/** `setFeatureVisible(kind, refs, false)` 的快捷写法 */
+	hideFeatures(kind: GisViewVisibilityKind, refs: GisViewVisibilityRefs): GisViewSetVisibilityOutcome
+	/** `setFeatureVisible(kind, refs, true)` 的快捷写法（隐藏后原样恢复） */
+	showFeatures(kind: GisViewVisibilityKind, refs: GisViewVisibilityRefs): GisViewSetVisibilityOutcome
 	/**
 	 * 某个下标的节点当前在不在图上：被筛选 / visible: false 隐藏掉的不算，
 	 * 初始化发散渲染还没排到的那一部分也不算。
@@ -7548,6 +8027,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 */
@@ -7708,6 +8191,8 @@ export interface GisViewEngineOptions {
 	lineSelectStyle?: GisViewLineStyle | null
 	/** Ctrl 点击累加多选时的线样式：缺省沿用 lineSelectStyle */
 	lineMultiSelectStyle?: GisViewLineStyle | null
+	/** 点击级联高亮：true / 对象打开，false / null 关闭；详细写法见 GisViewOptions.cascadeHighlight */
+	cascadeHighlight?: GisViewCascadeHighlightInput | null
 	/** 没有配置状态样式时是否仍画内置强调（尺寸 / 宽度增幅与强调环）；默认 false */
 	defaultHighlight?: boolean
 	/** 节点整体放大系数，默认 1 */
@@ -7720,12 +8205,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），只影响画哪些批次与分辨率 */
@@ -7750,7 +8237,7 @@ export interface GisViewEngineOptions {
 	contextMenu?: boolean
 	/**
 	 * 右键默认把浏览器的系统菜单收掉（组件接住右键时 preventDefault contextmenu）。
-	 * 写 false 保留系统菜单：onContextMenu / onChannelContextMenu 照常发，只是不再挡浏览器自己弹菜单。
+	 * 写 false 保留系统菜单：onContextMenu 照常发，只是不再挡浏览器自己弹菜单。
 	 */
 	preventContextMenu?: boolean
 	/** 悬停拾取的移动阈值（CSS 像素）：指针移动不超过它时不重算拾取，0 表示每次指针事件都重算；默认 2 */
@@ -7776,6 +8263,10 @@ export interface GisViewEngineOptions {
 	 * 切换走 setOptions / updateOptions 不用重排场景
 	 */
 	channelSelectMode?: GisViewChannelSelectMode
+	/** 分组拐点拖动模式：'parallel'（缺省）/ 'vertex'，见 GisViewOptions.channelWaypointDragMode */
+	channelWaypointDragMode?: GisViewChannelWaypointDragMode
+	/** 线路是否跟随节点，缺省 true；关闭后节点退场时线路 / 通道停在最后一份坐标与解析尺寸 */
+	lineFollowsNode?: boolean
 
 	/** 快捷键：动作 -> 写法（框选、多选、加点、复制、粘贴、取消、删除、适应视图），没写的沿用默认值 */
 	shortcuts?: GisViewShortcuts
@@ -7806,12 +8297,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
@@ -7819,8 +8317,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 拿到终点（线路结束） */
@@ -7997,7 +8493,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
@@ -8009,6 +8505,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 */
@@ -8051,9 +8553,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) */