diff --git a/docs/adr/0008-codex-startup-shadow-and-composer-surface.md b/docs/adr/0008-codex-startup-shadow-and-composer-surface.md
new file mode 100644
index 0000000..2bfb35c
--- /dev/null
+++ b/docs/adr/0008-codex-startup-shadow-and-composer-surface.md
@@ -0,0 +1,32 @@
+# ADR 0008：Codex 初始化阴影与输入区装饰层
+
+- 日期：2026-10-23
+- 状态：接受
+- 范围：Codex adapter；保持现有背景档案、存储键及其他客户端行为。
+
+## 问题与证据
+
+用户报告初始化阴影与设置不符，并提供输入框外围黑色矩形截图。
+现场 Codex 包版本为 26.1016.6573.0，CDP 与探索下的背景入口可识别。
+读取现场时保存值、API、根节点 CSS 变量及清单都为 46%，背景未活动；这次快照不代表已经复现真实客户端的启动时序。
+
+浏览器回归使用真实媒体载荷，复现两个初始化缺口：只有控制台负责恢复阴影，独立媒体启动不恢复；宿主替换 html.style 后，界面仍显示 46%，媒体阴影却回到 0%。
+现场还发现 composer 后有空的、不可交互、绝对定位的 bg-surface 元素；现有样式没有清除它的底色，与用户截图一致。生成的 CSS 模块哈希不作为适配契约。
+
+## 决定
+
+将阴影偏好的读取、校验、持久化及 CSS 同步移入独立 dim.js，媒体初始化前安装，控制台仅调用同一 API。继续使用 beauticode-dim 存储键与 0～1 值域，0 是有效设置，非法值回退自动。
+
+只监听 html 的 style 与 data-bc-dim-user 属性。幂等写入避免自身触发循环；重复安装复用同版本实例，替换版本释放旧监听。窗口关闭结束生命周期，清除媒体保留用户偏好供下次应用。自动滑块位置分别对应深色 0%、浅色 48%。
+
+只在背景活动时，将 main 内底部定位容器的空、不可交互 bg-surface 子装饰层设为透明。输入框、对话框和其他 surface 保留底色；清除背景恢复宿主样式。不引入通用 surface 透明规则。
+
+2026-10-26 补充：用户继续报告输入框上方的黑色渐变。现场确认它属于 thread-scroll-container 内 sticky bottom-0 页脚的空、不可交互、横向绝对定位 from-surface 子层；实际背景为从 #181818 到透明的线性渐变。旧的 bg-gradient-to-t/from-token-main-surface-primary 规则不匹配该结构。新增仅针对这一布局职责的规则，不依赖 _background_ / _fade_ 生成类名，不改变有内容的节点、非粘滞结构或聊天区之外的渐变。背景清除后由 data-bc-active 门控恢复宿主渐变。
+
+## 验证与边界
+
+appearance.browser.test.js 使用 Edge 实际渲染，覆盖首次恢复、根样式替换、零值、非法值、浅深色、清除偏好不重建舞台及输入区边界。通过 BEAUTICODE_PLAYWRIGHT_MODULE 指向已有 Playwright 运行时；没有运行时时显式跳过，不添加发布依赖。
+
+其他客户端现场均未运行，安装状态不能代表新版 DOM 验收。另一个已有五端浅色检查发现，四个非 DSH 客户端默认 48% 白色遮罩在纯黑壁纸上只有约 3.75:1 对比度，本次保留既有亮度策略，未将其宣称为通过。
+
+回滚可恢复安装目录 current.json 指向上一版本，再重启 beautiCode 辅助进程；无需重启或修改 Codex 二进制。源码回滚同时恢复 payload、console、CSS 并移除 dim.js，原存储键无需迁移。
diff --git a/docs/adr/0009-codex-wallpaper-surface-and-guest-lifecycle.md b/docs/adr/0009-codex-wallpaper-surface-and-guest-lifecycle.md
new file mode 100644
index 0000000..eb5620c
--- /dev/null
+++ b/docs/adr/0009-codex-wallpaper-surface-and-guest-lifecycle.md
@@ -0,0 +1,101 @@
+# ADR 0009：Codex 壁纸外壳与 guest 生命周期
+
+- 日期：2026-10-24
+- 状态：接受；现场与自动化证据的范围分别列于验收记录。
+- 基线：main aea3220；来源 PR #96 head d5f3252。
+- 关联：[实施与验收记录](../pr96-owner-completion.md)、PR #96。
+
+## 问题与现场事实
+
+PR 把原生圆角、tooltip、功能浮层、内容路由和 guest 注入混在两个文件中。
+固定浅色背景与宿主深色文字体系冲突；同代次短路前创建观察器会泄漏。
+尺寸扫描不能辨认页面外壳和阅读底板，直接修改内联背景还必须保存声明优先级。
+
+26.1016.6573.0 的宿主静态资源声明 /plugins、/library、/sites、/images 原生路由。
+实际切页也确认这些入口在宿主文档呈现；不能据路由声明推断所有版本均无 webview。
+当前存在独立的定价预热 webview：src 是 about:blank，toUrl 是相对路径，实际地址为 chatgpt.com。
+因此排除 sandbox 或仅限制 chatgpt.com 都不能形成正确的页面边界。
+支付与工作区设置资源还包含独立 webview 流程，本适配不进入这些流程。
+
+站点页的外壳由 workspace slot、全高 bg-surface、contents、滚动容器及居中 tabpanel 构成。
+资料库复用滚动标题结构，但不具有站点页的全高 bg-surface 根节点。
+两者的标题底板是滚动内容标题壳的 ::before；清理 h1 本身无效。
+真实 DOM 中存在生成类名，但它们只作为调查证据，不作为本次适配选择器。
+
+## 决策
+
+### 宿主样式
+
+只删除 beautiCode 对左栏、main 和首页卡片圆角的清零，保留宿主实际圆角。
+当前宿主部分外层原生圆角为 0；本修复不承诺把这些外层改成指定像素。
+普通 tooltip 保留原生底色与前景；Radix 定位壳透明，真正菜单面板保留主题底色。
+浮层及 sidebar peek 使用 --bc-readable-fill；peek 仅裁切并修正直接底板，沿用宿主圆角。
+所有新浮层规则排除 beautiCode 自身 UI 及其后代。
+
+保留 ADR 0008 的空、非交互 composer 装饰层规则。
+原生页面只匹配观测到的 workspace/滚动/标题/tabpanel 结构。
+不清空所有 bg-surface，不使用视口大小推断语义，也不新增生成类名兜底。
+布局契约失效时保持宿主底板，而不是回退到更宽泛的透明规则。
+
+### 模块与所有权
+
+媒体入口只负责代次、组合、舞台及销毁；工作态、用户播放偏好、媒体来源、图片、
+视频节点、就绪/重试和既有 API 分别拥有状态。
+图片与视频附件均需要可取消的原生事件等待，因此复用小型 media-wait 模块。
+销毁会取消等待并解绑事件；旧图片完成后不能更新下一代根属性。
+公开七个注入参数、既有方法名及健康快照字段保持不变。
+修正偏好恢复调用：沿用已有 isBackgroundTone 方法，不新增兼容别名。
+模块通过操作、只读 getter 和回调协作，不共享可变状态包。
+
+payload 在注入表达式的词法作用域内组合工厂，避免浏览器端 ESM/CSP 或新增全局注册框架。
+主入口从约 2022 行降到不足 400 行，新增媒体与 guest 模块均小于 500 行。
+保留现有 renderer 资产复制和插件打包机制，不引入运行时依赖。
+
+### guest 契约与生命周期
+
+guest 控制器内部接口为 setActive(boolean)、sync()、dispose()。
+同一文档同版本复用；媒体交接不捕获旧代次闭包，完整销毁释放实例。
+未激活时不创建宿主观察器，也不绑定 guest 事件或注入 CSS。
+
+条件允许的内容根路由仅 /plugins、/library、/sites、/images。
+还要求宿主 main 中的已连接 webview、about:blank 的预期路径和当前 HTTPS
+chatgpt.com 精确路径一致；不接受端口、用户凭据、相似域名或任意子路径。
+prewarm、sandbox、定价/结算/工作区 partition 及所有未知路由均拒绝。
+/pricing-plan、/checkout、/admin、认证流程和未验证的 /plans 不在允许表中。
+查询参数不作为账号授权依据，不将它们写入日志。
+
+“候选页面”只允许绑定就绪事件，只有实际地址通过校验才可注入。
+dom-ready、主框架导航、页内导航与动态挂载均重新检查。
+不支持或尚未验证的版本保持原生；没有合适现场实例时不得宣称 guest 现场验收通过。
+
+用 Electron insertCSS/removeInsertedCSS 的键管理根外壳样式。
+guest 自身表单、卡片、弹层及主题变量不改写；不安装 guest DOM 观察器、不改内联背景。
+样式只涉及 html/body 及直接根节点，内层没有已验证契约时不扩展清理范围。
+宿主视图使用宿主 CSS 处理其原生内层外壳。
+
+每个登记实例只有一个未完成插入调用；操作版本随导航、清除和销毁递增。
+过期结果通过自己的样式键撤销，不能删除重新激活后的新样式。
+旧调用阻塞过新文档时，完成后只为变化过的版本补同步一次；拒绝/超时不无限重试。
+超时为 3000ms。Electron Promise 不能真正取消；超时保留原生显示并诊断，
+迟到的成功结果仍会回收，底层 Promise 永不完成时不再堆积新调用。
+清理依赖登记表，能够处理已脱离 DOM 的 webview。
+撤销 API 拒绝时给出阶段/类别诊断，不能把 API 失败宣称为成功恢复。
+
+## 验证与限制
+
+Node 测试覆盖边界、候选就绪、动态新增/移除、100 次实例复用、清理竞态、超时、
+错误脱敏、视频交接后永久错误和图片取消。
+真实 Edge 浏览器执行完整载荷，覆盖主题切换、圆角、保留阅读卡片、媒体和交接；
+最终 Codex 插件包内载荷重复执行同组关键回归。
+合成浏览器中的 webview API 替身不是 Electron 现场证明。
+真实客户端检查仅临时替换 CSS，检查原生内容页后恢复；不安装新运行时或修改媒体档案。
+详细通过数、截图、采样视频及未验收边界见实施记录。
+
+## 演进与回滚
+
+宿主变更后先更新脱敏 DOM 样例和对应回归，再调整结构或允许表。
+新增 guest 页面必须有真实 URL、身份及根外壳证据，不扩大域名或尺寸扫描兜底。
+现有日志不会包含正文、账号或完整 URL。
+本次不改存储键及档案协议；回滚本组提交并重新打包即可恢复旧运行时。
+若已经安装某个包，应先停止该包的辅助注入进程，再切换到上一包，避免两代注入竞争；
+不修改 Codex 二进制，也无需数据迁移。
diff --git a/docs/pr96-owner-completion.md b/docs/pr96-owner-completion.md
new file mode 100644
index 0000000..e11c54e
--- /dev/null
+++ b/docs/pr96-owner-completion.md
@@ -0,0 +1,130 @@
+# PR #96：owner 实施与验收记录
+
+日期：2026-10-24。基线 origin/main aea32209f02de0e14b7248ac870f5868e195d167；
+来源 PR head d5f3252，经执行前在线复核未变。
+
+实施位于附加 worktree 的 codex/pr96-owner-completion 分支。
+原 E:/WoRk/beautiCode 工作区未修改；其 tracked patch 与 untracked 文件先复制后整合，
+包括阴影恢复、空 composer 装饰层、相关浏览器测试及 ADR 0008。
+其他复制的本地 DSH 文档/脚本不属于本次新增实现，不混入本次修复提交。
+实施与初次验收阶段未发布、推送或合并，也未把新运行时安装到用户应用。
+
+2026-10-26 提交准备：远程主线已通过 405fd81 合并 #96，本分支同步该主线，
+作为后续修复提交。冲突仅涉及旧运行时和 CSS；保留本分支已验证的新控制器、
+模块拆分和精确样式规则，没有重新引入被替换的尺寸扫描或宽泛透明规则。
+同步后重新执行类型检查及全仓测试：435 通过、20 显式跳过、0 失败；
+串行执行两组真实 Edge 浏览器回归共 9 项，全部通过、零跳过。
+对应日志为 pr-submission-typecheck.log、pr-submission-tests.log、pr-submission-browser.log。
+
+## 已实现
+
+- 保留宿主圆角与普通 tooltip 配色；定位壳透明，菜单/浮层/peek 随宿主主题。
+- 排除 beautiCode 自身 UI；保留输入框、普通卡片和无关 aside 底色。
+- 按现场结构清理站点的三层外壳及资料库/站点的标题伪元素，不新增生成类名选择器。
+- 媒体按职责拆分，修改后的主运行时及新增模块小于 500 行；既有大测试文件也按职责分拆。
+- guest 按预期/实际地址和宿主插槽验证；支付、预热、认证、sandbox 与未知页面保持原生。
+- 样式键替代内联修改和尺寸扫描；登记表管理事件、观察器和异步操作。
+- 同代次复用、交接、完整清除、销毁、动态节点、导航期间延迟完成均有行为回归。
+- 修正旧有图片等待取消及色调读取方法不一致，保留原公开方法。
+
+架构与明确的允许/拒绝规则见 [ADR 0009](adr/0009-codex-wallpaper-surface-and-guest-lifecycle.md)。
+
+## 实施过程与可复现证据
+
+基线 Codex：74 通过、5 跳过、0 失败；显式浏览器基线 4 通过、0 跳过。
+失败先于修复的记录保存在 artifacts/pr96/：
+
+| 失败证据 | 检查内容 |
+| --- | --- |
+| red.log | 固定样式、未实现 guest 行为 |
+| guest-readiness-red.log | about:blank 候选页面需要等待 dom-ready |
+| handoff-error-red.log | 交接已结束后，永久视频错误不能继续 pending |
+| navigation-race-red.log | 旧插入调用不能阻断新文档注入 |
+| image-cancel-red.log | 已销毁的图片附件不能更新下一代 |
+| guest-timer-red.log | 销毁必须释放插入超时计时器 |
+| owned-ui-red.log | 自有 UI 的嵌套浮层也必须排除 |
+| header-red.log / library-header-red.log | 清 h1 无效，且 Library 与 Sites 外壳不同 |
+| tone-red.log | 通过已有公开方法恢复色调偏好 |
+
+独立只读审查发现并复现 handoff 快照和 pending 导航收敛两项 Important；
+均已按失败测试→修复→通过完成，未发现 Critical。
+首次视频测试的 MediaRecorder 只产生文件头，原生 video 也无法解码；
+补充真实帧录制后才用于运行时验收，没有通过放宽断言绕过失败。
+
+## 自动化验收
+
+| 检查 | 结果 / 原始日志 |
+| --- | --- |
+| 全仓类型检查 | 通过；typecheck.log |
+| 全仓构建 | 通过；build.log |
+| 全仓最终确认 | 435 通过、19 跳过、0 失败；full-test-confirmation.log |
+| 最新 Codex 测试 | 106 通过、9 跳过、0 失败；adapter-final.log |
+| 完整载荷 Edge 浏览器 | 8 通过、0 跳过；browser-final.log |
+| 最终插件包内完整载荷 | 4 通过、0 跳过；packaged-browser.log |
+| 打包模块加载/语法 | 进入必跑 Node 测试，未遗漏私有模块 |
+| 空白与规模检查 | git diff --check；主入口及新运行时模块均不超过 500 行 |
+
+浏览器回归直接执行 loadRendererSource/buildInjectionExpression 产生的真实载荷，
+覆盖浅→深→浅、圆角、tooltip、peek、自有 UI、原生路由外壳及普通阅读卡片，
+以及真实视频解码、交接、静音、定位、摸鱼、色调继承和清除。
+包内验证通过 BEAUTICODE_RENDERER_PAYLOAD 指向 staged vendor/payload.js，
+不是只检查源文件字符串或包文件清单。
+
+全仓复跑曾在未修改的 DSH pack.test.mjs 出现一次 Node 测试器
+“Unable to deserialize cloned data due to invalid or unsupported version”。
+DSH 单独重跑 122 通过、10 跳过、0 失败，记录为 dsh-recheck.log；
+该异常记录保留为 full-test-final.log，不将其抹掉或归因于已证实的业务缺陷。
+最后一轮全仓确认 435 通过、19 跳过、0 失败，见 full-test-confirmation.log。
+
+## 真实客户端与视觉边界
+
+现场版本：Codex Desktop 26.1016.6573.0 / Windows，深色主题。
+通过当前 9335 CDP 读取 DOM/静态资源、切换内容入口并临时替换壁纸 CSS；
+finally 恢复原 CSS，并恢复本聊天，没有改动背景档案或安装包。
+
+- Plugins、Library、Sites、Images 均实际打开并采集截图。
+- Sites 的根外壳、内容容器、tabpanel 背景确认透明；普通卡片保留自身外观。
+- 初次截图暴露 Library 标题仍不透明，随后增加独立结构样例及回归再修复。
+- sandbox 未绑定旧式透明事件；定价预热保持排除。
+- 外层 sidebar 在本版本原生值可为 0px；保留原生不是强制增加圆角。
+
+截图：artifacts/pr96/live-route-0.png 至 live-route-3.png，
+合成但真实渲染的主题对照：fixture-dark.png、fixture-light.png。
+navigation-00.png 至 navigation-05.png 是实际切页采样；
+navigation-sampled.webm 是这六帧的回放，不是连续录屏，不能证明采样间绝无闪烁。
+原始无正文结构快照及结果为 live-*.json / live-css-results.json。
+这些本地证据位于忽略目录，不随提交公开。
+
+未宣称通过的范围：
+
+- 用户应用的浅色主题：已在真实 Edge + 脱敏结构中覆盖，未现场更改用户主题设置。
+- 允许的 Electron guest 现场：当前目标入口为原生页面，只有被排除的预热 guest；
+  不能把 API 替身测试或方法存在当作此项现场验收。
+- Plans/结算/认证等未验证页面：保留原生，不扩大透明范围。
+- 未安装旧版客户端，没有将本版本结论推广至 PR 描述的旧版本。
+
+## 2026-10-26 输入框上方渐变补充
+
+现场定位并清除了聊天滚动区粘滞页脚的空 from-surface 渐变层。
+当前窗口应用独立、带背景活动门控的样式修正；不修改安装包，窗口重载后须由更新的载荷重新注入。
+读取修正前后的计算样式：渐变由 linear-gradient 变为 none，输入框仍为 rgb(31, 31, 31)。
+截图 composer-fade-after.png 与脱敏计算结果 composer-fade-live.json 位于本地 artifacts/pr96。
+新增回归先失败后通过，覆盖浅→深→浅、相似元素不受影响及 dispose 后恢复。
+appearance 浏览器测试实际执行 5 项，全部通过、零跳过（composer-fade-browser.log）。
+本次全仓复跑为 435 通过、20 显式跳过、0 失败（composer-fade-full-test.log）；
+新打包 CSS 与源码 SHA256 一致。包内载荷浏览器测试首次视频用例仅录得 171 字节文件头而失败，
+未改测试或运行时代码，原样复跑 4 项全部通过、零跳过。
+首次失败与复跑日志分别为 composer-fade-packaged-browser.log、composer-fade-packaged-recheck.log；
+这是现有实时录制样例的时序波动，不能将该次首次执行记为通过。
+
+## 复跑
+
+从仓库根运行 npm run typecheck、npm test、npm run build。
+浏览器测试使用现有 BEAUTICODE_PLAYWRIGHT_MODULE，Windows 下赋值为 file:/// 模块 URL，
+运行 node --test packages/adapter-codex/test/appearance.browser.test.js
+packages/adapter-codex/test/wallpaper.browser.test.js。
+未配置该变量时浏览器测试会显式跳过，不能算视觉通过。
+
+运行 node scripts/pack-codex-plugin.mjs --no-build 后，
+将 BEAUTICODE_RENDERER_PAYLOAD 指向包内 vendor/adapter-codex/payload.js 的 file URL，
+再运行 wallpaper.browser.test.js 即可验证最终载荷。
diff --git a/packages/adapter-codex/src/payload.ts b/packages/adapter-codex/src/payload.ts
index a85148d..5411daa 100644
--- a/packages/adapter-codex/src/payload.ts
+++ b/packages/adapter-codex/src/payload.ts
@@ -10,16 +10,36 @@ export async function loadRendererSource(): Promise<{
   runtimeIife: string;
   consoleSource: string;
 }> {
-  const [cssText, runtimeIife, consoleJs, galleryJs, themeJs] = await Promise.all([
+  const [cssText, runtimeIife, consoleJs, galleryJs, themeJs, dimJs] = await Promise.all([
     fs.readFile(path.join(here, "renderer", "background.css"), "utf8"),
     fs.readFile(path.join(here, "renderer", "background-runtime.js"), "utf8"),
     fs.readFile(path.join(here, "renderer", "console.js"), "utf8"),
     fs.readFile(path.join(here, "renderer", "gallery.js"), "utf8"),
     fs.readFile(path.join(here, "renderer", "theme.js"), "utf8"),
+    fs.readFile(path.join(here, "renderer", "dim.js"), "utf8"),
   ]);
-  // Resolve host appearance after media installs, including healthy re-injects.
-  const themedRuntime = `((...args) => Promise.resolve((${runtimeIife})(...args)).then(result => { ${themeJs}\nreturn result; }))`;
-  return { cssText, runtimeIife: themedRuntime, consoleSource: `${consoleJs}\n${galleryJs}` };
+  const factories = {
+    createWorkingState: "runtime-working.js",
+    createPlaybackControls: "runtime-controls.js",
+    createMediaSources: "runtime-sources.js",
+    createMediaWaiter: "runtime-media-wait.js",
+    createImageRuntime: "runtime-image.js",
+    createVideoLifecycle: "runtime-video-lifecycle.js",
+    createVideoElementBinding: "runtime-video-element.js",
+    createVideoRuntime: "runtime-video.js",
+    createBackgroundApi: "runtime-api.js",
+    createGuestPolicy: "guest-policy.js",
+    createGuestController: "guest-wallpaper.js",
+    createGuestOwner: "guest-install.js",
+  };
+  const modules = await Promise.all(Object.entries(factories).map(async ([name,file]) =>
+    `const ${name} = ${await fs.readFile(path.join(here,"renderer",file),"utf8")};`));
+  // Factories remain lexical to the injected payload. Only the document-scoped
+  // guest owner survives media handoffs; modules expose operations, not state bags.
+  const themedRuntime = `((...args) => { ${dimJs}\n${modules.join("\n")}
+    const guest = createGuestOwner({createController:createGuestController,policy:createGuestPolicy()});
+    return Promise.resolve((${runtimeIife})(...args)).then(result => { ${themeJs}\nreturn result; }); })`;
+  return { cssText, runtimeIife: themedRuntime, consoleSource: `${dimJs}\n${consoleJs}\n${galleryJs}` };
 }
 
 /** 1×1 PNG. Video injects must not ship the live poster as a multi-MB data URL. */
diff --git a/packages/adapter-codex/src/renderer/background-runtime.js b/packages/adapter-codex/src/renderer/background-runtime.js
index 30d0ab1..3ab6818 100644
--- a/packages/adapter-codex/src/renderer/background-runtime.js
+++ b/packages/adapter-codex/src/renderer/background-runtime.js
@@ -20,2198 +20,370 @@
  * So media MUST arrive as data: or blob: URLs.
  */
 ((cssText, imageDataUrl, videoConfig, generation, imageUrl, forceRebuild, imageBlob) => {
-  const STAGE_ID = "beauticode-bg-stage";
-  const STYLE_ID = "beauticode-bg-style";
-  const VIDEO_INPUT_ID = "beauticode-video-input";
-  const IMAGE_INPUT_ID = "beauticode-image-input";
-  const gen = Number(generation) || 0;
-  const wantImageBlob = Boolean(imageBlob);
-
-  const toChineseMediaError = (error) => {
-    const message = String(error?.message || error || "").trim();
-    if (/^(?:failed to fetch|fetch failed|fail fetch)$/i.test(message)) {
-      return "未发现注入CDP的Codex进程";
-    }
-    if (/media fetch failed/i.test(message)) {
-      return "背景媒体加载失败。";
-    }
-    if (/data url fetch failed/i.test(message)) {
-      return "背景数据加载失败。";
-    }
-    if (/missing (?:media )?url|no video source/i.test(message)) {
-      return "背景媒体地址缺失。";
-    }
-    if (/malformed data url/i.test(message)) {
-      return "背景数据地址格式错误。";
-    }
-    if (/stale generation/i.test(message)) {
-      return "背景版本已过期，正在重新加载。";
-    }
-    return message || "背景媒体加载失败。";
-  };
-
-  const root = document.documentElement;
-  const previous = window.__BEAUTICODE_BG__;
-
-  // Full-page ChatGPT routes (Plugins, Skills, Library, Plans) live in an
-  // Electron <webview>. Host CSS cannot cross that document boundary, so clear
-  // the guest's opaque shell tokens from the host through executeJavaScript.
-  // Controls keep their own borders and foregrounds; only page-sized surfaces
-  // are made transparent so the full-window wallpaper remains the base layer.
-  const GUEST_STYLE_ID = "beauticode-guest-wallpaper-style";
-  const GUEST_CSS = `
-    html, body, body > #root, body > #__next {
-      background: transparent !important;
-      background-color: transparent !important;
-      background-image: none !important;
-    }
-  `;
-  const guestExpression = `(() => {
-    const id = ${JSON.stringify(GUEST_STYLE_ID)};
-    let style = document.getElementById(id);
-    if (!style) {
-      style = document.createElement("style");
-      style.id = id;
-      (document.head || document.documentElement).appendChild(style);
-    }
-    style.textContent = ${JSON.stringify(GUEST_CSS)};
-    const ATTR = "data-beauticode-guest-cleared";
-    const paint = () => {
-      if (!document.body) return;
-      const vw = window.innerWidth || 1;
-      const vh = window.innerHeight || 1;
-      const visit = (el, depth) => {
-        if (!(el instanceof HTMLElement) || depth > 6) return;
-        if (!el.hasAttribute(ATTR)) {
-          const rect = el.getBoundingClientRect();
-          if (rect.width >= vw * 0.9 && rect.height >= vh * 0.9) {
-            const bg = getComputedStyle(el).backgroundColor;
-            if (bg && bg !== "transparent" && bg !== "rgba(0, 0, 0, 0)") {
-              el.setAttribute(ATTR, el.style.backgroundColor || "");
-              el.style.setProperty("background-color", "transparent", "important");
-            }
-          }
-        }
-        for (const child of el.children) visit(child, depth + 1);
-      };
-      for (const child of document.body.children) visit(child, 0);
-    };
-    paint();
-    if (!window.__beauticodeGuestObserver) {
-      const observer = new MutationObserver(() => {
-        if (window.__beauticodeGuestPaintTimer) return;
-        window.__beauticodeGuestPaintTimer = setTimeout(() => {
-          window.__beauticodeGuestPaintTimer = 0;
-          try { paint(); } catch (_) {}
-        }, 300);
-      });
-      observer.observe(document.documentElement, { childList: true, subtree: true });
-      window.__beauticodeGuestObserver = observer;
-    }
-    return true;
-  })()`;
-  const clearGuestExpression = `(() => {
-    document.getElementById(${JSON.stringify(GUEST_STYLE_ID)})?.remove();
-    try {
-      window.__beauticodeGuestObserver?.disconnect();
-      window.__beauticodeGuestObserver = null;
-      if (window.__beauticodeGuestPaintTimer) {
-        clearTimeout(window.__beauticodeGuestPaintTimer);
-        window.__beauticodeGuestPaintTimer = 0;
-      }
-    } catch (_) {}
-    document.querySelectorAll("[data-beauticode-guest-cleared]").forEach((el) => {
-      const prev = el.getAttribute("data-beauticode-guest-cleared");
-      el.removeAttribute("data-beauticode-guest-cleared");
-      if (prev) el.style.backgroundColor = prev;
-      else el.style.removeProperty("background-color");
-    });
-    return true;
-  })()`;
-  const guestTransparencyAllowed = (webview) => {
-    try {
-      const src = webview.getAttribute("src") || "";
-      return !src.startsWith("codex-sandbox:");
-    } catch (_) {
-      return false;
-    }
-  };
-  const installGuestTransparency = (webview) => {
-    if (
-      !webview ||
-      !guestTransparencyAllowed(webview) ||
-      typeof webview.executeJavaScript !== "function"
-    ) {
-      return;
-    }
-    try {
-      const result = webview.executeJavaScript(guestExpression);
-      if (result && typeof result.catch === "function") result.catch(() => {});
-    } catch (_) {}
-    if (!webview.__beauticodeGuestTransparencyBound) {
-      webview.__beauticodeGuestTransparencyBound = true;
-      const refresh = () => installGuestTransparency(webview);
-      webview.__beauticodeGuestTransparencyRefresh = refresh;
-      try { webview.addEventListener("dom-ready", refresh); } catch (_) {}
-      try { webview.addEventListener("did-finish-load", refresh); } catch (_) {}
-    }
-  };
-  const syncGuestTransparency = () => {
-    try {
-      document.querySelectorAll('webview:not([src^="codex-sandbox:"])')
-        .forEach(installGuestTransparency);
-    } catch (_) {}
-  };
-  const clearGuestTransparency = () => {
-    try {
-      document.querySelectorAll("webview").forEach((webview) => {
-        if (!webview.__beauticodeGuestTransparencyBound) return;
-        if (typeof webview.executeJavaScript === "function") {
-          try {
-            const result = webview.executeJavaScript(clearGuestExpression);
-            if (result && typeof result.catch === "function") {
-              result.catch(() => {});
-            }
-          } catch (_) {}
-        }
-        const refresh = webview.__beauticodeGuestTransparencyRefresh;
-        if (refresh) {
-          try { webview.removeEventListener("dom-ready", refresh); } catch (_) {}
-          try {
-            webview.removeEventListener("did-finish-load", refresh);
-          } catch (_) {}
-        }
+    const STAGE_ID = "beauticode-bg-stage";
+    const STYLE_ID = "beauticode-bg-style";
+    const VIDEO_INPUT_ID = "beauticode-video-input";
+    const IMAGE_INPUT_ID = "beauticode-image-input";
+    const gen = Number(generation) || 0;
+    const wantImageBlob = Boolean(imageBlob);
+    const root = document.documentElement;
+    const previous = window.__BEAUTICODE_BG__;
+    // ---- Same-generation short-circuit (critical anti-flash) ----
+    // The tray watch loop re-publishes the active payload every ~1s. Rebuilding
+    // the stage on every poll creates stacked <video> nodes + poster flashes.
+    if (!forceRebuild &&
+        previous &&
+        previous.generation === gen &&
+        typeof previous.snapshot === "function") {
         try {
-          webview.__beauticodeGuestTransparencyBound = false;
-          delete webview.__beauticodeGuestTransparencyRefresh;
-        } catch (_) {}
-      });
-    } catch (_) {}
-  };
-  const isBackgroundActive = () =>
-    root.getAttribute("data-bc-active") === "true";
-  let guestSyncTimer = null;
-  const scheduleGuestSync = () => {
-    if (!isBackgroundActive() || guestSyncTimer) return;
-    guestSyncTimer = setTimeout(() => {
-      guestSyncTimer = null;
-      if (isBackgroundActive()) syncGuestTransparency();
-    }, 200);
-  };
-  let guestObserver = null;
-  try {
-    guestObserver = new MutationObserver((records) => {
-      for (const record of records) {
-        if (
-          record.type === "attributes" &&
-          record.target instanceof Element &&
-          record.target.tagName === "WEBVIEW"
-        ) {
-          scheduleGuestSync();
-          return;
+            const snap = previous.snapshot();
+            const wantsVideo = Boolean(videoConfig &&
+                typeof videoConfig === "object" &&
+                (videoConfig.mode === "blob" ||
+                    videoConfig.dataUrl ||
+                    videoConfig.srcUrl ||
+                    videoConfig.url));
+            const wantsClear = !imageDataUrl && !imageUrl && !wantsVideo && !wantImageBlob;
+            const healthyVideo = wantsVideo &&
+                snap &&
+                snap.active &&
+                snap.videoReady &&
+                !snap.videoFailed &&
+                snap.hasVideo;
+            const healthyImage = !wantsVideo &&
+                !wantsClear &&
+                snap &&
+                snap.active &&
+                snap.hasImage &&
+                snap.imageLoaded === true &&
+                snap.imageFailed !== true &&
+                snap.media === "image";
+            const healthyClear = wantsClear && snap && !snap.active && !snap.hasStage;
+            if (healthyVideo || healthyImage || healthyClear) {
+                // Refresh CSS text in place (style edits) without touching media.
+                try {
+                    let style = document.getElementById(STYLE_ID);
+                    if (!style) {
+                        style = document.createElement("style");
+                        style.id = STYLE_ID;
+                        (document.head || document.documentElement).appendChild(style);
+                    }
+                    if (typeof cssText === "string")
+                        style.textContent = cssText;
+                }
+                catch (_) { }
+                // Same-gen republish used to leave a playable video at inline opacity:0.
+                if (healthyVideo) {
+                    try {
+                        const v = document.querySelector("#beauticode-bg-stage video");
+                        if (v) {
+                            v.style.opacity = "";
+                            v.removeAttribute("poster");
+                        }
+                    }
+                    catch (_) { }
+                }
+                guest.setActive(Boolean(snap.active));
+                return { skipped: true, generation: gen, reason: "same-generation" };
+            }
         }
-        for (const node of record.addedNodes) {
-          if (!(node instanceof Element)) continue;
-          if (node.tagName === "WEBVIEW" || node.querySelector("webview")) {
-            scheduleGuestSync();
-            return;
-          }
+        catch (_) {
+            /* fall through and rebuild */
         }
-      }
-    });
-    guestObserver.observe(document.documentElement, {
-      childList: true,
-      subtree: true,
-      attributes: true,
-      attributeFilter: ["src"],
-    });
-  } catch (_) {}
-  const stopGuestWatchers = () => {
-    try {
-      guestObserver?.disconnect();
-    } catch (_) {}
-    guestObserver = null;
-    if (guestSyncTimer) {
-      clearTimeout(guestSyncTimer);
-      guestSyncTimer = null;
     }
-  };
-
-  // ---- Same-generation short-circuit (critical anti-flash) ----
-  // The tray watch loop re-publishes the active payload every ~1s. Rebuilding
-  // the stage on every poll creates stacked <video> nodes + poster flashes.
-  if (
-    !forceRebuild &&
-    previous &&
-    previous.generation === gen &&
-    typeof previous.snapshot === "function"
-  ) {
-    try {
-      const snap = previous.snapshot();
-      const wantsVideo = Boolean(
-        videoConfig &&
-          typeof videoConfig === "object" &&
-          (videoConfig.mode === "blob" ||
-            videoConfig.dataUrl ||
-            videoConfig.srcUrl ||
-            videoConfig.url),
-      );
-      const wantsClear = !imageDataUrl && !imageUrl && !wantsVideo && !wantImageBlob;
-      const healthyVideo =
-        wantsVideo &&
-        snap &&
-        snap.active &&
-        snap.videoReady &&
-        !snap.videoFailed &&
-        snap.hasVideo;
-      const healthyImage =
-        !wantsVideo &&
-        !wantsClear &&
-        snap &&
-        snap.active &&
-        snap.hasImage &&
-        snap.imageLoaded === true &&
-        snap.imageFailed !== true &&
-        snap.media === "image";
-      const healthyClear = wantsClear && snap && !snap.active && !snap.hasStage;
-      if (healthyVideo || healthyImage || healthyClear) {
-        // Refresh CSS text in place (style edits) without touching media.
+    // Capture previous playable video before dispose.
+    // Cross-generation always hands off. Same-generation rebuild (short-circuit
+    // failed because stage was unhealthy) also hands off so we do not flash
+    // poster while re-attaching the blob.
+    let handedOffVideo = null;
+    const canHandoff = previous && typeof previous.handoffVideo === "function";
+    if (canHandoff) {
         try {
-          let style = document.getElementById(STYLE_ID);
-          if (!style) {
-            style = document.createElement("style");
-            style.id = STYLE_ID;
-            (document.head || document.documentElement).appendChild(style);
-          }
-          if (typeof cssText === "string") style.textContent = cssText;
-        } catch (_) {}
-        // Same-gen republish used to leave a playable video at inline opacity:0.
-        if (healthyVideo) {
-          try {
-            const v = document.querySelector("#beauticode-bg-stage video");
-            if (v) {
-              v.style.opacity = "";
-              v.removeAttribute("poster");
+            const ho = previous.handoffVideo();
+            // Only preserve a playable frame. Empty pending shells must be dropped
+            // so cold blob re-attach does not stack two <video> nodes.
+            if (ho && ho.video && ho.ready) {
+                handedOffVideo = {
+                    stage: ho.stage || null,
+                    video: ho.video,
+                    objectUrl: ho.objectUrl || null,
+                    ready: true,
+                    preserve: true,
+                };
+            }
+            else if (ho && ho.video) {
+                // Tear down the non-ready shell immediately; we will rebuild.
+                try {
+                    ho.video.pause?.();
+                }
+                catch (_) { }
+                try {
+                    ho.video.removeAttribute?.("src");
+                    ho.video.removeAttribute?.("poster");
+                    ho.video.load?.();
+                }
+                catch (_) { }
+                try {
+                    ho.video.remove?.();
+                }
+                catch (_) { }
+                if (ho.objectUrl) {
+                    try {
+                        URL.revokeObjectURL(ho.objectUrl);
+                    }
+                    catch (_) { }
+                }
             }
-          } catch (_) {}
         }
-        if (isBackgroundActive()) syncGuestTransparency();
-        return { skipped: true, generation: gen, reason: "same-generation" };
-      }
-    } catch (_) {
-      /* fall through and rebuild */
+        catch (_) { }
     }
-  }
-
-  // Capture previous playable video before dispose.
-  // Cross-generation always hands off. Same-generation rebuild (short-circuit
-  // failed because stage was unhealthy) also hands off so we do not flash
-  // poster while re-attaching the blob.
-  let handedOffVideo = null;
-  const canHandoff =
-    previous && typeof previous.handoffVideo === "function";
-  if (canHandoff) {
-    try {
-      const ho = previous.handoffVideo();
-      // Only preserve a playable frame. Empty pending shells must be dropped
-      // so cold blob re-attach does not stack two <video> nodes.
-      if (ho && ho.video && ho.ready) {
-        handedOffVideo = {
-          stage: ho.stage || null,
-          video: ho.video,
-          objectUrl: ho.objectUrl || null,
-          ready: true,
-          preserve: true,
-        };
-      } else if (ho && ho.video) {
-        // Tear down the non-ready shell immediately; we will rebuild.
-        try {
-          ho.video.pause?.();
-        } catch (_) {}
+    // Always dispose the previous runtime when rebuilding — including same-gen
+    // unhealthy rebuilds. Leaving old listeners attached was a flash source
+    // (session 019fa31c / Dream Skin detachBackgroundVideoListeners).
+    if (previous && typeof previous.dispose === "function") {
         try {
-          ho.video.removeAttribute?.("src");
-          ho.video.removeAttribute?.("poster");
-          ho.video.load?.();
-        } catch (_) {}
-        try {
-          ho.video.remove?.();
-        } catch (_) {}
-        if (ho.objectUrl) {
-          try {
-            URL.revokeObjectURL(ho.objectUrl);
-          } catch (_) {}
+            previous.dispose({
+                handoff: Boolean(handedOffVideo) || Boolean(videoConfig),
+            });
         }
-      }
-    } catch (_) {}
-  }
-  // Always dispose the previous runtime when rebuilding — including same-gen
-  // unhealthy rebuilds. Leaving old listeners attached was a flash source
-  // (session 019fa31c / Dream Skin detachBackgroundVideoListeners).
-  if (previous && typeof previous.dispose === "function") {
-    try {
-      previous.dispose({
-        handoff: Boolean(handedOffVideo) || Boolean(videoConfig),
-      });
-    } catch (_) {}
-  }
-
-  const normalizedVideo =
-    videoConfig && typeof videoConfig === "object" ? videoConfig : null;
-  const videoMode =
-    normalizedVideo?.mode === "blob"
-      ? "blob"
-      : normalizedVideo?.mode === "server"
-        ? "server"
-        : normalizedVideo?.mode === "data"
-          ? "data"
-          : null;
-  const videoDataUrl =
-    typeof normalizedVideo?.dataUrl === "string" && normalizedVideo.dataUrl
-      ? normalizedVideo.dataUrl
-      : null;
-  const videoSrcRemote =
-    typeof normalizedVideo?.srcUrl === "string"
-      ? normalizedVideo.srcUrl
-      : typeof normalizedVideo?.url === "string"
-        ? normalizedVideo.url
-        : null;
-  const videoToken =
-    typeof normalizedVideo?.token === "string" ? normalizedVideo.token : null;
-  const videoEnabled = Boolean(
-    videoMode === "blob" || videoDataUrl || videoSrcRemote,
-  );
-
-  const dataImageUrl =
-    typeof imageDataUrl === "string" && imageDataUrl ? imageDataUrl : null;
-  const remoteImageUrl =
-    typeof imageUrl === "string" && imageUrl ? imageUrl : null;
-
-  let disposed = false;
-  let videoReady = false;
-  let videoFailed = false;
-  let videoError = null;
-  let imageFailed = false;
-  let imageObjectUrl = null;
-  let videoObjectUrl = null;
-  let videoEl = null;
-  let stageEl = null;
-  let imgEl = null;
-  let resolvedPoster = dataImageUrl;
-  let videoListeners = null; // { video, handlers, visibility }
-  let retryTimer = null;
-  let retryCount = 0;
-  let pendingPlay = false;
-  let lastPlaybackTime = -1;
-  const MAX_RETRY = 20;
-
-  // Fish mode (摸鱼): hide host chrome content, full-bleed media at native
-  // brightness. Attribute-only — never rebuilds media. Survives same-gen
-  // short-circuit (setFishMode API) and cross-gen reinject (preserve below).
-  let fishMode = false;
-  try {
-    if (previous && typeof previous.isFishMode === "function") {
-      fishMode = Boolean(previous.isFishMode());
-    } else if (root.getAttribute("data-bc-fish") === "true") {
-      fishMode = true;
-    }
-  } catch (_) {
-    fishMode = false;
-  }
-
-  // Video mute preference (default muted). Independent of fish mode.
-  // Start playback muted for autoplay policy, then unmute if preferred.
-  // Process-local via previous runtime; not persisted across tray restarts.
-  let videoMuted = true;
-  try {
-    if (previous && typeof previous.isMuted === "function") {
-      videoMuted = Boolean(previous.isMuted());
-    }
-  } catch (_) {
-    videoMuted = true;
-  }
-
-  // Background tone is a CSS-only preference. Keep dark as the legacy
-  // default, and carry the preference across same-generation/rebuild paths.
-  const normalizeTone = (value) =>
-    value === "light" || value === "auto" ? value : "dark";
-  let backgroundTone = "dark";
-  try {
-    if (previous && typeof previous.getBackgroundTone === "function") {
-      backgroundTone = normalizeTone(previous.getBackgroundTone());
-    } else {
-      backgroundTone = normalizeTone(root.getAttribute("data-bc-tone"));
-    }
-  } catch (_) {
-    backgroundTone = "dark";
-  }
-
-  // Optional initial seek for saved-theme restore (seconds). Applied once when
-  // the live <video> has metadata. Invalid / past end → 0 (start over).
-  let pendingStartAt = null;
-  let startAtApplied = false;
-  try {
-    const rawStart =
-      normalizedVideo && typeof normalizedVideo.startAt === "number"
-        ? normalizedVideo.startAt
+        catch (_) { }
+    }
+    const normalizedVideo = videoConfig && typeof videoConfig === "object" ? videoConfig : null;
+    const videoMode = normalizedVideo?.mode === "blob"
+        ? "blob"
+        : normalizedVideo?.mode === "server"
+            ? "server"
+            : normalizedVideo?.mode === "data"
+                ? "data"
+                : null;
+    const videoDataUrl = typeof normalizedVideo?.dataUrl === "string" && normalizedVideo.dataUrl
+        ? normalizedVideo.dataUrl
         : null;
-    if (rawStart != null && Number.isFinite(rawStart) && rawStart > 0) {
-      // Cap absurd values; host also clamps.
-      pendingStartAt = Math.min(rawStart, 24 * 60 * 60);
-    }
-  } catch (_) {
-    pendingStartAt = null;
-  }
-
-  // Focus dim: only when a project/task thread is confirmed open, set
-  // data-bc-working so CSS can slightly darken the RIGHT main column.
-  // Home / new-task (including just-imported media) stays bright. Agent
-  // generation on the landing must not dim. LEFT sidebar stays identical
-  // to home. Do NOT filter the whole stage (that would shift art under
-  // the sidebar). Media stays mounted and keeps playing. Fail open.
-  let working = false;
-  let workObserver = null;
-  let workPollTimer = null;
-  let workRaf = 0;
-  let workDebounceTimer = null;
-  let workRouteHooked = false;
-  const WORK_POLL_MS = 2000;
-  const WORK_DEBOUNCE_MS = 200;
-
-  const isCurrent = () =>
-    !disposed &&
-    window.__BEAUTICODE_BG__ &&
-    window.__BEAUTICODE_BG__.generation === gen;
-
-  const isDocHidden = () =>
-    Boolean(
-      (typeof document !== "undefined" &&
-        (document.visibilityState === "hidden" || document.hidden)) ||
-        false,
-    );
-
-  const revoke = (url) => {
-    if (!url || typeof url !== "string" || !url.startsWith("blob:")) return;
-    try {
-      URL.revokeObjectURL(url);
-    } catch (_) {}
-  };
-
-  const clearRetry = () => {
-    if (retryTimer) {
-      try {
-        clearTimeout(retryTimer);
-      } catch (_) {}
-      retryTimer = null;
-    }
-  };
-
-  const setWorkingAttr = (next) => {
-    working = Boolean(next);
-    if (!resolvedPoster && !videoEnabled && !remoteImageUrl && !dataImageUrl) {
-      root.removeAttribute("data-bc-working");
-      return;
-    }
-    if (working) root.setAttribute("data-bc-working", "true");
-    else root.removeAttribute("data-bc-working");
-  };
-
-  const isVisibleEl = (el) => {
-    if (!el || !el.isConnected) return false;
-    try {
-      const r = el.getBoundingClientRect?.();
-      if (r && (r.width < 1 || r.height < 1)) return false;
-      const st =
-        typeof window.getComputedStyle === "function"
-          ? window.getComputedStyle(el)
-          : null;
-      if (
-        st &&
-        (st.display === "none" ||
-          st.visibility === "hidden" ||
-          Number(st.opacity) === 0)
-      ) {
-        return false;
-      }
-    } catch (_) {
-      /* ignore */
-    }
-    return true;
-  };
-
-  /**
-   * True on the Codex home / empty landing (bright art is welcome).
-   * Uses the same home-icon hook already referenced by background.css.
-   */
-  const isHomeView = () => {
-    try {
-      const home = document.querySelector('[data-testid="home-icon"]');
-      return Boolean(home && isVisibleEl(home));
-    } catch (_) {
-      return false;
-    }
-  };
-
-  /**
-   * True when a project task / conversation thread is confirmed open —
-   * the only case that should dim. Prefer structural thread / selected-task
-   * signals over header+composer (home and new-task also have those).
-   */
-  const isTaskOrProjectView = () => {
-    try {
-      if (isHomeView()) return false;
-
-      // Thread / message list (Codex desktop task conversation).
-      const thread = document.querySelector(
-        [
-          ".thread-scroll-container",
-          "[data-message-author-role]",
-          '[data-testid*="conversation"]',
-          '[data-testid*="thread"]',
-          '[data-testid*="turn"]',
-          "body > #root main [data-message-id]",
-        ].join(", "),
-      );
-      if (thread && isVisibleEl(thread)) return true;
-
-      // Sidebar: a selected project task row (not the "无任务" empty label).
-      const selectedTask = document.querySelector(
-        [
-          'aside.app-shell-left-panel [aria-current="page"]',
-          "aside.app-shell-left-panel [aria-selected='true']",
-          "aside.app-shell-left-panel button[aria-pressed='true']",
-          "aside.app-shell-left-panel a[aria-current='true']",
-        ].join(", "),
-      );
-      if (selectedTask && isVisibleEl(selectedTask)) {
-        const t = (selectedTask.textContent || "").replace(/\s+/g, " ").trim();
-        if (t && !/^(无任务|no tasks?|new task|新建任务)$/i.test(t)) {
-          return true;
-        }
-      }
-
-      return false;
-    } catch (_) {
-      return false;
-    }
-  };
-
-  /**
-   * Dim only inside a confirmed project/task thread.
-   * Home / new-task landing stays bright even if the agent is generating.
-   * Attribute on <html> only.
-   */
-  const detectWorking = () => {
-    try {
-      if (typeof document === "undefined" || !document.body) return false;
-      return isTaskOrProjectView();
-    } catch (_) {
-      // Fail open: never dim on detector errors.
-      return false;
-    }
-  };
-
-  const refreshWorking = () => {
-    if (!isCurrent()) return;
-    const next = detectWorking();
-    if (next !== working) {
-      setWorkingAttr(next);
-    }
-  };
-
-  const scheduleWorkingRefresh = () => {
-    if (!isCurrent()) return;
-    if (workDebounceTimer || workRaf) return;
-    workDebounceTimer = setTimeout(() => {
-      workDebounceTimer = null;
-      try {
-        workRaf = requestAnimationFrame(() => {
-          workRaf = 0;
-          refreshWorking();
-        });
-      } catch (_) {
-        workRaf = 0;
-        refreshWorking();
-      }
-    }, WORK_DEBOUNCE_MS);
-  };
-
-  const onRouteMaybeChanged = () => {
-    scheduleWorkingRefresh();
-  };
-
-  const stopWorkingWatch = () => {
-    if (workObserver) {
-      try {
-        workObserver.disconnect();
-      } catch (_) {}
-      workObserver = null;
-    }
-    if (workPollTimer) {
-      try {
-        clearInterval(workPollTimer);
-      } catch (_) {}
-      workPollTimer = null;
-    }
-    if (workRaf) {
-      try {
-        cancelAnimationFrame(workRaf);
-      } catch (_) {}
-      workRaf = 0;
-    }
-    if (workDebounceTimer) {
-      try {
-        clearTimeout(workDebounceTimer);
-      } catch (_) {}
-      workDebounceTimer = null;
-    }
-    if (workRouteHooked) {
-      try {
-        window.removeEventListener("popstate", onRouteMaybeChanged);
-        window.removeEventListener("hashchange", onRouteMaybeChanged);
-        window.removeEventListener("focus", onRouteMaybeChanged);
-      } catch (_) {}
-      workRouteHooked = false;
-    }
-    working = false;
-    try {
-      root.removeAttribute("data-bc-working");
-    } catch (_) {}
-  };
-
-  const startWorkingWatch = () => {
-    if (!isCurrent()) return;
-    if (workObserver || workPollTimer) {
-      scheduleWorkingRefresh();
-      return;
-    }
-    try {
-      if (typeof MutationObserver === "function" && document.body) {
-        workObserver = new MutationObserver(() => {
-          scheduleWorkingRefresh();
-        });
-        workObserver.observe(document.body, {
-          subtree: true,
-          childList: true,
-          attributes: true,
-          attributeFilter: [
-            "aria-label",
-            "aria-busy",
-            "aria-current",
-            "aria-selected",
-            "aria-pressed",
-            "title",
-            "data-is-streaming",
-            "data-streaming",
-            "data-agent-running",
-            "data-bc-host-working",
-            "data-message-author-role",
-            "data-testid",
-            "disabled",
-            "hidden",
-          ],
-        });
-      }
-    } catch (_) {
-      workObserver = null;
-    }
-    // Poll as a safety net (SPA swaps / closed shadow roots).
-    try {
-      workPollTimer = setInterval(() => {
-        if (!isCurrent()) return;
-        refreshWorking();
-      }, WORK_POLL_MS);
-      workPollTimer.unref?.();
-    } catch (_) {
-      workPollTimer = null;
-    }
-    if (!workRouteHooked) {
-      try {
-        window.addEventListener("popstate", onRouteMaybeChanged);
-        window.addEventListener("hashchange", onRouteMaybeChanged);
-        window.addEventListener("focus", onRouteMaybeChanged);
-        workRouteHooked = true;
-      } catch (_) {
-        workRouteHooked = false;
-      }
-    }
-    refreshWorking();
-  };
-
-  const hasBackgroundMedia = () =>
-    Boolean(
-      resolvedPoster ||
-        videoEnabled ||
-        remoteImageUrl ||
-        dataImageUrl ||
-        wantImageBlob,
-    );
-
-  const applyFishAttr = () => {
-    try {
-      if (fishMode && hasBackgroundMedia()) {
-        root.setAttribute("data-bc-fish", "true");
-      } else {
-        root.removeAttribute("data-bc-fish");
-        if (!hasBackgroundMedia()) fishMode = false;
-      }
-    } catch (_) {}
-  };
-
-  const setFishMode = (enabled) => {
-    if (!isCurrent()) return false;
-    const want = Boolean(enabled);
-    if (want && !hasBackgroundMedia()) {
-      fishMode = false;
-      applyFishAttr();
-      return false;
-    }
-    fishMode = want;
-    applyFishAttr();
-    if (want) {
-      // Light input guard: drop focus so typing is less likely to hit composer.
-      try {
-        const ae = document.activeElement;
-        if (ae && typeof ae.blur === "function") ae.blur();
-      } catch (_) {}
-    }
-    return true;
-  };
-
-  const listStageVideos = () => {
-    const out = [];
-    const stage = stageEl || document.getElementById(STAGE_ID);
-    if (stage) {
-      try {
-        for (const v of stage.querySelectorAll("video")) {
-          if (v && out.indexOf(v) === -1) out.push(v);
-        }
-      } catch (_) {}
-    }
-    if (videoEl && out.indexOf(videoEl) === -1) out.push(videoEl);
-    return out;
-  };
-
-  /**
-   * Apply preferred mute state to live <video> nodes.
-   * Always starts from the preference; callers that need autoplay-safe cold
-   * start should mute first, play, then call this again.
-   */
-  const applyMuteState = () => {
-    const videos = listStageVideos();
-    let anyStillMuted = false;
-    for (const v of videos) {
-      try {
-        if (videoMuted) {
-          v.muted = true;
-          v.defaultMuted = true;
-          v.setAttribute("muted", "");
-        } else {
-          v.muted = false;
-          v.defaultMuted = false;
-          v.removeAttribute("muted");
+    const videoSrcRemote = typeof normalizedVideo?.srcUrl === "string"
+        ? normalizedVideo.srcUrl
+        : typeof normalizedVideo?.url === "string"
+            ? normalizedVideo.url
+            : null;
+    const videoToken = typeof normalizedVideo?.token === "string" ? normalizedVideo.token : null;
+    const videoEnabled = Boolean(videoMode === "blob" || videoDataUrl || videoSrcRemote);
+    const dataImageUrl = typeof imageDataUrl === "string" && imageDataUrl ? imageDataUrl : null;
+    const remoteImageUrl = typeof imageUrl === "string" && imageUrl ? imageUrl : null;
+    let disposed = false, stageEl = null;
+    const isCurrent = () => !disposed && window.__BEAUTICODE_BG__?.generation === gen;
+    const isDocHidden = () => Boolean(document.hidden || document.visibilityState === "hidden");
+    const sources = createMediaSources({ isCurrent });
+    const { revoke } = sources;
+    const image = createImageRuntime({ isCurrent, ensureStage: () => ensureStage(), setAttrs: () => setAttrs(), dataImageUrl, remoteImageUrl, sources });
+    let video;
+    const hasBackgroundMedia = () => Boolean(image.poster || videoEnabled || remoteImageUrl || dataImageUrl || wantImageBlob);
+    const controls = createPlaybackControls({ root, previous, normalizedVideo, isCurrent, hasBackgroundMedia, getStage: () => stageEl, getVideo: () => video?.element, setAttrs: () => setAttrs() });
+    const working = createWorkingState({ root, isCurrent, hasBackgroundMedia });
+    video = createVideoRuntime({ isCurrent, isDocHidden, sources, controls, setAttrs: () => setAttrs(), ensureStage: () => ensureStage(), getHandoff: () => handedOffVideo, releaseHandoff: () => releaseHandoff(), videoMode, videoDataUrl, videoSrcRemote, videoToken });
+    const setAttrs = () => {
+        if (!isCurrent())
+            return;
+        const handoffReady = videoEnabled &&
+            !video.failed &&
+            !video.ready &&
+            Boolean(handedOffVideo?.ready && handedOffVideo.video?.parentElement);
+        // Never make the host transparent while a replacement is still decoding.
+        // A cold first launch has no previous frame to cover the gap, so native
+        // Codex chrome must remain visible until an image load or video frame is
+        // confirmed.
+        const imageReady = !videoEnabled &&
+            !image.failed &&
+            Boolean(image.element?.isConnected && image.element.complete && image.element.naturalWidth > 0);
+        const mediaReady = videoEnabled
+            ? (!video.failed && (video.ready || handoffReady))
+            : imageReady;
+        const active = mediaReady;
+        if (!active) {
+            root.removeAttribute("data-bc-active");
+            guest.setActive(false);
+            root.removeAttribute("data-bc-media");
+            root.removeAttribute("data-bc-video-ready");
+            root.removeAttribute("data-bc-generation");
+            root.removeAttribute("data-bc-working");
+            root.removeAttribute("data-bc-fish");
+            root.removeAttribute("data-bc-tone");
+            controls.resetFish();
+            working.stop();
+            return;
         }
-        if (v.muted) anyStillMuted = true;
-      } catch (_) {
-        anyStillMuted = true;
-      }
-    }
-    return {
-      preferredMuted: Boolean(videoMuted),
-      // Blocked only when we wanted sound but every/any live node stayed muted.
-      blocked: !videoMuted && videos.length > 0 && anyStillMuted,
-      hasVideo: videos.length > 0,
+        root.setAttribute("data-bc-active", "true");
+        guest.setActive(true);
+        // Keep media=video during handoff so CSS does not snap back to image-only
+        // while the previous frame is still covering the stage.
+        const media = videoEnabled && !video.failed
+            ? video.ready || handoffReady
+                ? "video"
+                : "video-pending"
+            : "image";
+        root.setAttribute("data-bc-media", media);
+        root.setAttribute("data-bc-video-ready", video.ready || handoffReady ? "true" : "false");
+        root.setAttribute("data-bc-generation", String(gen));
+        root.setAttribute("data-bc-tone", controls.tone);
+        if (working.active)
+            root.setAttribute("data-bc-working", "true");
+        else
+            root.removeAttribute("data-bc-working");
+        controls.applyFishAttr();
     };
-  };
-
-  /**
-   * Set mute preference. Does not rebuild media.
-   * Returns { ok, muted, blocked, hasVideo }.
-   * muted = preferred state (true = silent). blocked = wanted sound but element stayed muted.
-   */
-  const setMuted = (muted) => {
-    if (!isCurrent()) {
-      return {
-        ok: false,
-        muted: Boolean(videoMuted),
-        blocked: false,
-        hasVideo: false,
-      };
-    }
-    videoMuted = Boolean(muted);
-    const applied = applyMuteState();
-    return {
-      ok: true,
-      muted: Boolean(videoMuted),
-      blocked: Boolean(applied.blocked),
-      hasVideo: Boolean(applied.hasVideo),
-    };
-  };
-
-  const setBackgroundTone = (tone) => {
-    if (!isCurrent()) return false;
-    backgroundTone = normalizeTone(tone);
-    setAttrs();
-    return true;
-  };
-
-  /**
-   * Clamp a desired seek time against live duration.
-   * Invalid / NaN / negative / past end → 0 (start over, per product rule).
-   */
-  const clampSeekSeconds = (sec, duration) => {
-    const t = typeof sec === "number" ? sec : Number(sec);
-    if (!Number.isFinite(t) || t <= 0) return 0;
-    const d = typeof duration === "number" ? duration : Number(duration);
-    if (Number.isFinite(d) && d > 0 && t >= d) return 0;
-    if (t > 24 * 60 * 60) return 0;
-    return t;
-  };
-
-  /**
-   * Apply pendingStartAt once metadata is available. Fail-soft → 0.
-   * Returns the seconds actually seeked to (or null if not yet applied).
-   */
-  const applyPendingStartAt = (video) => {
-    if (startAtApplied || pendingStartAt == null) return null;
-    if (!video || !isCurrent()) return null;
-    let duration = NaN;
-    try {
-      duration = Number(video.duration);
-    } catch (_) {
-      duration = NaN;
-    }
-    // Wait for metadata when duration is still unknown.
-    if (!(Number.isFinite(duration) && duration > 0) && (video.readyState || 0) < 1) {
-      return null;
-    }
-    const target = clampSeekSeconds(pendingStartAt, duration);
-    startAtApplied = true;
-    pendingStartAt = null;
-    try {
-      video.currentTime = target;
-    } catch (_) {
-      try {
-        video.currentTime = 0;
-      } catch (_) {}
-      return 0;
-    }
-    return target;
-  };
-
-  /** Current playback position for continuous theme progress writes. */
-  const getPlaybackPosition = () => {
-    if (!isCurrent()) {
-      return { ok: false, currentTime: 0, duration: 0, hasVideo: false };
-    }
-    const videos = listStageVideos();
-    const live =
-      (videoEl && videoEl.isConnected && videoEl) ||
-      videos[videos.length - 1] ||
-      null;
-    if (!live) {
-      return { ok: true, currentTime: 0, duration: 0, hasVideo: false };
-    }
-    let currentTime = 0;
-    let duration = 0;
-    try {
-      const t = Number(live.currentTime);
-      if (Number.isFinite(t) && t >= 0) currentTime = t;
-    } catch (_) {}
-    try {
-      const d = Number(live.duration);
-      if (Number.isFinite(d) && d > 0) duration = d;
-    } catch (_) {}
-    return {
-      ok: true,
-      currentTime,
-      duration,
-      hasVideo: true,
-    };
-  };
-
-  /**
-   * Seek live video. Invalid / past end → 0. Does not rebuild media.
-   */
-  const seekTo = (seconds) => {
-    if (!isCurrent()) {
-      return { ok: false, currentTime: 0, hasVideo: false };
-    }
-    const videos = listStageVideos();
-    const live =
-      (videoEl && videoEl.isConnected && videoEl) ||
-      videos[videos.length - 1] ||
-      null;
-    if (!live) {
-      // Remember for when the blob attaches.
-      const t = clampSeekSeconds(seconds, NaN);
-      pendingStartAt = t > 0 ? t : null;
-      startAtApplied = false;
-      return { ok: true, currentTime: t, hasVideo: false };
-    }
-    let duration = NaN;
-    try {
-      duration = Number(live.duration);
-    } catch (_) {
-      duration = NaN;
-    }
-    const target = clampSeekSeconds(seconds, duration);
-    startAtApplied = true;
-    pendingStartAt = null;
-    try {
-      live.currentTime = target;
-    } catch (_) {
-      try {
-        live.currentTime = 0;
-      } catch (_) {}
-      return { ok: true, currentTime: 0, hasVideo: true };
-    }
-    let now = target;
-    try {
-      const t = Number(live.currentTime);
-      if (Number.isFinite(t)) now = t;
-    } catch (_) {}
-    return { ok: true, currentTime: now, hasVideo: true };
-  };
-
-  const setAttrs = () => {
-    const wasActive = root.getAttribute("data-bc-active") === "true";
-    const handoffReady =
-      videoEnabled &&
-      !videoFailed &&
-      !videoReady &&
-      Boolean(handedOffVideo?.ready && handedOffVideo.video?.parentElement);
-    // Never make the host transparent while a replacement is still decoding.
-    // A cold first launch has no previous frame to cover the gap, so native
-    // Codex chrome must remain visible until an image load or video frame is
-    // confirmed.
-    const imageReady =
-      !videoEnabled &&
-      !imageFailed &&
-      Boolean(imgEl?.isConnected && imgEl.complete && imgEl.naturalWidth > 0);
-    const mediaReady = videoEnabled
-      ? (!videoFailed && (videoReady || handoffReady))
-      : imageReady;
-    const active = mediaReady;
-    if (!active) {
-      root.removeAttribute("data-bc-active");
-      root.removeAttribute("data-bc-media");
-      root.removeAttribute("data-bc-video-ready");
-      root.removeAttribute("data-bc-generation");
-      root.removeAttribute("data-bc-working");
-      root.removeAttribute("data-bc-fish");
-      root.removeAttribute("data-bc-tone");
-      fishMode = false;
-      stopWorkingWatch();
-      if (wasActive) clearGuestTransparency();
-      return;
-    }
-    root.setAttribute("data-bc-active", "true");
-    if (!wasActive) syncGuestTransparency();
-    // Keep media=video during handoff so CSS does not snap back to image-only
-    // while the previous frame is still covering the stage.
-    const media =
-      videoEnabled && !videoFailed
-        ? videoReady || handoffReady
-          ? "video"
-          : "video-pending"
-        : "image";
-    root.setAttribute("data-bc-media", media);
-    root.setAttribute(
-      "data-bc-video-ready",
-      videoReady || handoffReady ? "true" : "false",
-    );
-    root.setAttribute("data-bc-generation", String(gen));
-    root.setAttribute("data-bc-tone", backgroundTone);
-    if (working) root.setAttribute("data-bc-working", "true");
-    else root.removeAttribute("data-bc-working");
-    applyFishAttr();
-  };
-
-  const ensureStyle = () => {
-    let style = document.getElementById(STYLE_ID);
-    if (!style) {
-      style = document.createElement("style");
-      style.id = STYLE_ID;
-      (document.head || document.documentElement).appendChild(style);
-    }
-    style.textContent = typeof cssText === "string" ? cssText : "";
-  };
-
-  const ensureStage = () => {
-    // Prefer handed-off stage so the previous video node stays mounted.
-    // IMPORTANT: use handedOffVideo.stage itself (not .parentElement) —
-    // Dream Skin P1 bug was mistaking the parent shell for the stage.
-    let stage =
-      (handedOffVideo?.stage && handedOffVideo.stage.parentElement
-        ? handedOffVideo.stage
-        : null) || document.getElementById(STAGE_ID);
-    if (!stage) {
-      stage = document.createElement("div");
-      stage.id = STAGE_ID;
-      stage.setAttribute("aria-hidden", "true");
-      const parent = document.body || document.documentElement;
-      parent.insertBefore(stage, parent.firstChild);
-    } else if (!stage.parentElement) {
-      const parent = document.body || document.documentElement;
-      parent.insertBefore(stage, parent.firstChild);
-    }
-    stage.id = STAGE_ID;
-    stageEl = stage;
-    return stage;
-  };
-
-  const clearStage = () => {
-    const stage = document.getElementById(STAGE_ID);
-    if (stage) stage.remove();
-    const style = document.getElementById(STYLE_ID);
-    if (style) style.remove();
-    stageEl = null;
-    imgEl = null;
-  };
-
-  const detachVideoListeners = (bundle) => {
-    if (!bundle) return;
-    const { video, handlers, visibility } = bundle;
-    if (video && handlers) {
-      for (const [evt, fn] of Object.entries(handlers)) {
-        try {
-          video.removeEventListener(evt, fn);
-        } catch (_) {}
-      }
-    }
-    if (visibility) {
-      try {
-        document.removeEventListener("visibilitychange", visibility);
-      } catch (_) {}
-    }
-  };
-
-  const teardownVideo = (opts) => {
-    clearRetry();
-    // During handoff, leave the handed-out node alone — new generation owns it.
-    // But ALWAYS detach listeners so the superseded runtime cannot restart it.
-    if (opts && opts.skipElement && videoEl === opts.skipElement) {
-      if (videoListeners && videoListeners.video === opts.skipElement) {
-        detachVideoListeners(videoListeners);
-        videoListeners = null;
-      }
-      videoEl = null;
-      videoObjectUrl = null;
-      return;
-    }
-    if (videoListeners) {
-      detachVideoListeners(videoListeners);
-      videoListeners = null;
-    }
-    if (videoEl) {
-      try {
-        videoEl.pause();
-      } catch (_) {}
-      try {
-        videoEl.removeAttribute("src");
-        videoEl.removeAttribute("poster");
-        videoEl.load();
-      } catch (_) {}
-      try {
-        videoEl.remove();
-      } catch (_) {}
-      videoEl = null;
-    }
-    revoke(videoObjectUrl);
-    videoObjectUrl = null;
-  };
-
-  const teardownImageBlob = () => {
-    revoke(imageObjectUrl);
-    imageObjectUrl = null;
-  };
-
-  const releaseHandoff = () => {
-    if (!handedOffVideo) return;
-    const old = handedOffVideo;
-    handedOffVideo = null;
-    // Only remove if it is not the current video element.
-    if (old.video && old.video !== videoEl) {
-      try {
-        old.video.pause();
-      } catch (_) {}
-      try {
-        old.video.removeAttribute("src");
-        old.video.load();
-      } catch (_) {}
-      try {
-        old.video.remove();
-      } catch (_) {}
-      if (old.objectUrl && old.objectUrl !== videoObjectUrl) {
-        revoke(old.objectUrl);
-      }
-    }
-  };
-
-  const dataUrlToObjectUrl = async (dataUrl) => {
-    if (!dataUrl || typeof dataUrl !== "string") {
-      throw new Error("missing data url");
-    }
-    if (dataUrl.startsWith("blob:")) return dataUrl;
-    if (!dataUrl.startsWith("data:")) return dataUrl;
-    try {
-      const res = await fetch(dataUrl);
-      if (!res.ok) throw new Error("data url fetch failed: " + res.status);
-      const blob = await res.blob();
-      if (!isCurrent()) throw new Error("stale generation");
-      return URL.createObjectURL(blob);
-    } catch (_) {
-      const comma = dataUrl.indexOf(",");
-      if (comma < 0) throw new Error("malformed data url");
-      const meta = dataUrl.slice(0, comma);
-      const payload = dataUrl.slice(comma + 1);
-      const mimeMatch = /^data:([^;,]+)/i.exec(meta);
-      const mime = mimeMatch ? mimeMatch[1] : "application/octet-stream";
-      const isBase64 = /;base64/i.test(meta);
-      let bytes;
-      if (isBase64) {
-        const bin = atob(payload);
-        bytes = new Uint8Array(bin.length);
-        for (let i = 0; i < bin.length; i += 1) bytes[i] = bin.charCodeAt(i);
-      } else {
-        const decoded = decodeURIComponent(payload);
-        bytes = new Uint8Array(decoded.length);
-        for (let i = 0; i < decoded.length; i += 1) {
-          bytes[i] = decoded.charCodeAt(i);
+    const ensureStyle = () => {
+        let style = document.getElementById(STYLE_ID);
+        if (!style) {
+            style = document.createElement("style");
+            style.id = STYLE_ID;
+            (document.head || document.documentElement).appendChild(style);
         }
-      }
-      if (!isCurrent()) throw new Error("stale generation");
-      return URL.createObjectURL(new Blob([bytes], { type: mime }));
-    }
-  };
-
-  const fetchAsObjectUrl = async (url, token) => {
-    if (!url || typeof url !== "string") throw new Error("missing media url");
-    if (url.startsWith("blob:")) return url;
-    if (url.startsWith("data:")) return dataUrlToObjectUrl(url);
-    const headers = {};
-    if (token) headers["X-BeautiCode-Media-Token"] = token;
-    const res = await fetch(url, {
-      method: "GET",
-      headers,
-      mode: "cors",
-      credentials: "omit",
-      cache: "no-store",
-    });
-    if (!res.ok) throw new Error("media fetch failed: " + res.status);
-    const blob = await res.blob();
-    if (!isCurrent()) throw new Error("stale generation");
-    return URL.createObjectURL(blob);
-  };
-
-  const revealVideo = () => {
-    try {
-      if (videoEl) {
-        videoEl.style.opacity = "";
-        videoEl.removeAttribute("poster");
-      }
-    } catch (_) {}
-  };
-
-  const markReady = () => {
-    if (!isCurrent() || videoFailed) return;
-    // A second blob attach can set inline opacity:0 after the first ready
-    // signal. Always reveal; otherwise verify passes and the art stays hidden.
-    if (videoReady) {
-      revealVideo();
-      return;
-    }
-    videoReady = true;
-    pendingPlay = false;
-    retryCount = 0;
-    clearRetry();
-    revealVideo();
-    try {
-      if (videoEl) applyPendingStartAt(videoEl);
-    } catch (_) {}
-    try {
-      applyMuteState();
-    } catch (_) {}
-    setAttrs();
-    releaseHandoff();
-  };
-
-  const markFailed = (error) => {
-    if (!isCurrent() || videoFailed) return;
-    videoFailed = true;
-    videoReady = false;
-    videoError = {
-      name: error?.name || null,
-      message: toChineseMediaError(error),
-      mediaCode: videoEl?.error?.code ?? null,
-      readyState: videoEl?.readyState ?? null,
+        style.textContent = typeof cssText === "string" ? cssText : "";
     };
-    clearRetry();
-    try {
-      if (videoEl) videoEl.style.opacity = "0";
-    } catch (_) {}
-    setAttrs();
-    // On failure, keep handoff if it was ready so the prior frame stays up;
-    // otherwise fall back to poster image.
-    if (!handedOffVideo?.ready) {
-      releaseHandoff();
-    }
-  };
-
-  const isTransientVideoError = (error, video) => {
-    if (isDocHidden()) {
-      const message = String(error?.message || "").toLowerCase();
-      if (
-        error?.name === "AbortError" ||
-        /background media|save power|paused/.test(message)
-      ) {
-        return true;
-      }
-      // Chromium can emit an empty media error while the app target is hidden.
-      if (!video?.error && !message) return true;
-      if (!video?.error && /failed to fetch|network|load|media/.test(message)) {
-        return true;
-      }
-    }
-    const code = video?.error?.code ?? null;
-    // MEDIA_ERR_ABORTED (1), MEDIA_ERR_NETWORK (2), empty error object.
-    return code === null || code === 1 || code === 2;
-  };
-
-  const retryTransientVideo = () => {
-    if (!isCurrent() || videoFailed || !videoEl || !videoEl.src) return false;
-    if (retryCount >= MAX_RETRY) return false;
-    // Hidden Chromium suspends media — do not burn the finite retry budget.
-    // visibilitychange will resume. Preserving videoReady avoids the
-    // "flash then stick on image" failure mode from session 019fa31c.
-    if (isDocHidden()) {
-      pendingPlay = true;
-      return true;
-    }
-    if (retryTimer) return true;
-    retryCount += 1;
-    pendingPlay = true;
-    retryTimer = setTimeout(() => {
-      retryTimer = null;
-      if (!isCurrent() || videoFailed || !videoEl || !videoEl.src) return;
-      if (isDocHidden()) {
-        pendingPlay = true;
-        return;
-      }
-      Promise.resolve(videoEl.play?.())
-        .then(() => {
-          if (!isCurrent() || videoFailed) return;
-          pendingPlay = false;
-          // play() is an alternate ready signal for shells that skip loadeddata.
-          if (videoEl.readyState >= 2 || !videoEl.paused || videoEl.currentTime > 0) {
-            markReady();
-          }
-        })
-        .catch((err) => {
-          if (!isCurrent()) return;
-          if (isTransientVideoError(err, videoEl)) {
-            retryTransientVideo();
-            return;
-          }
-          markFailed(err);
-        });
-    }, 500);
-    return true;
-  };
-
-  const onVisibility = () => {
-    if (!isCurrent() || videoFailed) return;
-    if (isDocHidden()) return;
-    if (!videoEl || !videoEl.src) return;
-    try {
-      // Inline opacity:0 beats the ready CSS rule. Hidden pages often miss
-      // markReady's clear; restoring visibility must drop it or the video
-      // stays invisible while snapshot says ready.
-      videoEl.style.opacity = "";
-    } catch (_) {}
-    Promise.resolve(videoEl.play?.())
-      .then(() => {
-        if (!isCurrent() || videoFailed) return;
-        pendingPlay = false;
-        try {
-          videoEl.style.opacity = "";
-        } catch (_) {}
-        if (
-          videoReady ||
-          videoEl.readyState >= 2 ||
-          !videoEl.paused ||
-          videoEl.currentTime > 0
-        ) {
-          if (!videoReady) markReady();
-          else setAttrs();
+    const ensureStage = () => {
+        // Prefer handed-off stage so the previous video node stays mounted.
+        // IMPORTANT: use handedOffVideo.stage itself (not .parentElement) —
+        // Dream Skin P1 bug was mistaking the parent shell for the stage.
+        let stage = (handedOffVideo?.stage && handedOffVideo.stage.parentElement
+            ? handedOffVideo.stage
+            : null) || document.getElementById(STAGE_ID);
+        if (!stage) {
+            stage = document.createElement("div");
+            stage.id = STAGE_ID;
+            stage.setAttribute("aria-hidden", "true");
+            const parent = document.body || document.documentElement;
+            parent.insertBefore(stage, parent.firstChild);
         }
-      })
-      .catch((err) => {
-        if (!isCurrent()) return;
-        if (isTransientVideoError(err, videoEl) && retryTransientVideo()) return;
-        // Do not fail a previously-ready video on a single resume blip.
-        if (videoReady) {
-          pendingPlay = true;
-          retryTransientVideo();
-          return;
-        }
-        markFailed(err);
-      });
-  };
-
-  const resolvePoster = async () => {
-    if (dataImageUrl) {
-      resolvedPoster = dataImageUrl;
-      imageFailed = false;
-      return resolvedPoster;
-    }
-    if (remoteImageUrl) {
-      try {
-        let token = null;
-        try {
-          token = new URL(remoteImageUrl, "http://127.0.0.1").searchParams.get(
-            "t",
-          );
-        } catch (_) {}
-        const obj = await fetchAsObjectUrl(remoteImageUrl, token);
-        if (!isCurrent()) {
-          revoke(obj);
-          return null;
+        else if (!stage.parentElement) {
+            const parent = document.body || document.documentElement;
+            parent.insertBefore(stage, parent.firstChild);
         }
-        if (obj.startsWith("blob:")) imageObjectUrl = obj;
-        resolvedPoster = obj;
-        imageFailed = false;
-        return resolvedPoster;
-      } catch (_) {
-        imageFailed = true;
-      }
-    }
-    resolvedPoster = null;
-    return null;
-  };
-
-  const VIDEO_ACCEPT = "video/mp4,video/quicktime,.mp4,.mov";
-
-  const playbackVideoFile = (file) => {
-    if (!file) return file;
-    const type = String(file.type || "").toLowerCase();
-    const name = String(file.name || "").toLowerCase();
-    if (type === "video/mp4") return file;
-    if (type === "video/quicktime" || name.endsWith(".mov")) {
-      try {
-        return new File([file], file.name, {
-          type: "video/mp4",
-          lastModified: file.lastModified,
-        });
-      } catch (_) {
-        return file;
-      }
-    }
-    return file;
-  };
-
-  const createVideoInput = () => {
-    let input = document.getElementById(VIDEO_INPUT_ID);
-    if (input) {
-      input.accept = VIDEO_ACCEPT;
-      return input;
-    }
-    input = document.createElement("input");
-    input.type = "file";
-    input.id = VIDEO_INPUT_ID;
-    input.accept = VIDEO_ACCEPT;
-    input.tabIndex = -1;
-    input.setAttribute("aria-hidden", "true");
-    Object.assign(input.style, {
-      position: "fixed",
-      width: "1px",
-      height: "1px",
-      opacity: "0",
-      pointerEvents: "none",
-    });
-    (document.body || document.documentElement).appendChild(input);
-    return input;
-  };
-
-  const createImageInput = () => {
-    let input = document.getElementById(IMAGE_INPUT_ID);
-    if (input) return input;
-    input = document.createElement("input");
-    input.type = "file";
-    input.id = IMAGE_INPUT_ID;
-    input.accept = "image/jpeg,image/png,image/webp,image/avif,.jpg,.jpeg,.png,.webp,.avif";
-    input.tabIndex = -1;
-    input.setAttribute("aria-hidden", "true");
-    Object.assign(input.style, {
-      position: "fixed",
-      width: "1px",
-      height: "1px",
-      opacity: "0",
-      pointerEvents: "none",
-    });
-    (document.body || document.documentElement).appendChild(input);
-    return input;
-  };
-
-  const doAttachImageFile = async () => {
-    if (!isCurrent()) return false;
-    const input = document.getElementById(IMAGE_INPUT_ID);
-    const file = input && input.files && input.files[0] ? input.files[0] : null;
-    if (!file) return false;
-    try {
-      const objectUrl = URL.createObjectURL(file);
-      if (imageObjectUrl && imageObjectUrl !== objectUrl) revoke(imageObjectUrl);
-      imageObjectUrl = objectUrl;
-      resolvedPoster = objectUrl;
-      imageFailed = false;
-      const stage = ensureStage();
-      const img = ensurePosterImg(stage);
-      await new Promise((resolve) => {
-        let done = false;
-        const finish = () => {
-          if (done) return;
-          done = true;
-          resolve();
-        };
-        img.addEventListener("load", finish, { once: true });
-        img.addEventListener(
-          "error",
-          () => {
-            imageFailed = true;
-            finish();
-          },
-          { once: true },
-        );
-        setTimeout(finish, 2500);
-        if (img.getAttribute("src") !== objectUrl) img.src = objectUrl;
-        else if (img.naturalWidth > 0) finish();
-      });
-      setAttrs();
-      return Boolean(!imageFailed && img.getAttribute("src"));
-    } catch (_) {
-      imageFailed = true;
-      setAttrs();
-      return false;
-    }
-  };
-
-  const playVideoObjectUrl = async (video, objectUrl) => {
-    if (!isCurrent() || videoFailed) return false;
-    if (videoObjectUrl && videoObjectUrl !== objectUrl) revoke(videoObjectUrl);
-    if (objectUrl.startsWith("blob:")) videoObjectUrl = objectUrl;
-    try {
-      // Cold start always muted so autoplay is not blocked; preference applied after.
-      video.muted = true;
-      video.defaultMuted = true;
-      video.setAttribute("muted", "");
-      video.playsInline = true;
-      video.autoplay = true;
-      video.loop = true;
-    } catch (_) {}
-    // Keep replacement hidden until first frame; handoff covers the gap.
-    video.style.opacity = "0";
-    // Do NOT call video.load() after src assign — it aborts and flashes poster.
-    video.src = objectUrl;
-    try {
-      const p = video.play();
-      if (p && typeof p.then === "function") {
-        await p.catch(() => {});
-      }
-    } catch (_) {}
-    // Apply user mute preference after play has a chance to start.
-    try {
-      applyMuteState();
-    } catch (_) {}
-    if (!isCurrent() || videoFailed) return false;
-    if (video.readyState < 2) {
-      await new Promise((resolve) => {
-        let done = false;
-        const finish = () => {
-          if (done) return;
-          done = true;
-          cleanup();
-          resolve();
-        };
-        const cleanup = () => {
-          try {
-            video.removeEventListener("loadeddata", finish);
-            video.removeEventListener("canplay", finish);
-            video.removeEventListener("playing", finish);
-            video.removeEventListener("error", finish);
-          } catch (_) {}
-        };
-        video.addEventListener("loadeddata", finish, { once: true });
-        video.addEventListener("canplay", finish, { once: true });
-        video.addEventListener("playing", finish, { once: true });
-        video.addEventListener("error", finish, { once: true });
-        setTimeout(finish, 2500);
-      });
-      if (!isCurrent() || videoFailed) return false;
-      if (video.paused && video.readyState >= 2) {
-        try {
-          const p2 = video.play();
-          if (p2 && typeof p2.then === "function") await p2.catch(() => {});
-        } catch (_) {}
-      }
-    }
-    if (!isCurrent() || videoFailed) return false;
-    if (video.readyState >= 2 || !video.paused || video.currentTime > 0) {
-      markReady();
-    } else {
-      // Still decoding — keep pending; events / retry will reveal.
-      pendingPlay = true;
-      retryTransientVideo();
-    }
-    return Boolean(video.src);
-  };
-
-  const createVideoElement = (stage) => {
-    // Keep at most one handed-off previous video; purge every other child
-    // except the poster img we manage separately. Two playable nodes
-    // alternate frames and posters (Dream Skin 7a3b2ec).
-    const keepVideo =
-      handedOffVideo?.video && handedOffVideo.video.parentElement === stage
-        ? handedOffVideo.video
-        : null;
-    for (const child of [...(stage.children || [])]) {
-      if (child === keepVideo) continue;
-      if (child.tagName === "IMG") continue;
-      const staleSrc = typeof child.src === "string" ? child.src : "";
-      try {
-        child.pause?.();
-      } catch (_) {}
-      try {
-        child.removeAttribute?.("src");
-        child.removeAttribute?.("poster");
-        child.load?.();
-      } catch (_) {}
-      try {
-        child.remove?.();
-      } catch (_) {}
-      if (staleSrc.startsWith("blob:")) revoke(staleSrc);
-    }
-
-    const video = document.createElement("video");
-    // Create muted for autoplay policy; applyMuteState() runs after play paths.
-    video.setAttribute("muted", "");
-    video.setAttribute("autoplay", "");
-    video.setAttribute("loop", "");
-    video.setAttribute("playsinline", "");
-    video.setAttribute("aria-hidden", "true");
-    video.muted = true;
-    video.defaultMuted = true;
-    video.autoplay = true;
-    video.loop = true;
-    video.playsInline = true;
-    video.preload = "auto";
-    // Pending replacement stays opacity 0; CSS + handoff keep prior frame.
-    // data-bc-media="video" stays set during handoff — inline opacity blocks
-    // the CSS rule from exposing this node (or its poster) early.
-    video.style.opacity = "0";
-    // Do NOT set video.poster when a separate <img> poster is on the stage.
-    // Dual posters are the classic image/video alternate flash. The img covers
-    // the gap; markReady strips any residual poster attr anyway.
-
-    const onReady = () => {
-      if (!isCurrent()) return;
-      markReady();
-    };
-    const onError = (ev) => {
-      // Detached / superseded videos must never fail the newer generation.
-      if (!isCurrent()) return;
-      const err = ev?.error || video.error || null;
-      if (isTransientVideoError(err, video) && retryTransientVideo()) {
-        return;
-      }
-      // If handoff still covers, stay pending rather than hard-fail to image.
-      if (handedOffVideo?.ready) {
-        pendingPlay = true;
-        retryTransientVideo();
-        return;
-      }
-      markFailed(err);
-    };
-    const onStalled = () => {
-      if (!isCurrent() || videoFailed) return;
-      pendingPlay = true;
-      retryTransientVideo();
+        stage.id = STAGE_ID;
+        stageEl = stage;
+        return stage;
     };
-    const onAbort = () => {
-      if (!isCurrent() || videoFailed) return;
-      // Abort during source swap is normal — never hard-fail.
-      pendingPlay = true;
-      retryTransientVideo();
+    const clearStage = () => {
+        const stage = document.getElementById(STAGE_ID);
+        if (stage)
+            stage.remove();
+        const style = document.getElementById(STYLE_ID);
+        if (style)
+            style.remove();
+        stageEl = null;
     };
-    const onEmptied = () => {
-      if (!isCurrent() || videoFailed || !video.src) return;
-      pendingPlay = true;
-      retryTransientVideo();
-    };
-    const onEnded = () => {
-      if (!isCurrent() || videoFailed || isDocHidden()) return;
-      try {
-        video.currentTime = 0;
-      } catch (_) {}
-      Promise.resolve(video.play?.())
-        .then(() => {
-          if (isCurrent()) {
-            pendingPlay = false;
-            if (!videoReady) markReady();
-          }
-        })
-        .catch(() => {
-          pendingPlay = true;
-          retryTransientVideo();
-        });
-    };
-    const onTimeUpdate = () => {
-      if (!isCurrent() || videoFailed) return;
-      const t = Number(video.currentTime);
-      if (!Number.isFinite(t)) return;
-      if (t < lastPlaybackTime || t - lastPlaybackTime >= 0.1) {
-        lastPlaybackTime = t;
-        retryCount = 0;
-        pendingPlay = false;
-        // timeupdate with progress is enough to reveal if events were missed.
-        if (!videoReady && (video.readyState >= 2 || t > 0)) {
-          markReady();
-        }
-      }
-    };
-    const onLoadedMetadata = () => {
-      if (!isCurrent() || videoFailed) return;
-      try {
-        applyPendingStartAt(video);
-      } catch (_) {}
-    };
-
-    const handlers = {
-      loadeddata: onReady,
-      canplay: onReady,
-      playing: onReady,
-      loadedmetadata: onLoadedMetadata,
-      error: onError,
-      stalled: onStalled,
-      abort: onAbort,
-      emptied: onEmptied,
-      ended: onEnded,
-      timeupdate: onTimeUpdate,
-    };
-    for (const [evt, fn] of Object.entries(handlers)) {
-      video.addEventListener(evt, fn);
-    }
-    document.addEventListener("visibilitychange", onVisibility);
-    videoListeners = { video, handlers, visibility: onVisibility };
-
-    stage.appendChild(video);
-    videoEl = video;
-    return video;
-  };
-
-  const doAttachVideoFile = async () => {
-    if (!isCurrent() || videoFailed) return false;
-    const input = document.getElementById(VIDEO_INPUT_ID);
-    const file = input && input.files && input.files[0] ? input.files[0] : null;
-    if (!file) return false;
-    const stage = ensureStage();
-    let video = videoEl;
-    if (!video || !video.isConnected) {
-      video = createVideoElement(stage);
-    }
-    try {
-      const objectUrl = URL.createObjectURL(playbackVideoFile(file));
-      return await playVideoObjectUrl(video, objectUrl);
-    } catch (err) {
-      if (isTransientVideoError(err, videoEl) && retryTransientVideo()) {
-        return false;
-      }
-      if (handedOffVideo?.ready) {
-        pendingPlay = true;
-        retryTransientVideo();
-        return false;
-      }
-      markFailed(err);
-      return false;
-    }
-  };
-
-  const startVideo = async (stage) => {
-    const video = createVideoElement(stage);
-
-    if (videoMode === "blob") {
-      createVideoInput();
-      // Prefer CDP file-input path. Optional tiny dataUrl is a warm start only.
-      if (videoDataUrl) {
-        try {
-          let src = videoDataUrl;
-          if (videoDataUrl.startsWith("data:")) {
-            src = await dataUrlToObjectUrl(videoDataUrl);
-            if (!isCurrent()) {
-              revoke(src);
-              return;
+    const releaseHandoff = () => {
+        if (!handedOffVideo)
+            return;
+        const old = handedOffVideo;
+        handedOffVideo = null;
+        // Only remove if it is not the current video element.
+        if (old.video && old.video !== video.element) {
+            try {
+                old.video.pause();
             }
-            if (src.startsWith("blob:")) videoObjectUrl = src;
-          }
-          video.style.opacity = "0";
-          video.src = src;
-          try {
-            const p = video.play();
-            if (p && typeof p.then === "function") {
-              p.then(() => {
-                if (isCurrent() && (video.readyState >= 2 || !video.paused)) {
-                  markReady();
-                }
-              }).catch(() => {});
+            catch (_) { }
+            try {
+                old.video.removeAttribute("src");
+                old.video.load();
+            }
+            catch (_) { }
+            try {
+                old.video.remove();
+            }
+            catch (_) { }
+            if (old.objectUrl && old.objectUrl !== video.objectUrl) {
+                revoke(old.objectUrl);
             }
-          } catch (_) {}
-        } catch (_) {
-          /* CDP attach is the real path */
         }
-      }
-      // If CDP already stuffed the input (attach raced ahead of apply),
-      // consume it on this generation's <video> instead of leaving an empty shell.
-      const input = document.getElementById(VIDEO_INPUT_ID);
-      if (input && input.files && input.files[0]) {
-        return doAttachVideoFile();
-      }
-      return;
-    }
-
-    let assigned = false;
-    if (videoDataUrl) {
-      try {
-        let src = videoDataUrl;
-        if (videoDataUrl.startsWith("data:")) {
-          src = await dataUrlToObjectUrl(videoDataUrl);
-          if (!isCurrent()) {
-            revoke(src);
+    };
+    const apply = async () => {
+        if (!remoteImageUrl && !dataImageUrl && !videoEnabled && !wantImageBlob) {
+            video.dispose();
+            image.dispose();
+            releaseHandoff();
+            clearStage();
+            image.clear();
+            working.stop();
+            setAttrs();
             return;
-          }
-          if (src.startsWith("blob:")) videoObjectUrl = src;
-        }
-        video.style.opacity = "0";
-        video.src = src;
-        assigned = true;
-      } catch (_) {
-        assigned = false;
-      }
-    }
-    if (!assigned && videoSrcRemote) {
-      try {
-        const obj = await fetchAsObjectUrl(videoSrcRemote, videoToken);
-        if (!isCurrent()) {
-          revoke(obj);
-          return;
         }
-        if (obj.startsWith("blob:")) videoObjectUrl = obj;
-        video.style.opacity = "0";
-        video.src = obj;
-        assigned = true;
-      } catch (_) {
-        assigned = false;
-      }
-    }
-    if (!assigned && videoSrcRemote) {
-      try {
-        video.style.opacity = "0";
-        video.src = videoSrcRemote;
-        assigned = true;
-      } catch (_) {
-        assigned = false;
-      }
-    }
-    if (!assigned) {
-      markFailed(new Error("no video source"));
-      return;
-    }
-    try {
-      const p = video.play();
-      if (p && typeof p.then === "function") {
-        p.then(() => {
-          if (isCurrent() && (video.readyState >= 2 || !video.paused)) {
-            markReady();
-          }
-        }).catch((err) => {
-          if (!isCurrent()) return;
-          if (isTransientVideoError(err, video) && retryTransientVideo()) return;
-          // keep pending if handoff covers
-          if (handedOffVideo?.ready) {
-            pendingPlay = true;
-            retryTransientVideo();
+        ensureStyle();
+        const stage = ensureStage();
+        // Do NOT stage.innerHTML = "" — that kills the handed-off video and flashes.
+        video.reset();
+        image.reset();
+        await image.resolvePoster();
+        if (!isCurrent())
             return;
-          }
-        });
-      }
-    } catch (_) {}
-  };
-
-  const ensurePosterImg = (stage) => {
-    let img = stage.querySelector("img");
-    if (!img) {
-      img = document.createElement("img");
-      img.alt = "";
-      img.draggable = false;
-      img.referrerPolicy = "no-referrer";
-      stage.insertBefore(img, stage.firstChild);
-    }
-    img.addEventListener(
-      "error",
-      () => {
-        if (!isCurrent()) return;
-        imageFailed = true;
-      },
-      { once: true },
-    );
-    if (resolvedPoster && img.getAttribute("src") !== resolvedPoster) {
-      img.src = resolvedPoster;
-    }
-    imgEl = img;
-    return img;
-  };
-
-  const waitForImageReady = (img) =>
-    new Promise((resolve) => {
-      if (!img) {
-        resolve(false);
-        return;
-      }
-      try {
-        if (img.complete && img.naturalWidth > 0) {
-          resolve(true);
-          return;
+        const poster = image.ensurePosterImg(stage);
+        // For a real image, wait for a decoded resource before switching the host
+        // surface to transparent. Blob imports intentionally wait for their CDP
+        // file-input attach path instead.
+        if (!videoEnabled && !wantImageBlob) {
+            const loaded = await image.waitForImageReady(poster);
+            if (!isCurrent())
+                return;
+            if (!loaded) {
+                image.fail();
+                setAttrs();
+                return;
+            }
         }
-      } catch (_) {}
-      let done = false;
-      const finish = (ok) => {
-        if (done) return;
-        done = true;
-        try {
-          img.removeEventListener("load", onLoad);
-          img.removeEventListener("error", onError);
-        } catch (_) {}
-        resolve(ok);
-      };
-      const onLoad = () => finish(true);
-      const onError = () => finish(false);
-      img.addEventListener("load", onLoad, { once: true });
-      img.addEventListener("error", onError, { once: true });
-      setTimeout(() => {
-        let ready = false;
-        try {
-          ready = img.complete && img.naturalWidth > 0;
-        } catch (_) {}
-        finish(Boolean(ready));
-      }, 2500);
-    });
-
-  const apply = async () => {
-    if (!remoteImageUrl && !dataImageUrl && !videoEnabled && !wantImageBlob) {
-      teardownVideo();
-      teardownImageBlob();
-      releaseHandoff();
-      clearStage();
-      clearGuestTransparency();
-      resolvedPoster = null;
-      stopWorkingWatch();
-      setAttrs();
-      return;
-    }
-
-    ensureStyle();
-    const stage = ensureStage();
-
-    // Do NOT stage.innerHTML = "" — that kills the handed-off video and flashes.
-    videoReady = false;
-    videoFailed = false;
-    videoError = null;
-    imageFailed = false;
-    retryCount = 0;
-    pendingPlay = false;
-    lastPlaybackTime = -1;
-    clearRetry();
-
-    await resolvePoster();
-    if (!isCurrent()) return;
-
-    const poster = ensurePosterImg(stage);
-    // For a real image, wait for a decoded resource before switching the host
-    // surface to transparent. Blob imports intentionally wait for their CDP
-    // file-input attach path instead.
-    if (!videoEnabled && !wantImageBlob) {
-      const loaded = await waitForImageReady(poster);
-      if (!isCurrent()) return;
-      if (!loaded) {
-        imageFailed = true;
+        // Video remains native/visible until startVideo reports its first frame;
+        // a ready handoff is the only permitted pending exception.
         setAttrs();
-        return;
-      }
-    }
-    // Video remains native/visible until startVideo reports its first frame;
-    // a ready handoff is the only permitted pending exception.
-    setAttrs();
-    startWorkingWatch();
-
-    if (videoEnabled) {
-      await startVideo(stage);
-    } else {
-      if (wantImageBlob) createImageInput();
-      // Image-only: remove any leftover videos including handoff.
-      releaseHandoff();
-      if (videoListeners) {
-        detachVideoListeners(videoListeners);
-        videoListeners = null;
-      }
-      for (const child of [...(stage.children || [])]) {
-        if (child.tagName === "VIDEO") {
-          try {
-            child.pause?.();
-          } catch (_) {}
-          try {
-            child.removeAttribute?.("src");
-            child.load?.();
-          } catch (_) {}
-          try {
-            child.remove();
-          } catch (_) {}
+        working.start();
+        if (videoEnabled) {
+            await video.start(stage);
         }
-      }
-      videoEl = null;
-    }
-  };
-
-  const api = {
-    generation: gen,
-    get videoReady() {
-      return videoReady;
-    },
-    get videoFailed() {
-      return videoFailed;
-    },
-    get videoError() {
-      return videoError;
-    },
-    get imageFailed() {
-      return imageFailed;
-    },
-    get pendingPlay() {
-      return pendingPlay;
-    },
-    get media() {
-      if (
-        !resolvedPoster &&
-        !videoEnabled &&
-        !remoteImageUrl &&
-        !dataImageUrl &&
-        !wantImageBlob
-      ) {
-        return "clear";
-      }
-      return videoEnabled && !videoFailed ? "video" : "image";
-    },
-    ensureVideoInput() {
-      if (!videoEnabled) return false;
-      createVideoInput();
-      return Boolean(document.getElementById(VIDEO_INPUT_ID));
-    },
-    attachVideoFile() {
-      return doAttachVideoFile();
-    },
-    ensureImageInput() {
-      if (videoEnabled) return false;
-      createImageInput();
-      return Boolean(document.getElementById(IMAGE_INPUT_ID));
-    },
-    attachImageFile() {
-      return doAttachImageFile();
-    },
-    /**
-     * Snapshot the current playable video for the next generation.
-     * Caller must then dispose({handoff:true}) so we do not tear it down.
-     * Listeners stay attached until the NEW generation's dispose/handoff path
-     * detaches them via the previous.dispose({handoff}) call below — actually
-     * we detach in dispose(handoff) so the old runtime cannot restart media.
-     */
-    handoffVideo() {
-      const stage = stageEl || document.getElementById(STAGE_ID);
-      const video = videoEl;
-      if (!stage || !video || !video.parentElement) return null;
-      const payload = {
-        stage,
-        video,
-        objectUrl: videoObjectUrl,
-        ready: videoReady && !videoFailed,
-      };
-      // Detach ownership so dispose won't revoke/remove these.
-      videoEl = null;
-      videoObjectUrl = null;
-      return payload;
-    },
-    dispose(opts) {
-      disposed = true;
-      clearRetry();
-      // Always stop working-state watchers; the next generation starts its own.
-      // Do not leave MutationObservers / intervals from a superseded runtime.
-      stopWorkingWatch();
-      stopGuestWatchers();
-      const handoff = Boolean(opts && opts.handoff);
-      if (!handoff) {
-        teardownVideo();
-        releaseHandoff();
-      } else {
-        // Preserve decoded frame + object URL only. Superseded runtime must
-        // not keep visibility/media listeners that can restart this node
-        // (Dream Skin 7a3b2ec / session 019fa31c).
-        if (videoListeners) {
-          detachVideoListeners(videoListeners);
-          videoListeners = null;
+        else {
+            if (wantImageBlob)
+                image.createImageInput();
+            // Image-only: remove any leftover videos including handoff.
+            releaseHandoff();
+            for (const child of [...(stage.children || [])]) {
+                if (child.tagName === "VIDEO") {
+                    try {
+                        child.pause?.();
+                    }
+                    catch (_) { }
+                    try {
+                        child.removeAttribute?.("src");
+                        child.load?.();
+                    }
+                    catch (_) { }
+                    try {
+                        child.remove();
+                    }
+                    catch (_) { }
+                }
+            }
+        }
+    };
+    const dispose = (opts = {}) => {
+        if (disposed)
+            return;
+        disposed = true;
+        working.stop();
+        video.dispose(opts);
+        image.dispose();
+        if (!opts.handoff) {
+            releaseHandoff();
+            guest.dispose();
+            window.__BEAUTICODE_THEME__?.stop();
+            clearStage();
+            for (const id of [VIDEO_INPUT_ID, IMAGE_INPUT_ID])
+                document.getElementById(id)?.remove();
+            for (const key of ["active", "media", "video-ready", "generation", "working", "fish", "tone"])
+                root.removeAttribute("data-bc-" + key);
+            controls.resetFish();
+        }
+    };
+    const api = createBackgroundApi({ gen, root, getStage: () => stageEl, isCurrent, videoEnabled, remoteImageUrl, dataImageUrl, wantImageBlob, image, video, controls, dispose });
+    window.__BEAUTICODE_BG__ = api;
+    return Promise.resolve().then(apply).then(() => ({ installed: true, generation: gen })).catch(err => {
+        if (isCurrent()) {
+            image.fail();
+            video.fail(err);
         }
-        videoEl = null;
-        // Do not revoke videoObjectUrl if handoff took it.
-      }
-      teardownImageBlob();
-      try {
-        const input = document.getElementById(VIDEO_INPUT_ID);
-        if (input && !handoff) input.remove();
-      } catch (_) {}
-      try {
-        const imageInput = document.getElementById(IMAGE_INPUT_ID);
-        if (imageInput && !handoff) imageInput.remove();
-      } catch (_) {}
-      if (!handoff) {
-        window.__BEAUTICODE_THEME__?.stop();
-        clearGuestTransparency();
-        clearStage();
-        root.removeAttribute("data-bc-active");
-        root.removeAttribute("data-bc-media");
-        root.removeAttribute("data-bc-video-ready");
-        root.removeAttribute("data-bc-generation");
-        root.removeAttribute("data-bc-working");
-        root.removeAttribute("data-bc-fish");
-        root.removeAttribute("data-bc-tone");
-        fishMode = false;
-      }
-      // handoff: leave data-bc-fish for the next generation to inherit.
-    },
-    isFishMode() {
-      return Boolean(fishMode);
-    },
-    setFishMode(enabled) {
-      return setFishMode(enabled);
-    },
-    isMuted() {
-      return Boolean(videoMuted);
-    },
-    setMuted(muted) {
-      return setMuted(muted);
-    },
-    isBackgroundTone() {
-      return backgroundTone;
-    },
-    setBackgroundTone(tone) {
-      return setBackgroundTone(tone);
-    },
-    /** Re-apply stored mute preference (used after CDP attach / heal). */
-    applyMutePreference() {
-      if (!isCurrent()) return { ok: false, muted: true, blocked: false, hasVideo: false };
-      const applied = applyMuteState();
-      return {
-        ok: true,
-        muted: Boolean(videoMuted),
-        blocked: Boolean(applied.blocked),
-        hasVideo: Boolean(applied.hasVideo),
-      };
-    },
-    /** Current <video> currentTime/duration for theme progress persistence. */
-    getPlaybackPosition() {
-      return getPlaybackPosition();
-    },
-    /**
-     * Seek live video (or remember for pending attach).
-     * Invalid / past end → 0.
-     */
-    seekTo(seconds) {
-      return seekTo(seconds);
-    },
-    snapshot() {
-      const stage = document.getElementById(STAGE_ID);
-      const img = stage ? stage.querySelector("img") : null;
-      const videos = stage ? [...stage.querySelectorAll("video")] : [];
-      // Prefer the current generation's element; fall back to any live node.
-      const liveVideo =
-        (videoEl && videoEl.isConnected && videoEl) ||
-        videos[videos.length - 1] ||
-        null;
-      const cs = stage ? window.getComputedStyle(stage) : null;
-      let imageNatural = 0;
-      try {
-        imageNatural = img && img.naturalWidth ? img.naturalWidth : 0;
-      } catch (_) {
-        imageNatural = 0;
-      }
-      // Own-generation readiness only. Handoff may keep data-bc-video-ready=true
-      // for CSS continuity, but host health checks must not treat "previous
-      // frame still covering" as "new blob attached" — that skips CDP attach
-      // and sticks the switch on the old media.
-      const ownVideoReady = Boolean(
-        videoReady && !videoFailed && liveVideo && liveVideo === videoEl,
-      );
-      const ownSrc =
-        liveVideo && typeof liveVideo.src === "string" ? liveVideo.src : "";
-      const hasPlayableSrc =
-        ownSrc.startsWith("blob:") || ownSrc.startsWith("data:");
-      let elementMuted = true;
-      try {
-        if (liveVideo) elementMuted = Boolean(liveVideo.muted);
-      } catch (_) {
-        elementMuted = true;
-      }
-      return {
-        generation: gen,
-        active: root.getAttribute("data-bc-active") === "true",
-        media: root.getAttribute("data-bc-media"),
-        working: root.getAttribute("data-bc-working") === "true",
-        fish: root.getAttribute("data-bc-fish") === "true",
-        muted: Boolean(videoMuted),
-        elementMuted,
-        videoReady: ownVideoReady,
-        videoFailed: Boolean(videoFailed),
-        hasStage: Boolean(stage),
-        hasImage: Boolean(img && img.getAttribute("src")),
-        imageLoaded: imageNatural > 0,
-        imageFailed: Boolean(imageFailed),
-        hasVideo: Boolean(liveVideo),
-        hasPlayableSrc,
-        videoCount: videos.length,
-        stagePointerEvents: cs ? cs.pointerEvents : null,
-        horizontalOverflow:
-          document.documentElement.scrollWidth >
-          document.documentElement.clientWidth + 1,
-        documentHidden: Boolean(document.hidden),
-        documentVisibility:
-          typeof document.visibilityState === "string"
-            ? document.visibilityState
-            : null,
-      };
-    },
-  };
-
-  window.__BEAUTICODE_BG__ = api;
-  // Runtime.evaluate(awaitPromise) must wait until the stage exists.
-  // Returning {installed} immediately used to let CDP setFileInputFiles
-  // attach a blob, then this apply() rebuilt <video> and threw it away —
-  // every Codex video import then sat in verify until the console timed out.
-  return Promise.resolve()
-    .then(apply)
-    .then(() => {
-      if (isBackgroundActive()) syncGuestTransparency();
-      else clearGuestTransparency();
-      return { installed: true, generation: gen };
-    })
-    .catch((err) => {
-      if (isCurrent()) {
-        imageFailed = true;
-        markFailed(err);
-      }
-      return { installed: true, generation: gen };
+        return { installed: true, generation: gen };
     });
 })
diff --git a/packages/adapter-codex/src/renderer/background.css b/packages/adapter-codex/src/renderer/background.css
index 5ab3662..a9eae53 100644
--- a/packages/adapter-codex/src/renderer/background.css
+++ b/packages/adapter-codex/src/renderer/background.css
@@ -260,11 +260,27 @@ html[data-bc-active="true"] body > #root main
 
 html[data-bc-active="true"] body > #root main
   .thread-scroll-container
-  .bg-gradient-to-t.from-token-main-surface-primary {
+  .bg-gradient-to-t.from-token-main-surface-primary,
+/* 26.1016 puts the bottom fade in an empty absolute child of the sticky
+   thread footer. Its from-surface gradient survives the older token rule. */
+html[data-bc-active="true"] body > #root main .thread-scroll-container
+  .pointer-events-none.sticky.bottom-0 >
+  .pointer-events-none.absolute.inset-x-0.from-surface:empty {
   background-image: none !important;
   background: transparent !important;
 }
 
+/* Codex 26.1016: an empty, non-interactive surface behind the composer paints
+   a large black rectangle outside the rounded input. Target its layout role,
+   not the generated CSS-module hash or every bg-surface (which includes cards).
+   The data-composer-body and functional panels below retain their opaque fill. */
+html[data-bc-active="true"] body > #root main
+  .pointer-events-none.absolute.inset-x-0.bottom-0 >
+  .pointer-events-none.absolute.inset-x-0.bottom-0.bg-surface:empty {
+  background: transparent !important;
+  background-image: none !important;
+}
+
 /* Home hero card chrome — keep interactive, drop solid fill. */
 html[data-bc-active="true"] body > #root main
   [role="main"]:has([data-testid="home-icon"])
@@ -357,103 +373,82 @@ html[data-bc-active="true"] :is([role="dialog"], [role="alertdialog"],
   background-color: var(--bc-readable-fill) !important;
 }
 
-/* A tooltip keeps the host's own dark surface and light label; forcing the
-   readable fill here left near-white text on white. The Radix popper wrapper
-   only positions a rounded panel, so painting it leaves a square plate behind
-   an otherwise correct menu. */
+/* Positioning shells must not paint square plates behind rounded panels. */
 html[data-bc-active="true"] [data-radix-popper-content-wrapper] {
   background: transparent !important;
-  background-color: transparent !important;
-  background-image: none !important;
-}
-
-/* Full-page ChatGPT routes mount in an Electron <webview>. Keep the host frame
-   clear so the wallpaper stays the window base; the runtime also clears the
-   guest document's own opaque surfaces. */
-html[data-bc-active="true"] body > #root
-  webview:not([src^="codex-sandbox:"]) {
-  background: transparent !important;
-  background-color: transparent !important;
-  background-image: none !important;
-}
-
-/* Composer chrome: Codex paints a tinted band behind the input and a tinted
-   notice above it. Drop that wash so the wallpaper stays the base layer; the
-   input body keeps its own white card. */
-html[data-bc-active="true"] body > #root main
-  [class*="_background_"][class*="_surface_"],
-html[data-bc-active="true"] body > #root main
-  [class*="_ComposerLayoutRoot_"] {
-  background-color: transparent !important;
-  background-image: none !important;
-}
-
-html[data-bc-active="true"] body > #root main aside {
-  background-color: rgba(255, 255, 255, 0.9) !important;
-  background-image: none !important;
-}
-
-/* Scroll fade above the composer: Codex fades into the themed surface, which
-   leaves a tinted strip over the wallpaper. Let the wallpaper carry it. */
-html[data-bc-active="true"] body > #root main
-  [class*="_background_"][class*="_fade_"] {
-  background-image: none !important;
-  background-color: transparent !important;
-}
-
-/* Content routes (Library, Sites, Images) paint a page-sized tinted surface
-   plus a header plate on the shell's ::before. Keep both on the wallpaper. */
-html[data-bc-active="true"] body > #root main
-  div.bg-surface:has([class*="_shell_"]) {
-  background-color: transparent !important;
-  background-image: none !important;
 }
 
-html[data-bc-active="true"] body > #root main
-  [class*="_shell_"]::before {
-  background-color: transparent !important;
-  background-image: none !important;
-}
-
-html[data-bc-active="true"] body > #root main
-  div.bg-surface:has([class*="empty-state-pag"]) {
-  background-color: transparent !important;
-  background-image: none !important;
-}
-
-/* Hover previews and other floating cards keep a light plate so the card
-   separates from the page behind it. Only overlay surfaces match, so a page
-   stays on the wallpaper after navigating there. */
+/* Floating surface plates follow the host palette. Ordinary tooltips and
+   beautiCode UI retain their own colors. */
 html[data-bc-active="true"]
   :is([data-overlay-owner], [data-overlay-owner] *)
   :is(.bg-surface, .bg-surface-secondary, .bg-surface-elevated,
-      .bg-surface-elevated-secondary):not([role="tooltip"], [role="tooltip"] *) {
-  background-color: rgba(253, 252, 254, 0.94) !important;
+      .bg-surface-elevated-secondary):not([role="tooltip"], [role="tooltip"] *):not(
+      [data-bc-ui], [data-bc-ui] *, #beauticode-console, #beauticode-console *,
+      #beauticode-console-pop, #beauticode-console-pop *,
+      #beauticode-gallery, #beauticode-gallery *,
+      #beauticode-name-dialog, #beauticode-name-dialog *) {
+  background-color: var(--bc-readable-fill) !important;
   background-image: none !important;
 }
-
 html[data-bc-active="true"] [data-overlay-owner]:is(
   .bg-surface, .bg-surface-secondary, .bg-surface-elevated,
-  .bg-surface-elevated-secondary):not([role="tooltip"]) {
-  background-color: rgba(253, 252, 254, 0.94) !important;
-  background-image: none !important;
+  .bg-surface-elevated-secondary):not([role="tooltip"]):not(
+    [data-bc-ui], [data-bc-ui] *, #beauticode-console, #beauticode-console *,
+    #beauticode-console-pop, #beauticode-console-pop *,
+    #beauticode-gallery, #beauticode-gallery *,
+    #beauticode-name-dialog, #beauticode-name-dialog *) {
+  background-color: var(--bc-readable-fill) !important;
 }
 
-/* Project and page peeks: the card's inner wrapper paints a square white
-   plate over the rounded shell, so the preview reads as a hard rectangle.
-   Inherit the radius and clip the wrapper; a hairline ring keeps the rounded
-   silhouette visible on light wallpapers. */
-html[data-bc-active="true"]
-  [role="tooltip"][data-overlay-owner="slate-sidebar"] {
-  border-radius: 18px !important;
-  background-color: rgba(250, 249, 253, 0.97) !important;
+/* Sidebar peeks are cards represented as tooltips. Preserve the native
+   radius and clip the painted direct surface wrapper, not its controls. */
+html[data-bc-active="true"] [role="tooltip"][data-overlay-owner="slate-sidebar"]:not(
+    [data-bc-ui], [data-bc-ui] *, #beauticode-console, #beauticode-console *,
+    #beauticode-console-pop, #beauticode-console-pop *,
+    #beauticode-gallery, #beauticode-gallery *,
+    #beauticode-name-dialog, #beauticode-name-dialog *) {
+  background-color: var(--bc-readable-fill) !important;
   overflow: hidden !important;
-  box-shadow:
-    0 18px 44px rgba(40, 22, 54, 0.22),
-    0 0 0 1px rgba(74, 35, 95, 0.1) !important;
+  box-shadow: 0 12px 32px #0003,
+    0 0 0 1px color-mix(in srgb, currentColor 12%, transparent) !important;
 }
-
-html[data-bc-active="true"]
-  [role="tooltip"][data-overlay-owner="slate-sidebar"] > * {
+html[data-bc-active="true"] [role="tooltip"][data-overlay-owner="slate-sidebar"]:not(
+    [data-bc-ui], [data-bc-ui] *, #beauticode-console, #beauticode-console *,
+    #beauticode-console-pop, #beauticode-console-pop *,
+    #beauticode-gallery, #beauticode-gallery *,
+    #beauticode-name-dialog, #beauticode-name-dialog *) >
+  :is(.bg-surface, .bg-surface-secondary, .bg-surface-elevated, .bg-surface-elevated-secondary) {
   border-radius: inherit !important;
+  background-color: inherit !important;
+}
+
+/* Native content route contract observed on 26.1016 (Sites): workspace slot,
+   full-height shell and centered tab panels. Nested reading cards are absent
+   from these selectors. No generated class names or viewport-size guesses. */
+html[data-bc-active="true"] main
+  .outline-none.flex.h-full.min-h-0.min-w-0.flex-1.flex-col >
+  .bg-surface.flex.h-full.min-h-0.flex-col:has([role="tabpanel"],
+    > .contents > .h-full.min-h-0.flex-1.overflow-y-auto >
+      .flex.min-h-full.w-full.flex-col > .border-transparent h1),
+html[data-bc-active="true"] main
+  .outline-none.flex.h-full.min-h-0.min-w-0.flex-1.flex-col >
+  .bg-surface.flex.h-full.min-h-0.flex-col
+  .mx-auto.bg-surface:has(> [role="tabpanel"]),
+html[data-bc-active="true"] main
+  .outline-none.flex.h-full.min-h-0.min-w-0.flex-1.flex-col >
+  .bg-surface.flex.h-full.min-h-0.flex-col
+  [role="tabpanel"].mx-auto.bg-surface {
+  background-color: transparent !important;
+  background-image: none !important;
+}
+
+/* The native header plate is a pseudo-element on the scroll shell, not h1.
+   Anchor to its observed layout hierarchy rather than the generated _shell_ hash. */
+html[data-bc-active="true"] main
+  .outline-none.flex.h-full.min-h-0.min-w-0.flex-1.flex-col .contents >
+  .h-full.min-h-0.flex-1.overflow-y-auto > .flex.min-h-full.w-full.flex-col >
+  .border-transparent:has(> .mx-auto.w-full h1):not([data-bc-ui], [data-bc-ui] *)::before {
+  background-color: transparent !important;
+  background-image: none !important;
 }
diff --git a/packages/adapter-codex/src/renderer/console.js b/packages/adapter-codex/src/renderer/console.js
index 12b904c..9543421 100644
--- a/packages/adapter-codex/src/renderer/console.js
+++ b/packages/adapter-codex/src/renderer/console.js
@@ -1,6 +1,6 @@
 (() => {
   "use strict";
-  const CONSOLE_REV = 12;
+  const CONSOLE_REV = 13;
   if (window.__beauticodeConsoleRev === CONSOLE_REV && window.__beauticodeConsoleLoaded) {
     try {
       window.__beauticodeConsolePlace?.();
@@ -171,82 +171,10 @@ body:not([data-ds-dark-theme]) #beauticode-console-pop{background:#f3f0e9;color:
   let currentThemeId = "";
   let themesExpanded = true;
 
-  const DIM_STORAGE_KEY = "beauticode-dim";
-  let userDim = null;
-
-  function clampDim(value) {
-    const n = Number(value);
-    if (!Number.isFinite(n) || n < 0 || n > 1) return null;
-    return n;
-  }
-
-  function readStoredDim() {
-    try {
-      const raw = globalThis.localStorage?.getItem(DIM_STORAGE_KEY);
-      if (raw == null || raw === "") return null;
-      return clampDim(raw);
-    } catch {
-      return null;
-    }
-  }
-
-  function writeStoredDim(value) {
-    try {
-      if (value == null) globalThis.localStorage?.removeItem(DIM_STORAGE_KEY);
-      else globalThis.localStorage?.setItem(DIM_STORAGE_KEY, String(value));
-    } catch {
-      /* private mode / quota */
-    }
-  }
-
-  function applyUserDim(value) {
-    const root = document.documentElement;
-    if (value == null) {
-      try {
-        root.removeAttribute("data-bc-dim-user");
-        root.style?.removeProperty?.("--bc-dim");
-      } catch {
-        /* ignore */
-      }
-      return null;
-    }
-    try {
-      root.setAttribute("data-bc-dim-user", "true");
-      root.style?.setProperty?.("--bc-dim", String(value));
-    } catch {
-      /* ignore */
-    }
-    return value;
-  }
-
-  function setUserDim(value) {
-    const next = clampDim(value);
-    if (next == null) return userDim;
-    userDim = next;
-    writeStoredDim(next);
-    applyUserDim(next);
-    return next;
-  }
-
-  function clearUserDim() {
-    userDim = null;
-    writeStoredDim(null);
-    applyUserDim(null);
-    return null;
-  }
-
-  userDim = readStoredDim();
-  if (userDim != null) applyUserDim(userDim);
-  globalThis.BeauticodeBackgroundDim = {
-    get: () => userDim,
-    set: setUserDim,
-    clear: clearUserDim,
-  };
-
   function renderDim() {
     const current = globalThis.BeauticodeBackgroundDim?.get?.() ?? null;
     if (current == null) {
-      dimSlider.value = String(AUTO_DIM_PERCENT);
+      dimSlider.value = String(isLightTone() ? AUTO_DIM_PERCENT : 0);
       dimValue.textContent = "自动";
       dimReset.hidden = true;
       return;
@@ -476,6 +404,7 @@ body:not([data-ds-dark-theme]) #beauticode-console-pop{background:#f3f0e9;color:
       // Host appearance can flip while the pop is closed; sampling it on open
       // keeps a closed pop free of observers on a very large tree.
       renderBlur();
+      renderDim();
       void refresh();
     }
   }
diff --git a/packages/adapter-codex/src/renderer/dim.js b/packages/adapter-codex/src/renderer/dim.js
new file mode 100644
index 0000000..d683523
--- /dev/null
+++ b/packages/adapter-codex/src/renderer/dim.js
@@ -0,0 +1,45 @@
+// Shadow belongs to the media lifecycle, not the optional sidebar console.
+// Install before the first frame; Codex may replace html.style during startup.
+(() => {
+  const installed = globalThis.BeauticodeBackgroundDim;
+  if (installed?.rev === 1) { installed.refresh(); return; }
+  installed?.stop?.();
+  const root = document.documentElement;
+  const key = 'beauticode-dim';
+  function parse(value) {
+    if (value == null || String(value).trim() === '') return null;
+    const number = Number(value);
+    return Number.isFinite(number) && number >= 0 && number <= 1 ? number : null;
+  }
+  let value = null;
+  try { value = parse(localStorage.getItem(key)); } catch { /* Storage may be unavailable. */ }
+  function refresh() {
+    if (value == null) {
+      if (root.hasAttribute('data-bc-dim-user')) root.removeAttribute('data-bc-dim-user');
+      if (root.style.getPropertyValue('--bc-dim')) root.style.removeProperty('--bc-dim');
+    } else {
+      if (root.getAttribute('data-bc-dim-user') !== 'true') root.setAttribute('data-bc-dim-user', 'true');
+      if (root.style.getPropertyValue('--bc-dim') !== String(value)) root.style.setProperty('--bc-dim', String(value));
+    }
+  }
+  function persist() {
+    try {
+      if (value == null) localStorage.removeItem(key);
+      else localStorage.setItem(key, String(value));
+    } catch { /* Keep the live preference when storage is unavailable. */ }
+    refresh();
+  }
+  // Observe only the host-owned root attributes; idempotent writes prevent a
+  // mutation loop. Keep the preference across clear/reapply until window close.
+  const observer = new MutationObserver(refresh);
+  observer.observe(root, { attributes: true, attributeFilter: ['style', 'data-bc-dim-user'] });
+  globalThis.BeauticodeBackgroundDim = {
+    rev: 1,
+    get: () => value,
+    set(next) { const parsed = parse(next); if (parsed != null) { value = parsed; persist(); } return value; },
+    clear() { value = null; persist(); return null; },
+    refresh,
+    stop() { observer.disconnect(); },
+  };
+  refresh();
+})();
diff --git a/packages/adapter-codex/src/renderer/guest-install.js b/packages/adapter-codex/src/renderer/guest-install.js
new file mode 100644
index 0000000..d040765
--- /dev/null
+++ b/packages/adapter-codex/src/renderer/guest-install.js
@@ -0,0 +1,25 @@
+/* Shared across media handoffs, with explicit full-dispose ownership. */
+(({ createController, policy }) => {
+    const REV = 1;
+    const installed = () => window.__BEAUTICODE_GUEST__;
+    return {
+        setActive(active) {
+            let owner = installed();
+            if (!active) {
+                owner?.controller.setActive(false);
+                return;
+            }
+            if (owner?.rev !== REV) {
+                owner?.controller.dispose();
+                owner = { rev: REV, controller: createController({ policy }) };
+                window.__BEAUTICODE_GUEST__ = owner;
+            }
+            owner.controller.setActive(true);
+        },
+        sync() { installed()?.controller.sync(); },
+        dispose() {
+            installed()?.controller.dispose();
+            delete window.__BEAUTICODE_GUEST__;
+        },
+    };
+})
diff --git a/packages/adapter-codex/src/renderer/guest-policy.js b/packages/adapter-codex/src/renderer/guest-policy.js
new file mode 100644
index 0000000..e4a0fd6
--- /dev/null
+++ b/packages/adapter-codex/src/renderer/guest-policy.js
@@ -0,0 +1,57 @@
+/* Codex content-route contract. The 26.1016 renderer declares these routes
+ * natively; older/alternate layouts may embed them. A matching route alone
+ * never authorises an arbitrary webview: intended/current URL and host slot
+ * must agree. Checkout, prewarming and unknown routes remain untouched.
+ * See ADR 0009 for evidence and the limits of the Electron acceptance. */
+(() => {
+    const routes = new Set(["/plugins", "/library", "/sites", "/images"]);
+    const css = `
+    html, body, body > #root, body > #__next {
+      background-color: transparent !important;
+      background-image: none !important;
+    }
+  `;
+    const parse = value => {
+        const url = new URL(value, "https://chatgpt.com");
+        if (url.protocol !== "https:" || url.hostname !== "chatgpt.com" ||
+            url.port || url.username || url.password)
+            return null;
+        return url;
+    };
+    const candidate = webview => {
+        try {
+            if (!webview.isConnected || !webview.closest("main"))
+                return null;
+            const src = new URL(webview.getAttribute("src") || "");
+            if (src.protocol !== "about:" || src.pathname !== "blank")
+                return null;
+            if (src.searchParams.get("prewarm") === "true")
+                return null;
+            const partition = webview.getAttribute("partition") || "";
+            if (/pricing|checkout|workspace-settings|sandbox/i.test(partition))
+                return null;
+            const intended = parse(src.searchParams.get("toUrl") || "");
+            if (!intended || !routes.has(intended.pathname))
+                return null;
+            return { route: intended.pathname, css };
+        }
+        catch {
+            // A not-yet-ready webview is reconsidered at dom-ready.
+            return null;
+        }
+    };
+    const policy = webview => {
+        const contract = candidate(webview);
+        if (!contract)
+            return null;
+        try {
+            const actual = parse(webview.getURL());
+            return actual?.pathname === contract.route ? contract : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    policy.candidate = candidate;
+    return policy;
+})
diff --git a/packages/adapter-codex/src/renderer/guest-wallpaper.js b/packages/adapter-codex/src/renderer/guest-wallpaper.js
new file mode 100644
index 0000000..6c4ddb6
--- /dev/null
+++ b/packages/adapter-codex/src/renderer/guest-wallpaper.js
@@ -0,0 +1,168 @@
+/* One document-scoped owner. Never captures a media generation. */
+(({ policy, timeoutMs = 3000 }) => {
+    const records = new Map();
+    let active = false, disposed = false, observer = null, scheduled = false;
+    const diagnose = (stage, reason) => {
+        console.warn("[beautiCode guest]", { stage, reason });
+    };
+    const remove = (w, key) => {
+        if (!key)
+            return;
+        try {
+            Promise.resolve(w.removeInsertedCSS(key)).catch(() => diagnose("remove", "rejected"));
+        }
+        catch {
+            diagnose("remove", "unavailable");
+        }
+    };
+    const invalidate = record => {
+        record.epoch++;
+        clearTimeout(record.timer);
+        record.timer = null;
+        remove(record.webview, record.key);
+        record.key = null;
+        record.route = null;
+    };
+    const detach = record => {
+        invalidate(record);
+        for (const [event, handler] of record.handlers) {
+            record.webview.removeEventListener(event, handler);
+        }
+        records.delete(record.webview);
+    };
+    const inject = record => {
+        const w = record.webview;
+        const contract = active && !disposed ? policy(w) : null;
+        if (!contract) {
+            invalidate(record);
+            return;
+        }
+        if (record.pending || (record.key && record.route === contract.route))
+            return;
+        if (typeof w.insertCSS !== "function" || typeof w.removeInsertedCSS !== "function") {
+            diagnose("insert", "unsupported");
+            return;
+        }
+        const epoch = record.epoch;
+        record.pending = true;
+        let expired = false;
+        const timer = setTimeout(() => {
+            expired = true;
+            diagnose("insert", "timeout");
+            // Electron's promise cannot be cancelled. Keep at most one outstanding
+            // call, and revoke its key even if it resolves after this timeout.
+        }, timeoutMs);
+        record.timer = timer;
+        let result;
+        try {
+            result = w.insertCSS(contract.css);
+        }
+        catch {
+            result = Promise.reject(new Error("insert unavailable"));
+        }
+        Promise.resolve(result).then(key => {
+            const now = active && !disposed ? policy(w) : null;
+            if (expired || !records.has(w) || epoch !== record.epoch ||
+                !now || now.route !== contract.route) {
+                remove(w, key);
+                return;
+            }
+            record.key = key;
+            record.route = contract.route;
+        }, () => diagnose("insert", "rejected")).finally(() => {
+            clearTimeout(timer);
+            if (record.timer === timer)
+                record.timer = null;
+            record.pending = false;
+            // Navigation can request a new document while the previous call is
+            // unresolved. Converge once; ordinary rejection does not auto-retry.
+            if (records.get(w) === record && active && !disposed &&
+                epoch !== record.epoch && policy(w))
+                inject(record);
+        });
+    };
+    const bind = webview => {
+        if (records.has(webview))
+            return records.get(webview);
+        const record = { webview, key: null, route: null, epoch: 0, pending: false, timer: null, handlers: [] };
+        // Bind only allowed content, never sandbox, checkout or hidden prewarmers.
+        if (!policy.candidate(webview))
+            return null;
+        for (const event of ["dom-ready", "did-navigate", "did-navigate-in-page"]) {
+            const handler = e => {
+                if (e.isMainFrame === false)
+                    return;
+                invalidate(record);
+                inject(record);
+            };
+            webview.addEventListener(event, handler);
+            record.handlers.push([event, handler]);
+        }
+        const navigating = e => {
+            if (e.isMainFrame === false)
+                return;
+            invalidate(record);
+        };
+        webview.addEventListener("did-start-navigation", navigating);
+        record.handlers.push(["did-start-navigation", navigating]);
+        records.set(webview, record);
+        return record;
+    };
+    const sync = () => {
+        if (!active || disposed)
+            return;
+        const nodes = new Set(document.querySelectorAll("webview"));
+        for (const [w, record] of records) {
+            if (!nodes.has(w) || !w.isConnected || !policy.candidate(w))
+                detach(record);
+        }
+        for (const w of nodes) {
+            const record = bind(w);
+            if (record)
+                inject(record);
+        }
+    };
+    const schedule = () => {
+        if (scheduled)
+            return;
+        scheduled = true;
+        Promise.resolve().then(() => { scheduled = false; sync(); });
+    };
+    const setActive = value => {
+        if (disposed)
+            return;
+        const next = Boolean(value);
+        if (next === active) {
+            if (active)
+                sync();
+            return;
+        }
+        active = next;
+        if (active) {
+            observer = new MutationObserver(records => {
+                if (records.some(r => r.type === "attributes" ||
+                    [...r.addedNodes, ...r.removedNodes].some(n => n.nodeType === 1 && (n.tagName === "WEBVIEW" || n.querySelector?.("webview")))))
+                    schedule();
+            });
+            observer.observe(document.documentElement, {
+                subtree: true, childList: true, attributes: true, attributeFilter: ["src"],
+            });
+            sync();
+        }
+        else {
+            observer?.disconnect();
+            observer = null;
+            for (const record of [...records.values()])
+                detach(record);
+        }
+    };
+    return {
+        setActive, sync,
+        dispose() {
+            if (disposed)
+                return;
+            setActive(false);
+            disposed = true;
+        },
+    };
+})
diff --git a/packages/adapter-codex/src/renderer/runtime-api.js b/packages/adapter-codex/src/renderer/runtime-api.js
new file mode 100644
index 0000000..a22530f
--- /dev/null
+++ b/packages/adapter-codex/src/renderer/runtime-api.js
@@ -0,0 +1,160 @@
+/* Private state belongs to this module; callers receive operations and read-only views. */
+(({ gen, root, getStage, isCurrent, videoEnabled, remoteImageUrl, dataImageUrl, wantImageBlob, image, video, controls, dispose }) => {
+    const STAGE_ID = "beauticode-bg-stage";
+    const VIDEO_INPUT_ID = "beauticode-video-input";
+    const IMAGE_INPUT_ID = "beauticode-image-input";
+    const api = {
+        generation: gen,
+        get videoReady() {
+            return video.ready;
+        },
+        get videoFailed() {
+            return video.failed;
+        },
+        get videoError() {
+            return video.error;
+        },
+        get imageFailed() {
+            return image.failed;
+        },
+        get pendingPlay() {
+            return video.pending;
+        },
+        get media() {
+            if (!image.poster &&
+                !videoEnabled &&
+                !remoteImageUrl &&
+                !dataImageUrl &&
+                !wantImageBlob) {
+                return "clear";
+            }
+            return videoEnabled && !video.failed ? "video" : "image";
+        },
+        ensureVideoInput() {
+            if (!videoEnabled)
+                return false;
+            video.createVideoInput();
+            return Boolean(document.getElementById(VIDEO_INPUT_ID));
+        },
+        attachVideoFile() {
+            return video.attach();
+        },
+        ensureImageInput() {
+            if (videoEnabled)
+                return false;
+            image.createImageInput();
+            return Boolean(document.getElementById(IMAGE_INPUT_ID));
+        },
+        attachImageFile() {
+            return image.attach();
+        },
+        /**
+         * Snapshot the current playable video for the next generation.
+         * Caller must then dispose({handoff:true}) so we do not tear it down.
+         * Listeners stay attached until the NEW generation's dispose/handoff path
+         * detaches them via the previous.dispose({handoff}) call below — actually
+         * we detach in dispose(handoff) so the old runtime cannot restart media.
+         */
+        handoffVideo() { return video.handoff(getStage()); },
+        dispose,
+        isFishMode() {
+            return Boolean(controls.fish);
+        },
+        setFishMode(enabled) {
+            return controls.setFishMode(enabled);
+        },
+        isMuted() {
+            return Boolean(controls.muted);
+        },
+        setMuted(muted) {
+            return controls.setMuted(muted);
+        },
+        isBackgroundTone() {
+            return controls.tone;
+        },
+        setBackgroundTone(tone) {
+            return controls.setBackgroundTone(tone);
+        },
+        /** Re-apply stored mute preference (used after CDP attach / heal). */
+        applyMutePreference() {
+            if (!isCurrent())
+                return { ok: false, muted: true, blocked: false, hasVideo: false };
+            const applied = controls.applyMuteState();
+            return {
+                ok: true,
+                muted: Boolean(controls.muted),
+                blocked: Boolean(applied.blocked),
+                hasVideo: Boolean(applied.hasVideo),
+            };
+        },
+        /** Current <video> currentTime/duration for theme progress persistence. */
+        getPlaybackPosition() {
+            return controls.getPlaybackPosition();
+        },
+        /**
+         * Seek live video (or remember for pending attach).
+         * Invalid / past end → 0.
+         */
+        seekTo(seconds) {
+            return controls.seekTo(seconds);
+        },
+        snapshot() {
+            const stage = document.getElementById(STAGE_ID);
+            const img = stage ? stage.querySelector("img") : null;
+            const videos = stage ? [...stage.querySelectorAll("video")] : [];
+            // Prefer the current generation's element; fall back to any live node.
+            const liveVideo = (video.element && video.element.isConnected && video.element) ||
+                videos[videos.length - 1] ||
+                null;
+            const cs = stage ? window.getComputedStyle(stage) : null;
+            let imageNatural = 0;
+            try {
+                imageNatural = img && img.naturalWidth ? img.naturalWidth : 0;
+            }
+            catch (_) {
+                imageNatural = 0;
+            }
+            // Own-generation readiness only. Handoff may keep data-bc-video-ready=true
+            // for CSS continuity, but host health checks must not treat "previous
+            // frame still covering" as "new blob attached" — that skips CDP attach
+            // and sticks the switch on the old media.
+            const ownVideoReady = Boolean(video.ready && !video.failed && liveVideo && liveVideo === video.element);
+            const ownSrc = liveVideo && typeof liveVideo.src === "string" ? liveVideo.src : "";
+            const hasPlayableSrc = ownSrc.startsWith("blob:") || ownSrc.startsWith("data:");
+            let elementMuted = true;
+            try {
+                if (liveVideo)
+                    elementMuted = Boolean(liveVideo.muted);
+            }
+            catch (_) {
+                elementMuted = true;
+            }
+            return {
+                generation: gen,
+                active: root.getAttribute("data-bc-active") === "true",
+                media: root.getAttribute("data-bc-media"),
+                working: root.getAttribute("data-bc-working") === "true",
+                fish: root.getAttribute("data-bc-fish") === "true",
+                muted: Boolean(controls.muted),
+                elementMuted,
+                videoReady: ownVideoReady,
+                videoFailed: Boolean(video.failed),
+                hasStage: Boolean(stage),
+                hasImage: Boolean(img && img.getAttribute("src")),
+                imageLoaded: imageNatural > 0,
+                imageFailed: Boolean(image.failed),
+                hasVideo: Boolean(liveVideo),
+                hasPlayableSrc,
+                videoCount: videos.length,
+                stagePointerEvents: cs ? cs.pointerEvents : null,
+                horizontalOverflow: document.documentElement.scrollWidth >
+                    document.documentElement.clientWidth + 1,
+                documentHidden: Boolean(document.hidden),
+                documentVisibility: typeof document.visibilityState === "string"
+                    ? document.visibilityState
+                    : null,
+            };
+        },
+    };
+    return api;
+})
diff --git a/packages/adapter-codex/src/renderer/runtime-controls.js b/packages/adapter-codex/src/renderer/runtime-controls.js
new file mode 100644
index 0000000..7e83b9e
--- /dev/null
+++ b/packages/adapter-codex/src/renderer/runtime-controls.js
@@ -0,0 +1,306 @@
+/* Private state belongs to this module; callers receive operations and read-only views. */
+(({ root, previous, normalizedVideo, isCurrent, hasBackgroundMedia, getStage, getVideo, setAttrs }) => {
+    let fishMode = false;
+    try {
+        if (previous && typeof previous.isFishMode === "function") {
+            fishMode = Boolean(previous.isFishMode());
+        }
+        else if (root.getAttribute("data-bc-fish") === "true") {
+            fishMode = true;
+        }
+    }
+    catch (_) {
+        fishMode = false;
+    }
+    // Video mute preference (default muted). Independent of fish mode.
+    // Start playback muted for autoplay policy, then unmute if preferred.
+    // Process-local via previous runtime; not persisted across tray restarts.
+    let videoMuted = true;
+    try {
+        if (previous && typeof previous.isMuted === "function") {
+            videoMuted = Boolean(previous.isMuted());
+        }
+    }
+    catch (_) {
+        videoMuted = true;
+    }
+    // Background tone is a CSS-only preference. Keep dark as the legacy
+    // default, and carry the preference across same-generation/rebuild paths.
+    const normalizeTone = (value) => value === "light" || value === "auto" ? value : "dark";
+    let backgroundTone = "dark";
+    try {
+        if (previous && typeof previous.isBackgroundTone === "function") {
+            backgroundTone = normalizeTone(previous.isBackgroundTone());
+        }
+        else {
+            backgroundTone = normalizeTone(root.getAttribute("data-bc-tone"));
+        }
+    }
+    catch (_) {
+        backgroundTone = "dark";
+    }
+    // Optional initial seek for saved-theme restore (seconds). Applied once when
+    // the live <video> has metadata. Invalid / past end → 0 (start over).
+    let pendingStartAt = null;
+    let startAtApplied = false;
+    try {
+        const rawStart = normalizedVideo && typeof normalizedVideo.startAt === "number"
+            ? normalizedVideo.startAt
+            : null;
+        if (rawStart != null && Number.isFinite(rawStart) && rawStart > 0) {
+            // Cap absurd values; host also clamps.
+            pendingStartAt = Math.min(rawStart, 24 * 60 * 60);
+        }
+    }
+    catch (_) {
+        pendingStartAt = null;
+    }
+    // Focus dim: only when a project/task thread is confirmed open, set
+    // data-bc-working so CSS can slightly darken the RIGHT main column.
+    const applyFishAttr = () => {
+        try {
+            if (fishMode && hasBackgroundMedia()) {
+                root.setAttribute("data-bc-fish", "true");
+            }
+            else {
+                root.removeAttribute("data-bc-fish");
+                if (!hasBackgroundMedia())
+                    fishMode = false;
+            }
+        }
+        catch (_) { }
+    };
+    const setFishMode = (enabled) => {
+        if (!isCurrent())
+            return false;
+        const want = Boolean(enabled);
+        if (want && !hasBackgroundMedia()) {
+            fishMode = false;
+            applyFishAttr();
+            return false;
+        }
+        fishMode = want;
+        applyFishAttr();
+        if (want) {
+            // Light input guard: drop focus so typing is less likely to hit composer.
+            try {
+                const ae = document.activeElement;
+                if (ae && typeof ae.blur === "function")
+                    ae.blur();
+            }
+            catch (_) { }
+        }
+        return true;
+    };
+    const listStageVideos = () => {
+        const out = [];
+        const stage = getStage() || document.getElementById("beauticode-bg-stage");
+        if (stage) {
+            try {
+                for (const v of stage.querySelectorAll("video")) {
+                    if (v && out.indexOf(v) === -1)
+                        out.push(v);
+                }
+            }
+            catch (_) { }
+        }
+        if (getVideo() && out.indexOf(getVideo()) === -1)
+            out.push(getVideo());
+        return out;
+    };
+    /**
+     * Apply preferred mute state to live <video> nodes.
+     * Always starts from the preference; callers that need autoplay-safe cold
+     * start should mute first, play, then call this again.
+     */
+    const applyMuteState = () => {
+        const videos = listStageVideos();
+        let anyStillMuted = false;
+        for (const v of videos) {
+            try {
+                if (videoMuted) {
+                    v.muted = true;
+                    v.defaultMuted = true;
+                    v.setAttribute("muted", "");
+                }
+                else {
+                    v.muted = false;
+                    v.defaultMuted = false;
+                    v.removeAttribute("muted");
+                }
+                if (v.muted)
+                    anyStillMuted = true;
+            }
+            catch (_) {
+                anyStillMuted = true;
+            }
+        }
+        return {
+            preferredMuted: Boolean(videoMuted),
+            // Blocked only when we wanted sound but every/any live node stayed muted.
+            blocked: !videoMuted && videos.length > 0 && anyStillMuted,
+            hasVideo: videos.length > 0,
+        };
+    };
+    /**
+     * Set mute preference. Does not rebuild media.
+     * Returns { ok, muted, blocked, hasVideo }.
+     * muted = preferred state (true = silent). blocked = wanted sound but element stayed muted.
+     */
+    const setMuted = (muted) => {
+        if (!isCurrent()) {
+            return {
+                ok: false,
+                muted: Boolean(videoMuted),
+                blocked: false,
+                hasVideo: false,
+            };
+        }
+        videoMuted = Boolean(muted);
+        const applied = applyMuteState();
+        return {
+            ok: true,
+            muted: Boolean(videoMuted),
+            blocked: Boolean(applied.blocked),
+            hasVideo: Boolean(applied.hasVideo),
+        };
+    };
+    const setBackgroundTone = (tone) => {
+        if (!isCurrent())
+            return false;
+        backgroundTone = normalizeTone(tone);
+        setAttrs();
+        return true;
+    };
+    /**
+     * Clamp a desired seek time against live duration.
+     * Invalid / NaN / negative / past end → 0 (start over, per product rule).
+     */
+    const clampSeekSeconds = (sec, duration) => {
+        const t = typeof sec === "number" ? sec : Number(sec);
+        if (!Number.isFinite(t) || t <= 0)
+            return 0;
+        const d = typeof duration === "number" ? duration : Number(duration);
+        if (Number.isFinite(d) && d > 0 && t >= d)
+            return 0;
+        if (t > 24 * 60 * 60)
+            return 0;
+        return t;
+    };
+    /**
+     * Apply pendingStartAt once metadata is available. Fail-soft → 0.
+     * Returns the seconds actually seeked to (or null if not yet applied).
+     */
+    const applyPendingStartAt = (video) => {
+        if (startAtApplied || pendingStartAt == null)
+            return null;
+        if (!video || !isCurrent())
+            return null;
+        let duration = NaN;
+        try {
+            duration = Number(video.duration);
+        }
+        catch (_) {
+            duration = NaN;
+        }
+        // Wait for metadata when duration is still unknown.
+        if (!(Number.isFinite(duration) && duration > 0) && (video.readyState || 0) < 1) {
+            return null;
+        }
+        const target = clampSeekSeconds(pendingStartAt, duration);
+        startAtApplied = true;
+        pendingStartAt = null;
+        try {
+            video.currentTime = target;
+        }
+        catch (_) {
+            try {
+                video.currentTime = 0;
+            }
+            catch (_) { }
+            return 0;
+        }
+        return target;
+    };
+    /** Current playback position for continuous theme progress writes. */
+    const getPlaybackPosition = () => {
+        if (!isCurrent()) {
+            return { ok: false, currentTime: 0, duration: 0, hasVideo: false };
+        }
+        const videos = listStageVideos();
+        const live = (getVideo() && getVideo().isConnected && getVideo()) ||
+            videos[videos.length - 1] ||
+            null;
+        if (!live) {
+            return { ok: true, currentTime: 0, duration: 0, hasVideo: false };
+        }
+        let currentTime = 0;
+        let duration = 0;
+        try {
+            const t = Number(live.currentTime);
+            if (Number.isFinite(t) && t >= 0)
+                currentTime = t;
+        }
+        catch (_) { }
+        try {
+            const d = Number(live.duration);
+            if (Number.isFinite(d) && d > 0)
+                duration = d;
+        }
+        catch (_) { }
+        return {
+            ok: true,
+            currentTime,
+            duration,
+            hasVideo: true,
+        };
+    };
+    /**
+     * Seek live video. Invalid / past end → 0. Does not rebuild media.
+     */
+    const seekTo = (seconds) => {
+        if (!isCurrent()) {
+            return { ok: false, currentTime: 0, hasVideo: false };
+        }
+        const videos = listStageVideos();
+        const live = (getVideo() && getVideo().isConnected && getVideo()) ||
+            videos[videos.length - 1] ||
+            null;
+        if (!live) {
+            // Remember for when the blob attaches.
+            const t = clampSeekSeconds(seconds, NaN);
+            pendingStartAt = t > 0 ? t : null;
+            startAtApplied = false;
+            return { ok: true, currentTime: t, hasVideo: false };
+        }
+        let duration = NaN;
+        try {
+            duration = Number(live.duration);
+        }
+        catch (_) {
+            duration = NaN;
+        }
+        const target = clampSeekSeconds(seconds, duration);
+        startAtApplied = true;
+        pendingStartAt = null;
+        try {
+            live.currentTime = target;
+        }
+        catch (_) {
+            try {
+                live.currentTime = 0;
+            }
+            catch (_) { }
+            return { ok: true, currentTime: 0, hasVideo: true };
+        }
+        let now = target;
+        try {
+            const t = Number(live.currentTime);
+            if (Number.isFinite(t))
+                now = t;
+        }
+        catch (_) { }
+        return { ok: true, currentTime: now, hasVideo: true };
+    };
+    return { setFishMode, applyFishAttr, setMuted, applyMuteState, setBackgroundTone, applyPendingStartAt, getPlaybackPosition, seekTo, resetFish() { fishMode = false; }, get fish() { return fishMode; }, get muted() { return videoMuted; }, get tone() { return backgroundTone; } };
+})
diff --git a/packages/adapter-codex/src/renderer/runtime-image.js b/packages/adapter-codex/src/renderer/runtime-image.js
new file mode 100644
index 0000000..129dacc
--- /dev/null
+++ b/packages/adapter-codex/src/renderer/runtime-image.js
@@ -0,0 +1,122 @@
+/* Private state belongs to this module; callers receive operations and read-only views. */
+(({ isCurrent, ensureStage, setAttrs, dataImageUrl, remoteImageUrl, sources }) => {
+    const waiter = createMediaWaiter({ isCurrent });
+    const errorHandlers = new Map();
+    const IMAGE_INPUT_ID = "beauticode-image-input";
+    const { revoke, fetchAsObjectUrl } = sources;
+    let imageFailed = false, imageObjectUrl = null, imgEl = null, resolvedPoster = dataImageUrl;
+    const teardownImageBlob = () => {
+        waiter.dispose();
+        for (const [img, handler] of errorHandlers)
+            img.removeEventListener("error", handler);
+        errorHandlers.clear();
+        if (imageObjectUrl)
+            revoke(imageObjectUrl);
+        imageObjectUrl = null;
+    };
+    const resolvePoster = async () => {
+        if (dataImageUrl) {
+            resolvedPoster = dataImageUrl;
+            imageFailed = false;
+            return resolvedPoster;
+        }
+        if (remoteImageUrl) {
+            try {
+                let token = null;
+                try {
+                    token = new URL(remoteImageUrl, "http://127.0.0.1").searchParams.get("t");
+                }
+                catch (_) { }
+                const obj = await fetchAsObjectUrl(remoteImageUrl, token);
+                if (!isCurrent()) {
+                    revoke(obj);
+                    return null;
+                }
+                if (obj.startsWith("blob:"))
+                    imageObjectUrl = obj;
+                resolvedPoster = obj;
+                imageFailed = false;
+                return resolvedPoster;
+            }
+            catch (_) {
+                imageFailed = true;
+            }
+        }
+        resolvedPoster = null;
+        return null;
+    };
+    const createImageInput = () => {
+        let input = document.getElementById(IMAGE_INPUT_ID);
+        if (input)
+            return input;
+        input = document.createElement("input");
+        input.type = "file";
+        input.id = IMAGE_INPUT_ID;
+        input.accept = "image/jpeg,image/png,image/webp,image/avif,.jpg,.jpeg,.png,.webp,.avif";
+        input.tabIndex = -1;
+        input.setAttribute("aria-hidden", "true");
+        Object.assign(input.style, {
+            position: "fixed",
+            width: "1px",
+            height: "1px",
+            opacity: "0",
+            pointerEvents: "none",
+        });
+        (document.body || document.documentElement).appendChild(input);
+        return input;
+    };
+    const doAttachImageFile = async () => {
+        if (!isCurrent())
+            return false;
+        const input = document.getElementById(IMAGE_INPUT_ID);
+        const file = input && input.files && input.files[0] ? input.files[0] : null;
+        if (!file)
+            return false;
+        try {
+            const objectUrl = URL.createObjectURL(file);
+            if (imageObjectUrl && imageObjectUrl !== objectUrl)
+                revoke(imageObjectUrl);
+            imageObjectUrl = objectUrl;
+            resolvedPoster = objectUrl;
+            imageFailed = false;
+            const stage = ensureStage();
+            const img = ensurePosterImg(stage);
+            const ready = await waitForImageReady(img);
+            if (!isCurrent())
+                return false;
+            imageFailed = !ready;
+            setAttrs();
+            return Boolean(!imageFailed && img.getAttribute("src"));
+        }
+        catch (_) {
+            imageFailed = true;
+            setAttrs();
+            return false;
+        }
+    };
+    const ensurePosterImg = (stage) => {
+        let img = stage.querySelector("img");
+        if (!img) {
+            img = document.createElement("img");
+            img.alt = "";
+            img.draggable = false;
+            img.referrerPolicy = "no-referrer";
+            stage.insertBefore(img, stage.firstChild);
+        }
+        if (!errorHandlers.has(img)) {
+            const onError = () => { if (isCurrent()) {
+                imageFailed = true;
+                setAttrs();
+            } };
+            img.addEventListener("error", onError);
+            errorHandlers.set(img, onError);
+        }
+        if (resolvedPoster && img.getAttribute("src") !== resolvedPoster) {
+            img.src = resolvedPoster;
+        }
+        imgEl = img;
+        return img;
+    };
+    const waitForImageReady = img => waiter.wait(img, ["load"], () => Boolean(img.complete && img.naturalWidth > 0));
+    return { resolvePoster, ensurePosterImg, waitForImageReady, createImageInput, attach: doAttachImageFile, dispose: teardownImageBlob, reset() { imageFailed = false; }, fail() { imageFailed = true; }, clear() { teardownImageBlob(); resolvedPoster = null; imgEl = null; }, get failed() { return imageFailed; }, get element() { return imgEl; }, get poster() { return resolvedPoster; } };
+})
diff --git a/packages/adapter-codex/src/renderer/runtime-media-wait.js b/packages/adapter-codex/src/renderer/runtime-media-wait.js
new file mode 100644
index 0000000..a6c79b1
--- /dev/null
+++ b/packages/adapter-codex/src/renderer/runtime-media-wait.js
@@ -0,0 +1,36 @@
+/* Images and video attachments both need a cancellable native-event wait. */
+(({ isCurrent }) => {
+    const pending = new Set();
+    const wait = (element, events, ready, timeoutMs = 2500) => new Promise(resolve => {
+        if (!isCurrent() || !element) {
+            resolve(false);
+            return;
+        }
+        if (ready()) {
+            resolve(true);
+            return;
+        }
+        let timer, done = false;
+        const finish = value => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            for (const event of events)
+                element.removeEventListener(event, onReady);
+            element.removeEventListener("error", onError);
+            pending.delete(cancel);
+            resolve(Boolean(value && isCurrent()));
+        };
+        const onReady = () => finish(ready());
+        const onError = () => finish(false);
+        const cancel = () => finish(false);
+        pending.add(cancel);
+        for (const event of events)
+            element.addEventListener(event, onReady);
+        element.addEventListener("error", onError);
+        timer = setTimeout(() => finish(ready()), timeoutMs);
+    });
+    return { wait, dispose() { for (const cancel of [...pending])
+            cancel(); } };
+})
diff --git a/packages/adapter-codex/src/renderer/runtime-sources.js b/packages/adapter-codex/src/renderer/runtime-sources.js
new file mode 100644
index 0000000..5af7e94
--- /dev/null
+++ b/packages/adapter-codex/src/renderer/runtime-sources.js
@@ -0,0 +1,103 @@
+/* Private state belongs to this module; callers receive operations and read-only views. */
+(({ isCurrent }) => {
+    const toChineseMediaError = (error) => {
+        const message = String(error?.message || error || "").trim();
+        if (/^(?:failed to fetch|fetch failed|fail fetch)$/i.test(message)) {
+            return "未发现注入CDP的Codex进程";
+        }
+        if (/media fetch failed/i.test(message)) {
+            return "背景媒体加载失败。";
+        }
+        if (/data url fetch failed/i.test(message)) {
+            return "背景数据加载失败。";
+        }
+        if (/missing (?:media )?url|no video source/i.test(message)) {
+            return "背景媒体地址缺失。";
+        }
+        if (/malformed data url/i.test(message)) {
+            return "背景数据地址格式错误。";
+        }
+        if (/stale generation/i.test(message)) {
+            return "背景版本已过期，正在重新加载。";
+        }
+        return message || "背景媒体加载失败。";
+    };
+    const revoke = (url) => {
+        if (!url || typeof url !== "string" || !url.startsWith("blob:"))
+            return;
+        try {
+            URL.revokeObjectURL(url);
+        }
+        catch (_) { }
+    };
+    const dataUrlToObjectUrl = async (dataUrl) => {
+        if (!dataUrl || typeof dataUrl !== "string") {
+            throw new Error("missing data url");
+        }
+        if (dataUrl.startsWith("blob:"))
+            return dataUrl;
+        if (!dataUrl.startsWith("data:"))
+            return dataUrl;
+        try {
+            const res = await fetch(dataUrl);
+            if (!res.ok)
+                throw new Error("data url fetch failed: " + res.status);
+            const blob = await res.blob();
+            if (!isCurrent())
+                throw new Error("stale generation");
+            return URL.createObjectURL(blob);
+        }
+        catch (_) {
+            const comma = dataUrl.indexOf(",");
+            if (comma < 0)
+                throw new Error("malformed data url");
+            const meta = dataUrl.slice(0, comma);
+            const payload = dataUrl.slice(comma + 1);
+            const mimeMatch = /^data:([^;,]+)/i.exec(meta);
+            const mime = mimeMatch ? mimeMatch[1] : "application/octet-stream";
+            const isBase64 = /;base64/i.test(meta);
+            let bytes;
+            if (isBase64) {
+                const bin = atob(payload);
+                bytes = new Uint8Array(bin.length);
+                for (let i = 0; i < bin.length; i += 1)
+                    bytes[i] = bin.charCodeAt(i);
+            }
+            else {
+                const decoded = decodeURIComponent(payload);
+                bytes = new Uint8Array(decoded.length);
+                for (let i = 0; i < decoded.length; i += 1) {
+                    bytes[i] = decoded.charCodeAt(i);
+                }
+            }
+            if (!isCurrent())
+                throw new Error("stale generation");
+            return URL.createObjectURL(new Blob([bytes], { type: mime }));
+        }
+    };
+    const fetchAsObjectUrl = async (url, token) => {
+        if (!url || typeof url !== "string")
+            throw new Error("missing media url");
+        if (url.startsWith("blob:"))
+            return url;
+        if (url.startsWith("data:"))
+            return dataUrlToObjectUrl(url);
+        const headers = {};
+        if (token)
+            headers["X-BeautiCode-Media-Token"] = token;
+        const res = await fetch(url, {
+            method: "GET",
+            headers,
+            mode: "cors",
+            credentials: "omit",
+            cache: "no-store",
+        });
+        if (!res.ok)
+            throw new Error("media fetch failed: " + res.status);
+        const blob = await res.blob();
+        if (!isCurrent())
+            throw new Error("stale generation");
+        return URL.createObjectURL(blob);
+    };
+    return { revoke, dataUrlToObjectUrl, fetchAsObjectUrl, toChineseMediaError };
+})
diff --git a/packages/adapter-codex/src/renderer/runtime-video-element.js b/packages/adapter-codex/src/renderer/runtime-video-element.js
new file mode 100644
index 0000000..43477d3
--- /dev/null
+++ b/packages/adapter-codex/src/renderer/runtime-video-element.js
@@ -0,0 +1,148 @@
+/* Private state belongs to this module; callers receive operations and read-only views. */
+(({ stage, getHandoff, isCurrent, isDocHidden, lifecycle, controls, revoke }) => {
+    const handoff = getHandoff();
+    // Keep at most one handed-off previous video; purge every other child
+    // except the poster img we manage separately. Two playable nodes
+    // alternate frames and posters (Dream Skin 7a3b2ec).
+    const keepVideo = handoff?.video && handoff.video.parentElement === stage
+        ? handoff.video
+        : null;
+    for (const child of [...(stage.children || [])]) {
+        if (child === keepVideo)
+            continue;
+        if (child.tagName === "IMG")
+            continue;
+        const staleSrc = typeof child.src === "string" ? child.src : "";
+        try {
+            child.pause?.();
+        }
+        catch (_) { }
+        try {
+            child.removeAttribute?.("src");
+            child.removeAttribute?.("poster");
+            child.load?.();
+        }
+        catch (_) { }
+        try {
+            child.remove?.();
+        }
+        catch (_) { }
+        if (staleSrc.startsWith("blob:"))
+            revoke(staleSrc);
+    }
+    const video = document.createElement("video");
+    // Create muted for autoplay policy; applyMuteState() runs after play paths.
+    video.setAttribute("muted", "");
+    video.setAttribute("autoplay", "");
+    video.setAttribute("loop", "");
+    video.setAttribute("playsinline", "");
+    video.setAttribute("aria-hidden", "true");
+    video.muted = true;
+    video.defaultMuted = true;
+    video.autoplay = true;
+    video.loop = true;
+    video.playsInline = true;
+    video.preload = "auto";
+    // Pending replacement stays opacity 0; CSS + handoff keep prior frame.
+    // data-bc-media="video" stays set during handoff — inline opacity blocks
+    // the CSS rule from exposing this node (or its poster) early.
+    video.style.opacity = "0";
+    // Do NOT set video.poster when a separate <img> poster is on the stage.
+    // Dual posters are the classic image/video alternate flash. The img covers
+    // the gap; markReady strips any residual poster attr anyway.
+    const onReady = () => {
+        if (!isCurrent())
+            return;
+        lifecycle.markReady();
+    };
+    const onError = (ev) => {
+        // Detached / superseded videos must never fail the newer generation.
+        if (!isCurrent())
+            return;
+        const err = ev?.error || video.error || null;
+        if (lifecycle.isTransientVideoError(err, video) && lifecycle.retryTransientVideo()) {
+            return;
+        }
+        // If handoff still covers, stay pending rather than hard-fail to image.
+        if (getHandoff()?.ready) {
+            lifecycle.setPending(true);
+            lifecycle.retryTransientVideo();
+            return;
+        }
+        lifecycle.markFailed(err);
+    };
+    const onStalled = () => {
+        if (!isCurrent() || lifecycle.failed)
+            return;
+        lifecycle.setPending(true);
+        lifecycle.retryTransientVideo();
+    };
+    const onAbort = () => {
+        if (!isCurrent() || lifecycle.failed)
+            return;
+        // Abort during source swap is normal — never hard-fail.
+        lifecycle.setPending(true);
+        lifecycle.retryTransientVideo();
+    };
+    const onEmptied = () => {
+        if (!isCurrent() || lifecycle.failed || !video.src)
+            return;
+        lifecycle.setPending(true);
+        lifecycle.retryTransientVideo();
+    };
+    const onEnded = () => {
+        if (!isCurrent() || lifecycle.failed || isDocHidden())
+            return;
+        try {
+            video.currentTime = 0;
+        }
+        catch (_) { }
+        Promise.resolve(video.play?.())
+            .then(() => {
+            if (isCurrent()) {
+                lifecycle.setPending(false);
+                if (!lifecycle.ready)
+                    lifecycle.markReady();
+            }
+        })
+            .catch(() => {
+            lifecycle.setPending(true);
+            lifecycle.retryTransientVideo();
+        });
+    };
+    const onTimeUpdate = () => {
+        if (!isCurrent() || lifecycle.failed)
+            return;
+        lifecycle.progress(Number(video.currentTime));
+    };
+    const onLoadedMetadata = () => {
+        if (!isCurrent() || lifecycle.failed)
+            return;
+        try {
+            controls.applyPendingStartAt(video);
+        }
+        catch (_) { }
+    };
+    const handlers = {
+        loadeddata: onReady,
+        canplay: onReady,
+        playing: onReady,
+        loadedmetadata: onLoadedMetadata,
+        error: onError,
+        stalled: onStalled,
+        abort: onAbort,
+        emptied: onEmptied,
+        ended: onEnded,
+        timeupdate: onTimeUpdate,
+    };
+    for (const [evt, fn] of Object.entries(handlers)) {
+        video.addEventListener(evt, fn);
+    }
+    document.addEventListener("visibilitychange", lifecycle.onVisibility);
+    stage.appendChild(video);
+    return { video, dispose() {
+            for (const [event, handler] of Object.entries(handlers))
+                video.removeEventListener(event, handler);
+            document.removeEventListener("visibilitychange", lifecycle.onVisibility);
+        } };
+})
diff --git a/packages/adapter-codex/src/renderer/runtime-video-lifecycle.js b/packages/adapter-codex/src/renderer/runtime-video-lifecycle.js
new file mode 100644
index 0000000..b1a8b8b
--- /dev/null
+++ b/packages/adapter-codex/src/renderer/runtime-video-lifecycle.js
@@ -0,0 +1,197 @@
+/* Private state belongs to this module; callers receive operations and read-only views. */
+(({ isCurrent, isDocHidden, getVideo, hasHandoff, onChange, onReady, controls, toChineseMediaError }) => {
+    let videoReady = false, videoFailed = false, videoError = null, pendingPlay = false, retryTimer = null, retryCount = 0, lastPlaybackTime = -1;
+    const MAX_RETRY = 20;
+    const clearRetry = () => {
+        if (retryTimer) {
+            try {
+                clearTimeout(retryTimer);
+            }
+            catch (_) { }
+            retryTimer = null;
+        }
+    };
+    const revealVideo = () => {
+        try {
+            if (getVideo()) {
+                getVideo().style.opacity = "";
+                getVideo().removeAttribute("poster");
+            }
+        }
+        catch (_) { }
+    };
+    const markReady = () => {
+        if (!isCurrent() || videoFailed)
+            return;
+        // A second blob attach can set inline opacity:0 after the first ready
+        // signal. Always reveal; otherwise verify passes and the art stays hidden.
+        if (videoReady) {
+            revealVideo();
+            return;
+        }
+        videoReady = true;
+        pendingPlay = false;
+        retryCount = 0;
+        clearRetry();
+        revealVideo();
+        try {
+            if (getVideo())
+                controls.applyPendingStartAt(getVideo());
+        }
+        catch (_) { }
+        try {
+            controls.applyMuteState();
+        }
+        catch (_) { }
+        onChange();
+        onReady();
+    };
+    const markFailed = (error) => {
+        if (!isCurrent() || videoFailed)
+            return;
+        videoFailed = true;
+        videoReady = false;
+        videoError = {
+            name: error?.name || null,
+            message: toChineseMediaError(error),
+            mediaCode: getVideo()?.error?.code ?? null,
+            readyState: getVideo()?.readyState ?? null,
+        };
+        clearRetry();
+        try {
+            if (getVideo())
+                getVideo().style.opacity = "0";
+        }
+        catch (_) { }
+        onChange();
+        // On failure, keep handoff if it was ready so the prior frame stays up;
+        // otherwise fall back to poster image.
+        if (!hasHandoff()) {
+            onReady();
+        }
+    };
+    const isTransientVideoError = (error, video) => {
+        if (isDocHidden()) {
+            const message = String(error?.message || "").toLowerCase();
+            if (error?.name === "AbortError" ||
+                /background media|save power|paused/.test(message)) {
+                return true;
+            }
+            // Chromium can emit an empty media error while the app target is hidden.
+            if (!video?.error && !message)
+                return true;
+            if (!video?.error && /failed to fetch|network|load|media/.test(message)) {
+                return true;
+            }
+        }
+        const code = video?.error?.code ?? null;
+        // MEDIA_ERR_ABORTED (1), MEDIA_ERR_NETWORK (2), empty error object.
+        return code === null || code === 1 || code === 2;
+    };
+    const retryTransientVideo = () => {
+        if (!isCurrent() || videoFailed || !getVideo() || !getVideo().src)
+            return false;
+        if (retryCount >= MAX_RETRY)
+            return false;
+        // Hidden Chromium suspends media — do not burn the finite retry budget.
+        // visibilitychange will resume. Preserving videoReady avoids the
+        // "flash then stick on image" failure mode from session 019fa31c.
+        if (isDocHidden()) {
+            pendingPlay = true;
+            return true;
+        }
+        if (retryTimer)
+            return true;
+        retryCount += 1;
+        pendingPlay = true;
+        retryTimer = setTimeout(() => {
+            retryTimer = null;
+            if (!isCurrent() || videoFailed || !getVideo() || !getVideo().src)
+                return;
+            if (isDocHidden()) {
+                pendingPlay = true;
+                return;
+            }
+            Promise.resolve(getVideo().play?.())
+                .then(() => {
+                if (!isCurrent() || videoFailed)
+                    return;
+                pendingPlay = false;
+                // play() is an alternate ready signal for shells that skip loadeddata.
+                if (getVideo().readyState >= 2 || !getVideo().paused || getVideo().currentTime > 0) {
+                    markReady();
+                }
+            })
+                .catch((err) => {
+                if (!isCurrent())
+                    return;
+                if (isTransientVideoError(err, getVideo())) {
+                    retryTransientVideo();
+                    return;
+                }
+                markFailed(err);
+            });
+        }, 500);
+        return true;
+    };
+    const onVisibility = () => {
+        if (!isCurrent() || videoFailed)
+            return;
+        if (isDocHidden())
+            return;
+        if (!getVideo() || !getVideo().src)
+            return;
+        try {
+            // Inline opacity:0 beats the ready CSS rule. Hidden pages often miss
+            // markReady's clear; restoring visibility must drop it or the video
+            // stays invisible while snapshot says ready.
+            getVideo().style.opacity = "";
+        }
+        catch (_) { }
+        Promise.resolve(getVideo().play?.())
+            .then(() => {
+            if (!isCurrent() || videoFailed)
+                return;
+            pendingPlay = false;
+            try {
+                getVideo().style.opacity = "";
+            }
+            catch (_) { }
+            if (videoReady ||
+                getVideo().readyState >= 2 ||
+                !getVideo().paused ||
+                getVideo().currentTime > 0) {
+                if (!videoReady)
+                    markReady();
+                else
+                    onChange();
+            }
+        })
+            .catch((err) => {
+            if (!isCurrent())
+                return;
+            if (isTransientVideoError(err, getVideo()) && retryTransientVideo())
+                return;
+            // Do not fail a previously-ready video on a single resume blip.
+            if (videoReady) {
+                pendingPlay = true;
+                retryTransientVideo();
+                return;
+            }
+            markFailed(err);
+        });
+    };
+    return { markReady, markFailed, isTransientVideoError, retryTransientVideo, onVisibility,
+        setPending(value) { pendingPlay = Boolean(value); },
+        progress(t) {
+            if (Number.isFinite(t) && (t < lastPlaybackTime || t - lastPlaybackTime >= 0.1)) {
+                lastPlaybackTime = t;
+                retryCount = 0;
+                pendingPlay = false;
+                if (!videoReady && (getVideo().readyState >= 2 || t > 0))
+                    markReady();
+            }
+        },
+        reset() { videoReady = false; videoFailed = false; videoError = null; pendingPlay = false; retryCount = 0; lastPlaybackTime = -1; clearRetry(); },
+        dispose: clearRetry, get ready() { return videoReady; }, get failed() { return videoFailed; }, get error() { return videoError; }, get pending() { return pendingPlay; } };
+})
diff --git a/packages/adapter-codex/src/renderer/runtime-video.js b/packages/adapter-codex/src/renderer/runtime-video.js
new file mode 100644
index 0000000..d2eb8e6
--- /dev/null
+++ b/packages/adapter-codex/src/renderer/runtime-video.js
@@ -0,0 +1,313 @@
+/* Private state belongs to this module; callers receive operations and read-only views. */
+(({ isCurrent, isDocHidden, sources, controls, setAttrs, ensureStage, getHandoff, releaseHandoff, videoMode, videoDataUrl, videoSrcRemote, videoToken }) => {
+    const waiter = createMediaWaiter({ isCurrent });
+    const VIDEO_INPUT_ID = "beauticode-video-input";
+    let videoEl = null, videoObjectUrl = null, videoListeners = null;
+    const { revoke, dataUrlToObjectUrl, fetchAsObjectUrl, toChineseMediaError } = sources;
+    const lifecycle = createVideoLifecycle({ isCurrent, isDocHidden, getVideo: () => videoEl,
+        hasHandoff: () => Boolean(getHandoff()?.ready), onChange: setAttrs, onReady: releaseHandoff, controls, toChineseMediaError });
+    const detachVideoListeners = bundle => bundle?.dispose();
+    const createVideoElement = stage => { const bound = createVideoElementBinding({ stage, getHandoff, isCurrent, isDocHidden, lifecycle, controls, revoke }); videoListeners = bound; videoEl = bound.video; return videoEl; };
+    const teardownVideo = (opts) => {
+        lifecycle.dispose();
+        // During handoff, leave the handed-out node alone — new generation owns it.
+        // But ALWAYS detach listeners so the superseded runtime cannot restart it.
+        if (opts && opts.skipElement && videoEl === opts.skipElement) {
+            if (videoListeners && videoListeners.video === opts.skipElement) {
+                detachVideoListeners(videoListeners);
+                videoListeners = null;
+            }
+            videoEl = null;
+            videoObjectUrl = null;
+            return;
+        }
+        if (videoListeners) {
+            detachVideoListeners(videoListeners);
+            videoListeners = null;
+        }
+        if (videoEl) {
+            try {
+                videoEl.pause();
+            }
+            catch (_) { }
+            try {
+                videoEl.removeAttribute("src");
+                videoEl.removeAttribute("poster");
+                videoEl.load();
+            }
+            catch (_) { }
+            try {
+                videoEl.remove();
+            }
+            catch (_) { }
+            videoEl = null;
+        }
+        revoke(videoObjectUrl);
+        videoObjectUrl = null;
+    };
+    const VIDEO_ACCEPT = "video/mp4,video/quicktime,.mp4,.mov";
+    const playbackVideoFile = (file) => {
+        if (!file)
+            return file;
+        const type = String(file.type || "").toLowerCase();
+        const name = String(file.name || "").toLowerCase();
+        if (type === "video/mp4")
+            return file;
+        if (type === "video/quicktime" || name.endsWith(".mov")) {
+            try {
+                return new File([file], file.name, {
+                    type: "video/mp4",
+                    lastModified: file.lastModified,
+                });
+            }
+            catch (_) {
+                return file;
+            }
+        }
+        return file;
+    };
+    const createVideoInput = () => {
+        let input = document.getElementById(VIDEO_INPUT_ID);
+        if (input) {
+            input.accept = VIDEO_ACCEPT;
+            return input;
+        }
+        input = document.createElement("input");
+        input.type = "file";
+        input.id = VIDEO_INPUT_ID;
+        input.accept = VIDEO_ACCEPT;
+        input.tabIndex = -1;
+        input.setAttribute("aria-hidden", "true");
+        Object.assign(input.style, {
+            position: "fixed",
+            width: "1px",
+            height: "1px",
+            opacity: "0",
+            pointerEvents: "none",
+        });
+        (document.body || document.documentElement).appendChild(input);
+        return input;
+    };
+    const playVideoObjectUrl = async (video, objectUrl) => {
+        if (!isCurrent() || lifecycle.failed)
+            return false;
+        if (videoObjectUrl && videoObjectUrl !== objectUrl)
+            revoke(videoObjectUrl);
+        if (objectUrl.startsWith("blob:"))
+            videoObjectUrl = objectUrl;
+        try {
+            // Cold start always muted so autoplay is not blocked; preference applied after.
+            video.muted = true;
+            video.defaultMuted = true;
+            video.setAttribute("muted", "");
+            video.playsInline = true;
+            video.autoplay = true;
+            video.loop = true;
+        }
+        catch (_) { }
+        // Keep replacement hidden until first frame; handoff covers the gap.
+        video.style.opacity = "0";
+        // Do NOT call video.load() after src assign — it aborts and flashes poster.
+        video.src = objectUrl;
+        try {
+            const p = video.play();
+            if (p && typeof p.then === "function") {
+                await p.catch(() => { });
+            }
+        }
+        catch (_) { }
+        // Apply user mute preference after play has a chance to start.
+        try {
+            controls.applyMuteState();
+        }
+        catch (_) { }
+        if (!isCurrent() || lifecycle.failed)
+            return false;
+        if (video.readyState < 2) {
+            await waiter.wait(video, ["loadeddata", "canplay", "playing"], () => video.readyState >= 2);
+            if (!isCurrent() || lifecycle.failed)
+                return false;
+            if (video.paused && video.readyState >= 2) {
+                try {
+                    const p2 = video.play();
+                    if (p2 && typeof p2.then === "function")
+                        await p2.catch(() => { });
+                }
+                catch (_) { }
+            }
+        }
+        if (!isCurrent() || lifecycle.failed)
+            return false;
+        if (video.readyState >= 2 || !video.paused || video.currentTime > 0) {
+            lifecycle.markReady();
+        }
+        else {
+            // Still decoding — keep pending; events / retry will reveal.
+            lifecycle.setPending(true);
+            lifecycle.retryTransientVideo();
+        }
+        return Boolean(video.src);
+    };
+    const doAttachVideoFile = async () => {
+        if (!isCurrent() || lifecycle.failed)
+            return false;
+        const input = document.getElementById(VIDEO_INPUT_ID);
+        const file = input && input.files && input.files[0] ? input.files[0] : null;
+        if (!file)
+            return false;
+        const stage = ensureStage();
+        let video = videoEl;
+        if (!video || !video.isConnected) {
+            video = createVideoElement(stage);
+        }
+        try {
+            const objectUrl = URL.createObjectURL(playbackVideoFile(file));
+            return await playVideoObjectUrl(video, objectUrl);
+        }
+        catch (err) {
+            if (lifecycle.isTransientVideoError(err, videoEl) && lifecycle.retryTransientVideo()) {
+                return false;
+            }
+            if (getHandoff()?.ready) {
+                lifecycle.setPending(true);
+                lifecycle.retryTransientVideo();
+                return false;
+            }
+            lifecycle.markFailed(err);
+            return false;
+        }
+    };
+    const startVideo = async (stage) => {
+        const video = createVideoElement(stage);
+        if (videoMode === "blob") {
+            createVideoInput();
+            // Prefer CDP file-input path. Optional tiny dataUrl is a warm start only.
+            if (videoDataUrl) {
+                try {
+                    let src = videoDataUrl;
+                    if (videoDataUrl.startsWith("data:")) {
+                        src = await dataUrlToObjectUrl(videoDataUrl);
+                        if (!isCurrent()) {
+                            revoke(src);
+                            return;
+                        }
+                        if (src.startsWith("blob:"))
+                            videoObjectUrl = src;
+                    }
+                    video.style.opacity = "0";
+                    video.src = src;
+                    try {
+                        const p = video.play();
+                        if (p && typeof p.then === "function") {
+                            p.then(() => {
+                                if (isCurrent() && (video.readyState >= 2 || !video.paused)) {
+                                    lifecycle.markReady();
+                                }
+                            }).catch(() => { });
+                        }
+                    }
+                    catch (_) { }
+                }
+                catch (_) {
+                    /* CDP attach is the real path */
+                }
+            }
+            // If CDP already stuffed the input (attach raced ahead of apply),
+            // consume it on this generation's <video> instead of leaving an empty shell.
+            const input = document.getElementById(VIDEO_INPUT_ID);
+            if (input && input.files && input.files[0]) {
+                return doAttachVideoFile();
+            }
+            return;
+        }
+        let assigned = false;
+        if (videoDataUrl) {
+            try {
+                let src = videoDataUrl;
+                if (videoDataUrl.startsWith("data:")) {
+                    src = await dataUrlToObjectUrl(videoDataUrl);
+                    if (!isCurrent()) {
+                        revoke(src);
+                        return;
+                    }
+                    if (src.startsWith("blob:"))
+                        videoObjectUrl = src;
+                }
+                video.style.opacity = "0";
+                video.src = src;
+                assigned = true;
+            }
+            catch (_) {
+                assigned = false;
+            }
+        }
+        if (!assigned && videoSrcRemote) {
+            try {
+                const obj = await fetchAsObjectUrl(videoSrcRemote, videoToken);
+                if (!isCurrent()) {
+                    revoke(obj);
+                    return;
+                }
+                if (obj.startsWith("blob:"))
+                    videoObjectUrl = obj;
+                video.style.opacity = "0";
+                video.src = obj;
+                assigned = true;
+            }
+            catch (_) {
+                assigned = false;
+            }
+        }
+        if (!assigned && videoSrcRemote) {
+            try {
+                video.style.opacity = "0";
+                video.src = videoSrcRemote;
+                assigned = true;
+            }
+            catch (_) {
+                assigned = false;
+            }
+        }
+        if (!assigned) {
+            lifecycle.markFailed(new Error("no video source"));
+            return;
+        }
+        try {
+            const p = video.play();
+            if (p && typeof p.then === "function") {
+                p.then(() => {
+                    if (isCurrent() && (video.readyState >= 2 || !video.paused)) {
+                        lifecycle.markReady();
+                    }
+                }).catch((err) => {
+                    if (!isCurrent())
+                        return;
+                    if (lifecycle.isTransientVideoError(err, video) && lifecycle.retryTransientVideo())
+                        return;
+                    // keep pending if handoff covers
+                    if (getHandoff()?.ready) {
+                        lifecycle.setPending(true);
+                        lifecycle.retryTransientVideo();
+                        return;
+                    }
+                });
+            }
+        }
+        catch (_) { }
+    };
+    return { start: startVideo, attach: doAttachVideoFile, createVideoInput, reset: () => lifecycle.reset(),
+        handoff(stage) { const payload = { stage, video: videoEl, objectUrl: videoObjectUrl, ready: lifecycle.ready && !lifecycle.failed }; videoEl = null; videoObjectUrl = null; return payload; },
+        dispose({ handoff = false } = {}) {
+            waiter.dispose();
+            lifecycle.dispose();
+            if (handoff) {
+                detachVideoListeners(videoListeners);
+                videoListeners = null;
+                videoEl = null;
+                videoObjectUrl = null;
+            }
+            else
+                teardownVideo();
+        },
+        get element() { return videoEl; }, get objectUrl() { return videoObjectUrl; }, get ready() { return lifecycle.ready; }, get failed() { return lifecycle.failed; }, get error() { return lifecycle.error; }, get pending() { return lifecycle.pending; }, fail: lifecycle.markFailed };
+})
diff --git a/packages/adapter-codex/src/renderer/runtime-working.js b/packages/adapter-codex/src/renderer/runtime-working.js
new file mode 100644
index 0000000..8716b4f
--- /dev/null
+++ b/packages/adapter-codex/src/renderer/runtime-working.js
@@ -0,0 +1,251 @@
+/* Private state belongs to this module; callers receive operations and read-only views. */
+(({ root, isCurrent, hasBackgroundMedia }) => {
+    // the sidebar). Media stays mounted and keeps playing. Fail open.
+    let working = false;
+    let workObserver = null;
+    let workPollTimer = null;
+    let workRaf = 0;
+    let workDebounceTimer = null;
+    let workRouteHooked = false;
+    const WORK_POLL_MS = 2000;
+    const WORK_DEBOUNCE_MS = 200;
+    const setWorkingAttr = (next) => {
+        working = Boolean(next);
+        if (!hasBackgroundMedia()) {
+            root.removeAttribute("data-bc-working");
+            return;
+        }
+        if (working)
+            root.setAttribute("data-bc-working", "true");
+        else
+            root.removeAttribute("data-bc-working");
+    };
+    const isVisibleEl = (el) => {
+        if (!el || !el.isConnected)
+            return false;
+        try {
+            const r = el.getBoundingClientRect?.();
+            if (r && (r.width < 1 || r.height < 1))
+                return false;
+            const st = typeof window.getComputedStyle === "function"
+                ? window.getComputedStyle(el)
+                : null;
+            if (st &&
+                (st.display === "none" ||
+                    st.visibility === "hidden" ||
+                    Number(st.opacity) === 0)) {
+                return false;
+            }
+        }
+        catch (_) {
+            /* ignore */
+        }
+        return true;
+    };
+    /**
+     * True on the Codex home / empty landing (bright art is welcome).
+     * Uses the same home-icon hook already referenced by background.css.
+     */
+    const isHomeView = () => {
+        try {
+            const home = document.querySelector('[data-testid="home-icon"]');
+            return Boolean(home && isVisibleEl(home));
+        }
+        catch (_) {
+            return false;
+        }
+    };
+    /**
+     * True when a project task / conversation thread is confirmed open —
+     * the only case that should dim. Prefer structural thread / selected-task
+     * signals over header+composer (home and new-task also have those).
+     */
+    const isTaskOrProjectView = () => {
+        try {
+            if (isHomeView())
+                return false;
+            // Thread / message list (Codex desktop task conversation).
+            const thread = document.querySelector([
+                ".thread-scroll-container",
+                "[data-message-author-role]",
+                '[data-testid*="conversation"]',
+                '[data-testid*="thread"]',
+                '[data-testid*="turn"]',
+                "body > #root main [data-message-id]",
+            ].join(", "));
+            if (thread && isVisibleEl(thread))
+                return true;
+            // Sidebar: a selected project task row (not the "无任务" empty label).
+            const selectedTask = document.querySelector([
+                'aside.app-shell-left-panel [aria-current="page"]',
+                "aside.app-shell-left-panel [aria-selected='true']",
+                "aside.app-shell-left-panel button[aria-pressed='true']",
+                "aside.app-shell-left-panel a[aria-current='true']",
+            ].join(", "));
+            if (selectedTask && isVisibleEl(selectedTask)) {
+                const t = (selectedTask.textContent || "").replace(/\s+/g, " ").trim();
+                if (t && !/^(无任务|no tasks?|new task|新建任务)$/i.test(t)) {
+                    return true;
+                }
+            }
+            return false;
+        }
+        catch (_) {
+            return false;
+        }
+    };
+    /**
+     * Dim only inside a confirmed project/task thread.
+     * Home / new-task landing stays bright even if the agent is generating.
+     * Attribute on <html> only.
+     */
+    const detectWorking = () => {
+        try {
+            if (typeof document === "undefined" || !document.body)
+                return false;
+            return isTaskOrProjectView();
+        }
+        catch (_) {
+            // Fail open: never dim on detector errors.
+            return false;
+        }
+    };
+    const refreshWorking = () => {
+        if (!isCurrent())
+            return;
+        const next = detectWorking();
+        if (next !== working) {
+            setWorkingAttr(next);
+        }
+    };
+    const scheduleWorkingRefresh = () => {
+        if (!isCurrent())
+            return;
+        if (workDebounceTimer || workRaf)
+            return;
+        workDebounceTimer = setTimeout(() => {
+            workDebounceTimer = null;
+            try {
+                workRaf = requestAnimationFrame(() => {
+                    workRaf = 0;
+                    refreshWorking();
+                });
+            }
+            catch (_) {
+                workRaf = 0;
+                refreshWorking();
+            }
+        }, WORK_DEBOUNCE_MS);
+    };
+    const onRouteMaybeChanged = () => {
+        scheduleWorkingRefresh();
+    };
+    const stopWorkingWatch = () => {
+        if (workObserver) {
+            try {
+                workObserver.disconnect();
+            }
+            catch (_) { }
+            workObserver = null;
+        }
+        if (workPollTimer) {
+            try {
+                clearInterval(workPollTimer);
+            }
+            catch (_) { }
+            workPollTimer = null;
+        }
+        if (workRaf) {
+            try {
+                cancelAnimationFrame(workRaf);
+            }
+            catch (_) { }
+            workRaf = 0;
+        }
+        if (workDebounceTimer) {
+            try {
+                clearTimeout(workDebounceTimer);
+            }
+            catch (_) { }
+            workDebounceTimer = null;
+        }
+        if (workRouteHooked) {
+            try {
+                window.removeEventListener("popstate", onRouteMaybeChanged);
+                window.removeEventListener("hashchange", onRouteMaybeChanged);
+                window.removeEventListener("focus", onRouteMaybeChanged);
+            }
+            catch (_) { }
+            workRouteHooked = false;
+        }
+        working = false;
+        try {
+            root.removeAttribute("data-bc-working");
+        }
+        catch (_) { }
+    };
+    const startWorkingWatch = () => {
+        if (!isCurrent())
+            return;
+        if (workObserver || workPollTimer) {
+            scheduleWorkingRefresh();
+            return;
+        }
+        try {
+            if (typeof MutationObserver === "function" && document.body) {
+                workObserver = new MutationObserver(() => {
+                    scheduleWorkingRefresh();
+                });
+                workObserver.observe(document.body, {
+                    subtree: true,
+                    childList: true,
+                    attributes: true,
+                    attributeFilter: [
+                        "aria-label",
+                        "aria-busy",
+                        "aria-current",
+                        "aria-selected",
+                        "aria-pressed",
+                        "title",
+                        "data-is-streaming",
+                        "data-streaming",
+                        "data-agent-running",
+                        "data-bc-host-working",
+                        "data-message-author-role",
+                        "data-testid",
+                        "disabled",
+                        "hidden",
+                    ],
+                });
+            }
+        }
+        catch (_) {
+            workObserver = null;
+        }
+        // Poll as a safety net (SPA swaps / closed shadow roots).
+        try {
+            workPollTimer = setInterval(() => {
+                if (!isCurrent())
+                    return;
+                refreshWorking();
+            }, WORK_POLL_MS);
+            workPollTimer.unref?.();
+        }
+        catch (_) {
+            workPollTimer = null;
+        }
+        if (!workRouteHooked) {
+            try {
+                window.addEventListener("popstate", onRouteMaybeChanged);
+                window.addEventListener("hashchange", onRouteMaybeChanged);
+                window.addEventListener("focus", onRouteMaybeChanged);
+                workRouteHooked = true;
+            }
+            catch (_) {
+                workRouteHooked = false;
+            }
+        }
+        refreshWorking();
+    };
+    return { start: startWorkingWatch, stop: stopWorkingWatch, get active() { return working; } };
+})
diff --git a/packages/adapter-codex/test/adapter-session.test.js b/packages/adapter-codex/test/adapter-session.test.js
new file mode 100644
index 0000000..5666887
--- /dev/null
+++ b/packages/adapter-codex/test/adapter-session.test.js
@@ -0,0 +1,239 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import {
+  assessReadiness,
+  browserIdFromVersion,
+  buildInjectionExpression,
+  slimCodexCdpPayload,
+  TINY_PNG_DATA_URL,
+  MAX_CDP_DATA_URL_CHARS,
+  CodexHostApplier,
+  isCandidatePageTarget,
+  MemoryHostApplier,
+  readBoundedJson,
+  runApplyOnce,
+  runWatch,
+  validatedDebuggerUrl,
+  acquireInjectorLock,
+  CdpError,
+  parseRemoteDebuggingFlags,
+  discoverCdpEndpoints,
+  getCodexLaunchGuidance,
+  BeautiSession,
+  DEFAULT_CODEX_CDP_PORT,
+  codexInstallCandidates,
+  pickAvailableCodexPort,
+  ensureCodexCdp,
+} from "../dist/index.js";
+import { startMockCdp } from "./mock-cdp.js";
+import http from "node:http";
+import net from "node:net";
+import {
+  buildCodexLaunchCommand,
+  buildWindowsCodexProcessStartScript,
+  CodexStartupRepairController,
+  classifyCodexStartupProcess,
+  looksLikeCodexMain,
+  parseAppxCodexInstallLocations,
+} from "../dist/launch.js";
+
+test("BeautiSession reapply reconnects after CDP browser identity changes", async () => {
+  const mock = await startMockCdp();
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-restart-"));
+  const png = Buffer.from(
+    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000a49444154789c63000100000500010d0a2db40000000049454e44ae426082",
+    "hex",
+  );
+  const imagePath = path.join(root, "a.png");
+  await fs.writeFile(imagePath, png);
+  const errors = [];
+  const session = new BeautiSession({
+    port: mock.port,
+    dataRoot: path.join(root, "data"),
+    verifyDeadlineMs: 5_000,
+    pollMs: 10_000,
+    autoDiscover: false,
+    deferHostConnect: false,
+    onError: (err) => errors.push(err),
+  });
+  try {
+    await session.start();
+    const applied = await session.apply({ type: "image", imagePath });
+    assert.equal(applied.ok, true, applied.ok ? "" : applied.error);
+
+    mock.rotateBrowserIdentity("test-browser-after-restart");
+    const reapplied = await session.reapply();
+
+    assert.equal(reapplied.ok, true, reapplied.ok ? "" : reapplied.error);
+    assert.equal(session.isHostReady, true);
+    assert.equal(errors.length, 0);
+  } finally {
+    await session.stop();
+    await mock.close();
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("BeautiSession stop drains a deferred startup and releases its lock", async () => {
+  const mock = await startMockCdp();
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-stop-"));
+  const dataRoot = path.join(root, "data");
+  const session = new BeautiSession({
+    port: mock.port,
+    dataRoot,
+    pollMs: 50,
+    deferHostConnect: true,
+    autoDiscover: false,
+  });
+  await session.start();
+  await session.stop();
+  assert.equal(session.isOpen, false);
+  assert.equal(session.isHostReady, false);
+  const release = await acquireInjectorLock(dataRoot, mock.port);
+  await release();
+  await mock.close();
+  await fs.rm(root, { recursive: true, force: true });
+});
+
+test("BeautiSession fish mode requires background and toggles", async () => {
+  const mock = await startMockCdp();
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-fish-"));
+  const png = Buffer.from(
+    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000a49444154789c63000100000500010d0a2db40000000049454e44ae426082",
+    "hex",
+  );
+  const imagePath = path.join(root, "a.png");
+  await fs.writeFile(imagePath, png);
+  const session = new BeautiSession({
+    port: mock.port,
+    dataRoot: path.join(root, "data"),
+    verifyDeadlineMs: 5_000,
+    pollMs: 200,
+    autoDiscover: false,
+    deferHostConnect: false,
+  });
+  try {
+    await session.start();
+    // Refuse without background.
+    const denied = await session.setFishMode(true);
+    assert.equal(denied.ok, false);
+    assert.equal(denied.fish, false);
+    assert.match(String(denied.error || ""), /No active background/i);
+
+    const applied = await session.apply({ type: "image", imagePath });
+    assert.equal(applied.ok, true, applied.ok ? "" : applied.error);
+
+    const on = await session.setFishMode(true);
+    assert.equal(on.ok, true, on.ok ? "" : on.error);
+    assert.equal(on.fish, true);
+    assert.equal(session.isFishMode, true);
+    const stOn = await session.status();
+    assert.equal(stOn.fish, true);
+
+    const off = await session.setFishMode(false);
+    assert.equal(off.ok, true, off.ok ? "" : off.error);
+    assert.equal(off.fish, false);
+    assert.equal(session.isFishMode, false);
+
+    // Re-enter then clear must drop fish.
+    const on2 = await session.setFishMode(true);
+    assert.equal(on2.ok, true, on2.ok ? "" : on2.error);
+    const cleared = await session.apply({ type: "clear" });
+    assert.equal(cleared.ok, true, cleared.ok ? "" : cleared.error);
+    assert.equal(session.isFishMode, false);
+    const stClear = await session.status();
+    assert.equal(stClear.fish, false);
+  } finally {
+    await session.stop();
+    await mock.close();
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("BeautiSession video mute defaults on and toggles without rebuild", async () => {
+  const mock = await startMockCdp();
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-mute-"));
+  const png = Buffer.from(
+    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000a49444154789c63000100000500010d0a2db40000000049454e44ae426082",
+    "hex",
+  );
+  const imagePath = path.join(root, "a.png");
+  await fs.writeFile(imagePath, png);
+  const session = new BeautiSession({
+    port: mock.port,
+    dataRoot: path.join(root, "data"),
+    verifyDeadlineMs: 5_000,
+    pollMs: 200,
+    autoDiscover: false,
+    deferHostConnect: false,
+  });
+  try {
+    await session.start();
+    assert.equal(session.isVideoMuted, true);
+    const st0 = await session.status();
+    assert.equal(st0.muted, true);
+
+    // Preference can be set before media exists.
+    const open = await session.setMuted(false);
+    assert.equal(open.ok, true, open.ok ? "" : open.error);
+    assert.equal(open.muted, false);
+    assert.equal(session.isVideoMuted, false);
+
+    const applied = await session.apply({ type: "image", imagePath });
+    assert.equal(applied.ok, true, applied.ok ? "" : applied.error);
+    // Preference survives apply.
+    assert.equal(session.isVideoMuted, false);
+
+    const silent = await session.setMuted(true);
+    assert.equal(silent.ok, true, silent.ok ? "" : silent.error);
+    assert.equal(silent.muted, true);
+    assert.equal(session.isVideoMuted, true);
+    const st1 = await session.status();
+    assert.equal(st1.muted, true);
+  } finally {
+    await session.stop();
+    await mock.close();
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("BeautiSession background tone changes CSS only and survives publish", async () => {
+  const mock = await startMockCdp();
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-tone-"));
+  const png = Buffer.from(
+    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000a49444154789c63000100000500010d0a2db40000000049454e44ae426082",
+    "hex",
+  );
+  const imagePath = path.join(root, "a.png");
+  await fs.writeFile(imagePath, png);
+  const session = new BeautiSession({
+    port: mock.port,
+    dataRoot: path.join(root, "data"),
+    verifyDeadlineMs: 5_000,
+    pollMs: 200,
+    autoDiscover: false,
+    deferHostConnect: false,
+  });
+  try {
+    await session.start();
+    const applied = await session.apply({ type: "image", imagePath });
+    assert.equal(applied.ok, true, applied.ok ? "" : applied.error);
+    const generation = applied.generation;
+
+    const light = await session.setBackgroundTone("light");
+    assert.equal(light.ok, true, light.ok ? "" : light.error);
+    assert.equal(light.tone, "light");
+    const auto = await session.setBackgroundTone("auto");
+    assert.equal(auto.ok, true, auto.ok ? "" : auto.error);
+    const status = await session.status();
+    assert.equal(status.tone, "auto");
+    assert.equal(status.manifest.generation, generation);
+  } finally {
+    await session.stop();
+    await mock.close();
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
diff --git a/packages/adapter-codex/test/adapter-startup.test.js b/packages/adapter-codex/test/adapter-startup.test.js
new file mode 100644
index 0000000..3fd57f4
--- /dev/null
+++ b/packages/adapter-codex/test/adapter-startup.test.js
@@ -0,0 +1,455 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import {
+  assessReadiness,
+  browserIdFromVersion,
+  buildInjectionExpression,
+  slimCodexCdpPayload,
+  TINY_PNG_DATA_URL,
+  MAX_CDP_DATA_URL_CHARS,
+  CodexHostApplier,
+  isCandidatePageTarget,
+  MemoryHostApplier,
+  readBoundedJson,
+  runApplyOnce,
+  runWatch,
+  validatedDebuggerUrl,
+  acquireInjectorLock,
+  CdpError,
+  parseRemoteDebuggingFlags,
+  discoverCdpEndpoints,
+  getCodexLaunchGuidance,
+  BeautiSession,
+  DEFAULT_CODEX_CDP_PORT,
+  codexInstallCandidates,
+  pickAvailableCodexPort,
+  ensureCodexCdp,
+} from "../dist/index.js";
+import { startMockCdp } from "./mock-cdp.js";
+import http from "node:http";
+import net from "node:net";
+import {
+  buildCodexLaunchCommand,
+  buildWindowsCodexProcessStartScript,
+  CodexStartupRepairController,
+  classifyCodexStartupProcess,
+  looksLikeCodexMain,
+  parseAppxCodexInstallLocations,
+} from "../dist/launch.js";
+
+test("CodexHostApplier verify fails on generation mismatch", async () => {
+  const mock = await startMockCdp();
+  const host = new CodexHostApplier({
+    port: mock.port,
+    connectDeadlineMs: 5_000,
+    pollMs: 40,
+  });
+  try {
+    await host.connect();
+    await host.apply({
+      generation: 1,
+      media: "image",
+      imageDataUrl:
+        "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
+      imageUrl: null,
+      video: null,
+      cssText: "",
+    });
+    const result = await host.verify(
+      { generation: 99, media: "image" },
+      { deadlineMs: 400 },
+    );
+    assert.equal(result.status, "fail");
+    assert.match(result.reason, /generation mismatch/);
+  } finally {
+    host.close();
+    await mock.close();
+  }
+});
+
+test("CodexHostApplier close interrupts an inconclusive verify", async () => {
+  const mock = await startMockCdp();
+  const host = new CodexHostApplier({
+    port: mock.port,
+    connectDeadlineMs: 5_000,
+    pollMs: 25,
+  });
+  try {
+    await host.connect();
+    const started = Date.now();
+    const verifying = host.verify(
+      { generation: 1, media: "image" },
+      { deadlineMs: 10_000 },
+    );
+    setTimeout(() => host.close(), 50);
+    const result = await verifying;
+    assert.equal(result.status, "fail");
+    assert.match(result.reason, /closed during verification/);
+    assert.ok(Date.now() - started < 1_000);
+  } finally {
+    host.close();
+    await mock.close();
+  }
+});
+
+test("runApplyOnce end-to-end with mock CDP + store", async () => {
+  const mock = await startMockCdp();
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-e2e-"));
+  const png = Buffer.from(
+    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000a49444154789c63000100000500010d0a2db40000000049454e44ae426082",
+    "hex",
+  );
+  const imagePath = path.join(root, "a.png");
+  await fs.writeFile(imagePath, png);
+  try {
+    const result = await runApplyOnce({
+      port: mock.port,
+      dataRoot: path.join(root, "data"),
+      input: { type: "image", imagePath },
+      verifyDeadlineMs: 5_000,
+      requireAppProtocol: true,
+    });
+    assert.equal(result.ok, true, result.ok ? "" : result.error);
+    if (result.ok) {
+      assert.equal(result.mode, "image");
+      assert.ok(result.generation >= 1);
+    }
+  } finally {
+    await mock.close();
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("runWatch uses one session and releases its lock on abort", async () => {
+  const mock = await startMockCdp();
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-watch-"));
+  const dataRoot = path.join(root, "data");
+  const controller = new AbortController();
+  let ticks = 0;
+  try {
+    await runWatch({
+      port: mock.port,
+      dataRoot,
+      pollMs: 25,
+      signal: controller.signal,
+      onTick() {
+        ticks += 1;
+        controller.abort();
+      },
+    });
+    assert.ok(ticks >= 1);
+    const release = await acquireInjectorLock(dataRoot, mock.port);
+    await release();
+  } finally {
+    controller.abort();
+    await mock.close();
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("acquireInjectorLock prevents dueling injectors", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-lock-"));
+  const release = await acquireInjectorLock(root, 9335);
+  try {
+    await assert.rejects(() => acquireInjectorLock(root, 9335), CdpError);
+  } finally {
+    await release();
+  }
+
+  // A live pre-nonce lock from an older version must also block takeover.
+  const lockFile = path.join(root, "injector.lock");
+  await fs.writeFile(
+    lockFile,
+    JSON.stringify({
+      pid: process.pid,
+      port: 9335,
+      startedAt: new Date().toISOString(),
+    }),
+  );
+  await assert.rejects(() => acquireInjectorLock(root, 9335), CdpError);
+  await fs.rm(lockFile, { force: true });
+
+  // Fresh lock after release works
+  const release2 = await acquireInjectorLock(root, 9335);
+  await release2();
+  await fs.rm(root, { recursive: true, force: true });
+});
+
+test("parseRemoteDebuggingFlags treats omitted address as a loopback-probe candidate", () => {
+  const ok = parseRemoteDebuggingFlags(
+    `"ChatGPT.exe" --remote-debugging-address=127.0.0.1 --remote-debugging-port=9335`,
+  );
+  assert.equal(ok.safe, true);
+  assert.equal(ok.port, 9335);
+  assert.equal(ok.address, "127.0.0.1");
+
+  const bad = parseRemoteDebuggingFlags(
+    `app --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222`,
+  );
+  assert.equal(bad.safe, false);
+  assert.equal(bad.port, 9222);
+
+  const badQuoted = parseRemoteDebuggingFlags(
+    `app --remote-debugging-address="0.0.0.0" --remote-debugging-port="9222"`,
+  );
+  assert.equal(badQuoted.safe, false);
+  assert.equal(badQuoted.port, 9222);
+
+  const missing = parseRemoteDebuggingFlags("no flags here");
+  assert.equal(missing.port, null);
+  assert.equal(missing.safe, false);
+
+  const missingAddress = parseRemoteDebuggingFlags(
+    `app --remote-debugging-port=9335`,
+  );
+  assert.equal(missingAddress.port, 9335);
+  assert.equal(missingAddress.safe, true);
+});
+
+test("discoverCdpEndpoints finds mock loopback CDP", async () => {
+  const mock = await startMockCdp();
+  try {
+    const hits = await discoverCdpEndpoints({
+      ports: [mock.port],
+      scanProcesses: false,
+      requirePages: true,
+    });
+    assert.equal(hits.length, 1);
+    assert.equal(hits[0].port, mock.port);
+    assert.ok(hits[0].primaryPages >= 1);
+  } finally {
+    await mock.close();
+  }
+});
+
+test("Codex auto-launch does not mistake WorkBuddy CDP for Codex", async () => {
+  const mock = await startMockCdp({
+    title: "WorkBuddy",
+    pageUrl: "file:///C:/Programs/WorkBuddy/resources/app.asar/renderer/index.html",
+  });
+  try {
+    await assert.rejects(
+      () =>
+        ensureCodexCdp({
+          preferredPort: mock.port,
+          candidatePorts: [mock.port],
+          scanProcesses: false,
+          launch: false,
+          timeoutMs: 500,
+        }),
+      /CDP is missing/,
+    );
+  } finally {
+    await mock.close();
+  }
+});
+
+test("getCodexLaunchGuidance is loopback-only", () => {
+  const g = getCodexLaunchGuidance();
+  assert.ok(g.preferredFlags.every((f) => !/0\.0\.0\.0/.test(f)));
+  assert.ok(g.preferredFlags.some((f) => /127\.0\.0\.1/.test(f)));
+});
+
+test("codex install candidates include the usual Windows locations", () => {
+  const win = codexInstallCandidates(
+    { LOCALAPPDATA: "C:\\Users\\me\\AppData\\Local", ProgramFiles: "C:\\Program Files" },
+    "win32",
+  );
+  assert.ok(win.some((p) => p.endsWith("ChatGPT.exe")));
+  assert.ok(win.some((p) => p.endsWith("Codex.exe")));
+  assert.equal(DEFAULT_CODEX_CDP_PORT, 9335);
+  assert.equal(codexInstallCandidates({}, "darwin").length, 0);
+});
+
+test("Codex CDP launch avoids a preferred port already used by WorkBuddy", async () => {
+  const occupied = net.createServer();
+  await new Promise((resolve, reject) => {
+    occupied.once("error", reject);
+    occupied.listen(0, "127.0.0.1", resolve);
+  });
+  try {
+    const address = occupied.address();
+    assert.ok(address && typeof address === "object");
+    const picked = await pickAvailableCodexPort(address.port, [address.port]);
+    assert.notEqual(picked, address.port);
+    assert.ok(picked > 0 && picked <= 65535);
+  } finally {
+    await new Promise((resolve) => occupied.close(resolve));
+  }
+});
+
+test("Windows Store Codex is launched directly so Chromium receives CDP flags", () => {
+  const executable =
+    "C:\\Program Files\\WindowsApps\\OpenAI.Codex_1.0.0.0_x64__test\\app\\ChatGPT.exe";
+  const command = buildCodexLaunchCommand(9222, executable);
+  assert.equal(command.file, executable);
+  assert.deepEqual(command.args, [
+    "--remote-debugging-address=127.0.0.1",
+    "--remote-debugging-port=9222",
+  ]);
+});
+
+test("Codex process scan filters the app-server helper", () => {
+  assert.equal(
+    looksLikeCodexMain(
+      '"C:\\Program Files\\WindowsApps\\OpenAI.Codex_test\\app\\ChatGPT.exe"',
+      "ChatGPT.exe",
+      "C:\\Program Files\\WindowsApps\\OpenAI.Codex_test\\app\\ChatGPT.exe",
+    ),
+    true,
+  );
+  assert.equal(
+    looksLikeCodexMain(
+      "C:\\Users\\me\\OpenAI\\Codex\\bin\\codex.exe app-server --analytics-default-enabled",
+      "codex.exe",
+      "C:\\Users\\me\\OpenAI\\Codex\\bin\\codex.exe",
+    ),
+    false,
+  );
+});
+
+test("fresh Codex without CDP is repaired immediately only inside the 10s window", () => {
+  const now = 50_000;
+  const blind = {
+    pid: 101,
+    name: "ChatGPT.exe",
+    executablePath: "C:\\Program Files\\WindowsApps\\OpenAI.Codex_test\\app\\ChatGPT.exe",
+    commandLine: '"C:\\Program Files\\WindowsApps\\OpenAI.Codex_test\\app\\ChatGPT.exe"',
+    port: null,
+    createdAtMs: now - 9_999,
+  };
+
+  assert.equal(classifyCodexStartupProcess(blind, now), "repair-now");
+  assert.equal(
+    classifyCodexStartupProcess({ ...blind, createdAtMs: now - 10_000 }, now),
+    "ignore-stale",
+  );
+  assert.equal(
+    classifyCodexStartupProcess(
+      {
+        ...blind,
+        commandLine: `${blind.commandLine} --remote-debugging-port=9222`,
+        port: 9222,
+      },
+      now,
+    ),
+    "wait-for-cdp",
+  );
+});
+
+test("Codex startup repair runs once per process generation without a CDP wait", async () => {
+  const calls = [];
+  const controller = new CodexStartupRepairController({
+    now: () => 20_000,
+    repair: async (process) => {
+      calls.push(process.pid);
+    },
+  });
+  const process = {
+    pid: 202,
+    name: "ChatGPT.exe",
+    executablePath: "C:\\Codex\\ChatGPT.exe",
+    commandLine: '"C:\\Codex\\ChatGPT.exe"',
+    port: null,
+    createdAtMs: 19_500,
+  };
+
+  assert.equal(await controller.observe(process), "repaired");
+  assert.equal(await controller.observe(process), "already-handled");
+  assert.deepEqual(calls, [202]);
+});
+
+test("Codex startup monitor detects new PIDs without privileged WMI events", () => {
+  const source = buildWindowsCodexProcessStartScript(4321);
+  assert.match(source, /Get-Process -Id 4321/);
+  assert.match(source, /Get-Process -Name ChatGPT,Codex/);
+  assert.match(source, /Start-Sleep -Milliseconds 200/);
+  assert.doesNotMatch(source, /Win32_ProcessStartTrace|Register-WmiEvent/);
+  assert.match(source, /CreationDate/);
+  assert.ok(
+    source.indexOf("$seen[$pidValue]=$true") >
+      source.indexOf("if(-not $cmd){continue}"),
+  );
+});
+
+test("BeautiSession defaults to preserving a user-closed Codex host", () => {
+  const session = new BeautiSession({ autoDiscover: false });
+  assert.equal(session.autoLaunchHost, false);
+});
+
+test("Codex watch host has one serialized ensure owner", async () => {
+  const source = await fs.readFile(
+    new URL("../../../integrations/codex-desktop/watch-host.mjs", import.meta.url),
+    "utf8",
+  );
+  assert.doesNotMatch(source, /ensureCodexCdp/);
+  assert.equal((source.match(/setInterval\(/g) ?? []).length, 1);
+  assert.match(source, /startCodexStartupRepairMonitor/);
+  assert.match(source, /repairWindowMs:\s*10_000/);
+  assert.match(source, /autoLaunchHost:\s*false/);
+});
+
+test("Codex AppX install locations are parsed without locale-dependent JSON", () => {
+  assert.deepEqual(
+    parseAppxCodexInstallLocations(
+      "C:\\Program Files\\WindowsApps\\OpenAI.Codex_2.0\r\n\r\nC:\\Program Files\\WindowsApps\\OpenAI.Codex_1.0\r\n",
+    ),
+    [
+      "C:\\Program Files\\WindowsApps\\OpenAI.Codex_2.0",
+      "C:\\Program Files\\WindowsApps\\OpenAI.Codex_1.0",
+    ],
+  );
+});
+
+test("Codex installer starts the immediate watcher outside the host process tree", async () => {
+  const source = await fs.readFile(
+    new URL("../../../integrations/codex-desktop/cli.js", import.meta.url),
+    "utf8",
+  );
+  assert.match(source, /Invoke-CimMethod/);
+  assert.match(source, /Win32_Process/);
+  assert.match(source, /\$ErrorActionPreference\s*=\s*'Stop'/);
+  assert.match(source, /\$null\s+-eq\s+\$result/);
+  assert.match(source, /本次未能立即启动后台监视器/);
+  assert.match(source, /startIndependentWindows\(starter\)/);
+});
+
+test("BeautiSession applies image against mock CDP", async () => {
+  const mock = await startMockCdp();
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-sess-"));
+  const png = Buffer.from(
+    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000a49444154789c63000100000500010d0a2db40000000049454e44ae426082",
+    "hex",
+  );
+  const imagePath = path.join(root, "a.png");
+  await fs.writeFile(imagePath, png);
+  const session = new BeautiSession({
+    port: mock.port,
+    dataRoot: path.join(root, "data"),
+    verifyDeadlineMs: 5_000,
+    pollMs: 200,
+    autoDiscover: false,
+    // CLI/test path: connect host before start() returns.
+    deferHostConnect: false,
+  });
+  try {
+    const started = await session.start();
+    assert.equal(started.port, mock.port);
+    const result = await session.apply({ type: "image", imagePath });
+    assert.equal(result.ok, true, result.ok ? "" : result.error);
+    const st = await session.status();
+    assert.equal(st.manifest.background?.type, "image");
+    const reapplied = await session.reapply();
+    assert.equal(reapplied.ok, true, reapplied.ok ? "" : reapplied.error);
+    assert.equal(mock.state.consoleInstalled, true);
+    const clear = await session.apply({ type: "clear" });
+    assert.equal(clear.ok, true, clear.ok ? "" : clear.error);
+  } finally {
+    await session.stop();
+    await mock.close();
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
diff --git a/packages/adapter-codex/test/adapter.test.js b/packages/adapter-codex/test/adapter.test.js
index 8b87282..a56d371 100644
--- a/packages/adapter-codex/test/adapter.test.js
+++ b/packages/adapter-codex/test/adapter.test.js
@@ -465,747 +465,3 @@ test("CodexHostApplier still injects 背景 console after addBinding already exi
     await mock.close();
   }
 });
-
-test("CodexHostApplier verify fails on generation mismatch", async () => {
-  const mock = await startMockCdp();
-  const host = new CodexHostApplier({
-    port: mock.port,
-    connectDeadlineMs: 5_000,
-    pollMs: 40,
-  });
-  try {
-    await host.connect();
-    await host.apply({
-      generation: 1,
-      media: "image",
-      imageDataUrl:
-        "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
-      imageUrl: null,
-      video: null,
-      cssText: "",
-    });
-    const result = await host.verify(
-      { generation: 99, media: "image" },
-      { deadlineMs: 400 },
-    );
-    assert.equal(result.status, "fail");
-    assert.match(result.reason, /generation mismatch/);
-  } finally {
-    host.close();
-    await mock.close();
-  }
-});
-
-test("CodexHostApplier close interrupts an inconclusive verify", async () => {
-  const mock = await startMockCdp();
-  const host = new CodexHostApplier({
-    port: mock.port,
-    connectDeadlineMs: 5_000,
-    pollMs: 25,
-  });
-  try {
-    await host.connect();
-    const started = Date.now();
-    const verifying = host.verify(
-      { generation: 1, media: "image" },
-      { deadlineMs: 10_000 },
-    );
-    setTimeout(() => host.close(), 50);
-    const result = await verifying;
-    assert.equal(result.status, "fail");
-    assert.match(result.reason, /closed during verification/);
-    assert.ok(Date.now() - started < 1_000);
-  } finally {
-    host.close();
-    await mock.close();
-  }
-});
-
-test("runApplyOnce end-to-end with mock CDP + store", async () => {
-  const mock = await startMockCdp();
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-e2e-"));
-  const png = Buffer.from(
-    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000a49444154789c63000100000500010d0a2db40000000049454e44ae426082",
-    "hex",
-  );
-  const imagePath = path.join(root, "a.png");
-  await fs.writeFile(imagePath, png);
-  try {
-    const result = await runApplyOnce({
-      port: mock.port,
-      dataRoot: path.join(root, "data"),
-      input: { type: "image", imagePath },
-      verifyDeadlineMs: 5_000,
-      requireAppProtocol: true,
-    });
-    assert.equal(result.ok, true, result.ok ? "" : result.error);
-    if (result.ok) {
-      assert.equal(result.mode, "image");
-      assert.ok(result.generation >= 1);
-    }
-  } finally {
-    await mock.close();
-    await fs.rm(root, { recursive: true, force: true });
-  }
-});
-
-test("runWatch uses one session and releases its lock on abort", async () => {
-  const mock = await startMockCdp();
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-watch-"));
-  const dataRoot = path.join(root, "data");
-  const controller = new AbortController();
-  let ticks = 0;
-  try {
-    await runWatch({
-      port: mock.port,
-      dataRoot,
-      pollMs: 25,
-      signal: controller.signal,
-      onTick() {
-        ticks += 1;
-        controller.abort();
-      },
-    });
-    assert.ok(ticks >= 1);
-    const release = await acquireInjectorLock(dataRoot, mock.port);
-    await release();
-  } finally {
-    controller.abort();
-    await mock.close();
-    await fs.rm(root, { recursive: true, force: true });
-  }
-});
-
-test("acquireInjectorLock prevents dueling injectors", async () => {
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-lock-"));
-  const release = await acquireInjectorLock(root, 9335);
-  try {
-    await assert.rejects(() => acquireInjectorLock(root, 9335), CdpError);
-  } finally {
-    await release();
-  }
-
-  // A live pre-nonce lock from an older version must also block takeover.
-  const lockFile = path.join(root, "injector.lock");
-  await fs.writeFile(
-    lockFile,
-    JSON.stringify({
-      pid: process.pid,
-      port: 9335,
-      startedAt: new Date().toISOString(),
-    }),
-  );
-  await assert.rejects(() => acquireInjectorLock(root, 9335), CdpError);
-  await fs.rm(lockFile, { force: true });
-
-  // Fresh lock after release works
-  const release2 = await acquireInjectorLock(root, 9335);
-  await release2();
-  await fs.rm(root, { recursive: true, force: true });
-});
-
-test("parseRemoteDebuggingFlags treats omitted address as a loopback-probe candidate", () => {
-  const ok = parseRemoteDebuggingFlags(
-    `"ChatGPT.exe" --remote-debugging-address=127.0.0.1 --remote-debugging-port=9335`,
-  );
-  assert.equal(ok.safe, true);
-  assert.equal(ok.port, 9335);
-  assert.equal(ok.address, "127.0.0.1");
-
-  const bad = parseRemoteDebuggingFlags(
-    `app --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222`,
-  );
-  assert.equal(bad.safe, false);
-  assert.equal(bad.port, 9222);
-
-  const badQuoted = parseRemoteDebuggingFlags(
-    `app --remote-debugging-address="0.0.0.0" --remote-debugging-port="9222"`,
-  );
-  assert.equal(badQuoted.safe, false);
-  assert.equal(badQuoted.port, 9222);
-
-  const missing = parseRemoteDebuggingFlags("no flags here");
-  assert.equal(missing.port, null);
-  assert.equal(missing.safe, false);
-
-  const missingAddress = parseRemoteDebuggingFlags(
-    `app --remote-debugging-port=9335`,
-  );
-  assert.equal(missingAddress.port, 9335);
-  assert.equal(missingAddress.safe, true);
-});
-
-test("discoverCdpEndpoints finds mock loopback CDP", async () => {
-  const mock = await startMockCdp();
-  try {
-    const hits = await discoverCdpEndpoints({
-      ports: [mock.port],
-      scanProcesses: false,
-      requirePages: true,
-    });
-    assert.equal(hits.length, 1);
-    assert.equal(hits[0].port, mock.port);
-    assert.ok(hits[0].primaryPages >= 1);
-  } finally {
-    await mock.close();
-  }
-});
-
-test("Codex auto-launch does not mistake WorkBuddy CDP for Codex", async () => {
-  const mock = await startMockCdp({
-    title: "WorkBuddy",
-    pageUrl: "file:///C:/Programs/WorkBuddy/resources/app.asar/renderer/index.html",
-  });
-  try {
-    await assert.rejects(
-      () =>
-        ensureCodexCdp({
-          preferredPort: mock.port,
-          candidatePorts: [mock.port],
-          scanProcesses: false,
-          launch: false,
-          timeoutMs: 500,
-        }),
-      /CDP is missing/,
-    );
-  } finally {
-    await mock.close();
-  }
-});
-
-test("getCodexLaunchGuidance is loopback-only", () => {
-  const g = getCodexLaunchGuidance();
-  assert.ok(g.preferredFlags.every((f) => !/0\.0\.0\.0/.test(f)));
-  assert.ok(g.preferredFlags.some((f) => /127\.0\.0\.1/.test(f)));
-});
-
-test("codex install candidates include the usual Windows locations", () => {
-  const win = codexInstallCandidates(
-    { LOCALAPPDATA: "C:\\Users\\me\\AppData\\Local", ProgramFiles: "C:\\Program Files" },
-    "win32",
-  );
-  assert.ok(win.some((p) => p.endsWith("ChatGPT.exe")));
-  assert.ok(win.some((p) => p.endsWith("Codex.exe")));
-  assert.equal(DEFAULT_CODEX_CDP_PORT, 9335);
-  assert.equal(codexInstallCandidates({}, "darwin").length, 0);
-});
-
-test("Codex CDP launch avoids a preferred port already used by WorkBuddy", async () => {
-  const occupied = net.createServer();
-  await new Promise((resolve, reject) => {
-    occupied.once("error", reject);
-    occupied.listen(0, "127.0.0.1", resolve);
-  });
-  try {
-    const address = occupied.address();
-    assert.ok(address && typeof address === "object");
-    const picked = await pickAvailableCodexPort(address.port, [address.port]);
-    assert.notEqual(picked, address.port);
-    assert.ok(picked > 0 && picked <= 65535);
-  } finally {
-    await new Promise((resolve) => occupied.close(resolve));
-  }
-});
-
-test("Windows Store Codex is launched directly so Chromium receives CDP flags", () => {
-  const executable =
-    "C:\\Program Files\\WindowsApps\\OpenAI.Codex_1.0.0.0_x64__test\\app\\ChatGPT.exe";
-  const command = buildCodexLaunchCommand(9222, executable);
-  assert.equal(command.file, executable);
-  assert.deepEqual(command.args, [
-    "--remote-debugging-address=127.0.0.1",
-    "--remote-debugging-port=9222",
-  ]);
-});
-
-test("Codex process scan filters the app-server helper", () => {
-  assert.equal(
-    looksLikeCodexMain(
-      '"C:\\Program Files\\WindowsApps\\OpenAI.Codex_test\\app\\ChatGPT.exe"',
-      "ChatGPT.exe",
-      "C:\\Program Files\\WindowsApps\\OpenAI.Codex_test\\app\\ChatGPT.exe",
-    ),
-    true,
-  );
-  assert.equal(
-    looksLikeCodexMain(
-      "C:\\Users\\me\\OpenAI\\Codex\\bin\\codex.exe app-server --analytics-default-enabled",
-      "codex.exe",
-      "C:\\Users\\me\\OpenAI\\Codex\\bin\\codex.exe",
-    ),
-    false,
-  );
-});
-
-test("fresh Codex without CDP is repaired immediately only inside the 10s window", () => {
-  const now = 50_000;
-  const blind = {
-    pid: 101,
-    name: "ChatGPT.exe",
-    executablePath: "C:\\Program Files\\WindowsApps\\OpenAI.Codex_test\\app\\ChatGPT.exe",
-    commandLine: '"C:\\Program Files\\WindowsApps\\OpenAI.Codex_test\\app\\ChatGPT.exe"',
-    port: null,
-    createdAtMs: now - 9_999,
-  };
-
-  assert.equal(classifyCodexStartupProcess(blind, now), "repair-now");
-  assert.equal(
-    classifyCodexStartupProcess({ ...blind, createdAtMs: now - 10_000 }, now),
-    "ignore-stale",
-  );
-  assert.equal(
-    classifyCodexStartupProcess(
-      {
-        ...blind,
-        commandLine: `${blind.commandLine} --remote-debugging-port=9222`,
-        port: 9222,
-      },
-      now,
-    ),
-    "wait-for-cdp",
-  );
-});
-
-test("Codex startup repair runs once per process generation without a CDP wait", async () => {
-  const calls = [];
-  const controller = new CodexStartupRepairController({
-    now: () => 20_000,
-    repair: async (process) => {
-      calls.push(process.pid);
-    },
-  });
-  const process = {
-    pid: 202,
-    name: "ChatGPT.exe",
-    executablePath: "C:\\Codex\\ChatGPT.exe",
-    commandLine: '"C:\\Codex\\ChatGPT.exe"',
-    port: null,
-    createdAtMs: 19_500,
-  };
-
-  assert.equal(await controller.observe(process), "repaired");
-  assert.equal(await controller.observe(process), "already-handled");
-  assert.deepEqual(calls, [202]);
-});
-
-test("Codex startup monitor detects new PIDs without privileged WMI events", () => {
-  const source = buildWindowsCodexProcessStartScript(4321);
-  assert.match(source, /Get-Process -Id 4321/);
-  assert.match(source, /Get-Process -Name ChatGPT,Codex/);
-  assert.match(source, /Start-Sleep -Milliseconds 200/);
-  assert.doesNotMatch(source, /Win32_ProcessStartTrace|Register-WmiEvent/);
-  assert.match(source, /CreationDate/);
-  assert.ok(
-    source.indexOf("$seen[$pidValue]=$true") >
-      source.indexOf("if(-not $cmd){continue}"),
-  );
-});
-
-test("BeautiSession defaults to preserving a user-closed Codex host", () => {
-  const session = new BeautiSession({ autoDiscover: false });
-  assert.equal(session.autoLaunchHost, false);
-});
-
-test("Codex watch host has one serialized ensure owner", async () => {
-  const source = await fs.readFile(
-    new URL("../../../integrations/codex-desktop/watch-host.mjs", import.meta.url),
-    "utf8",
-  );
-  assert.doesNotMatch(source, /ensureCodexCdp/);
-  assert.equal((source.match(/setInterval\(/g) ?? []).length, 1);
-  assert.match(source, /startCodexStartupRepairMonitor/);
-  assert.match(source, /repairWindowMs:\s*10_000/);
-  assert.match(source, /autoLaunchHost:\s*false/);
-});
-
-test("Codex AppX install locations are parsed without locale-dependent JSON", () => {
-  assert.deepEqual(
-    parseAppxCodexInstallLocations(
-      "C:\\Program Files\\WindowsApps\\OpenAI.Codex_2.0\r\n\r\nC:\\Program Files\\WindowsApps\\OpenAI.Codex_1.0\r\n",
-    ),
-    [
-      "C:\\Program Files\\WindowsApps\\OpenAI.Codex_2.0",
-      "C:\\Program Files\\WindowsApps\\OpenAI.Codex_1.0",
-    ],
-  );
-});
-
-test("Codex installer starts the immediate watcher outside the host process tree", async () => {
-  const source = await fs.readFile(
-    new URL("../../../integrations/codex-desktop/cli.js", import.meta.url),
-    "utf8",
-  );
-  assert.match(source, /Invoke-CimMethod/);
-  assert.match(source, /Win32_Process/);
-  assert.match(source, /\$ErrorActionPreference\s*=\s*'Stop'/);
-  assert.match(source, /\$null\s+-eq\s+\$result/);
-  assert.match(source, /本次未能立即启动后台监视器/);
-  assert.match(source, /startIndependentWindows\(starter\)/);
-});
-
-test("BeautiSession applies image against mock CDP", async () => {
-  const mock = await startMockCdp();
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-sess-"));
-  const png = Buffer.from(
-    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000a49444154789c63000100000500010d0a2db40000000049454e44ae426082",
-    "hex",
-  );
-  const imagePath = path.join(root, "a.png");
-  await fs.writeFile(imagePath, png);
-  const session = new BeautiSession({
-    port: mock.port,
-    dataRoot: path.join(root, "data"),
-    verifyDeadlineMs: 5_000,
-    pollMs: 200,
-    autoDiscover: false,
-    // CLI/test path: connect host before start() returns.
-    deferHostConnect: false,
-  });
-  try {
-    const started = await session.start();
-    assert.equal(started.port, mock.port);
-    const result = await session.apply({ type: "image", imagePath });
-    assert.equal(result.ok, true, result.ok ? "" : result.error);
-    const st = await session.status();
-    assert.equal(st.manifest.background?.type, "image");
-    const reapplied = await session.reapply();
-    assert.equal(reapplied.ok, true, reapplied.ok ? "" : reapplied.error);
-    assert.equal(mock.state.consoleInstalled, true);
-    const clear = await session.apply({ type: "clear" });
-    assert.equal(clear.ok, true, clear.ok ? "" : clear.error);
-  } finally {
-    await session.stop();
-    await mock.close();
-    await fs.rm(root, { recursive: true, force: true });
-  }
-});
-
-test("BeautiSession reapply reconnects after CDP browser identity changes", async () => {
-  const mock = await startMockCdp();
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-restart-"));
-  const png = Buffer.from(
-    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000a49444154789c63000100000500010d0a2db40000000049454e44ae426082",
-    "hex",
-  );
-  const imagePath = path.join(root, "a.png");
-  await fs.writeFile(imagePath, png);
-  const errors = [];
-  const session = new BeautiSession({
-    port: mock.port,
-    dataRoot: path.join(root, "data"),
-    verifyDeadlineMs: 5_000,
-    pollMs: 10_000,
-    autoDiscover: false,
-    deferHostConnect: false,
-    onError: (err) => errors.push(err),
-  });
-  try {
-    await session.start();
-    const applied = await session.apply({ type: "image", imagePath });
-    assert.equal(applied.ok, true, applied.ok ? "" : applied.error);
-
-    mock.rotateBrowserIdentity("test-browser-after-restart");
-    const reapplied = await session.reapply();
-
-    assert.equal(reapplied.ok, true, reapplied.ok ? "" : reapplied.error);
-    assert.equal(session.isHostReady, true);
-    assert.equal(errors.length, 0);
-  } finally {
-    await session.stop();
-    await mock.close();
-    await fs.rm(root, { recursive: true, force: true });
-  }
-});
-
-test("BeautiSession stop drains a deferred startup and releases its lock", async () => {
-  const mock = await startMockCdp();
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-stop-"));
-  const dataRoot = path.join(root, "data");
-  const session = new BeautiSession({
-    port: mock.port,
-    dataRoot,
-    pollMs: 50,
-    deferHostConnect: true,
-    autoDiscover: false,
-  });
-  await session.start();
-  await session.stop();
-  assert.equal(session.isOpen, false);
-  assert.equal(session.isHostReady, false);
-  const release = await acquireInjectorLock(dataRoot, mock.port);
-  await release();
-  await mock.close();
-  await fs.rm(root, { recursive: true, force: true });
-});
-
-test("BeautiSession fish mode requires background and toggles", async () => {
-  const mock = await startMockCdp();
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-fish-"));
-  const png = Buffer.from(
-    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000a49444154789c63000100000500010d0a2db40000000049454e44ae426082",
-    "hex",
-  );
-  const imagePath = path.join(root, "a.png");
-  await fs.writeFile(imagePath, png);
-  const session = new BeautiSession({
-    port: mock.port,
-    dataRoot: path.join(root, "data"),
-    verifyDeadlineMs: 5_000,
-    pollMs: 200,
-    autoDiscover: false,
-    deferHostConnect: false,
-  });
-  try {
-    await session.start();
-    // Refuse without background.
-    const denied = await session.setFishMode(true);
-    assert.equal(denied.ok, false);
-    assert.equal(denied.fish, false);
-    assert.match(String(denied.error || ""), /No active background/i);
-
-    const applied = await session.apply({ type: "image", imagePath });
-    assert.equal(applied.ok, true, applied.ok ? "" : applied.error);
-
-    const on = await session.setFishMode(true);
-    assert.equal(on.ok, true, on.ok ? "" : on.error);
-    assert.equal(on.fish, true);
-    assert.equal(session.isFishMode, true);
-    const stOn = await session.status();
-    assert.equal(stOn.fish, true);
-
-    const off = await session.setFishMode(false);
-    assert.equal(off.ok, true, off.ok ? "" : off.error);
-    assert.equal(off.fish, false);
-    assert.equal(session.isFishMode, false);
-
-    // Re-enter then clear must drop fish.
-    const on2 = await session.setFishMode(true);
-    assert.equal(on2.ok, true, on2.ok ? "" : on2.error);
-    const cleared = await session.apply({ type: "clear" });
-    assert.equal(cleared.ok, true, cleared.ok ? "" : cleared.error);
-    assert.equal(session.isFishMode, false);
-    const stClear = await session.status();
-    assert.equal(stClear.fish, false);
-  } finally {
-    await session.stop();
-    await mock.close();
-    await fs.rm(root, { recursive: true, force: true });
-  }
-});
-
-test("fish mode CSS and runtime expose data-bc-fish helpers", async () => {
-  const { fileURLToPath } = await import("node:url");
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  const css = await fs.readFile(
-    path.join(here, "../src/renderer/background.css"),
-    "utf8",
-  );
-  const runtime = await fs.readFile(
-    path.join(here, "../src/renderer/background-runtime.js"),
-    "utf8",
-  );
-  assert.match(css, /data-bc-fish/);
-  assert.match(css, /filter:\s*none/);
-  assert.match(runtime, /setFishMode/);
-  assert.match(runtime, /isFishMode/);
-  assert.match(runtime, /data-bc-fish/);
-  assert.match(runtime, /setMuted/);
-  assert.match(runtime, /isMuted/);
-  assert.match(runtime, /applyMutePreference/);
-  assert.match(css, /data-bc-tone/);
-  assert.match(css, /prefers-color-scheme: light/);
-  // Codex's main-surface class is CSS-module hashed and changes between builds.
-  assert.match(css, /body > #root main/);
-  assert.match(
-    css,
-    /body > #root main \{\s*position:\s*relative !important;\s*background-color:\s*transparent !important;/,
-  );
-  assert.doesNotMatch(css, /main\.main-surface/);
-  // Current Codex builds use a CSS-module hash for the main viewport's
-  // otherwise opaque top fade; keep the stable component-name fragment.
-  assert.match(css, /\[class\*="_MainContentTopFade_"\]/);
-  assert.match(css, /\[class\*="token-main-surface"\]/);
-  assert.doesNotMatch(css, /--bc-panel:/);
-  assert.doesNotMatch(css, /--bc-working-main/);
-  assert.match(
-    css,
-    /aside\.app-shell-left-panel[\s\S]{0,200}background:\s*transparent !important;/,
-  );
-  // New Codex scopes its 65%-opaque wash on a child, not the aside/nav.
-  assert.match(css, /#app-shell-sidebar \.sidebar-navigation\s*\{[^}]*background-color:\s*transparent !important;/);
-  assert.match(css, /backdrop-filter:\s*none !important;/);
-  assert.doesNotMatch(css, /backdrop-filter:\s*blur\(/);
-  assert.match(css, /data-bc-dim-user/);
-  assert.match(
-    css,
-    /\[data-bc-dim-user="true"\]\[data-bc-active="true"\] #beauticode-bg-stage::after/,
-  );
-  assert.match(css, /\[class\*="MainSurface"\]/);
-  assert.match(
-    css,
-    /\[data-bc-video-ready="true"\][\s\S]{0,80}#beauticode-bg-stage[\s\S]{0,40}video \{[\s\S]{0,40}opacity:\s*1 !important;/,
-  );
-  assert.match(runtime, /if \(videoReady\) \{\s*revealVideo\(\);/);
-  assert.match(
-    runtime,
-    /#beauticode-bg-stage video[\s\S]{0,80}v\.style\.opacity = ""/,
-  );
-  assert.match(runtime, /setBackgroundTone/);
-  assert.match(runtime, /data-bc-tone/);
-  assert.match(runtime, /getPlaybackPosition/);
-  assert.match(runtime, /seekTo/);
-  assert.match(runtime, /startAt/);
-  assert.match(runtime, /pendingStartAt/);
-  assert.match(runtime, /isTaskOrProjectView/);
-  assert.match(runtime, /detectWorking/);
-  // Inject must finish apply() before returning; otherwise CDP blob attach
-  // races the stage rebuild and every video import fails verify.
-  assert.match(runtime, /window\.__BEAUTICODE_BG__ = api;/);
-  assert.match(runtime, /return Promise\.resolve\(\)\s*\.then\(apply\)/);
-  assert.match(runtime, /beauticode-image-input/);
-  assert.match(runtime, /wantImageBlob/);
-  assert.match(runtime, /videoEl\.style\.opacity = ""/);
-  assert.match(runtime, /Promise\.resolve\(videoEl\.play\?\.\(\)\)/);
-  assert.match(runtime, /const imageReady =/);
-  assert.match(runtime, /const mediaReady = videoEnabled/);
-  assert.match(runtime, /waitForImageReady/);
-  assert.match(runtime, /Never make the host transparent while a replacement is still decoding/);
-  assert.doesNotMatch(
-    runtime,
-    /Promise\.resolve\(\)\s*\.then\(apply\)\s*\.catch\([\s\S]{0,240}\)\s*;\s*return \{ installed: true/,
-  );
-  assert.doesNotMatch(runtime, /isAgentBusy/);
-  assert.match(css, /#beauticode-bg-stage::before/);
-  assert.match(
-    css,
-    /#beauticode-bg-stage::before \{[\s\S]*?background:\s*none;[\s\S]*?opacity:\s*0;/,
-  );
-  assert.doesNotMatch(
-    css,
-    /html\[data-bc-active="true"\]\[data-bc-media="video"\]\s+#beauticode-bg-stage::before/,
-  );
-  // Light handling must not hinge on theme.js: CSS also matches the host's own
-  // appearance attribute, because a stale/missing marker left near-black text on
-  // an untreated wallpaper (measured 1.07:1 contrast).
-  assert.match(
-    css,
-    /\[data-bc-resolved-tone="light"\], \[data-theme="light"\], \.light/,
-  );
-  // No :has() fallback: the tone attribute lives on <html> in every observed
-  // Codex build, and document-wide selectors are re-evaluated on each swap.
-  assert.doesNotMatch(css, /:has\(> body\[data-theme="light"\]/);
-  // Light readability rides on the veil, never on a panel plate: a plate on top
-  // of a veil double-dips and hides the wallpaper the user chose, so the reading
-  // surfaces carry no fill rule at all.
-  assert.match(css, /--bc-scrim-val:\s*var\(--bc-dim, 0\.48\)/);
-  assert.doesNotMatch(css, /--bc-reading-min/);
-  assert.doesNotMatch(css, /--bc-surface-alpha-pct/);
-  assert.doesNotMatch(css, /body > #root main,[\s\S]{0,320}background-color: color-mix/);
-  assert.match(css, /--bc-scrim-rgb:\s*255, 255, 255/);
-  assert.match(css, /\[data-composer-body\]/);
-  // beautiCode's own surfaces carry role=dialog too; the reader must not paint
-  // them — by id for already-mounted UI, and by marker for future surfaces.
-  assert.match(css, /:not\(\[data-bc-ui\], \[data-bc-ui\] \*,/);
-  assert.match(css, /#beauticode-gallery, #beauticode-gallery \*/);
-  assert.match(css, /#beauticode-console-pop, #beauticode-console-pop \*/);
-  assert.match(css, /--bc-bg-blur/);
-  // Blur stays behind an opt-in attribute: a blur filter on the full-window
-  // media is a per-frame convolution and must never sit on the default path.
-  assert.match(
-    css,
-    /\[data-bc-blur-user="true"\] #beauticode-bg-stage img[\s\S]{0,240}filter:\s*blur\(var\(--bc-bg-blur\)\)/,
-  );
-  // Blur must not move or resize the media: an inset offset with a width that
-  // cannot follow it shifted the picture and left a bare strip on the right.
-  assert.doesNotMatch(css, /\[data-bc-blur-user="true"\][\s\S]{0,200}inset:\s*-/);
-  assert.doesNotMatch(css, /\[data-bc-blur-user="true"\][\s\S]{0,200}width:\s*calc\(100% \+/);
-  assert.match(css, /--bc-stage-fallback/);
-  // The default media path keeps the plain tone filter.
-  assert.match(css, /border:\s*0;\s*filter:\s*var\(--bc-video-filter\);/);
-  assert.doesNotMatch(css, /rgba\(255,255,255,\.82\)/);
-});
-
-test("BeautiSession video mute defaults on and toggles without rebuild", async () => {
-  const mock = await startMockCdp();
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-mute-"));
-  const png = Buffer.from(
-    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000a49444154789c63000100000500010d0a2db40000000049454e44ae426082",
-    "hex",
-  );
-  const imagePath = path.join(root, "a.png");
-  await fs.writeFile(imagePath, png);
-  const session = new BeautiSession({
-    port: mock.port,
-    dataRoot: path.join(root, "data"),
-    verifyDeadlineMs: 5_000,
-    pollMs: 200,
-    autoDiscover: false,
-    deferHostConnect: false,
-  });
-  try {
-    await session.start();
-    assert.equal(session.isVideoMuted, true);
-    const st0 = await session.status();
-    assert.equal(st0.muted, true);
-
-    // Preference can be set before media exists.
-    const open = await session.setMuted(false);
-    assert.equal(open.ok, true, open.ok ? "" : open.error);
-    assert.equal(open.muted, false);
-    assert.equal(session.isVideoMuted, false);
-
-    const applied = await session.apply({ type: "image", imagePath });
-    assert.equal(applied.ok, true, applied.ok ? "" : applied.error);
-    // Preference survives apply.
-    assert.equal(session.isVideoMuted, false);
-
-    const silent = await session.setMuted(true);
-    assert.equal(silent.ok, true, silent.ok ? "" : silent.error);
-    assert.equal(silent.muted, true);
-    assert.equal(session.isVideoMuted, true);
-    const st1 = await session.status();
-    assert.equal(st1.muted, true);
-  } finally {
-    await session.stop();
-    await mock.close();
-    await fs.rm(root, { recursive: true, force: true });
-  }
-});
-
-test("BeautiSession background tone changes CSS only and survives publish", async () => {
-  const mock = await startMockCdp();
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-tone-"));
-  const png = Buffer.from(
-    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000a49444154789c63000100000500010d0a2db40000000049454e44ae426082",
-    "hex",
-  );
-  const imagePath = path.join(root, "a.png");
-  await fs.writeFile(imagePath, png);
-  const session = new BeautiSession({
-    port: mock.port,
-    dataRoot: path.join(root, "data"),
-    verifyDeadlineMs: 5_000,
-    pollMs: 200,
-    autoDiscover: false,
-    deferHostConnect: false,
-  });
-  try {
-    await session.start();
-    const applied = await session.apply({ type: "image", imagePath });
-    assert.equal(applied.ok, true, applied.ok ? "" : applied.error);
-    const generation = applied.generation;
-
-    const light = await session.setBackgroundTone("light");
-    assert.equal(light.ok, true, light.ok ? "" : light.error);
-    assert.equal(light.tone, "light");
-    const auto = await session.setBackgroundTone("auto");
-    assert.equal(auto.ok, true, auto.ok ? "" : auto.error);
-    const status = await session.status();
-    assert.equal(status.tone, "auto");
-    assert.equal(status.manifest.generation, generation);
-  } finally {
-    await session.stop();
-    await mock.close();
-    await fs.rm(root, { recursive: true, force: true });
-  }
-});
diff --git a/packages/adapter-codex/test/appearance.browser.test.js b/packages/adapter-codex/test/appearance.browser.test.js
new file mode 100644
index 0000000..a78e32f
--- /dev/null
+++ b/packages/adapter-codex/test/appearance.browser.test.js
@@ -0,0 +1,99 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { loadRendererSource, buildInjectionExpression } from '../dist/payload.js';
+
+const runtime = process.env.BEAUTICODE_PLAYWRIGHT_MODULE;
+const browserTest = runtime ? test : test.skip;
+const image = 'data:image/svg+xml,' + encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" width="8" height="8"><rect width="8" height="8" fill="#789"/></svg>');
+
+async function fixture(t, stored = '0.46', tone = 'dark') {
+  const { chromium } = await import(runtime);
+  const browser = await chromium.launch({ channel: 'msedge', headless: true });
+  t.after(() => browser.close());
+  const page = await browser.newPage();
+  await page.route('http://127.0.0.1:19335/**', route => route.fulfill({ body: `<!doctype html><html data-theme="${tone}"><head><style>
+    .bg-surface {background:rgb(24,24,24)} [data-composer-body]{background:#333}
+    .from-surface {background-image:linear-gradient(to top, #181818, transparent)}
+    main{height:600px} .decoration{height:240px}
+  </style></head><body><div id="root"><main>
+    <div class="thread-scroll-container"><div>
+      <div class="pointer-events-none sticky bottom-0">
+        <div id="thread-fade" class="pointer-events-none absolute inset-x-0 from-surface"></div>
+        <div id="nonempty-fade" class="pointer-events-none absolute inset-x-0 from-surface">Content</div>
+      </div>
+      <div id="unpositioned-fade" class="pointer-events-none absolute inset-x-0 from-surface"></div>
+    </div></div>
+    <div class="pointer-events-none sticky bottom-0">
+      <div id="unrelated-fade" class="pointer-events-none absolute inset-x-0 from-surface"></div>
+    </div>
+    <div class="pointer-events-none absolute inset-x-0 bottom-0">
+      <div id="decoration" class="decoration pointer-events-none absolute inset-x-0 bottom-0 bg-surface"></div>
+      <div data-composer-body><textarea aria-label="Draft"></textarea></div>
+    </div><div role="dialog">Dialog</div><div class="bg-surface" id="unrelated">Other surface</div>
+  </main></div></body></html>`, contentType: 'text/html' }));
+  await page.goto('http://127.0.0.1:19335/');
+  await page.evaluate(value => { if(value !== null) localStorage.setItem('beauticode-dim',value); }, stored);
+  const source = await loadRendererSource();
+  await page.evaluate(buildInjectionExpression(source.runtimeIife, { generation: 1, media: 'image', imageDataUrl: image }, source.cssText));
+  return { page, source };
+}
+
+browserTest('saved shadow is restored before the first active background without a console', async t => {
+  const { page } = await fixture(t);
+  assert.equal(await page.locator('#beauticode-bg-stage').evaluate(n => getComputedStyle(n,'::after').backgroundColor), 'rgba(0, 0, 0, 0.46)');
+});
+
+browserTest('host root style replacement cannot desynchronise saved shadow from its setting', async t => {
+  const { page, source } = await fixture(t);
+  await page.addScriptTag({ content: source.consoleSource });
+  await page.evaluate(() => document.documentElement.setAttribute('style','--font-ui-size:14px'));
+  await page.waitForTimeout(30);
+  assert.equal(await page.locator('#beauticode-bg-stage').evaluate(n => getComputedStyle(n,'::after').backgroundColor), 'rgba(0, 0, 0, 0.46)');
+  assert.equal(await page.locator('.bc-dim-value').first().textContent(), '46%');
+});
+
+browserTest('zero, automatic and invalid stored shadow keep their intended appearance', async t => {
+  for (const [stored, tone, expected] of [
+    ['0', 'dark', 'rgba(0, 0, 0, 0)'],
+    [null, 'dark', 'rgba(0, 0, 0, 0)'],
+    ['invalid', 'light', 'rgba(255, 255, 255, 0.48)'],
+    ['0.46', 'light', 'rgba(255, 255, 255, 0.46)'],
+  ]) {
+    const { page, source } = await fixture(t, stored, tone);
+    assert.equal(await page.locator('#beauticode-bg-stage').evaluate(n => getComputedStyle(n,'::after').backgroundColor), expected);
+    await page.addScriptTag({ content: source.consoleSource });
+    const stage = await page.locator('#beauticode-bg-stage').elementHandle();
+    await page.evaluate(() => { BeauticodeBackgroundDim.set(0.7); BeauticodeBackgroundDim.clear(); });
+    await page.waitForTimeout(30);
+    assert.equal(await page.evaluate(() => localStorage.getItem('beauticode-dim')), null);
+    assert.equal(await page.evaluate(() => document.documentElement.style.getPropertyValue('--bc-dim')), '');
+    assert.equal(await stage.evaluate(n => n === document.getElementById('beauticode-bg-stage')), true);
+    await page.close();
+  }
+});
+
+browserTest('new composer decoration is transparent while composer and dialogs stay opaque', async t => {
+  const { page } = await fixture(t);
+  const bg = selector => page.locator(selector).evaluate(n => getComputedStyle(n).backgroundColor);
+  assert.equal(await bg('#decoration'), 'rgba(0, 0, 0, 0)');
+  assert.equal(await bg('[data-composer-body]'), 'rgb(31, 31, 31)');
+  assert.equal(await bg('[role=dialog]'), 'rgb(31, 31, 31)');
+  assert.equal(await bg('#unrelated'), 'rgb(24, 24, 24)');
+  await page.evaluate(() => window.__BEAUTICODE_BG__.dispose());
+  assert.equal(await bg('#decoration'), 'rgb(24, 24, 24)');
+});
+
+browserTest('empty sticky thread fade above the composer clears only while wallpaper is active', async t => {
+  const { page } = await fixture(t);
+  const gradient = selector => page.locator(selector).evaluate(n => getComputedStyle(n).backgroundImage);
+  for (const tone of ['light', 'dark', 'light']) {
+    await page.evaluate(value => document.documentElement.setAttribute('data-theme', value), tone);
+    assert.equal(await gradient('#thread-fade'), 'none');
+    for (const selector of ['#nonempty-fade', '#unpositioned-fade', '#unrelated-fade']) {
+      assert.match(await gradient(selector), /linear-gradient/);
+    }
+    assert.notEqual(await page.locator('[data-composer-body]').evaluate(n => getComputedStyle(n).backgroundColor), 'rgba(0, 0, 0, 0)');
+  }
+  await page.evaluate(() => window.__BEAUTICODE_BG__.dispose());
+  assert.match(await gradient('#thread-fade'), /linear-gradient/);
+});
diff --git a/packages/adapter-codex/test/guest-wallpaper.test.js b/packages/adapter-codex/test/guest-wallpaper.test.js
new file mode 100644
index 0000000..65a2b21
--- /dev/null
+++ b/packages/adapter-codex/test/guest-wallpaper.test.js
@@ -0,0 +1,242 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import vm from "node:vm";
+import test from "node:test";
+const filename = new URL("../src/renderer/guest-wallpaper.js", import.meta.url);
+const source = await fs.readFile(filename, "utf8").catch(e => { if (e.code !== "ENOENT")
+    throw e; return "(() => null)"; });
+const policySource = await fs.readFile(new URL("../src/renderer/guest-policy.js", import.meta.url), "utf8").catch(e => { if (e.code !== "ENOENT")
+    throw e; return "(() => () => null)"; });
+const tick = () => new Promise(r => setImmediate(r));
+function fixture(t, { path = "/library", actual = path, partition = "persist:codex", delay = false, reject = false, timeout = false } = {}) {
+    const installed = new Set(), removed = [], events = new Map(), observers = [], timers = new Set();
+    let resolveInsert, insertions = 0;
+    const w = {
+        isConnected: true,
+        getAttribute: k => ({ src: "about:blank?toUrl=" + encodeURIComponent(path), partition }[k] ?? null),
+        getURL: () => "https://chatgpt.com" + actual,
+        closest: s => s === "main" ? {} : null,
+        addEventListener: (k, fn) => { const a = events.get(k) || new Set(); a.add(fn); events.set(k, a); },
+        removeEventListener: (k, fn) => events.get(k)?.delete(fn),
+        insertCSS: () => { insertions++; return new Promise((resolve, rejectFn) => { resolveInsert = () => { const key = "css-" + insertions; installed.add(key); resolve(key); }; if (reject)
+            rejectFn(Error("private URL?account=SECRET"));
+        else if (!delay)
+            resolveInsert(); }); },
+        removeInsertedCSS: async (key) => { installed.delete(key); removed.push(key); },
+    };
+    let nodes = [w], active = false;
+    const document = { documentElement: { getAttribute: () => active ? "true" : null }, querySelectorAll: () => nodes };
+    const diagnostics = [];
+    const context = { document, window: {}, URL, console: { warn: (_prefix, data) => diagnostics.push(data) },
+        setTimeout(fn, ms) { const timer = setTimeout(() => { timers.delete(timer); fn(); }, ms); timers.add(timer); return timer; },
+        clearTimeout(timer) { timers.delete(timer); clearTimeout(timer); },
+        MutationObserver: class {
+            constructor(fn) { this.fn = fn; this.connected = false; observers.push(this); }
+            observe() { this.connected = true; }
+            disconnect() { this.connected = false; }
+        } };
+    const policy = vm.runInNewContext(policySource, context)();
+    const create = vm.runInNewContext(source, context);
+    const controller = create({ policy, timeoutMs: timeout ? 10 : 3000 });
+    assert.ok(controller, "guest wallpaper controller must be available");
+    t.after(() => controller.dispose());
+    return { controller, w, installed, removed, observers, diagnostics, events, context, policy, create, timers,
+        setNodes: value => { nodes=value; },
+        start: () => { active = true; controller.setActive(true); },
+        finish: () => resolveInsert?.(),
+        count: () => insertions,
+        emit: k => { for (const fn of events.get(k) || [])
+            fn({ isMainFrame: true }); },
+        remove: () => { w.isConnected = false; nodes = []; controller.sync(); },
+    };
+}
+test("inactive and direct-clear do not inject or bind guest events", async (t) => {
+    const f = fixture(t);
+    f.controller.setActive(false);
+    await tick();
+    assert.equal(f.installed.size, 0);
+    assert.equal(f.events.size, 0);
+    assert.equal(f.observers.filter(o => o.connected).length, 0);
+});
+test("100 repeated synchronisations keep one style and one host observer", async (t) => {
+    const f = fixture(t);
+    f.start();
+    await tick();
+    for (let i = 0; i < 100; i++) {
+        f.controller.setActive(true);
+        f.controller.sync();
+    }
+    await tick();
+    assert.equal(f.count(), 1);
+    assert.equal(f.installed.size, 1);
+    assert.equal(f.observers.filter(o => o.connected).length, 1);
+    for (const listeners of f.events.values())
+        assert.equal(listeners.size, 1);
+});
+test("clear restores a previously injected document and unbinds all resources", async (t) => {
+    const f = fixture(t);
+    f.start();
+    await tick();
+    f.controller.setActive(false);
+    await tick();
+    assert.equal(f.installed.size, 0);
+    assert.equal(f.removed.length, 1);
+    assert.equal(f.observers.filter(o => o.connected).length, 0);
+    for (const listeners of f.events.values())
+        assert.equal(listeners.size, 0);
+});
+test("late insertion after clear is removed instead of reviving transparency", async (t) => {
+    const f = fixture(t, { delay: true });
+    f.start();
+    f.controller.setActive(false);
+    f.finish();
+    await tick();
+    assert.equal(f.installed.size, 0);
+});
+test("removed webviews are cleaned from the registered resources", async (t) => {
+    const f = fixture(t);
+    f.start();
+    await tick();
+    f.remove();
+    await tick();
+    assert.equal(f.installed.size, 0);
+    for (const listeners of f.events.values())
+        assert.equal(listeners.size, 0);
+});
+test("destroy is idempotent and late completions remain revocable", async (t) => {
+    const f = fixture(t, { delay: true });
+    f.start();
+    f.controller.dispose();
+    f.controller.dispose();
+    f.finish();
+    await tick();
+    assert.equal(f.installed.size, 0);
+});
+for (const path of ["/", "/checkout/web", "/pricing-plan", "/api/auth/session", "/admin", "/plugins/demo/app/tool", "/unknown"]) {
+    test("unverified or transactional guest remains native: " + path, async (t) => {
+        const f = fixture(t, { path });
+        f.start();
+        await tick();
+        assert.equal(f.count(), 0);
+    });
+}
+test("redirect to another path is not authorised by the intended source", async (t) => {
+    const f = fixture(t, { actual: "/checkout/web" });
+    f.start();
+    await tick();
+    assert.equal(f.count(), 0);
+});
+test("in-page navigation revalidates and removes an old style", async (t) => {
+    const f = fixture(t);
+    f.start();
+    await tick();
+    f.w.getURL = () => "https://chatgpt.com/checkout/web";
+    f.emit("did-navigate-in-page");
+    await tick();
+    assert.equal(f.installed.size, 0);
+});
+test("insertion rejection is observable without leaking URL or account data", async (t) => {
+    const f = fixture(t, { reject: true });
+    f.start();
+    await tick();
+    assert.equal(f.installed.size, 0);
+    assert.ok(f.diagnostics.length);
+    assert.doesNotMatch(JSON.stringify(f.diagnostics), /SECRET|account=/);
+});
+test("timed-out insertion is still revoked when Electron eventually completes", async (t) => {
+    const f = fixture(t, { delay: true, timeout: true });
+    f.start();
+    await new Promise(r => setTimeout(r, 25));
+    f.finish();
+    await tick();
+    assert.equal(f.installed.size, 0);
+    assert.ok(f.diagnostics.length);
+});
+test("new pending content binds readiness without injecting about:blank", async (t) => {
+    const f = fixture(t);
+    f.w.getURL = () => "about:blank";
+    f.start();
+    await tick();
+    assert.equal(f.count(), 0);
+    assert.ok(f.events.get("dom-ready")?.size, "pending allowed content must be observed");
+    f.w.getURL = () => "https://chatgpt.com/library";
+    f.emit("dom-ready");
+    await tick();
+    assert.equal(f.installed.size, 1);
+});
+test("100 complete payload owners reuse the document controller across handoff", async (t) => {
+    const f = fixture(t);
+    const ownerSource = await fs.readFile(new URL("../src/renderer/guest-install.js", import.meta.url), "utf8");
+    const install = vm.runInNewContext(ownerSource, f.context);
+    let owner;
+    for (let i = 0; i < 100; i++) {
+        owner = install({ createController: f.create, policy: f.policy });
+        owner.setActive(true);
+    }
+    await tick();
+    assert.equal(f.count(), 1);
+    assert.equal(f.observers.filter(o => o.connected).length, 1);
+    owner.dispose();
+    await tick();
+    assert.equal(f.installed.size, 0);
+});
+test("sandbox and cross-origin redirects never receive CSS", async (t) => {
+    const f = fixture(t);
+    f.w.getAttribute = k => k === "src" ? "codex-sandbox://example/" : null;
+    f.start();
+    await tick();
+    assert.equal(f.count(), 0);
+    f.controller.setActive(false);
+    f.w.getAttribute = k => k === "src" ? "about:blank?toUrl=%2Flibrary" : null;
+    f.w.getURL = () => "https://chatgpt.com.evil.example/library";
+    f.controller.setActive(true);
+    await tick();
+    assert.equal(f.count(), 0);
+});
+test("navigation during insertion converges without requiring another host refresh", async (t) => {
+    const f = fixture(t, { delay: true });
+    f.start();
+    f.emit("did-start-navigation");
+    f.emit("dom-ready");
+    f.w.insertCSS = async () => { f.installed.add("new-document"); return "new-document"; };
+    f.finish();
+    await tick();
+    await tick();
+    assert.deepEqual([...f.installed], ["new-document"]);
+});
+test("destroy cancels the timeout while retaining late completion cleanup", async (t) => {
+    const f = fixture(t, { delay: true });
+    f.start();
+    assert.equal(f.timers.size, 1);
+    f.controller.dispose();
+    assert.equal(f.timers.size, 0);
+    f.finish();
+    await tick();
+    assert.equal(f.installed.size, 0);
+});
+test("CSS removal failure is diagnosed without exposing page information", async (t) => {
+    const f = fixture(t);
+    f.start();
+    await tick();
+    f.w.removeInsertedCSS = async () => { throw Error("private account=SECRET"); };
+    f.controller.setActive(false);
+    await tick();
+    assert.ok(f.diagnostics.some(d => d.stage === "remove"));
+    assert.doesNotMatch(JSON.stringify(f.diagnostics), /SECRET|account=/);
+});
+test("new and removed webviews synchronise through host mutations without republishing media", async (t) => {
+    const f=fixture(t);f.setNodes([]);f.start();await tick();
+    f.setNodes([f.w]);
+    const node={nodeType:1,tagName:"WEBVIEW"};
+    f.observers[0].fn([{type:"childList",addedNodes:[node],removedNodes:[]}]);
+    await tick();assert.equal(f.installed.size,1);
+    f.setNodes([]);f.w.isConnected=false;
+    f.observers[0].fn([{type:"childList",addedNodes:[],removedNodes:[node]}]);
+    await tick();assert.equal(f.installed.size,0);
+});
+test("late CSS cleanup cannot remove the reactivated document's replacement style", async (t) => {
+    const f=fixture(t,{delay:true});f.start();f.controller.setActive(false);
+    f.w.insertCSS=async()=>{f.installed.add("replacement");return "replacement";};
+    f.controller.setActive(true);await tick();f.finish();await tick();
+    assert.deepEqual([...f.installed],["replacement"]);
+});
diff --git a/packages/adapter-codex/test/image-lifecycle.test.js b/packages/adapter-codex/test/image-lifecycle.test.js
new file mode 100644
index 0000000..5acc6a7
--- /dev/null
+++ b/packages/adapter-codex/test/image-lifecycle.test.js
@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import vm from "node:vm";
+import test from "node:test";
+const waiterSource = await fs.readFile(new URL("../src/renderer/runtime-media-wait.js", import.meta.url), "utf8");
+const source = await fs.readFile(new URL("../src/renderer/runtime-image.js", import.meta.url), "utf8");
+test("disposing a pending image attach cancels readiness and cannot update the next generation", async () => {
+    let current = true, changes = 0, revoked = 0;
+    const timers = new Set(), listeners = new Map(), attributes = new Map();
+    const img = {
+        complete: false, naturalWidth: 0,
+        addEventListener(name, fn) { const a = listeners.get(name) || new Set(); a.add(fn); listeners.set(name, a); },
+        removeEventListener(name, fn) { listeners.get(name)?.delete(fn); },
+        getAttribute: name => attributes.get(name),
+        set src(value) { attributes.set("src", value); },
+    };
+    const context = {
+        document: { getElementById: () => ({ files: [{}] }) },
+        URL: { createObjectURL: () => "blob:synthetic" },
+        setTimeout(fn) { timers.add(fn); return fn; },
+        clearTimeout(fn) { timers.delete(fn); },
+    };
+    context.createMediaWaiter = vm.runInNewContext(waiterSource, context);
+    const create = vm.runInNewContext(source, context);
+    const image = create({ isCurrent: () => current, ensureStage: () => ({ querySelector: () => img }),
+        setAttrs: () => changes++, dataImageUrl: null, remoteImageUrl: null,
+        sources: { revoke() { revoked++; }, fetchAsObjectUrl() { throw Error("unexpected remote media"); } } });
+    const attaching = image.attach();
+    current = false;
+    image.dispose();
+    // Simulate a late native load/timeout even after resources are cancelled.
+    for (const fn of [...listeners.get("load") || []])
+        fn();
+    for (const fn of [...timers])
+        fn();
+    assert.equal(await attaching, false);
+    assert.equal(changes, 0);
+    assert.equal(timers.size, 0);
+    assert.equal(revoked, 1);
+    for (const a of listeners.values())
+        assert.equal(a.size, 0);
+});
diff --git a/packages/adapter-codex/test/packaged-renderer.test.js b/packages/adapter-codex/test/packaged-renderer.test.js
new file mode 100644
index 0000000..431cd4d
--- /dev/null
+++ b/packages/adapter-codex/test/packaged-renderer.test.js
@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import vm from "node:vm";
+import test from "node:test";
+import { stageCodexPlugin } from "../../../scripts/pack-codex-plugin.mjs";
+test("staged Codex payload loads and compiles every private renderer module", async (t) => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "bc-renderer-package-"));
+    t.after(() => fs.rm(root, { recursive: true, force: true }));
+    await stageCodexPlugin(root, { build: false });
+    const { loadRendererSource, buildInjectionExpression } = await import(pathToFileURL(path.join(root, "vendor/adapter-codex/payload.js")).href);
+    const source = await loadRendererSource();
+    assert.doesNotThrow(() => new vm.Script(buildInjectionExpression(source.runtimeIife, {
+        generation: 1, media: "clear", imageDataUrl: null, video: null,
+    }, source.cssText)));
+    assert.equal(source.consoleSource.includes("beauticode-dim"), true);
+    assert.doesNotMatch(source.cssText, /border-radius:\s*0\s*!important/);
+});
diff --git a/packages/adapter-codex/test/renderer-contract.test.js b/packages/adapter-codex/test/renderer-contract.test.js
new file mode 100644
index 0000000..3667360
--- /dev/null
+++ b/packages/adapter-codex/test/renderer-contract.test.js
@@ -0,0 +1,135 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import test from "node:test";
+
+test("fish mode CSS and runtime expose data-bc-fish helpers", async () => {
+  const { fileURLToPath } = await import("node:url");
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const css = await fs.readFile(
+    path.join(here, "../src/renderer/background.css"),
+    "utf8",
+  );
+  const {loadRendererSource}=await import("../dist/payload.js");
+  const {runtimeIife:runtime}=await loadRendererSource();
+  assert.match(css, /data-bc-fish/);
+  assert.match(css, /filter:\s*none/);
+  assert.match(runtime, /setFishMode/);
+  assert.match(runtime, /isFishMode/);
+  assert.match(runtime, /data-bc-fish/);
+  assert.match(runtime, /setMuted/);
+  assert.match(runtime, /isMuted/);
+  assert.match(runtime, /applyMutePreference/);
+  assert.match(css, /data-bc-tone/);
+  assert.match(css, /prefers-color-scheme: light/);
+  // Codex's main-surface class is CSS-module hashed and changes between builds.
+  assert.match(css, /body > #root main/);
+  assert.match(
+    css,
+    /body > #root main \{\s*position:\s*relative !important;\s*background-color:\s*transparent !important;/,
+  );
+  assert.doesNotMatch(css, /main\.main-surface/);
+  // Current Codex builds use a CSS-module hash for the main viewport's
+  // otherwise opaque top fade; keep the stable component-name fragment.
+  assert.match(css, /\[class\*="_MainContentTopFade_"\]/);
+  assert.match(css, /\[class\*="token-main-surface"\]/);
+  assert.doesNotMatch(css, /--bc-panel:/);
+  assert.doesNotMatch(css, /--bc-working-main/);
+  assert.match(
+    css,
+    /aside\.app-shell-left-panel[\s\S]{0,200}background:\s*transparent !important;/,
+  );
+  // New Codex scopes its 65%-opaque wash on a child, not the aside/nav.
+  assert.match(css, /#app-shell-sidebar \.sidebar-navigation\s*\{[^}]*background-color:\s*transparent !important;/);
+  assert.match(css, /backdrop-filter:\s*none !important;/);
+  assert.doesNotMatch(css, /backdrop-filter:\s*blur\(/);
+  assert.match(css, /data-bc-dim-user/);
+  assert.match(
+    css,
+    /\[data-bc-dim-user="true"\]\[data-bc-active="true"\] #beauticode-bg-stage::after/,
+  );
+  assert.match(css, /\[class\*="MainSurface"\]/);
+  assert.match(
+    css,
+    /\[data-bc-video-ready="true"\][\s\S]{0,80}#beauticode-bg-stage[\s\S]{0,40}video \{[\s\S]{0,40}opacity:\s*1 !important;/,
+  );
+  assert.match(runtime, /if \(videoReady\) \{\s*revealVideo\(\);/);
+  assert.match(
+    runtime,
+    /#beauticode-bg-stage video[\s\S]{0,80}v\.style\.opacity = ""/,
+  );
+  assert.match(runtime, /setBackgroundTone/);
+  assert.match(runtime, /data-bc-tone/);
+  assert.match(runtime, /getPlaybackPosition/);
+  assert.match(runtime, /seekTo/);
+  assert.match(runtime, /startAt/);
+  assert.match(runtime, /pendingStartAt/);
+  assert.match(runtime, /isTaskOrProjectView/);
+  assert.match(runtime, /detectWorking/);
+  // Inject must finish apply() before returning; otherwise CDP blob attach
+  // races the stage rebuild and every video import fails verify.
+  assert.match(runtime, /window\.__BEAUTICODE_BG__ = api;/);
+  assert.match(runtime, /return Promise\.resolve\(\)\s*\.then\(apply\)/);
+  assert.match(runtime, /beauticode-image-input/);
+  assert.match(runtime, /wantImageBlob/);
+  assert.match(runtime, /getVideo\(\)\.style\.opacity = ""/);
+  assert.match(runtime, /Promise\.resolve\(getVideo\(\)\.play\?\.\(\)\)/);
+  assert.match(runtime, /const imageReady =/);
+  assert.match(runtime, /const mediaReady = videoEnabled/);
+  assert.match(runtime, /waitForImageReady/);
+  assert.match(runtime, /Never make the host transparent while a replacement is still decoding/);
+  assert.doesNotMatch(
+    runtime,
+    /Promise\.resolve\(\)\s*\.then\(apply\)\s*\.catch\([\s\S]{0,240}\)\s*;\s*return \{ installed: true/,
+  );
+  assert.doesNotMatch(runtime, /isAgentBusy/);
+  assert.match(css, /#beauticode-bg-stage::before/);
+  assert.match(
+    css,
+    /#beauticode-bg-stage::before \{[\s\S]*?background:\s*none;[\s\S]*?opacity:\s*0;/,
+  );
+  assert.doesNotMatch(
+    css,
+    /html\[data-bc-active="true"\]\[data-bc-media="video"\]\s+#beauticode-bg-stage::before/,
+  );
+  // Light handling must not hinge on theme.js: CSS also matches the host's own
+  // appearance attribute, because a stale/missing marker left near-black text on
+  // an untreated wallpaper (measured 1.07:1 contrast).
+  assert.match(
+    css,
+    /\[data-bc-resolved-tone="light"\], \[data-theme="light"\], \.light/,
+  );
+  // No :has() fallback: the tone attribute lives on <html> in every observed
+  // Codex build, and document-wide selectors are re-evaluated on each swap.
+  assert.doesNotMatch(css, /:has\(> body\[data-theme="light"\]/);
+  // Light readability rides on the veil, never on a panel plate: a plate on top
+  // of a veil double-dips and hides the wallpaper the user chose, so the reading
+  // surfaces carry no fill rule at all.
+  assert.match(css, /--bc-scrim-val:\s*var\(--bc-dim, 0\.48\)/);
+  assert.doesNotMatch(css, /--bc-reading-min/);
+  assert.doesNotMatch(css, /--bc-surface-alpha-pct/);
+  assert.doesNotMatch(css, /body > #root main,[\s\S]{0,320}background-color: color-mix/);
+  assert.match(css, /--bc-scrim-rgb:\s*255, 255, 255/);
+  assert.match(css, /\[data-composer-body\]/);
+  // beautiCode's own surfaces carry role=dialog too; the reader must not paint
+  // them — by id for already-mounted UI, and by marker for future surfaces.
+  assert.match(css, /:not\(\[data-bc-ui\], \[data-bc-ui\] \*,/);
+  assert.match(css, /#beauticode-gallery, #beauticode-gallery \*/);
+  assert.match(css, /#beauticode-console-pop, #beauticode-console-pop \*/);
+  assert.match(css, /--bc-bg-blur/);
+  // Blur stays behind an opt-in attribute: a blur filter on the full-window
+  // media is a per-frame convolution and must never sit on the default path.
+  assert.match(
+    css,
+    /\[data-bc-blur-user="true"\] #beauticode-bg-stage img[\s\S]{0,240}filter:\s*blur\(var\(--bc-bg-blur\)\)/,
+  );
+  // Blur must not move or resize the media: an inset offset with a width that
+  // cannot follow it shifted the picture and left a bare strip on the right.
+  assert.doesNotMatch(css, /\[data-bc-blur-user="true"\][\s\S]{0,200}inset:\s*-/);
+  assert.doesNotMatch(css, /\[data-bc-blur-user="true"\][\s\S]{0,200}width:\s*calc\(100% \+/);
+  assert.match(css, /--bc-stage-fallback/);
+  // The default media path keeps the plain tone filter.
+  assert.match(css, /border:\s*0;\s*filter:\s*var\(--bc-video-filter\);/);
+  assert.doesNotMatch(css, /rgba\(255,255,255,\.82\)/);
+});
+
diff --git a/packages/adapter-codex/test/video-lifecycle.test.js b/packages/adapter-codex/test/video-lifecycle.test.js
new file mode 100644
index 0000000..c6a806d
--- /dev/null
+++ b/packages/adapter-codex/test/video-lifecycle.test.js
@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import vm from "node:vm";
+import test from "node:test";
+const read = name => fs.readFile(new URL("../src/renderer/" + name, import.meta.url), "utf8");
+const lifecycleSource = await read("runtime-video-lifecycle.js");
+const elementSource = await read("runtime-video-element.js");
+const controlsSource = await read("runtime-controls.js");
+test("media replacement preserves the tone through the existing public accessor", () => {
+    const create = vm.runInNewContext(controlsSource, {});
+    const controls = create({
+        root: {getAttribute:()=>null},
+        previous: {isBackgroundTone:()=>"light",isMuted:()=>false,isFishMode:()=>true},
+        normalizedVideo:null,isCurrent:()=>true,hasBackgroundMedia:()=>true,
+        getStage:()=>null,getVideo:()=>null,setAttrs(){},
+    });
+    assert.equal(controls.tone,"light");
+    assert.equal(controls.muted,false);
+    assert.equal(controls.fish,true);
+});
+test("a permanent decode error after handoff completes cannot stay pending forever", () => {
+    let handoff = { ready: true }, video;
+    class Video extends EventTarget {
+        constructor() { super(); this.style = {}; this.src = "blob:synthetic"; this.currentTime = 0; }
+        setAttribute() { }
+        removeAttribute() { }
+    }
+    const context = { document: { createElement: () => new Video(), addEventListener() { }, removeEventListener() { } }, setTimeout, clearTimeout };
+    const controls = { applyPendingStartAt() { }, applyMuteState() { } };
+    const lifecycle = vm.runInNewContext(lifecycleSource, context)({
+        isCurrent: () => true, isDocHidden: () => false, getVideo: () => video,
+        hasHandoff: () => Boolean(handoff?.ready), onChange() { }, onReady() { handoff = null; },
+        controls, toChineseMediaError: () => "decode failure",
+    });
+    const bind = vm.runInNewContext(elementSource, context);
+    const stage = { children: [], appendChild(v) { video = v; } };
+    const binding = bind({ stage, handoff, getHandoff: () => handoff, isCurrent: () => true,
+        isDocHidden: () => false, lifecycle, controls, revoke() { } });
+    lifecycle.markReady();
+    video.error = { code: 3 };
+    video.dispatchEvent(new Event("error"));
+    assert.equal(lifecycle.failed, true);
+    assert.equal(lifecycle.error.message, "decode failure");
+    lifecycle.dispose();
+    binding.dispose();
+});
diff --git a/packages/adapter-codex/test/wallpaper-css.test.js b/packages/adapter-codex/test/wallpaper-css.test.js
new file mode 100644
index 0000000..74213d5
--- /dev/null
+++ b/packages/adapter-codex/test/wallpaper-css.test.js
@@ -0,0 +1,17 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import test from "node:test";
+const css = await fs.readFile(new URL("../src/renderer/background.css", import.meta.url), "utf8");
+test("wallpaper preserves the host sidebar, main and hero corner radii", () => {
+    assert.doesNotMatch(css, /border-radius:\s*0\s*!important/);
+});
+test("ordinary tooltips and popper positioning wrappers are not painted as panels", () => {
+    const panels = css.slice(css.indexOf("/* Functional panels"), css.indexOf("background-color: var(--bc-readable-fill)", css.indexOf("/* Functional panels")));
+    assert.doesNotMatch(panels, /role="tooltip"|data-radix-popper-content-wrapper/);
+});
+test("overlay protection follows the host palette and excludes owned UI", () => {
+    assert.match(css, /data-overlay-owner/);
+    assert.doesNotMatch(css, /rgba\(25[035],\s*25[0259],\s*25[345],\s*0\.9/);
+    assert.doesNotMatch(css, /main aside\s*\{/);
+    assert.doesNotMatch(css, /_ComposerLayoutRoot_|empty-state-pag|class\*="_shell_"/);
+});
diff --git a/packages/adapter-codex/test/wallpaper.browser.test.js b/packages/adapter-codex/test/wallpaper.browser.test.js
new file mode 100644
index 0000000..34011c0
--- /dev/null
+++ b/packages/adapter-codex/test/wallpaper.browser.test.js
@@ -0,0 +1,168 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import test from "node:test";
+const { loadRendererSource, buildInjectionExpression } = await import(process.env.BEAUTICODE_RENDERER_PAYLOAD || "../dist/payload.js");
+const modulePath = process.env.BEAUTICODE_PLAYWRIGHT_MODULE;
+const browserTest = modulePath ? test : test.skip;
+const image = "data:image/svg+xml," + encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20"><path fill="#936" d="M0 0h20v20H0z"/><path fill="#69c" d="M0 0h10v10H0z"/></svg>');
+async function fixture(t) {
+    const { chromium } = await import(modulePath);
+    const browser = await chromium.launch({ channel: "msedge", headless: true });
+    t.after(() => browser.close());
+    const page = await browser.newPage({ viewport: { width: 1000, height: 720 } });
+    await page.goto("about:blank");
+    await page.setContent(`<html data-theme="dark"><head><style>
+    body{margin:0;color:#eee}html[data-theme=light] body{color:#202124}
+    #root{display:flex;height:720px}aside.app-shell-left-panel{width:230px;border-radius:24px;background:#333}
+    main{flex:1;border-radius:22px;background:#333;padding:20px}.hero{border-radius:18px}
+    .bg-surface{background:white} [role=menu]{padding:20px;border-radius:16px}
+    [data-overlay-owner]{position:fixed;top:100px;left:300px;width:250px;height:100px}
+    [role=tooltip]{background:#282033;color:#fff;border-radius:8px;padding:10px}
+    #tip{position:fixed;top:300px;left:300px}
+    #peek{border-radius:14px;top:450px;height:100px;padding:0}
+    #peek>div{height:100px;background:white;border-radius:0}
+    #unrelated{background:rgb(98,52,120)}[data-bc-ui]{background:rgb(17,34,51)!important}
+    .native-header::before{content:"";background:rgb(24,24,24)}
+  </style></head><body><div id=root><aside class=app-shell-left-panel>Sidebar</aside><main>
+    <div class=hero>Home</div><aside id=unrelated>Other panel</aside>
+    <div data-composer-body>Composer</div>
+    <div class="flex h-full min-h-0 min-w-0 flex-1 flex-col outline-none"><div class="relative h-full min-h-0"><div class="contents">
+      <div class="h-full min-h-0 flex-1 overflow-y-auto relative"><div class="flex min-h-full w-full flex-col">
+        <div id="library-header" class="native-header border-transparent"><div class="mx-auto w-full"><h1>Library</h1></div></div>
+      </div></div>
+    </div></div></div>
+    <div class="flex h-full min-h-0 min-w-0 flex-1 flex-col outline-none">
+      <div id="route-shell" class="flex h-full min-h-0 flex-col bg-surface"><div class="contents">
+        <div class="h-full min-h-0 flex-1 overflow-y-auto relative"><div class="flex min-h-full w-full flex-col">
+          <div id="route-header" class="native-header border-transparent"><div class="mx-auto w-full"><h1>Sites</h1></div></div>
+        <div id="route-content" class="mx-auto flex min-h-0 w-full flex-1 flex-col bg-surface">
+          <div id="route-panel" role="tabpanel" class="mx-auto flex min-h-full w-full flex-1 flex-col bg-surface">
+            <article id="reading-card" class="bg-surface">Readable card</article>
+          </div>
+        </div>
+        </div></div>
+      </div></div>
+    </div>
+  </main></div><div data-radix-popper-content-wrapper><div role=menu>Menu</div></div>
+  <div data-overlay-owner="test"><div class=bg-surface id=overlay>Overlay</div></div>
+  <div role=tooltip id=tip>Native tooltip</div>
+  <div role=tooltip data-overlay-owner=slate-sidebar id=peek><div class=bg-surface>Preview</div></div>
+  <div data-bc-ui data-overlay-owner=test class=bg-surface id=owned>Skin UI</div>
+  <div data-bc-ui><div data-overlay-owner=test class=bg-surface id=owned-child style="background:rgb(17,34,51)">Owned nested surface</div></div></body></html>`);
+    const source = await loadRendererSource();
+    const inject = payload => page.evaluate(buildInjectionExpression(source.runtimeIife, payload, source.cssText));
+    await inject({ generation: 1, media: "image", imageDataUrl: image });
+    return { page, inject };
+}
+browserTest("real CSS preserves corners and native tooltips across both host themes", async (t) => {
+    const { page } = await fixture(t);
+    const style = (selector, property) => page.locator(selector).evaluate((e, p) => getComputedStyle(e)[p], property);
+    assert.equal(await style("aside.app-shell-left-panel", "borderTopLeftRadius"), "24px");
+    assert.equal(await style("main", "borderTopLeftRadius"), "22px");
+    assert.equal(await style("#peek>div", "borderTopLeftRadius"), "14px");
+    assert.equal(await style("#peek", "overflow"), "hidden");
+    assert.equal(await style("[data-radix-popper-content-wrapper]", "backgroundColor"), "rgba(0, 0, 0, 0)");
+    for (const [theme, color] of [["light", "rgb(255, 255, 255)"], ["dark", "rgb(31, 31, 31)"], ["light", "rgb(255, 255, 255)"]]) {
+        await page.evaluate(theme => document.documentElement.dataset.theme = theme, theme);
+        await page.waitForFunction(color => getComputedStyle(document.querySelector("#overlay")).backgroundColor === color, color);
+        for (const selector of ["#overlay", "#peek", "#peek>div", "[data-composer-body]", "[role=menu]"])
+            assert.equal(await style(selector, "backgroundColor"), color);
+        assert.equal(await style("#tip", "backgroundColor"), "rgb(40, 32, 51)");
+        assert.equal(await style("#tip", "color"), "rgb(255, 255, 255)");
+        assert.equal(await style("#unrelated", "backgroundColor"), "rgb(98, 52, 120)");
+        assert.equal(await style("#owned", "backgroundColor"), "rgb(17, 34, 51)");
+        assert.equal(await style("#owned-child", "backgroundColor"), "rgb(17, 34, 51)");
+        await fs.mkdir(new URL("../../../artifacts/pr96/", import.meta.url), { recursive: true });
+        await page.screenshot({ path: new URL("../../../artifacts/pr96/fixture-" + theme + ".png", import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1") });
+    }
+    await page.evaluate(() => window.__BEAUTICODE_BG__.dispose());
+    assert.equal(await style("#peek>div", "borderTopLeftRadius"), "0px");
+    assert.equal(await style("#peek>div", "backgroundColor"), "rgb(255, 255, 255)");
+});
+browserTest("full payload repeated injection keeps the media and guest owner, then releases both", async (t) => {
+    const { page, inject } = await fixture(t);
+    await page.evaluate(() => { window.initialStage = document.getElementById("beauticode-bg-stage"); window.initialGuest = window.__BEAUTICODE_GUEST__; });
+    for (let i = 0; i < 100; i++)
+        await inject({ generation: 1, media: "image", imageDataUrl: image });
+    assert.equal(await page.evaluate(() => initialStage === document.getElementById("beauticode-bg-stage")), true);
+    assert.equal(await page.evaluate(() => initialGuest === window.__BEAUTICODE_GUEST__), true);
+    assert.equal((await page.evaluate(() => __BEAUTICODE_BG__.snapshot())).imageLoaded, true);
+    await inject({ generation: 2, media: "clear", imageDataUrl: null });
+    assert.equal(await page.locator("#beauticode-bg-stage").count(), 0);
+    await page.evaluate(() => __BEAUTICODE_BG__.dispose());
+    assert.equal(await page.evaluate(() => Boolean(window.__BEAUTICODE_GUEST__)), false);
+});
+browserTest("native content shells clear only route plates while reading cards stay opaque", async (t) => {
+    const { page } = await fixture(t);
+    const bg = selector => page.locator(selector).evaluate(e => getComputedStyle(e).backgroundColor);
+    for (const selector of ["#route-shell", "#route-content", "#route-panel"])
+        assert.equal(await bg(selector), "rgba(0, 0, 0, 0)");
+    assert.equal(await page.locator("#route-header").evaluate(e => getComputedStyle(e, "::before").backgroundColor), "rgba(0, 0, 0, 0)");
+    assert.equal(await page.locator("#library-header").evaluate(e => getComputedStyle(e, "::before").backgroundColor), "rgba(0, 0, 0, 0)");
+    assert.equal(await bg("#reading-card"), "rgb(255, 255, 255)");
+    await page.evaluate(() => __BEAUTICODE_BG__.dispose());
+    for (const selector of ["#route-shell", "#route-content", "#route-panel"])
+        assert.equal(await bg(selector), "rgb(255, 255, 255)");
+});
+browserTest("real video decode, handoff, mute, seek and fish mode survive modularisation", async (t) => {
+    const { page, inject } = await fixture(t);
+    const data = await page.evaluate(async () => {
+        const canvas = document.createElement("canvas");
+        canvas.width = 16;
+        canvas.height = 16;
+        canvas.style.cssText = "position:fixed;top:0;left:0;z-index:2147483647";
+        document.body.append(canvas);
+        const stream = canvas.captureStream(0), recorder = new MediaRecorder(stream, { mimeType: "video/webm" }), parts = [];
+        recorder.ondataavailable = e => parts.push(e.data);
+        const done = new Promise(resolve => recorder.onstop = resolve);
+        recorder.start();
+        const ctx = canvas.getContext("2d");
+        for (let i = 0; i < 8; i++) {
+            ctx.fillStyle = i % 2 ? "#936" : "#69c";
+            ctx.fillRect(0, 0, 16, 16);
+            stream.getVideoTracks()[0].requestFrame();
+            await new Promise(r => setTimeout(r, 100));
+        }
+        recorder.stop();
+        await done;
+        for (const track of stream.getTracks())
+            track.stop();
+        canvas.remove();
+        return await new Promise(resolve => { const reader = new FileReader(); reader.onload = () => resolve(reader.result); reader.readAsDataURL(new Blob(parts, { type: "video/webm" })); });
+    });
+    assert.ok(data.length > 100, "recorder must emit media bytes");
+    const decode = await page.evaluate(async (data) => { const v = document.createElement("video"); v.muted = true; v.src = data; try {
+        await v.play();
+        return { ready: v.readyState, bytes: data.length };
+    }
+    catch (e) {
+        return { error: e.message, media: v.error?.message, bytes: data.length };
+    }
+    finally {
+        v.src = "";
+    } }, data);
+    assert.ok(decode.ready >= 2, JSON.stringify(decode));
+    const payload = { generation: 2, media: "video", imageDataUrl: image, video: { mode: "data", dataUrl: data } };
+    await inject(payload);
+    assert.equal(await page.evaluate(() => __BEAUTICODE_BG__.videoError), null);
+    await page.waitForFunction(() => __BEAUTICODE_BG__.snapshot().videoReady, null, { timeout: 5000 }).catch(async () => {
+        throw new Error(JSON.stringify(await page.evaluate(() => ({ snapshot: __BEAUTICODE_BG__.snapshot(), error: __BEAUTICODE_BG__.videoError, video: [...document.querySelectorAll("video")].map(v => ({ readyState: v.readyState, paused: v.paused, srcLength: v.src.length, error: v.error?.message })) }))));
+    });
+    assert.equal(await page.evaluate(() => __BEAUTICODE_BG__.setMuted(true).muted), true);
+    assert.equal(await page.evaluate(() => __BEAUTICODE_BG__.seekTo(0).ok), true);
+    assert.equal(await page.evaluate(() => __BEAUTICODE_BG__.setFishMode(true)), true);
+    assert.equal(await page.evaluate(() => __BEAUTICODE_BG__.setBackgroundTone("light")), true);
+    await page.evaluate(() => { window.guestBeforeHandoff = __BEAUTICODE_GUEST__; });
+    await inject({ ...payload, generation: 3 });
+    await page.waitForFunction(() => __BEAUTICODE_BG__.snapshot().videoReady, null, { timeout: 5000 }).catch(async () => {
+        throw new Error(JSON.stringify(await page.evaluate(() => ({ snapshot: __BEAUTICODE_BG__.snapshot(), error: __BEAUTICODE_BG__.videoError, video: [...document.querySelectorAll("video")].map(v => ({ readyState: v.readyState, paused: v.paused, srcLength: v.src.length, error: v.error?.message })) }))));
+    });
+    const snap = await page.evaluate(() => __BEAUTICODE_BG__.snapshot());
+    assert.equal(snap.videoCount, 1);
+    assert.equal(snap.fish, true);
+    assert.equal(snap.muted, true);
+    assert.equal(await page.evaluate(() => __BEAUTICODE_BG__.isBackgroundTone()), "light");
+    assert.equal(await page.evaluate(() => guestBeforeHandoff === __BEAUTICODE_GUEST__), true);
+    await page.evaluate(() => __BEAUTICODE_BG__.dispose());
+    assert.equal(await page.locator("#beauticode-bg-stage").count(), 0);
+});