dsh-data-domain-knowledge 0.1.0-alpha.2 → 0.1.0-alpha.3

package/src/client/attribution/AttributionGraph.tsx

@@ -1,8 +1,14 @@
 import { Graph } from '@antv/g6'
-import { useEffect, useRef, useState, type ReactNode } from 'react'
-import { buildGraphOptions, seedPositions, toGraphData, type GraphLayout, type StageMode } from './graph-options.ts'
+import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
 import { cn } from '@tita-data-agent/ui/components'
-import type { AttributionGraphData } from './model.ts'
+import {
+  buildGraphOptions, laneGuides, laneLayoutOf, laneMetricsFor, seedPositions, toGraphData,
+  type GraphLayout, type LaneGeometry, type StageMode,
+} from './graph-options.ts'
+import {
+  chainOf, chainStartAllowed, laneBandsOf, laneSegments,
+  type AttributionGraphData, type LaneId, type LaneSegment,
+} from './model.ts'
 
 export interface AttributionGraphProps {
   data: AttributionGraphData
@@ -10,76 +16,253 @@ export interface AttributionGraphProps {
   gapIds: ReadonlySet<string>
   /**
    * 布局方向。**它随视图模式变**，不是用户偏好：
-   * 承载面板的右侧边栏只有 380px（宿主 `width:380px`），所以布局的长宽比必须
+   * 承载面板的右侧边栏只有 380px（宿主 `width:380px`），所以关系布局的长宽比必须
    * 配合视口 —— 全景用 LR（竖长，贴住竖屏视口），聚焦用 TB（紧凑，让 7 个节点
-   * 能按接近 1:1 渲染而不是被压成一半）。
+   * 能按接近 1:1 渲染而不是被压成一半）。动线视角忽略它：段位决定一切。
    */
   rankdir: 'LR' | 'TB'
-  /** `force` 浮动节点（默认）；`layered` 分层 DAG。 */
+  /** `line` 动线（默认，五段泳道）；`force` 关系（浮动节点）。 */
   layout: GraphLayout
-  /** 视口参数档位：面板内 / 全屏。决定缩放区间与留白。 */
+  /** 视口参数档位：面板内 / 全屏。决定缩放区间、留白与段位尺寸。 */
   mode: StageMode
+  /** 选中节点：它的那条链被点亮，其余降到 0.35（§7.4 第 9 条）。 */
   selectedId?: string
-  onSelect: (id: string) => void
+  /** 是否展开 ⑤ 段（实例层）。被点亮的链上的实例节点不受它限制。 */
+  includeInstance?: boolean
+  /**
+   * 被用户收起的段（④ 查询依据默认收起）。收起是「有数据但不画」——
+   * 与「这一段是空的」是两件事，段头必须分开说（见 `LaneSegment.collapsed`）。
+   */
+  collapsedLanes?: ReadonlySet<LaneId>
+  /** 点段头收起 / 展开它。 */
+  onToggleLane?: (lane: LaneId) => void
+  /** 被切面关掉的段（`kinds` 里没有这一段的任何一种节点）。 */
+  lanesOff?: ReadonlySet<LaneId>
+  /** ① 段只画这一个现象；其余现象进段头的切换入口。 */
+  focusSymptomId?: string
+  /** 点段头上的现象入口：换到那个现象的动线。 */
+  onPickSymptom?: (id: string) => void
+  onSelect: (id: string | undefined) => void
+  /** 段头读数（每段画了几个 / 一共几个）同步给左栏的段 chip。 */
+  onLaneCounts?: (counts: Record<LaneId, { shown: number; total: number }>) => void
   className?: string
 }
 
 /**
- * G6 v5 画布。
+ * 每一段的底色色相。
+ *
+ * 参照的是配图 `assets/0021-智能归因图谱-动线视角布局.svg`：现象与实例偏琥珀
+ * （同一个问题的两头）、假设偏蓝、检查点偏紫、查询依据中性。段与段因此有分区感，
+ * 而色相不承担语义 —— 语义在段名与节点配色上（避免「蓝到底是哪一段」这种读法）。
+ */
+const LANE_TINT: Record<LaneId, string> = {
+  symptom: 'var(--tita-tone-amber)',
+  hypothesis: 'var(--tita-tone-blue)',
+  check_point: 'var(--tita-tone-violet)',
+  asset: 'var(--tita-ink-faint)',
+  instance: 'var(--tita-tone-amber)',
+}
+
+/** 空集：没有段被收起 / 关掉时的默认值。写成常量是为了它每次渲染都是同一个引用。 */
+const EMPTY_LANES: ReadonlySet<LaneId> = new Set<LaneId>()
+
+/** 五段一条都没有时的初值：段 chip 的数字必须**始终有值**。 */
+const ZERO_COUNTS: Record<LaneId, { shown: number; total: number }> = {
+  symptom: { shown: 0, total: 0 },
+  hypothesis: { shown: 0, total: 0 },
+  check_point: { shown: 0, total: 0 },
+  asset: { shown: 0, total: 0 },
+  instance: { shown: 0, total: 0 },
+}
+
+function countsOf(segments: LaneSegment[]): Record<LaneId, { shown: number; total: number }> {
+  const counts = { ...ZERO_COUNTS }
+  for (const segment of segments) counts[segment.lane.id] = { shown: segment.nodes.length, total: segment.total }
+  return counts
+}
+
+/**
+ * G6 v5 画布 + 动线视角的泳道带。
  *
  * **它铺满父容器，自己不带高度。** 尺寸由父级用 CSS 决定（`absolute inset-0` 或
  * 普通 `h-full`），画布只负责把 `clientWidth/clientHeight` 读出来 —— 这样「图谱占满
  * 整个内容区」是布局层的事，画布不需要知道「面板有多高」这种知识，全屏切换也就
  * 只是父容器换了个尺寸，画布跟着 ResizeObserver 走。
  *
- * 实例策略：**在布局方向、档位或数据变化时重建 Graph，只有选中态变化时才走
- * `setElementState`**。重建一个 20 多节点的图只要几十毫秒，而增量同步布局、
- * 样式、标签的边界情况（G6 会缓存节点位置与 state）远比一次重建更容易出错 ——
- * 这个取舍随图上到几千节点才需要反过来。
+ * 两条关于坐标的硬约束（动线视角的地基）：
+ * 1. **相机锁在 `[0, 0, 1]`**（`buildGraphOptions` 里不给 `autoFit`、给 `zoom: 1`，
+ *    行为里不带 `drag-canvas` / `zoom-canvas`）。世界坐标因此等于屏幕像素，
+ *    叠在画布上的 HTML 泳道带才可能与节点对齐。
+ * 2. **段位由 `laneLayoutOf` 一次性算好**，节点的 `x` / `y` / `size` 直接写进数据，
+ *    G6 那边只给一个「原样采用我给的坐标」的布局。
+ *
+ * 实例策略：**只在布局、档位或数据变化时重建 Graph**；选中态、段展开与尺寸变化都走
+ * 增量（`setElementState` / `updateNodeData` / `setData` + `draw`）。重建一个二十多
+ * 节点的图只要几十毫秒，但每次点节点都重建会让高亮闪一下，还会把关系视图里拖动过的
+ * 位置吹散。
  */
-export function AttributionGraph({ data, gapIds, rankdir, layout, mode, selectedId, onSelect, className }: AttributionGraphProps): ReactNode {
+export function AttributionGraph({
+  data, gapIds, rankdir, layout, mode, selectedId, includeInstance = false, onSelect, onLaneCounts, className,
+  collapsedLanes = EMPTY_LANES,
+  focusSymptomId,
+  onPickSymptom,
+  onToggleLane,
+  lanesOff = EMPTY_LANES
+}: AttributionGraphProps): ReactNode {
   const host = useRef<HTMLDivElement>(null)
   const graphRef = useRef<Graph | null>(null)
   const selectRef = useRef(onSelect)
   selectRef.current = onSelect
+  const countsRef = useRef(onLaneCounts)
+  countsRef.current = onLaneCounts
   const dataRef = useRef(data)
   dataRef.current = data
+  const gapRef = useRef(gapIds)
+  gapRef.current = gapIds
+
+  /** 一条被点亮的链：从现象 / 假设出发，沿有语义方向的边往前走（§7.4 第 9 条）。 */
+  const chainIds = useMemo(() => {
+    if (!selectedId) return undefined
+    const start = data.nodes.find(node => node.id === selectedId)
+    if (!chainStartAllowed(start)) return undefined
+    return chainOf(data, selectedId)
+  }, [data, selectedId])
+
+  /** 要被压暗的元素：链之外的节点，以及两端不都在链上的边。 */
+  const dimmed = useMemo(() => {
+    if (!chainIds) return { nodes: new Set<string>(), edges: new Set<string>() }
+    const edges = new Set<string>()
+    for (const edge of data.edges) {
+      // 边的判据是「**两端都不在链上**」：一端在链上的边恰恰是这条链与外界的关系
+      // （它从这里接出去），压暗它就等于把链的出口抹掉。
+      if (!(chainIds.has(edge.source) || chainIds.has(edge.target))) edges.add(edge.id)
+    }
+    return { nodes: new Set(data.nodes.filter(node => !chainIds.has(node.id)).map(node => node.id)), edges }
+  }, [data, chainIds])
+
+  /** 五段的分段结果。段头读数与泳道带都读它，纯函数所以每次渲染重算即可。 */
+  const segments = useMemo(
+    // 被点亮的那条链上的实例节点在折叠态下仍然画出来（§7.7 末段）。
+    () => laneSegments(data, { includeInstance, collapsedLanes, ...(focusSymptomId ? { focusSymptomId } : {}), ...(chainIds ? { chainIds } : {}) }),
+    [data, includeInstance, chainIds],
+  )
+
+  /** 段头读数同步给左栏。 */
+  useEffect(() => {
+    countsRef.current?.(countsOf(segments))
+  }, [segments])
+
+  const [geometry, setGeometry] = useState<LaneGeometry | undefined>(undefined)
   // 重建之后选中态要重新贴上去：新节点上没有任何 state，只靠 selectedId 的
   // 变化触发不了那个 effect。
-  const [renderToken, setRenderToken] = useState(0)
+  const [renderToken, bumpRender] = useState(0)
+
+  const chainKey = chainIds ? [...chainIds].sort().join(',') : ''
+  /**
+   * 收起态的**内容指纹**。
+   *
+   * `collapsedLanes` 是一个 `Set`，每次渲染都是新对象 —— 直接进依赖数组会让增量
+   * effect 每一帧都跑一遍（重算段位、重下数据、重画）。指纹只认内容。
+   */
+  const collapsedKey = [...collapsedLanes].sort().join(',')
+  // 换一个当前现象 = 换一整条动线，所以要重算段位并重下数据（与收起态同一路）。
+  const focusKey = focusSymptomId ?? ''
+
+  /**
+   * 重建 effect 里要用到「当前的链」与「当前的展开态」，但它们**不该触发重建**
+   * （那是下面两个增量 effect 的事）—— 所以走 ref 读当前值，不进依赖数组。
+   */
+  const chainRef = useRef<ReadonlySet<string> | undefined>(chainIds)
+  chainRef.current = chainIds
+  const includeRef = useRef(includeInstance)
+  includeRef.current = includeInstance
+  const collapsedRef = useRef(collapsedLanes)
+  collapsedRef.current = collapsedLanes
+  const focusRef = useRef(focusSymptomId)
+  focusRef.current = focusSymptomId
+  /**
+   * 重建 effect 已经跑过一轮了吗？
+   *
+   * 下面那个增量 effect 与它挂载时的依赖相同 —— 不挡一下，首帧就会**下发两遍数据、
+   * 画两次**（后一次还会把节点位置重新算一遍）。它只在「段展开 / 高亮链真的变了」
+   * 时才该跑；重建 effect 一开跑就把它压回 false，那一轮的变化由重建自己承担。
+   */
+  const builtRef = useRef(false)
 
   useEffect(() => {
     const el = host.current
     if (!el) return
+    builtRef.current = false
     const measure = (): { width: number; height: number } => ({
       // 兜底尺寸：容器还没被布局出来时（首帧、或宿主面板宽度为 0）先给一个能画的值，
       // 免得 G6 拿到 0 之后整块空白。
       width: el.clientWidth || 348,
       height: el.clientHeight || 360,
     })
+
+    /**
+     * 段位几何。关系视图没有段 —— 但**仍然返回一个几何**：调用方要拿它统一构造
+     * 数据（`laneGeometry` 给了就按段位摆，不给就走 `positions`）。
+     */
+    const computeGeometry = (size: { width: number; height: number }): LaneGeometry | undefined => {
+      if (layout !== 'line') return undefined
+      return laneLayoutOf(
+        laneBandsOf(laneSegments(dataRef.current, {
+          includeInstance: includeRef.current,
+          collapsedLanes: collapsedRef.current,
+          ...(focusRef.current ? { focusSymptomId: focusRef.current } : {}),
+          ...(chainRef.current ? { chainIds: chainRef.current } : {}),
+        })),
+        { width: size.width, height: size.height, mode, viewportHeight: size.height },
+      )
+    }
+
+    const size = measure()
+    const first = computeGeometry(size)
+    const positions = layout === 'line' ? undefined : seedPositions(dataRef.current, size.width, size.height)
     const graph = new Graph({
-      ...buildGraphOptions(measure(), layout, rankdir, mode),
+      ...buildGraphOptions(size, layout, rankdir, mode),
       container: el,
     })
     graphRef.current = graph
+
     graph.on('node:click', event => {
       // G6 的 IEvent 是联合类型，取 id 需要一次窄化；断言限制在这一行内。
       const id = (event as { target?: { id?: string } }).target?.id
       if (id) selectRef.current(id)
     })
-    const size = measure()
-    // 只有力导向才需要喂初始位置：分层布局的坐标由 dagre 算，喂了也会被覆盖。
-    const positions = layout === 'force' ? seedPositions(data, size.width, size.height) : undefined
-    graph.setData(toGraphData(data, { gapIds, ...(positions ? { positions } : {}) }))
-    void graph.render().then(() => setRenderToken(token => token + 1))
+    // 点空白处取消点亮（§7.4 第 9 条）。
+    graph.on('canvas:click', () => selectRef.current(undefined))
+
+    graph.setData(toGraphData(dataRef.current, {
+      layout,
+      gapIds: gapRef.current,
+      ...(positions ? { positions } : {}),
+      ...(first ? { laneGeometry: first, edgeLabels: false } : {}),
+    }))
+    setGeometry(first)
+    void graph.render().then(() => {
+      builtRef.current = true
+      bumpRender(token => token + 1)
+    })
 
     // 宿主面板宽度可被用户拖动，全屏切换也会改变尺寸，画布必须跟着走，
-    // 否则会留下一块空白或裁掉右侧。
+    // 否则会留下一块空白或裁掉右侧。动线视角还要**重算段位**：段位依赖容器宽高
+    // （换行点、垂直居中），只改画布尺寸会让节点与泳道带错开。
     const observed = new ResizeObserver(() => {
       const next = measure()
       if (next.width <= 0 || next.height <= 0) return
+      const [w, h] = graph.getSize()
+      if (Math.abs(w - next.width) < 2 && Math.abs(h - next.height) < 2) return
       graph.setSize(next.width, next.height)
-      void graph.fitView()
+      if (layout !== 'line') {
+        void graph.fitView()
+        return
+      }
+      const lane = computeGeometry(next)
+      if (!lane) return
+      applyPlacements(graph, lane, dataRef.current)
+      setGeometry(lane)
     })
     observed.observe(el)
     return () => {
@@ -87,18 +270,282 @@ export function AttributionGraph({ data, gapIds, rankdir, layout, mode, selected
       graph.destroy()
       graphRef.current = null
     }
-  }, [data, gapIds, rankdir, layout, mode])
+    // 段展开与高亮链由下面两个 effect 负责（它们走增量，不重建）；
+    // 这里只读它们的**当前值**，不跟着重建。
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [data, layout, rankdir, mode])
 
+  /**
+   * 段展开 / 高亮链会让「哪些节点在图上」变化。这是**数据变化**，不能只改状态，
+   * 所以走一次数据下发；坐标复用当前段位算法，不重建 Graph（拖动过位置的
+   * 关系视图不受影响 —— 它本来也不走这条分支）。
+   */
   useEffect(() => {
     const graph = graphRef.current
-    if (!graph || !selectedId) return
-    // 选中节点可能被筛选掉了：G6 的 `setElementState` 对未知 id 是**抛异常**，
-    // 不是静默忽略（`data.getElementType` 里 `throw new Error`）。所以先确认它还在图上。
-    if (!dataRef.current.nodes.some(node => node.id === selectedId)) return
-    void graph.setElementState(selectedId, ['selected'])
-    // 上一个选中节点必须显式取消，否则连着点三个节点会留下三个蓝色描边。
-    return () => { void graph.setElementState(selectedId, []) }
-  }, [selectedId, renderToken])
-
-  return <div ref={host} className={cn('h-full w-full overflow-hidden bg-tita-surface', className)} />
+    const el = host.current
+    // 首轮由重建 effect 已经下发过了（见 `builtRef`）；这里只处理**之后**的变化。
+    if (!builtRef.current || !graph || !el || layout !== 'line') return
+    const size = { width: el.clientWidth || 348, height: el.clientHeight || 360 }
+    const lane = laneLayoutOf(
+      laneBandsOf(laneSegments(dataRef.current, {
+        includeInstance, collapsedLanes,
+        ...(focusSymptomId ? { focusSymptomId } : {}),
+        ...(chainIds ? { chainIds } : {}),
+      })),
+      { width: size.width, height: size.height, mode, viewportHeight: size.height },
+    )
+    graph.setData(toGraphData(dataRef.current, {
+      layout,
+      gapIds: gapRef.current, laneGeometry: lane, edgeLabels: false, includeInstance,
+    }))
+    setGeometry(lane)
+    void graph.draw()
+    // `chainKey` 是 `chainIds` 的内容指纹：Set 每次渲染都是新对象，直接依赖它
+    // 会让这个 effect 每一帧都跑一遍。
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [includeInstance, chainKey, collapsedKey, focusKey, layout, mode])
+
+  /**
+   * 选中态：**只走 `setElementState`，不重建整张图**（§7.4 第 9 条）。
+   *
+   * 三种状态一起下发：链上的节点是 `active`（描边加粗），用户点的那个是 `selected`，
+   * 其余是 `dim`（透明度 0.35）。链之外的边也一起压暗 —— 只淡节点的话，二十几条边
+   * 在暗节点之间仍然亮着，画面会碎成一片。
+   */
+  useEffect(() => {
+    const graph = graphRef.current
+    if (!graph) return
+    const onGraph = new Set(dataRef.current.nodes.map(node => node.id))
+    const states: Record<string, string[]> = {}
+    if (chainIds) {
+      for (const id of chainIds) if (onGraph.has(id)) states[id] = id === selectedId ? ['selected'] : ['active']
+      for (const id of dimmed.nodes) if (onGraph.has(id)) states[id] = ['dim']
+      const edgeIds = new Set(dataRef.current.edges.map(edge => edge.id))
+      for (const id of dimmed.edges) if (edgeIds.has(id)) states[id] = ['dim']
+    } else if (selectedId && onGraph.has(selectedId)) {
+      // 起点不允许点亮（资产 / 检查点 / 失败原因）：仍然给一个选中描边，
+      // 否则用户点了没反应，看起来像坏了。
+      states[selectedId] = ['selected']
+    }
+    if (Object.keys(states).length === 0) return
+    void graph.setElementState(states)
+  }, [chainIds, chainKey, dimmed, selectedId, renderToken])
+
+  return <div className={cn('relative h-full w-full overflow-hidden bg-tita-surface', className)}>
+    {/*
+      三层，顺序就是层叠顺序（都没有 z-index），**每一层的层叠要求正好相反**：
+
+      1. 段底色 —— 必须在节点**下面**。`color-mix()` 出来的是不透明色，排在画布之后
+         会把节点连同标题整片盖住（A/B/C 对照量过：带底色的覆盖层一压上去，
+         胶囊与标题全没了，只剩位置更高的徽标）。
+      2. 画布 —— G6 的容器。**不能给它 `background`**：G6 v5 会把它变成一块铺满的
+         不透明画布，把底下的带子整个盖住（见 `buildGraphOptions` 的注释）。
+      3. 段头 —— 必须在画布**上面**才能收到点击。G6 的容器是铺满的 `absolute inset-0`，
+         谁在 DOM 里靠后谁拿到 `elementFromPoint`。整层 `pointer-events-none`，
+         只有段头那一小条是 `auto`，所以「点节点看链」照旧落到画布上。
+    */}
+    {layout === 'line' && geometry && <LaneTints geometry={geometry} segments={segments} lanesOff={lanesOff} />}
+    <div ref={host} className="absolute inset-0" />
+    {layout === 'line' && geometry && <LaneHeaders
+      geometry={geometry}
+      segments={segments}
+      mode={mode}
+      lanesOff={lanesOff}
+      {...(onToggleLane ? { onToggleLane } : {})}
+      {...(onPickSymptom ? { onPickSymptom } : {})}
+    />}
+  </div>
+}
+
+function LaneTints({ geometry, segments, lanesOff }: {
+  geometry: LaneGeometry
+  segments: LaneSegment[]
+  lanesOff: ReadonlySet<LaneId>
+}): ReactNode {
+  const byId = new Map(segments.map(segment => [segment.lane.id, segment]))
+  return <div
+    data-tita-lane-tints=""
+    className="pointer-events-none absolute inset-0 overflow-hidden"
+    style={{ width: geometry.contentWidth }}
+  >
+    {laneGuides(geometry).map(guide => {
+      const segment = byId.get(guide.laneId as LaneId)
+      if (!segment) return null
+      return <div
+        key={guide.laneId}
+        className="tita-attrBand"
+        data-tita-lane-state={laneStateOf(segment, lanesOff)}
+        style={{
+          position: 'absolute',
+          left: guide.left,
+          top: guide.top,
+          width: guide.width,
+          height: guide.height,
+          // 段的底色走高混合：主题一换，带子跟着走，不需要第二份颜色。
+          // 色相跟着配图（现象琥珀 / 假设蓝 / 检查点紫 / 依据中性 / 实例琥珀）——
+          // 段与段之间因此有分区感，而同色相的两个节点种类本来就在相邻两段。
+          ['--tita-band-tint' as string]: LANE_TINT[segment.lane.id],
+        }}
+      />
+    })}
+  </div>
+}
+
+/**
+ * 段头（段名 / 计数 / 读法 / 现象切换入口）。
+ *
+ * **它与段底色分在两层，因为两者的层叠要求正好相反：**
+ *
+ * - 底色必须在节点**下面** —— 排在画布之后会盖住节点。`color-mix()` 出来的是
+ *   不透明色（5% 色相 + 95% 白，alpha = 1），压上去之后节点胶囊与标题整片消失，
+ *   只剩画布上位置更高的徽标露在外面。这一条是拿 A/B/C 三组对照量出来的：
+ *   A 无覆盖层 → 节点正常；B 覆盖层带底色 → 节点与标题全没了；C 覆盖层透明底 → 正常。
+ * - 段头必须在画布**上面** —— 排在画布之前就收不到点击（G6 的容器铺满整个区域）。
+ *
+ * 合成一层的话，二者必坏其一。
+ */
+function LaneHeaders({ geometry, segments, mode, lanesOff, onToggleLane, onPickSymptom }: {
+  geometry: LaneGeometry
+  segments: LaneSegment[]
+  /** 面板 / 全屏。它决定段头放得下几个现象入口（见 `PICK_LIMIT`）。 */
+  mode: StageMode
+  /** 被切面关掉的段。它与「收起」「空」是三件不同的事。 */
+  lanesOff: ReadonlySet<LaneId>
+  onToggleLane?: (lane: LaneId) => void
+  /** 点①段段头上的现象入口：换到那个现象的动线。 */
+  onPickSymptom?: (id: string) => void
+}): ReactNode {
+  const byId = new Map(segments.map(segment => [segment.lane.id, segment]))
+  return <div
+    data-tita-lane-heads=""
+    className="pointer-events-none absolute inset-0 overflow-hidden"
+    style={{ width: geometry.contentWidth }}
+  >
+    {laneGuides(geometry).map(guide => {
+      const segment = byId.get(guide.laneId as LaneId)
+      if (!segment) return null
+      const shown = segment.nodes.length
+      const readout = laneReadoutOf(segment, lanesOff)
+      // 有现象入口时段头右侧留给入口：`1/5` 已经说明了「库里五个、这屏一个」，
+      // 再挤一句排序依据进去只会换行。
+      const picks = segment.lane.id === 'symptom' ? segment.hidden : []
+      const limit = PICK_LIMIT[mode]
+      return <div
+        key={guide.laneId}
+        className="tita-attrBandHeader pointer-events-auto"
+        style={{
+          position: 'absolute',
+          left: guide.left,
+          top: guide.top,
+          width: guide.width,
+          height: guide.headerHeight,
+          ['--tita-band-tint' as string]: LANE_TINT[segment.lane.id],
+        }}
+      >
+        <button
+          type="button"
+          className="tita-attrBandHeadMain"
+          disabled={!readout.action || !onToggleLane}
+          aria-expanded={readout.action ? !segment.collapsed : undefined}
+          title={readout.text}
+          onClick={() => onToggleLane?.(segment.lane.id)}
+        >
+          <span className="tita-attrBandName">{segment.lane.ordinal} {segment.lane.label}</span>
+          <span className="tita-attrBandCount">
+            {shown}
+            {segment.total !== shown && <span className="tita-attrBandCountDim">/{segment.total}</span>}
+          </span>
+          <span className="tita-attrBandHint">{picks.length > 0 ? '' : readout.text}</span>
+        </button>
+        {picks.length > 0 && onPickSymptom && (
+          <span className="tita-attrBandPicks">
+            <span className="tita-attrBandPicksLabel">换</span>
+            {picks.slice(0, limit).map(node => <button
+              key={node.id}
+              type="button"
+              className="tita-attrBandPick"
+              onClick={() => onPickSymptom(node.id)}
+              title={`看 ${node.id} ${node.title} 的动线`}
+            >{node.id}</button>)}
+            {picks.length > limit && <button
+              type="button"
+              className="tita-attrBandPick"
+              // 多出来的收成一枚 `+N`：段头是入口不是清单，但**不能假装只有这几个**。
+              title={`还有 ${picks.length - limit} 个现象：${picks.slice(limit).map(node => `${node.id} ${node.title}`).join('、')}`}
+              onClick={() => onPickSymptom(picks[limit]!.id)}
+            >+{picks.length - limit}</button>}
+          </span>
+        )}
+      </div>
+    })}
+  </div>
+}
+
+/**
+ * 段头最多放几个现象入口，超出的收成 `+N`。
+ *
+ * 380px 的段头里，「① 问题现象 1/5」已经占掉一半，再排五个 `candidate-1s1w50u` 这种
+ * 长度的 id 就会换行、把段头顶出带子。所以限个数，多出来的进 `+N`（悬停能看到全部）。
+ * 段头是**入口**不是清单 —— 真要看全部现象，左栏的①组里有。
+ */
+const PICK_LIMIT: Record<StageMode, number> = { panel: 2, fullscreen: 4 }
+
+/** 段的三态：空（没数据）/ 收起（有数据但不画）/ 被切面关掉。三者互斥，见 `laneReadoutOf`。 */
+function laneStateOf(segment: LaneSegment, lanesOff: ReadonlySet<LaneId>): 'empty' | 'off' | 'collapsed' | 'open' {
+  if (segment.total === 0) return 'empty'
+  if (lanesOff.has(segment.lane.id)) return 'off'
+  return segment.collapsed ? 'collapsed' : 'open'
 }
+
+/**
+ * 段头的读数。**三种「这一段的节点没画出来」必须分开说**，因为含义完全不同：
+ *
+ * | 状态 | 含义 | 段头写什么 |
+ * | --- | --- | --- |
+ * | `empty`（total = 0） | 这类数据一条都没有 | 段的 `note`：「还没有查询依据：检查点没写 assets」 |
+ * | `collapsed` | 有数据，是**你**选择暂时不看 | 「已收起 · N 个 · 点这里展开」 |
+ * | `lanesOff` | 有数据，是**切面**把它关了 | 「已关闭 · N 个」 |
+ *
+ * 上一版只有 `shown === 0 ? note : orderHint`，于是用户主动收起④段时，段头会写
+ * 「还没有查询依据」—— 那是**在撒谎**，而且恰好抹掉了 §7.7 说最该显眼的那条读数
+ * （「哪一段还没建」）。
+ */
+function laneReadoutOf(segment: LaneSegment, lanesOff: ReadonlySet<LaneId>): { text: string; action: boolean } {
+  if (segment.total === 0) return { text: segment.lane.note, action: false }
+  if (lanesOff.has(segment.lane.id)) return { text: `已关闭 · ${segment.total} 个（在左栏那一段的开关里打开）`, action: false }
+  if (segment.collapsed) {
+    const hidden = segment.total - segment.nodes.length
+    return { text: hidden > 0 ? `已收起 · ${hidden} 个 · 点这里展开` : '已收起 · 点这里展开', action: true }
+  }
+  return { text: segment.lane.orderHint, action: true }
+}
+
+/** 只更新已有节点（和新增节点）的位置，不重新下发整张图的数据。 */
+function applyPlacements(graph: Graph, geometry: LaneGeometry, data: AttributionGraphData): void {
+  const updates = data.nodes
+    .map(node => ({ id: node.id, placement: geometry.nodes.get(node.id) }))
+    .filter(item => item.placement !== undefined)
+    .map(item => ({
+      id: item.id,
+      style: { x: item.placement!.x, y: item.placement!.y, size: [item.placement!.width, item.placement!.height] as [number, number] },
+    }))
+  // 与 `toGraphData` 同一处收口：样式是运行时按数据算出来的键值对，G6 的
+  // `NodeStyle` 是联合类型。断言只在这一行，别处不再需要。
+  graph.updateNodeData(updates as unknown as Parameters<Graph['updateNodeData']>[0])
+  void graph.draw()
+}
+
+/**
+ * 泳道带 + 段头。
+ *
+ * **叠一层 HTML 而不是写 G6 插件**，理由是段头要写中文与计数：G6 的 `text` 元素在
+ * 段位坐标里要自己做换行、对齐与省略，而这些正是浏览器排版最擅长的。代价是它必须与
+ * 画布严格对齐 —— 靠两条约束保证：
+ *
+ * 1. 相机锁在 `[0, 0, 1]`（见 `AttributionGraph` 顶部注释），所以世界坐标就是屏幕
+ *    像素，这里可以直接用 `geometry` 里的坐标；
+ * 2. 同一份 `LaneGeometry` **既喂画布也喂这里**，不存在两套坐标。
+ *
+ * 整层 `pointer-events-none`（§7.4 第 10 条）：带子只负责读，命中一律落到画布上。
+ * 段开关在左栏，不在这里。
+ */