gis-view-webgl2 0.1.2 → 0.1.3

package/docs/steps/selftest-labels.html

@@ -1287,8 +1287,82 @@
 				const exportedZoomed = exportedZoom.node
 				const expectedZoomX = canvasLabelView.project(anchorPoint.x, anchorPoint.y)[0] + anchorGap
 				check('Canvas 标签随缩放只推一次，不与导出坐标二次叠加', Number.isFinite(anchorGap) && exportedZoomed !== null && Math.abs(Number(exportedZoomed.getAttribute('x')) - expectedZoomX) <= 1, `期望 x=${expectedZoomX.toFixed(1)} / 实际 ${exportedZoomed?.getAttribute('x') ?? '没有标签'} / 文本 ${exportedZoom.texts.length} 条：${exportedZoom.texts.slice(0, 8).join(',')} / 画布 ${canvasCount()} / DOM ${canvasDomCount()} / 收起 ${canvasLayer?.classList.contains('gis-view__label-layer--hidden')} / 相机 ${JSON.stringify(canvasLabelView.getCamera())}`)
+				// 前面的导出断言把视图放大了 2 倍：缩回能看见全部 1100 条的尺度，后面的数量断言才有稳定基数
+				canvasLabelView.setCamera({ ...cameraBeforeCanvasZoom, scale: 1 })
+				await settle(600)
+				// 29. 画布文字测量缓存：1100 条同文案标签只量一次宽度
+				const measureContext = labelCanvas.getContext('2d')
+				const nativeMeasureText = measureContext.measureText
+				let measureCalls = 0
+				measureContext.measureText = function (...args) {
+					measureCalls += 1
+					return nativeMeasureText.apply(this, args)
+				}
+				const sameNamePoints = canvasLabelPoints.map(point => ({ ...point, name: '同名' }))
+				try {
+					canvasLabelView.updateOptions({ points: sameNamePoints, labelRender: 'canvas' })
+					await settle(600)
+				}
+				finally {
+					measureContext.measureText = nativeMeasureText
+				}
+				check('1100 条同文案画布标签共用文字测量缓存（measureText ≤ 2 次）', canvasCount() >= 1100 && canvasDomCount() === 0 && measureCalls <= 2, `画布 ${canvasCount()} 条 / DOM ${canvasDomCount()} 条 / measureText ${measureCalls} 次`)
+				// 30. 连续缩放按 rAF 合并：同一次任务里的多次相机变化只重绘一次
+				const nativeClearRect = measureContext.clearRect
+				let canvasClears = 0
+				measureContext.clearRect = function (...args) {
+					canvasClears += 1
+					return nativeClearRect.apply(this, args)
+				}
+				const cameraBeforeBurst = canvasLabelView.getCamera()
+				try {
+					for (let step = 1; step <= 5; step += 1) {
+						canvasLabelView.setCamera({ ...cameraBeforeBurst, scale: cameraBeforeBurst.scale * (1 + step * 0.01) })
+					}
+					await settle(80)
+				}
+				finally {
+					measureContext.clearRect = nativeClearRect
+				}
+				check('连续 5 次缩放变化只重绘画布一次', canvasClears >= 1 && canvasClears <= 2, `clearRect ${canvasClears} 次 / 画布 ${canvasCount()} 条`)
+				// 31. 显式 canvas 不受 1024 条阈值限制，优化档也走画布并遵守 maxCount
+				canvasLabelView.updateOptions({
+					points: sameNamePoints,
+					labelOptimize: true,
+					labelRender: 'canvas',
+					label: { enabled: true, content: '{name}', maxCount: 200 }
+				})
+				await settle(600)
+				check('labelRender: canvas 在优化档强制画布并遵守 maxCount（200 条）', canvasCount() > 0 && canvasCount() <= 200 && canvasDomCount() === 0, `画布 ${canvasCount()} 条 / DOM ${canvasDomCount()} 条 / maxCount ${canvasLabelView.getOptions().label?.maxCount}`)
 				canvasLabelView.destroy()
 				canvasLabelHost.remove()
+				const canvasLineHost = document.createElement('div')
+				canvasLineHost.style.cssText = 'width:800px;height:500px'
+				document.body.append(canvasLineHost)
+				const canvasLinePoints = []
+				const canvasLines = []
+				for (let row = 0; row < 6; row += 1) {
+					const from = `line-from-${row}`
+					const to = `line-to-${row}`
+					canvasLinePoints.push({ id: from, x: -220, y: (row - 2.5) * 52, name: from })
+					canvasLinePoints.push({ id: to, x: 220, y: (row - 2.5) * 52, name: to })
+					canvasLines.push({ id: `canvas-line-${row}`, from, to, name: `线路 ${row}` })
+				}
+				const canvasLineView = createGisViewRaw(canvasLineHost, {
+					points: canvasLinePoints,
+					lines: canvasLines,
+					initialView: { scale: 1, center: [0, 0] },
+					lineLabel: { enabled: true, content: '{name}', position: 0.5, maxCount: 20 },
+					labelOptimize: true,
+					labelRender: 'canvas',
+					showGrid: false
+				})
+				await settle(300)
+				const lineCanvasLayer = canvasLineHost.querySelector('.gis-view__label-layer--line')
+				const lineCanvas = lineCanvasLayer?.querySelector('.gis-view__label-canvas')
+				check('线路标签同样支持 labelRender: canvas（优化档、6 条全部进画布）', Number(lineCanvas?.dataset.labelCount || 0) === 6 && (lineCanvasLayer?.querySelectorAll('.gis-view__label').length ?? 0) === 0, `画布 ${lineCanvas?.dataset.labelCount ?? 0} 条 / DOM ${lineCanvasLayer?.querySelectorAll('.gis-view__label').length ?? 0} 条`)
+				canvasLineView.destroy()
+				canvasLineHost.remove()
 				richView.destroy()
 				reRichView.destroy()
 				richHost.remove()

package/docs/steps/selftest-perf.html

@@ -28,11 +28,78 @@
 			// 拾取用的节点：线路只挂在前面 8000 个节点上，取后面的才不会被线抢走命中
 			const clearPoint = 15000
 			try {
-				const { createGisView: createGisViewRaw, QUALITY_LEVELS, QUALITY_MODES, createQualityGovernor, normalizeQualityOptions } = await import('../../src/gis-view/index.js')
-				// 性能断言是照「优化档」（限数 + 避让）测的老口径：统一带上 labelOptimize: true
-				const createGisView = (host, options = {}) => createGisViewRaw(host, { labelOptimize: true, ...options })
-
-				/* ---------------- 档位表与归一（纯函数） ---------------- */
+				const { createGisView: createGisViewRaw, QUALITY_LEVELS, QUALITY_MODES, createQualityGovernor, normalizeQualityOptions } = await import('../../src/gis-view/index.js')
+				const { normalizePointCluster, pointClusterZoomActive } = await import('../../src/gis-view/cluster.js')
+				const { createHeatmap } = await import('../../src/gis-view/heatmap.js')
+				const { normalizeDensity, renderDensityField } = await import('../../src/gis-view/density.js')
+				const clusterDefault = normalizePointCluster(true)
+				const clusterClamped = normalizePointCluster({ enabled: true, radius: 2, minPoints: 1, maxZoom: -3 })
+				check('点聚合：true 用缺省档（半径 60 / 最少 2 点 / 不限缩放）',
+					clusterDefault.enabled && clusterDefault.radius === 60 && clusterDefault.minPoints === 2 && clusterDefault.maxZoom === 0,
+					JSON.stringify(clusterDefault))
+				check('点聚合：半径 / 最少点数 / maxZoom 都夹到可用区间', clusterClamped.radius === 8 && clusterClamped.minPoints === 2 && clusterClamped.maxZoom === 0,
+					JSON.stringify(clusterClamped))
+				check('点聚合：maxZoom 按相机比例 / 基准比例判定，超过后展开',
+					pointClusterZoomActive({ enabled: true, maxZoom: 2 }, 1.5, 1) === true && pointClusterZoomActive({ enabled: true, maxZoom: 2 }, 2.1, 1) === false,
+					'1.5× 聚合 / 2.1× 展开')
+				// 性能断言是照「优化档」（限数 + 避让）测的老口径：统一带上 labelOptimize: true
+				const createGisView = (host, options = {}) => createGisViewRaw(host, { labelOptimize: true, ...options })
+				/* ---------------- 热力图语义键：只改密度画法不重采要素 ---------------- */
+				let semanticHeatmapOption = {
+					enabled: true,
+					field: 'value',
+					targets: ['point', 'line'],
+					domain: [0, 100],
+					colors: ['#0b3d91', '#ffd166', '#ff5e5e'],
+					density: { opacity: 1, layer: 'below', radius: 24 }
+				}
+				const semanticHeatmap = createHeatmap(() => semanticHeatmapOption, () => [])
+				const styleKeyBefore = semanticHeatmap.styleKey()
+				const weightKeyBefore = semanticHeatmap.weightKey()
+				semanticHeatmapOption = {
+					...semanticHeatmapOption,
+					density: { ...semanticHeatmapOption.density, opacity: 0.25, layer: 'top', radius: 40 }
+				}
+				check('热力图语义键：只改 density 的透明度 / 画层 / 核半径，样式键与权重键都不变',
+					semanticHeatmap.styleKey() === styleKeyBefore && semanticHeatmap.weightKey() === weightKeyBefore)
+				const densityOnlyStyleKey = semanticHeatmap.styleKey()
+				const densityOnlyWeightKey = semanticHeatmap.weightKey()
+				semanticHeatmapOption = { ...semanticHeatmapOption, colors: ['#123456', '#7ce0b0', '#ff8a3d'] }
+				check('热力图语义键：换色带只改样式键，权重键保持不动',
+					semanticHeatmap.styleKey() !== densityOnlyStyleKey && semanticHeatmap.weightKey() === densityOnlyWeightKey)
+				const colorWeightKey = semanticHeatmap.weightKey()
+				semanticHeatmapOption = { ...semanticHeatmapOption, field: 'score' }
+				check('热力图语义键：换取值字段时两个键都变（密度场要重新采样）',
+					semanticHeatmap.weightKey() !== colorWeightKey && semanticHeatmap.styleKey() !== densityOnlyStyleKey)
+
+				/* ---------------- 热力图密度场：透明边缘的 RGB 预乘 alpha ---------------- */
+				const premultOptions = normalizeDensity({ style: 'smooth', max: 1, radius: 6, resolution: 64, threshold: 0, core: 0 })
+				const premultPalette = {
+					bands: [[1, 0, 0, 1]],
+					smooth: [[1, 0, 0, 1], [1, 0, 0, 1]],
+					core: null
+				}
+				const premultField = renderDensityField([{ x: 0, y: 0, ratio: 1 }], premultOptions, premultPalette)
+				let premultPartial = 0
+				let premultBad = 0
+				if (premultField) {
+					for (let offset = 0; offset < premultField.pixels.length; offset += 4) {
+						const alpha = premultField.pixels[offset + 3]
+						if (alpha === 0 || alpha === 255) {
+							continue
+						}
+						premultPartial += 1
+						// 纯红色带：预乘后 R 应与 A 同值、G/B 都还是 0；旧实现固定写 R=255，透明边缘会发灰。
+						if (premultField.pixels[offset] !== alpha || premultField.pixels[offset + 1] !== 0 || premultField.pixels[offset + 2] !== 0) {
+							premultBad += 1
+						}
+					}
+				}
+				check('热力图密度场：透明边缘的 RGB 已预乘（R 跟 A 同降、G/B 为 0，不再留灰边）',
+					Boolean(premultField) && premultPartial > 0 && premultBad === 0,
+					`${premultField?.width ?? 0}×${premultField?.height ?? 0} / 半透明 ${premultPartial} 格 / 未预乘 ${premultBad} 格`)
+
+				/* ---------------- 档位表与归一（纯函数） ---------------- */
 				check('QUALITY_MODES 是五档：四个固定档 + auto', QUALITY_MODES.join(',') === 'high,balanced,lean,fast,auto', QUALITY_MODES.join(','))
 				check('QUALITY_LEVELS 从高到低，越往下省得越多', QUALITY_LEVELS.length === 4 &&
 					QUALITY_LEVELS[0].glow && QUALITY_LEVELS[0].ornament && QUALITY_LEVELS[0].scale === 1 &&
@@ -81,6 +148,28 @@
 				fixed.sample(50)
 				check('固定档不受帧耗时影响', fixed.state().name === 'balanced' && fixed.state().glow === false && fixed.state().scale === 1, `${fixed.state().name} glow=${fixed.state().glow}`)
 
+				/* ---------------- 视口可见性：离开视口停动画，回来再续 ---------------- */
+				const visibilityHost = document.createElement('div')
+				visibilityHost.style.cssText = 'position:fixed;left:-10000px;top:0;width:320px;height:200px'
+				document.body.append(visibilityHost)
+				const visibilityView = createGisView(visibilityHost, {
+					points: [{ id: 'visibility-point', x: 0, y: 0 }],
+					lines: [],
+					effects: { point: { radius: 16, period: 1.5, count: 1 } },
+					showGrid: false
+				})
+				visibilityView.fitView()
+				await sleep(260)
+				const hiddenAnimating = visibilityView.getStats().animating
+				visibilityHost.style.left = '0px'
+				await sleep(260)
+				const shownAnimating = visibilityView.getStats().animating
+				check('画布离开视口时连续动画停住，回到视口后再继续',
+					hiddenAnimating === false && shownAnimating === true,
+					`视口外 animating=${hiddenAnimating} / 视口内 animating=${shownAnimating}`)
+				visibilityView.destroy()
+				visibilityHost.remove()
+
 				/* ---------------- 大数据密集档：手动开关 / auto 阈值 / 效果恢复 ---------------- */
 				const denseHost = document.createElement('div')
 				denseHost.style.cssText = 'width:420px;height:280px'
@@ -1189,10 +1278,63 @@
 				const heatFreshView = createGisView(heatFreshHost, { points: heatPoints, lines: heatLines, heatmap: heatB, width: 640, height: 380, quality: 'high' })
 				heatFreshView.setCamera({ center: [320, 200], scale: 1 })
 				const heatFreshText = JSON.stringify(heatFreshView.snapshotScene())
-				check('样式快路径：同一份热力图配置原样再发一次，值域按当前数据重算（与整份重建一致）',
-					heatRefreshedText !== heatAfter && heatRefreshedText === heatFreshText,
-					heatRefreshedText === heatFreshText ? `快照 ${heatRefreshedText.length} 字节，逐字段一致` : diffText(heatRefreshedText, heatFreshText))
-				heatFreshView.destroy()
+				check('样式快路径：同一份热力图配置原样再发一次，值域按当前数据重算（与整份重建一致）',
+					heatRefreshedText !== heatAfter && heatRefreshedText === heatFreshText,
+					heatRefreshedText === heatFreshText ? `快照 ${heatRefreshedText.length} 字节，逐字段一致` : diffText(heatRefreshedText, heatFreshText))
+				// 密度场：只改 opacity 时复用上一份采样与贴图；换色带 / 换要素值才重烤。
+				// 判断重烤用 heatDensityStats 的对象身份：只改画法那条快路不会换它。
+				const densityOption = {
+					enabled: true,
+					field: 'value',
+					targets: ['point'],
+					domain: [0, 100],
+					colors: ['#0b3d91', '#ffd166', '#ff5e5e'],
+					density: { opacity: 1, radius: 22, resolution: 192, levels: 8 }
+				}
+				const densityHost = document.createElement('div')
+				document.querySelector('#map').append(densityHost)
+				const densityView = createGisView(densityHost, {
+					points: heatPoints,
+					lines: [],
+					heatmap: densityOption,
+					width: 640,
+					height: 380,
+					quality: 'high',
+					showGrid: false,
+					background: null
+				})
+				densityView.fitView()
+				await densityView.whenRendered()
+				await densityView.whenRendered()
+				const densityFirst = densityView.getStats().heatDensity
+				check('热力图密度场：首帧烤出有效场（有采样数、贴图尺寸非零）',
+					Boolean(densityFirst) && densityFirst.samples > 0 && densityFirst.width > 0 && densityFirst.height > 0,
+					JSON.stringify(densityFirst))
+				const opacityOption = { ...densityOption, density: { ...densityOption.density, opacity: 0.35 } }
+				const opacityStarted = now()
+				densityView.updateOptions({ heatmap: opacityOption })
+				const opacityUpdateMs = now() - opacityStarted
+				await densityView.whenRendered()
+				const densityAfterOpacity = densityView.getStats().heatDensity
+				check('热力图密度场：只改 density.opacity 不重采、不重烤（复用同一份烘焙读数）',
+					densityAfterOpacity === densityFirst)
+				const colorOption = { ...opacityOption, colors: ['#123456', '#7ce0b0', '#ff8a3d'] }
+				const colorStarted = now()
+				densityView.updateOptions({ heatmap: colorOption })
+				const colorUpdateMs = now() - colorStarted
+				await densityView.whenRendered()
+				const densityAfterColor = densityView.getStats().heatDensity
+				check('热力图密度场：换色带会重烤（生成新一份烘焙读数）',
+					densityAfterColor !== densityAfterOpacity && densityAfterColor.samples === densityAfterOpacity.samples)
+				densityView.updatePoint('h0', { value: 7 })
+				await densityView.whenRendered()
+				const densityAfterPoint = densityView.getStats().heatDensity
+				check('热力图密度场：定向 updatePoint 改要素值后场跟着重烤（不再停在旧数据上）',
+					densityAfterPoint !== densityAfterColor && densityAfterPoint.samples === densityAfterColor.samples)
+				diag('热力图密度场更新', `纯透明度 ${opacityUpdateMs.toFixed(2)} ms / 换色带 ${colorUpdateMs.toFixed(2)} ms；烘焙 ${densityAfterColor.ms.toFixed(1)} ms`)
+				densityView.destroy()
+				densityHost.remove()
+				heatFreshView.destroy()
 				heatFreshHost.remove()
 				heatView.destroy()
 				heatHost.remove()
@@ -1669,16 +1811,18 @@
 				document.body.appendChild(thinHost)
 				const thinPoints = Array.from({ length: 12 }, (unused, index) => ({ id: `tp-${index}`, x: index * 10, y: index % 3 * 6, name: `小点 ${index}` }))
 				const thinLines = thinPoints.slice(1).map((point, index) => ({ id: `tl-${index}`, from: thinPoints[index].id, to: point.id }))
-				const thinView = createGisView(thinHost, {
+				const thinView = createGisView(thinHost, {
 					points: thinPoints,
 					lines: thinLines,
 					pointStyle: { size: 6 },
 					lineStyle: { width: 1 },
 					fitPadding: 20,
 					// 交互期的那几条读数（细线快路径 / 后备缓冲）靠拖动触发：平移显式打开
-					features: { pan: true }
-				})
-				await sleep(400)
+					features: { pan: true }
+				})
+				// 页面底部的临时画布先滚进视口：动画与交互帧只在可见时连续推进
+				thinHost.scrollIntoView({ block: 'center', inline: 'nearest' })
+				await sleep(400)
 				const thinCanvas = thinHost.querySelector('canvas')
 				const thinPointerId = 91
 				const fireThin = (type, at) => thinCanvas.dispatchEvent(new PointerEvent(type, {
@@ -1820,15 +1964,17 @@
 					channelLines.push({ id: `cm-${index}`, from: 'p1', to: 'p2' })
 					channelLineIds.push(`cm-${index}`)
 				}
-				const channelView = createGisView(channelHost, {
+				const channelView = createGisView(channelHost, {
 					points: channelPoints,
 					lines: channelLines,
 					channels: [{ id: 'ch-cost', from: 'p1', to: 'p2', lineIds: channelLineIds, path: [[100, 30]] }],
 					fitPadding: 20,
-					waypointEditable: true
-				})
+					waypointEditable: true
+				})
 				channelView.selectFeatures('cm-0')
-				await sleep(200)
+				// 拐点拖动靠真实指针命中：先把这张临时画布滚进视口，别让命中坐标落在视口外
+				channelHost.scrollIntoView({ block: 'center', inline: 'nearest' })
+				await sleep(200)
 				const channelCanvas = channelHost.querySelector('canvas')
 				const channelWaypoint = channelView.getWaypoints(0).find(item => item.pathIndex === 1)
 				const channelSkeletonBefore = channelView.getChannelGroups('ch-cost')[0].skeleton.map(coordinate => coordinate[0])
@@ -1903,9 +2049,136 @@
 				const goCostBest = Math.min(...goCostMerge)
 				diag('分组编辑（2 万回线、只写 groups 的通道，合并一次）', `最快 ${goCostBest.toFixed(1)} ms`)
 				check('2 万回线的通道合并分组：40 ms 以内（成员池一次建表 + 集合去重，老的逐条 includes 是平方级）', goCostBest < 40, `最快 ${goCostBest.toFixed(1)} ms`)
-				check('只写 groups 的通道合并之后成员一条不少（2 万条只走声明，不靠顶层 lineIds）', goCostMergedLines === goCostCount, `${goCostMergedLines} / ${goCostCount}`)
-
-				thinView.destroy()
+				check('只写 groups 的通道合并之后成员一条不少（2 万条只走声明，不靠顶层 lineIds）', goCostMergedLines === goCostCount, `${goCostMergedLines} / ${goCostCount}`)
+
+				/* ---------------- 点聚合：展示成员、拾取、点击语义与 maxZoom ---------------- */
+				const clusterPointCount = 12000
+				const clusterRandom = (() => {
+					let seed = 20261021
+					return () => {
+						seed = (seed * 1664525 + 1013904223) % 4294967296
+						return seed / 4294967296
+					}
+				})()
+				const clusterCenters = [[0, 0], [120, 0], [60, 90]]
+				// 留出几个远离簇中心的点，覆盖 getClusters() 的单成员分支；它们仍计入总点数。
+				const clusterIsolated = [
+					[-360, -170], [380, -170], [-360, 200], [380, 200],
+					[-440, 20], [460, 20], [20, -220], [20, 240]
+				]
+				const clusterPoints = new Array(clusterPointCount)
+				for (let index = 0; index < clusterPointCount; index += 1) {
+					const isolatedIndex = index - (clusterPointCount - clusterIsolated.length)
+					if (isolatedIndex >= 0) {
+						clusterPoints[index] = {
+							id: `cp${index}`,
+							x: clusterIsolated[isolatedIndex][0],
+							y: clusterIsolated[isolatedIndex][1],
+							name: `独立点 ${index}`
+						}
+						continue
+					}
+					const center = clusterCenters[index % clusterCenters.length]
+					clusterPoints[index] = {
+						id: `cp${index}`,
+						x: center[0] + (clusterRandom() - 0.5) * 24,
+						y: center[1] + (clusterRandom() - 0.5) * 24,
+						name: `聚合点 ${index}`
+					}
+				}
+				const clusterHost = document.createElement('div')
+				clusterHost.style.cssText = 'width:640px;height:380px'
+				document.body.appendChild(clusterHost)
+				let clusterEvents = 0
+				let plainEvents = 0
+				let lastClusterPayload = null
+				const clusterView = createGisView(clusterHost, {
+					points: clusterPoints,
+					width: 640,
+					height: 380,
+					pointStyle: { size: 4 },
+					features: 'view',
+					fitPadding: 24,
+					pointCluster: { enabled: true, radius: 60, minPoints: 2 }
+				})
+				clusterView.on('clusterClick', payload => {
+					clusterEvents += 1
+					lastClusterPayload = payload
+				})
+				clusterView.on('click', () => {
+					plainEvents += 1
+				})
+				await clusterView.whenRendered()
+				const clusterStats = clusterView.getStats()
+				check('点聚合：一万二千点建出多成员圆，统计口径自洽',
+					clusterStats.clusterCount > 0 && clusterStats.clusterPointCount >= clusterStats.clusterCount && clusterStats.clusterMs >= 0,
+					JSON.stringify({ clusterCount: clusterStats.clusterCount, clusterPointCount: clusterStats.clusterPointCount, clusterMs: clusterStats.clusterMs }))
+				check('点聚合：getPointCluster() 给出归一化配置与 active',
+					clusterView.getPointCluster()?.active === true && clusterView.getPointCluster()?.radius === 60,
+					JSON.stringify(clusterView.getPointCluster()))
+				const clusterGroups = clusterView.getClusters()
+				const multiClusters = clusterGroups.filter(item => item.count > 1)
+				const singletonGroups = clusterGroups.filter(item => item.count === 1)
+				check('点聚合：getClusters() 含单成员，单成员 count=1、多成员 id 以 cluster: 开头',
+					singletonGroups.length > 0 && multiClusters.length > 0 && singletonGroups.every(item => item.count === 1 && item.pointIndexes.length === 1) && multiClusters.every(item => item.id.startsWith('cluster:')),
+					`${clusterGroups.length} 组（${singletonGroups.length} 单成员 / ${multiClusters.length} 多成员）`)
+				check('点聚合：原始数据与 getData() 一条不少',
+					clusterView.getData().points.length === clusterPointCount && clusterView.listPoints({ visibleOnly: false }).length === clusterPointCount,
+					`getData ${clusterView.getData().points.length} / listPoints ${clusterView.listPoints({ visibleOnly: false }).length}`)
+				const visibleSingletons = clusterView.listPoints({ visibleOnly: true })
+				let visitedSingletons = 0
+				clusterView.forEachPointInView(clusterView.getViewRect(), () => {
+					visitedSingletons += 1
+				})
+				check('点聚合：聚合内部成员不出现在 visibleOnly / forEachPointInView',
+					visibleSingletons.length === clusterPointCount - clusterStats.clusterPointCount && visitedSingletons === visibleSingletons.length,
+					`可见 ${visibleSingletons.length} / 遍历 ${visitedSingletons} / 隐藏 ${clusterStats.clusterPointCount}`)
+				const clusterPick = clusterView.pick(multiClusters[0].screen[0], multiClusters[0].screen[1])
+				check('点聚合：聚合圆拾取返回 type=cluster，带 count / pointIds / bounds',
+					clusterPick?.type === 'cluster' && clusterPick.count >= 2 && clusterPick.pointIds.length === clusterPick.count && Boolean(clusterPick.bounds),
+					JSON.stringify({ type: clusterPick?.type, count: clusterPick?.count, ids: clusterPick?.pointIds?.length }))
+				const selectionProbe = visibleSingletons[0]
+				clusterView.selectFeatures([selectionProbe.item.id])
+				await clusterView.whenRendered()
+				const selectedBefore = clusterView.getSelections().map(entry => entry.item?.id ?? entry.index).join(',')
+				const clusterCanvas = clusterHost.querySelector('canvas')
+				// 合成指针事件使用真实客户端坐标：先把画布滚进视口，避免 clientY 落在窗口外
+				clusterCanvas.scrollIntoView({ block: 'center' })
+				await sleep(50)
+				const clickPick = clusterView.pick(multiClusters[0].screen[0], multiClusters[0].screen[1])
+				const clickScreen = clickPick?.screen ?? multiClusters[0].screen
+				const clickClient = clusterView.screenToClient(clickScreen[0], clickScreen[1])
+				const fireCluster = type => clusterCanvas.dispatchEvent(new PointerEvent(type, {
+					bubbles: true, cancelable: true, pointerId: 93, pointerType: 'mouse', button: 0,
+					buttons: type === 'pointerup' ? 0 : 1, clientX: clickClient[0], clientY: clickClient[1]
+				}))
+				fireCluster('pointerdown')
+				fireCluster('pointerup')
+				await sleep(30)
+				const selectedAfter = clusterView.getSelections().map(entry => entry.item?.id ?? entry.index).join(',')
+				check('点聚合：点击聚合只发 clusterClick，不发普通 click，选中集不变',
+					clusterEvents === 1 && plainEvents === 0 && selectedAfter === selectedBefore && lastClusterPayload?.action?.type === 'clusterClick' && lastClusterPayload?.action?.data?.type === 'cluster',
+					`clusterClick=${clusterEvents} click=${plainEvents} 选中 ${selectedBefore} → ${selectedAfter} action=${lastClusterPayload?.action?.type} clickPick=${clickPick?.type ?? 'null'} clickScreen=${clickScreen.map(value => value.toFixed(1)).join(',')} client=${clickClient.map(value => value.toFixed(1)).join(',')}`)
+				const fitScale = clusterView.getCamera().scale
+				clusterView.updateOptions({ pointCluster: { enabled: true, radius: 60, minPoints: 2, maxZoom: 2 } })
+				clusterView.setCamera({ scale: fitScale * 3 })
+				await clusterView.whenRendered()
+				const zoomedStats = clusterView.getStats()
+				check('点聚合：缩放超过 maxZoom 后展开原始点（active=false、聚合圆清空）',
+					clusterView.getPointCluster()?.active === false && zoomedStats.clusterCount === 0 && clusterView.listPoints({ visibleOnly: true }).length === clusterPointCount,
+					JSON.stringify({ active: clusterView.getPointCluster()?.active, clusterCount: zoomedStats.clusterCount, visible: clusterView.listPoints({ visibleOnly: true }).length }))
+				clusterView.setCamera({ scale: fitScale })
+				await clusterView.whenRendered()
+				clusterView.updateOptions({ pointCluster: false })
+				await clusterView.whenRendered()
+				const disabledStats = clusterView.getStats()
+				check('点聚合：关掉之后原始点全部恢复，getPointCluster().enabled=false',
+					clusterView.getPointCluster()?.enabled === false && clusterView.getPointCluster()?.active === false && disabledStats.clusterCount === 0 && disabledStats.clusterPointCount === 0,
+					JSON.stringify({ cluster: clusterView.getPointCluster(), stats: { count: disabledStats.clusterCount, points: disabledStats.clusterPointCount } }))
+				clusterView.destroy()
+				clusterHost.remove()
+
+				thinView.destroy()
 				thinHost.remove()
 				big.destroy()
 				bigHost.remove()

package/docs/steps/selftest-scale.html

@@ -123,6 +123,7 @@
 				const plainView = createGisView(host(320, 200), {
 					points: [{ id: 'p0', x: 0, y: 0 }, { id: 'p1', x: 40, y: 0 }],
 					lines: [{ id: 'pl0', from: 'p0', to: 'p1', start: [-20, -20], end: [60, -20] }],
+					lineFollowsNode: false,
 					filterWorker: false
 				})
 				await settle()
@@ -132,8 +133,8 @@
 					`首顶点 ${JSON.stringify(firstVertex())}`)
 				plainView.updatePoint('p0', { visible: false })
 				await settle()
-				check('无筛选：visible: false 的节点当场退场（绑定线的端点退回自身坐标）',
-					plainView.isPointVisible(0) === false && firstVertex()?.[0] === -20,
+				check('无筛选：lineFollowsNode: false 时 visible: false 只收起节点，绑定线停在最后坐标',
+					plainView.isPointVisible(0) === false && firstVertex()?.[0] === 0,
 					`首顶点 ${JSON.stringify(firstVertex())}`)
 				plainView.updatePoint('p0', { visible: true })
 				await settle()
@@ -776,36 +777,58 @@
 				const claimPath = claimView.getLine('cl')?.path
 				check('追加被线路按 id 认领的节点：回落整份重建，线跟着出来', claimPath?.length === 2 && Math.abs(claimPath[1][0] - 200) < 0.5 && claimView.getStats().pointCount === 3, `${claimPath?.length} 个顶点 / ${claimView.getStats().pointCount} 个点`)
 				claimView.destroy()
-				/* 自适应比例（zoomScaleAuto）与重定基准（setZoomBaseScale）：包围盒 / 比例一变，节点与通道间距一起变 */
-				const autoView = createGisView(host(640, 320), {
-					points: [{ id: 'z0', x: 0, y: 0, size: 10 }, { id: 'z1', x: 600, y: 0, size: 10 }],
-					lines: [{ id: 'zl', from: 'z0', to: 'z1', width: 2 }],
-					zoomScaleAuto: true,
-					showGrid: false
-				})
+				/* 适应视图的节点间距（fitSpacing）：远处孤立点撑大包围盒时，按最近可见节点中心距反推比例 */
+				const spacingPoints = [
+					{ id: 'f0', x: 0, y: 0, size: 10 },
+					{ id: 'f0b', x: 0, y: 0, size: 10 },
+					{ id: 'f1', x: 60, y: 0, size: 10 },
+					{ id: 'f2', x: 200, y: 0, size: 10 },
+					{ id: 'f3', x: 0, y: 200, size: 10 },
+					{ id: 'fx', x: 10000, y: 10000, size: 10 }
+				]
+				const fitSpacingBaseView = createGisView(host(640, 320), { points: spacingPoints, showGrid: false })
+				const spacingView = createGisView(host(640, 320), { points: spacingPoints, fitSpacing: { minDistance: 24, maxZoom: 0 }, showGrid: false })
 				await settle(140)
-				const autoFit = autoView.getCamera().scale
-				const autoSizeFit = autoView.snapshotScene({ background: false }).points[0]?.size ?? 0
-				check('自适应比例：开关写进 getOptions（面板回显读得到）', autoView.getOptions().zoomScaleAuto === true, String(autoView.getOptions().zoomScaleAuto))
-				check('自适应比例：联动基准缺省取首次适应视图时的比例', Math.abs(autoView.getZoomBaseScale() - autoFit) < 1e-9, `基准 ${autoView.getZoomBaseScale()} / 相机 ${autoFit}`)
-				autoView.setCamera({ scale: autoFit * 2, center: [0, 0] })
-				await settle(60)
-				const autoSizeZoom = autoView.snapshotScene({ background: false }).points[0]?.size ?? 0
-				check('自适应比例：相机放大 2 倍，节点绘制尺寸跟着翻倍（没写 pointZoomScale 时按 1 算）', Math.abs(autoSizeZoom - autoSizeFit * 2) < 0.02, `${autoSizeFit} → ${autoSizeZoom}`)
-				autoView.setZoomBaseScale()
+				const plainFit = fitSpacingBaseView.getCamera().scale
+				const spacingFit = spacingView.getCamera().scale
+				check('适应节点间距：配置写进 getOptions（面板回显读得到）', spacingView.getOptions().fitSpacing?.minDistance === 24, JSON.stringify(spacingView.getOptions().fitSpacing))
+				check('适应节点间距：远处孤立点撑大包围盒后仍提高比例（重合点不算最近距离）', spacingFit > plainFit * 5, `${plainFit} → ${spacingFit}`)
+				const spacingCenter = spacingView.getCamera().center
+				check('适应节点间距：相机保持在普通适应的包围盒中心', Math.abs(spacingCenter[0] - 5000) < 0.5 && Math.abs(spacingCenter[1] - 5000) < 0.5, JSON.stringify(spacingCenter))
+				const spacingViewport = spacingView.getViewport()
+				const spacingCenterScreen = spacingView.project(5000, 5000)
+				check('适应节点间距：放大围绕普通适应中心发生，不跳到最近节点对', Math.abs(spacingCenterScreen[0] - spacingViewport.cssWidth / 2) < 0.1 && Math.abs(spacingCenterScreen[1] - spacingViewport.cssHeight / 2) < 0.1, JSON.stringify(spacingCenterScreen))
+				const spacingScreen0 = spacingView.project(0, 0)
+				const spacingScreen1 = spacingView.project(60, 0)
+				const spacingScreen = Math.hypot(spacingScreen1[0] - spacingScreen0[0], spacingScreen1[1] - spacingScreen0[1])
+				check('适应节点间距：最近节点中心距达到 minDistance（CSS 像素）', Math.abs(spacingScreen - 24) < 0.1, String(spacingScreen))
+				spacingView.updateOptions({ fitSpacing: { minDistance: 24, maxZoom: 2 } })
+				spacingView.fitView()
 				await settle(60)
-				const autoSizeBased = autoView.snapshotScene({ background: false }).points[0]?.size ?? 0
-				check('重定基准：不传参数取当下相机比例，比例系数回到 1（节点回到原样大小）', Math.abs(autoView.getZoomBaseScale() - autoFit * 2) < 1e-9 && Math.abs(autoSizeBased - autoSizeFit) < 0.02, `基准 ${autoView.getZoomBaseScale()} / ${autoSizeZoom} → ${autoSizeBased}`)
-				autoView.updateOptions({ pointZoomScale: 0 })
-				autoView.setCamera({ scale: autoFit, center: [0, 0] })
+				const spacingCapped = spacingView.getCamera().scale
+				check('适应节点间距：maxZoom 限制相对普通适应比例的上限', Math.abs(spacingCapped - plainFit * 2) < 1e-6, `${plainFit} → ${spacingCapped}`)
+				spacingView.updateOptions({ fitSpacing: false })
+				spacingView.fitView()
 				await settle(60)
-				const autoSizeExplicit = autoView.snapshotScene({ background: false }).points[0]?.size ?? 0
-				check('自适应比例：显式写过指数就以显式值为准（写 0 即这一项不跟随）', Math.abs(autoSizeExplicit - autoSizeFit) < 0.02, `${autoSizeFit} / ${autoSizeExplicit}`)
-				autoView.updateOptions({ zoomScaleAuto: false })
-				autoView.setCamera({ scale: autoFit * 2, center: [0, 0] })
-				await settle(60)
-				check('自适应比例：关掉开关之后节点尺寸不再跟随（比例只按显式指数算）', Math.abs((autoView.snapshotScene({ background: false }).points[0]?.size ?? 0) - autoSizeFit) < 0.02, String(autoView.snapshotScene({ background: false }).points[0]?.size))
-				autoView.destroy()
+				const spacingOff = spacingView.getCamera()
+				check('适应节点间距：关闭后恢复普通适应比例与包围盒中心', Math.abs(spacingOff.scale - plainFit) < 1e-9 && Math.abs(spacingOff.center[0] - 5000) < 0.5, `${spacingCapped} → ${spacingOff.scale} / ${JSON.stringify(spacingOff.center)}`)
+				/* 规则网格里最近距离满地都是：比例仍按最近距离算，相机中心继续沿用普通适应的包围盒中心 */
+				const gridPoints = []
+				for (let row = 0; row < 5; row += 1) {
+					for (let column = 0; column < 5; column += 1) {
+						gridPoints.push({ id: `g${column}_${row}`, x: column * 10, y: row * 10, size: 10 })
+					}
+				}
+				gridPoints.push({ id: 'gx', x: 10000, y: 10000, size: 10 })
+				const gridSpacingView = createGisView(host(640, 320), { points: gridPoints, fitSpacing: { minDistance: 24, maxZoom: 0 }, showGrid: false })
+				await settle(140)
+				const gridCenter = gridSpacingView.getCamera().center
+				check('适应节点间距：最近距离并列时只调整比例，相机仍停在普通适应中心',
+					Math.abs(gridCenter[0] - 5000) <= 0.5 && Math.abs(gridCenter[1] - 5000) <= 0.5,
+					JSON.stringify(gridCenter))
+				gridSpacingView.destroy()
+				fitSpacingBaseView.destroy()
+				spacingView.destroy()
 			}
 			catch (error) {
 				check('页面没有抛错', false, String(error && error.stack ? error.stack : error).split('\n').slice(0, 3).join(' | '))

package/docs/steps/step-10-full.js

@@ -76,7 +76,7 @@ export const createFullView = (target, options = {}) => {
 		draggable: true,
 		boxSelect: true,
 		waypointEditable: true,
-		features: { pan: true, zoom: true, hover: true, select: true, contextMenu: true, keyboard: true, channelDraft: true, channelMenu: true },
+		features: { pan: true, zoom: true, hover: true, select: true, contextMenu: true, keyboard: true, channelDraft: true },
 		// 组件的回调都带载荷：type / index / item 就是「当前是哪个元素」，world 是光标处的世界坐标
 		onHover: payload => forward.onHover?.(payload),
 		onClick: payload => forward.onClick?.(payload),

package/docs/steps/step-12-events.js

@@ -119,7 +119,7 @@ export const createActionView = (target, options = {}) => {
 		draggable: true,
 		boxSelect: true,
 		waypointEditable: true,
-		features: { pan: true, zoom: true, hover: true, select: true, contextMenu: true, keyboard: true, channelDraft: true, channelMenu: true },
+		features: { pan: true, zoom: true, hover: true, select: true, contextMenu: true, keyboard: true, channelDraft: true },
 		// 下面五条是同一条路：每个回调先报一句判读，再交给页面自己那一条（日志、草稿读数都还在）
 		onPointerDown: (payload, event) => {
 			report(describeAction(payload, '按下'))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gis-view-webgl2",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "WebGL2 矢量视图：点、线与 GeoJSON / 图片背景层，无内置界面，点击 / 双击 / 拖拽可配置",
   "type": "module",
   "scripts": {