dsh-panel-control 0.4.0 → 0.7.1

package/docs/discussion-bundle-evaluated-twice.md

@@ -0,0 +1,100 @@
+# 「同一个 client bundle 被求值两次」：一个插件让另一个插件整条消失的排查记录
+
+> 本文记录一次真实故障：插件 A 一旦启用，插件 B 的侧栏入口和全部功能就**整体消失**，看起来像 B 被平台「移除」了。最终定位到的根因不是两个插件的功能冲突，而是 **A 的客户端 bundle 在同一个 document 里被当作经典脚本求值了两次**：第二次在解析阶段抛 `SyntaxError`，而这条错误发生在「组合批」执行过程中，**打断了整轮插件启动**，排在 A 后面出场的 B 永远轮不到 `apply()`。
+
+---
+
+## 1. 现象
+
+- 环境：DSH 桌面端（Web 前端壳 `dsh-app://app`），Cordis 插件体系，插件用本地 `link:` 安装。
+- 症状：启用**面板管理**（dsh-panel-control）后，**工作区管理**（dsh-workspace-control）的侧栏入口立即消失，会话菜单项与相关工具一并不可用；插件管理里它仍显示为「运行」。
+- 关键对照：**关掉面板管理并刷新页面，工作区管理立刻回来。** 因果成立，但不是功能冲突。
+- 更迷惑的是：面板管理自己有时也「不运行」——同一进程里冷启动成功、刷新后失效，行为不稳定。
+
+## 2. 环境
+
+| 项 | 值 |
+| --- | --- |
+| 桌面端 | DSH Desktop（Web 前端壳 `dsh-app://app`） |
+| 插件机制 | Cordis：宿主半边（Node）+ 客户端半边（`client.js` bundle） |
+| 安装方式 | `dsh.profile.bundles` 列表 + `dependencies: link:` |
+| 干扰项 | `dsh-unlag`（刷新/热重载插件，会代理 `/plugins/` 路由并按图重拼组合批） |
+| 系统 | Windows 11 |
+
+## 3. 走过的弯路（这部分比结论更有用）
+
+| # | 假设 | 为什么被否掉 |
+| --- | --- | --- |
+| 1 | 「模块图每次启动都在重组，页面冻结的清单对不上」 | 同一形状的 26 项批重复出现，结果时好时坏 ⇒ 是竞态 + 另一条独立路径，不是单纯的图抖动 |
+| 2 | 宿主侧把「过期组合批」用「单模块字节」顶替 | 服务器日志 13 条 bundle 请求**全是 single**，没有一次 combo 走到该分支；修好后症状依旧 |
+| 3 | 单个模块 import 失败会连坐其它插件 | 读源码：`reconcile` 每包独立 try/catch，失败只进 `failures`，不中止别人 |
+| 4 | 我们的插件把对方隐藏了（hidden 列表 / 侧栏 `display:none`） | `prefs.json` 里 `hidden=[]`；而且即使 DOM 全隐藏，槽表也应该还有对方条目——实际没有 |
+| 5 | 页面自动刷新打断了批次加载 | `reloadPage` 只挂在用户手动点击的按钮上，没有自动调用点 |
+
+> 教训：**「槽表里没有它」比「DOM 里没有它」是强得多的判据。** `entriesOfSlot` 返回已注册条目且不按可见性过滤，所以「槽表无条目」直接排除所有 CSS/DOM 解释，把问题逼进「客户端模块到底有没有执行」这一层。
+
+## 4. 真正的证据来自页面内部
+
+宿主日志只能看 HTTP 状态码，而这里所有 bundle 都是 200，宿主侧完全看不出问题。突破口是**让插件自己在页面里留痕**：
+
+1. **模块顶层就写 localStorage**：`client.js` 一执行就记一条（阶段序列 `top → build → factory → apply → ready`，加上 `typeof window.__ModuleLoader__` 与 boot 清单摘要）。阶段停在 `factory` 就说明「脚本跑了，但 apply 没被调用」。
+2. **`window.addEventListener('error', ..., true)` + unhandledrejection + 包装 console.error/warn**，把原文写进同一个值。
+3. 离线读 Chromium 的 LevelDB（`Local Storage/leveldb` 下的 `*.log`/`*.ldb`，值按 UTF-16LE 解码）——不需要 DevTools，也不需要人工盯界面。
+
+拿到的决定性一行：
+
+```text
+Uncaught SyntaxError: Identifier 'PAGE_LOG' has already been declared
+  @ dsh-app://app/plugins/??dsh-panel-control/client.js&rev=4bbae3358a87:1
+```
+
+以及更早一批重复注册错误（说明这是同一个实例的第二次执行）：
+
+```text
+Error: keyed slot "main" already has an entry for key "panel-control" at priority 0
+list slot "sidebar.panellist" already has an entry with id "panel-control"
+list slot "settings.section" already has an entry with id "panel-control-settings"
+```
+
+## 5. 根因链条
+
+机制（`dsh-client-modules/lib/client.js`）：
+
+1. `start()` 先 `await Promise.all(desired.plugins.map(...))` 再 `await loader.await()`，**没有 per-entry 失败隔离**：一轮里抛出即整轮中止。
+2. 同一 bundle 执行两次时，`register` 会抛 `client-modules: duplicate factory registration for "<id>" (bundle executed twice without invalidate?)`；但如果脚本带顶层 `const`，它在**解析阶段**就死了，连这句友好错误都拿不到，只剩 `SyntaxError`。
+3. 对立即加载的插件，平台会发一条独立单包 URL；同一份代码又出现在组合批里（批用于补齐增量模块）。两条路径各执行一次 ⇒ 双求值。`invalidate(id, rev)` 本应在重载时清工厂，但「同 rev 被两个入口各执行一次」不经过它。
+
+**症状对应**：批内顺序上 dsh-workspace-control 恰好紧跟在本插件后面（多次日志都是 `[dsh-panel-control], dsh-workspace-control` 相邻），所以整轮一断它第一个陪葬 → 入口、菜单、工具全没 → 看起来「像被移除了」。插件管理读宿主状态，宿主半边一直活着，所以仍显示「运行」。
+
+## 6. 修复（插件侧，已上线 v0.6.4）
+
+1. **整份 `client.js` 包进 IIFE**，杜绝顶层 `const/let` 落到全局词法作用域——双求值从此最多是「重复注册」，不再是 `SyntaxError`。
+2. **注册调用全部 try/catch**：撞 duplicate 时 `console.warn` 并保留第一个实例，绝不外抛。
+3. **不做跨版本「早退」优化**：停用插件时平台会 delete 工厂，重开必须重新注册；早退会导致 `import failed` 启动崩溃（我们踩过）。
+4. 声明 `immediately: true`，拥有独立单包 URL，不依赖组合批是否包含自己。
+5. 删掉一切「自己造 `/plugins/` 请求」的探针——那会额外制造 duplicate factory registration，等于自己给自己下毒。
+
+验证：连续 4 次冷启动 + 1 次停用/启用，`slots` 同时含两个插件、侧栏两条入口均 shown、page-log 0 条、崩溃目录无新增 `web-boot` 日志。
+
+## 7. 给平台的建议（按收益排序）
+
+1. **`loader.start()` 做 per-entry 隔离**：单条 create/apply 失败只把该条目记进 `failures`，不要中止整轮。今天「一个插件写错一行」= 「后面所有插件静默消失」。
+2. **bundle 执行幂等化**：同一 `(id, rev)` 在同一个 document 内第二次执行直接跳过；或注入前比对 rev，已注册就不再插 `<script>`。
+3. **重复注册可降级为警告**（opt-in）：撞 id 时若两份 label/locale 相同，保留先注册者。
+4. **启动失败要能看见**：`web boot: 1 entry did not activate` 应带上是哪一条，以及被中止后继条目的完整列表。
+5. 文档补一句：`client.js` 是经典脚本，**必须**自包 IIFE；顶层 `const` 在双求值场景下是致命错误。
+
+## 8. 给插件作者的防御清单
+
+- [ ] 整份 `client.js` 包 IIFE，不往 window 写裸 `const/let`。
+- [ ] 所有 `ctx.slots.register` / `ctx.provide` / 工具注册包 try/catch，撞重复只警告。
+- [ ] 不要主动请求 `/plugins/...`：那不是探针，是自伤。
+- [ ] 别在 `dsh-app://` 页面用 `performance.getEntriesByType('resource')` 观测网络：非 http(s) 协议不计数，永远是 0。
+- [ ] 页面内取证优先写 `localStorage`（模块顶层就写），离线读 LevelDB，可留档且不依赖人工。
+- [ ] 「插件没出现」先查 `ctx.slots.entriesOfSlot(...)`：**槽表有 = 渲染问题；槽表无 = 执行问题**。
+- [ ] 宿主侧日志记录**所有** bundle 请求与状态码（不止自己），否则 404 / 双求值完全不可见。
+- [ ] 把平台报的 duplicate registration 原文贴进 issue，它通常直接指向双求值。
+
+---
+
+**一句话总结**：这不是「两个插件冲突」，而是「一个插件被平台执行了两次，第二次在解析期爆炸，把整批插件的启动循环炸断了」。诊断的关键不在宿主 HTTP 日志（全是 200），而在让页面自己把执行阶段写到硬盘上。

package/docs/sidebar-layout.md

@@ -0,0 +1,40 @@
+# 侧栏布局：为什么是兜底而不是改包
+
+## 问题
+
+`@deepseek-ai/dsh-client-ui-sidebar` 的 `.root` 下，`panelList` 与 `regionArea` 是兄弟节点：
+
+```css
+.hHd-Xa_panelList  { flex: none; }
+.hHd-Xa_regionArea { flex: 1; overflow: hidden; }
+```
+
+导航项超过窗口能容纳的高度后，列表按内容高度独占，`regionArea` 分到的高度趋近 0，`overflow:hidden`
+把内容裁掉，而全页没有任何可滚动容器——滚轮"失效"只是现象。官方包在 0.2.1-rc.4 上如此，桌面浏览器
+压到约 700px 也能复现。
+
+## 做法
+
+1. **不改官方包**。类名是构建时哈希（`hHd-Xa_`、`wtg9ga_`），每次发版都会变，任何按类名写的补丁都会碎。
+   插件只加自己的属性：`data-dpc-list`、`data-dpc-unbounded`、`data-dpc-region`。
+2. **CSS 只依赖属性**，写在 `SIDEBAR_CSS`：
+   - 列表 `flex:0 1 auto;min-height:0;overflow-y:auto;max-height:max(120px,var(--dpc-panellist-max,45vh))`
+   - 上限「不限」时加 `data-dpc-unbounded` → `max-height:none`（仍然可滚）
+   - 区域 `flex:1 1 auto;min-height:min(120px,18vh)`，保证会话区永远有位置
+3. **每次 apply 重新打标**（列表可能被 React 重建）；`destroy()` 逐个移除属性与 `--dpc-panellist-max`。
+4. **分组标题即折叠按钮**。标题本来由本插件插入，所以点击处理不碰 React 的节点；折叠只是给组员按钮
+   写 `display:none` + `data-dpc-collapsed`，与「隐藏」是两条独立的状态。
+
+## 边界
+
+- 窄侧栏（宽度 < `WIDE_MIN_WIDTH`=64px）不渲染标题、不折叠：那里没有空间放 caret 和计数。
+- 设置里关掉「高度兜底」后两个属性都会被移除，行为完全回到官方默认；用户随时能退回。
+- 上限夹在 0–70vh；`sanitize()` 会把历史文件里缺失的字段补成默认值（guard/collapse 默认开，panelMax 45）。
+- 折叠状态按组 id 保存；组被删除后残留的 id 无害，`sanitize()` 会去重并限长。
+
+## 验证
+
+- `npm run check` 跑 `scripts/layout-smoke.mjs`：断言属性钩子、CSS 三条规则、`BUILD_STAMP` 与
+  `package.json` 版本一致。
+- 运行时：`[data-dpc-list]` 的 `getComputedStyle(...).overflowY` 应为 `auto`，上限 45vh 时
+  `maxHeight` 为 `max(120px, 45vh)`；点标题后该组按钮 `display:none`、标题仍在。

package/index.js

@@ -17,6 +17,7 @@
 
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -75,6 +76,23 @@ function isLoopbackAuthority(authority) {
   }
 }
 
+/**
+ * The desktop's dev-proxy serves the page from a reserved origin such as
+ * `http://unlag.invalid`. That TLD never resolves, so only a proxy running
+ * inside this Host can put it in a Host header -- but the page is still ours.
+ * Treating it as foreign refused every call the plugin made for itself.
+ */
+function isProxyAuthority(authority) {
+  if (typeof authority !== 'string' || authority === '') return false;
+  try {
+    const url = new URL(`http://${authority}`);
+    if (url.username || url.password || url.pathname !== '/' || url.search || url.hash) return false;
+    return /\.invalid$/.test(url.hostname.replace(/\.$/, ''));
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Only the page the Host itself served may call this route.
  *
@@ -86,7 +104,10 @@ function isLoopbackAuthority(authority) {
  */
 function isOwnRequest(request) {
   const host = request.headers.get('host');
-  if (!isLoopbackAuthority(host)) return false;
+  const proxied = isProxyAuthority(host);
+  if (!isLoopbackAuthority(host) && !proxied) return false;
+  // A proxied page cannot be told apart by port: the proxy owns the authority.
+  if (proxied) return true;
   // A browser labels where the request came from; anything but same-origin (or
   // a non-browser caller) is a different page and has no business here.
   const site = request.headers.get('sec-fetch-site');
@@ -401,7 +422,30 @@ async function classify(scope, payload, signal) {
 /* -------------------------------------------------------------------- route */
 
 async function handle(scope, request) {
-  if (!isOwnRequest(request)) return new Response('forbidden', { status: 403 });
+  // A page beacon is a plain GET: it has to work from the bundle's module scope,
+  // where no service exists yet, and it is the only channel that still speaks
+  // when the runner never applies the Client half.
+  {
+    const beaconUrl = new URL(String(request.url || ''), 'http://beacon.invalid');
+    if (beaconUrl.pathname === ROUTE_PATH && beaconUrl.searchParams.has('d')) {
+      if (!isOwnRequest(request)) {
+        logHost(`page-beacon refused: host=${request.headers.get('host')} origin=${request.headers.get('origin')}`);
+        return new Response('forbidden', { status: 403 });
+      }
+      const text = String(beaconUrl.searchParams.get('d') || '').slice(0, 700);
+      logHost(`page-beacon: ${text}`);
+      return new Response('ok', { status: 200, headers: { 'content-type': 'text/plain' } });
+    }
+  }
+  if (!isOwnRequest(request)) {
+    // Stay quiet here and "the page ran but was refused" looks exactly like
+    // "the page never ran": every hostCall returns null on a 403, so the
+    // Client half logs nothing either way.
+    logHost(
+      `refused: ${request.method} host=${request.headers.get('host')} origin=${request.headers.get('origin')} site=${request.headers.get('sec-fetch-site')} · ${String(request.url || '').split('?')[0].slice(0, 80)}`,
+    );
+    return new Response('forbidden', { status: 403 });
+  }
   if (request.method !== 'POST') return new Response('method not allowed', { status: 405 });
   const contentType = request.headers.get('content-type');
   if (!contentType || contentType.split(';', 1)[0].trim().toLowerCase() !== 'application/json') {
@@ -513,12 +557,82 @@ function logInventoryOnApply(scope) {
       `graph: ${listed ? 'lists' : 'does not list'} ${PACKAGE} · rev ${value.rev} · ` +
         `${value.ids.length} client entr${value.ids.length === 1 ? 'y' : 'ies'}`,
     );
-    if (listed) void probeOwnBundle(scope);
+    if (listed) {
+      void probeOwnBundle(scope);
+      logBatchPlacement(scope);
+    }
   } catch (error) {
     logHost(`graph: probe failed (${describeError(error)})`);
   }
 }
 
+/**
+ * Where in the composed graph this package sits. The page's frozen list names
+ * our package by two URLs: the single-resource URL on `entry.url` (rev == our
+ * artifact rev) and the batch URL it actually boots with (a combo rev shared
+ * with the neighbours). When a cold start serves the batch but never executes
+ * it, these lines show whether the page's batch rev matches the one the Host
+ * composed now, or is a retired batch.
+ */
+function logBatchPlacement(scope) {
+  try {
+    const modules = clientModules || serviceOf(scope, 'clientModules');
+    const graph = modules && typeof modules.graph === 'function' ? modules.graph() : null;
+    const entries = graph && Array.isArray(graph.entries) ? graph.entries : [];
+    const batches = graph && Array.isArray(graph.batches) ? graph.batches : [];
+    const entry = entries.find((row) => row && row.id === PACKAGE);
+    if (entry) {
+      logHost(
+        `graph: own row ${JSON.stringify({
+          id: entry.id,
+          url: entry.url,
+          rev: entry.rev,
+          immediately: entry.immediately,
+          inject: entry.inject,
+          external: entry.external,
+        })}`,
+      );
+    }
+    // Every row, once per start: a repeated id, or two ids over one bundle, is what makes a
+    // page apply a plugin twice and collide on the slot ids it registers.
+    const rows = entries.map((row) => ({
+        id: row && row.id,
+        rev: row && row.rev,
+        immediately: row && row.immediately,
+        url: String((row && row.url) || '').slice(0, 120),
+      }));
+      const byId = new Map();
+      for (const row of rows) byId.set(row.id, (byId.get(row.id) || 0) + 1);
+      const repeated = [...byId].filter((pair) => pair[1] > 1).map((pair) => `${pair[0]}x${pair[1]}`);
+      const byUrl = new Map();
+      for (const row of rows) {
+        const key = String(row.url || '').split('&rev=')[0];
+        byUrl.set(key, [...(byUrl.get(key) || []), row.id]);
+      }
+      const shared = [...byUrl].filter((pair) => pair[1].length > 1).map((pair) => `${pair[0]} <- ${pair[1].join(',')}`);
+      logHost(`graph: batches=${batches.length} rows=${rows.length} repeated=${JSON.stringify(repeated)} shared-bundle=${JSON.stringify(shared.slice(0, 4))}`);
+        for (const batch of batches) {
+          const ids = batch && Array.isArray(batch.entries) ? batch.entries : [];
+          logHost(`graph: batch dump one phase=${String(batch && batch.phase)} rev=${String(batch && batch.rev)} n=${ids.length} ws=${ids.includes('dsh-workspace-control')} pc=${ids.includes(PACKAGE)}`);
+        }
+      logHost(`graph: ids ${rows.map((row) => row.id).join(',')}`);
+    for (const batch of batches) {
+      if (!batch || !Array.isArray(batch.entries) || !batch.entries.includes(PACKAGE)) continue;
+      const index = batch.entries.indexOf(PACKAGE);
+      const neighbours = batch.entries
+        .slice(Math.max(0, index - 1), index + 2)
+        .map((id, i) => (id === PACKAGE ? `[${id}]` : id))
+        .join(',');
+      logHost(
+        `graph: batch ${batch.phase} · rev ${String(batch.rev)} · ${batch.entries.length} entries · ` +
+          `#${index} near {${neighbours}} · url ${String(batch.url)}`,
+      );
+    }
+  } catch (error) {
+    logHost(`graph: batch placement failed (${describeError(error)})`);
+  }
+}
+
 /**
  * Serve the current revision when a page asks for one this process has retired.
  *
@@ -535,7 +649,9 @@ function logInventoryOnApply(scope) {
  * gets the bytes it needs; everything else passes straight through, and the
  * patch is undone on teardown.
  */
-const SERVE_CURRENT = String(process.env.DPC_SERVE_CURRENT || '').toLowerCase() !== 'off';
+// Off by default: rewriting the shared bundle service is a whole-page change that
+// other plugins pay for. It stays available as an explicit escape hatch only.
+const SERVE_CURRENT = String(process.env.DPC_SERVE_CURRENT || '').toLowerCase() === 'on';
 let servePatched = null;
 let serveLoggedAt = 0;
 /**
@@ -548,9 +664,30 @@ let serveLoggedAt = 0;
  */
 const servedBytes = new Map();
 const SERVED_BYTES_KEPT = 5;
+
+/**
+ * A combo request asks for several bundles at once (`/plugins/??a,b,c`).
+ *
+ * A combo response can only be answered whole: handing back one module's bytes
+ * for a combo URL is not a stale revision, it is a broken batch. The page that
+ * receives it registers this plugin and nothing else in the batch, so every
+ * plugin after ours in the composition disappears without an error. Keep the
+ * two shapes strictly apart.
+ */
+function isComboUrl(url) {
+  const value = String(url || '');
+  const query = value.indexOf('??');
+  return query !== -1 && value.slice(query + 2).split('&')[0].includes(',');
+}
+
+/** Bytes are remembered per (revision, shape): one revision can exist as a
+ * single bundle and as a combo, and the two bodies are not interchangeable. */
+function servedKey(url) {
+  return `${revisionOf(url) || ''}|${isComboUrl(url) ? 'combo' : 'single'}`;
+}
 /** Requests to log per Host process: enough to see a boot, not a chatty stream. */
 let bundleAsked = 0;
-const BUNDLE_ASK_LIMIT = 8;
+const BUNDLE_ASK_LIMIT = 120;
 
 function revisionOf(url) {
   const match = /[?&]rev=([A-Za-z0-9._-]+)/.exec(String(url || ''));
@@ -565,15 +702,23 @@ function serveCurrentRevision(scope) {
   servePatched = modules;
   modules.bundleResource = async function bundleResourceWithFallback(method, url) {
     const answer = await original(method, url);
-    if (String(url || '').includes(PACKAGE) && bundleAsked < BUNDLE_ASK_LIMIT) {
+    // Log every bundle the page asks for, whichever plugin it belongs to: when a
+    // neighbour disappears, the question is whether its script *failed to arrive*
+    // (a status code here) or arrived and failed (a client-side message instead).
+    const askedUrl = String(url || '');
+    if (askedUrl.includes('??') && bundleAsked < BUNDLE_ASK_LIMIT) {
       bundleAsked += 1;
-      logHost(`bundle: asked rev ${String(revisionOf(url))} -> ${answer && answer.status}`);
+      logHost(
+        `bundle: asked ${isComboUrl(askedUrl) ? 'combo' : 'single'} ` +
+          `rev ${String(revisionOf(askedUrl))} -> ${answer && answer.status} · ${askedUrl.slice(0, 160)}`,
+      );
     }
     if (answer && answer.status === 200 && method === 'GET' && String(url || '').includes(PACKAGE)) {
       const rev = revisionOf(url);
       if (rev && typeof answer.body === 'string') {
-        servedBytes.delete(rev);
-        servedBytes.set(rev, answer);
+        const key = servedKey(url);
+        servedBytes.delete(key);
+        servedBytes.set(key, answer);
         while (servedBytes.size > SERVED_BYTES_KEPT) {
           servedBytes.delete(servedBytes.keys().next().value);
         }
@@ -582,11 +727,12 @@ function serveCurrentRevision(scope) {
     if (answer && answer.status !== 404) return answer;
     try {
       const requested = String(url || '');
-      if (!requested.includes(PACKAGE)) return answer;
       // A revision this Host already handed out outranks the current one: the
       // page booted with it, and its list will keep naming it.
       const asked = revisionOf(requested);
-      const remembered = asked ? servedBytes.get(asked) : undefined;
+      const remembered = asked && requested.includes(PACKAGE)
+        ? servedBytes.get(servedKey(requested))
+        : undefined;
       if (remembered !== undefined) {
         if (Date.now() - serveLoggedAt > 30_000) {
           serveLoggedAt = Date.now();
@@ -596,10 +742,37 @@ function serveCurrentRevision(scope) {
         }
         return method === 'HEAD' ? { ...remembered, body: undefined } : remembered;
       }
+      // Only a single-bundle request may be re-pointed at the current revision.
+      // A combo has to be answered as the batch it asked for: replying with this
+      // package alone drops every other module the page listed, and the ones
+      // ordered after us in the composition never run. Let the registry's 404
+      // through instead, so the page reloads its list instead of half-booting.
+      if (isComboUrl(requested)) {
+        if (Date.now() - serveLoggedAt > 30_000) {
+          serveLoggedAt = Date.now();
+          logHost(
+            `bundle: stale combo rev ${String(asked)} left as a 404 (a batch cannot be ` +
+              'answered with one module; the page must reload its plugin list)',
+          );
+        }
+        return answer;
+      }
       const graph = typeof modules.graph === 'function' ? modules.graph() : null;
       const rows = graph && Array.isArray(graph.entries) ? graph.entries : [];
-      const entry = rows.find((row) => row && row.id === PACKAGE);
-      if (!entry || typeof entry.url !== 'string') return answer;
+      // Every plugin that declares `immediately` is fetched as a single bundle
+      // of its own, so a retired revision drops exactly one plugin: its script
+      // never runs, it never registers a slot, and the manager still reports it
+      // running. Rescuing only this package made this plugin outlive its
+      // neighbours: the one carrying the fallback survived while the one next
+      // to it vanished. Rescue every row the page named instead.
+      const entry = rows.find(
+        (row) =>
+          row &&
+          typeof row.id === 'string' &&
+          typeof row.url === 'string' &&
+          requested.includes(`${row.id}/client.js`),
+      );
+      if (!entry) return answer;
       const retryUrl = entry.url.startsWith('/') ? entry.url : `/${entry.url}`;
       if (retryUrl === requested) return answer;
       const retried = await original(method, retryUrl);
@@ -607,8 +780,11 @@ function serveCurrentRevision(scope) {
       if (Date.now() - serveLoggedAt > 30_000) {
         serveLoggedAt = Date.now();
         logHost(
-          `served ${PACKAGE} at the current revision: the page asked for a retired one ` +
-            '(its plugin list predates the last write to client.js)',
+          entry.id === PACKAGE
+            ? `served ${PACKAGE} at the current revision: the page asked for a retired ` +
+              'one (its plugin list predates the last write to client.js)'
+            : `served ${entry.id} at the current revision: the page asked for a retired ` +
+              'one, and a missing bundle silently drops that plugin',
         );
       }
       return retried;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-panel-control",
-  "version": "0.4.0",
+  "version": "0.7.1",
   "type": "module",
   "description": "Manage the global panel navigation at the top of the DSH sidebar: reorder, hide and group every entry, with the layout persisted per installation.",
   "keywords": [
@@ -50,7 +50,7 @@
     "url": "https://github.com/QIUZAIYOU/dsh-panel-control/issues"
   },
   "scripts": {
-    "check": "node --check index.js && node --check client.js && node scripts/host-smoke.mjs",
+    "check": "node --check index.js && node --check client.js && node scripts/host-smoke.mjs && node scripts/layout-smoke.mjs",
     "smoke": "node scripts/host-smoke.mjs",
     "doctor": "node scripts/profile-doctor.mjs",
     "enable": "node scripts/enable-local.mjs"

package/scripts/host-smoke.mjs

@@ -29,6 +29,9 @@ const MODULE = pathToFileURL(override ? path.resolve(override) : path.join(here,
 // The recovery nudge rewrites the real client.js when a page never reports; the
 // harness must stay read-only about the checkout.
 process.env.DPC_NUDGE = 'off';
+// Rescue-by-current-revision is an explicit opt-in now: the pages below exercise
+// it deliberately, while the default path is asserted later.
+process.env.DPC_SERVE_CURRENT = 'on';
 
 const timers = [];
 const realSetTimeout = globalThis.setTimeout;
@@ -62,6 +65,10 @@ const clientModulesStub = {
       { id: 'a' },
       { id: 'b' },
       { id: 'dsh-panel-control', rev: 'rev-now', url: 'plugins/??dsh-panel-control/client.js&rev=rev-now' },
+      // The plugin that sits next to this one in the real profile: it carries no
+      // fallback of its own, so a retired revision used to drop it silently
+      // while the manager still reported it running.
+      { id: 'dsh-workspace-control', rev: 'rev-now', url: 'plugins/??dsh-workspace-control/client.js&rev=rev-now' },
     ],
     batches: [],
   }),
@@ -195,6 +202,19 @@ if (route) {
       '/plugins/??dsh-panel-control/client.js&rev=rev-old',
     );
     check('stale revision is served at the current one', stale.status === 200, `status ${stale.status}`);
+    // A combo is the batch the page booted with. Answering it with this one
+    // module's bytes registers this plugin and silently drops every other module
+    // in the batch -- the page then runs one plugin instead of the list it
+    // booted with. The stale combo has to stay a 404.
+    const staleCombo = await clientModulesStub.bundleResource(
+      'GET',
+      '/plugins/??a/client.js,b/client.js,dsh-panel-control/client.js&rev=rev-old-combo',
+    );
+    check(
+      'a stale combo is not answered with the single bundle',
+      staleCombo.status === 404,
+      `status ${staleCombo.status}`,
+    );
     // A revision this Host already handed out must survive the registry
     // forgetting it: the page keeps asking for the list it booted with.
     await clientModulesStub.bundleResource('GET', '/plugins/??dsh-panel-control/client.js&rev=rev-now');
@@ -211,11 +231,23 @@ if (route) {
     );
     check('current revision passes straight through', fresh.status === 200, `status ${fresh.status}`);
     const other = await clientModulesStub.bundleResource('GET', '/plugins/??someone-else/client.js&rev=old');
-    check('other packages keep their 404', other.status === 404, `status ${other.status}`);
+    check('packages outside the graph keep their 404', other.status === 404, `status ${other.status}`);
+    // The reported bug: a *neighbouring* plugin on a retired revision. Our
+    // bundle loaded, theirs 404'd, and it vanished from the page while the
+    // manager kept saying "running". One fallback for the whole list fixes it.
+    const neighbour = await clientModulesStub.bundleResource(
+      'GET',
+      '/plugins/??dsh-workspace-control/client.js&rev=rev-old',
+    );
+    check(
+      'a neighbouring plugin is served at the current revision too',
+      neighbour.status === 200,
+      `status ${neighbour.status}`
+    );
     check(
       'inventory ids',
       Array.isArray(body.result.value.ids) &&
-        body.result.value.ids.join() === 'a,b,dsh-panel-control',
+        body.result.value.ids.join() === 'a,b,dsh-panel-control,dsh-workspace-control',
       body.result.value && body.result.value.ids.join(),
     );
   } catch (error) {
@@ -259,6 +291,17 @@ if (route) {
   } catch (error) {
     check('custom-protocol page allowed', false, error.message);
   }
+  // The desktop dev-proxy serves the page from a reserved .invalid origin; the
+  // page is still ours, so its calls must not be refused.
+  try {
+    const response = await route.fetch(
+      request(envelope('inventory'), { host: 'unlag.invalid', origin: 'http://unlag.invalid' }),
+    );
+    const body = await response.json();
+    check('dev-proxy page allowed', response.ok === true && body.result && body.result.ok === true, String(response.status));
+  } catch (error) {
+    check('dev-proxy page allowed', false, error.message);
+  }
   // An oversized body is refused before it is parsed.
   try {
     const huge = request(envelope('inventory'));

package/scripts/layout-smoke.mjs

@@ -0,0 +1,48 @@
+// Static gate for the sidebar layout guard (discussion #12083).
+//
+// The guard is CSS plus a handful of attributes the engine writes; neither is
+// reachable from a node unit test because client.js only loads inside the page
+// module loader. These assertions keep the pieces the runtime check proved are
+// necessary from silently disappearing in a refactor.
+import { readFileSync } from 'node:fs';
+
+const read = (name) => readFileSync(new URL('../' + name, import.meta.url), 'utf8');
+const client = read('client.js');
+const pkg = JSON.parse(read('package.json'));
+const problems = [];
+
+const expect = (ok, message) => {
+  if (!ok) problems.push(message);
+};
+
+for (const marker of [
+  'data-dpc-list',
+  'data-dpc-unbounded',
+  'data-dpc-region',
+  '--dpc-panellist-max',
+  'data-dpc-group-id',
+  'dpc-caret',
+  'dpc-sepCount',
+  'layoutTitle',
+  'layoutGuard',
+  'layoutMaxNone',
+  'toggleCollapse',
+]) {
+  expect(client.includes(marker), 'client.js lost ' + marker);
+}
+
+expect(client.includes("const BUILD_STAMP = 'dsh-panel-control/" + pkg.version + "'"), 'BUILD_STAMP and package.json version disagree');
+expect(pkg.scripts && String(pkg.scripts.check).includes('layout-smoke'), 'npm run check no longer runs this gate');
+expect(/\[data-dpc-list\]\{[^}]*overflow-y:auto/.test(client), 'the panel list is not scrollable');
+expect(/\[data-dpc-list\]\{[^}]*max-height:max\(120px,var\(--dpc-panellist-max,45vh\)\)/.test(client), 'the panel list lost its height cap');
+expect(/\[data-dpc-region\]\{[^}]*min-height/.test(client), 'the region below the list lost its floor');
+
+expect(/\.dpc-layoutRow:first-of-type\{[^}]*border-top:0/.test(client), 'the first layout row has a hairline touching the card hint');
+expect(/\.dpc-layout > \.dpc-note\{[^}]*margin:6px 0 10px/.test(client), 'the card hint lost its gap above the rows');
+expect(/\.dpc-layoutActions\{[^}]*margin-top:12px/.test(client), 'the collapse/expand actions lost their separation');
+if (problems.length) {
+  console.error('layout-smoke: ' + problems.length + ' problem(s)');
+  for (const problem of problems) console.error(' - ' + problem);
+  process.exit(1);
+}
+console.log('layout-smoke: ok (' + pkg.version + ')');