@pioneer_zmc/dsh-workbench 0.2.1

package/web/assets/furniture-page.js

@@ -0,0 +1,302 @@
+// 家具图鉴页（E9b）：经真实 loadFurnitureCatalog 读取随包共用家具库，展示真实缩略图、
+// 名称、尺寸、风格、放置方式与互动；页内勾选生成「名称＋assetId」清单，供用户复制回
+// 聊天交 AI 布置。纯看图挑选页：不加载模型（loader 只用于确认引用）、不按业务过滤、
+// 不请求 inventory / /api/room、不写业务数据；选择只存本页内存，刷新即清空。
+// 所有外部名称、描述、错误一律 textContent / DOM 安全赋值，不拼 HTML。
+import { loadFurnitureCatalog } from './furniture/catalog.js'
+import { $, fetchJson, renderEmptyWorkspaceParam, setStatus, workspaceParamEmpty } from './common.js'
+
+const INDEX_URL = '/specdev-workbench/assets/furniture/index.json'
+const ASSET_ROOT = '/specdev-workbench/assets/furniture/'
+
+// 风格标记固定映射；未知值按原文字展示，不伪装成已知风格。
+const STYLE_LABELS = { fairy: '童话', ceramic: '陶瓷', realistic: '写实' }
+// 放置方式转人话；详细限制以元数据描述为准，这里不复制 placement 算法。
+const KIND_LABELS = { floor: '落地摆放', surface: '放桌面／承载面' }
+// 互动能力固定映射；没有的能力不伪造入口。
+const CAPABILITY_LABELS = { 'open-document-collection': '可查看文档与流程图' }
+
+const sizeText = (asset) => {
+  const b = asset.bounds
+  if (!b || typeof b !== 'object') return '尺寸信息不完整'
+  // 先检查原始轴值，避免减法把 null、布尔值或数字字符串悄悄转换成有效尺寸。
+  if (![b.minX, b.maxX, b.minZ, b.maxZ, b.minY, b.maxY].every(Number.isFinite)) return '尺寸信息不完整'
+  const width = b.maxX - b.minX
+  const depth = b.maxZ - b.minZ
+  const height = b.maxY - b.minY // Y 是高度轴；深度取 Z，不把 Y 当深度
+  if (![width, depth, height].every(Number.isFinite)) return '尺寸信息不完整'
+  return `宽×深×高：${width.toFixed(2)} × ${depth.toFixed(2)} × ${height.toFixed(2)} 米`
+}
+
+const kindText = (asset) => {
+  const kinds = Array.isArray(asset.placement?.allowedKinds) ? asset.placement.allowedKinds : []
+  const labels = kinds.map((kind) => KIND_LABELS[kind] ?? String(kind))
+  return labels.length > 0 ? labels.join('或') : '放置方式见详情'
+}
+
+const capabilityText = (asset) => {
+  const caps = Array.isArray(asset.capabilities) ? asset.capabilities : []
+  const labels = caps.map((cap) => CAPABILITY_LABELS[cap] ?? String(cap))
+  return labels.length > 0 ? labels.join('；') : '无页内动作'
+}
+
+const el = (tag, className) => {
+  const node = document.createElement(tag)
+  if (className) node.className = className
+  return node
+}
+
+// ── 选择集：assetId → 名称，清单输出按目录顺序稳定排列；不落任何存储。 ──────────
+const selection = new Map()
+let catalogOrder = [] // 目录里的 assetId 顺序（加载成功后填充），清单按它排序
+let selectionVersion = 0 // 每次变化自增：晚到的复制结果不能误称当前清单已复制
+let copyNoteTimer = 0
+
+const listText = () => {
+  const lines = []
+  for (const assetId of catalogOrder) {
+    if (!selection.has(assetId)) continue
+    lines.push(`- ${selection.get(assetId)}（assetId：${assetId}）`)
+  }
+  return [
+    '【家具图鉴挑选清单】',
+    ...lines,
+    '默认每款一件。请结合已说明的风格和用途布置；数量或其他要求可以补充；放不下或承载冲突时先说明。',
+  ].join('\n')
+}
+
+const refreshPicker = () => {
+  $('pickCount').textContent = `已选 ${selection.size} 款`
+  const empty = selection.size === 0
+  $('copyButton').disabled = empty
+  $('clearButton').disabled = empty
+  $('pickList').value = empty ? '' : listText()
+}
+
+const showCopyNote = (text, kind) => {
+  const note = $('copyNote')
+  note.textContent = text
+  note.dataset.kind = kind
+  note.hidden = false
+}
+
+const onPickChange = () => {
+  selectionVersion += 1
+  $('copyNote').hidden = true // 选择变化后旧的「已复制」提示失效
+  refreshPicker()
+}
+
+// ── 卡片 ──────────────────────────────────────────────────────────────────────
+/** 缩略图：previewRef 为 null 直接显示暂无图片；加载失败一次性降级，不反复请求。 */
+const mountThumb = (box, asset) => {
+  if (typeof asset.previewRef !== 'string' || asset.previewRef === '') {
+    mountNoPreview(box, asset)
+    return
+  }
+  const img = el('img')
+  img.alt = `${asset.name} 缩略图`
+  img.loading = 'lazy'
+  img.src = ASSET_ROOT + asset.previewRef // 固定包前缀＋目录校验过的 previewRef，不接外链
+  img.addEventListener('error', () => mountNoPreview(box, asset), { once: true })
+  box.appendChild(img)
+}
+
+const mountNoPreview = (box, asset) => {
+  box.textContent = ''
+  const p = el('p', 'no-preview')
+  p.textContent = `暂无图片（${asset.name} 的名称与选择功能不受影响）`
+  box.appendChild(p)
+}
+
+const mountCard = (asset) => {
+  const card = el('article', 'furniture-card')
+  const pick = el('label', 'furniture-pick')
+  const box = document.createElement('input')
+  box.type = 'checkbox'
+  box.checked = selection.has(asset.assetId)
+  box.addEventListener('change', () => {
+    if (box.checked) selection.set(asset.assetId, asset.name)
+    else selection.delete(asset.assetId)
+    onPickChange()
+  })
+  const name = el('span', 'furniture-name')
+  name.textContent = asset.name
+  pick.append(box, name)
+
+  const thumb = el('div', 'furniture-thumb')
+  mountThumb(thumb, asset)
+
+  const size = el('p', 'furniture-size')
+  size.textContent = sizeText(asset)
+  const styleLine = el('p', 'furniture-meta')
+  const styleNames = (Array.isArray(asset.styleIds) ? asset.styleIds : [])
+    .map((id) => STYLE_LABELS[id] ?? String(id)).join('、')
+  styleLine.textContent = `风格：${styleNames || '未标注'}（风格可混搭）`
+  const kindLine = el('p', 'furniture-meta')
+  kindLine.textContent = `放置：${kindText(asset)}`
+  const capLine = el('p', 'furniture-meta')
+  capLine.textContent = `互动：${capabilityText(asset)}`
+  const idLine = el('p', 'asset-id')
+  idLine.textContent = `assetId：${asset.assetId}`
+
+  const details = el('details')
+  const summary = el('summary')
+  summary.textContent = '用途与详情'
+  const description = el('p')
+  description.textContent = asset.description
+  const recommend = el('p')
+  recommend.textContent = asset.recommendations?.note ?? ''
+  details.append(summary, description)
+  if (recommend.textContent !== '') details.append(recommend)
+
+  card.append(pick, thumb, size, styleLine, kindLine, capLine, idLine, details)
+  return card
+}
+
+// ── 目录加载与渲染 ────────────────────────────────────────────────────────────
+// run 序号：离页（含往返缓存离开）后晚到的目录结果不再改 DOM；bfcache 返回若还停在
+// 加载态则用新序号重读一次，不永久卡在「正在加载」。
+let runSerial = 0
+let finished = false
+let pageGone = false // 离页后晚到的复制回调也不再改 DOM（返回时复位）
+
+const renderCatalog = (catalog, categories) => {
+  const main = $('catalog')
+  main.textContent = ''
+  if (catalog.assets.length === 0) {
+    const empty = el('p', 'furniture-empty')
+    empty.textContent = '目录里还没有登记家具。'
+    main.appendChild(empty)
+    return
+  }
+  // 分类映射来自同一次 loader 验证成功的索引：叶类型 → 分类名；映射不全时整页退回单一列表。
+  const leafToName = new Map()
+  for (const category of categories ?? []) {
+    for (const type of Array.isArray(category.types) ? category.types : []) leafToName.set(type, category.name)
+  }
+  const groups = new Map() // 分类名 → 资产数组；组顺序按索引 categories 声明顺序
+  const categoryOrder = []
+  for (const category of categories ?? []) {
+    if (isNonEmpty(category?.name)) categoryOrder.push(category.name)
+  }
+  const groupOrder = []
+  const groupOf = (name) => {
+    if (!groups.has(name)) { groups.set(name, []); groupOrder.push(name) }
+    return groups.get(name)
+  }
+  for (const name of categoryOrder) groupOf(name) // 先按声明顺序立组（空组不渲染）
+  let fallbackUsed = false
+  for (const asset of catalog.assets) {
+    const groupName = leafToName.get(asset.category)
+    if (groupName === undefined) { groupOf('全部家具'); fallbackUsed = true }
+    else groups.get(groupName).push(asset)
+  }
+  const toRender = groupOrder.filter((name) => (groups.get(name) ?? []).length > 0)
+  if (toRender.length === 1 && toRender[0] === '全部家具') {
+    const grid = el('div', 'furniture-cards')
+    for (const asset of catalog.assets) grid.appendChild(mountCard(asset))
+    main.appendChild(grid)
+    return
+  }
+  for (const name of toRender) {
+    const group = el('section', 'furniture-group')
+    const h = el('h2')
+    h.textContent = name
+    const note = el('p', 'group-note')
+    note.textContent = fallbackUsed && name === '全部家具'
+      ? '这些款式没有归入分类。勾选想要的款式，稍后在页面顶部复制清单。'
+      : '勾选想要的款式，稍后在页面顶部复制清单。'
+    const grid = el('div', 'furniture-cards')
+    for (const asset of groups.get(name)) grid.appendChild(mountCard(asset))
+    group.append(h, note, grid)
+    main.appendChild(group)
+  }
+}
+
+const isNonEmpty = (value) => typeof value === 'string' && value !== ''
+
+const main = async () => {
+  const run = ++runSerial
+  finished = false
+  let loadedIndex = null
+  // 轻量包装：目录读取仍走真实 fetchJson 与 loader 校验，这里只额外记下读到的索引，
+  // 供分类映射使用；不改 catalog 的返回契约，也不另建分类目录。
+  const tracingFetch = async (url) => {
+    const body = await fetchJson(url)
+    if (url === INDEX_URL && body && typeof body === 'object' && !Array.isArray(body)) loadedIndex = body
+    return body
+  }
+  let result
+  try {
+    result = await loadFurnitureCatalog({ fetchJson: tracingFetch })
+  } catch (error) {
+    if (run !== runSerial) return // 已离页或已被新一轮取代，晚到结果不碰 DOM
+    setStatus('读取失败', 'bad')
+    $('errorBox').hidden = false
+    $('errorBox').textContent = `读取家具目录时出现未预料的错误：${error instanceof Error ? error.message : String(error)}`
+    finished = true
+    return
+  }
+  if (run !== runSerial) return
+  finished = true
+  if (!result.ok) {
+    setStatus('目录读取失败', 'bad')
+    $('errorBox').hidden = false
+    $('errorBox').textContent = result.diagnostics.map((d) => d.message).join('\n')
+    $('catalog').textContent = '' // 坏目录不残留半份列表
+    return
+  }
+  setStatus(`已加载 ${result.catalog.assets.length} 款家具`, 'ok')
+  catalogOrder = result.catalog.assets.map((asset) => asset.assetId)
+  renderCatalog(result.catalog, Array.isArray(loadedIndex?.categories) ? loadedIndex.categories : null)
+  refreshPicker()
+  $('picker').hidden = false
+  $('pickListBox').hidden = false
+}
+
+// ── 复制与清空 ────────────────────────────────────────────────────────────────
+$('clearButton').addEventListener('click', () => {
+  selection.clear()
+  for (const input of document.querySelectorAll('.furniture-pick input')) input.checked = false
+  onPickChange()
+})
+
+$('copyButton').addEventListener('click', () => {
+  const text = listText()
+  const version = selectionVersion
+  const note = $('copyNote')
+  note.hidden = true
+  const myTimer = ++copyNoteTimer
+  const late = () => myTimer !== copyNoteTimer // 期间又点了复制：旧结果不再覆盖新结果
+  if (!navigator.clipboard || typeof navigator.clipboard.writeText !== 'function') {
+    showCopyNote('当前环境没有可用的复制接口，请在下方文本框全选后手动复制。', 'bad')
+    return
+  }
+  navigator.clipboard.writeText(text).then(
+    () => {
+      if (pageGone || late()) return // 离页后的晚到提示不再写入 DOM
+      if (version !== selectionVersion) {
+        showCopyNote('清单在复制后发生了变化，刚复制的内容不是当前清单，请重新复制。', 'bad')
+        return
+      }
+      showCopyNote('已复制。把清单粘贴到聊天发给 AI，即可按选择布置房间。', 'ok')
+    },
+    () => {
+      if (pageGone || late()) return
+      showCopyNote('复制被浏览器拒绝，请在下方文本框全选后手动复制。', 'bad')
+    },
+  )
+})
+
+window.addEventListener('pagehide', () => { runSerial += 1; pageGone = true }) // 离页后在途结果（含复制回调）全部失效
+window.addEventListener('pageshow', (event) => {
+  pageGone = false
+  // 往返缓存返回：若此前停在加载态（未完成），重新读取；已完成则原样保留。
+  if (event.persisted && !finished) void main()
+})
+
+if (workspaceParamEmpty) {
+  renderEmptyWorkspaceParam()
+} else {
+  void main()
+}

package/web/assets/home.js

@@ -0,0 +1,65 @@
+// 首页只从现有清单汇总项目与业务，不推测代码活动或图与代码的同步情况。
+import { $, businessCard, el, fetchJson, pageTitle, renderEmptyWorkspaceParam, renderGuide, renderRepoLine, renderRepoState, setStatus, showError, workspaceParamEmpty, wsUrl } from './common.js'
+
+/**
+ * 首页最醒目的那一下：进建筑。只有这个项目**真有建筑**才出现——探测一次 /api/building：
+ * 读到了（模型或诊断列表都算）就亮出来；「还没有建筑蓝图」或这一下没读到，入口就不出现，
+ * 不给人一个点进去只看得到空态的按钮。只读、不改任何东西；探测失败不影响首页其余部分。
+ */
+async function revealBuildingLink() {
+  const link = $('buildingLink')
+  try {
+    await fetchJson(wsUrl('/specdev-workbench/api/building'))
+    link.hidden = false
+  } catch {
+    link.hidden = true
+  }
+}
+
+async function main() {
+  const root = $('root')
+  try {
+    if (workspaceParamEmpty) return renderEmptyWorkspaceParam()
+    const inventory = await fetchJson(wsUrl('/specdev-workbench/api/inventory'))
+    if (inventory.code === 'repo-not-configured') return renderGuide(inventory)
+
+    document.title = pageTitle(inventory.project.name, inventory.repo)
+    $('projectName').textContent = inventory.project.name
+    $('projectDesc').textContent = inventory.project.description || '从业务出发，阅读流程、理解实现，回看每一个版本。'
+    renderRepoLine(inventory.repo)
+
+    const businesses = inventory.businesses
+    const chartCount = businesses.reduce((count, business) => count + business.charts.length, 0)
+    $('businessCount').textContent = businesses.length
+    $('chartCount').textContent = chartCount
+    $('chartCountNote').textContent = businesses.some((business) => business.descriptorError) ? '张图（不含读取异常的业务）' : '张登记的图'
+    $('projectMetrics').hidden = false
+    $('heroActions').hidden = businesses.length === 0
+    $('showcaseLink').hidden = businesses.length === 0
+    // 没有业务就没有建筑（蓝图必须逐间绑业务），这种项目连探测都不发。
+    if (businesses.length > 0) void revealBuildingLink()
+    root.replaceChildren()
+
+    for (const [index, business] of businesses.entries()) {
+      root.append(businessCard(business, index))
+    }
+    if (businesses.length === 0) {
+      const empty = el('div', 'empty-state')
+      const h = el('h3')
+      h.textContent = '项目已就绪，等待第一项业务'
+      const p = el('p')
+      p.textContent = '当前项目清单中还没有业务。添加业务资料后，刷新即可在这里查看。'
+      empty.append(h, p)
+      root.append(empty)
+    }
+    setStatus(`共 ${businesses.length} 个业务`, 'ok')
+  } catch (error) {
+    if (error.repo) renderRepoLine(error.repo)
+    if (!renderRepoState(error)) showError(error.message)
+  } finally {
+    root.querySelector('.loading-copy')?.remove()
+    root.setAttribute('aria-busy', 'false')
+  }
+}
+
+main()

package/web/assets/node-detail.js

@@ -0,0 +1,148 @@
+// 节点源码对照：只认文案中显式的“（证据 编号）”，不按相似名称推断关联。
+import { findSection, splitInline } from './details.js'
+import { describeSource, displayError, formatCodeBlock } from './evidence.js'
+
+const make = (tag, cls, text) => {
+  const node = document.createElement(tag)
+  if (cls) node.className = cls
+  if (text !== undefined) node.textContent = text
+  return node
+}
+
+// 围栏内的示例不作为证据声明，也不把示例中的标题拆成业务步骤。
+export function detailGroups(body) {
+  const groups = []
+  let lines = [], title = '', fence = null
+  const flush = () => {
+    if (!title && !lines.join('').trim()) return
+    const text = lines.join('\n').trim()
+    let inFence = null
+    const declarations = text.split('\n').filter(line => {
+      const mark = /^\s*(`{3,}|~{3,})/.exec(line)?.[1]
+      if (mark) {
+        if (!inFence) inFence = mark
+        else if (mark[0] === inFence[0] && mark.length >= inFence.length) inFence = null
+        return false
+      }
+      return !inFence
+    }).join('\n')
+    const ids = [...declarations.matchAll(/[（(]证据\s+([^）)\n]+)[）)]/g)]
+      .flatMap(match => match[1].split(/[、，,；;\s]+/)).filter(Boolean)
+    groups.push({ title, body: text, ids: [...new Set(ids)] })
+    lines = []
+  }
+  for (const line of String(body || '').split(/\r?\n/)) {
+    const mark = /^\s*(`{3,}|~{3,})/.exec(line)?.[1]
+    if (fence) {
+      lines.push(line)
+      if (mark && mark[0] === fence[0] && mark.length >= fence.length && !line.trim().slice(mark.length).trim()) fence = null
+      continue
+    }
+    if (mark) { fence = mark; lines.push(line); continue }
+    const heading = /^###\s+(.+?)\s*#*\s*$/.exec(line)
+    if (heading) { flush(); title = heading[1]; continue }
+    // 没有子标题的旧详情按段落对照；有标题则保留整个步骤为一组。
+    if (!title && !line.trim()) { flush(); continue }
+    lines.push(line)
+  }
+  flush()
+  return groups
+}
+
+function inline(host, text) {
+  for (const part of splitInline(text)) {
+    host.append(part.code || part.strong ? make(part.code ? 'code' : 'strong', '', part.text) : document.createTextNode(part.text))
+  }
+}
+
+function prose(host, text) {
+  let fence = null, code = [], list = null
+  const flushCode = () => { host.append(make('pre', 'detail-example', code.join('\n'))); code = [] }
+  for (const line of text.split('\n')) {
+    const mark = /^\s*(`{3,}|~{3,})/.exec(line)?.[1]
+    if (fence) {
+      if (mark && mark[0] === fence[0] && mark.length >= fence.length && !line.trim().slice(mark.length).trim()) { fence = null; flushCode() }
+      else code.push(line)
+      continue
+    }
+    if (mark) { fence = mark; list = null; continue }
+    if (!line.trim()) { list = null; continue }
+    const bullet = /^\s*(?:[-*+]|\d+\.)\s+(.*)$/.exec(line)
+    const heading = /^#{3,6}\s+(.*)$/.exec(line)
+    const node = make(bullet ? 'li' : heading ? 'h4' : 'p')
+    inline(node, bullet?.[1] || heading?.[1] || line)
+    if (bullet) {
+      if (!list) { list = make('ul'); host.append(list) }
+      list.append(node)
+    } else { list = null; host.append(node) }
+  }
+  if (fence) flushCode()
+}
+
+export async function loadDetailEvidence(version, request) {
+  if (version.evidenceError) return { refs: [], message: `证据文件读不开：${version.evidenceError}` }
+  if (version.files.evidence === null) return { refs: [], message: '这个版本没有证据文件。' }
+  try {
+    const data = await request(version.files.evidence)
+    return { refs: data.refs || [], message: data.parseError ? `证据文件有问题：${data.parseError}` : data.missing ? '这个版本没有证据文件。' : '' }
+  } catch (error) { return { refs: [], message: `证据读取失败：${error.message}` } }
+}
+
+export function renderNodeDetail(host, version, details, selection, evidence) {
+  host.replaceChildren()
+  const found = findSection(details, selection.id, { unreadable: version.detailsError })
+  host.append(make('h2', 'reader-title', selection.label), make('p', 'detail-source', `${selection.id} · ${version.kind === 'snapshot' ? version.label || version.tag : '当前工作区'}`))
+  if (found.kind !== 'section') {
+    const reason = found.kind === 'unreadable' ? `说明文档读不开：${found.reason}`
+      : found.kind === 'malformed' ? '说明文档没有按“## 节点编号”分节，暂时无法定位此节点。'
+      : found.kind === 'empty' ? '这个版本没有说明文档。' : '这个节点还没有说明。'
+    host.append(make('p', 'detail-miss', reason))
+    return
+  }
+  if (found.repeats > 1) host.append(make('p', 'details-warn', `此编号有 ${found.repeats} 节说明，当前显示第一份。`))
+  if (found.block.note) host.append(make('p', 'muted', found.block.note))
+  const labels = make('div', 'reader-columns')
+  labels.append(make('span', '', '源码依据'), make('span', '', '业务说明'))
+  host.append(labels)
+  const groups = detailGroups(found.block.body)
+  if (!groups.length) host.append(make('p', 'detail-miss', '这一节还没有正文。'))
+  for (const group of groups) {
+    const row = make('section', 'reader-pair')
+    const left = make('div', 'reader-code')
+    const link = make('span', 'reader-link')
+    link.setAttribute('aria-hidden', 'true')
+    const right = make('div', 'reader-prose')
+    if (group.title) right.append(make('h3', '', group.title))
+    prose(right, group.body)
+    if (!group.ids.length) {
+      left.append(make('p', 'muted', '此段未关联源码证据'))
+      row.classList.add('reader-unpaired')
+    } else if (evidence.loading || evidence.message) {
+      left.append(make('p', 'ev-warn', evidence.loading ? '正在读取源码证据…' : evidence.message))
+    } else {
+      for (const id of group.ids) {
+        const refs = evidence.refs.filter(ref => ref.id === id)
+        if (refs.length !== 1) {
+          left.append(make('p', 'ev-bad', refs.length ? `证据编号重复：${id}，无法确定对应源码。` : `找不到引用：${id}`))
+          continue
+        }
+        const ref = refs[0]
+        const box = make('figure', 'reader-snippet')
+        box.append(make('figcaption', '', ref.label || id))
+        if (!ref.ok) box.append(make('p', 'ev-bad', displayError(ref.error)))
+        else {
+          const source = make('p', 'ev-src', describeSource(ref))
+          source.title = `完整提交：${ref.commit}`
+          const code = make('pre', 'ev-code', formatCodeBlock(ref.text, ref.fromLine))
+          code.tabIndex = 0
+          code.setAttribute('aria-label', `源码 ${ref.path}`)
+          box.append(source, code)
+        }
+        left.append(box)
+      }
+    }
+    row.append(left, link, right)
+    host.append(row)
+  }
+  host.append(make('p', 'detail-source', '仅按文案中明确注明的证据编号配对；未关联资料可从“全部阅读资料”查看。源码取自引用写定的提交。'))
+}

package/web/assets/panel-link.js

@@ -0,0 +1,47 @@
+// 资料面板与它里面那份阅读页之间的两句话（同源 postMessage）。为什么需要它：
+// 流程图装在 iframe 里，用户点进阅读页后焦点进了子文档，父文档收不到键盘事件——
+// 面板上的 ESC 就"失灵"了。所以由阅读页在自己那侧接住 ESC，把"关掉资料面板"
+// 转给宿主页；顶层标签页里打开阅读页时什么都不做（没有面板可关）。
+// 另外：iframe 导航失败不会触发 error 事件，别指望用它报加载失败（见 MDN iframe 说明）；
+// 宿主页在设置 src 之前先自己取一次入口，那里才是可靠的门。
+
+/** 面板与阅读页约定的那一句话（只此一条，不带任何数据）。 */
+export const MATERIAL_CLOSE_REQUEST = 'archify-material-close'
+
+/**
+ * 阅读页侧：嵌在资料面板里时，把"用户想关掉面板"的 ESC 转给宿主页。
+ * 阅读页自己的弹层（节点详情／全部资料／保存版本）开着时不动手——那时 ESC 是关弹层的，
+ * 交给它们自己的原生 dialog 行为；只有没有弹层时才算"想退出阅读"。
+ * 用捕获阶段接：转发只是捎个话，不 preventDefault，但别被别的 document 级监听挡在前面。
+ * 同一个窗口可以接多份文档（阅读页自己的、以及它里面那张图的那份）。
+ * 返回解绑函数；顶层窗口（parent === window）直接返回空函数。
+ */
+export function forwardEscapeToHost(win, doc, { type = MATERIAL_CLOSE_REQUEST } = {}) {
+  const host = win?.parent
+  if (!host || host === win || !doc) return () => {}
+  const onKeyDown = (event) => {
+    if (event.key !== 'Escape') return
+    if (doc.querySelector('dialog[open]')) return
+    host.postMessage({ type }, win.location.origin)
+  }
+  doc.addEventListener('keydown', onKeyDown, true)
+  return () => doc.removeEventListener('keydown', onKeyDown, true)
+}
+
+/**
+ * 宿主页侧：收到面板里那份阅读页的关闭请求就关面板。
+ * 只认同一来源（同源）与约定的那一句话：这条消息只会关掉一个只读面板，
+ * 不带数据进来，也不触发任何读写。frame 在手上时再核一次事件来源，
+ * 免得别处的同源窗口冒名（拿不到 contentWindow 时不因此拒收——宁可关得上）。
+ */
+export function listenMaterialClose(win, frame, onClose, { type = MATERIAL_CLOSE_REQUEST } = {}) {
+  const onMessage = (event) => {
+    if (!event?.data || event.data.type !== type) return
+    if (event.origin !== win.location.origin) return
+    const source = frame?.contentWindow
+    if (event.source && source && event.source !== source) return
+    onClose()
+  }
+  win.addEventListener('message', onMessage)
+  return () => win.removeEventListener('message', onMessage)
+}