@pioneer_zmc/dsh-workbench 0.2.1

package/web/assets/rooms/reader.js

@@ -0,0 +1,441 @@
+// 房间阅读面板（E3b-2；E9c 扩展流程图）：点书架、告示牌或"业务资料"后在房间之上
+// 打开的资料集合与阅读区。文档继续本模块正文阅读；流程图复用既有 read 页面装进
+// iframe（不开新标签、不另造图渲染）。本模块只负责 DOM 面板、资料请求、焦点与请求
+// 失效；不 import Three、场景、旧建筑模型或业务清单读取代码。解析内核复用 details.js
+//（parseDocument／splitInline），正文与行内标记的 DOM 做法迁用 building.js 的
+// renderDocumentBody／appendInline（不经 innerHTML，业务数据里的 HTML 字符一律按文字显示）。
+// 流程图的打开做法迁用 building.js 的 openWorkflowReader：先 fetch 同工作区阅读入口，
+// 取不到如实报错并可重试；取到再设 iframe 地址——预检 200 只证明 read.html 可达，
+// 图文件缺失、坏 JSON 和编译问题由阅读页自己显示，不用 iframe 的 error 事件判断。
+//
+// 暂停与恢复不在本模块：open/close 时经 onReadingChange 通知页面（页面调场景句柄
+// setReading 并同步按钮），重复 open 不重复暂停，dispose 不触发恢复。
+// iframe 里的阅读页按既有约定（panel-link.js）把 ESC 转发回来关面板；它自己的
+// 节点详情等 dialog 开着时先按原行为关 dialog，不提前退出面板——本模块不改 read.js。
+import { el, wsUrl } from '../common.js'
+import { parseDocument, splitInline } from '../details.js'
+import { listenMaterialClose } from '../panel-link.js'
+
+/** 接口失败时优先说后端给的中文原因（JSON 错误体的 error 字段），拿不到再按 HTTP 状态说。
+ *  与 building.js 同口径（迁用，不 import 整个页面脚本）。 */
+async function failureReason(response) {
+  try {
+    const body = await response.json()
+    if (body && typeof body.error === 'string' && body.error) return body.error
+  } catch { /* 正文不是 JSON：按状态码说。 */ }
+  return `HTTP ${response.status}`
+}
+
+/**
+ * 房间阅读面板。
+ * @param root           room.html 里唯一的阅读覆盖层（面板放在 viewport 外、roomStage 内，
+ *                       背景视口加 inert 不会波及面板）
+ * @param onReadingChange 开／关面板时各通知一次（true＝进入阅读，false＝退出）；页面负责
+ *                       暂停场景与按钮同步
+ * @param focusFallback  归还焦点时的兜底元素（触发元素已不在文档里时用）
+ * @returns { open({ title, entries, emptyText, returnFocus }), close(), isOpen(), dispose() }
+ *   entries 条目来自 resolver 已验证的目录（{ kind: 'document'|'workflow', … }），本模块
+ *   不自行造链接；文档条目带 path，图条目带 chartId（unavailableReason 的登记图不发请求）。
+ */
+
+/** 资料条目的稳定身份（与绑定层同口径）：文档＝登记路径、流程图＝图 ID；不按标题区分。 */
+const materialKey = (entry) => (entry.kind === 'workflow' ? `chart:${entry.chartId}` : `doc:${entry.path}`)
+
+/** 清单与标题里的人话前缀。 */
+const kindLabel = (entry) => (entry.kind === 'workflow' ? '流程图' : '文档')
+
+export function createRoomReader({ root, onReadingChange = () => {}, focusFallback = null } = {}) {
+  const panel = root.querySelector('#readerPanel')
+  const title = root.querySelector('#readerTitle')
+  const closeBtn = root.querySelector('#readerClose')
+  const listLabel = root.querySelector('#readerListLabel')
+  const list = root.querySelector('#readerList')
+  const count = root.querySelector('#readerCount')
+  const listEmpty = root.querySelector('#readerEmpty')
+  const hint = root.querySelector('#readerHint')
+  const docTitle = root.querySelector('#readerDocTitle')
+  const status = root.querySelector('#readerStatus')
+  const body = root.querySelector('#readerBody')
+  const retryLine = root.querySelector('#readerRetryLine')
+  const retryBtn = root.querySelector('#readerRetry')
+  const frameHost = root.querySelector('#readerFrameHost')
+  const listToggle = root.querySelector('#readerListToggle')
+  const sizeToggle = root.querySelector('#readerSizeToggle')
+  const side = root.querySelector('.material-side')
+  const startGuard = root.querySelector('#readerFocusStart')
+  const endGuard = root.querySelector('#readerFocusEnd')
+
+  let openState = false
+  let disposed = false
+  // 左侧清单收缩（作者令 2026-10-01）：换集合（open）时重置为展开——新集合要看清单；
+  // 同一次打开内自由切换。面板放大跨 open 保持——窗口大小是阅读偏好，不随换家具回弹。
+  let listCollapsed = false
+  let enlarged = false
+  // 单调请求序号＝最终写入条件：换资料、换集合（resetReader）、关闭、dispose 都使旧序号
+  // 失效；成功与失败分支在异步正文／错误体读取之后都复查"当前请求、面板仍开着、控制器仍存活"。
+  let requestSeq = 0
+  let currentEntry = null
+  let returnFocus = null
+  // 当前集合的条目表（按钮 → 已验证 entry，E3b-2 验收补齐 R1）：条目点击经 list 一次性
+  // 委托分发，只认这张表——不从 DOM 的 dataset/path 重建资料链接；换集合清空、销毁清空。
+  const entryByButton = new Map()
+  // 图阅读页（E9c）：同时最多一个 iframe。每次选图新建节点，切走/换集合/关闭/销毁时
+  // 清空导航（about:blank）、移除节点并解绑关闭消息监听——旧 load/消息不能改写新资料，
+  // 也不能在关闭后复活面板。
+  let frame = null
+  let unlistenClose = null
+
+  const setNote = (kind, text) => {
+    status.hidden = !text
+    status.textContent = text || ''
+    status.dataset.kind = kind || ''
+  }
+
+  /** 撤掉当前图 iframe：先解绑关闭消息，再清空导航并移除节点。幂等。 */
+  function clearFrame() {
+    if (unlistenClose) {
+      unlistenClose()
+      unlistenClose = null
+    }
+    if (frame) {
+      frame.setAttribute('src', 'about:blank')
+      frame.remove()
+      frame = null
+    }
+    frameHost.textContent = ''
+    frameHost.hidden = true
+  }
+
+  const markActive = () => {
+    const currentKey = currentEntry ? materialKey(currentEntry) : ''
+    for (const button of list.querySelectorAll('.material-item')) {
+      if (currentKey && button.dataset.material === currentKey) button.setAttribute('aria-current', 'true')
+      else button.removeAttribute('aria-current')
+    }
+  }
+
+  /** 换集合、换资料、关闭都走这里：使在途请求失效并回到"还没挑资料"。 */
+  const resetReader = () => {
+    requestSeq += 1
+    currentEntry = null
+    clearFrame()
+    body.textContent = ''
+    body.hidden = true
+    retryLine.hidden = true
+    docTitle.hidden = true
+    setNote('', '')
+    hint.textContent = '选择一份资料开始阅读'
+    hint.hidden = false
+    markActive()
+  }
+
+  const renderList = (entries, emptyText) => {
+    list.textContent = '' // 旧按钮随清空移除（脱离文档的引用无法再冒泡到委托层）
+    entryByButton.clear() // 换集合：旧条目表整体作废
+    const empty = entries.length === 0
+    listLabel.hidden = empty
+    list.hidden = empty
+    listEmpty.hidden = !empty
+    listEmpty.textContent = empty ? emptyText : ''
+    count.textContent = empty ? '' : `${entries.length} 份`
+    for (const entry of entries) {
+      const item = el('li')
+      const button = el('button', 'material-item')
+      button.type = 'button'
+      button.dataset.kind = entry.kind
+      button.dataset.material = materialKey(entry)
+      button.textContent = `${kindLabel(entry)} · ${entry.title}`
+      entryByButton.set(button, entry)
+      item.appendChild(button)
+      list.appendChild(item)
+    }
+  }
+
+  const showFailure = (reason) => {
+    setNote('bad', `读不到这份资料：${reason}。可以点“重试”再取一次。`)
+    retryLine.hidden = false
+  }
+
+  /** 取一份文档的正文（不缓存：每次点击都重新请求，服务端仍负责当时的登记与文件权限）。
+   *  入口先于一切 DOM 写入与请求检查存活与打开：销毁后或面板已关时，旧按钮引用
+   *  （含已脱离文档的）不能再触发加载状态或发起新请求（E3b-2 验收补齐 R1）。 */
+  async function openEntry(entry) {
+    if (disposed || !openState) return
+    requestSeq += 1 // 所有切换都先作废旧请求，包括不发请求的不可用图。
+    currentEntry = entry
+    markActive()
+    hint.hidden = true
+    docTitle.textContent = `${kindLabel(entry)} · ${entry.title}`
+    docTitle.hidden = false
+    body.textContent = ''
+    body.hidden = true
+    retryLine.hidden = true
+    clearFrame() // 换目标：旧图先让位（含解绑监听），文档与图互不残留
+    return entry.kind === 'workflow' ? openChart(entry) : openDocument(entry)
+  }
+
+  /** 文档正文：错误体读取也是等待，期间用户可能已换目标/关面板。 */
+  async function openDocument(entry) {
+    setNote('info', '正在读取文档…')
+    const seq = ++requestSeq
+    try {
+      const response = await fetch(wsUrl(entry.href))
+      if (seq !== requestSeq || !openState || disposed) return
+      if (!response.ok) {
+        const reason = await failureReason(response) // 异步读错误体期间用户可能已换目标
+        if (seq !== requestSeq || !openState || disposed) return
+        return showFailure(reason)
+      }
+      const text = await response.text()
+      if (seq !== requestSeq || !openState || disposed) return
+      setNote('', '')
+      renderDocumentBody(text)
+    } catch (error) {
+      if (seq !== requestSeq || !openState || disposed) return
+      showFailure(error instanceof Error ? error.message : String(error))
+    }
+  }
+
+  /** 流程图（E9c）：入口预检（同 building.js 做法）成功后新建 iframe 装既有阅读页；
+   *  重试按当前资料类型重新走本入口。坏登记条目（unavailableReason）不发网络请求，
+   *  只显示说明——刷新房间后可重新读取登记状态。 */
+  async function openChart(entry) {
+    if (entry.unavailableReason) {
+      setNote('bad', `这张流程图当前不可用：${entry.unavailableReason}。刷新房间后可重新读取登记状态。`)
+      retryLine.hidden = true // 不发请求的说明不是网络失败，不给重试按钮
+      return
+    }
+    setNote('info', '正在打开阅读页…')
+    const seq = ++requestSeq
+    const url = wsUrl(entry.href)
+    let response
+    try {
+      response = await fetch(url)
+    } catch (error) {
+      if (seq !== requestSeq || !openState || disposed) return
+      return showFailure(`阅读页没有打开（${error instanceof Error ? error.message : String(error)}）`)
+    }
+    if (seq !== requestSeq || !openState || disposed) return
+    if (!response.ok) {
+      const reason = await failureReason(response) // 异步读错误体期间用户可能已换目标
+      if (seq !== requestSeq || !openState || disposed) return
+      return showFailure(`阅读页打不开（${reason}）`)
+    }
+    if (seq !== requestSeq || !openState || disposed) return
+    // 说明行留到用户换资料/关闭为止：iframe 导航失败不触发 error 事件，"正在打开"
+    // 比一片空白诚实；图内容问题由阅读页自己那套说法显示（缺图、坏 JSON、编号冲突）。
+    const node = el('iframe', 'material-reader-frame')
+    node.title = `流程图阅读：${entry.title}`
+    frameHost.textContent = ''
+    frameHost.appendChild(node)
+    frameHost.hidden = false
+    frame = node
+    node.setAttribute('src', url)
+    // 阅读页里按 ESC 会经 panel-link.js 转发关面板；只认当前 iframe 的同源消息。
+    unlistenClose = listenMaterialClose(window, frame, () => close())
+  }
+
+  /** 正文按块呈现（迁用 building.js 的 DOM 做法）：标题成标题、列表成列表、空文件给空态。 */
+  function renderDocumentBody(text) {
+    body.textContent = ''
+    const blocks = parseDocument(text)
+    if (!blocks.length) {
+      const empty = el('p', 'material-doc-empty')
+      empty.textContent = '这份文档没有正文（文件是空的）。'
+      body.appendChild(empty)
+    }
+    let listNode = null
+    for (const block of blocks) {
+      if (block.kind === 'bullet') {
+        if (!listNode) {
+          listNode = el('ul', 'material-doc-list')
+          body.appendChild(listNode)
+        }
+        const item = el('li')
+        appendInline(item, block.text)
+        listNode.appendChild(item)
+        continue
+      }
+      listNode = null
+      if (block.kind === 'heading') {
+        const heading = el('h3', 'material-doc-heading')
+        heading.dataset.level = String(block.level)
+        appendInline(heading, block.text)
+        body.appendChild(heading)
+        continue
+      }
+      const paragraph = el('p', 'material-doc-paragraph')
+      appendInline(paragraph, block.text)
+      body.appendChild(paragraph)
+    }
+    body.hidden = false
+  }
+
+  /** 行内 **加粗**／`代码` 拼成 DOM，不经 innerHTML（迁用 building.js）。 */
+  function appendInline(host, text) {
+    for (const part of splitInline(text)) {
+      if (part.strong) {
+        const node = el('strong')
+        node.textContent = part.text
+        host.appendChild(node)
+      } else if (part.code) {
+        const node = el('code')
+        node.textContent = part.text
+        host.appendChild(node)
+      } else {
+        host.appendChild(document.createTextNode(part.text))
+      }
+    }
+  }
+
+  /** 清单收缩与面板放大（作者令 2026-10-01）只改 root 的 data 属性，样式在 room.css；
+   *  按钮文案与 aria-pressed 同步，两按钮照常参与 Tab 焦点循环。 */
+  const syncListToggle = () => {
+    side.hidden = listCollapsed // DOM 与样式同步隐藏，焦点循环也能排除收起清单。
+    if (listCollapsed) root.dataset.list = 'collapsed'
+    else delete root.dataset.list
+    listToggle.textContent = listCollapsed ? '展开清单' : '收起清单'
+    listToggle.setAttribute('aria-pressed', String(listCollapsed))
+  }
+  const syncSizeToggle = () => {
+    if (enlarged) root.dataset.size = 'large'
+    else delete root.dataset.size
+    sizeToggle.textContent = enlarged ? '还原' : '放大'
+    sizeToggle.setAttribute('aria-pressed', String(enlarged))
+  }
+
+  function onListToggleClick() {
+    if (disposed) return
+    listCollapsed = !listCollapsed
+    syncListToggle()
+  }
+
+  function onSizeToggleClick() {
+    if (disposed) return
+    enlarged = !enlarged
+    syncSizeToggle()
+  }
+
+  function open({ title: heading = '', entries = [], emptyText = '', returnFocus: focusTarget = null } = {}) {
+    if (disposed) return
+    const wasOpen = openState
+    openState = true
+    returnFocus = focusTarget || focusFallback
+    title.textContent = heading
+    renderList(Array.isArray(entries) ? entries : [], emptyText)
+    listCollapsed = false // 换集合重置清单为展开（新集合要看清单）；放大状态保持
+    syncListToggle()
+    resetReader()
+    root.hidden = false
+    if (wasOpen) return // 已打开时换集合：不重复暂停、不动焦点
+    onReadingChange(true)
+    closeBtn.focus()
+  }
+
+  function close() {
+    if (disposed || !openState) return
+    openState = false
+    requestSeq += 1 // 关闭后晚到的响应不能重新打开面板或写正文
+    currentEntry = null
+    clearFrame() // 关面板：停掉图阅读页与它的关闭消息监听（dispose 也不再补发恢复）
+    root.hidden = true
+    onReadingChange(false) // 页面先解除背景 inert，焦点才能落回触发元素
+    const target = returnFocus
+    returnFocus = null
+    if (target && target.isConnected) target.focus?.()
+    else if (focusFallback && focusFallback.isConnected) focusFallback.focus?.()
+  }
+
+  function dispose() {
+    if (disposed) return
+    disposed = true
+    openState = false
+    requestSeq += 1
+    currentEntry = null
+    returnFocus = null
+    clearFrame() // 销毁后旧条目引用/委托不再请求或写 DOM（幂等：clearFrame 重复调用安全）
+    root.removeEventListener('keydown', onRootKeydown)
+    closeBtn.removeEventListener('click', onCloseClick)
+    retryBtn.removeEventListener('click', onRetryClick)
+    list.removeEventListener('click', onListClick)
+    listToggle.removeEventListener('click', onListToggleClick)
+    sizeToggle.removeEventListener('click', onSizeToggleClick)
+    startGuard.removeEventListener('focus', onStartGuardFocus)
+    endGuard.removeEventListener('focus', onEndGuardFocus)
+    entryByButton.clear()
+  }
+
+  function onCloseClick() { close() }
+
+  function onRetryClick() {
+    if (disposed || !openState || !currentEntry) return
+    openEntry(currentEntry) // 重试取当前资料类型：文档重取正文、图重走入口预检
+  }
+
+  const visibleFocusables = () => [...root.querySelectorAll('button:not([disabled]), iframe')]
+    .filter((node) => !node.closest('[hidden]'))
+
+  // 子文档键盘事件不会冒泡到父页：靠原生 Tab 离开 iframe 后到达的边界守卫回环。
+  function onStartGuardFocus() {
+    if (disposed || !openState) return
+    const nodes = visibleFocusables()
+    nodes.at(-1)?.focus()
+  }
+  function onEndGuardFocus() {
+    if (disposed || !openState) return
+    visibleFocusables()[0]?.focus()
+  }
+
+  /** 只在阅读开启时拦截 Escape／Tab，不影响原页面键盘操作。
+   *  焦点循环收可见按钮与可见图 iframe（E9c）：键盘可以进图、离图、到关闭按钮并回环，
+   *  不深入改子页控件。iframe 里的 ESC 由 read.js 经 panel-link.js 转发回来，不在这里处理。 */
+  function onRootKeydown(event) {
+    if (disposed || !openState) return
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      close()
+      return
+    }
+    if (event.key !== 'Tab') return
+    // 只算真正露着的控件（隐藏的重试行、空目录与收起的 iframe 不参与循环）。
+    const focusables = visibleFocusables()
+    if (focusables.length === 0) return
+    const first = focusables[0]
+    const last = focusables[focusables.length - 1]
+    const inside = root.contains(document.activeElement)
+    if (event.shiftKey && (document.activeElement === first || !inside)) {
+      event.preventDefault()
+      last.focus()
+    } else if (!event.shiftKey && (document.activeElement === last || !inside)) {
+      event.preventDefault()
+      first.focus()
+    }
+  }
+
+  /** 条目点击在 list 上一次性委托分发（E3b-2 验收补齐 R1）：只认当前条目表里的
+   *  按钮——换集合后残留的旧按钮、销毁后保存的按钮引用都不处理；资料链接不从
+   *  DOM 重建，entry 永远来自页面交入并经 resolver 验证的集合。 */
+  function onListClick(event) {
+    const button = event.target instanceof Element ? event.target.closest('.material-item') : null
+    if (!button || !list.contains(button)) return
+    const entry = entryByButton.get(button)
+    if (!entry) return
+    void openEntry(entry)
+  }
+
+  root.addEventListener('keydown', onRootKeydown)
+  closeBtn.addEventListener('click', onCloseClick)
+  retryBtn.addEventListener('click', onRetryClick)
+  list.addEventListener('click', onListClick)
+  listToggle.addEventListener('click', onListToggleClick)
+  sizeToggle.addEventListener('click', onSizeToggleClick)
+  startGuard.addEventListener('focus', onStartGuardFocus)
+  endGuard.addEventListener('focus', onEndGuardFocus)
+
+  return {
+    open,
+    close,
+    isOpen: () => !disposed && openState,
+    dispose,
+  }
+}

package/web/assets/rooms/reading-gate.js

@@ -0,0 +1,157 @@
+// 独立房间的阅读暂停闸门（E3b-1）：阅读开始时停住场景的全部操作输入，
+// 阅读结束后仍在原模式、原位置、原视线继续。动画氛围与渲染由场景照常推进，
+// 本模块不冻结画面。只协调输入与帧推进——不读配置、不访问文档、不计算碰撞、
+// 不保存第二份人物位置、不建 Three 渲染器；站位与视线始终留在会话／帧推进器，
+// 模式始终由场景函数切换（本模块只按 getMode() 读，不改模式）。
+//
+// 为什么不能只在页面遮住画面或隐藏按钮：键盘监听仍在（WASD 会继续走动）；
+// OrbitControls 的 enabled=false 也拦不住程序继续 update() 推进阻尼——
+// r186 的 update 不检查 enabled。因此暂停做三件事：
+//   1) 输入器 setEnabled(false)（键盘／拖动／虚拟按键同一道闸）＋clear＋resetClock；
+//   2) OrbitControls disconnect() 结束未完成手势并拆监听，随后用公开接口
+//      消耗残余阻尼并同步回原机位（见 pauseOverview 的步骤注释）；
+//   3) 场景侧 pointerdown/up 在阅读中直接忽略；clearPick 在暂停时清掉未完成
+//      拾取，恢复后不把暂停前的按下与恢复后的抬起拼成新点击。
+
+/**
+ * 建一个阅读暂停闸门。依赖均由场景传入：原版 createWalkInput 句柄、
+ * 已创建并连接的 OrbitControls、行走帧推进器 walk-frame 句柄、读场景当前
+ * 模式的 getMode（'walk'｜'overview'）、清掉未完成拾取的 clearPick。
+ * 返回 { setReading, isReading, syncMode, advance, dispose }。
+ */
+export function createRoomReadingGate({ input, controls, walkFrame, getMode, clearPick }) {
+  let reading = false
+  let disposed = false
+  // 场景创建 controls 时构造函数已自动 connect；这里只记录是否由本闸门断开，
+  // 恢复时按记录重连原 domElement，避免重复连接。
+  let controlsConnected = true
+
+  /** 总览机位快照：相机 position／quaternion／zoom 与 controls.target（暂停前后保持）。 */
+  function snapshotCamera() {
+    const camera = controls.object
+    return {
+      position: camera.position.clone(),
+      quaternion: camera.quaternion.clone(),
+      zoom: camera.zoom,
+      target: controls.target.clone(),
+    }
+  }
+
+  function restoreCamera(snapshot) {
+    const camera = controls.object
+    camera.position.copy(snapshot.position)
+    camera.quaternion.copy(snapshot.quaternion)
+    camera.zoom = snapshot.zoom
+    camera.updateProjectionMatrix?.()
+    controls.target.copy(snapshot.target)
+  }
+
+  /**
+   * 停住总览操作并清掉残余运动，全程同步执行、不渲染中间机位：
+   *  1. 保存机位与设置 → enabled=false → disconnect()（结束未完成手势、
+   *     清指针列表，r186 的 disconnect 会拆监听并把 state 置回 NONE）；
+   *  2. 暂时关掉 autoRotate／enableDamping，update() 一次——无阻尼分支会把
+   *     残余旋转／平移一次应用并在末尾清零，缩放比例重置；残余消耗在临时机位上；
+   *  3. 相机恢复到保存的机位，再以无阻尼／无自动旋转 update() 一次，让控制器
+   *     的内部球坐标与原机位重新对齐——此后没有任何可推进的残余；
+   *  4. 恢复原 enableDamping／autoRotate 设置。只用公开接口，不读写私有字段，
+   *     不调用 reset()／saveState()，不重建相机。
+   */
+  function pauseOverview() {
+    const savedDamping = controls.enableDamping
+    const savedAutoRotate = controls.autoRotate
+    const snapshot = snapshotCamera()
+    controls.enabled = false
+    if (controlsConnected) {
+      controls.disconnect()
+      controlsConnected = false
+    }
+    controls.autoRotate = false
+    controls.enableDamping = false
+    controls.update() // 消耗残余运动（此步可能临时移动相机，不渲染）
+    restoreCamera(snapshot)
+    controls.update() // 从原机位重建控制器内部状态，无残余可推进
+    controls.enableDamping = savedDamping
+    controls.autoRotate = savedAutoRotate
+  }
+
+  /** 按当前模式与阅读状态设输入启用：walk 未阅读→行走进启用、总览停；
+   *  overview 未阅读→OrbitControls 启用、行走停。阅读中一律停用。模式由场景切。 */
+  function syncMode() {
+    if (disposed) return
+    if (reading) {
+      input.setEnabled(false)
+      controls.enabled = false
+      return
+    }
+    if (getMode() === 'walk') {
+      input.setEnabled(true)
+      controls.enabled = false
+    } else {
+      input.setEnabled(false)
+      controls.enabled = true
+    }
+  }
+
+  /**
+   * 暂停（true）或恢复（false）场景操作。重复设置同一值无副作用（不重新保存
+   * 机位、不重复断开/连接监听）；非 boolean 明确抛参数错误且不改变状态。
+   * 恢复不重置机位：总览机位在暂停时原样锁定，行走站位与视线一直在会话／
+   * 帧推进器里；恢复只重连控制器、清空输入并重置计时（首帧 dt=0，不补阅读
+   * 时长，阅读中按下的键不许在恢复后补算）。
+   */
+  function setReading(value) {
+    if (disposed) return
+    if (typeof value !== 'boolean') {
+      throw new TypeError(`setReading 只接受布尔值（实际是 ${value === null ? 'null' : typeof value}）`)
+    }
+    if (value === reading) return
+    reading = value
+    if (value) {
+      input.setEnabled(false) // 键盘／拖动／虚拟按键同一道闸，停用即清空
+      input.clear()
+      walkFrame.resetClock()
+      clearPick?.()
+      pauseOverview()
+    } else {
+      if (!controlsConnected) {
+        controls.connect(controls.domElement)
+        controlsConnected = true
+      }
+      input.clear()
+      walkFrame.resetClock()
+      syncMode()
+    }
+  }
+
+  /** 场景渲染循环唯一的相机推进入口：阅读时两种推进都不做；
+   *  非阅读时 walk 交帧推进器（人物与视线），overview 交 OrbitControls。 */
+  function advance(now) {
+    if (disposed || reading) return
+    if (getMode() === 'walk') walkFrame.frame(now)
+    else controls.update()
+  }
+
+  function isReading() {
+    return !disposed && reading
+  }
+
+  /** 只使闸门失效并停用全部交互——含总览控制器：enabled=false 并主动断开已连接的
+   *  监听（销毁自 overview／非阅读状态时鼠标事件不得再绕过失效的 advance 驱动它）；
+   *  已在阅读中（先前已断开）则不重复主动断开。不调用 controls.dispose、不释放
+   *  场景／渲染器／底座／家具——那些归场景的既有释放路径；不恢复相机、不重连、
+   *  不改模式与站位。销毁后一切调用均为无操作，isReading 返回 false。 */
+  function dispose() {
+    if (disposed) return
+    disposed = true
+    reading = false
+    input.setEnabled(false)
+    controls.enabled = false
+    if (controlsConnected) {
+      controls.disconnect()
+      controlsConnected = false
+    }
+  }
+
+  return { setReading, isReading, syncMode, advance, dispose }
+}

package/web/assets/rooms/room-lighting.js

@@ -0,0 +1,50 @@
+// 空房间风格的公共光照；场景模块不依赖旧建筑蓝图或业务资料。
+import * as THREE from 'three';
+
+export function createRoomLighting(renderer,scene){
+  const group=new THREE.Group(); group.name='room-style-lighting'; scene.add(group);
+  const hemi=new THREE.HemisphereLight(0xe6efff,0x9a896e,2);group.add(hemi);
+  const key=new THREE.DirectionalLight(0xffeed2,3.7);key.position.set(-5,9,4);key.castShadow=true;
+  key.shadow.mapSize.set(2048,2048); Object.assign(key.shadow.camera,{left:-8,right:8,top:7,bottom:-7,near:.1,far:35});
+  key.shadow.bias=-.00025;key.shadow.normalBias=.025;key.shadow.radius=3;group.add(key);group.add(key.target);
+  const fill=new THREE.DirectionalLight(0xd9e7ff,1.4);fill.position.set(4,5,-1);group.add(fill);
+  const bounce=new THREE.DirectionalLight(0xffdbaa,.5);bounce.position.set(1,2,6);group.add(bounce);
+  const studio=new THREE.Scene();studio.background=new THREE.Color(0xbfc4ce);
+  const panel=(w,h,x,y,z,power)=>{const m=new THREE.Mesh(new THREE.PlaneGeometry(w,h),new THREE.MeshBasicMaterial({color:new THREE.Color(power,power*.98,power*.93),side:THREE.DoubleSide}));m.position.set(x,y,z);m.lookAt(0,1,0);studio.add(m);};
+  panel(9,6,-5,8,2,5);panel(5,7,6,3,0,2.2);panel(8,3,0,3,-8,1.5);
+  const pmrem=new THREE.PMREMGenerator(renderer);const env=pmrem.fromScene(studio,.04,.1,40);pmrem.dispose();
+  studio.traverse(o=>{o.geometry?.dispose();o.material?.dispose();});
+  const previousEnv=scene.environment;scene.environment=env.texture;
+  const skyMaterial=new THREE.ShaderMaterial({side:THREE.BackSide,depthWrite:false,uniforms:{top:{value:new THREE.Color('#c9dfed')},horizon:{value:new THREE.Color('#eff0df')},bottom:{value:new THREE.Color('#cddcc4')}},vertexShader:'varying vec3 vWorld; void main(){ vWorld=(modelMatrix*vec4(position,1.)).xyz; gl_Position=projectionMatrix*modelViewMatrix*vec4(position,1.); }',fragmentShader:'varying vec3 vWorld; uniform vec3 top; uniform vec3 horizon; uniform vec3 bottom; void main(){float h=normalize(vWorld).y;vec3 c=mix(horizon,top,smoothstep(0.,.72,h));c=mix(c,bottom,1.-smoothstep(-.5,0.,h));gl_FragColor=vec4(c,1.);\n#include <tonemapping_fragment>\n#include <colorspace_fragment>\n}'});
+  const sky=new THREE.Mesh(new THREE.SphereGeometry(90,32,16),skyMaterial);sky.renderOrder=-10;group.add(sky);
+  const stage=new THREE.Mesh(new THREE.PlaneGeometry(180,180),new THREE.MeshStandardMaterial({color:0xe2e4dc,roughness:1}));stage.rotation.x=-Math.PI/2;stage.position.y=-.46;stage.receiveShadow=true;group.add(stage);
+  const glowCanvas=document.createElement('canvas');glowCanvas.width=128;glowCanvas.height=128;const ctx=glowCanvas.getContext('2d');const grad=ctx.createRadialGradient(64,64,0,64,64,64);grad.addColorStop(0,'rgba(255,244,205,.6)');grad.addColorStop(.18,'rgba(255,238,186,.28)');grad.addColorStop(.5,'rgba(255,220,165,.08)');grad.addColorStop(1,'rgba(255,220,165,0)');ctx.fillStyle=grad;ctx.fillRect(0,0,128,128);
+  const glowTexture=new THREE.CanvasTexture(glowCanvas);glowTexture.colorSpace=THREE.SRGBColorSpace;
+  const celestial=new THREE.Group();celestial.position.set(-6,8,-12);group.add(celestial);
+  const moonMaterial=new THREE.MeshBasicMaterial({color:0xffe5ac});
+  const orb=new THREE.Mesh(new THREE.SphereGeometry(1,48,32),moonMaterial);celestial.add(orb);
+  const halo=new THREE.Sprite(new THREE.SpriteMaterial({map:glowTexture,transparent:true,depthWrite:false,blending:THREE.AdditiveBlending,toneMapped:false}));halo.scale.set(8,8,1);celestial.add(halo);
+  // 月面细节是建筑外的低对比点缀，不作为室内物品。
+  const craters=new THREE.Group();celestial.add(craters);
+  [[-.3,.35,.89,.16],[.32,-.23,.91,.22],[-.2,-.46,.86,.1],[.43,.42,.78,.12],[.05,.65,.75,.08]].forEach(([x,y,z,r])=>{const crater=new THREE.Mesh(new THREE.CircleGeometry(r,24),new THREE.MeshBasicMaterial({color:0xd3be8e,transparent:true,opacity:.21,depthWrite:false}));crater.position.set(x,y,z+.02);crater.lookAt(new THREE.Vector3(x,y,z).multiplyScalar(2));craters.add(crater);});
+  let seed=478;const random=()=>{seed=(seed*1664525+1013904223)>>>0;return seed/4294967296;};
+  const positions=[];for(let i=0;i<120;i++){const a=random()*Math.PI*2,r=25+random()*25;positions.push(Math.cos(a)*r,9+random()*24,Math.sin(a)*r);}
+  const stars=new THREE.Points(new THREE.BufferGeometry().setAttribute('position',new THREE.Float32BufferAttribute(positions,3)),new THREE.PointsMaterial({color:0xffecc4,size:.095,transparent:true,opacity:.75,depthWrite:false,toneMapped:false}));group.add(stars);
+  let style='ceramic',period='day';
+  function set(nextStyle,nextPeriod='day'){
+    style=nextStyle;period=nextPeriod;const fairy=style==='fairy',night=fairy&&period==='night';
+    sky.visible=fairy;stage.visible=!fairy;celestial.visible=fairy;stars.visible=night;craters.visible=night;
+    scene.background=new THREE.Color(night?0x1c263b:fairy?0xd6e3dc:0xe5e6df);
+    scene.fog=fairy?new THREE.Fog(night?0x26364b:0xd7e3d5,26,76):new THREE.Fog(0xe5e6df,35,90);
+    scene.environmentIntensity=night?.20:fairy?.45:.75;
+    hemi.color.set(night?0x92aeed:fairy?0xdbefff:0xe8f1ff);hemi.groundColor.set(night?0x3f3b52:0xb4a27f);hemi.intensity=night?.85:fairy?1.7:2.2;
+    key.color.set(night?0xb4c9ff:fairy?0xffd99d:0xfff1df);key.intensity=night?1.5:fairy?3.1:3.3;
+    key.position.set(night?-5:-4,night?7:9,night?-6:5);key.target.position.set(0,0,0);
+    fill.color.set(night?0x969bde:0xdeeeff);fill.intensity=night?.7:1.1;bounce.color.set(night?0xeebd76:0xffdfa8);bounce.intensity=night?.35:.55;
+    renderer.toneMappingExposure=night?1.1:fairy?1.08:1.02;
+    skyMaterial.uniforms.top.value.set(night?'#111b37':'#a9cfe4');skyMaterial.uniforms.horizon.value.set(night?'#566078':'#f4e6c6');skyMaterial.uniforms.bottom.value.set(night?'#283f47':'#bbcfad');
+    moonMaterial.color.set(night?0xffe5af:0xfff4cb);celestial.scale.setScalar(night?1.05:.7);halo.material.opacity=night?.58:.7;
+  }
+  set('ceramic');
+  return {set,update(t){if(style==='fairy'&&period==='night')stars.material.opacity=.68+Math.sin(t*.4)*.07;},dispose(){scene.remove(group);if(scene.environment===env.texture)scene.environment=previousEnv;env.dispose();const g=new Set(),m=new Set();group.traverse(o=>{if(o.geometry)g.add(o.geometry);if(o.material)m.add(o.material);});g.forEach(v=>v.dispose());m.forEach(v=>v.dispose());glowTexture.dispose();key.shadow.map?.dispose();}};
+}