dsh-data-domain-knowledge 0.1.0-alpha.1

package/src/client/attribution/AttributionTab.tsx

@@ -0,0 +1,332 @@
+import {
+  GitBranch, History, Stethoscope, X,
+} from '@tita-data-agent/ui/icons'
+import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import { Button } from '@tita-data-agent/ui/components'
+import { AttributionGraph } from './AttributionGraph.tsx'
+import { CaseView } from './CaseView.tsx'
+import { GraphStage } from './GraphStage.tsx'
+import { RunView } from './RunView.tsx'
+import { ViewSwitch, type ViewSwitchItem } from './ViewSwitch.tsx'
+import {
+  FilterBar, LegendBody, LegendToggle, NodeDetailCard, StatsStrip, ToolPill, ToolRail,
+} from './StageChrome.tsx'
+import type { GraphLayout } from './graph-options.ts'
+import {
+  candidatesOf, defaultFocusId, EMPTY_FILTER, filterGraph, gapHypothesisIds,
+  neighborhoodOf, summarize, symptomCountByProblemClass,
+  type AttributionGraphData, type AttributionNodeKind, type FailureMode, type ProblemClassId,
+} from './model.ts'
+import { SEED_CASES, SEED_GRAPH } from '../../diagnosis/seed.js'
+
+type SubView = 'graph' | 'case' | 'run'
+
+/**
+ * 智能归因面板。
+ *
+ * **整块是一个画框，不是一个表单。** 承载面板的右侧边栏实测只有 380px（宿主
+ * `dsh-client-ui-sidebar-right` 的 `width:380px`），所以改版把筛选、图例、统计
+ * 全部从「图谱的兄弟节点」改成「浮在画布上的四条边」：画布吃掉全部高度，控件
+ * 叠在它上面。视觉结果就是「打开之后就是一张大图」。
+ *
+ * 三条读法各自回答一个问题（图谱=结构、案例=路径、排查=剪枝），它们是同一画框里
+ * 的三层内容，由顶部的分段切换换页 —— 切换器本身也浮在同一个框里，所以**全屏时
+ * 它天然跟着一起上去**，不需要为全屏再抄一份控件。
+ *
+ * 另外两个开关各自回答一个不同的问题：
+ * - **布局**：`力导向` 回答「这张图长什么样」（浮动、可拖、靠聚簇表达关系）；
+ *   `分层` 回答「谁是上游」（现象→假设→检查 的方向被显式画出来）。
+ * - **筛选**：按类型 / 失败模式 / 文本收窄。它是**切面**而不是树的一层 ——
+ *   可以多选、可以为空、随时能改回看全图，不会像层级那样「选错就得往回退」。
+ */
+export function AttributionTab({ visible }: { visible: boolean }): ReactNode {
+  const [subView, setSubView] = useState<SubView>('graph')
+  const [layout, setLayout] = useState<GraphLayout>('force')
+  const [overview, setOverview] = useState(true)
+  const [focusId, setFocusId] = useState<string | undefined>(() => defaultFocusId(SEED_GRAPH))
+  const [activeCase, setActiveCase] = useState('CASE-001')
+  const [full, setFull] = useState(false)
+  const [railOpen, setRailOpen] = useState(true)
+  const [legendOpen, setLegendOpen] = useState(false)
+  const [data, setData] = useState<AttributionGraphData>(SEED_GRAPH)
+  /**
+   * 宿主返回的**来源状态**。
+   *
+   * 三种形态的可信度不同，必须分开显示：卡片是当前真相；`05_diagnosis` 旧格式意味着迁移
+   * 没能无损生效（有人手工加的边或孤立的资产节点会让它放弃迁移）；`seed 数据` 是宿主没就绪
+   * 时的兜底示例。`problems` 一并显示 —— 写卡片失败、迁移分歧都属于「不能只进日志」的信息。
+   */
+  const [remote, setRemote] = useState<{ source: string; problems: string[] } | undefined>(undefined)
+  const [resetToken, setResetToken] = useState(0)
+  const [query, setQuery] = useState('')
+  const [kinds, setKinds] = useState<ReadonlySet<AttributionNodeKind>>(new Set())
+  const [modes, setModes] = useState<ReadonlySet<FailureMode>>(new Set())
+  const [problems, setProblems] = useState<ReadonlySet<ProblemClassId>>(new Set())
+  const [includeNeighbors, setIncludeNeighbors] = useState(true)
+  const [symptomId, setSymptomId] = useState('S1')
+
+  // `/diagnosis/graph`：宿主已实现这条路由（05_diagnosis）。拿不到就静默回落到 seed，
+  // 并在界面上写明来源 ——「有没有真实数据」必须可见，不能靠猜。
+  useEffect(() => {
+    if (!visible) return
+    let cancelled = false
+    void (async () => {
+      try {
+        const response = await fetch('/diagnosis/graph')
+        if (!response.ok) return
+        const payload = await response.json() as {
+          data?: { graph?: AttributionGraphData; source?: string; migrated?: boolean; problems?: string[] }
+        } & AttributionGraphData
+        const graph = payload.data?.graph ?? payload
+        if (!cancelled && Array.isArray(graph.nodes) && graph.nodes.length > 0) {
+          setData(graph)
+          const source = payload.data?.source
+          const problems = payload.data?.problems ?? []
+          setRemote({
+            source: source === 'cards' ? '02_wiki/diagnosis'
+              : source === 'jsonl' ? '05_diagnosis（旧格式）'
+                : '05_diagnosis',
+            // 迁移成功也是信息：它说明这个知识根刚从旧格式换过来。
+            problems: payload.data?.migrated ? [...problems, '本次已把 05_diagnosis 的知识迁移为 wiki 卡片'] : problems,
+          })
+        }
+      } catch { /* 宿主未就绪：保留 seed。 */ }
+    })()
+    return () => { cancelled = true }
+  }, [visible])
+
+  /**
+   * 全屏期间锁住宿主页面的滚动。
+   *
+   * 只把浮层铺满视口是不够的：滚轮落在浮层的非画布区域上时，事件会冒泡给宿主，
+   * 背后的页面照样滚。锁 `body` 是这里唯一简单可靠的做法（宿主用的是文档级滚动），
+   * 退出时按原值还原而不是写死 `''`。
+   */
+  useEffect(() => {
+    if (!full) return
+    const previous = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+    const onKeyDown = (event: KeyboardEvent): void => { if (event.key === 'Escape') setFull(false) }
+    window.addEventListener('keydown', onKeyDown)
+    return () => {
+      document.body.style.overflow = previous
+      window.removeEventListener('keydown', onKeyDown)
+    }
+  }, [full])
+
+  const filter = useMemo(
+    () => ({ ...EMPTY_FILTER, query, kinds, failureModes: modes, problemClasses: problems, includeNeighbors }),
+    [query, kinds, modes, problems, includeNeighbors],
+  )
+  const filtered = useMemo(() => filterGraph(data, filter), [data, filter])
+  const gapIds = useMemo(() => new Set(gapHypothesisIds(filtered)), [filtered])
+  const stats = useMemo(() => summarize(filtered), [filtered])
+  const candidateCount = useMemo(() => candidatesOf(data, symptomId).length, [data, symptomId])
+  const symptomCounts = useMemo(() => symptomCountByProblemClass(data.nodes), [data])
+  const symptoms = useMemo(() => data.nodes.filter(node => node.kind === 'symptom'), [data])
+  const graphData = useMemo(
+    () => (overview ? filtered : (focusId ? neighborhoodOf(filtered, focusId, 1) : filtered)),
+    [filtered, overview, focusId],
+  )
+  const focused = data.nodes.find(node => node.id === focusId)
+  const filtering = query.trim() !== '' || kinds.size > 0 || modes.size > 0 || problems.size > 0
+
+  const toggleKind = (kind: AttributionNodeKind): void => {
+    const next = new Set(kinds)
+    if (next.has(kind)) next.delete(kind); else next.add(kind)
+    setKinds(next)
+  }
+  const toggleMode = (mode: FailureMode): void => {
+    const next = new Set(modes)
+    if (next.has(mode)) next.delete(mode); else next.add(mode)
+    setModes(next)
+  }
+  const toggleProblem = (id: ProblemClassId): void => {
+    const next = new Set(problems)
+    if (next.has(id)) next.delete(id); else next.add(id)
+    setProblems(next)
+  }
+  const clearFilter = (): void => { setQuery(''); setKinds(new Set()); setModes(new Set()); setProblems(new Set()) }
+
+  /**
+   * 进出全屏。
+   *
+   * 进全屏时顺手把图例打开：那个档位本来就该「相关选项都展示上去」，而且全屏里
+   * 右侧副栏宽一倍，放得下。退出时不动用户的选择 —— 收起图例是用户的决定，
+   * 不该被一次全屏往返改回去。
+   */
+  const toggleFull = (): void => {
+    if (!full) setLegendOpen(true)
+    setFull(!full)
+  }
+
+  /** 页签上的计数是「这一页有多少东西可看」，而不是装饰 —— 空页和满页要能一眼分开。 */
+  const viewItems: ReadonlyArray<ViewSwitchItem<SubView>> = [
+    {
+      id: 'graph', label: '图谱', icon: GitBranch,
+      hint: '结构：谁可能是谁的原因。空区和僵尸边只在这张图上可见。',
+      meta: String(stats.typeNodes + stats.referenceNodes),
+    },
+    {
+      id: 'case', label: '案例', icon: History,
+      hint: '路径：一次真实排查怎么走的，包括走错的那一段。',
+      meta: String(SEED_CASES.length),
+    },
+    {
+      id: 'run', label: '排查', icon: Stethoscope,
+      hint: '剪枝：按优先分排出下一步该查什么，每个检查都有主操作。',
+      meta: String(candidateCount),
+    },
+  ]
+
+  const layoutHint = layout === 'force'
+    ? '力导向：节点可拖动，松手后图会继续摊开 —— 关系靠聚簇和距离表达，方向不保证。'
+    : '分层：现象 → 假设 → 检查 的方向被显式画出来，但看起来更像流程图。'
+
+  const stage = <GraphStage
+    mode={full ? 'fullscreen' : 'panel'}
+    // 画布不随子视图卸载：切走再切回来时，拖过的位置要还在。
+    canvas={<AttributionGraph
+      key={`${resetToken}-${layout}`}
+      data={graphData}
+      gapIds={gapIds}
+      rankdir="LR"
+      layout={layout}
+      mode={full ? 'fullscreen' : 'panel'}
+      selectedId={focusId}
+      onSelect={setFocusId}
+    />}
+    topLeft={
+      // 画布左上角只剩「这张图怎么画」：布局 + 类型切面。页面切换已经搬到画框之外。
+      // 案例 / 排查页没有图可读，这两个开关也就没有对象 —— 不传，不留空壳。
+      subView !== 'graph' ? undefined : railOpen
+        ? <ToolRail
+          layout={layout}
+          onLayout={setLayout}
+          onReset={() => setResetToken(token => token + 1)}
+          kinds={kinds}
+          onToggleKind={toggleKind}
+          problems={problems}
+          onToggleProblem={toggleProblem}
+          symptomCounts={symptomCounts}
+          hint={layoutHint + (!overview && focused ? ` 聚焦 ${focused.id} 的 1 跳邻域，点节点切换。` : '')}
+          onCollapse={() => setRailOpen(false)}
+        />
+        : <ToolPill layout={layout} kinds={kinds} problems={problems} onClick={() => setRailOpen(true)} />
+    }
+    topRight={<LegendToggle
+      open={legendOpen}
+      onToggle={() => setLegendOpen(!legendOpen)}
+      full={full}
+      onToggleFull={toggleFull}
+      showLegend={subView === 'graph'}
+    />}
+    {...(subView === 'case' ? { layer: <CaseView activeId={activeCase} onActiveChange={setActiveCase} /> } : {})}
+    {...(subView === 'run' ? {
+      layer: <RunView
+        data={data}
+        symptoms={symptoms}
+        symptomId={symptomId}
+        onSymptomChange={setSymptomId}
+        onSelectNode={id => { setFocusId(id); setSubView('graph') }}
+      />,
+    } : {})}
+    {...(subView === 'graph' ? {
+      bottomCenter: <FilterBar
+        query={query}
+        onQuery={setQuery}
+        modes={modes}
+        onToggleMode={toggleMode}
+        includeNeighbors={includeNeighbors}
+        onIncludeNeighbors={setIncludeNeighbors}
+        filtering={filtering}
+        onClear={clearFilter}
+        hit={filtered.nodes.length}
+        total={data.nodes.length}
+      />,
+      bottomRight: <StatsStrip
+        stats={stats}
+        source={remote?.source ?? 'seed 数据'}
+        problems={remote?.problems ?? []}
+      />,
+      side: <>
+        {/* 「全景 / 聚焦邻域」是画布读法，不是筛选，所以它贴在图例下面而不是筛选条里。 */}
+        <div className="mb-1.5 flex justify-end">
+          <Button
+            size="sm"
+            className="h-[26px] min-h-[26px] px-2 text-[11px]"
+            variant={overview ? 'default' : 'outline'}
+            onClick={() => setOverview(!overview)}
+          >{overview ? '全景' : '聚焦 1 跳'}</Button>
+        </div>
+        <div className="flex flex-col gap-1.5">
+          {legendOpen && <LegendBody stats={stats} />}
+          {focused && <NodeDetailCard node={focused} />}
+        </div>
+      </>,
+    } : {})}
+  />
+
+  /**
+   * 页面切换器：**画框之外，页面左上角**。
+   *
+   * 它曾经浮在画布的左上角。搬到外面来的理由不是审美：**页面切换是页面级控件，
+   * 画布是它切换的内容之一**。放在画布里，等于把「换一页」和「改这张图怎么画」
+   * 混成同一层的浮层 —— 而 §7.1 的分区原则正好相反（改「怎么画」的贴画布，
+   * 换「看哪一页」的贴页面）。搬出来之后画布左上角只剩布局与类型两个开关。
+   *
+   * 说明文案不在切换器内部，而是同一行的右侧：一整行读下来是
+   * 「你在哪一页 → 这一页回答什么问题」，比把它折到切换器下面更省一行高度。
+   */
+  const switcher = <ViewSwitch
+    items={viewItems}
+    value={subView}
+    onChange={setSubView}
+    ariaLabel="智能归因视图"
+    showHint={false}
+    className="shrink-0"
+  />
+  const viewHint = viewItems.find(item => item.id === subView)?.hint ?? ''
+
+  if (full) {
+    return createPortal(
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-label="智能归因全屏视图"
+        className="fixed inset-0 z-[900] flex flex-col gap-2 overscroll-contain bg-tita-surface-muted p-3"
+      >
+        {/* 全屏只有一行页头：标题 + 页面切换 + 当前页说明 + 出口。全屏是「同一块内容
+            换成整个视口」，所以这一行就是面板里那两行（页头 + 切换行）压成一行。 */}
+        <header className="flex items-center gap-2">
+          <span
+            className="inline-flex h-6 w-6 shrink-0 items-center justify-center rounded-lg border"
+            style={{ borderColor: 'var(--tita-tone-green-line)', background: 'var(--tita-tone-green-tint)', color: 'var(--tita-tone-green)' }}
+          >
+            <Stethoscope size={14} />
+          </span>
+          <h2 className="shrink-0 text-[14px] font-[750] tracking-[-0.02em]">智能归因</h2>
+          {switcher}
+          <p className="min-w-0 flex-1 truncate text-[11px] text-tita-ink-muted">{viewHint}</p>
+          <Button
+            size="sm"
+            variant="outline"
+            className="h-[26px] min-h-[26px] shrink-0 px-2 text-[11px]"
+            onClick={() => setFull(false)}
+          ><X size={12} />退出全屏（Esc）</Button>
+        </header>
+        {stage}
+      </div>,
+      document.body,
+    )
+  }
+
+  return <div className="flex min-h-0 flex-1 flex-col gap-1.5">
+    <div className="flex min-w-0 items-center gap-2">
+      {switcher}
+      <p className="min-w-0 flex-1 truncate text-[10px] text-tita-ink-muted">{viewHint}</p>
+    </div>
+    {stage}
+  </div>
+}

package/src/client/attribution/CaseView.tsx

@@ -0,0 +1,102 @@
+import { ChevronDown, CircleDot, FileText, TriangleAlert } from '@tita-data-agent/ui/icons'
+import type { ReactNode } from 'react'
+import { Badge, Button, Card, cn } from '@tita-data-agent/ui/components'
+import { SEED_CASES } from '../../diagnosis/seed.js'
+
+/**
+ * 案例视图：**wiki 定义 + 排查节点**。
+ *
+ * 这两段是案例的两个面，不是一个东西的两种画法：
+ * - wiki 段回答「当时到底发生了什么」（散文、可评审、可被向量召回）；
+ * - 节点段回答「知识怎么走的」（有序、可判真假、含被否定的分支）。
+ *
+ * 所以这里不做「文档里嵌一张图」那种合成视图，而是把两段并排放在同一张卡里 ——
+ * 读者能同时看到叙述和结构，而两者的数据源仍然各自独立。
+ *
+ * 红色底边与绿色底没有共享的 Tailwind 工具类（工具类只在 packages/ui 构建时按用到的类
+ * 生成，而插件不能改 packages/ui），所以这两处走行内 `style`，取值仍是共享令牌。
+ */
+/** 被否定的一步 / 误导段共用的红色底与边（见文件头）。 */
+const REFUTED_WASH = { borderColor: 'var(--ddk-danger-line)', background: 'var(--ddk-danger-tint)' }
+
+export function CaseView({ activeId, onActiveChange }: {
+  activeId: string
+  onActiveChange: (id: string) => void
+}): ReactNode {
+  const active = SEED_CASES.find(item => item.id === activeId) ?? SEED_CASES[0]!
+
+  return <div className="flex flex-col gap-3">
+    <div className="flex flex-wrap gap-1.5">
+      {SEED_CASES.map(item => <Button
+        key={item.id}
+        variant={item.id === active.id ? 'default' : 'outline'}
+        size="sm"
+        onClick={() => onActiveChange(item.id)}
+      >{item.id.replace('CASE-', '#')} {item.title}</Button>)}
+    </div>
+
+    <Card className="gap-3 p-3">
+      <header className="flex items-start justify-between gap-2">
+        <div className="min-w-0">
+          <h3 className="text-[13px] font-semibold leading-snug">{active.title}</h3>
+          <p className="mt-0.5 text-[10.5px] text-tita-ink-muted">{active.id} · 耗时 {active.durationMinutes} min</p>
+        </div>
+        <Badge tone="success">已确认根因</Badge>
+      </header>
+
+      {/* ── wiki 段 ── */}
+      <section aria-label="wiki 定义">
+        <div className="mb-1.5 flex items-center gap-1.5 text-[10px] tracking-wide text-tita-ink-muted">
+          <FileText size={12} />WIKI 定义
+        </div>
+        <div className="flex flex-col gap-2">
+          {active.sections.map(section => <div key={section.heading}>
+            <div className="text-[11px] font-semibold">{section.heading}</div>
+            <p className="mt-0.5 text-[11px] leading-relaxed text-tita-ink-muted">{section.body}</p>
+          </div>)}
+        </div>
+      </section>
+
+      {/* ── 节点段 ── */}
+      <section aria-label="排查节点">
+        <div className="mb-1.5 flex items-center gap-1.5 text-[10px] tracking-wide text-tita-ink-muted">
+          <CircleDot size={12} />排查节点
+        </div>
+        <ol className="flex flex-col gap-1">
+          {active.path.map((step, index) => <li key={`${step.nodeId}-${index}`} className="flex items-start gap-2">
+            <span className={cn(
+              'mt-0.5 inline-flex h-[18px] min-w-[42px] shrink-0 items-center justify-center rounded-md border px-1 font-mono text-[10px]',
+              step.refuted ? 'text-tita-danger' : 'border-tita-line bg-tita-surface-muted text-tita-ink-muted',
+            )} style={step.refuted ? REFUTED_WASH : undefined}>{step.label}</span>
+            <span className="pt-0.5 text-[11px] leading-snug text-tita-ink-muted">{step.note}</span>
+          </li>)}
+        </ol>
+      </section>
+
+      {active.misleading && <div className="rounded-lg border p-2" style={REFUTED_WASH}>
+        <div className="flex items-center gap-1.5 text-[11px] font-semibold text-tita-danger">
+          <TriangleAlert size={12} />误导段 · {active.misleading.label} · 浪费 {active.misleading.wastedMinutes} min
+        </div>
+        <p className="mt-1 text-[11px] leading-relaxed text-tita-danger">{active.misleading.why}</p>
+      </div>}
+
+      <footer
+        className="rounded-lg p-2 text-[11px] leading-relaxed"
+        style={{ background: 'var(--tita-tone-green-tint)', color: 'var(--tita-tone-green)' }}
+      >
+        <b>根因</b>{active.rootCause}
+      </footer>
+    </Card>
+
+    <details className="group rounded-lg border border-tita-line bg-tita-surface p-2.5">
+      <summary className="flex cursor-pointer list-none items-center gap-1.5 text-[11.5px] font-medium">
+        <ChevronDown size={13} className="transition-transform group-open:rotate-180" />
+        为什么案例要分「wiki 段」和「节点段」两段
+      </summary>
+      <p className="mt-1.5 text-[10.5px] leading-relaxed text-tita-ink-muted">
+        wiki 段是给人读、给向量召回的散文；节点段是给归并与剪枝读的结构。把「序」和「枚举」写进散文，
+        归并算法就再也读不到它们了 —— 这也是案例不能只存成一篇文档的原因。
+      </p>
+    </details>
+  </div>
+}

package/src/client/attribution/GraphStage.tsx

@@ -0,0 +1,87 @@
+import type { ReactNode } from 'react'
+import { cn } from '@tita-data-agent/ui/components'
+import type { StageMode } from './graph-options.ts'
+
+export interface GraphStageProps {
+  /** 视口档位。只影响浮层的宽度预算，不影响画布（画布由父级尺寸决定）。 */
+  mode: StageMode
+  /** 画布层。它在两种排布下都铺满整个框。 */
+  canvas: ReactNode
+  /**
+   * 覆盖层（案例 / 排查视图）。
+   *
+   * 给了它，画布**不卸载**，只是被盖住。理由是位置记忆：力导向图被拖动过之后，
+   * 切到案例再切回来应该还是原来的形状；卸载重建会让每次切页都把图重新吹散。
+   */
+  layer?: ReactNode
+  /** 左上：布局切换 + 类型切面。 */
+  topLeft?: ReactNode
+  /** 右上：图例 + 全屏。 */
+  topRight?: ReactNode
+  /** 底部中间：其余筛选。 */
+  bottomCenter?: ReactNode
+  /** 右下：统计。 */
+  bottomRight?: ReactNode
+  /** 右侧副栏，贴在顶部那一行之下（图例正文、选中节点详情）。 */
+  side?: ReactNode
+  className?: string
+}
+
+/**
+ * 图谱画框。
+ *
+ * **它存在的唯一理由是「图谱占满内容区」。** 改版前，筛选、统计、图例都是图谱的
+ * 兄弟节点，从上到下堆成一列 —— 在 380px 宽的右栏里，图谱被自己的控件挤到只剩
+ * 一半高度。改版后所有这些控件变成**浮在画布上的四条边**（左上 / 右上 / 底中 /
+ * 右下），画布本身吃掉整块面积。这是「打开就是一张大图」在结构上的实现方式：
+ * 不是把图放大，而是把其它东西从它的高度里拿走。
+ *
+ * 两套排布分开写，而不是用一套 `absolute` 加条件：
+ * - **画布模式**（无明显层）：四条边浮在画布上，画布铺满，节点在浮层下面继续延展。
+ * - **内容模式**（案例 / 排查）：内容要滚动，浮层浮在滚动内容上会遮住正文，
+ *   所以顶部控件改为正常流里的一行，内容占满其余高度。
+ *
+ * 浮层容器整体 `pointer-events-none`、只给面板本身打开命中 —— 否则四条边的
+ * 空档会把画布的拖拽和滚轮缩放吞掉。
+ */
+export function GraphStage({ mode, canvas, layer, topLeft, topRight, bottomCenter, bottomRight, side, className }: GraphStageProps): ReactNode {
+  const frame = cn(
+    'relative min-h-0 w-full flex-1 overflow-hidden rounded-xl border border-tita-line bg-tita-surface',
+    className,
+  )
+
+  if (layer) {
+    return <div className={frame}>
+      <div className="absolute inset-0">{canvas}</div>
+      <div className="relative flex h-full flex-col gap-1.5 bg-tita-surface">
+        {(topLeft || topRight) && <div className="flex items-start gap-1.5 px-2 pt-2">
+          {topLeft && <div className="min-w-0 max-w-full">{topLeft}</div>}
+          {topRight && <div className="ml-auto shrink-0">{topRight}</div>}
+        </div>}
+        <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain px-2.5 pb-2.5">{layer}</div>
+      </div>
+    </div>
+  }
+
+  return <div className={frame}>
+    <div className="absolute inset-0">{canvas}</div>
+    <div className="pointer-events-none relative flex h-full flex-col gap-1.5 p-2">
+      <div className="flex items-start gap-1.5">
+        {topLeft && <div className="pointer-events-auto min-w-0 max-w-full">{topLeft}</div>}
+        {topRight && <div className="pointer-events-auto ml-auto shrink-0">{topRight}</div>}
+      </div>
+      {side && <div className={cn(
+        'pointer-events-auto ml-auto overflow-y-auto overscroll-contain',
+        // 副栏宽度按**档位**给：面板里 380px 的侧栏减去两条浮层只剩约 240px，
+        // 全屏才有余量把图例铺成两列。
+        mode === 'fullscreen' ? 'max-h-[62%] w-[min(360px,62%)]' : 'max-h-[52%] w-[min(238px,76%)]',
+      )}>
+        {side}
+      </div>}
+      <div className="mt-auto flex flex-col gap-1.5">
+        {bottomCenter && <div className="pointer-events-auto mx-auto w-full">{bottomCenter}</div>}
+        {bottomRight && <div className="pointer-events-auto ml-auto">{bottomRight}</div>}
+      </div>
+    </div>
+  </div>
+}