Document Picture-in-Picture：权限与窗口边界
了解 Document Picture-in-Picture 如何创建同源文档窗口、为何需要用户激活，以及如何保留可访问的页面内回退路径。
BotBrowser Team
BotBrowser 可以在受控 profile 中验证受支持的 Document Picture-in-Picture 控件和关闭后的回退路径，但不能授予浏览器支持、绕过瞬时用户激活、控制窗口位置，也不能保证不同引擎的行为一致。
TL;DR
Document Picture-in-Picture 会在用户操作后打开一个由浏览器管理的同源文档窗口。应把支持和用户激活视为运行时条件，监听窗口关闭，并在请求被拒绝或不可用时保留页面内的同一任务。
内容
API 改变了什么
Document Picture-in-Picture 不同于视频 Picture-in-Picture。应用请求一个新的浏览器管理窗口，并把文档界面放入其中，而不是分离视频轨道。提案描述了 documentPictureInPicture.requestWindow() 和 enter 事件；MDN 将其列为支持范围有限的功能。浏览器允许时，新文档与打开方保持同源，但这不是跨源访问，也不是绕过权限。
产品真正要回答的问题不是浏览器是否暴露了一个全局对象，而是用户当前任务能否在小型辅助界面中继续。控制面板、字幕或参考视图可能适合这个窗口；窗口无法创建时，应用仍应可用。
支持检查与用户激活
功能检测应当范围明确，并绑定真实的点击或键盘激活。不要在页面加载、定时器或无关网络数据变化时请求。若支持、激活、策略或窗口条件不满足，浏览器可能拒绝该 Promise。
async function openPanel(panel) {
if (!('documentPictureInPicture' in window)) return showInline(panel);
try {
const pip = await documentPictureInPicture.requestWindow({ width: 360, height: 240 });
pip.document.body.append(panel);
pip.addEventListener('pagehide', () => showInline(panel), { once: true });
} catch {
showInline(panel);
}
}
这个检查是能力分支，不是浏览器身份信号。不要把完整能力对象发送到分析系统；如确需统计，只保留 opened、unsupported 或 rejected 等结果，并写明用途和保留期限。
窗口生命周期与隐私
辅助文档有自己的生命周期，可能被用户、导航或浏览器关闭。窗口消失时应把任务放回页面，不要把打开状态当作持久存储。只在同源范围内保存完成任务所需的最少状态；分离出来的视图不是私密容器。
同源访问只能协调应用自己的界面，不能检查无关站点。API 不会暴露接收方、用户窗口清单或稳定设备属性。测试应记录请求尺寸、创建是否成功和关闭恢复是否成功，而不是收集历史或窗口标识符。
可访问的回退路径
页面内版本必须能用键盘访问并播报状态变化。按钮应说明面板是否打开，焦点移动要可预测，辅助窗口关闭后要把焦点还给发起控件。回退可以是对话框、折叠区或普通页面段落，但应保留相同操作和取消路径。
用合成内容测试四种结果：支持并打开、支持但被拒绝、不支持，以及显示内容后关闭。BotBrowser 可以在运行器暴露 API 时重复这些受控检查，但不能让引擎强行支持它。比较任务完成和恢复结果，不要承诺所有浏览器窗口行为相同。
兼容性矩阵与尺寸
测试时要分开回答四个问题：浏览器是否暴露 API，用户激活是否仍然有效，Promise 是否创建了可用文档，以及辅助窗口关闭后任务是否回到页面。每种结果需要不同修复：属性不存在时走回退，被拒绝时让用户从按钮重试，窗口创建但样式失效时修复资源，关闭时恢复状态和焦点。请求的宽高只是提示，浏览器可能限制尺寸或改变位置。读取最终 viewport，在狭窄空间使用纵向布局和更大的操作目标。
状态、错误与取消
辅助窗口不能成为唯一状态源。页面应保留选中项和任务状态，只把最小、已脱敏的模型传给新文档。移动节点会改变 owner document，也可能影响样式、事件监听、焦点和表单；应显式初始化和清理面板，并在关闭时移除监听器。测试请求被拒绝、立即关闭、导航、样式表加载失败和依赖不可用。每条路径都应保留原任务、尽量恢复焦点，并在页面内提供相同操作。关闭面板可以是正常取消，不应被当成错误。
隐私与 BotBrowser 验证
发布前要问清复制了哪些数据、脱敏摘要是否足够、缺少支持或请求被拒绝时记录什么，以及任一文档关闭后临时状态如何处理。最多保留带有用途和保留期限的聚合结果（'opened'、'unsupported'、'rejected' 或 'closed'）；不要发送内容、窗口标识、账户、历史记录或完整能力对象。若运行器暴露该 API，BotBrowser 可以用合成内容重复受授权 fixture，比较可见尺寸并验证关闭恢复。这只能说明声明的版本、profile、日期和路径的结果，不代表普遍兼容，也不会授予权限。
发布清单与浏览器更新
确认鼠标和键盘激活、可见关闭控件、焦点恢复、等价页面内回退、窄 viewport、样式资源失败、导航和立即关闭都能工作。浏览器、策略或组件更新后，用相同矩阵重测，每次只改变一个输入。只保存版本、系统族、修订、请求尺寸、激活方式和结果码。引擎之间的差异是这些版本的兼容性事实，不是用户身份，也不是创建持久标识符的理由。
选择回退并重复测试
根据任务选择回退：阅读辅助可以变成带标题和跳转链接的页内侧栏；会议控件可以留在主页面工具栏；字幕可以放进带有明确名称和关闭方式的对话框。复用同一组件逻辑能减少两个窗口之间的差异。不要让回退依赖另一个可选 API 或新增的权限链。如果依赖不可用，应解释影响，同时保留核心操作。
浏览器、策略、焦点或样式变化后，用相同的合成面板、尺寸、激活和关闭流程重复矩阵，每次只改一个输入。记录日期、版本、fixture 修订和结果码。截图能展示关闭后控件是否仍可访问，但不能证明所有环境都兼容。分享前应脱敏姓名与内容。
维护与责任归属
指定一位负责人维护支持检查、生命周期和焦点恢复，再由另一位审查回退与遥测。调查时描述实际观察到的效果，例如“没有用户激活时请求被拒绝”，不要猜测实现原因。用聚合结果区分不支持与激活回归，改变回退之前先重跑 fixture。工单和日志不需要用户正文或持久身份标识。
结论
Document Picture-in-Picture 是用户介导的展示界面，不是权限捷径或身份信号。以支持和激活为条件，处理关闭恢复，减少遥测，并保留可访问的页面内路径，才能在不制造隐私承诺的情况下使用它。