# ADR-0004 — 预览面板以独立文档侧边栏停靠

日期：2026-09-08。状态：采用。

## 决策背景

用户提供当前页面截图，要求右侧像 Harness 左侧导航一样展开、收起，并在右上
「工作区文档」位置使用相应的面板按钮。之前的纯覆盖预览面板不能同时让出对话空间。

锁定基线的 `ILayout` 只公开左栏开合和工具详情开合，`details` 已被原生工具详情
占用；`root` 和 `conversation` 同样为已占用的 single Slot。替换这些贡献会改变
宿主功能。`shell.overlay` 是现有可叠加贡献入口，但不提供空间预留 API。

## 决策

仍从 `shell.overlay` 注册预览面板。一个独立、可释放的 DOM 适配器从此贡献的
锚点定位锁定基线的 `[data-shell-overlay]` 及其 frame 父元素；仅临时限制 frame
的 `max-width`，让原生 `AppFrame` 的 ResizeObserver 重新计算列宽。可用宽度取
frame 的实际 containing block，跳过真实 renderer 的 `display: contents` 包裹。
面板经 baseline 的 React DOM portal 呈现在该宿主根容器内，位置与容器对齐，
不被 frame 的 overflow 裁切；仍处在原生设置/引导弹层管理的 `#root` inert 边界内。
不搬移宿主 DOM，不更换 Slot 贡献，不访问其他 feature 的运行时模块或私有状态。

- ≥1056px：正常宽度停靠，至少给宿主留 696px（原生收起导航 56px + 对话 640px）。
- 更窄或最大化：恢复宿主宽度，面板覆盖展开；手动宽度偏好保持不变。
- 会话头部回形针图标开合工作区浏览，面板右上 × 关闭；2026-09-08 根据用户
  人工截图反馈区分入口与关闭图标。关闭继续经过既有未保存守卫，关闭后焦点返回入口。
- 收起、卸载、替换均恢复此前的 inline max-width（含 priority）；断开 observer、
  移除监听并取消待执行的 rAF。仅撤销自身仍持有的样式值。
- 若挂载位置或测量不可用，保留覆盖面板能力，不修改猜测出来的宿主元素。

## 影响与验收

这是锁定基线的 DOM 兼容适配，不是 Harness 的公共布局 API。升级基线必须重新
验证该锚点、父子关系、frame 的自身尺寸观察，以及原生左右栏的共存行为。未来有
公共侧边栏注册接口时，以该接口替换适配器。

自动化覆盖开合、宽度预留、窄屏/最大化恢复、原生 frame 的列宽响应、未保存守卫、
焦点返回及卸载清理。真实浏览器仍需验证：左右栏同时开合、拖宽、工具详情共存、
浅/深主题和缩放；自动化 DOM 测试不能替代截图验收。