gis-view-webgl2 0.1.3 → 0.1.4

package/docs/manual/21-/350/257/264/346/230/216/344/270/216/345/270/270/350/247/201/351/227/256/351/242/230.md

@@ -39,6 +39,9 @@
 **数据更新之后画面没变？**
 `updateData`（只换一列时用 `updateData({ points })` / `updateData({ lines })`）会换数据副本；直接改数组里的对象不会触发重画，改单个要素请用 `updatePoint` / `updateLine` / `updateChannel`，或者重新 `updateData` 一次。
 
+**筛选之后，选中的要素会从选中集里消失吗？**
+默认不会。`setFilter` 的 `mode` 缺省是 `'hide'`：原始数据、选中集与 `getSelections()` 都保持原样，被隐藏的选中项在条件放宽 / 清空后恢复高亮，也不会额外发一次 `onSelectChange`。显式写 `mode: 'remove'` 时，不命中的要素会从数据里删掉（被删的选中项也会从选中集移除），只发一条 `filterRemove`，可用历史撤销。搜索同理：`search({ scope: 'group' })` 只返回分组命中，不隐藏其它要素；命中可交给 `focusOn` / `selectFeatures`。
+
 **接口数据还没回来，先 createGisView 还是等回来再建？**
 先建。空实例照样先铺底图 / 网格，第一次 `updateData` 拿到数据时会按 `initialView` 自动落一次位（容器当时是 0×0 也会记成待办、显示出来补上）；相机、筛选、选中、标签与历史都挂在实例上，等接口回来再 `destroy()` 重建会全丢。收 loading 用 `whenDataRendered()`，完整写法与几条注意点在「动态换数据与加载完成」的「从接口拿数据」与「接口列名不一样」两段。
 
@@ -174,17 +177,17 @@
 | 规则与条件 | `GisViewPointRule`、`GisViewLineRule`、`GisViewConditionInput`、`GisViewCondition`、`GisViewConditionOperator`、`createConditionMatcher` |
 | 热力图 | `GisViewHeatmap`、`GisViewHeatmapGlow`、`GisViewHeatmapDensity`、`GisViewHeatmapDensityCore`、`GisViewHeatmapTarget`、`GisViewHeatmapMissing`、`GisViewHeatmapOverride` |
 | 覆盖层 | `GisViewLabelOptions`、`GisViewLineLabelOptions`、`GisViewItemLabel`、`GisViewLabelState`、`GisViewLabelPatch`、`GisViewSetLabelContentOptions`、`GisViewLabelListItem`、`GisViewItemLabelsInfo`、`GisViewRemoveLabelResult`、`GisViewSetLabelStatesResult`、`GisViewLabelChangePayload`、`GisViewLabelDragPayload`、`GisViewLabelClickPayload`、`GisViewLabelPointerPayload`、`GisViewLabelRef`、`GisViewLabelTarget`、`GisViewLabelBatchEntry`、`GisViewLabelRemoveEntry`、`GisViewLabelBatchSkip`、`GisViewAddLabelsResult`、`GisViewUpdateLabelsResult`、`GisViewRemoveLabelsResult`、`GisViewLineDecoration`、`GisViewTooltipOptions`、`GisViewLabelPayload`、`GisViewLineLabelPayload` |
-| 筛选 | `GisViewFilter`、`GisViewFilterResult`、`GisViewFilterCascade`、`GisViewFilterWorkerOptions` |
+| 筛选 | `GisViewFilter`、`GisViewFilterInput`、`GisViewFilterShorthand`、`GisViewFilterResult`、`GisViewFilterCascade`、`GisViewFilterMode`、`GisViewFilterWorkerOptions` |
 | 大数据展示模式 | `GisViewDenseMode`、`GisViewDenseModeOptions`、`GisViewDenseModeInput`、`GisViewDenseState` |
 | 通道 | `GisViewChannelInput`、`GisViewChannelBuildOptions`、`GisViewChannelBuild`、`GisViewChannelInfo`、`GisViewChannelGroupInfo`、`GisViewChannelGroupWaypoints`、`GisViewChannelGroupLineWaypoints`、`GisViewChannelMember`、`GisViewChannelContext`、`GisViewChannelAddPlan`、`GisViewChannelBetween`、`GisViewChannelAddOption`、`GisViewChannelAddInput`、`GisViewChannelAddResult`、`GisViewChannelDraftOptions`、`GisViewChannelDraftPayload`、`GisViewChannelLineMoveTarget`、`GisViewChannelLineMoveResult`、`GisViewRemoveLineResult`、`GisViewRemoveChannelResult`、`GisViewRemoveLinesResult`、`GisViewChannelInView`、`GisViewChannelAction`、`GisViewChannelActionId`、`GisViewChannelDraftStyle`、`GisViewChannelWaypointDragMode`、`createChannels`、`CHANNEL_DEFAULT_COLORS` |
 | 事件载荷 | `GisViewPickResult`、`GisViewPickAtResult`、`GisViewRectQueryResult`、`GisViewSelectionInfo`、`GisViewSelectedItems`、`GisViewSelectPayload`、`GisViewClickPayload`、`GisViewPointerPayload、GisViewCascadeHighlightScope、GisViewCascadeHighlightOptions、GisViewCascadeHighlightInput、GisViewCascadeHighlightEntry、GisViewCascadeHighlightOrigin、GisViewCascadeHighlightInfo`、`GisViewPointerAction`、`GisViewPointerActionType`、`GisViewPointerTarget`、`GisViewPointerModifiers`、`GisViewWaypointActionData`、`GisViewLabelActionData`、`GisViewHoverPayload`、`GisViewCursorPayload`、`GisViewPointDragPayload`、`GisViewDragPointChange`、`GisViewDragLineChange`、`GisViewPointCopyPayload`、`GisViewPointCopyState`、`GisViewPointMergePayload`、`GisViewMergeImpact`、`GisViewMergeResult`、`GisViewMergeFailure`、`GisViewWaypointPayload`、`GisViewWaypointInfo`、`GisViewWaypointKey`、`GisViewParallelGroup`、`GisViewReadyPayload`、`GisViewEngineStats`、`GisViewEngineHeatDensity`、`GisViewDataChangeType`、`GisViewDataChangePayload`、`GisViewSelectChangePayload`、`GisViewShortcutPayload`、`GisViewRenderPayload`、`GisViewAddItemsResult`、`GisViewAddPointResult` |
 | 快捷键与复制 / 合并 / 删除 | `GisViewShortcuts`、`GisViewShortcut`、`GisViewShortcutAction`、`GisViewCopyOptions`、`GisViewCopyContext`、`GisViewCopyStartOptions`、`GisViewPasteOptions`、`GisViewCopyItem`、`GisViewClipboardItem`、`GisViewMergeOptions`、`GisViewMergeContext`、`GisViewPointStyleSnapshot`、`GisViewPointRef`、`GisViewMergeResult`、`GisViewMergeFailure`、`GisViewMergeOutcome`、`GisViewRemovePointsOutcome`、`GisViewRemoveSelectedOutcome`、`GisViewRemoveOptions`、`GisViewRemoveScope`、`GisViewRemovePayload`、`GisViewRemoveResult`、`GisViewRemoveOutcome`、`GisViewRemoveFailure`、`GisViewRemoveAction`、`GisViewRemovePoint`、`GisViewRemoveLine`、`GisViewRemoveWaypoint`、`GisViewRemoveGroup`、`GisViewRemoveChannel`、`GisViewRemoveCounts`、`GisViewChannelSelectMode`、`GisViewUpdateItemsOutcome`、`GisViewUpdateItemEntry` |
 | 相机与视图 | `GisViewCamera`、`GisViewViewport`、`GisViewFocusOptions`、`GisViewFocusTarget`、`GisViewExportImageOptions`、`GisViewExportSelectionOptions`、`GisViewExportSelectionResult` |
 | 导出数据 | `GisViewExportScope`、`GisViewExportPart`、`GisViewExportDataOptions`、`GisViewExportDataResult`、`GisViewFeatureRef`、`GisViewExportFilterOptions`、`GisViewExportMeta`、`GisViewExportedLabel`、`GisViewStationRecord`、`GisViewPointRecord`、`GisViewLineRecord`、`GisViewChannelRecord`、`GisViewExportFormat`、`GisViewBuiltinExportFormat`、`GisViewExportFormatContext`、`GisViewExportFormatAdapter` |
-| 开关 / 历史 / 事件 | `GisViewFeatureName`、`GisViewFeatures`、`GisViewFeatureState`、`GisViewFeaturePreset`、`GisViewFeaturesInput`、`FEATURE_NAMES`、`FEATURE_PRESETS`、`FEATURE_PRESET_NAMES`、`FEATURE_EDIT_NAMES`、`featureDefault`、`normalizeFeatures`、`featureOn`、`hasForcedFeatures`、`GisViewHistoryOptions`、`GisViewHistoryState`、`GisViewHistoryEntry`、`GisViewHistoryRecord`、`GisViewHistoryOp`、`GisViewHistoryOpEntry`、`GisViewHistoryRecorder`、`GisViewHistoryHost`、`GisViewHistoryPayload`、`GisViewHistoryStepResult`、`GisViewHistoryAction`、`GisViewHistoryCollection`、`createGisHistory`、`normalizeHistoryOptions`、`applyHistoryOps`、`DEFAULT_HISTORY_LIMIT`、`HISTORY_COLLECTIONS`、`GisViewEventMap`、`GisViewEventName`、`GisViewEventNameInput`、`GisViewEventWildcard`、`GisViewEventListener`、`GisViewAnyEventListener`、`GisViewEventBus`、`GisViewEventBusHost`、`createGisEventBus`、`EVENT_NAMES` |
+| 开关 / 历史 / 事件 | `GisViewFeatureName`、`GisViewFeatures`、`GisViewFeatureState`、`GisViewFeaturePreset`、`GisViewFeaturesInput`、`GisViewSelectTrigger`、`FEATURE_NAMES`、`FEATURE_PRESETS`、`FEATURE_PRESET_NAMES`、`FEATURE_EDIT_NAMES`、`featureDefault`、`normalizeFeatures`、`featureOn`、`hasForcedFeatures`、`GisViewHistoryOptions`、`GisViewHistoryState`、`GisViewHistoryEntry`、`GisViewHistoryRecord`、`GisViewHistoryOp`、`GisViewHistoryOpEntry`、`GisViewHistoryRecorder`、`GisViewHistoryHost`、`GisViewHistoryPayload`、`GisViewHistoryStepResult`、`GisViewHistoryAction`、`GisViewHistoryCollection`、`createGisHistory`、`normalizeHistoryOptions`、`applyHistoryOps`、`DEFAULT_HISTORY_LIMIT`、`HISTORY_COLLECTIONS`、`GisViewEventMap`、`GisViewEventName`、`GisViewEventNameInput`、`GisViewEventWildcard`、`GisViewEventListener`、`GisViewAnyEventListener`、`GisViewEventBus`、`GisViewEventBusHost`、`createGisEventBus`、`EVENT_NAMES` |
 | 动画效果与预热 | `GisViewLineEffect`、`GisViewLineEffectInput`、`GisViewPointEffect`、`GisViewPointEffectInput`、`GisViewEffectsOptions`、`GisViewEffectsInput`、`GisViewEffectsReadout`、`GisViewLineEffectReadout`、`GisViewPointEffectReadout`、`GisViewPrebakeOptions`、`GisViewPrebakeCombo`、`GisViewPrebakeReadout`、`GisViewSymbolCombos`、`PREBAKE_COMBO_KEYS`、`LINE_EFFECT_DEFAULTS`、`LINE_EFFECT_KEYS`、`POINT_EFFECT_DEFAULTS`、`POINT_EFFECT_KEYS`、`EFFECT_OPTION_KEYS`、`PREBAKE_OPTION_KEYS`、`normalizeLineEffect`、`normalizePointEffect`、`normalizeEffectsOptions`、`normalizePrebakeCombo`、`normalizePrebakeOptions`、`isEffectConfig`、`isEffectsExplicitlyOff`、`wrapPhase`、`phaseSeed`、`polylineLength`、`samplePolyline`、`lineEffectDistance`、`pointEffectPhase`、`sameLineEffect`、`samePointEffect` |
 | 坐标与映射 | `GisViewGeoProjection`、`GisViewGeoMapper`、`GisViewGeoMapperOptions`、`GisViewPointerState`、`GisViewResolvedGeoJson`、`createGeoProjection`、`createGeoMapper` |
-| 搜索 | `GisViewSearchOptions`、`GisViewSearchScope`、`GisViewSearchHit`、`GisViewSearchResult`、`GisViewVisiblePoint` |
+| 搜索 | `GisViewSearchOptions`、`GisViewSearchScope`、`GisViewSearchScopeInput`、`GisViewSearchHit`、`GisViewSearchGroupItem`、`GisViewSearchResult`、`GisViewVisiblePoint` |
 | 背景 | `GisViewBackground`、`GisViewBackgroundImage`、`GisViewGeoJsonStyle`、`GeoJsonInput`、`GeoJsonFeatureCollection`、`GeoJsonFeature`、`GeoJsonGeometry`、`GeoJsonPosition` |
 | 鹰眼图 | `GisViewMinimapOptions`、`GisViewMinimapExtent`、`GisViewMinimapPointStyle`、`GisViewMinimapLineStyle`、`GisViewMinimapBoxStyle`、`GisViewMinimapPointRule`、`GisViewMinimapLineRule`、`GisViewMinimapDrawData`、`GisViewMinimapDrawInfo`、`GisViewMinimapLayer`、`GisViewMinimapLayerPlacement`、`GisViewMinimapLayerStage`、`GisViewMinimapInteractionType`、`GisViewMinimapInteractionInfo` |
 

package/docs/steps/README.md

@@ -16,11 +16,11 @@ npm run dev            # 或 npx vite
 控制台里 `__gisSteps.view` 就是当前这一步的视图，`__gisSteps.DATA` 是那份园区数据，可以随手调 API。
 地址栏里带步骤号（`index.html#7`）可以直接打开某一步，也能收藏 / 分享。
 
-自测页就在同一个目录下（`selftest.html` / `selftest-demo.html` / `selftest-demos.html` / `selftest-labels.html` / `selftest-select.html` / `selftest-actions.html` / `selftest-scale.html` / `selftest-perf.html` / `selftest-features.html` / `selftest-full.html` / `selftest-effects.html` / `selftest-data.html` / `selftest-decoration.html` / `selftest-docs.html`）：打开就跑，标题报 `PASS` / `FAIL`，页面上的清单是逐条断言。**无头环境下 `requestAnimationFrame` 基本不推进**，动画类断言要用真时间（CDP 或直接开浏览器）跑 —— `selftest-effects.html` 因此自己装了一个「帧泵」（把 `requestAnimationFrame` 收进 Map、手动按帧推进），涟漪与动点的断言才测得动。另有 docs/index.html（文档中心：把仓库里的 markdown 读成 HTML）、docs/api/index.html（API 速查：253 个实例成员逐个一张卡，参数 / 返回 / 说明 / 示例与复制，搜索 + `#成员名` 深链、左侧分组跟随与深浅主题）、docs/guide/sample-document.html（sample-document.json 的交互图解）与 docs/steps/selftest-docs.html（上面这三个页面的自测：清单 / 渲染 / 点选标注一页跑完）。
+自测页就在同一个目录下（`selftest.html` / `selftest-demo.html` / `selftest-demos.html` / `selftest-labels.html` / `selftest-select.html` / `selftest-actions.html` / `selftest-scale.html` / `selftest-perf.html` / `selftest-features.html` / `selftest-full.html` / `selftest-effects.html` / `selftest-data.html` / `selftest-decoration.html` / `selftest-docs.html`）：打开就跑，标题报 `PASS` / `FAIL`，页面上的清单是逐条断言。**无头环境下 `requestAnimationFrame` 基本不推进**，动画类断言要用真时间（CDP 或直接开浏览器）跑 —— `selftest-effects.html` 因此自己装了一个「帧泵」（把 `requestAnimationFrame` 收进 Map、手动按帧推进），涟漪与动点的断言才测得动。另有 docs/index.html（文档中心：把仓库里的 markdown 读成 HTML）、docs/api/index.html（API 速查：256 个实例成员逐个一张卡，参数 / 返回 / 说明 / 示例与复制，搜索 + `#成员名` 深链、左侧分组跟随与深浅主题）、docs/guide/sample-document.html（sample-document.json 的交互图解）与 docs/steps/selftest-docs.html（上面这三个页面的自测：清单 / 渲染 / 点选标注一页跑完）。
 
 ## 怎么查全部属性与方法
 
-组件的完整 API 是同一份清单的五个去处（当前：实例成员 **253** 个 = 250 个方法 + `el` / `canvas` / `gl` 三个属性，`options` **95** 个键，数据字段 **249** 个）：
+组件的完整 API 是同一份清单的五个去处（当前：实例成员 **256** 个 = 253 个方法 + `el` / `canvas` / `gl` 三个属性，`options` **96** 个键，数据字段 **250** 个）：
 
 - **手册里查**：`docs/manual/` 把整本手册拆成 21 章（索引页 `docs/GisView.md` 有目录与按任务的快速跳转）—— 找方法先看 [`16 实例方法总表`](../manual/16-实例方法总表.md)、要把每个成员逐个列全（参数写「名字: 类型 = 默认值」、返回值只写类型）看 [`17 参数速查`](../manual/17-参数速查.md)、要能直接复制的调用看 [`18 逐方法示例`](../manual/18-逐方法示例.md)；`options` 表与数据字段表分别在 [`03 配置项（options）`](../manual/03-配置项.md) 与 [`02 坐标与数据`](../manual/02-坐标与数据.md)。同名的接口在 `src/gis-view/types.d.ts`。
 - **页面上查**：`docs/api/index.html`（API 速查）—— 左栏按 16 个分组列出全部成员，带搜索（Ctrl+K）与方法 / 属性 / options 三档开关，当前读到的分组会跟着高亮；右栏每个成员一张卡，参数 / 返回 / 说明之外，示例块直接来自 [`18 逐方法示例`](../manual/18-逐方法示例.md)，带高亮与「复制名字 / 复制代码」，旁边还有「在调试页跑 →」；地址栏带 `#updateLine` 这样的 hash 直接跳到那一条。右上角主题按钮与文档中心共用 `gisDocs.reading`，跟随系统 / 浅色 / 深色三档换页不会各记一套；深链落点还留了 `scroll-margin-top`，不会被吸顶栏盖住。页面数据来自 `docs/demos/api-index.js`（生成物，禁止手改），自测页 `docs/steps/selftest-docs.html` 盯着它别掉队。
@@ -106,21 +106,21 @@ API 名字与前面几步是一一对应的；第 11 步再补两件「数据之
 - `selftest.html`：手写版第 1 ~ 9 步的断言（拾取、草稿的 step 1 / 2、落地、移除、连续新增、平移……）；
 - `selftest-full.html`：真组件上的同一套断言，外加把 `index.html` 的十三个步骤逐个挂载一遍（第 13 步再点一遍画质 / 批量 / 撤销 / 重做 / 功能预设五个按钮）；
   这一轮又补了四条：小图上的 GeoJSON 底图在主视图放大 3 倍前后红色描边像素数不变（容差 20%）、小图放大 6 倍时 `pointZoomScale` 指数 0 / 1 的像素对比（指数 1 至少 4 倍面积、指数 0 不长大，且倍数回到 1 时指数 1 也不再放大）、以及 stub host 上「拖节点没有结束事件、空闲计时器也会把 `hideOnInteract` 收起的标签层放出来」。
-- `selftest-features.html`（662 条）：真组件上的线型 / 线路装饰 / 光标 / 表现型配置断言 —— 把画面用 `exportImage` 读回 2D 画布数像素（实线 > 虚线 > 点线的墨量、`dc_line` 中点装饰的像素差、`showGrid` 只重画一帧），光标则用合成的指针事件与 Ctrl 键读出 `canvas.style.cursor`；装饰那几条还会量「几何变了装饰跟不跟着走」—— 写回新路径、拖绑定的节点、加 / 删拐点之后，装饰的紫色像素质心都要落在新中点上（容差 3px）；另外两条量的是**固定档**：`anchor: 'fixed'` + `at` 先把装饰钉在写死的世界坐标上，再把线从水平拖成斜的，装饰必须留在原坐标、不能跑到新中点。线路标签在单独一张画布上验：默认挂在中点、内容取 `name`，`position: 0` 落到起点，`hideOnInteract` 在缩放期间给整层加 `--hidden`、停手恢复，关掉 `lineLabel` 之后标签消失。装饰缺省 `auto` 的那一串也在这里量：没有拐点时拖端点装饰保持同一个比例（一直挂在中点）、加上拐点之后钉在那一刻的坐标上（改折线也不动）、把拐点删回直线又回到比例跟随、`anchor: 'follow'` 则一直跟到折线的新中点；`parallel` 用一条横条符号验（默认包围盒 26×6，平行之后转成 4×26），方形符号走的是 gl.POINTS 那条路（旋转后外接盒从 24×24 撑成 32×32）。通道里「每条回线各显示自己的标签」也在这里验：没有逐条配置时会被 32px 屏幕小格去重（只显示 1 ~ 2 条），给每条回线写上自己的 `lineLabelPosition` 之后 8 条全都在、位置各不相同，斜线上的标签按线路方向转、朝左的自动翻半圈（rotate = 0）。线路的层序（`zIndex`）也在这里验：画布正中一横一竖两条粗线交叉，默认后写的竖线在上（中心像素蓝），规则里给横线写 `zIndex: 5` 就换成红，`updateLine` 给竖线写 `zIndex: 9` 又换回蓝，写回 0 再回到红。这一轮另外验了插件上下文：`options.plugins` 与 `view.use()` 拿到的第二个参数是同一个冻结对象（`apiVersion === 1`、`view` 指回实例），旧的一参插件写法照常可用。这一轮另补 3 条合并触发时机断言（center 差 10px 不触发、继续拖入目标区域触发并带 trigger、collision 同距离照旧触发）。这一轮再补 1 条：13 个旧快捷方法已从实例删除，`updatePoint` / `updateLine` / `updateChannel` / `updateOptions` / `setFilter` / `setDropPreview` 仍在。对账组另补 8 条：`getChangedChannels({ ignoreGroups })` 忽略分组增删、已有分组拐点仍报、`reasons` 收窄与线路字段 / 路径 / 显隐变化，以及删除通道 / 删除线路 / 无通道场景同步清账。本轮再补 16 条：筛选恢复后通道宽度与回线车道、`focusOn` 显式 `point` / `line` / `channel` / `group` 与统一缩放口径、`selectFeatures` 分组写法、`selectWaypoint` 带选线路，以及 `lineFollowsNode` 的隐藏 / 筛选 / 删除 / 撤销与动态切换。
+- `selftest-features.html`（672 条）：真组件上的线型 / 线路装饰 / 光标 / 表现型配置断言 —— 把画面用 `exportImage` 读回 2D 画布数像素（实线 > 虚线 > 点线的墨量、`dc_line` 中点装饰的像素差、`showGrid` 只重画一帧），光标则用合成的指针事件与 Ctrl 键读出 `canvas.style.cursor`；装饰那几条还会量「几何变了装饰跟不跟着走」—— 写回新路径、拖绑定的节点、加 / 删拐点之后，装饰的紫色像素质心都要落在新中点上（容差 3px）；另外两条量的是**固定档**：`anchor: 'fixed'` + `at` 先把装饰钉在写死的世界坐标上，再把线从水平拖成斜的，装饰必须留在原坐标、不能跑到新中点。线路标签在单独一张画布上验：默认挂在中点、内容取 `name`，`position: 0` 落到起点，`hideOnInteract` 在缩放期间给整层加 `--hidden`、停手恢复，关掉 `lineLabel` 之后标签消失。装饰缺省 `auto` 的那一串也在这里量：没有拐点时拖端点装饰保持同一个比例（一直挂在中点）、加上拐点之后钉在那一刻的坐标上（改折线也不动）、把拐点删回直线又回到比例跟随、`anchor: 'follow'` 则一直跟到折线的新中点；`parallel` 用一条横条符号验（默认包围盒 26×6，平行之后转成 4×26），方形符号走的是 gl.POINTS 那条路（旋转后外接盒从 24×24 撑成 32×32）。通道里「每条回线各显示自己的标签」也在这里验：没有逐条配置时会被 32px 屏幕小格去重（只显示 1 ~ 2 条），给每条回线写上自己的 `lineLabelPosition` 之后 8 条全都在、位置各不相同，斜线上的标签按线路方向转、朝左的自动翻半圈（rotate = 0）。线路的层序（`zIndex`）也在这里验：画布正中一横一竖两条粗线交叉，默认后写的竖线在上（中心像素蓝），规则里给横线写 `zIndex: 5` 就换成红，`updateLine` 给竖线写 `zIndex: 9` 又换回蓝，写回 0 再回到红。这一轮另外验了插件上下文：`options.plugins` 与 `view.use()` 拿到的第二个参数是同一个冻结对象（`apiVersion === 1`、`view` 指回实例），旧的一参插件写法照常可用。这一轮另补 3 条合并触发时机断言（center 差 10px 不触发、继续拖入目标区域触发并带 trigger、collision 同距离照旧触发）。这一轮再补 1 条：13 个旧快捷方法已从实例删除，`updatePoint` / `updateLine` / `updateChannel` / `updateOptions` / `setFilter` / `setDropPreview` 仍在。对账组另补 8 条：`getChangedChannels({ ignoreGroups })` 忽略分组增删、已有分组拐点仍报、`reasons` 收窄与线路字段 / 路径 / 显隐变化，以及删除通道 / 删除线路 / 无通道场景同步清账。本轮再补实例命令的注册 / 同名覆盖 / 异常与销毁断言，并再补 16 条：筛选恢复后通道宽度与回线车道、`focusOn` 显式 `point` / `line` / `channel` / `group` 与统一缩放口径、`selectFeatures` 分组写法、`selectWaypoint` 带选线路，以及 `lineFollowsNode` 的隐藏 / 筛选 / 删除 / 撤销与动态切换。
 - `selftest-decoration.html`（75 条）：动态装饰器草稿专项自测 —— 开启后的 `start` 载荷、默认 14px 触发半径与每条线路不限量、指针在线路上 `hover`（命中线 / 自身 `decoration` / 平行角）、同一位置重复移动不重复发事件、移出目标 `leave`、在线路与空白处 `pointerup` 的 `ready` 差异、按下 / 抬起 `action.type` 都是 `decorationDraft`、单线 / 分组 / 整条通道三档作用域与非通道回退、`maxPerLine` 满额时悬浮与松手都不触发且提交前复核不写数据、`allowedLines` / `allowedChannels` / `allowedGroups` 三种白名单在悬浮与提交两处都拦截、`update` 改图标 / 尺寸 / 方向、`commit` 一次 `batch` 写四条且只发一条 `dataChange`、`cancel` 不改数据、重复 `begin` 替换旧草稿、整份换数据后过期草稿静默清掉。节点侧另有 32 条：`target: 'point'` 命中与只展开一个节点目标、方向 / 距离换算成屏幕偏移、相对偏移 / 固定世界坐标 / 鼠标位置三种位置来源、连接线样式随提交保存、`allowedPoints` 与 `maxPerPoint` 在悬浮 / 提交两处拦截、`both` 等距时节点优先且最近节点被白名单拦住时回退线路、节点与线路的重复 `reject` / `offset` 两种策略、节点装饰 get / update / remove 与整批提交、度转角与连接线进入矢量快照。这一轮另补 8 条节点断言：既有的 2 条「装饰随移动」仍保留；新增 6 条覆盖 `pointer + follow`、`fixed + follow`、`offset + fixed` 三种跨组合的预览与提交结果，确认位置来源和落地关系解耦后分别写成 `offset` 或 `at`。
 - `selftest-demo.html`：demo 级自测 —— 面板上的「定位直流线路」按当前数据集的 `dc_line` 条数走（默认数据集 `new.json` 里现在自带 5 条，点一下直接选中并定位到第一条；一条都没有的数据集才切到样例数据、定位到「直流送电」，中点挂着 `PATH_DC_LINE` 装饰），断言按数据算出来的条数写、不写死数字，读数与选中面板都跟着更新；打开时说明段落默认收起、面板按组折叠，节点标签只给最高电压那一档、线路标签默认整个不显示（面板上勾「显示」再按「显示范围」展开），面板上有 PATH_DC_LINE 的「标记定位」下拉（自动 / 一直跟随 / 写死坐标三档）。「通道回线各自显示」这一档从数据层核对（勾上之后 3669 条回线都带上了自己的 `lineLabelPosition`），再放大三步后勾「与线路平行」，画出来的标签 transform 里要出现 `rotate(...)`。这一轮又补了「数据映射」下拉（raw / lngLat / fit / scale）与「节点 / geojson 比例」滑块：切到 fit 后 320 个站点都要落进 GeoJSON 画出来的范围、读数里给出换算比例；「经纬度 → 屏幕」「屏幕 → 经纬度」两个按钮来回换算一致（屏幕读数保留 1 位小数，允许 0.01° 的回差）；在画布上挪一下鼠标，面板上就要出现屏幕像素与经纬度两行读数。
 - `selftest-perf.html`（162 条）：大数据量与画质档位的性能自测 —— 20000 点 / 8000 线的建场景与整份重排耗时、500 次拾取、逐个改 500 个节点对 `view.batch()`、四档画质与 `'auto'` 的自动升降；前面几轮补过 8 条交互期细线的断言（`getStats()` 给出 `antialias` / `software` / `thinLines` 三个读数；交互期 1px 实线整批走 `gl.LINES` 快路径、停手回到四边形展开；`interactionThinLines: false`、线宽 8px、整批带虚线这三种情况下都不走快路径，改回细实线又走）；上一轮补过 7 条线路标签候选复用的断言（复用态与整层重排逐字一致，改线路内容 / 挪节点 / 相机变化之后缓存都作废）与 1 条连续更新的耗时 DIAG（2 万点 / 1 万线，中位 0.30 ms / 次）；**这一轮再补 3 条标签避让盒的断言**（4 万点 + 4 万条长线放大后连续整层重排：第 2 轮起一次布局都不读、同一轮里没有哪条标签被量第二次）与 1 条量测读数 DIAG（逐轮 1427 / 0 / 0 / 0 / 0 次，旧写法 2662 / 0 … 次、第 1 轮重复量 1235 条；**上一轮把「没有哪条标签被量第二次」从按 DOM 节点去重改成按标签身份（`labelKind` # `labelIndex` # `labelLabel`）去重** —— 标签节点是池化复用的，按节点去重会把「同一格换了条标签」误报成重复量，旧代码实测第 1 轮 1235 条、新代码 0 条；**这一轮再补 3 条线路批次视口裁剪的断言**（20000 点 / 8000 线放大到 `scale: 10`：`lineInstances` 8000 → 27、相机挪回来回到 8000、来回一趟整幅像素差 0 / 241164）与 1 条读数 DIAG。这一轮再补 2 条点视口网格的断言（网格可用时枚举顺序与整份筛出来的下标序列一致、回调返回 `false` 最多只访问一个）。这一轮再补 19 条点聚合断言（归一化、1.2 万点建组与统计、原始数据不变、`visibleOnly` 排除成员、拾取 `type=cluster`、点击语义、`maxZoom` 展开、关闭恢复），页面每段之间让出一帧，边跑边出结果。这一轮另补 7 条热力图缓存断言：`styleKey` / `weightKey` 的语义、只改 `density.opacity` 不重采不重烤、换色带与定向改要素值会重烤。
-- `selftest-scale.html`（115 条：109 PASS + 6 DIAG）：大数据交互这一轮的自测 —— 2000 点 / 2000 线、筛选开着：`batch()` 里改 200 个节点只发 1 条 `onFilter` 与 1 条 `onDataChange`（对照组逐个调用是 200 条）；改字段 / 改坐标 / 改线路之后「增量补写的隐藏集」与「从零建一个同样条件的视图」逐位一致；点挪到被筛掉的坐标上，按 `coordinate` 联动的线路当场隐藏、挪回去又出来；线段网格的步进登记与多层粗格（沿线查得到、线不经过的角落不进候选、跨层只返回一次、2 万条长线密集时小范围查询的候选远少于总条数、整图估计值与总条数同量级）；点 / 线 / 空白的拾取；搜索文本缓存的命中与「改过字段之后按新值搜得到、旧值搜不到」。最底下几条 DIAG 是耗时读数（`Date.now()`），无头浏览器里虚拟时钟不往前走、显示 0.0 ms，带界面的浏览器里才是真实数字。；这一轮又补了 8 条：三万点的发散渲染（超过 2 万点走分批铺开）铺完之后装饰 400 个一条不少、挪一条带装饰的线的端点只动那一条线的装饰且落在新路径中点上、贴图符号进的是贴图批次、选中的节点抬到最上层、整份重排之后装饰与动点不翻倍，以及「节点自己配的涟漪数得清」（这一条顺带抓出了发散渲染期间涟漪补不齐的 bug）。这一轮再补一条 `createPointGrid.estimate` 与 `query` 同口径、带 `stopAfter` 提前封顶的断言（不建候选数组也能判断值不值得走网格）。
+- `selftest-scale.html`（125 条：119 PASS + 6 DIAG）：大数据交互这一轮的自测 —— 2000 点 / 2000 线、筛选开着：`batch()` 里改 200 个节点只发 1 条 `onFilter` 与 1 条 `onDataChange`（对照组逐个调用是 200 条）；改字段 / 改坐标 / 改线路之后「增量补写的隐藏集」与「从零建一个同样条件的视图」逐位一致；点挪到被筛掉的坐标上，按 `coordinate` 联动的线路当场隐藏、挪回去又出来；线段网格的步进登记与多层粗格（沿线查得到、线不经过的角落不进候选、跨层只返回一次、2 万条长线密集时小范围查询的候选远少于总条数、整图估计值与总条数同量级）；点 / 线 / 空白的拾取；搜索文本缓存的命中与「改过字段之后按新值搜得到、旧值搜不到」。最底下几条 DIAG 是耗时读数（`Date.now()`），无头浏览器里虚拟时钟不往前走、显示 0.0 ms，带界面的浏览器里才是真实数字。；这一轮又补了 8 条：三万点的发散渲染（超过 2 万点走分批铺开）铺完之后装饰 400 个一条不少、挪一条带装饰的线的端点只动那一条线的装饰且落在新路径中点上、贴图符号进的是贴图批次、选中的节点抬到最上层、整份重排之后装饰与动点不翻倍，以及「节点自己配的涟漪数得清」（这一条顺带抓出了发散渲染期间涟漪补不齐的 bug）。这一轮再补一条 `createPointGrid.estimate` 与 `query` 同口径、带 `stopAfter` 提前封顶的断言（不建候选数组也能判断值不值得走网格）；本轮又补了删除型筛选的 10 条回归：同步初始删除先于 `ready`、无 id 线路按下标删、级联线路与空通道一起清掉、单条 `filterRemove` / 单次 `onFilter`、历史一步、撤销不再次删除、重做不补发第二条事件、运行时 `setFilter` 与 `cascade: false` 对照，另校验载荷里的 `removedPoints` / `removedLineItems` 与剩余数据。
 - `bench-filter.html`：基准页（不是自测，只会打印读数）—— 20000 点 / 20000 线、`cascade: 'binding'` 的筛选开着（`filterWorker: false`），量「连换 10 次筛选条件」「`batch()` 里改 500 个节点（筛选开着 / 关掉）」「单个 `updatePoint`」「默认全字段 `search` 跑两次」这几档，每档先热身一遍再计时（`Date.now()`）。标题从 `bench running` 变成 `bench done` 表示跑完；别用 `--virtual-time-budget` 打开它 —— 虚拟时钟下同步脚本里的 `Date.now()` 不往前走，量出来全是 0。
 - `bench-scale.html`：百万级基准页（同样只打印读数）—— 点 / 线规模与视口走 URL 参数，`window.__bench.run(options)` 量生成数据、建场景与发散渲染、平移 / 缩放 / 放大 / 拾取、`refresh` / `updatePoint` / `updateOptions`、内存账与销毁回收；另有 `prepare`（只建场景）、`__bench.op(name)`（单步）与 `__bench.micro(count)`（原语微基准）。配 `scripts/bench-scale.mjs` 用（CDP 驱动，`--points=1000000 --gpu --port=93xx`，另有 `--profile` 抓 CPU profile、`--heap` 抓堆快照）；跑全部自测页用 `scripts/run-selftests.mjs`（`node scripts/run-selftests.mjs [页面名…]`，无头 Chrome + 真时间），两个脚本都要先起 dev server。
 - `selftest-labels.html`（165 条）：标签拖动与编辑、HTML 语义、高密度画布、导出分项多选的专项自测 —— 按住标签拖 90 px 之后标签真的挪了那么多、同时画布不平移，`labelDrag` 的 `start` / `move` / `end` 三态与 `offset` / `delta` 对得上，偏移进得了 `getLabelStates()`、再拖动节点时偏移照旧叠在节点位移上，`resetLabel` 之后回到默认锚点；`updateLabel` 改内容 / 字号 / 颜色（`style` 是增量合并，只改字号不动颜色）、`resetLabels` 一次清干净；点一下标签发 `labelClick` 并把这一条交给面板；线路标签的拖动与恢复默认同一条路；导出侧验「选什么导什么」（选场站只出场站、选通道自动带上拐点、不认识的分项记一条提示），`exportData({ scope: 'selection' })` 验场站 + 通道 / 只出线路 / 没选中时的 `ok: false` 三个分支。HTML 专项验全局 / 逐条 `true` / `false`、模板与 `field` / 默认名称转义、`updateLabel` 双向切换、线路标签富文本、点击载荷保留 `html` 与原标记、`getLabels()` 报运行时偏移、只改样式不替换 HTML 子节点、导出 → 回灌保持逐条语义，以及 120 条同内容标签首轮布局读取 ≤ 4 次的缓存断言。高密度专项用 1100 条纯文本验缺省 `auto` 只留一张画布、混入一条 `html: true` 仍保留那一条 DOM、`labelRender: 'dom'` 回退逐条 DOM 并清空画布、切回 `auto` 回收上一轮 div、SVG 导出包含画布标签与缩放只推一次；新增断言还验 1100 条同文案只调用 `measureText` ≤ 2 次、同一任务连续 5 次缩放只重绘 1 ~ 2 次、显式 `canvas` 在优化档遵守 `maxCount: 200`，以及 6 条线路标签在优化档全部进画布且 DOM 为 0。另验 GeoJSON 区域文字同一相机重复刷新 0 次 `style` 写入、只改字号复用同一 DOM 节点、离屏时改样式再回到视野仍能恢复显示、只改锚点位置也会重新投影，以及同一帧 12 次相机变化只做 1 次重投影。设备像素专项把 `devicePixelRatio` 临时设为 1.25，验标签落点与拖动期整层位移都落在物理像素网格上，并确认逐条标签不再各自声明 `will-change`。
 - `selftest-actions.html`：事件判读与只读接口的专项自测 —— 左右键、拖动、框选、拐点与标签的 `action` 三件套（type / target / data）、`button` / `modifiers` / `moved` / `double`、Shift 框选（含没框到东西的空框）与 Ctrl 取反在 `selectChange.action.type` 上的分辨、`pickAt` 的客户端坐标与只读性、`getFeaturesInRect`（含宽高为负的矩形）与 `getChannelsInView`、`addPoints` / `addPoint` / `addLines` / `removeLines` 的返回与 `dataChange` 类型；最后一段把第 12 步 `step-12-events.js` 挂起来跑一遍（判读读数、`probeAt` / `probeRect`、两条走廊）。页面底部流式打印 PASS / FAIL。
-- `selftest-select.html`：选择与框选的专项自测（60 条）—— 点选 / 悬停 / Ctrl 取反 / 多选开关的像素级状态样式与恢复，`select` / `deselect` / 通道写法 / 变更来源的接口断言，以及 SVG 状态贴图的预热与不同尺寸配方；这一轮补了 `selectionKinds: 'all'` 下 `selectInBox` 一次收下节点、独立线路与按 `channelSelectMode` 摊开的通道回线。
-- `selftest-demos.html`：演示外壳与 22 个页签（21 个功能 + 综合，按基础 / 交互 / 样式 / 数据 / 性能 / 综合六组排列）的自测（333 条）—— 逐个用 `?demo=<id>` 打开基础视图、标签交互、标签显示、鹰眼图配置、样式与规则、悬停与提示、通道与数据、编辑与保存、事件与方法、接口能力、批量复制与合并、拖拽落点、可视化连线、动态装饰器、批量新增、搜索与筛选、扩展能力、性能与质量、点聚合、动画效果、扩展图形与综合示例，画布与右栏读数都在、切页签会把 `?demo=` 写回地址栏、切走之后上一个实例被销毁（不留画布）、缺省页签是综合示例、页签总数与注册表一致、顶部六个分组按钮一次只展开一组且组名可见；鹰眼图配置页另验 `layers` 的自定义 `draw` 真被调用、`placement` 切到数据前 / 后时 `drawInfo.stage` 跟着变、框拖动触发 `onInteraction` 并带相机、尺寸切换走 `updateOptions` 重铺画布、DPR 2 下 `maxPixelRatio` 的 1× / 2× 备份尺寸、关掉扩展层与 `zoomMinimapBy` / `setMinimapZoom`；批量复制 / 合并、通道拐点 / 分组两页另有假接口断言（Shift 框选、整份请求体、标准响应包与资源级结果、版本号 / opId、200 / 网络失败 / 500 / 409、原 opId 重试与幂等重放不推进版本、409 rebase、本地回滚）；假后端严格契约另有一组直接断言（请求头与 body 不一致返回 400、baseVersion 非有限数字返回 400、同 opId 换 body 返回 409 `IDEMPOTENCY_CONFLICT` 且版本不前进），通道页还验了自定义格式按钮注册 → 导出 → 注销；扩展能力页另验自定义运算符 / 图元 / `view.use` 插件 / `defineExportFormat` 的注册、切换、卸载与业务 DTO 结构，并验同名重新注册图元当场换画笔；可视化连线页另验初始 `channels` 为空、正交折线拐点、预览箭头、取消不写数据，以及默认提交 / `addLines` / `addChannels` 三种落地；动态装饰器页另验吸附方式只有「跟随 / 固定」、两档下位置都有「相对节点 / 固定位置 / 鼠标位置」三档，固定 + 相对节点只改 `anchor`，固定 / 跟随 + 鼠标位置分别映射为 `placement: pointer` + 对应 `anchor` 且不带 `at`，跟随 + 固定位置仍传 `at`；通道与数据页另验「线路分组」弹框：分组卡片与「场站对标标识」都在，行内「确认移入」只改本地草稿、组件数据不动，取消 / Esc / 遮罩关闭不写数据，「确定分组」只调用一次 `splitChannelGroups` 把整份 groups 一次落地。点聚合页另验配置控件、聚合点击只增聚合计数、`maxZoom` 展开与适应全部后恢复、半径 / 重建 / 关闭统计；接口能力页另验三种级联触发独立开关、通道 / 分组 / 拐点程序化选中、通道 `focusOn`、`lineFollowsNode` 联动，以及样式字段合并、节点 / 线路装饰 CRUD、通道线宽与线路对账、GeoJSON 背景投影、历史 / 复制 / 删除收尾、`once`、WebGL 层清理、注册表注销与初始化 options 读数；页面底部流式打印 PASS / FAIL。这一轮另补 3 条鹰眼图线路层断言：首帧只铺固定范围里的线路、同一份数据补画命中缓存、小图缩放只重铺一次且仍裁剪范围外线路。
+- `selftest-select.html`：选择与框选的专项自测（69 条）—— 点选 / 悬停 / Ctrl 取反 / 多选开关的像素级状态样式与恢复，`select` / `deselect` / 通道写法 / 变更来源的接口断言，以及 SVG 状态贴图的预热与不同尺寸配方；这一轮补了 `selectionKinds: 'all'` 下 `selectInBox` 一次收下节点、独立线路与按 `channelSelectMode` 摊开的通道回线；本轮再补 SVG 导出 `currentStrokeColor` 的描边色还原，以及 `selectTrigger` 默认单击、双击选中、空白双击清空、运行时切回单击与双击 + `multiSelect` 的取反 / 累加 / 取消。
+- `selftest-demos.html`：演示外壳与 22 个页签（21 个功能 + 综合，按基础 / 交互 / 样式 / 数据 / 性能 / 综合六组排列）的自测（337 条）—— 逐个用 `?demo=<id>` 打开基础视图、标签交互、标签显示、鹰眼图配置、样式与规则、悬停与提示、通道与数据、编辑与保存、事件与方法、接口能力、批量复制与合并、拖拽落点、可视化连线、动态装饰器、批量新增、搜索与筛选、扩展能力、性能与质量、点聚合、动画效果、扩展图形与综合示例，画布与右栏读数都在、切页签会把 `?demo=` 写回地址栏、切走之后上一个实例被销毁（不留画布）、缺省页签是综合示例、页签总数与注册表一致、顶部六个分组按钮一次只展开一组且组名可见；鹰眼图配置页另验 `layers` 的自定义 `draw` 真被调用、`placement` 切到数据前 / 后时 `drawInfo.stage` 跟着变、框拖动触发 `onInteraction` 并带相机、尺寸切换走 `updateOptions` 重铺画布、DPR 2 下 `maxPixelRatio` 的 1× / 2× 备份尺寸、关掉扩展层与 `zoomMinimapBy` / `setMinimapZoom`；批量复制 / 合并、通道拐点 / 分组两页另有假接口断言（Shift 框选、整份请求体、标准响应包与资源级结果、版本号 / opId、200 / 网络失败 / 500 / 409、原 opId 重试与幂等重放不推进版本、409 rebase、本地回滚）；假后端严格契约另有一组直接断言（请求头与 body 不一致返回 400、baseVersion 非有限数字返回 400、同 opId 换 body 返回 409 `IDEMPOTENCY_CONFLICT` 且版本不前进），通道页还验了自定义格式按钮注册 → 导出 → 注销；扩展能力页另验自定义运算符 / 图元 / `view.use` 插件 / `defineExportFormat` / 实例命令的注册、执行、同名覆盖、卸载与业务 DTO 结构，并验同名重新注册图元当场换画笔；可视化连线页另验初始 `channels` 为空、正交折线拐点、预览箭头、取消不写数据，以及默认提交 / `addLines` / `addChannels` 三种落地；动态装饰器页另验吸附方式只有「跟随 / 固定」、两档下位置都有「相对节点 / 固定位置 / 鼠标位置」三档，固定 + 相对节点只改 `anchor`，固定 / 跟随 + 鼠标位置分别映射为 `placement: pointer` + 对应 `anchor` 且不带 `at`，跟随 + 固定位置仍传 `at`；通道与数据页另验「线路分组」弹框：分组卡片与「场站对标标识」都在，行内「确认移入」只改本地草稿、组件数据不动，取消 / Esc / 遮罩关闭不写数据，「确定分组」只调用一次 `splitChannelGroups` 把整份 groups 一次落地。点聚合页另验配置控件、聚合点击只增聚合计数、`maxZoom` 展开与适应全部后恢复、半径 / 重建 / 关闭统计；接口能力页另验三种级联触发独立开关、通道 / 分组 / 拐点程序化选中、通道 `focusOn`、`lineFollowsNode` 联动，以及样式字段合并、节点 / 线路装饰 CRUD、通道线宽与线路对账、GeoJSON 背景投影、历史 / 复制 / 删除收尾、`once`、WebGL 层清理、注册表注销与初始化 options 读数；页面底部流式打印 PASS / FAIL。这一轮另补 3 条鹰眼图线路层断言：首帧只铺固定范围里的线路、同一份数据补画命中缓存、小图缩放只重铺一次且仍裁剪范围外线路。
 - `selftest-effects.html`：线路 / 节点动画与贴图预热的专项自测（96 条，页面自带「帧泵」—— 无头环境里 `requestAnimationFrame` 几乎不推进，它把 rAF 收进 Map、手动推帧，动画类断言才测得动）：纯函数组（归一化、三层「关」的语义、按弧长采样、拐点连续、相位打散）、引擎组（铺批次 / 关掉一层 / 恢复 / 逐要素覆盖 / `getLineEffects` 全程贴线）、像素组（画布上真的有一个红点在两帧之间挪了位置）、**涟漪跟手组**（开着动画拖节点：拖动前圆心在节点坐标上、拖动中跟着走且是就地改实例缓冲、松手后整份重建也对齐、再拖回原位跟着回来，另有一条像素级断言量绿圈质心落在新坐标上）、**预热组**（全排列条数、第二次命中缓存、`getSymbolCombos()` 的去重与线路侧那一条、照着它配的一份**零张新画布**、反向一条「没画过的组合会当场烤、画布 +1」）、提醒组（`effects.line` 里写 `show` 被点名）；这一轮另补 4 条动点缓存断言（5000 条普通线 + 2 条动点线：每帧只遍历动画线路，路径换短 / 换长后总长跟着更新）。
 - `selftest-data.html`：标准数据文档与渲染后端开关的自测（103 条）—— `normalizeDocument` 的标准写法与 JSON 安全（无效日期写 `null` 并告警、类实例不静默变成空对象）、整份文档直接当 `createGisView` 入参、`exportData({ format: 'full' })` 导出 → 重建 → 再导出逐字节相同、`importData` 的整份与分列、`renderer` 三档与能力探测、网格顶点缓存窗口，以及自定义导出格式的注册 / 上下文 DTO 映射 / 深拷贝 / 视口导出 / 注销后失效；断言全在接口层，不读像素。
 - `check-sample-fields.mjs`：不是页面、是对账脚本（`node docs/steps/check-sample-fields.mjs`）—— 核对 `sample-document.json` 自己就是标准写法（`normalizeDocument` 后逐字节相同、0 条提醒）、`docs/sample-document字段详解.md` 里的读数与 `documentCounts()` 一致、以及它的「字段索引」与从文件里摘出来的字段路径集合一个不多一个不少（当前 154 个）；改完样本数据跑 `--write` 重写那两段机器块（幂等）。
-- `selftest-docs.html`：三个文档页 + 调试页的自测（130 条）—— 文档中心（`docs/index.html`）的清单 92 份 md（10 个根 + 82 份子文档，含新的 `接口协议.md`；树形侧栏按 `parent` / `groupLabel` 分成 6 组 `details`）、首屏 README 渲染、markdown 渲染器（表格 / 带语言代码块 / 两级列表 / 引用 / 行内代码 / md 链接 / 目录 / 首条摘要卡片 / 首段导语）、元信息里的阅读时长、索引页的子文档链接、换一份子文档、代码块复制按钮、跨文档搜索与深链、跨文档锚点链接（`文件.md#小节` 原地切文档并闪一下）、能直接跑的围栏才有的「在调试页跑」与元信息行的「这一份的调试页（N 段示例）」、390px 窄屏首屏 / 深链 / 横向溢出回归、阅读百分比与「回到顶部」的联动；调试演示页（`docs/playground/index.html`）的一个示例下拉（内置示例 + 「这一份文档」两组 optgroup）、`?doc=` 读文档抽示例、片段标注与来源子栏、顶层 await 运行、`channels` 快照、光标行列、草稿自动保存与恢复、`Ctrl+S` 运行、复制 / 清空输出、状态胶囊；API 速查页（`docs/api/index.html`）的 `__gisApi` 钩子、六张统计卡、253 张成员卡都带签名网格与示例、95 个 options 四列网格、搜索过滤与命中读数、`select(名字)` 高亮、类型开关能单独收起属性、左侧当前分组高亮、深浅主题切换与阅读设置共用；图解页（`docs/guide/sample-document.html`）的 47 条数据列表、点线路 / 分组 / 标签状态的图上标注、`点击时居中` 与 `显示编号` 开关、清空标注；三个页面都跑在 iframe 里，要用 dev server 打开。
+- `selftest-docs.html`：三个文档页 + 调试页的自测（134 条）—— 文档中心（`docs/index.html`）的清单 92 份 md（10 个根 + 82 份子文档，含新的 `接口协议.md`；树形侧栏按 `parent` / `groupLabel` 分成 6 组 `details`）、首屏 README 渲染、markdown 渲染器（表格 / 带语言代码块 / 两级列表 / 引用 / 行内代码 / md 链接 / 目录 / 首条摘要卡片 / 首段导语）、元信息里的阅读时长、索引页的子文档链接、换一份子文档、代码块复制按钮、跨文档搜索与深链、跨文档锚点链接（`文件.md#小节` 原地切文档并闪一下）、能直接跑的围栏才有的「在调试页跑」与元信息行的「这一份的调试页（N 段示例）」、390px 窄屏首屏 / 深链 / 横向溢出回归、阅读百分比与「回到顶部」的联动；调试演示页（`docs/playground/index.html`）的一个示例下拉（内置示例 + 「这一份文档」两组 optgroup）、`?doc=` 读文档抽示例、片段标注与来源子栏、顶层 await 运行、`channels` 快照、光标行列、草稿自动保存与恢复、`Ctrl+S` 运行、复制 / 清空输出、状态胶囊；API 速查页（`docs/api/index.html`）的 `__gisApi` 钩子、六张统计卡、256 张成员卡都带签名网格与示例、96 个 options 四列网格、搜索过滤与命中读数、`select(名字)` 高亮、类型开关能单独收起属性、左侧当前分组高亮与即时跳转、顶栏文档深链、每个分组的手册章节链接、深浅主题切换与阅读设置共用；图解页（`docs/guide/sample-document.html`）的 47 条数据列表、点线路 / 分组 / 标签状态的图上标注、`点击时居中` 与 `显示编号` 开关、清空标注；三个页面都跑在 iframe 里，要用 dev server 打开。
 
 上一轮补上的两组断言：`selftest-features.html` 新增 8 条 —— 3 条验 `channelSelectMode` 在 Ctrl + 点击加点后的高亮范围（`line` / `group` / `channel`），5 条验分组 `channelWaypointDragMode: 'vertex'`（`{ x, y }` 偏移归一化并参与实际路由、同组同序号拐点按世界增量平移、相邻拐点与其它分组不动、只写 `waypointOffsets` 不改公共 `path`、`parallel_groups.group_route` 带刚性偏移）。`selftest-demos.html` 新增 1 条，验通道演示页可切到 `vertex`，且「准备两分组拐点」会拆成两组、每组两个拐点。
 

package/docs/steps/selftest-demos.html

@@ -651,10 +651,16 @@
 						click('search-filter-preset-owner')
 						const ownerReady = await until(() => readout('search-filter-summary').includes('节点 8'), 4000)
 						check('搜索与筛选：fields=[props.owner] 能命中嵌套业务字段', Boolean(ownerReady) && readout('search-filter-meta').includes('truncated=否'), `${readout('search-filter-summary')} / ${readout('search-filter-meta')}`)
-						click('search-filter-preset-channel')
-						const channelReady = await until(() => readout('search-filter-summary').includes('通道 1'), 4000)
-						check('搜索与筛选：scope=channels 只把通道放进命中', Boolean(channelReady) && readout('search-filter-summary').includes('节点 0') && readout('search-filter-summary').includes('线路 0'), readout('search-filter-summary'))
-						click('search-filter-preset-symbol')
+							click('search-filter-preset-channel')
+							const channelReady = await until(() => readout('search-filter-summary').includes('通道 1'), 4000)
+							check('搜索与筛选：scope=channels 只把通道放进命中', Boolean(channelReady) && readout('search-filter-summary').includes('节点 0') && readout('search-filter-summary').includes('线路 0'), readout('search-filter-summary'))
+							click('search-filter-preset-group')
+							const groupReady = await until(() => readout('search-filter-summary').includes('分组 1'), 4000)
+							const groupHit = view.search({ keyword: 'channel-a', scope: 'groups', limit: 10 }).groups[0]
+							view.focusOn(groupHit)
+							view.selectFeatures(groupHit)
+							check('搜索与筛选：scope=groups 返回通道分组，并可直接聚焦 / 选中分组命中', Boolean(groupReady) && readout('search-filter-summary').includes('节点 0') && readout('search-filter-summary').includes('通道 0') && groupHit?.kind === 'group' && view.getSelections().length > 0, `${readout('search-filter-summary')} / ${JSON.stringify(groupHit)}`)
+							click('search-filter-preset-symbol')
 						const symbolReady = await until(() => readout('search-filter-summary').includes('节点 8'), 4000)
 						check('搜索与筛选：显式 fields=[symbol] 能搜默认跳过的符号字段', Boolean(symbolReady) && readout('search-filter-hit-0').includes('symbol = square'), `${readout('search-filter-summary')} / ${readout('search-filter-hit-0')}`)
 						document.querySelector('[data-demo=search-filter-worker]')?.click()
@@ -986,7 +992,7 @@
 					}
 				}
 
-				// 2.0c 扩展能力：五个扩展点各开一次，读数 / 徽标 / 导出结果与 WebGL 层都要跟着变
+				// 2.0c 扩展能力：六个扩展点各开一次，读数 / 徽标 / 导出结果 / WebGL 层与命令表都要跟着变
 				if (await clickTab('扩展能力')) {
 					const ready = await canvasReady()
 					await wait(220)
@@ -1013,6 +1019,17 @@
 					click('extension-plugin')
 					const badgeRemoved = await until(() => !document.querySelector('.demo-extension-badge'), 4000)
 					check('扩展能力：卸载函数执行 destroy，徽标与读数一起撤回', Boolean(badgeRemoved) && readout().includes('运行时插件 未挂载'), readout())
+					click('extension-command-register')
+					const commandReady = await until(() => setup.commandRegistered === true && view?.listCommands().includes('focusHighestLoad') && readout().includes('focusHighestLoad 已注册'), 4000)
+					check('扩展能力：registerCommand 把业务动作注册进当前实例的命令表', Boolean(commandReady), readout())
+					click('extension-command-run')
+					const commandText = () => document.querySelector('[data-demo=extension-command-readout]')?.textContent.trim() ?? ''
+					const commandRan = await until(() => commandText().includes('ok: true') && commandText().includes('focusHighestLoad') === false && view?.getSelectionData().count === 1, 4000)
+					check('扩展能力：executeCommand 执行 handler、返回业务值并顺带选中定位目标', Boolean(commandRan) && commandText().includes('selected'), commandText())
+					click('extension-command-register')
+					const commandRemoved = await until(() => setup.commandRegistered === false && !view?.listCommands().includes('focusHighestLoad') && readout().includes('实例命令 未注册'), 4000)
+					const missingCommand = view?.executeCommand('focusHighestLoad', {})
+					check('扩展能力：命令卸载后从 listCommands 消失，再执行返回 ok: false', Boolean(commandRemoved) && missingCommand?.ok === false, commandText())
 					click('extension-export')
 					const exported = await until(() => exportText().includes('gis-view.extension-summary.v1') && exportText().includes('highLoadStations'), 4000)
 					let summary = null
@@ -2237,8 +2254,8 @@
 					await wait(150)
 					const apiItems = () => [...document.querySelectorAll('.demo-api-list:not(.demo-api-list--options) .demo-api-item')]
 					const optionItems = () => [...document.querySelectorAll('.demo-api-list--options .demo-api-item')]
-					check('实例方法速查：整份成员清单按分组列全（16 组 / 253 个成员）',
-						Boolean(ready) && document.querySelectorAll('.demo-api-group').length === 16 && apiItems().length === 253,
+					check('实例方法速查：整份成员清单按分组列全（16 组 / 256 个成员）',
+						Boolean(ready) && document.querySelectorAll('.demo-api-group').length === 16 && apiItems().length === 256,
 						`${document.querySelectorAll('.demo-api-group').length} 组 / ${apiItems().length} 个成员`)
 					const apiNames = apiItems().map(node => node.querySelector('b')?.textContent)
 					const roundNames = ['registerSymbol', 'unregisterSymbol', 'listSymbols']
@@ -2253,7 +2270,7 @@
 					check('实例方法速查：这一轮拆出来的方法也在清单里（addChannelGroupLines / joinChannelGroupLines / endAddChannel）',
 						roundNames1597.every(name => apiNames.includes(name)),
 						roundNames1597.filter(name => !apiNames.includes(name)).join(' / ') || '三个都在')
-					check('实例方法速查：options 折叠清单列全 95 个键', optionItems().length === 95, `${optionItems().length} 个键`)
+					check('实例方法速查：options 折叠清单列全 96 个键', optionItems().length === 96, `${optionItems().length} 个键`)
 					const apiSearch = document.querySelector('.demo-api-search input[type="search"]')
 					apiSearch.value = 'focusOn'
 					apiSearch.dispatchEvent(new Event('input', { bubbles: true }))
@@ -2492,7 +2509,7 @@
 						document.querySelector('[data-demo=focus-channel]')?.click()
 						await wait(120)
 						const cameraAfter = apiView.getCamera()
-						check('接口能力 demo：focusOn({ type: channel }) 走统一包围盒适配并更新相机',
+						check('接口能力 demo：focusOn({ type: channel }, { zoom: true }) 显式走包围盒适配并更新相机',
 							cameraAfter.scale > 0 && (cameraAfter.scale !== cameraBefore.scale || cameraAfter.center[0] !== cameraBefore.center[0] || cameraAfter.center[1] !== cameraBefore.center[1]),
 							`scale ${cameraBefore.scale} → ${cameraAfter.scale} · center ${JSON.stringify(cameraBefore.center)} → ${JSON.stringify(cameraAfter.center)}`)
 						document.querySelector('[data-demo=style-apis]')?.click()

package/docs/steps/selftest-docs.html

@@ -127,8 +127,10 @@
 					check('文档中心：README 顶部有 4 条推荐阅读路径，3 篇文档加 API 页都指向真实目标', pathCards.length === 4 && pathDocs.length === 3 && pathDocs.every(file => files.includes(file)) && (apiPathCard?.getAttribute('href') ?? '').includes('api/index.html') && pathCards.every(card => card.querySelector('.doc-path__badge') && card.textContent.trim().length > 12), pathCards.map(card => card.querySelector('b')?.textContent?.trim()).join(' / '))
 					check('文档中心：正文链接的解析（相对「当前那份文档」算，解析不到给 null）', api.resolve('docs/GisView.md', '../README.md') === 'GisView.md' && api.resolve('../从0到完整的实现.md', 'steps/README.md') === '从0到完整的实现.md' && api.resolve('../index.html', 'README.md') === null)
 					const fixture = api.render('# 文档标题\n\n> 一句话摘要\n\n## 标题\n\n| A | B |\n| --- | --- |\n| 1 | 2 |\n\n```js\nconst a = 1\n```\n\n- 一级\n  - 二级\n\n> 正文引用\n\n行内 `code` 与 [链接](GisView.md)\n')
+					const tableFixture = api.render('| 字段 | 类型 |\n| --- | --- |\n| `type` | `\'image/png\' \\| \'image/jpeg\' \\| \'svg\'` |\n')
 					const leadFixture = api.render('# 只有导语\n\n第一段就是全文导语。\n')
 					check('文档中心：markdown 渲染器（标题 / 表格 / 带语言代码块 / 两级列表 / 引用 / 行内代码 / md 链接 / 目录）', fixture.html.includes('<table>') && fixture.html.includes('data-lang="js"') && (fixture.html.match(/<ul>/g) ?? []).length >= 2 && fixture.html.includes('<blockquote class="doc-summary">') && fixture.html.includes('<blockquote><p>正文引用</p></blockquote>') && fixture.html.includes('<code>code</code>') && fixture.html.includes('data-doc="GisView.md"') && fixture.toc.length === 1, `${fixture.html.length} 字符 / ${fixture.toc.length} 条目录`)
+					check('文档中心：表格里的反引号联合类型不被 `|` 拆列（转义竖线留在同一格）', (tableFixture.html.match(/<td>/g) ?? []).length === 2 && tableFixture.html.includes('<code>\'image/png\' | \'image/jpeg\' | \'svg\'</code>'), (tableFixture.html.match(/<td>[\s\S]*?<\/td>/g) ?? []).join(' / ').slice(0, 180))
 					check('文档中心：H1 后的摘要 / 首段分别套导语卡片与导语段落', leadFixture.html.includes('<p class="doc-lead">第一段就是全文导语。</p>'), leadFixture.html.slice(0, 120))
 					await api.load('数据格式.md')
 					const meta2 = doc.querySelector('#content .meta')
@@ -518,10 +520,37 @@
 				if (check('API 速查：挂上了 __gisApi 钩子（数据来自 api-index.js，没钩子多半是 file:// 打开的）', Boolean(apiHook))) {
 					const apiDoc = apiFrame.contentDocument
 					const summary = apiHook.summary
-					check('API 速查：清单来自 api-index（253 个成员 / 95 个 options / 16 个分组）',
-						summary.members === 253 && summary.options === 95 && summary.sections === 16,
+					check('API 速查：清单来自 api-index（256 个成员 / 253 个方法 / 96 个 options / 16 个分组）',
+						summary.members === 256 && summary.methods === 253 && summary.options === 96 && summary.sections === 16,
 						JSON.stringify(summary))
+					const topJumps = [...apiDoc.querySelectorAll('.doc-jump')]
+					const jumpTargets = topJumps.map(node => `${node.dataset.docJump}:${node.getAttribute('href')}`)
+					check('API 速查：顶栏四个文档深链齐全，分别指到文档中心 / 实例方法 / 参数速查 / 逐方法示例',
+						jumpTargets.join('|') === 'center:../index.html#GisView.md|methods:../index.html#manual/16-实例方法总表.md|params:../index.html#manual/17-参数速查.md|examples:../index.html#manual/18-逐方法示例.md',
+						jumpTargets.join(' | '))
+					const groupLinks = [...apiDoc.querySelectorAll('.api-group > h2 .group-manual')]
+					check('API 速查：每个分组都有回手册的章节链接（16 组 + options）',
+						groupLinks.length === summary.sections + 1 && groupLinks.length === apiDoc.querySelectorAll('.api-group').length &&
+						groupLinks.every(node => node.dataset.manualGroup && decodeURIComponent(String(node.getAttribute('href'))).startsWith('../index.html#manual/')),
+						groupLinks.map(node => node.dataset.manualGroup).join(' / '))
 					check('API 速查：左侧分组有当前项，滚动 / 点选时会跟着亮', apiHook.activeGroup() !== null, String(apiHook.activeGroup()))
+					const apiWindow = apiFrame.contentWindow
+					const elementPrototype = apiWindow.Element?.prototype
+					const originalScrollIntoView = elementPrototype?.scrollIntoView
+					let groupScrollCall = null
+					if (elementPrototype) {
+						elementPrototype.scrollIntoView = function (options) {
+							groupScrollCall = { options, target: this.id }
+						}
+					}
+					const secondGroupButton = apiDoc.querySelector('#side-list .side-item[data-group="1"]')
+					click(secondGroupButton)
+					if (elementPrototype) {
+						elementPrototype.scrollIntoView = originalScrollIntoView
+					}
+					check('API 速查：左侧分组跳转用即时滚动（behavior: auto），长页不会平滑滚好几秒',
+						Boolean(secondGroupButton) && groupScrollCall?.options?.behavior === 'auto' && groupScrollCall?.options?.block === 'start' && groupScrollCall?.target === 'group-1',
+						JSON.stringify(groupScrollCall))
 					check('API 速查：分组都渲染出来（16 组 + options 一组）',
 						apiDoc.querySelectorAll('.api-group').length === 17 && apiDoc.querySelectorAll('.api-group > h2 b').length === 17,
 						`${apiDoc.querySelectorAll('.api-group').length} 组`)
@@ -530,8 +559,8 @@
 						`${apiDoc.querySelectorAll('.api-member').length} 张卡片 / 属性 ${apiDoc.querySelectorAll('.api-member[data-kind="property"]').length} 张`)
 					const noExample = [...apiDoc.querySelectorAll('.api-member')].filter(node => Number(node.dataset.examples) < 1)
 					check('API 速查：每个成员都带至少一段示例（不出现空卡片）', noExample.length === 0,
-						noExample.length ? noExample.map(node => node.dataset.name).join(' / ') : '253 张卡片都有示例')
-					check('API 速查：95 个 options 都列全（名字 / 类型 / 默认值 / 说明四件套）',
+						noExample.length ? noExample.map(node => node.dataset.name).join(' / ') : '256 张卡片都有示例')
+					check('API 速查：96 个 options 都列全（名字 / 类型 / 默认值 / 说明四件套）',
 						apiDoc.querySelectorAll('.api-option').length === summary.options && [...apiDoc.querySelectorAll('.api-option')].every(node => node.querySelector('.name code') && node.querySelector('.type') && node.querySelector('.def') && node.querySelector('.doc')),
 						`${apiDoc.querySelectorAll('.api-option').length} 个`)
 					const statCards = [...apiDoc.querySelectorAll('#stats .api-stat')]

package/docs/steps/selftest-features.html

@@ -1765,9 +1765,59 @@
 					faView.selectFeatures('fa-around')
 					const faWaypointCleared = faView.getWaypoints().filter(item => item.lineIndex === 5).every(item => !item.selected)
 					check('selectWaypoint：按线路 + 下标选中拐点并带选线路，selectFeatures 会清掉拐点选中', faWaypointSelected && faWaypointLineSelected && faWaypointCleared, JSON.stringify({ selected: faWaypointSelected, line: faWaypointLineSelected, cleared: faWaypointCleared, all: faView.getWaypoints(), lines: faView.getData().lines }))
+					// search 也认 focusOn 的四种目标；分组命中可以直接交给 focusOn / selectFeatures
+					const faGroupSearch = faView.search({ keyword: 'fa-high', scope: 'group', limit: 10 })
+					const faGroupHit = faGroupSearch.groups[0]
+					faView.focusOn(faGroupHit)
+					const faGroupSearchCenter = faView.getCamera().center
+					faView.selectFeatures(faGroupHit)
+					const faGroupHitSelected = faView.getSelections().filter(item => item.type === 'line').map(item => item.item.id).sort()
+					const faDefaultGroupSearch = await faView.searchAsync({ keyword: 'fa-high', limit: 10 })
+					check('search：单数 group 范围返回分组命中，命中可直接 focusOn / selectFeatures', faGroupSearch.scope.length === 1 && faGroupSearch.scope[0] === 'groups' && faGroupHit?.kind === 'group' && faGroupHit.channelIndex === 1 && faGroupHit.groupId === 'fa-high' && faGroupHit.groupIndex === 0 && Math.abs(faGroupSearchCenter[1] - 40) < 0.01 && faGroupHitSelected.join(',') === 'fa-l3,fa-l4', JSON.stringify({ scope: faGroupSearch.scope, hit: faGroupHit, center: faGroupSearchCenter, selected: faGroupHitSelected }))
+					check('searchAsync：缺省范围包含 groups，Worker / 同步回落都带 groups 结果', faDefaultGroupSearch.groups.length === 1 && faDefaultGroupSearch.hits.some(hit => hit.kind === 'group' && hit.groupId === 'fa-high'), JSON.stringify({ scope: faDefaultGroupSearch.scope, groups: faDefaultGroupSearch.groups.length, worker: faDefaultGroupSearch.worker }))
+					// 线路 / 通道 / 分组都只在 zoom: true 时适配：与显式 zoomToBounds 的比例逐位一致，没有类型专属放大倍率
+					const faLineHit = faView.search({ keyword: 'fa-around', scope: 'line', limit: 1 }).lines[0]
+					const faChannelHit = faView.search({ keyword: 'fa-low-ch', scope: 'channel', limit: 1 }).channels[0]
+					const faFocusScales = [faLineHit, faChannelHit, faGroupHit].map((hit) => {
+						faView.zoomToBounds(hit.bounds)
+						const expected = faView.getCamera().scale
+						faView.focusOn(hit, { zoom: true })
+						return [expected, faView.getCamera().scale]
+					})
+					check('focusOn({ zoom: true })：线路 / 通道 / 分组适配后的比例与同一份 bounds 的 zoomToBounds 完全一致', faFocusScales.every(([expected, actual]) => Math.abs(expected - actual) < 1e-9), JSON.stringify(faFocusScales))
 					faView.destroy()
 					faHost.remove()
 
+					/* 筛选是隐藏、不是删除：选中的要素被筛掉时保留在选中集里，条件清空后原样恢复 */
+					const fsHost = document.createElement('div')
+					fsHost.style.cssText = 'width:320px;height:200px'
+					document.body.appendChild(fsHost)
+					const fsChanges = []
+					const fsView = createGisView(fsHost, {
+						points: [
+							{ id: 'fs-a', x: -30, y: 0, level: 0 },
+							{ id: 'fs-b', x: 30, y: 0, level: 1 }
+						],
+						lines: [{ id: 'fs-l1', from: 'fs-a', to: 'fs-b' }],
+						initialView: { center: [0, 0], scale: 1 },
+						showGrid: false,
+						onSelectChange: payload => fsChanges.push(payload)
+					})
+					await settle(100)
+					fsView.selectFeatures(['fs-a', 'fs-l1'])
+					const fsChangesBeforeFilter = fsChanges.length
+					fsView.setFilter({ points: { level: 1 }, cascade: false })
+					await settle(100)
+					const fsHiddenIds = fsView.getSelections().map(item => String(item.item.id)).sort().join(',')
+					const fsHiddenVisible = fsView.getVisibleData().points.some(point => point.id === 'fs-a')
+					const fsChangesAfterFilter = fsChanges.length
+					fsView.setFilter(null)
+					await settle(100)
+					const fsRestoredIds = fsView.getSelections().map(item => String(item.item.id)).sort().join(',')
+					check('setFilter 只隐藏要素：选中项保留，条件清空后仍选中且不额外发选中变更', fsHiddenIds === 'fs-a,fs-l1' && fsHiddenVisible === false && fsChangesAfterFilter === fsChangesBeforeFilter && fsRestoredIds === 'fs-a,fs-l1', JSON.stringify({ hidden: fsHiddenIds, visible: fsHiddenVisible, changes: [fsChangesBeforeFilter, fsChangesAfterFilter], restored: fsRestoredIds }))
+					fsView.destroy()
+					fsHost.remove()
+
 					/* lineFollowsNode: false：隐藏 / 筛选 / 删除只动节点，回线与通道停在最后坐标 */
 					const lfHost = document.createElement('div')
 					lfHost.style.cssText = 'width:360px;height:220px'
@@ -3405,13 +3455,13 @@
 						showGrid: false
 					})
 					await settle(160)
-					fitView.focusOn('fl1', { padding: 220 })
+					fitView.focusOn('fl1', { zoom: true, padding: 220 })
 					await settle(80)
 					const fitStart = fitView.project(0, 0)
 					const fitEnd = fitView.project(300, 200)
 					const fitSpan = Math.hypot(fitStart[0] - fitEnd[0], fitStart[1] - fitEnd[1])
 					check('适应视图的留白比画布还大时：内容不会被挤成一个点（至少留给它 48px）', fitSpan > 40, `跨度 ${fitSpan.toFixed(1)}px / 画布 ${fitView.getStats().cssWidth}×${fitView.getStats().cssHeight}`)
-					fitView.focusOn('fl1', { padding: 20 })
+					fitView.focusOn('fl1', { zoom: true, padding: 20 })
 					await settle(80)
 					const fitPadStart = fitView.project(0, 0)
 					const fitPadEnd = fitView.project(300, 200)
@@ -3921,13 +3971,17 @@
 					apiSend('pointerup', [apiRight, apiBottom], { button: 0, buttons: 0, shiftKey: true })
 					await settle()
 					check('框选的结果用同一份读数读回来（Shift + 拖动）', apiIds() === 'api-a,api-b,api-c' && apiView.getSelectionData().count === 3, apiIds())
-					// focusOn 一批目标：数组取整体包围盒 —— 这三个点的中心（200, 20）当屏幕中心、按这一批的范围适配
+					// focusOn 一批目标：缺省只居中；显式 zoom: true 才按整体包围盒适配
+					const apiDefaultScale = apiView.getCamera().scale
 					apiView.focusOn(['api-a', 'api-b', 'api-c'])
+					const apiCenteredBatch = apiView.getCamera()
+					check('focusOn(一批目标)：缺省只把中心挪到 (200, 20)，比例一点不动', Math.abs(apiCenteredBatch.center[0] - 200) < 1e-6 && Math.abs(apiCenteredBatch.center[1] - 20) < 1e-6 && apiCenteredBatch.scale === apiDefaultScale, JSON.stringify({ scale: [apiDefaultScale, apiCenteredBatch.scale], center: apiCenteredBatch.center }))
+					apiView.focusOn(['api-a', 'api-b', 'api-c'], { zoom: true })
 					const apiBatch = apiView.getCamera()
 					const apiStats = apiView.getStats()
 					const apiCorners = [[0, 0], [400, 40]].map(spot => apiView.project(spot[0], spot[1]))
 					const apiInside = apiCorners.every(spot => spot[0] >= 0 && spot[0] <= apiStats.cssWidth && spot[1] >= 0 && spot[1] <= apiStats.cssHeight)
-					check('focusOn(一批目标)：整体包围盒居中（三个点的中心当屏幕中心，三个点都在视口里）', Math.abs(apiBatch.center[0] - 200) < 1e-6 && Math.abs(apiBatch.center[1] - 20) < 1e-6 && apiBatch.scale > 0 && apiInside, JSON.stringify({ center: apiBatch.center, corners: apiCorners }))
+					check('focusOn(一批目标, { zoom: true })：整体包围盒居中，三个点都在视口里', Math.abs(apiBatch.center[0] - 200) < 1e-6 && Math.abs(apiBatch.center[1] - 20) < 1e-6 && apiBatch.scale > 0 && apiInside, JSON.stringify({ center: apiBatch.center, corners: apiCorners }))
 					// center: true 是原来 centerOn 的语义：只挪中心，比例一点不动
 					apiView.focusOn(['api-a', 'api-b'], { center: true })
 					const apiCenter1 = apiView.getCamera()
@@ -3938,9 +3992,11 @@
 					apiView.focusOn('api-b', { center: true })
 					const apiCenter3 = apiView.getCamera().center
 					check('focusOn(id, { center: true })：中心挪到这个要素上', Math.abs(apiCenter3[0] - 200) < 1e-6 && Math.abs(apiCenter3[1] - 40) < 1e-6, JSON.stringify(apiCenter3))
-					apiView.focusOn({ type: 'channel', channelId: 'api-ch' }, { center: true })
-					const apiCenter4 = apiView.getCamera().center
-					check('focusOn(通道写法, { center: true })：取这条通道范围的中心', Math.abs(apiCenter4[0] - 100) < 5 && Math.abs(apiCenter4[1] - 20) < 5, JSON.stringify(apiCenter4))
+					const apiChannelScale = apiView.getCamera().scale
+					apiView.focusOn({ type: 'channel', channelId: 'api-ch' })
+					const apiChannelCamera = apiView.getCamera()
+					const apiCenter4 = apiChannelCamera.center
+					check('focusOn(通道写法) 缺省只居中，线路 / 通道不再自动放大', Math.abs(apiCenter4[0] - 100) < 5 && Math.abs(apiCenter4[1] - 20) < 5 && apiChannelCamera.scale === apiChannelScale, JSON.stringify({ center: apiCenter4, scale: [apiChannelScale, apiChannelCamera.scale] }))
 					apiView.focusOn('没有这个 id', { center: true })
 					const apiCenter5 = apiView.getCamera().center
 					check('focusOn：认不出来的目标什么都不做（视角停在原处）', apiCenter5[0] === apiCenter4[0] && apiCenter5[1] === apiCenter4[1], JSON.stringify(apiCenter5))
@@ -3949,16 +4005,41 @@
 					check('focusOn(一段范围, { center: true })：取中心', Math.abs(apiCenter6[0] - 200) < 1e-6 && Math.abs(apiCenter6[1] - 20) < 1e-6, JSON.stringify(apiCenter6))
 					// select: true：被聚焦的要素同时变成选中状态（与接口选中同一份 state）；mode 决定怎么并进当前选中集
 					const apiBeforeFocusSelect = apiView.getSelectionData().ids.join(',')
-					apiView.focusOn(['api-a', 'api-b', 'api-c'], { select: true, padding: 20 })
+					apiView.focusOn(['api-a', 'api-b', 'api-c'], { select: true, zoom: true, padding: 20 })
 					check('focusOn(一批, { select: true })：被聚焦的这一批同时选中（整份选中集换成这三个）', apiView.getSelectionData().ids.join(',') === 'api-a,api-b,api-c' && apiBeforeFocusSelect === 'api-a,api-b,api-c' && apiView.getSelectionData().count === 3, `${apiBeforeFocusSelect} -> ${apiView.getSelectionData().ids.join(',')}`)
 					apiView.focusOn('api-a', { select: true, mode: 'remove' })
 					check("focusOn(..., { select: true, mode: 'remove' })：只把聚焦的这个从选中集里去掉", apiView.getSelectionData().ids.join(',') === 'api-b,api-c', apiView.getSelectionData().ids.join(','))
 					apiView.selectFeatures(null)
 					const apiAreaScale = apiView.getCamera().scale
-					apiView.focusOn('api-b', { maxZoom: 12 })
+					apiView.focusOn('api-b', { zoom: true, maxZoom: 12 })
 					const apiZoomCamera = apiView.getCamera()
-					check('focusOn(单个节点, { maxZoom })：零面积目标撑出最小范围，放大并居中', apiZoomCamera.scale > apiAreaScale && Math.abs(apiZoomCamera.center[0] - 200) < 1e-6 && Math.abs(apiZoomCamera.center[1] - 40) < 1e-6, JSON.stringify({ scale: apiZoomCamera.scale, center: apiZoomCamera.center }))
+					check('focusOn(单个节点, { zoom: true, maxZoom })：零面积目标撑出最小范围，放大并居中', apiZoomCamera.scale > apiAreaScale && Math.abs(apiZoomCamera.center[0] - 200) < 1e-6 && Math.abs(apiZoomCamera.center[1] - 40) < 1e-6, JSON.stringify({ scale: apiZoomCamera.scale, center: apiZoomCamera.center }))
+					// 实例命令：注册 / 执行 / 同名覆盖 / 幂等卸载；名字与 handler 非法时只提醒、不动注册表
+					let commandPayload = null
+					let commandContext = null
+					const disposeEcho = apiView.registerCommand('  demo:echo  ', (payload, context) => {
+						commandPayload = payload
+						commandContext = context
+						return { doubled: Number(payload?.value ?? 0) * 2 }
+					})
+					const echoResult = apiView.executeCommand('demo:echo', { value: 21 })
+					check('registerCommand / executeCommand：名字规范化、payload 与冻结上下文可用，handler 的返回值原样带回', apiView.listCommands().join(',') === 'demo:echo' && echoResult.ok === true && echoResult.name === 'demo:echo' && echoResult.value?.doubled === 42 && commandPayload?.value === 21 && commandContext?.view === apiView && commandContext?.name === 'demo:echo' && Object.isFrozen(commandContext), JSON.stringify({ commands: apiView.listCommands(), result: echoResult, context: commandContext?.name }))
+					const disposeReplacement = apiView.registerCommand('demo:echo', payload => `replacement:${payload}`)
+					disposeEcho()
+					const replacementResult = apiView.executeCommand('demo:echo', 'still-here')
+					check('registerCommand：同名后注册覆盖先生效，旧卸载函数不会误删新命令', apiView.listCommands().join(',') === 'demo:echo' && replacementResult.ok === true && replacementResult.value === 'replacement:still-here', JSON.stringify({ commands: apiView.listCommands(), result: replacementResult }))
+					disposeReplacement()
+					const invalidDispose = apiView.registerCommand('   ', () => 'never')
+					const invalidResult = apiView.executeCommand('', {})
+					const missingResult = apiView.executeCommand('demo:missing', {})
+					check('实例命令：非法名 / 未注册 / 空名字都返回 ok: false，注册表不受影响', typeof invalidDispose === 'function' && invalidResult.ok === false && missingResult.ok === false && apiView.listCommands().length === 0, JSON.stringify({ invalid: invalidResult, missing: missingResult, commands: apiView.listCommands() }))
+					apiView.registerCommand('demo:throw', () => { throw new Error('命令执行失败') })
+					const thrownResult = apiView.executeCommand('demo:throw', null)
+					check('实例命令：handler 抛错收成 ok: false + reason，不把异常甩给调用方', thrownResult.ok === false && thrownResult.name === 'demo:throw' && thrownResult.reason === '命令执行失败', JSON.stringify(thrownResult))
+					apiView.registerCommand('demo:destroyed', () => 'never')
 					apiView.destroy()
+					const afterDestroy = apiView.executeCommand('demo:destroyed', null)
+					check('destroy：实例命令表清空，销毁后执行返回 ok: false', apiView.listCommands().length === 0 && afterDestroy.ok === false, JSON.stringify({ commands: apiView.listCommands(), result: afterDestroy }))
 					apiHost.remove()
 				}
 				/* ---------------- 线路 zIndex：电压高的线压在上面（见 15.47） ---------------- */

package/docs/steps/selftest-scale.html

@@ -373,6 +373,104 @@
 				await settle()
 				check('cascade: false 换回来，通道回线又出来', cascadeView.listLines({}).length === 2, `画出来的线 ${cascadeView.listLines({}).length} 条`)
 				cascadeView.destroy()
+				/* 3.7 删除型筛选：不命中的要素真正从数据里删掉；无 id 线路、点级联、通道、单条事件与历史都走同一条路。
+				   初始 filter 在创建期就生效，ready 看到的是删完的数据；undo / redo 只回放数据，不会让 remove 筛选再删一次 */
+				const removeChanges = []
+				let removeFilterCount = 0
+				let removeReady = null
+				const filterRemoveView = createGisView(host(420, 240), {
+					points: [
+						{ id: 'keep-a', x: 0, y: 0, keep: true },
+						{ id: 'drop', x: 50, y: 0, keep: false },
+						{ id: 'keep-b', x: 100, y: 0, keep: true }
+					],
+					lines: [
+						{ id: 'bound', from: 'drop', to: 'keep-a', keep: true },
+						{ path: [[50, 20], [100, 20]], keep: false },
+						{ id: 'kept-line', from: 'keep-a', to: 'keep-b', keep: true }
+					],
+					channels: [{ id: 'filter-ch', from: 'drop', to: 'keep-a', lineIds: ['bound'] }],
+					filter: { points: { keep: true }, lines: { keep: true }, cascade: 'binding', mode: 'remove' },
+					filterWorker: false,
+					history: true,
+					onReady: () => queueMicrotask(() => {
+						const data = filterRemoveView.getData()
+						removeReady = { points: data.points.length, lines: data.lines.length, channels: filterRemoveView.getOptions().channels.length }
+					}),
+					onFilter: () => { removeFilterCount += 1 },
+					onDataChange: payload => removeChanges.push(payload)
+				})
+				await settle()
+				const removeData = filterRemoveView.getData()
+				const removeChange = removeChanges.find(payload => payload.type === 'filterRemove') ?? null
+				const removeFinal = filterRemoveView.getFilterResult()
+				check('remove 筛选：初始条件在 ready 前删完（只留命中的点 / 线，空通道一并消失）',
+					removeReady?.points === 2 && removeReady?.lines === 1 && removeReady?.channels === 0 &&
+					removeData.points.every(point => point.keep === true) && removeData.lines.length === 1 && filterRemoveView.getOptions().channels.length === 0,
+					`ready ${JSON.stringify(removeReady)} / 数据 ${removeData.points.length} 点 ${removeData.lines.length} 线 ${filterRemoveView.getOptions().channels.length} 通道`)
+				check('remove 筛选：无 id 线路按原下标删除，级联线路与通道一起清掉',
+					removeData.lines[0]?.id === 'kept-line' &&
+					JSON.stringify(removeChange?.pointIndexes) === JSON.stringify([1]) &&
+					JSON.stringify(removeChange?.removedLineIndexes) === JSON.stringify([0, 1]) &&
+					removeChange?.removedLines === 2 && removeChange?.removedChannels === 1 &&
+					removeChange?.mode === 'remove' && removeChange?.removedPoints?.length === 1 && removeChange?.removedPoints?.[0]?.id === 'drop' &&
+					removeChange?.removedLineItems?.length === 2 && removeChange?.removedLineItems.some(line => line?.id === 'bound') &&
+					removeChange?.points?.length === 2 && !removeChange.points.some(point => point?.id === 'drop'),
+					JSON.stringify({ pointIndexes: removeChange?.pointIndexes, removedLineIndexes: removeChange?.removedLineIndexes, removedPoints: removeChange?.removedPoints?.map(point => point?.id), removedLineItems: removeChange?.removedLineItems?.map(line => line?.id ?? '无 id'), remainingPoints: removeChange?.points?.map(point => point?.id), lines: removeChange?.removedLines, channels: removeChange?.removedChannels }))
+				check('remove 筛选：只发一条 filterRemove 数据变更，不发中间的 removePoints / removeLines',
+					removeChanges.length === 1 && removeChange?.type === 'filterRemove' && removeChange?.ok === true,
+					removeChanges.map(payload => payload.type).join(',') || '无')
+				check('remove 筛选：删除完成后隐藏集合为空，并只回调一次 onFilter',
+					removeFinal?.hiddenPoints.length === 0 && removeFinal?.hiddenLines.length === 0 && removeFilterCount === 1,
+					`hidden ${removeFinal?.hiddenPoints.length}/${removeFinal?.hiddenLines.length} · onFilter ${removeFilterCount}`)
+				check('remove 筛选：历史只记一步 filterRemove',
+					filterRemoveView.getHistoryState().undoCount === 1 && filterRemoveView.getHistory()[0]?.type === 'filterRemove',
+					JSON.stringify(filterRemoveView.getHistory()))
+				const removeHistoryChanges = removeChanges.length
+				filterRemoveView.undo()
+				await settle()
+				const removeUndone = filterRemoveView.getData()
+				check('remove 筛选撤销：数据原样恢复，不会被仍生效的 remove 条件再次删除',
+					removeUndone.points.length === 3 && removeUndone.lines.length === 3 && filterRemoveView.getOptions().channels.length === 1 &&
+					removeChanges.filter(payload => payload.type === 'filterRemove').length === 1,
+					`${removeUndone.points.length} 点 ${removeUndone.lines.length} 线 ${filterRemoveView.getOptions().channels.length} 通道 / 新增 ${removeChanges.length - removeHistoryChanges} 条事件`)
+				check('remove 筛选撤销：筛选仍生效，恢复出来的不命中要素按隐藏态显示',
+					filterRemoveView.getFilter()?.mode === 'remove' &&
+					JSON.stringify(filterRemoveView.getFilterResult()?.hiddenPoints) === JSON.stringify([1]) &&
+					JSON.stringify(filterRemoveView.getFilterResult()?.hiddenLines) === JSON.stringify([0, 1]),
+					JSON.stringify({ hiddenPoints: filterRemoveView.getFilterResult()?.hiddenPoints, hiddenLines: filterRemoveView.getFilterResult()?.hiddenLines }))
+				filterRemoveView.redo()
+				await settle()
+				const removeRedone = filterRemoveView.getData()
+				check('remove 筛选重做：数据回到删完的状态，不会补发第二条 filterRemove',
+					removeRedone.points.length === 2 && removeRedone.lines.length === 1 && filterRemoveView.getOptions().channels.length === 0 &&
+					removeChanges.filter(payload => payload.type === 'filterRemove').length === 1,
+					`${removeRedone.points.length} 点 ${removeRedone.lines.length} 线 ${filterRemoveView.getOptions().channels.length} 通道`)
+				filterRemoveView.destroy()
+				const runtimeRemoveChanges = []
+				const runtimeRemoveView = createGisView(host(320, 200), {
+					points: [{ id: 'r0', x: 0, y: 0, keep: true }, { id: 'r1', x: 60, y: 0, keep: false }],
+					filterWorker: false,
+					onDataChange: payload => runtimeRemoveChanges.push(payload.type)
+				})
+				runtimeRemoveView.setFilter({ points: { keep: true }, mode: 'remove' })
+				await settle()
+				check('remove 筛选：运行时 setFilter 同样只发一条 filterRemove 并删掉不命中项',
+					runtimeRemoveView.getData().points.length === 1 && runtimeRemoveChanges.filter(type => type === 'filterRemove').length === 1,
+					`${runtimeRemoveView.getData().points.length} 点 / ${runtimeRemoveChanges.join(',') || '无事件'}`)
+				runtimeRemoveView.destroy()
+				const isolatedRemoveView = createGisView(host(320, 200), {
+					points: [{ id: 'i0', x: 0, y: 0, keep: true }, { id: 'i1', x: 80, y: 0, keep: false }],
+					lines: [{ id: 'i-line', from: 'i1', to: 'i0', keep: true }],
+					filter: { points: { keep: true }, cascade: false, mode: 'remove' },
+					filterWorker: false
+				})
+				await settle()
+				const isolatedRemoveData = isolatedRemoveView.getData()
+				check('remove 筛选：cascade: false 时删点只删筛选结果，不按 lineFollowsNode 连带删线路',
+					isolatedRemoveData.points.length === 1 && isolatedRemoveData.lines.length === 1,
+					`${isolatedRemoveData.points.length} 点 / ${isolatedRemoveData.lines.length} 线`)
+				isolatedRemoveView.destroy()
 				/* 4. 网格索引：线段按「真正穿过的格子」登记，一层铺不下就换更粗的一层（不再按包围盒兜底） */
 				const segments = [{ start: [0, 0], end: [1000, 1000] }, { start: [0, 950], end: [1000, 1000] }]
 				for (let index = 0; index < 4000; index += 1) {