gis-view-webgl2 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -138,6 +138,20 @@ export type GisViewSymbol = GisViewCircleSymbol | GisViewSquareSymbol | GisViewI
 /** 符号简写：'circle' / 'square'、注册过的自定义图元名字、图片地址、以 svg 标记开头的字符串 */
 export type GisViewSymbolInput = GisViewSymbol | 'circle' | 'square' | string
 
+/** 注册（或覆盖）一支自定义图元画笔；名字为空或画笔不是函数返回 false，不动注册表 */
+export declare const registerSymbolPainter: (name: string, painter: GisViewSymbolPainter) => boolean
+/**
+ * 带作用域地注册一支自定义图元画笔：返回清理函数，只在当前注册项仍是这支画笔时删除，
+ * 旧插件 / 旧视图卸载不会误删后来覆盖注册的同名画笔。参数不合法时抛 TypeError。
+ */
+export declare const defineSymbolPainter: (name: string, painter: GisViewSymbolPainter) => () => boolean
+/** 注销一支自定义图元画笔，返回它之前是否在注册表里 */
+export declare const unregisterSymbolPainter: (name: string) => boolean
+/** 这个名字注册过没有 */
+export declare const hasSymbolPainter: (name: string) => boolean
+/** 当前注册着的自定义图元名字（按注册顺序） */
+export declare const listSymbolPainters: () => string[]
+
 export interface GisViewShadow {
 	color?: string
 	opacity?: number
@@ -419,6 +433,50 @@ export interface GisViewMinimapDrawInfo {
 	data: GisViewMinimapDrawData
 	/** 这一帧的底图（inherit 时是主视图解析好的那一份） */
 	background: GisViewBackground | null
+	/** 当前绘制阶段：数据前 / 数据后的自定义层，或兼容旧写法的最终 draw 钩子 */
+	stage: GisViewMinimapLayerStage
+}
+
+/** 自定义层画在内置线路 / 节点之前还是之后；缺省 after 对应的 above-data */
+export type GisViewMinimapLayerPlacement = 'below-data' | 'above-data'
+/** 回调实际所处的绘制阶段；兼容旧写法的 draw 固定为 overlay */
+export type GisViewMinimapLayerStage = GisViewMinimapLayerPlacement | 'overlay'
+
+/**
+ * 鹰眼图自定义层：按 placement 分到内置数据前 / 后，组内再按 `order` 依次绘制；
+ * 旧 draw 钩子固定最后执行。适合把指北针、网格、业务标记拆成互不干扰的几层。
+ */
+export interface GisViewMinimapLayer {
+	/** 给这一层一个名字，便于配置与调试（绘制时不需要） */
+	id?: string
+	/** 叠放顺序：数值小的先画，相同 or 缺省按数组顺序 */
+	order?: number
+	/** 画在内置线路 / 节点之前（below-data）还是之后（above-data，默认） */
+	placement?: GisViewMinimapLayerPlacement
+	/** 临时关掉这一层而不必改数组内容 */
+	enabled?: boolean
+	/** 与 draw 钩子同一份入参：上下文已按备份像素比缩放，直接用 CSS 像素画 */
+	draw: (info: GisViewMinimapDrawInfo) => void
+}
+
+/** 鹰眼图完成一次交互（长按为触发时）后的通知类型 */
+export type GisViewMinimapInteractionType = 'box-drag' | 'select' | 'pan' | 'zoom' | 'wheel-main' | 'long-press'
+
+/** 鹰眼图交互回调：一次手势结束时发一条（长按在触发时发），不在 pointermove 里逐帧触发 */
+export interface GisViewMinimapInteractionInfo {
+	type: GisViewMinimapInteractionType
+	/** 触发这次交互的原始事件；长按回调保留 pointerdown，其余为 pointerup / wheel */
+	originalEvent: Event | null
+	/** 指针在小图里的 CSS 像素坐标 */
+	local: [number, number]
+	/** 同一个位置对应的世界坐标 */
+	world: [number, number]
+	/** 交互完成时小图自身的倍数 */
+	zoom: number
+	/** 当前小图铺开的世界范围 */
+	extent: GisViewBounds
+	camera: GisViewCamera | null
+	viewport: GisViewViewport | null
 }
 
 /**
@@ -455,8 +513,12 @@ export interface GisViewMinimapOptions {
 	 * 拿到已缩放好的画布上下文、当前范围与 project / unproject，在小图上画标记、指北针这类东西
 	 */
 	draw?: (info: GisViewMinimapDrawInfo) => void
+	/** 可拆分的自定义绘制层：按 placement 分段、段内按 order，最后才轮到旧的 draw */
+	layers?: GisViewMinimapLayer[]
 	/** 小图容器的底色（CSS），默认 rgba(255, 255, 255, 0.92) */
 	backgroundStyle?: string
+	/** 小图画布备份像素比上限（默认 4）：高分屏或宿主缩放很大时可降到 1 ~ 2 降低填充开销 */
+	maxPixelRatio?: number
 	borderColor?: string
 	borderWidth?: number
 	/** 圆角（CSS 像素），默认 6 */
@@ -516,6 +578,8 @@ export interface GisViewMinimapOptions {
 	selectStyle?: GisViewMinimapBoxStyle
 	/** 关掉后鹰眼图只看不动，默认 true */
 	interactive?: boolean
+	/** 一次手势完成后的通知（无位移的点击不发）：框拖动 / 框选 / 小图平移 / 缩放 / 滚轮缩放主图 / 长按跟随 */
+	onInteraction?: (info: GisViewMinimapInteractionInfo) => void
 	/** 长按多久算「要移动视角」（毫秒），默认 180 */
 	longPressDelay?: number
 	/** 在小图上滚轮是否缩放主图（以光标处的世界坐标为锚点），默认 true；zoomable 打开时改由 Ctrl / ⌘ + 滚轮触发 */
@@ -903,6 +967,55 @@ export interface GisViewPointEffectReadout {
 	from: number
 }
 
+/** 节点装饰连接线：true 用默认样式，对象可覆盖颜色 / 线宽 / 透明度 / 虚线 */
+export interface GisViewPointDecorationConnector {
+	color?: string
+	/** 线宽（CSS 像素），缺省 1 */
+	width?: number
+	/** 透明度，缺省 0.82 */
+	opacity?: number
+	/** true 等价于 lineType: 'dashed' */
+	dashed?: boolean
+	lineType?: 'solid' | 'dashed' | 'dotted'
+}
+
+/**
+ * 节点上的图片 / SVG 装饰：相对节点按屏幕像素偏移，或写死世界坐标。
+ * - `offset` / `distance + direction`：相对节点，缩放时保持同样的屏幕像素距离；
+ * - `at` / `anchor: 'fixed'`：世界坐标固定，节点移动不跟随；
+ * - `connector`：从节点中心画一条连接线到装饰中心。
+ */
+export interface GisViewPointDecoration {
+	/** 图片 / SVG / 内置形状，和节点的 symbol 写法一样 */
+	symbol: GisViewSymbolInput
+	/** 定位方式：offset 相对节点（缺省），fixed 写死世界坐标 */
+	anchor?: 'offset' | 'fixed'
+	/** 相对节点的屏幕像素偏移（x 向右、y 向下），优先于 distance / direction */
+	offset?: [number, number] | GisViewCoordinate
+	/** 离节点的屏幕像素距离，缺省 28 */
+	distance?: number
+	/** 相对方向：0 度向上、顺时针，缺省 0（正上方） */
+	direction?: number
+	/** 固定位置（世界坐标）；给了它就按 fixed 处理，优先级最高 */
+	at?: GisViewCoordinate
+	/** 图标旋转角（度），缺省 0 */
+	angle?: number
+	/** 屏幕尺寸（CSS 像素），缺省 18 */
+	size?: number
+	/** 填充 / 色调，缺省白色 */
+	color?: string
+	/** 描边色，缺省透明 */
+	strokeColor?: string
+	/** 描边宽度（CSS 像素），缺省 0 */
+	strokeWidth?: number
+	/** 透明度，缺省 1 */
+	opacity?: number
+	/** 阴影，和节点一样 */
+	shadow?: GisViewShadow
+	/** 是否从节点中心画一条连接线，缺省不画 */
+	connector?: boolean | GisViewPointDecorationConnector
+}
+
 export interface GisViewPoint {
 	id?: string | number
 	x: number
@@ -921,6 +1034,8 @@ export interface GisViewPoint {
 	opacity?: number
 	shadow?: GisViewShadow
 	visible?: boolean
+	/** 这个节点上挂的图片 / SVG 装饰：可相对节点偏移、固定世界坐标，也可以带一条连接线 */
+	decorations?: GisViewPointDecoration[]
 	/** 这个点的标签是否显示：false 时即使启用了标签也不画 */
 	labelVisible?: boolean
 	/** 这个点的标签显隐策略：auto 智能隐藏、always 一直显示、hidden 不显示，缺省用 options.label.visibility */
@@ -1113,8 +1228,9 @@ export interface GisViewChannel {
 	 */
 	groups?: GisViewChannelGroup[]
 	/**
-	 * 骨架折线（中心线）：两端用 from / to 绑定点 id 时可以只写中间拐点，首尾顶点由节点坐标决定；
-	 * 完全缺省时取第一条回线自身的路径
+	 * 可选。骨架折线（中心线）：两端用 from / to 绑定点 id 时可以只写中间拐点，首尾顶点由节点坐标决定，
+	 * 不写就是两端直连；未锚定时写完整折线，完全缺省则取第一条回线自身的路径。
+	 * 配了 groups 时，第一组没写自己的 path 会回落到这里
 	 */
 	path?: GisViewCoordinate[]
 	/**
@@ -1567,6 +1683,12 @@ export interface GisViewChannelDraftOptions {
 	linePropsByMember?: Array<Partial<GisViewLine> | undefined>
 	/** 第二段 lineItems（一条或一批）：与 linePropsByMember 同义，给了几条这一段就加几条（circuits 按它对齐）；每项也可以只写一个 id */
 	lineItems?: GisViewChannelLineItems
+	/** 走线方式：'straight'（缺省，两端直连）/ 'orthogonal'（自动补一个先横后纵的 90° 拐点） */
+	routing?: 'straight' | 'orthogonal'
+	/** 中间拐点（不含两端）：给了就按它折线；routing 的自动拐点只在没给有效拐点时补 */
+	path?: GisViewCoordinate[]
+	/** 本次草稿的预览样式：盖在全局 channelDraftStyle 之上，草稿结束即丢弃 */
+	channelDraftStyle?: GisViewChannelDraftStyle
 	/**
 	 * 交接模式：两个节点选完、发完 phase: 'ready' 就把草稿收掉（假通道当场消失、不补 cancel），
 	 * 由使用方在事件里自己调 addChannel 落地；与 autoCommit 同时给时 autoCommit 先落地
@@ -1585,7 +1707,8 @@ export interface GisViewChannelDraftOptions {
 
 /**
  * 新增通道的交互载荷：start → from（选好起点，预览线跟随光标）→ ready（选好终点）→ commit / blocked，
- * 取消走 cancel，连续新增落地之后开下一段走 restart，草稿期间点到空白 / 点回起点走 pick。
+ * 取消走 cancel（已选起点后点空白也会直接取消），连续新增落地之后开下一段走 restart，
+ * 还没选起点时点到空白 / 点回起点走 pick。
  * 两个节点的信息（id / 名称 / 坐标）与可选方案（plan）在每个阶段都带着
  */
 export interface GisViewChannelDraftPayload {
@@ -1625,6 +1748,12 @@ export interface GisViewChannelDraftPayload {
 	/** 第二段 lineItems（一条或一批）：与 linePropsByMember 同一份写法，提交时一起交给 addChannel */
 	lineItems?: Array<Partial<GisViewLine> | undefined> | null
 	channelProps?: Partial<GisViewChannel>
+	/** 这一次草稿实际生效的预览样式（全局配置 + 本次覆盖） */
+	style: GisViewChannelDraftStyle
+	/** 草稿的走线方式：直线 / 自动正交折线 */
+	routing: 'straight' | 'orthogonal'
+	/** 草稿的中间拐点（已选好两端时是实际会落地的那一份，正交路由的拐点也在这里）；没有为 null */
+	path: GisViewCoordinate[] | null
 	/** 两个节点都选好之后才有方案表，否则为 null */
 	plan: GisViewChannelAddPlan | null
 	options: GisViewChannelAddOption[]
@@ -1884,8 +2013,10 @@ export interface GisViewChannelAddInput {
 	 */
 	lineItems?: GisViewChannelLineItems
 	channelProps?: Partial<GisViewChannel>
-	/** 新建通道时的中间拐点 */
+	/** 中间拐点（不含两端）：新建通道写进骨架，新建独立线路展开成完整 path；routing 为 orthogonal 时自动补拐点 */
 	path?: GisViewCoordinate[]
+	/** 走线方式：'straight'（缺省）/ 'orthogonal'（自动补一个先横后纵的 90° 拐点） */
+	routing?: 'straight' | 'orthogonal'
 }
 
 /** 第二段线路数据（新签名的 line_data / 旧写法的 lineItems 同一份）：对象里的 id 就是回线 id（没写的自动编号），裸字符串 / 数字等价于 { id } */
@@ -1924,6 +2055,48 @@ export interface GisViewChannelDraftStyle {
 	width?: number
 	/** 两端圆点半径（CSS 像素），0 表示不画 */
 	dot?: number
+	/** 端点圆点颜色，缺省沿用 color */
+	dotColor?: string
+	/** 预览线末端是否画方向箭头，缺省 false */
+	arrow?: boolean
+	/** 箭头大小（CSS 像素），缺省 12 */
+	arrowSize?: number
+	/** 箭头沿线的归一化位置：0 起点、0.5 中点、1 终点；单个数或数组都可，arrow 为 true 时生效 */
+	arrowPositions?: number | number[]
+	/** 箭头反向（默认从起点指向终点） */
+	arrowReverse?: boolean
+	/** 箭头颜色，缺省沿用 color */
+	arrowColor?: string
+	/** 通道预览的回线间距（CSS 像素，缺省 10）：kind 为 channel 且 circuits > 1 时按它排平行回线 */
+	circuitSpacing?: number
+	/** 整条预览的透明度（0 ~ 1，缺省 1） */
+	opacity?: number
+	/**
+	 * 内置预览画完之后的自绘钩子：拿得到最终 GL 上下文、世界坐标路径与每条回线的路径，
+	 * 适合画自定义箭头 / 标记 / 光环；下一帧会重新调用，需要主动刷新时调用 context.requestRender()
+	 */
+	customDraw?: (context: GisViewChannelDraftDrawContext) => void
+}
+
+/** 草稿自绘钩子的上下文：几何都是世界坐标，投影用 project / unproject */
+export interface GisViewChannelDraftDrawContext {
+	gl: WebGL2RenderingContext
+	canvas: HTMLCanvasElement
+	viewport: GisViewViewport
+	camera: GisViewCamera
+	/** 像素 / 世界单位（与 camera.scale 相同） */
+	scale: number
+	/** 解析后的完整折线（含两端） */
+	path: GisViewCoordinate[]
+	/** 每条回线的实际路径：单回线时只有一条，通道多回线时是平行偏移之后的那几条 */
+	circuitPaths: GisViewCoordinate[][]
+	circuits: number
+	kind: 'channel' | 'line'
+	phase: 'start' | 'from' | 'ready'
+	style: GisViewChannelDraftStyle
+	project(x: number, y: number): [number, number]
+	unproject(x: number, y: number): [number, number]
+	requestRender(): void
 }
 /** 通道成员表：只给成员下标与各自偏移，不复制几何（鹰眼图挑「只画一根」时的中间那条回线用它） */
 export interface GisViewChannelMember {
@@ -2483,7 +2656,7 @@ export type GisViewPointerTarget = 'point' | 'line' | 'channel' | 'waypoint' | '
 /**
  * 一次指针操作的动作名。同一个名字在「按下 / 松开 / 点击」三条事件里含义略有不同：
  * - onPointerDown 是「这一次按下打算做什么」（意图）：'pan' / 'dragPoint' / 'dragWaypoint' / 'boxSelect' /
- *   'copy' / 'channelDraft'（点两次加通道）/ 'contextMenu'（右键）/ 'click'（左键按下，但下面没有可拖的东西）；
+ *   'copy' / 'channelDraft'（点两次加通道）/ 'decorationDraft'（动态装饰器草稿）/ 'contextMenu'（右键）/ 'click'（左键按下，但下面没有可拖的东西）；
  * - onPointerUp 是「刚做完的那一件事」：拖过就是拖动的名字，没拖就是 'click'（配合 action.moved 判读）；
  * - onClick / onDblClick 是真正发生的那一件：'select'（点中要素）/ 'click'（没开选中）/ 'dblClick'（双击）；
  * - 拐点、标签、选中集各有自己那一套：'addWaypoint' / 'dragWaypoint' / 'selectLabel' / 'dragLabel' /
@@ -2507,7 +2680,8 @@ export type GisViewPointerActionType =
 	| 'click'
 	| 'pan'
 	| 'copy'
-	| 'channelDraft'
+	| 'channelDraft'
+	| 'decorationDraft'
 	| 'drag'
 	| 'pointer'
 
@@ -2955,6 +3129,8 @@ export interface GisViewPointMergePayload {
 	target: { index: number; item: GisViewPoint; coordinate: [number, number] }
 	/** 停在目标上的光标位置（画布 CSS 像素） */
 	screen: [number, number] | null
+	/** 这一次合并是按哪种时机命中的，与 merge.trigger 同一口径 */
+	trigger: GisViewMergeTrigger
 	originalEvent: Event | null
 	/** 按当前 keep 预演的影响读数（pending / confirm / state 有值；cancel 与对不上数据时为 null） */
 	impact: GisViewMergeImpact | null
@@ -3139,13 +3315,13 @@ export interface GisViewRemoveSelectedOutcome {
 }
 
 /**
- * updatePoints / updateLines 里的一条：给一个定位（id / 下标 / `{ id }` / `{ index }`，与公共补丁一起用），
+ * patchPoints / patchLines 里的一条：给一个定位（id / 下标 / `{ id }` / `{ index }`，与公共补丁一起用），
  * 或者「定位 + 自己这一份补丁」（`{ id: 'a', name: 'A' }`）—— id / index 之外的字段就是这一条的补丁
  */
 export type GisViewUpdateItemEntry<T> = GisViewPointRef | (Partial<T> & { id?: string | number; index?: number })
 
 /**
- * updatePoints / updateLines 的返回：改完的那几条按 indexes / items 对应列出（items 是数据里的新对象），
+ * patchPoints / patchLines 的返回：改完的那几条按 indexes / items 对应列出（items 是数据里的新对象），
  * 认不出来的定位在 skipped 里（不影响其余条目）。一次调用只发一条数据变更。
  */
 export interface GisViewUpdateItemsOutcome<T = GisViewPoint | GisViewLine> {
@@ -3162,7 +3338,6 @@ export type GisViewDataChangeType =
 	| 'updateData'
 	| 'updatePoints'
 	| 'updateLines'
-	| 'updateChannels'
 	| 'updateOptions'
 	| 'updateBackground'
 	| 'updatePoint'
@@ -3304,6 +3479,45 @@ export interface GisViewEngineStats {
 	/** 动画是否还在排下一帧：静止画面是按需渲染的，这时候是 false */
 	animating: boolean
 	quality: GisViewQualityState
+	/**
+	 * 大数据展示模式的有效读数（组件的 getStats() / onStats / onRender 会带上；纯引擎实例没有这一项）。
+	 * active 为 true 时标签走避让 / 截断档，线路动点与节点涟漪暂停。
+	 */
+	dense?: GisViewDenseState
+}
+
+/** 大数据展示模式的三种档位：auto 按阈值自动切，on / off 强制打开或关闭 */
+export type GisViewDenseMode = 'auto' | 'on' | 'off'
+
+/**
+ * denseMode 的对象写法：阈值都按「正数才生效」处理，不写用内置缺省。
+ * `visibleThreshold` 是视口内节点数，`densityThreshold` 是每百万 CSS 像素的节点数，
+ * `pointThreshold` 是整份数据的节点总数；任意一项越线就进入 dense。
+ */
+export interface GisViewDenseModeOptions {
+	mode?: GisViewDenseMode
+	/** 视口内可见节点达到多少个进入密集档，默认 4000 */
+	visibleThreshold?: number
+	/** 每百万 CSS 像素的可见节点密度阈值，默认 3000 */
+	densityThreshold?: number
+	/** 数据总节点数阈值，默认 50000（只看总量，不要求同屏） */
+	pointThreshold?: number
+}
+
+/** denseMode 的入参：布尔值 true / false 等价于 'on' / 'off' */
+export type GisViewDenseModeInput = boolean | GisViewDenseMode | GisViewDenseModeOptions
+
+/** 大数据展示模式的读数：getStats().dense / onStats / onRender 的 dense 字段 */
+export interface GisViewDenseState {
+	mode: GisViewDenseMode
+	active: boolean
+	/** 这次判定的依据（checking 表示还在等首帧 / 发散渲染铺完） */
+	reason: 'manual-on' | 'manual-off' | 'total' | 'visible' | 'density' | 'below-threshold' | 'checking'
+	/** 最近一次量到的可见节点数（只数到触发阈值；按总量触发时是 null） */
+	visiblePoints: number | null
+	visibleThreshold: number
+	densityThreshold: number
+	pointThreshold: number
 }
 
 /** 渲染帧回调载荷：onStats 的读数 + 帧序号 / 节流间隔 / 时刻与当前相机 */
@@ -3356,6 +3570,20 @@ export type GisViewConditionOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte'
  */
 export type GisViewConditionOperatorTest = (value: unknown) => (current: unknown) => boolean
 
+/** 注册一个自定义条件运算符；名字为空、与内置重名或工厂不是函数时返回 false */
+export declare const registerConditionOperator: (name: string, test: GisViewConditionOperatorTest) => boolean
+/**
+ * 带作用域地注册一个自定义条件运算符：返回清理函数，只在当前注册项仍是这个工厂时删除，
+ * 同名被后注册覆盖时旧清理函数不会误删。参数不合法或撞内置名时抛 TypeError。
+ */
+export declare const defineConditionOperator: (name: string, test: GisViewConditionOperatorTest) => () => boolean
+/** 注销一个自定义条件运算符，返回它之前是否在注册表里；内置运算符不能用它摘掉 */
+export declare const unregisterConditionOperator: (name: string) => boolean
+/** 这个名字能不能用（内置或注册过的自定义） */
+export declare const hasConditionOperator: (name: string) => boolean
+/** 当前能用哪些运算符：内置 14 个在前，自定义按注册顺序跟在后面 */
+export declare const listConditionOperators: () => string[]
+
 /**
  * 显式条件：`{ field: 'vnkv', op: 'gte', value: 500 }`，op 缺省为 eq，not 取反。
  * field 支持 `props.vnkv` 这样的嵌套路径。
@@ -4075,6 +4303,210 @@ export interface GisViewLineDecoration {
 	shadow?: GisViewShadow
 }
 
+/** 动态装饰器草稿的作用域：单条线路 / 命中线所在分组 / 整条通道（不在通道里时都退回单条） */
+export type GisViewDecorationDraftScope = 'line' | 'group' | 'channel'
+
+/** 动态装饰器草稿要命中哪一类要素：线路、节点，或两类同时开启 */
+export type GisViewDecorationDraftTarget = 'line' | 'point' | 'both'
+
+/** 节点装饰的位置来源：相对节点偏移 / 固定世界坐标 / 当前鼠标位置；落地关系另由 anchor 决定 */
+export type GisViewDecorationDraftPointPlacement = 'offset' | 'fixed' | 'pointer'
+
+/**
+ * 节点装饰的落地关系：
+ * - follow：保留相对节点的屏幕偏移，节点移动 / 画布缩放时跟着节点；
+ * - fixed：保留世界坐标，节点移动后仍停在原处。
+ * 缺省由 placement 推导：offset → follow，fixed / pointer → fixed。
+ */
+export type GisViewDecorationDraftPointAnchor = 'follow' | 'fixed'
+
+/** 同一目标位置出现重复装饰时：offset 自动让开，reject 直接不允许添加 */
+export type GisViewDecorationDraftDuplicateStrategy = 'offset' | 'reject'
+
+/** 动态装饰器草稿的阶段：start（开启）→ hover（命中跟随）/ leave（移出目标）→ ready（松手命中）→ commit / cancel */
+export type GisViewDecorationDraftPhase = 'start' | 'hover' | 'leave' | 'ready' | 'update' | 'commit' | 'cancel'
+
+/**
+ * 动态装饰器草稿的配置：图标 / 大小 / 配色与真实线路、节点装饰同一套写法。
+ * `target` 决定命中线路 / 节点 / 两类同时；线路侧 `parallel` 决定是否跟着方向转、`scope` 决定一次给哪些线路都挂上，
+ * `maxPerLine` / `allowedLines` / `allowedChannels` / `allowedGroups` 限定线路目标；
+ * 节点侧 `placement` 决定位置来源（相对偏移 / 固定坐标 / 鼠标位置），`anchor` 决定落地后跟随节点还是固定世界坐标；
+ * `maxPerPoint` / `allowedPoints` 限定节点目标。
+ * 两边都受 `allowDuplicate` / `duplicateStrategy` / `duplicateDistance` 的重复策略约束。
+ */
+export interface GisViewDecorationDraftOptions {
+	/** 命中类型，缺省 'line'（保持原有线路装饰器行为） */
+	target?: GisViewDecorationDraftTarget
+	/** 图片 / SVG / 内置形状，缺省 'circle' */
+	symbol?: GisViewSymbolInput
+	/** 屏幕尺寸（CSS 像素），缺省 18 */
+	size?: number
+	/** 填充 / 色调，缺省白色 */
+	color?: string
+	/** 描边色，缺省透明 */
+	strokeColor?: string
+	/** 描边宽度（CSS 像素），缺省 0 */
+	strokeWidth?: number
+	/** 透明度，缺省 1 */
+	opacity?: number
+	/** 阴影，和节点一样 */
+	shadow?: GisViewShadow
+	/** 是否跟着线路方向转，缺省 false（保持水平） */
+	parallel?: boolean
+	/** 作用域，缺省 'line' */
+	scope?: GisViewDecorationDraftScope
+	/** 离线路多远算命中（屏幕像素），缺省 14；只有贴近线路时才出现预览 */
+	maxDistance?: number
+	/** 每条线路最多允许多少个 decoration（按 `lines[].decorations.length` 计），0 / 缺省 = 不限 */
+	maxPerLine?: number
+	/** 每个节点最多允许多少个 decoration（按 `points[].decorations.length` 计），0 / 缺省 = 不限 */
+	maxPerPoint?: number
+	/** 允许挂装饰的线路 id；空数组 / 缺省表示不限制这一类 */
+	allowedLines?: Array<string | number>
+	/** 允许挂装饰的通道 id；空数组 / 缺省表示不限制这一类 */
+	allowedChannels?: Array<string | number>
+	/** 允许挂装饰的分组 id；空数组 / 缺省表示不限制这一类 */
+	allowedGroups?: Array<string | number>
+	/** 允许挂装饰的节点 id；空数组 / 缺省表示不限制这一类 */
+	allowedPoints?: Array<string | number>
+	/** 节点位置来源，缺省 'offset'（相对节点偏移） */
+	placement?: GisViewDecorationDraftPointPlacement
+	/** 落地关系，缺省由 placement 推导：offset → follow，fixed / pointer → fixed */
+	anchor?: GisViewDecorationDraftPointAnchor
+	/** 相对节点的屏幕像素偏移（x 向右、y 向下），优先于 distance / direction */
+	offset?: [number, number] | GisViewCoordinate
+	/** 相对节点的屏幕像素距离，缺省 28 */
+	distance?: number
+	/** 相对方向：0 度向上、顺时针，缺省 0（正上方） */
+	direction?: number
+	/** placement 为 fixed 时的世界坐标；缺省落在节点中心 */
+	at?: GisViewCoordinate
+	/** 节点装饰旋转角（度），缺省 0 */
+	angle?: number
+	/** 节点装饰连接线：true 用默认样式，对象可覆盖颜色 / 线宽 / 透明度 / 虚线 */
+	connector?: boolean | GisViewPointDecorationConnector
+	/** 是否允许同一目标位置上重复添加，缺省 true（保持原有行为） */
+	allowDuplicate?: boolean
+	/** allowDuplicate 为 false 时：offset 自动让开（缺省），reject 直接拦下 */
+	duplicateStrategy?: GisViewDecorationDraftDuplicateStrategy
+	/** 重复判定容差（屏幕像素），缺省 8 */
+	duplicateDistance?: number
+	/** 触发这次草稿的原始事件（begin / update 时可选带进来） */
+	originalEvent?: Event | null
+}
+
+/** 草稿作用域展开之后的一条目标线路：线路 id 与它在通道 / 分组里的归属 */
+export interface GisViewDecorationDraftLineTarget {
+	lineIndex: number
+	lineId: string | number
+	channelId: string | number | null
+	groupId: string | number | null
+	channelIndex: number | null
+	/** 这条线路当前已有的 decoration 数（maxPerLine 判断用） */
+	existingCount: number
+}
+
+/** 草稿命中的节点目标：节点 id 与已有装饰数（maxPerPoint 判断用） */
+export interface GisViewDecorationDraftPointTarget {
+	pointIndex: number
+	pointId: string | number
+	/** 这个节点当前已有的 decoration 数 */
+	existingCount: number
+	x: number
+	y: number
+}
+
+/**
+ * 动态装饰器草稿的事件载荷（options.onDecorationDraft / on('decorationDraft') 共用）。
+ * phase 为 leave / cancel 时命中相关的字段为 null；targets 是这一次会挂到哪些线路（单条 / 分组 / 整条通道）。
+ */
+export interface GisViewDecorationDraftPayload {
+	phase: GisViewDecorationDraftPhase
+	/** 归一化之后的草稿配置 */
+	options: GisViewDecorationDraftOptions
+	/** 符号类型名（circle / square / svg / image），面板读数用 */
+	symbol: string
+	/** 原始符号写法（可直接写进 decorations[].symbol） */
+	symbolInput: GisViewSymbolInput
+	size: number
+	color: string | null
+	strokeColor: string | null
+	strokeWidth: number
+	opacity: number
+	parallel: boolean
+	scope: GisViewDecorationDraftScope
+	maxDistance: number
+	maxPerLine: number
+	maxPerPoint: number
+	allowedLines: Array<string | number>
+	allowedChannels: Array<string | number>
+	allowedGroups: Array<string | number>
+	allowedPoints: Array<string | number>
+	target: GisViewDecorationDraftTarget
+	placement: GisViewDecorationDraftPointPlacement
+	anchor: GisViewDecorationDraftPointAnchor
+	connector: boolean | GisViewPointDecorationConnector | null
+	allowDuplicate: boolean
+	duplicateStrategy: GisViewDecorationDraftDuplicateStrategy
+	duplicateDistance: number
+	/** 本次预览是否因为不允许重复而自动让开了位置 */
+	duplicateAdjusted: boolean
+	/** 最近一次命中的目标为什么不可用：limit（满额）/ not-allowed（白名单）/ targets-missing（目标已不在）/ duplicate（重复） */
+	blockedReason: string | null
+	/** 沿线比例（0~1）；离开目标线时为 null */
+	position: number | null
+	/** 指针的画布 CSS 像素坐标 */
+	screen: [number, number] | null
+	/** 图标预览的屏幕坐标（节点装饰的固定 / 偏移位置也在这里） */
+	decorationScreen: [number, number] | null
+	/** 图标最终的世界坐标（线路为沿线落点，节点为吸附位置） */
+	world: [number, number] | null
+	/** 图标当前的屏幕旋转角（弧度；线路 parallel 或节点装饰 angle 换算后） */
+	angle: number
+	lineIndex: number | null
+	lineId: string | number | null
+	item: GisViewLine | null
+	channelId: string | number | null
+	groupId: string | number | null
+	channelIndex: number | null
+	/** 命中的线路读数（nearestLineAt 同一份），离开目标线时为 null */
+	hit: GisViewNearestLine | null
+	/** 本次命中的类型；离开目标时为 null */
+	hitKind: 'line' | 'point' | null
+	/** 与 hitKind 相同（便于面板按 targetKind 读数） */
+	targetKind: 'line' | 'point' | null
+	/** 命中的节点下标 / id / 数据；命中线路时为 null */
+	pointIndex: number | null
+	pointId: string | number | null
+	pointItem: GisViewPoint | null
+	pointHit: GisViewNearestPoint | null
+	targets: GisViewDecorationDraftLineTarget[]
+	pointTargets: GisViewDecorationDraftPointTarget[]
+	lineTargetCount: number
+	pointTargetCount: number
+	/** 本次会写入的目标总数（线路目标 + 节点目标） */
+	targetCount: number
+	/** 与 targetCount 相同，commit 事件里便于统一读数 */
+	count: number
+	/** 归一化之后的真实装饰字段，commit 时逐条写进 decorations */
+	decoration: GisViewLineDecoration | null
+	/** 命中节点时归一化之后的真实装饰字段 */
+	pointDecoration: GisViewPointDecoration | null
+	originalEvent: Event | null
+}
+
+/** commitDecorationDraft 的结果：ok 为 false 时 reason 说明原因（no-draft / no-target / limit / not-allowed / targets-missing / duplicate） */
+export interface GisViewDecorationCommitResult {
+	ok: boolean
+	reason?: string
+	count: number
+	targets: GisViewDecorationDraftLineTarget[]
+	decorations: GisViewLineDecoration[]
+	pointTargets: GisViewDecorationDraftPointTarget[]
+	pointDecorations: GisViewPointDecoration[]
+	draft?: GisViewDecorationDraftPayload
+}
+
 /** 悬浮提示内容：模板字符串（`{name}` / `{vnkv}`）或返回文本 / 元素 / null 的函数 */
 export type GisViewTooltipContent = string | ((payload: GisViewPickResult) => string | HTMLElement | number | null | undefined)
 
@@ -4423,10 +4855,17 @@ export interface GisViewInitialView {
 }
 
 /**
- * 插件：视图建好之后调用一次，拿到实例本身；返回 { destroy } 时会挂进实例的 destroy。
+ * 插件：视图建好之后调用一次，拿到实例本身与带 apiVersion 的上下文；返回 { destroy } 时会挂进实例的 destroy。
  * 写一次插件，之后换项目直接复用，不必把「URL 同步 / 自建图例 / 业务操作」再抄一遍。
  */
-export type GisViewPlugin = (view: GisViewInstance) => void | { destroy?: () => void }
+export interface GisViewPluginContext {
+	/** 插件 API 版本：当前为 1；以后只做加字段的向后兼容扩展 */
+	readonly apiVersion: 1
+	/** 与插件第一个参数相同，方便统一改写成只收一个上下文对象 */
+	readonly view: GisViewInstance
+}
+
+export type GisViewPlugin = (view: GisViewInstance, context: GisViewPluginContext) => void | { destroy?: () => void }
 
 /**
  * 快捷键写法（大小写不敏感，多个用 + 连接）：
@@ -4537,7 +4976,16 @@ export interface GisViewMergeOptions {
 	 * **缺省关**：写了这份 merge 配置才算开（`enabled: false` 显式关掉），也可以由 features.merge 强制
 	 */
 	enabled?: boolean
-	/** 额外的碰撞容差（CSS 像素）：两个节点画在屏幕上的半径之和再加它，默认 0 */
+	/**
+	 * 拖拽合并的触发时机：
+	 * - `'collision'`（缺省）：两个节点画在屏幕上的半径之和以内就算碰上，响应更早；
+	 * - `'center'`：拖动的节点中心点进入目标节点的屏幕区域（目标节点半径）时才触发，比碰撞更晚、更稳。
+	 * 两种都再叠加 `distance` 的像素容差。
+	 */
+	trigger?: GisViewMergeTrigger
+	/**
+	 * 额外的像素容差（CSS 像素）：`'collision'` 加在两个节点屏幕半径之和上，`'center'` 加在目标节点半径上，默认 0
+	 */
 	distance?: number
 	/**
 	 * 确认方式：组件不弹任何对话框，只把载荷交给使用方 ——
@@ -4560,6 +5008,8 @@ export interface GisViewMergeOptions {
 	createItem?: (source: GisViewPoint, target: GisViewPoint, context: GisViewMergeContext) => GisViewPoint
 }
 
+/** 拖拽合并的触发时机：两个节点的屏幕半径相碰 / 拖动节点中心进入目标节点区域 */
+export type GisViewMergeTrigger = 'collision' | 'center'
 
 /** 通道选中模式：点中通道里的一条回线时选中什么 */
 export type GisViewChannelSelectMode =
@@ -4590,7 +5040,7 @@ export interface GisViewSelectInBoxOptions {
 	originalEvent?: Event | null
 }
 
-/** confirmPointMerge / payload.confirm 的参数：保留哪一端，以及最终节点（可只给要改的字段） */
+/** resolvePointMerge / payload.confirm 的参数：保留哪一端，以及最终节点（可只给要改的字段） */
 export interface GisViewPointMergeConfirmOptions {
 	keep?: GisViewMergeKeep
 	item?: Partial<GisViewPoint> | null
@@ -5076,6 +5526,8 @@ export interface GisViewEventMap {
 	channelContextMenu: { payload: GisViewChannelContextPayload | null; event: MouseEvent }
 	channelDraft: GisViewChannelDraftPayload
 	channelDraftClick: GisViewChannelDraftPayload
+	/** 动态装饰器草稿：start / hover / leave / ready / update / commit / cancel */
+	decorationDraft: GisViewDecorationDraftPayload
 	/** 分组变化：拆分 / 合并 / 挪线 / 新建组 / 整份声明换（updateChannel），action.type 说明这一笔是什么 */
 	channelGroupChange: GisViewChannelGroupChangePayload
 	dataChange: GisViewDataChangePayload
@@ -5110,6 +5562,110 @@ export type GisViewEventListener<K extends GisViewEventName> = (payload: GisView
 /** `on('*', fn)` 的回调：载荷类型随事件名变化，第二个参数说明这次是哪一条 */
 export type GisViewAnyEventListener = (payload: GisViewEventMap[GisViewEventName], name: GisViewEventName) => void
 
+/** 扩展图形类型：SVG 路径 / 图片 / 外部 Canvas */
+export type GisViewGraphicType = 'path' | 'image' | 'canvas'
+
+/** 图形的锚点：九宫格名字，或 [x, y]（0~1，[0.5, 0.5] 是中心） */
+export type GisViewGraphicAnchor =
+	| 'center' | 'top' | 'bottom' | 'left' | 'right'
+	| 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+	| [number, number]
+
+/** 图形的路径 / 图片样式（与直接写在图形对象上的同名字段等价，直接字段优先） */
+export interface GisViewGraphicStyle {
+	fill?: string
+	stroke?: string
+	lineWidth?: number
+	strokeWidth?: number
+	opacity?: number
+	lineCap?: 'butt' | 'round' | 'square'
+	lineJoin?: 'miter' | 'round' | 'bevel'
+	lineDash?: number[]
+	dash?: number[]
+	dashOffset?: number
+	fillRule?: 'nonzero' | 'evenodd'
+	preserveAspectRatio?: string
+	width?: number
+	height?: number
+}
+
+/**
+ * 一个扩展图形（类似 ECharts 的 graphic）：画在 WebGL 画布之上、标签之下，
+ * 不参与拾取、不进节点 / 线路数据。`x` / `y` 是世界坐标（也可以写 `position: [x, y]`）；
+ * 默认是屏幕像素尺寸，`scaleWithView: true` 时宽高按世界单位随相机缩放。
+ */
+export interface GisViewGraphic {
+	id?: string | number
+	type?: GisViewGraphicType
+	x?: number
+	y?: number
+	position?: [number, number]
+	width?: number
+	height?: number
+	anchor?: GisViewGraphicAnchor
+	offset?: [number, number]
+	rotation?: number
+	scale?: number | [number, number]
+	opacity?: number
+	visible?: boolean
+	zIndex?: number
+	scaleWithView?: boolean
+	d?: string
+	path?: string
+	viewBox?: string | [number, number, number, number]
+	fill?: string
+	stroke?: string
+	strokeWidth?: number
+	lineCap?: 'butt' | 'round' | 'square'
+	lineJoin?: 'miter' | 'round' | 'bevel'
+	lineDash?: number[]
+	dash?: number[]
+	dashOffset?: number
+	fillRule?: 'nonzero' | 'evenodd'
+	style?: GisViewGraphicStyle
+	src?: string
+	href?: string
+	image?: string
+	alt?: string
+	crossOrigin?: 'anonymous' | 'use-credentials' | ''
+	referrerPolicy?: ReferrerPolicy
+	preserveAspectRatio?: string
+	canvas?: HTMLCanvasElement
+	element?: HTMLCanvasElement
+}
+
+/** WebGL 自定义层 draw 回调的上下文：画在组件内置内容之后，坐标是最终画布的设备像素 */
+export interface GisViewWebGLLayerDrawContext {
+	gl: WebGL2RenderingContext
+	/** 最终画布：width / height 是绘制缓冲尺寸（CSS 尺寸乘 pixelRatio） */
+	canvas: HTMLCanvasElement
+	viewport: GisViewViewport
+	camera: GisViewCamera
+	/** 第几帧（从 1 开始），用来做按帧推进的自定义动画 */
+	frame: number
+	/** 世界坐标 → 画布 CSS 像素 */
+	project(x: number, y: number): [number, number]
+	/** 画布 CSS 像素 → 世界坐标 */
+	unproject(x: number, y: number): [number, number]
+	/** 外部数据变了时请求下一帧（层内动画也可以每帧调用） */
+	requestRender(): void
+}
+
+/**
+ * WebGL 自定义层：直接拿组件的 WebGL2 上下文画自己的东西（标记、特效、调试几何…）。
+ * 每层开画前会重置到默认帧缓冲、全画布 viewport 与 SRC_ALPHA / ONE_MINUS_SRC_ALPHA 混合；
+ * 层不影响数据、拾取、标签与导出，只在屏幕上叠加。
+ */
+export interface GisViewWebGLLayer {
+	/** 层 id：同 id 再加会覆盖；不写自动生成 */
+	id?: string | number
+	/** 绘制顺序，从小到大（缺省 0）；同 order 保持加入顺序 */
+	order?: number
+	/** false 时跳过这一层（缺省 true） */
+	enabled?: boolean
+	draw(context: GisViewWebGLLayerDrawContext): void
+}
+
 export interface GisViewOptions {
 	/**
 	 * 功能开关：预设名（'edit' / 'view' / 'static'）、开关表或布尔值 ——
@@ -5135,6 +5691,13 @@ export interface GisViewOptions {
 	 * 缺省 'high'，与从前完全一致。运行时 setQuality() 换档、getQuality() 读当前档位与最近一帧耗时。
 	 */
 	quality?: GisViewQualityOptions
+	/**
+	 * 大数据展示模式：`'auto'`（缺省）按视口内可见节点数、屏幕密度与数据总量自动切；
+	 * `'on'` / `'off'` / true / false 强制开关；对象写法可改三档阈值（见 GisViewDenseModeOptions）。
+	 * 进入密集档后标签自动走避让 / 截断（等价 labelOptimize: true），线路动点与节点涟漪暂停；
+	 * 运行时用 updateOptions({ denseMode }) 切换，当前有效值与判定依据看 getStats().dense。
+	 */
+	denseMode?: GisViewDenseModeInput
 	/**
 	 * 渲染后端开关：'auto'（缺省）/ 'webgl2' / 'webgpu'，布尔值 true / false 等价于 'webgpu' / 'webgl2'。
 	 * 当前实装的绘制后端只有 WebGL2 —— 第 18 章量得很清楚：十万级下换 WebGPU 省不到填充率与
@@ -5148,7 +5711,7 @@ export interface GisViewOptions {
 	 * 这里是全局缺省，逐条线路的 lines[].effect / 逐点 points[].effect 覆盖它（写法见 GisViewLineEffect /
 	 * GisViewPointEffect）。不配 = 没有全局缺省（数据里自己配了 effect 的照样动）；
 	 * `false` / `{ enabled: false }` = 一处关掉所有动画（连逐要素配好的也一起关）。
-	 * 运行时 setEffects() 换一份、getEffects() 读归一化之后的配置、getLineEffects() 读这一帧动点的位置。
+	 * 运行时 updateOptions({ effects }) 换一份、getEffects() 读归一化之后的配置、getLineEffects() 读这一帧动点的位置。
 	 */
 	effects?: GisViewEffectsInput
 	/**
@@ -5189,6 +5752,8 @@ export interface GisViewOptions {
 	channelGroupMaxLines?: number
 	/** 新增通道草稿线的样式（跟随光标的那条预览线） */
 	channelDraftStyle?: GisViewChannelDraftStyle
+	/** WebGL 自定义层：内置内容之后按 order 绘制；运行时用 addWebGLLayer / updateWebGLLayer 等维护 */
+	webglLayers?: GisViewWebGLLayer[]
 	background?: GisViewBackground
 	pointStyle?: GisViewPointStyle
 	lineStyle?: GisViewLineStyle
@@ -5227,6 +5792,12 @@ export interface GisViewOptions {
 	 * `exportData({ format: 'input' })` 的结果里叫 `labelStates`，原样接上即可完成存档 → 回灌
 	 */
 	labelStates?: GisViewLabelState[]
+	/**
+	 * 与节点无关的扩展图形：在画布之上、标签之下绘制 SVG 路径 / 图片 / Canvas，
+	 * 支持世界坐标锚点、旋转、透明度、zIndex 与随视图缩放。运行时用 addGraphic / addGraphics /
+	 * updateGraphic / removeGraphic / clearGraphics 增删改；exportImage 的 PNG / SVG 都会带上这一层。
+	 */
+	graphics?: GisViewGraphic[]
 	/** 悬停提示：配了就按这个配置显示，点 / 线 / 通道可分别配置内容 */
 	tooltip?: GisViewTooltipOptions
 	/** 初始筛选条件，等价于创建之后调用 setFilter；可以写完整格式，也可以只给节点条件 */
@@ -5367,7 +5938,10 @@ export interface GisViewOptions {
 	copy?: GisViewCopyOptions
 	/** 合并节点（**缺省关**：写了这份配置才算开）：把一个节点拖到另一个节点上（考虑碰撞）时怎么确认与怎么并 */
 	merge?: GisViewMergeOptions
-	/** 是否允许编辑线路拐点：Ctrl + 点击添加、拖动移动、双击或 Delete 删除；**缺省关**，单条线可用 waypointEditable 覆盖 */
+	/**
+	 * 是否允许编辑线路拐点：Ctrl + 点击添加、拖动移动、双击或 Delete 删除；**缺省关**，单条线可用 waypointEditable 覆盖。
+	 * `false`（以及 `features: { waypoint: false }`）会同时关闭新增、移动与删除；没有只关其中一项的细分开关
+	 */
 	waypointEditable?: boolean
 	/** 拐点显示时机：selected 只在线路被选中（或刚加过拐点）时显示，always 始终显示；默认 selected */
 	waypointVisibility?: 'selected' | 'always'
@@ -5398,7 +5972,7 @@ export interface GisViewOptions {
 	 */
 	renderEmitInterval?: number
 	/**
-	 * 插件：视图建好之后依次调用`plugin(view)`，用来把跨项目复用的逻辑
+	 * 插件：视图建好之后依次调用 `plugin(view, context)`（context 带 apiVersion / view），用来把跨项目复用的逻辑
 	 * （URL 同步、业务快捷操作、自建图例…）封装成一份；返回值里的 destroy 会在 view.destroy() 时回调。
 	 */
 	plugins?: GisViewPlugin[]
@@ -5482,6 +6056,8 @@ export interface GisViewOptions {
 	onChannelDraft?: (payload: GisViewChannelDraftPayload) => void
 	/** 草稿里每点一次发一条：step 1 拿到起点、step 2 拿到终点（线路结束），载荷与 onChannelDraft 相同 */
 	onChannelDraftClick?: (payload: GisViewChannelDraftPayload) => void
+	/** 动态装饰器草稿：鼠标在线路上跟随 / 移出 / 松手 ready，以及 update / commit / cancel */
+	onDecorationDraft?: (payload: GisViewDecorationDraftPayload) => void
 	/** 分组变化：拆分 / 合并 / 挪线 / 新建组 / 整份声明换（updateChannel），action.type 说明这一笔是什么 */
 	onChannelGroupChange?: (payload: GisViewChannelGroupChangePayload) => void
 	onCameraChange?: (camera: GisViewCamera) => void
@@ -5677,48 +6253,6 @@ export interface GisViewExportSelectionResult {
 	lineIndexes: number[]
 }
 
-/**
- * exportSelectionData 的选项：选中口径与 exportSelection 完全一致（不给 points 就用当前选中集里的节点，
- * 线路取两端都在导出集里的那些），但出的是一份份业务表口径的记录，按 parts 多选。
- */
-export interface GisViewExportSelectionDataOptions {
-	/** 要导出的节点（id / 下标 / `{ id }` / `{ index }`，单个或数组）；缺省用当前选中集里的节点 */
-	points?: GisViewFeatureRef | GisViewFeatureRef[]
-	/** 要导出的线路：缺省取两端都在导出集里的那些（withLines: false 表示不要线路） */
-	lines?: GisViewFeatureRef | GisViewFeatureRef[]
-	/** 要导出的通道：缺省取成员里有导出线路的那些通道 */
-	channels?: GisViewFeatureRef | GisViewFeatureRef[]
-	/** 是否带上「两端都在这批节点里」的线路（含通道回线），缺省 true；显式给了 lines 时以 lines 为准 */
-	withLines?: boolean
-	/** 要哪几份（多选，见 GisViewExportPart）；缺省四份都要，选了通道 / 线路会自动带上拐点 */
-	parts?: GisViewExportPart | GisViewExportPart[]
-	/** 拐点要不要连没编辑过的分组一起列（同 exportParallelGroups 的 all），缺省 false */
-	all?: boolean
-	/** 额外挂到结果上的字段（同导出数据的 extra） */
-	extra?: Record<string, unknown>
-}
-
-/**
- * exportSelectionData 的返回：只带上 parts 选中的那几份（选通道 / 线路时 parallelGroups 会自动在内），
- * 每份与同名的分项导出同一口径 —— points 是 station_data 那一套、lines 是 line_data、
- * channels 是 channel_data、parallelGroups 是 parallel_groups，直接回写业务表。
- */
-export interface GisViewExportSelectionDataResult extends GisViewExportMeta {
-	/** ok 为 false 时说明原因（没有选中的节点 / 没找到要导出的节点） */
-	reason: string | null
-	points?: GisViewStationRecord[]
-	lines?: GisViewLineRecord[]
-	channels?: GisViewChannelRecord[]
-	parallelGroups?: GisViewParallelGroup[]
-	/** 这次带了哪几份（view 口径的键名，含自动补上的 parallelGroups） */
-	parts: Array<'points' | 'lines' | 'channels' | 'parallelGroups'>
-	counts: { points: number; lines: number; channels: number; parallelGroups: number }
-	/** 导出用的节点 / 线路 / 通道下标（升序，可以直接交给别的接口继续用） */
-	pointIndexes: number[]
-	lineIndexes: number[]
-	channelIndexes: number[]
-}
-
 /** 定位一条线路 / 一条通道 / 一个分组：与 GisViewPointRef 同一种写法（id、下标或 `{ id }` / `{ index }`） */
 export type GisViewFeatureRef = string | number | { id: string | number } | { index: number }
 
@@ -5852,68 +6386,21 @@ export interface GisViewChannelRecord {
 	[key: string]: unknown
 }
 
-/** 导出节点数据（new.json 的 station_data 口径）的选项 */
-export interface GisViewExportStationDataOptions extends GisViewExportFilterOptions {
-	/** 要不要带 new.json 顶上那四列四至范围（max_lat / min_lat / max_lon / min_lon），缺省 true */
-	box?: boolean
-	/** 要不要带 show_station_list / show_station_data（站内母线清单，new.json 里就在节点表隔壁），缺省 true */
-	showStation?: boolean
-	/** new.json 的 tc_file_path / warning_msg 两列，缺省是空串 / 空数组，也可以走 extra 给 */
-	tcFilePath?: string
-	warningMsg?: unknown[]
-	tc_file_path?: string
-	warning_msg?: unknown[]
-}
-
-/** exportStationData 的返回：节点表 + new.json 顶上那几列 */
-export interface GisViewExportStationDataResult extends GisViewExportMeta {
-	station_data: GisViewStationRecord[]
-	counts: { points: number }
-	max_lat?: number | null
-	min_lat?: number | null
-	max_lon?: number | null
-	min_lon?: number | null
-	show_station_list?: unknown[]
-	show_station_data?: unknown[][]
-	tc_file_path?: string
-	warning_msg?: unknown[]
-}
+/** 内置的五档导出格式；自定义名字用 registerExportFormat 注册 */
+export type GisViewBuiltinExportFormat = 'view' | 'new' | 'test' | 'input' | 'full'
+/** exportData 认的格式名：内置五档，或注册过的自定义名字 */
+export type GisViewExportFormat = GisViewBuiltinExportFormat | (string & {})
 
-/** exportPointData 的返回：test.json 的 point_data */
-export interface GisViewExportPointDataResult extends GisViewExportMeta {
-	point_data: GisViewPointRecord[]
-	counts: { points: number }
-}
-
-/** exportLineData 的返回：test.json 的 line_data */
-export interface GisViewExportLineDataResult extends GisViewExportMeta {
-	line_data: GisViewLineRecord[]
-	counts: { lines: number }
-}
+/** 导出范围：all 全量、viewport 当前视口、selection 当前选中集（exportData 的统一入口） */
+export type GisViewExportScope = 'all' | 'viewport' | 'selection'
 
-/** exportChannelData 的返回：new.json 的 channel_data（counts.lines 是这些通道里回线的总数） */
-export interface GisViewExportChannelDataResult extends GisViewExportMeta {
-	channel_data: GisViewChannelRecord[]
-	counts: { channels: number; lines: number }
-}
-
-/** 导出拐点分组的选项 */
-export interface GisViewExportParallelGroupsOptions extends GisViewExportFilterOptions {
-	/**
-	 * 缺省 false：只出加过 / 拖过拐点的分组（与 getParallelGroups 同一份）；
-	 * true：把当前所有通道分组（以及通道外带折线的线路）都列出来，声明里原本就写了拐点的也在
-	 */
-	all?: boolean
-}
-
-/** exportParallelGroups 的返回：test.json 的 parallel_groups */
-export interface GisViewExportParallelGroupsResult extends GisViewExportMeta {
-	parallel_groups: GisViewParallelGroup[]
-	counts: { parallelGroups: number; waypoints: number }
-}
-
-/** 导出数据的选项：format 决定要哪一套列名，points / lines / channels 三个筛选搭着用 */
+/**
+ * 导出数据的选项：`scope` 决定导哪一块，`format` 决定要哪一套列名，
+ * `parts` 决定要哪些分项，points / lines / channels 三个筛选搭着用。
+ */
 export interface GisViewExportDataOptions extends GisViewExportFilterOptions {
+	/** 导出范围，缺省 'all'；selected / visible 之类的同义词在运行时也认 */
+	scope?: GisViewExportScope
 	/**
 	 * 要哪一套：'view'（缺省，节点 / 线路 / 通道 / 拐点分组四份，JS 风格的键名）/
 	 * 'new'（new.json 口径的整份：station_data + channel_data + 四至范围那几列）/
@@ -5922,27 +6409,64 @@ export interface GisViewExportDataOptions extends GisViewExportFilterOptions {
 	 * updateData + updateOptions 回显，是回灌 / 存档用的那一档）/
 	 * 'full'（标准数据文档，见 GisViewDocument：format / version / points / lines / channels /
 	 * labelStates / view / filter 八列，与 createGisView / importData 的整份入参是同一份写法，
-	 * 「导出 → 存下来 → 读回来 → 再导出」逐字节相同）
+	 * 「导出 → 存下来 → 读回来 → 再导出」逐字节相同）；
+	 * 也可以是 registerExportFormat 注册过的自定义名字
 	 */
-	format?: 'view' | 'new' | 'test' | 'input' | 'full'
+	format?: GisViewExportFormat
 	/**
 	 * 要哪几份（多选，见 GisViewExportPart）：不写是四份都要（老行为），写了只出选中的那几份；
 	 * 选了通道或线路会自动带上拐点。'new' 口径里线路折在 channel_data 里、'test' 口径里通道写在
 	 * 回线的 channel_id 列上，这两种口径下「要线路 / 通道」会带上对应那一份
 	 */
 	parts?: GisViewExportPart | GisViewExportPart[]
-	/** format 为 'view' / 'test' 时拐点分组要不要连没编辑过的分组一起列（见 exportParallelGroups） */
+	/** format 为 'view' / 'test' 时拐点分组要不要连没编辑过的分组一起列 */
 	all?: boolean
 	/** format 为 'new' 时 new.json 的 tc_file_path / warning_msg 两列 */
 	tcFilePath?: string
 	warningMsg?: unknown[]
+	/** format 为 'new' 时要不要带四至范围（max_lat / min_lat / max_lon / min_lon），缺省带 */
+	box?: boolean
+	/** format 为 'new' 时要不要带 show_station_list / show_station_data，缺省带 */
+	showStation?: boolean
+	/** scope 为 'viewport' 时视口外扩的屏幕 CSS 像素，缺省 0 */
+	margin?: number
+	/** scope 为 'viewport' 时直接给一份世界矩形替掉当前视口 */
+	rect?: GisViewBounds
 }
 
+/**
+ * 自定义导出器拿到的上下文：document 已经按标准文档做过深拷贝、坐标归一与 JSON 安全，
+ * counts 与 documentCounts(document) 同一份；warnings 可以继续追加，exportData 会统一走 onWarning。
+ * 返回值就是 exportData 的返回值，必须是同步的普通数据（不能返回 Promise）。
+ */
+export interface GisViewExportFormatContext {
+	view: GisViewInstance
+	document: GisViewDocument
+	counts: GisViewDocumentCounts
+	options: GisViewExportDataOptions & { format: string }
+	parts: GisViewExportPart[]
+	warnings: string[]
+}
+
+/** 自定义导出器的函数签名；Result 由调用方按自己的 DTO 指定 */
+export type GisViewExportFormatAdapter<Result = unknown> = (context: GisViewExportFormatContext) => Result
+
 /**
  * exportData 的返回：format 决定带上哪几组键（认键名就知道是哪一套）。
  * counts 四份都有，warnings 是没找到的 id 这类提示
  */
 export interface GisViewExportDataResult extends GisViewExportMeta {
+	/** 这次实际用的导出范围 */
+	scope?: GisViewExportScope
+	/** scope 为 'selection' 时：成功为 null，没有可导出的节点时为原因 */
+	reason?: string | null
+	/** scope 为 'selection' 时导出的节点 / 线路 / 通道下标 */
+	pointIndexes?: number[]
+	lineIndexes?: number[]
+	channelIndexes?: number[]
+	/** scope 为 'viewport' 时这次筛用的世界矩形与屏幕像素外扩 */
+	viewRect?: GisViewBounds
+	margin?: number
 	/**
 	 * format 为 'view'（缺省）：节点 / 线路 / 通道（new.json 口径的业务记录）；
 	 * format 为 'input'：与 createGisView 入参同构的当前数据副本（拖过的点、改过的拐点、
@@ -5979,28 +6503,6 @@ export interface GisViewExportDataResult extends GisViewExportMeta {
 	parts?: Array<'points' | 'lines' | 'channels' | 'parallelGroups'>
 }
 
-/**
- * exportViewportData 的选项：与 exportData 同一套写法，范围改由视口决定 ——
- * points / lines / channels 这三个筛选这一档不认（写了也按视口来），要放宽 / 换范围用 margin / rect
- */
-export interface GisViewExportViewportOptions extends GisViewExportDataOptions {
-	/** 视口外再往外扩多少**屏幕 CSS 像素**：贴着边的一圈也带上（按当前 scale 换算），缺省 0 */
-	margin?: number
-	/** 直接给一份世界矩形替掉当前视口（写法同 getViewRect()，也认 listPoints / listLines 的 inView 那一份） */
-	rect?: GisViewBounds
-}
-
-/** 视口导出多带的读数：这次筛用的世界矩形与屏幕像素外扩 */
-export interface GisViewExportViewportMeta {
-	/** 这次筛用的世界矩形（含 margin 换算过来的外扩） */
-	viewRect: GisViewBounds
-	/** 实际生效的屏幕像素外扩，缺省 0 */
-	margin: number
-}
-
-/** exportViewportData 的返回：exportData 那一份读数（format 决定带哪几组键）+ viewRect / margin 两条位置读数 */
-export interface GisViewExportViewportResult extends GisViewExportDataResult, GisViewExportViewportMeta {}
-
 
 /**
  * 标准数据文档的一份视图落位：相机那一列（`view.camera`，导出时写全，读回来就在同一屏）。
@@ -6223,6 +6725,34 @@ export interface GisViewSceneRegion {
  * 当前画面的矢量快照：屏幕坐标（CSS 像素）的纯数据，交给 buildSceneSvg 就是一份 SVG。
  * 画序与 WebGL 那一帧一致：背景 → 底图 → 区域 → 网格 → 线 → 点 → 背景点 → 装饰 → 拐点 → 抬层的点 → 标签。
  */
+/** 矢量快照里的扩展图形（屏幕坐标；href 是图片地址 / Canvas 的 PNG data URL） */
+export interface GisViewSceneGraphic {
+	id: string
+	type: GisViewGraphicType
+	x: number
+	y: number
+	left: number
+	top: number
+	width: number
+	height: number
+	anchor: [number, number]
+	rotation: number
+	scale: [number, number]
+	opacity: number
+	d: string
+	viewBox: [number, number, number, number]
+	fill: string
+	stroke: string
+	strokeWidth: number
+	lineCap: string
+	lineJoin: string
+	lineDash: number[]
+	dashOffset: number
+	fillRule: string
+	href: string | null
+	preserveAspectRatio: string
+}
+
 export interface GisViewSceneSnapshot {
 	width: number
 	height: number
@@ -6233,6 +6763,7 @@ export interface GisViewSceneSnapshot {
 	/** 网格（关了网格或带了透明背景时为 null） */
 	grid: { d: string; color: string } | null
 	regions: GisViewSceneRegion[]
+	/** 数据线路与节点装饰连接线（连接线也画在节点 / 装饰之前） */
 	lines: GisViewSceneLine[]
 	points: GisViewSceneNode[]
 	backgroundPoints: GisViewSceneNode[]
@@ -6240,6 +6771,8 @@ export interface GisViewSceneSnapshot {
 	waypoints: GisViewSceneNode[]
 	/** 选中 / 拖动中的节点（画在最上面） */
 	raised: GisViewSceneNode[]
+	/** 扩展图形（画在标签之前；直接读 engine.snapshotScene 时没有这一列） */
+	graphics?: GisViewSceneGraphic[]
 	labels: GisViewLabelBox[]
 }
 
@@ -6256,6 +6789,22 @@ export interface GisViewInstance {
 	readonly el: HTMLElement
 	readonly canvas: HTMLCanvasElement
 	readonly gl: WebGL2RenderingContext | null
+	/** 请求重画一帧：自定义 WebGL 层的数据源变了、组件自己不知道时调用 */
+	requestRender(): GisViewInstance
+	/**
+	 * 加一个 WebGL 自定义绘制层（同 id 覆盖）：draw 在内置内容之后、最终画布上执行。
+	 * 返回卸载函数；层只影响画面，不参与拾取 / 场景解析 / 数据导出。
+	 * 同 id 后来被别的层覆盖时，旧卸载函数不会误删新层
+	 */
+	addWebGLLayer(layer: GisViewWebGLLayer): () => void
+	/** 改一个 WebGL 层（order / enabled / draw），返回改后的读数；id 不存在时 null */
+	updateWebGLLayer(id: string | number, patch: Partial<GisViewWebGLLayer>): GisViewWebGLLayer | null
+	/** 删一个 WebGL 层，返回删掉的读数；id 不存在时 null */
+	removeWebGLLayer(id: string | number): GisViewWebGLLayer | null
+	/** 清空全部 WebGL 层，返回清掉的条数 */
+	clearWebGLLayers(): number
+	/** 当前 WebGL 层读数（按 order 排好） */
+	getWebGLLayers(): GisViewWebGLLayer[]
 	updateOptions(options?: GisViewOptions, replace?: boolean): GisViewInstance
 	/**
 	 * 改全局点样式的某几个字段（字段级合并，不写的保持原来那一份；传 null 清掉整份全局点样式）：
@@ -6273,20 +6822,10 @@ export interface GisViewInstance {
 	 * 第三个参数给 channels 时连通道一起换 —— 切场景（场站与通道整批变了）一次换完、只发一条数据变更。
 	 * 也收单对象写法：`updateData({ points, lines, channels })` 只换给出的那几列 ——
 	 * 接口返回的数据先在调用方映射成这三列（见 demo 里的做法），再整份喂进来。
+	 * 只换通道声明时写 `updateData({ channels })`（场站与回线数据不动）。
 	 */
 	updateData(points?: GisViewPoint[], lines?: GisViewLine[], channels?: GisViewChannel[]): GisViewInstance
 	updateData(payload: GisViewDocumentSource): GisViewInstance
-	/**
-	 * 整份换通道声明（回线怎么分组、骨架拐点在哪）：场站与回线数据一个都不动，引擎按新声明重排一遍。
-	 * 与 updateChannel 的分工：那一条是按 id 给某一条通道打补丁（定向），这一条是全换、点不出某一条；
-	 * 声明里的 `lineIds` 同样是通道成员的整表 —— 落地前逐条与 `groups` 调和（写了非空 `lineIds`
-	 * 就以它为准、`groups` 按它收窄；「只写 groups」的声明原样保留）；
-	 * 声明里没写分组 id 时引擎按「单组用通道 id、多组 通道id::序号」补，并把补好的分组（含拐点路径）与对齐后的成员表
-	 * 写回数据副本；声明里认不出的成员 id、重名的分组 id 各报一句 warning，不静默
-	 */
-	updateChannels(channels?: GisViewChannel[]): GisViewInstance
-	updatePoints(points?: GisViewPoint[]): GisViewInstance
-	updateLines(lines?: GisViewLine[]): GisViewInstance
 	/**
 	 * 整份喂回一份数据 / 一份标准文档（`exportData` 的五种格式都认，最标准的是 `format: 'full'` 那一份）：
 	 * 顶层出哪一列就应用哪一列，没出的列一个都不动 —— points / lines / channels / labelStates / view / filter
@@ -6372,6 +6911,20 @@ export interface GisViewInstance {
 	resetLabel(kind: GisViewLabelKind, ref: GisViewFeatureRef, labelId?: string): boolean
 	/** 恢复某一类（不写则两类都恢复）标签的默认：返回清掉几条状态 */
 	resetLabels(kind?: GisViewLabelKind): number
+	/** 新增一个扩展图形（世界坐标上的 SVG 路径 / 图片 / Canvas）：id 已存在时按更新覆盖 */
+	addGraphic(graphic: GisViewGraphic): GisViewGraphic | null
+	/** 批量新增扩展图形：返回实际加进去的读数数组 */
+	addGraphics(graphics: GisViewGraphic | GisViewGraphic[]): GisViewGraphic[]
+	/** 改一个扩展图形（patch 与创建写法一致）：id 不存在时返回 null */
+	updateGraphic(id: string | number, patch: Partial<GisViewGraphic>): GisViewGraphic | null
+	/** 删一个扩展图形：返回删掉的读数；id 不存在时返回 null */
+	removeGraphic(id: string | number): GisViewGraphic | null
+	/** 清空全部扩展图形：返回清掉的条数 */
+	clearGraphics(): number
+	/** 读一个扩展图形（副本，没有时 null） */
+	getGraphic(id: string | number): GisViewGraphic | null
+	/** 现在有哪些扩展图形（按 zIndex、再按加入顺序） */
+	getGraphics(): GisViewGraphic[]
 	updateBackground(background?: GisViewBackground): GisViewInstance
 	/**
 	 * 把当前画面导出成图片（data URL）：画布内容 + DOM 标签合成到一张 2D 画布上。
@@ -6386,46 +6939,18 @@ export interface GisViewInstance {
 	 */
 	exportSelection(options?: GisViewExportSelectionOptions): Promise<GisViewExportSelectionResult>
 	/**
-	 * 导出「选中的这一撮」的数据（分项多选）：选中口径与 exportSelection 一致，
-	 * 出的是一份份业务表口径的记录（points = station_data、lines = line_data、channels = channel_data、
-	 * parallelGroups = parallel_groups），选了通道 / 线路自动带上拐点；缺省四份都出
-	 */
-	exportSelectionData(options?: GisViewExportSelectionDataOptions): GisViewExportSelectionDataResult
-	/**
-	 * 一次把数据按概念分好：节点 / 线路 / 通道 / 拐点分组四份互不混在一起，一次拿走（都是拷贝，改它不影响组件内部那一份）。
+	 * 统一导出入口：`scope` 决定导全量（all，缺省）/ 视口（viewport）/ 选中（selection），
+	 * `parts` 决定要场站 / 线路 / 通道 / 拐点里的哪几份，其余筛选与 format 照旧。
+	 * 一次把数据按概念分好：节点 / 线路 / 通道 / 拐点分组四份互不混在一起（都是拷贝，改它不影响组件内部那一份）。
 	 * 缺省给 { points, lines, channels, parallelGroups }；format: 'new' 给 new.json 口径的整份
 	 * （station_data + channel_data + 四至范围那几列）；format: 'test' 给 test.json 口径的整份
 	 * （point_data + line_data + parallel_groups）；format: 'full' 给一份标准数据文档（单独一条重载，
-	 * 返回 GisViewDocument 本身，八列齐全、没有 ok / counts / warnings 这些读数）
+	 * 返回 GisViewDocument 本身，八列齐全、没有 ok / counts / warnings 这些读数）；
+	 * format 是 registerExportFormat 注册过的名字时，走自定义导出器，返回它的结果（可写泛型指定 DTO）
 	 */
 	exportData(options: GisViewExportDataOptions & { format: 'full' }): GisViewDocument
+	exportData<Result = GisViewExportDataResult>(options: GisViewExportDataOptions & { format: string }): Result
 	exportData(options?: GisViewExportDataOptions): GisViewExportDataResult
-	/**
-	 * 导出**视口内**的数据：节点 / 线路 / 通道先按当前可视范围（getViewRect()）筛一遍再出 ——
-	 * 可见判定与图上画出来的那一份、与 listPoints / listLines 的 inView 完全一致（被筛选 / 隐藏、
-	 * 发散渲染还没铺到的不算）；通道取「成员回线有一条在视口里」的那些，分组一起跟着走。
-	 * 其余参数与 exportData 同写（format / parts / labels / box…），margin 是屏幕 CSS 像素的外扩、
-	 * rect 可以直接给一份世界矩形；返回里多带 viewRect / margin 两条读数
-	 */
-	exportViewportData(options: GisViewExportViewportOptions & { format: 'full' }): GisViewDocument & GisViewExportViewportMeta
-	exportViewportData(options?: GisViewExportViewportOptions): GisViewExportViewportResult
-	/**
-	 * 导出节点数据（new.json 的 station_data 口径）：id / 名称 / 电压 / 经纬度 + 站内母线那几列
-	 * （bus_name_list / bus_id_list / trafo_* / feedin_relation_*），其余业务列原样透传；
-	 * 一并给 new.json 顶上那几列：四至范围（box，缺省给）与 show_station_list / show_station_data
-	 */
-	exportStationData(options?: GisViewExportStationDataOptions): GisViewExportStationDataResult
-	/** 导出节点数据（test.json 的 point_data 口径）：同一份节点换一套列名（带 zone_id / zone_name） */
-	exportPointData(options?: GisViewExportFilterOptions): GisViewExportPointDataResult
-	/**
-	 * 导出线路数据（test.json 的 line_data 口径）：通道回线带上 channel_id / channel_name /
-	 * parallel_group_id 与第几回，coords_list 是当下画出来的折线（含平行偏移）
-	 */
-	exportLineData(options?: GisViewExportFilterOptions): GisViewExportLineDataResult
-	/** 导出通道数据（new.json 的 channel_data 口径）：一条通道一行，回线在 line_data 里，整条通道的路由在 coords 里 */
-	exportChannelData(options?: GisViewExportFilterOptions): GisViewExportChannelDataResult
-	/** 导出拐点分组（test.json 的 parallel_groups 口径）：与通道数据分开取，直接回写业务数据 */
-	exportParallelGroups(options?: GisViewExportParallelGroupsOptions): GisViewExportParallelGroupsResult
 	/**
 	 * 当前画面的矢量快照（屏幕坐标的线 / 点 / 标签 / 背景 / 网格）：导出 SVG 或自拼别的矢量格式时用它。
 	 * 与 WebGL 那一帧读同一份解析结果，所以颜色 / 线宽 / 线型与画面一致；引擎还没准备好时是 null
@@ -6471,11 +6996,6 @@ export interface GisViewInstance {
 	setMinimapZoom(zoom: number): GisViewInstance
 	/** 在当前倍数上再乘一个系数，origin 是鹰眼图内的 CSS 像素锚点，缺省取小图中心 */
 	zoomMinimapBy(factor: number, origin?: [number, number]): GisViewInstance
-	/**
-	 * 换动画效果的整体配置（写法与 options.effects 一致，见 GisViewEffectsOptions）：
-	 * 样式类快路径 —— 重解析要素、不重铺数据，逐要素的 effect 在这一次重解析里定下来。
-	 */
-	setEffects(effects: GisViewEffectsInput): GisViewInstance
 	/** 当前生效的动画效果配置（归一化之后的读数）：没配的那一层是 null */
 	getEffects(): GisViewEffectsReadout
 	/**
@@ -6582,12 +7102,6 @@ export interface GisViewInstance {
 	 * 「点了一条回线，想知道它属于哪条通道 / 哪一组」用它一句问清。
 	 */
 	getLineChannel(ref: GisViewFeatureRef): GisViewLineChannelInfo | null
-	/**
-	 * 接口选中（换一份选中集）：单选传 id，多选传数组，null / 空数组清空。
-	 * 写法与 selectFeatures 一致 —— 数组里可以混着写 id 与对象（见 GisViewSelectionRef），
-	 * options.mode 也给同一份（'add' / 'toggle' / 'remove'）
-	 */
-	select(refs: GisViewSelectionRefs, options?: GisViewSelectOptions): GisViewInstance
 	/**
 	 * 让一批东西变成选中状态（接口选中）：与点击选中走同一份 state，因此 getSelections / getSelectionData
 	 * getSelectionData 立刻就能读回来。认这些写法（见 GisViewSelectionRef）：
@@ -6602,7 +7116,7 @@ export interface GisViewInstance {
 	 * 取消选中：写法与 selectFeatures 完全一样（节点 / 通道 / 线路，一批可以混着写），
 	 * 把这些从当前选中集里去掉，其余选中原样留着 —— `deselect('p-1')` 取消一个节点、
 	 * `deselect({ type: 'channel', channelId: 'channel-a' })` 取消整条通道的回线。
-	 * 一个目标都不给（不传 / 传 null）等于取消全部（与 select(null) 同一件事），
+	 * 一个目标都不给（不传 / 传 null）等于取消全部（与 selectFeatures(null) 同一件事），
 	 * 传空数组是「没有目标」，什么都不做；认不出来的条目跳过
 	 */
 	deselect(refs?: GisViewSelectionRefs): GisViewInstance
@@ -6619,7 +7133,7 @@ export interface GisViewInstance {
 	 * 当前画布上选中的数据（一次取全）：ids / count 与各类型条数（通道回线按通道算一个）、
 	 * 要素本身 points / lines / channels 三个数组、下标清单 pointIndexes / lineIndexes、
 	 * items（与 getSelections() 同一份）与世界包围盒 bounds（空选中时 null）。
-	 * 单击、Ctrl 多选、框选与接口选中（select / selectFeatures / selectInBox）都是同一份 state，不挑选中来源；
+	 * 单击、Ctrl 多选、框选与接口选中（selectFeatures / selectInBox）都是同一份 state，不挑选中来源；
 	 * bounds 走一次 getElementBounds（十万级选中下约 5 ms），只想问「选了哪几个」用 getSelections() 更省
 	 */
 	getSelectionData(): GisViewSelectionData
@@ -6689,10 +7203,6 @@ export interface GisViewInstance {
 	 * 可以改、也可以 cancel()），组件随后把数据并起来；false 让拖动的节点与跟随它的线路回原位（两站都能取消）
 	 */
 	resolvePointMerge(confirmed?: boolean, options?: GisViewPointMergeConfirmOptions): GisViewPointMergePayload | null
-	/** 确认待确认的合并（resolvePointMerge(true) 的别名）：可指定保留来源 / 目标并改写最终节点 */
-	confirmPointMerge(options?: GisViewPointMergeConfirmOptions): GisViewPointMergePayload | null
-	/** 取消待确认的合并（resolvePointMerge(false) 的别名）：拖动的节点回原位，数据不动 */
-	cancelPointMerge(): GisViewPointMergePayload | null
 	/** 合并落地之后收掉引擎里的合并状态（mergePoints 已经调过，自己接界面时用得到） */
 	commitPointMerge(): boolean
 	/** 合并并不了：把拖动的节点还原回原位并收掉状态（silent 为 true 时不补发 cancel 载荷） */
@@ -6814,6 +7324,8 @@ export interface GisViewInstance {
 	beginAddChannel(options?: GisViewChannelDraftOptions): GisViewInstance
 	/** 当前新增通道草稿：两个节点的信息与可选方案，没有草稿时为 null */
 	getAddChannelDraft(): GisViewChannelDraftPayload | null
+	/** 改当前草稿的预览样式（字段级合并，传 null 回到全局 channelDraftStyle）；没有草稿时什么也不做 */
+	updateAddChannelStyle(patch?: GisViewChannelDraftStyle | null): GisViewInstance
 	/** 开下一段草稿：连续模式落地时内部自动调用，也可以手动调（没有草稿就按 options 重新进来） */
 	continueAddChannel(options?: GisViewChannelDraftOptions): GisViewInstance
 	/** 取消新增通道（草稿期间按 Esc 等价；会补一条 phase: 'cancel'） */
@@ -6902,7 +7414,7 @@ export interface GisViewInstance {
 	 * （id / index 之外的字段就是这一条的补丁），或者 `patchPoints(['a', 'b'], { status: 1 })`
 	 * 把同一份补丁盖到一批节点上。认不出来的记进 skipped，不影响其余条目；
 	 * 返回 `{ ok, indexes, items, count, skipped }`，只记一条历史、只发一条 updatePoints 数据变更。
-	 * 与 updatePoints(points) 的分工：那一条是整份替换节点数据，这里只动点到的这几条
+	 * 与 `updateData({ points })` 的分工：那一条是整份替换节点数据，这里只动点到的这几条
 	 */
 	patchPoints(entries: GisViewUpdateItemEntry<GisViewPoint> | Array<GisViewUpdateItemEntry<GisViewPoint>>, patch?: Partial<GisViewPoint>): GisViewUpdateItemsOutcome<GisViewPoint>
 	/**
@@ -6912,11 +7424,11 @@ export interface GisViewInstance {
 	 */
 	patchLines(entries: GisViewUpdateItemEntry<GisViewLine> | Array<GisViewUpdateItemEntry<GisViewLine>>, patch?: Partial<GisViewLine>): GisViewUpdateItemsOutcome<GisViewLine>
 	/**
-	 * 改某个通道的数据（分组、宽度、端点等）并重渲染（与整份换声明的 updateChannels 一对）：
+	 * 改某个通道的数据（分组、宽度、端点等）并重渲染（与整份换声明的 `updateData({ channels })` 一对）：
 	 * 成员表没变时只把成员回线换成新几何，成员表换了（改 lineIds）整份重解析。
 	 * 补丁里的 lineIds 是通道成员的整表 —— 增删线路就是改它：写回声明前与 groups 调和
 	 * （不在表里的成员从各组剔掉、空组去掉，表里没落进组的成员补进第一组，组剔完回「整条通道一组」）；
-	 * 建视图 / updateChannels / updateOptions / updateData / importData 这些整份提交的入口逐条同一份口径；
+	 * 建视图 / updateOptions / updateData / importData 这些整份提交的入口逐条同一份口径；
 	 * 补丁里写 groups / lineIds 时写完把引擎那边的最终声明（分组 id、拐点路径）写回数据副本、
 	 * 成员表对齐到各组（拆分 / 挪组之后 lineIds 仍覆盖得上），
 	 * 并补一条 channelGroups 变更（与 splitChannelGroups / mergeChannelGroups 同一份口径），
@@ -6936,24 +7448,10 @@ export interface GisViewInstance {
 	 * 不属于这条通道的条目跳过并报一句 warning（同一个条目只提醒一次）
 	 */
 	updateChannel(id: string | number, patch: Partial<GisViewChannel>, linePatches?: GisViewChannelLinePatch | GisViewChannelLinePatch[], lineIds?: string | number | Array<string | number>): GisViewInstance
-	/**
-	 * 逐要素的细粒度改法：一个方法只改一样东西，改完就走 updatePoint / updateLine / updateChannel
-	 * 的定向更新那条路（只重排受影响的一小片、只发一条数据变更、只落一步历史）。
-	 * 要素没找到时不抛错：发一条 warning（同一个 id 只提醒一次）并原样返回，链式调用不断。
-	 */
-	/** 只改一个节点的屏幕大小（CSS 像素，再乘 pointSizeScale 与缩放档位） */
-	setPointSize(id: string | number, size: number): GisViewInstance
-	/** 只换一个节点的图标（内置形状 / 图片 / 自定义 SVG）：传 null 清掉逐点符号，回落到规则与 pointStyle */
-	setPointSymbol(id: string | number, symbol: GisViewSymbolInput | null): GisViewInstance
-	/** 只改一个节点的填充色（悬停 / 选中样式与热力图仍然压过它） */
-	setPointColor(id: string | number, color: string): GisViewInstance
+	/** 逐要素的复合改法：同时处理多种字段、通道分组或成员回线时用这些入口；单项字段直接用 updatePoint / updateLine / updateChannel */
 	/** 挪一个节点：`movePoint('n1', { x, y })` / `movePoint('n1', [x, y])` / `movePoint('n1', x, y)` 都认，绑定线路与锚定通道跟着重排 */
 	movePoint(id: string | number, coordinate: GisViewCoordinate): GisViewInstance
 	movePoint(id: string | number, x: number, y: number): GisViewInstance
-	/** 只改一条线路的线宽（CSS 像素，再乘 lineWidthScale） */
-	setLineWidth(id: string | number, width: number): GisViewInstance
-	/** 只改一条线路的颜色 */
-	setLineColor(id: string | number, color: string): GisViewInstance
 	/** 整份换一条线路的拐点：只写中间拐点、不含首尾两端（单个坐标 = 只留一个拐点，空数组 = 拉直），两端按节点 / start / end 补齐；通道里的回线改的是它所在分组的骨架 */
 	setLineWaypoints(id: string | number, coordinates: GisViewCoordinate | GisViewCoordinate[]): GisViewInstance
 	/** 一条线路上挂着的装饰（图片 / SVG 标记）清单：要素没找到时给空数组，给的是副本 */
@@ -6966,20 +7464,32 @@ export interface GisViewInstance {
 	updateLineDecoration(id: string | number, decorationIndex: number, patch: Partial<GisViewLineDecoration>): GisViewLineDecoration | null
 	/** 摘掉一条线路上的某一个装饰（剩下的保持原顺序）：返回被摘掉的那一条，没找到返回 null */
 	removeLineDecoration(id: string | number, decorationIndex: number): GisViewLineDecoration | null
-	/**
-	 * 只改一条通道的宽度（世界单位；tangent 模式下是最外侧两条回线中心的间距）。
-	 * 通道默认按两端节点尺寸取宽（nodeWidth 系数），那种模式下这一项只在两端没挂节点时生效，
-	 * 「调了没反应」先 setChannelNodeWidth(id, 0) 关掉自动取宽
-	 */
-	setChannelWidth(id: string | number, width: number): GisViewInstance
-	/** 只改一条通道「按两端节点尺寸取宽」的系数：1 = 回线铺满节点（缺省）、0 = 关掉自动取宽改用通道自己的 width */
-	setChannelNodeWidth(id: string | number, nodeWidth: number): GisViewInstance
-	/** 只改一条通道两端的内收（占通道宽度，负数外收；传 null 回默认「按线宽收」），只影响 offsetMode 为 inset 的排列 */
-	setChannelInset(id: string | number, inset: number | null): GisViewInstance
-	/** 只改一条通道两端切点往节点里的内收（CSS 像素）：正数内收、负数外收、0 = 切点落在节点边上、null = 按回线线宽收 */
-	setChannelTangentInset(id: string | number, tangentInset: number | null): GisViewInstance
-	/** 只改一条通道的名称：悬停提示 / 标签模板的 `{name}`、搜索与自建面板都取它（传 null 摘掉名称） */
-	setChannelName(id: string | number, name: string | number | null): GisViewInstance
+	/** 一个节点上挂着的装饰清单：节点没找到时给空数组，给的是副本 */
+	getPointDecorations(id: string | number): GisViewPointDecoration[]
+	/** 整份换一个节点的装饰清单（空数组 = 全摘掉），写法与 points[].decorations 一致 */
+	setPointDecorations(id: string | number, decorations: GisViewPointDecoration[]): GisViewInstance
+	/** 给一个节点加一个装饰（追加在末尾）：返回加进去的那一条，节点没找到 / 写法不对时返回 null */
+	addPointDecoration(id: string | number, decoration: GisViewPointDecoration): GisViewPointDecoration | null
+	/** 改一个节点上的某一个装饰（按 decorations 的顺序数，只合并这一条的字段）：返回改完的那一条，没找到返回 null */
+	updatePointDecoration(id: string | number, decorationIndex: number, patch: Partial<GisViewPointDecoration>): GisViewPointDecoration | null
+	/** 摘掉一个节点上的某一个装饰（剩下的保持原顺序）：返回被摘掉的那一条，没找到返回 null */
+	removePointDecoration(id: string | number, decorationIndex: number): GisViewPointDecoration | null
+	/**
+	 * 动态装饰器模式：`target` 决定命中线路 / 节点 / 两类同时；开启后鼠标移到目标附近出现临时图标，
+	 * 移出目标立即消失；左键松开仍命中才发 `decorationDraft` 的 ready（空白处 / 不允许的目标不发）。
+	 * 临时图标不写数据：确认调 `commitDecorationDraft`（整批一次 dataChange + 一条历史），取消调 `cancelDecorationDraft`。
+	 * 线路：`parallel` 决定是否跟着切向转，`scope` 取 'line' / 'group' / 'channel' 决定挂到哪些线路。
+	 * 节点：`placement` 取 offset / fixed / pointer，`connector` 决定是否从节点中心画连接线。
+	 */
+	beginDecorationDraft(options?: GisViewDecorationDraftOptions): GisViewDecorationDraftPayload | null
+	/** 当前草稿读数（与 onDecorationDraft 同一份；没有草稿时 null） */
+	getDecorationDraft(): GisViewDecorationDraftPayload | null
+	/** 改草稿的图标 / 大小 / 方向 / 作用域：命中中的预览与后续提交都用新值 */
+	updateDecorationDraft(patch?: Partial<GisViewDecorationDraftOptions>): GisViewDecorationDraftPayload | null
+	/** 把当前假装饰转成真实数据：逐条追加 decorations，整批一次 dataChange、一条历史 */
+	commitDecorationDraft(overrides?: Partial<GisViewDecorationDraftOptions> & { position?: number }): GisViewDecorationCommitResult
+	/** 取消当前假装饰（Esc 等价）：只清预览并发 cancel，数据一个字节都不动 */
+	cancelDecorationDraft(options?: { originalEvent?: Event | null }): GisViewDecorationDraftPayload | null
 	/** 只改一条通道的回线线宽：成员回线与通道声明一起改（一次 batch，只发一条数据变更、只落一步历史） */
 	setChannelLineWidth(id: string | number, lineWidth: number): GisViewInstance
 	/** 整份换一条通道的逐回线颜色：成员回线与通道声明一起改，颜色不够时按顺序循环取，只给一个就整条通道一个色 */
@@ -6991,7 +7501,6 @@ export interface GisViewInstance {
 	 * 完整格式 `{ points, lines, cascade, worker }`；只筛节点时可以简写成节点条件本身。
 	 */
 	setFilter(filter: GisViewFilterInput | null): GisViewInstance
-	clearFilter(): GisViewInstance
 	/** 当前筛选条件（简写已经归一成 `{ points: 条件 }`），没设过返回 null */
 	getFilter(): GisViewFilter | null
 	/** 最近一次筛选结果：Worker 计算时在结果回来之后才会有值 */
@@ -7001,7 +7510,7 @@ export interface GisViewInstance {
 	/**
 	 * 相对上一次对账，位置变过的节点（拖动 / updatePoint / patchPoints / 撤销都算）：按 id 去重，
 	 * 返回 `{ index, id, x, y, item }` 的数组。被删掉的节点不在返回里（账本顺手清掉），
-	 * 整份换数据（updateData / updatePoints / updateOptions 里换 points）之后以新数据为基准。
+	 * 整份换数据（updateData / updateOptions 里换 points）之后以新数据为基准。
 	 */
 	getMovedPoints(): GisViewMovedPoint[]
 	/**
@@ -7067,14 +7576,12 @@ export interface GisViewInstance {
 	nearestLineAt(x: number, y: number, options?: GisViewNearestLineOptions): GisViewNearestLine | null
 	/**
 	 * 拖拽落点预览：拖拽期间就把「松手之后会长成什么」按规则画到地图上，返回解析后的读数
-	 * （图标尺寸 / 颜色 / 符号、线宽…）；传 null 或调 clearDropPreview() 清掉。
+	 * （图标尺寸 / 颜色 / 符号、线宽…）；传 null 清掉。
 	 * 预览与落地走同一条样式链、同一个符号 store，因此读数里的 size 与落地后 getPointStyle() 一个是同一个数
 	 */
 	setDropPreview(preview: GisViewDropPreviewInput | null): GisViewDropPreview | null
 	/** 当前落点预览的读数（没有预览时 null） */
 	getDropPreview(): GisViewDropPreview | null
-	/** 清掉落点预览：与 setDropPreview(null) 同一条路 */
-	clearDropPreview(): GisViewInstance
 	/* 事件订阅 / 功能开关 / 历史：自建界面直接接的三个入口 */
 	/**
 	 * 订阅事件（与 options 里的回调同一条，同一个事件可以挂多条）：返回取消订阅的函数。
@@ -7175,6 +7682,8 @@ export interface GisViewEngineOptions {
 	channelGroupMaxLines?: number
 	/** 新增通道草稿线的样式（跟随光标的那条预览线） */
 	channelDraftStyle?: GisViewChannelDraftStyle
+	/** WebGL 自定义层：与 GisViewOptions.webglLayers 同一份写法 */
+	webglLayers?: GisViewWebGLLayer[]
 	background?: GisViewBackground
 	pointStyle?: GisViewPointStyle
 	lineStyle?: GisViewLineStyle
@@ -7272,7 +7781,7 @@ export interface GisViewEngineOptions {
 	shortcuts?: GisViewShortcuts
 	/** 复制节点的配置（**缺省关**：写了才算开）：开关、落点偏移、id 生成与数据定制 */
 	copy?: GisViewCopyOptions
-	/** 合并节点的配置（**缺省关**：写了才算开）：开关、碰撞容差、确认方式与数据合并规则 */
+	/** 合并节点的配置（**缺省关**：写了才算开）：开关、触发时机、像素容差、确认方式与数据合并规则 */
 	merge?: GisViewMergeOptions
 	/** 是否允许编辑拐点，**缺省关** */
 	waypointEditable?: boolean
@@ -7316,6 +7825,8 @@ export interface GisViewEngineOptions {
 	onChannelDraft?: (payload: GisViewChannelDraftPayload) => void
 	/** 草稿里每点一次发一条：step 1 拿到起点、step 2 拿到终点（线路结束） */
 	onChannelDraftClick?: (payload: GisViewChannelDraftPayload) => void
+	/** 动态装饰器草稿：鼠标在线路上跟随 / 移出 / 松手 ready，以及 update / commit / cancel */
+	onDecorationDraft?: (payload: GisViewDecorationDraftPayload) => void
 	/** 分组变化：拆分 / 合并 / 挪线 / 新建组 / 整份声明换（updateChannel） */
 	onChannelGroupChange?: (payload: GisViewChannelGroupChangePayload) => void
 	onStats?: (stats: GisViewEngineStats) => void
@@ -7370,6 +7881,8 @@ export interface GisViewEngine {
 	getParallelGroups(): GisViewParallelGroup[]
 	/** 通道运行时状态：骨架、回线偏移与每条回线的折线 */
 	getChannels(): GisViewChannelInfo[]
+	/** 单条通道运行时状态：只复制这一组；channelId 找不到时可按 channels 下标兜底 */
+	getChannel(channelId?: string | number | null, channelIndex?: number): GisViewChannelInfo | null
 	/** 通道成员表：成员回线下标与各自的横向偏移，不复制几何（自建覆盖层按通道分流绘制用它） */
 	getChannelMembers(): GisViewChannelMembers[]
 	/** 通道分组现状：不传 channelId 返回所有分组 */
@@ -7413,6 +7926,8 @@ export interface GisViewEngine {
 		chain?: boolean
 		kind?: 'channel' | 'line'
 		circuits?: number
+		/** 换这一段草稿的预览样式（字段级合并；null 回到全局 channelDraftStyle，不传就沿用） */
+		channelDraftStyle?: GisViewChannelDraftStyle | null
 		/** 换一份逐条回线的属性（不传就沿用这一段草稿原来的） */
 		linePropsByMember?: Array<Partial<GisViewLine> | undefined>
 		/** 换这一段草稿的交接模式（不传就沿用） */
@@ -7425,6 +7940,12 @@ export interface GisViewEngine {
 	cancelChannelDraft(options?: { silent?: boolean }): GisViewChannelDraftPayload | null
 	/** 静默收掉草稿：提交之后调用，不发取消事件 */
 	clearChannelDraft(): void
+	/** 动态装饰器草稿：开启 / 改选项 / 取读数 / 交出当前结果（不写数据）/ 取消 */
+	beginDecorationDraft(options?: GisViewDecorationDraftOptions): GisViewDecorationDraftPayload | null
+	getDecorationDraft(): GisViewDecorationDraftPayload | null
+	updateDecorationDraft(patch?: Partial<GisViewDecorationDraftOptions>): GisViewDecorationDraftPayload | null
+	takeDecorationDraft(overrides?: Partial<GisViewDecorationDraftOptions> & { position?: number }): GisViewDecorationDraftPayload | null
+	cancelDecorationDraft(options?: { originalEvent?: Event | null }): GisViewDecorationDraftPayload | null
 	/** 单个节点的定向更新：只重解析这一个节点，绑定线 / 锚定通道跟着重排；结构变了返回 true（调用方此时看得到整份重排） */
 	updatePoint(index: number, item: GisViewPoint): boolean
 	/** 单条线路的定向更新：只重排这一条；身份 / 绑定变了时整份重排并返回 true */
@@ -7503,7 +8024,7 @@ export interface GisViewEngine {
 	 */
 	snapshotScene(options?: GisViewSceneSnapshotOptions): GisViewSceneSnapshot
 	getStats(): GisViewEngineStats
-	/** 换动画效果的整体配置（与组件实例的 setEffects 同一条路） */
+	/** 换动画效果的整体配置（与组件实例的 updateOptions({ effects }) 同一条路） */
 	setEffects(effects: GisViewEffectsInput): void
 	/** 当前生效的动画效果配置（归一化之后的读数） */
 	getEffects(): GisViewEffectsReadout
@@ -7747,9 +8268,6 @@ export declare const createGisEventBus: (host?: GisViewEventBusHost) => GisViewE
 /** 全部可订阅事件名（顺序与组件一致，末尾的 `'*'` 表示「全部事件」） */
 export declare const EVENT_NAMES: GisViewEventNameInput[]
 
-/** 把任意条件输入编成一个判定函数：给不经过视图的批量过滤复用同一套条件语言 */
-export declare const createConditionMatcher: (input: GisViewConditionInput) => (item: unknown, index?: number) => boolean
-
 /** 筛选完整格式的保留键：顶层出现其中之一就不再按「只筛节点」的简写解释 */
 export declare const FILTER_FORM_KEYS: string[]
 
@@ -7847,6 +8365,23 @@ export declare const normalizeDocument: (input: unknown, options?: GisViewNormal
 /** 文档里各列有多少条（拐点 = 线路 path 的中间顶点 + 各分组 path） */
 export declare const documentCounts: (document: GisViewDocument | null | undefined) => GisViewDocumentCounts
 
+/* ---------- 自定义导出格式（export-formats.js） ---------- */
+
+/** 注册一个同步导出器；内置名（含大小写变体）、空名或非函数返回 false，同一个自定义名重复注册以后一次为准 */
+export declare const registerExportFormat: <Result = unknown>(name: string, adapter: GisViewExportFormatAdapter<Result>) => boolean
+/**
+ * 带作用域地定义自定义导出格式：注册成功返回清理函数，适合在插件 / 组件挂载时注册、卸载时注销。
+ * 清理函数只在当前注册项仍是自己那次定义时删除（同名重复注册且 adapter 相同也算新的一次，不会误删后来覆盖注册的同名适配器），重复调用返回 false。
+ * 名字为空或撞内置保留格式（含大小写变体）时抛 TypeError。
+ */
+export declare const defineExportFormat: <Result = unknown>(name: string, adapter: GisViewExportFormatAdapter<Result>) => () => boolean
+/** 注销一个自定义导出格式，返回它之前是否注册着；内置格式永远返回 false */
+export declare const unregisterExportFormat: (name: string) => boolean
+/** 这个名字现在能不能直接交给 exportData（内置五档或已注册的自定义格式） */
+export declare const hasExportFormat: (name: string) => boolean
+/** 当前可用的全部导出格式：内置五档在前，自定义按注册顺序跟在后面 */
+export declare const listExportFormats: () => string[]
+
 /* ---------- 渲染后端开关（renderer.js） ---------- */
 
 /** renderer 认的三档写法（与 options.renderer 同一套） */