dsh-sidebar-suite 0.2.9 → 0.3.0

package/CHANGELOG.md

@@ -1,12 +1,29 @@
 # 更新日志 / Changelog
 
-> 版本号以 npm registry **实际发布记录**为准（当前：`0.0.0-stage`、`0.1.3`、`0.2.4`、`0.2.5`、`0.2.6`、`0.2.7`、`0.2.8`、`0.2.9`）。
+> 版本号以 npm registry **实际发布记录**为准（当前：`0.0.0-stage`、`0.1.3`、`0.2.4`、`0.2.5`、`0.2.6`、`0.2.7`、`0.2.8`、`0.2.9`、`0.3.0`）。
 > `0.2.0`、`0.2.1`、`0.2.2`、`0.2.3` 是开发过程中的本地迭代号，**从未单独发布**；它们的功能一次性随 `0.2.4` 上线，所以在下面合并记录。
 >
 > Versions mirror the npm registry. `0.2.0`–`0.2.3` were local iteration numbers that were never published on their own; all of their features shipped together in `0.2.4`.
 
 ---
 
+## 0.3.0 — 第三方插件可以注册自己的页签 / Third-party tabs（2026-11-11）
+
+**这次改了运行时代码**（`lib/client.js`），所以**升级后要托盘退出 DSH 再重开一次**。This release touches `lib/client.js`; quit DSH from the tray and reopen once after upgrading.
+
+- **侧栏变成可插拔的页容器** — 客户端通过 `ctx.provide('sidebarSuite', …)` 发布一个服务，别的插件 `inject = ['sidebarSuite']` 之后就能 `registerTab({ id, title, icon, order, mount })` 把自己的界面挂进侧栏。The sidebar is now a pluggable page container: a `sidebarSuite` service is published on the client context, and any plugin injecting it can register its own page.
+- **给的是普通 DOM 容器，不是 React 组件** — `mount(container, tab)` 拿到一个空 `<div>`，原生 DOM / React / canvas 都行，消费方不必和本插件的框架版本对齐。Consumers get a plain container, so any stack works and no React version has to line up.
+- **懒挂载 + 自带清理** — `mount` 只在页签第一次被打开时执行；返回的清理函数在页签移除、消费方卸载、DSH 退出时都会调用。`registerTab` 返回自己的 dispose 函数，正好能直接塞进 `ctx.effect`。Mount runs on first activation, and the returned disposer plugs straight into `ctx.effect`.
+- **同 id 重注册 = 原地替换** — 客户端热重载会重复注册，替换保证不会叠出两个同名页签，且旧页签的清理函数先跑。Re-registering an id replaces in place, which is what a hot reload needs.
+- **失败只烂在自己那一页** — `mount` 抛异常时错误写进它自己的容器并 `console.error` 一次，侧栏其余部分照常工作。A throwing consumer is contained inside its own page.
+- **页签条按布局出现** — 布局 B 下是 `[扩展][工作区][插件页…]` 并排；布局 A / C 下只有插件页进条（内置两组仍由原按钮控制，那两种布局不是页签模型）。**一个消费方都没有时这排页签是 `hidden` 的，不占高度**，看到的和 0.2.9 完全一样。Layout B lists the built-in groups alongside the plugin pages; layouts A and C list plugin pages only. With no consumers the strip is `hidden`: zero height, no visual change from 0.2.9.
+- **选中态是宿主主题色** — 当前页签底部一条 2px 强调色（`--dsw-alias-state-business-primary`），跟随工作区主题；窄侧栏（< 300px）自动只留图标，没给图标的页签保留文字而不是变成空白方块。The active page carries a 2 px accent underline in the workspace's theme colour; narrow columns go icon-only, and a tab without an icon keeps its label.
+- **选中哪一页跟着侧栏走** — 存 `localStorage["dsh-sidebar-suite:active-tab"]`，不写插件配置；再点一次当前页签退回原来的组。The selection lives in its own storage key, and re-clicking the active page returns to the groups.
+- **点了内置页签也会通知订阅者** — 布局 B 下点「扩展 / 工作区」等于把这一列从插件页手里拿走，`subscribe` 现在会像其它切换一样发出 `('active', null)`；反过来，在两个内置组之间来回切是静默的，不会假装有插件页移动。没有这一条，靠订阅停表 / 停轮询 / 停画布的消费方会以为自己还挂在屏幕上。A click on a built-in page notifies subscribers exactly like any other switch; moving between two built-ins stays silent.
+- **测试** — 新增两套：`tests/test_030.mjs` 在 vm 沙箱里按消费方的方式调服务（注册、列表、激活、订阅、注销、重复注册、非法入参，外加渲染与样式的源码契约、文档与版本联动，70 项）；`tests/test_031.mjs` 自己搭了一个符合宿主契约的侧栏 DOM，跑真实 `lib/client.js`，然后像用户那样点页签、再点一次退回、切布局 A/C、注销、点内置页签看通知（53 项，含「连续 60 次重绘不新增节点」的防抖动断言——`paint()` 每次插入节点的话，它自己装的 `MutationObserver` 会把它重新触发成死循环）。`npm test` 链扩为 9 套。Two new suites: one drives the service the way a consumer would, the other runs the real bundle against a synthetic host sidebar and clicks through it, including a repaint-loop guard.
+
+---
+
 ## 0.2.9 — 布局栏重做 + 视觉精修 / Toolbar rebuilt as a segmented control（2026-11-11）
 
 **这次改了运行时代码**（`lib/client.js`），所以**升级后要托盘退出 DSH 再重开一次**。This release touches `lib/client.js`; quit DSH from the tray and reopen once after upgrading.

package/DETAIL.md

@@ -81,6 +81,45 @@ The toolbar is one segmented control: `[fold | tabs | overlay] │ actions`. The
 
 `换布局 / Cycle` 默认不出现（`showQuickSwitch`），打开后和其它动作按钮共用同一套图标。`Cycle` is off by default and shares the icon set when enabled.
 
+## 第三方页签 / Third-party tabs（0.3.0）
+
+侧栏从 0.3.0 起是一个**可插拔的页容器**：别的插件通过 `ctx.sidebarSuite` 注册自己的页，用户点一下就能在你的界面和你自己的界面之间切换。
+
+```js
+export const inject = ['sidebarSuite']
+
+export function apply(ctx) {
+  ctx.effect(() => ctx.sidebarSuite.registerTab({
+    id: 'my-plugin',
+    title: { zh: '我的面板', en: 'My panel' },
+    icon: '<svg viewBox="0 0 16 16">…</svg>',   // 或一个 emoji
+    order: 100,
+    mount(container, tab) {
+      container.textContent = 'hello'
+      return () => { /* 清理 */ }
+    },
+  }))
+}
+```
+
+设计取舍 / Why it looks like this：
+
+- **给 DOM 容器，不给 React 组件** — 消费方可以是任何技术栈写的插件，不必和本插件的 React 版本对齐。A plain container works for every consumer regardless of framework.
+- **懒挂载** — `mount` 只在页签第一次被打开时执行，没打开过的页签不跑任何代码。Mount runs on first activation only.
+- **`registerTab` 返回自己的 dispose** — 正好是 `ctx.effect` 要的形状，消费方不用自己维护注销；消费方卸载时页签自动消失。The returned disposer plugs straight into `ctx.effect`.
+- **同 id 重注册 = 原地替换** — 客户端热重载会重复注册，替换能保证只有一个页签。Re-registering an id replaces in place, which is what a hot client reload needs.
+- **失败只烂在自己那一页** — `mount` 抛异常时，错误写进它自己的容器并 `console.error` 一次，侧栏其余部分不受影响。A throwing consumer is contained inside its own page.
+- **"失去这一列"只有一种通知方式** — 不管是被另一个插件页顶掉、被用户再点一次退回、还是布局 B 下点了「扩展 / 工作区」，走的都是同一次 `subscribe('active', null)`；在两个内置组之间来回切则不通知，因为对消费方来说什么都没变。订阅者不必自己推断"我现在还在不在屏幕上"。Losing the column always arrives as one notification, whoever took it; switching between two built-ins stays silent because nothing changed for the consumer.
+- **进不去的边界** — 页签只拿到发给它的容器，没有能力移动、覆盖或重构宿主 DOM。A tab owns its container and nothing else.
+
+三种布局的差异 / Under the three layouts：
+
+- B 标签页：`[扩展][工作区][你的页…]` 并排，都是页。
+- A 折叠、C 浮层：**只有第三方页**进条；内置两组仍由原按钮控制，因为这两种布局不是页签模型。
+- 没有任何第三方注册：页签条本身带 `hidden`，不占高度、不参与布局，看到的和 0.2.x 一模一样（只是多一个隐藏的空容器）。With no consumer the strip carries `hidden`: zero height, no layout impact — visually identical to 0.2.x.
+
+选中态存 `localStorage["dsh-sidebar-suite:active-tab"]`，不写插件配置；再点当前页签退回原来的组。
+
 ## 安装与生效 / Install & apply
 
 ```sh

package/README.md

@@ -104,6 +104,53 @@ The toolbar is one segmented control: the three mutually exclusive layouts share
 `换布局 / Cycle` 默认不出现，可用 `showQuickSwitch: true` 打开；它和其余动作按钮一起走同一套图标。
 `Cycle` stays hidden unless `showQuickSwitch: true`; it uses the same icon set as the other action buttons.
 
+## 第三方插件接入：注册自己的页签 / Third-party tabs（0.3.0）
+
+别的插件可以往侧栏注册一页自己的界面。客户端会拿到一个 `sidebarSuite` 服务：
+
+Any other plugin can put its own page in the sidebar through one client service.
+
+```js
+// 在消费方插件里 / in the consumer plugin
+export const inject = ['sidebarSuite']
+
+export function apply(ctx) {
+  ctx.effect(() => ctx.sidebarSuite.registerTab({
+    id: 'my-plugin',                            // 必填，[A-Za-z0-9._-]，≤48 字符
+    title: { zh: '我的面板', en: 'My panel' },   // 必填，或直接给字符串
+    icon: '<svg viewBox="0 0 16 16">…</svg>',   // 可选，也可以是一个 emoji
+    order: 100,                                 // 可选，越小越靠左，默认 100
+    mount(container, tab) {                     // 必填（别名 render）
+      container.textContent = 'hello'
+      return () => { /* 清理 */ }                // 可选：移除/卸载时调用
+    },
+  }))
+}
+```
+
+- `mount` 拿到的是**一个空的普通 `<div>`**，原生 DOM、React、canvas 都行，不要求你用哪套框架。
+- **首次点开才调用 `mount`**：没被打开过的页签不执行任何代码。
+- 返回的清理函数在页签被移除、消费方插件卸载、DSH 退出这三种情况下都会执行。
+- `registerTab` 返回它自己的 dispose 函数，所以 `ctx.effect(() => api.registerTab(...))` 就是完整写法，不用自己记着取消。
+- 同一个 id 重复注册 = **热重载**，会原地替换而不是叠出两个页签。
+
+页签出现在哪儿 / Where the page shows up：
+
+| 布局 | 表现 |
+|---|---|
+| B 标签页 | 和控制栏下面那排「扩展 / 工作区」并排 |
+| A 折叠、C 浮层 | 只有插件页签进条；内置两组仍由原按钮控制（这两种布局本来就不是"页签"模型） |
+| 没人注册 | 这排页签**完全不出现**，界面和 0.2.x 一模一样 |
+
+选中哪一页记在 `localStorage["dsh-sidebar-suite:active-tab"]`；**再点一次当前页签就退回原来的组**（布局 A / C 下这是唯一的退出口）。
+
+服务其余方法：`unregisterTab(id)`、`getTabs()`、`activateTab(id)`、`getActiveTab()`、`subscribe(fn)`（`fn(tabs, reason, activeId)`）、`getLayout()`。
+
+`reason` 的取值是 `register` / `unregister` / `active` / `orphan`。**点内置页签（布局 B 下的「扩展 / 工作区」）也算一次 `active`**（`activeId` 为 `null`），所以靠订阅停表、停轮询、停动画的代码不需要为内置页签另写一套判断；反过来，在两个内置组之间切换是静默的。
+
+> 边界是刻意的：一个页签只拥有发给它的那个容器，没有能力移动或重构侧栏，也不能覆盖宿主自己的界面。
+> A tab owns its container and nothing else — it cannot restructure the sidebar.
+
 ## 实现要点 / How it works
 
 - 所有持久状态写在 `<html>` 属性上：`data-dsbs-mode`、`data-dsbs-tab`、`data-dsbs-fold-ext`、`data-dsbs-fold-ws`、`data-dsbs-pop`、`data-dsbs-quick`、`data-dsbs-rail`、`data-dsbs-narrow`。CSS 负责显隐，插件不重构宿主 DOM。All state lives in `<html>` attributes; CSS owns visibility.

package/lib/client.js

@@ -19,8 +19,15 @@ window.__ModuleLoader__.load({
     'use strict'
 
     var ENTRY = 'dsh-sidebar-suite'
+    // Reported to tab consumers so they can feature-detect. Kept in lockstep
+    // with package.json by tests/test_030.mjs.
+    var VERSION = '0.3.0'
     var NS = 'sidebar-suite'
     var LS_KEY = 'dsh-sidebar-suite:state'
+    // Where the third-party tab choice lives. Kept out of LS_KEY on purpose:
+    // the config form describes the sidebar, this describes the user's
+    // current position inside it, and the two have different lifetimes.
+    var TAB_STORE_KEY = 'dsh-sidebar-suite:active-tab'
     var STYLE_ID = 'dsh-sidebar-suite-style'
     // Where feedback goes. A plugin bundle cannot open a mail client or post a
     // form without a server, so the entry point assembles a ready-to-send
@@ -79,6 +86,10 @@ window.__ModuleLoader__.load({
         'tab.to.ext.hint': 'Switch the shared space to the panels group.',
         'tab.to.ws': 'Show workspaces',
         'tab.to.ws.hint': 'Switch the shared space to the workspaces group.',
+        'tab.ext': 'Panels',
+        'tab.ws': 'Workspaces',
+        'tabs.label': 'Sidebar pages',
+        'tabs.own': 'This page is provided by {name}.',
         'pop.open': 'Open panels',
         'pop.close': 'Close panels',
         'pop.hint': 'Open or close the panels overlay.',
@@ -129,6 +140,10 @@ window.__ModuleLoader__.load({
         'tab.to.ext.hint': '把共用的一栏切换到扩展区。',
         'tab.to.ws': '显示工作区',
         'tab.to.ws.hint': '把共用的一栏切换到工作区。',
+        'tab.ext': '扩展',
+        'tab.ws': '工作区',
+        'tabs.label': '侧栏页签',
+        'tabs.own': '这一页由 {name} 提供。',
         'pop.open': '展开扩展',
         'pop.close': '收起扩展',
         'pop.hint': '打开或收起扩展浮层。',
@@ -356,6 +371,34 @@ window.__ModuleLoader__.load({
       '[data-row-key^="session:"]{transition:background-color .13s ease,box-shadow .13s ease,color .13s ease;font-variant-numeric:tabular-nums}',
       '[data-row-key^="session:"][aria-selected="true"]{box-shadow:inset 2px 0 0 var(--dsw-alias-state-business-primary,var(--dsw-alias-label-primary,#4d6bfe))!important}',
       'html[data-dsbs-rail="true"] [data-row-key^="session:"][aria-selected="true"]{box-shadow:none!important}',
+
+      // ---- third-party page strip (0.3.0) ------------------------------
+      // The strip only exists while at least one plugin registered a tab, so a
+      // stock profile never sees it. Everything inherits currentColor, which
+      // is what keeps it legible in both host themes without a palette here.
+      '[data-dsbs-tabs]{display:flex;align-items:center;gap:2px;padding:3px 4px 0;flex:none;overflow-x:auto;overflow-y:hidden;scrollbar-width:none}',
+      '[data-dsbs-tabs][hidden]{display:none!important}',
+      '[data-dsbs-tabs]::-webkit-scrollbar{display:none}',
+      '[data-dsbs-tabs] button{position:relative;display:inline-flex;align-items:center;gap:5px;flex:none;min-width:0;max-width:150px;padding:4px 9px;border:0;border-radius:7px 7px 0 0;background:transparent;color:inherit;font:inherit;font-size:11px;line-height:1.3;opacity:.6;cursor:pointer;white-space:nowrap;transition:opacity .14s ease,background-color .14s ease}',
+      '[data-dsbs-tabs] button:hover{opacity:.92;background:color-mix(in srgb,currentColor 8%,transparent)}',
+      '[data-dsbs-tabs] button[aria-selected="true"]{opacity:1;font-weight:600;background:color-mix(in srgb,currentColor 12%,transparent);box-shadow:inset 0 -2px 0 var(--dsw-alias-state-business-primary,currentColor)}',
+      '[data-dsbs-tablabel]{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;min-width:0}',
+      '[data-dsbs-tabicon]{display:inline-flex;align-items:center;justify-content:center;width:14px;height:14px;flex:none}',
+      '[data-dsbs-tabicon] svg{width:14px;height:14px;display:block;fill:none;stroke:currentColor;stroke-width:1.5;stroke-linecap:round;stroke-linejoin:round}',
+      '[data-dsbs-tabicon-text]{font-size:12px;line-height:1}',
+      '[data-dsbs-tabbadge]{flex:none;min-width:15px;padding:0 4px;border-radius:7px;font-size:10px;line-height:15px;text-align:center;background:color-mix(in srgb,currentColor 16%,transparent);font-variant-numeric:tabular-nums}',
+      // The tab's own container inherits the column the two groups gave up.
+      '[data-dsbs-tabpanel]{display:none;flex:1 1 auto;min-height:0;min-width:0;overflow:auto;flex-direction:column}',
+      '[data-dsbs-tabpanel][data-dsbs-visible="true"]{display:flex}',
+      'html[data-dsbs-ptab="true"] nav[data-dsbs-ext]{display:none!important}',
+      'html[data-dsbs-ptab="true"] div:has(> [data-slot="sidebar.workspaces"]){display:none!important}',
+      // Narrow: icon-only pages, the same rule the control bar follows. A tab
+      // without an icon keeps its label instead of becoming an empty box.
+      'html[data-dsbs-narrow="true"] [data-dsbs-tabs] button{max-width:64px;padding:4px 6px}',
+      'html[data-dsbs-narrow="true"] [data-dsbs-tabs] button[data-dsbs-hasicon] [data-dsbs-tablabel]{display:none}',
+      'html[data-dsbs-narrow="true"] [data-dsbs-tabs] button[data-dsbs-hasicon] [data-dsbs-tabbadge]{display:none}',
+      'html[data-dsbs-rail="true"] [data-dsbs-tabs]{padding:2px 2px 0}',
+      'html[data-dsbs-rail="true"] [data-dsbs-tabs] button{max-width:40px;padding:4px 5px}',
     ].join('\n')
 
     function assign(target) {
@@ -504,6 +547,11 @@ window.__ModuleLoader__.load({
         return DICTS[lang][key] || DICTS.en[key] || key
       }
       t.refresh = refresh
+      // Third-party tab titles may arrive as `{ zh, en }`; resolving them needs
+      // the same detector the dictionaries use, not a second guess.
+      t.langName = function () {
+        return lang
+      }
       return t
     }
 
@@ -559,6 +607,100 @@ window.__ModuleLoader__.load({
         resizeObserver: null,
         mutationObserver: null,
         raf: 0,
+        // 0.3.0 — third-party tabs. `activeTab` holds a registered id (or null
+        // for the built-in groups); `tabPanels` caches one live container per
+        // tab so a mount callback runs once and its disposer stays reachable.
+        activeTab: readActiveTab(),
+        seenTabs: Object.create(null),
+        tabStrip: null,
+        tabPanels: Object.create(null),
+        tabSignature: '',
+      }
+
+      // The public surface other plugins see. Everything here is either a
+      // function declaration (hoisted, so the object can be built before the
+      // implementations read below) or a getter that touches live state only
+      // when called.
+      var sidebarService = {
+        version: VERSION,
+        // Returns its own disposer, which is exactly what `ctx.effect(() => …)`
+        // wants, so a consumer never has to remember to unregister.
+        registerTab: function (descriptor) {
+          return registerTab(descriptor)
+        },
+        unregisterTab: function (id) {
+          return unregisterTab(id)
+        },
+        getTabs: function () {
+          return tabSnapshot()
+        },
+        activateTab: function (id) {
+          return activateTab(id)
+        },
+        getActiveTab: function () {
+          return runtime.activeTab && findTab(runtime.activeTab) ? runtime.activeTab : null
+        },
+        // A consumer can follow the strip instead of polling it: called with
+        // (tabs, reason, activeId) whenever the list or the selection changes.
+        subscribe: function (listener) {
+          if (typeof listener !== 'function') return function () {}
+          tabListeners.push(listener)
+          var off = false
+          return function () {
+            if (off) return
+            off = true
+            var at = tabListeners.indexOf(listener)
+            if (at >= 0) tabListeners.splice(at, 1)
+          }
+        },
+        // Reading the current shape lets a consumer align with the layout
+        // instead of sniffing classes off <html>.
+        getLayout: function () {
+          return {
+            mode: config.values.mode,
+            tab: config.values.tab,
+            activeTab: runtime.activeTab,
+            narrow: runtime.narrow === true,
+            rail: runtime.rail === true,
+          }
+        },
+      }
+
+      // Publish the service once the slot system is live.
+      //
+      // Two dead ends measured against this client context, both of which take
+      // the whole sidebar down:
+      //   * ctx.provide() directly inside apply() stalls the plugin loader on
+      //     "Loading plugins..." forever;
+      //   * a static `inject: ['slots']` never activates, so apply() never runs.
+      // Publishing from inside a dependency callback is the shape that works.
+      function publishService() {
+        try {
+          if (typeof ctx.provide === 'function') ctx.provide('sidebarSuite', sidebarService)
+        } catch (error) {
+          try {
+            console.warn('[dsh-sidebar-suite] could not publish the sidebarSuite service:', error)
+          } catch (inner) {
+            void inner
+          }
+        }
+      }
+      if (typeof ctx.inject === 'function') {
+        try {
+          ctx.inject(['slots'], function () { publishService() })
+        } catch (error) {
+          publishService()
+        }
+      } else {
+        publishService()
+      }
+      // One window handle for the same object. Not a second API: it exists so a
+      // consumer can reach the service from a plain browser context (and so the
+      // release checks can drive the strip over CDP).
+      try {
+        window.__dshSidebarSuite = sidebarService
+      } catch (error) {
+        void error
       }
 
       var manualCleanups = []
@@ -1163,6 +1305,430 @@ window.__ModuleLoader__.load({
         return bar
       }
 
+      // ---- third-party tabs (0.3.0) --------------------------------------
+      // Another plugin cannot reach into this bundle, so the whole feature is
+      // one service object handed to the client context (`ctx.provide` at the
+      // bottom of this file). The contract is deliberately DOM-shaped rather
+      // than React-shaped: a consumer receives a plain container and paints
+      // into it, which works for every plugin no matter how it was built.
+      //
+      // Deliberately absent: any way for a tab to restructure the sidebar.
+      // A tab owns its own container and nothing else.
+      var TAB_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,47}$/
+      var tabRecords = []
+      var tabListeners = []
+      var tabSeq = 0
+
+      function readActiveTab() {
+        try {
+          var raw = localStorage.getItem(TAB_STORE_KEY)
+          return typeof raw === 'string' && raw ? raw : null
+        } catch (error) {
+          return null
+        }
+      }
+
+      function writeActiveTab(id) {
+        try {
+          if (id) localStorage.setItem(TAB_STORE_KEY, id)
+          else localStorage.removeItem(TAB_STORE_KEY)
+        } catch (error) {
+          void error
+        }
+      }
+
+      function findTab(id) {
+        for (var i = 0; i < tabRecords.length; i++) {
+          if (tabRecords[i].id === id) return tabRecords[i]
+        }
+        return null
+      }
+
+      // `title` may be a plain string or `{ zh, en }`. Resolving it here keeps
+      // the two languages in one descriptor instead of making every consumer
+      // read the locale itself.
+      function tabTitle(record) {
+        var title = record.title
+        if (title && typeof title === 'object') {
+          var zh = typeof title.zh === 'string' ? title.zh : ''
+          var en = typeof title.en === 'string' ? title.en : ''
+          var preferred = t.langName() === 'zh' ? zh || en : en || zh
+          return preferred || record.id
+        }
+        return typeof title === 'string' && title ? title : record.id
+      }
+
+      function tabSnapshot() {
+        var out = []
+        for (var i = 0; i < tabRecords.length; i++) {
+          var record = tabRecords[i]
+          out.push({
+            id: record.id,
+            title: tabTitle(record),
+            icon: record.icon,
+            order: record.order,
+            badge: record.badge,
+            hidden: record.hidden,
+            owner: record.owner,
+          })
+        }
+        return out
+      }
+
+      function notifyTabs(reason) {
+        if (!tabListeners.length) return
+        var list = tabSnapshot()
+        var active = runtime.activeTab
+        for (var i = 0; i < tabListeners.length; i++) {
+          try {
+            tabListeners[i](list, reason, active)
+          } catch (error) {
+            void error
+          }
+        }
+      }
+
+      function tabContext(record) {
+        return {
+          id: record.id,
+          t: function (key) {
+            return t(key)
+          },
+          lang: function () {
+            return t.langName()
+          },
+          // Lets a consumer close its own tab once the user is done with it,
+          // rather than leaving a dead page in the strip.
+          close: function () {
+            if (runtime.activeTab === record.id) activateTab(null)
+          },
+        }
+      }
+
+      function createTabPanel(record) {
+        var panel = document.createElement('div')
+        panel.setAttribute('data-dsbs-tabpanel', record.id)
+        panel.setAttribute('role', 'tabpanel')
+        panel.setAttribute('aria-label', tabTitle(record))
+        panel.setAttribute('data-dsbs-visible', 'false')
+        var entry = { el: panel, cleanup: null, record: record, mounted: false }
+        runtime.tabPanels[record.id] = entry
+        return entry
+      }
+
+      // Mounting is deferred until the first activation: a tab that is never
+      // opened should cost nothing, and a container that is still `display:
+      // none` has no geometry to measure.
+      function mountTabPanel(entry) {
+        if (!entry || entry.mounted) return
+        entry.mounted = true
+        var record = entry.record
+        if (typeof record.mount !== 'function') return
+        try {
+          var result = record.mount(entry.el, tabContext(record))
+          if (typeof result === 'function') entry.cleanup = result
+          else if (result && typeof result.dispose === 'function') {
+            entry.cleanup = function () {
+              result.dispose()
+            }
+          }
+        } catch (error) {
+          // A broken consumer must never take the sidebar down with it: the
+          // failure is reported inside its own tab and logged once.
+          try {
+            entry.el.textContent = '[dsh-sidebar-suite] tab "' + record.id + '" failed to mount: '
+              + (error && error.message ? error.message : String(error))
+          } catch (inner) {
+            void inner
+          }
+          try {
+            console.error('[dsh-sidebar-suite] tab mount failed:', record.id, error)
+          } catch (inner) {
+            void inner
+          }
+        }
+      }
+
+      function disposeTabPanel(id) {
+        var entry = runtime.tabPanels[id]
+        if (!entry) return
+        delete runtime.tabPanels[id]
+        try {
+          if (typeof entry.cleanup === 'function') entry.cleanup()
+        } catch (error) {
+          void error
+        }
+        try {
+          if (entry.el && entry.el.parentNode) entry.el.parentNode.removeChild(entry.el)
+        } catch (error) {
+          void error
+        }
+      }
+
+      function disposeAllTabPanels() {
+        var ids = []
+        for (var id in runtime.tabPanels) ids.push(id)
+        for (var i = 0; i < ids.length; i++) disposeTabPanel(ids[i])
+      }
+
+      function unregisterTab(id) {
+        var record = findTab(id)
+        if (!record) return false
+        tabRecords.splice(tabRecords.indexOf(record), 1)
+        disposeTabPanel(id)
+        if (runtime.activeTab === id) {
+          runtime.activeTab = null
+          writeActiveTab(null)
+        }
+        notifyTabs('unregister')
+        scheduleSync()
+        return true
+      }
+
+      function registerTab(descriptor) {
+        if (!descriptor || typeof descriptor !== 'object') {
+          throw new TypeError('[dsh-sidebar-suite] registerTab(descriptor) needs an object')
+        }
+        var id = String(descriptor.id == null ? '' : descriptor.id).trim()
+        if (!TAB_ID_RE.test(id)) {
+          throw new TypeError('[dsh-sidebar-suite] registerTab: id must match ' + TAB_ID_RE + ', got "' + id + '"')
+        }
+        if (id === 'ext' || id === 'ws') {
+          throw new TypeError('[dsh-sidebar-suite] registerTab: "' + id + '" is reserved for a built-in group')
+        }
+        var mount = descriptor.mount || descriptor.render
+        if (typeof mount !== 'function') {
+          throw new TypeError('[dsh-sidebar-suite] registerTab: "' + id + '" needs mount(container) or render(container)')
+        }
+        var record = {
+          id: id,
+          title: descriptor.title,
+          icon: typeof descriptor.icon === 'string' ? descriptor.icon : null,
+          order: typeof descriptor.order === 'number' && isFinite(descriptor.order) ? descriptor.order : 100,
+          badge: descriptor.badge == null ? null : descriptor.badge,
+          hidden: descriptor.hidden === true,
+          mount: mount,
+          owner: descriptor.owner == null ? null : String(descriptor.owner),
+          seq: (tabSeq += 1),
+        }
+        // Re-registering the same id is exactly what a hot client reload looks
+        // like, so it replaces in place instead of stacking a duplicate page.
+        var previous = findTab(id)
+        if (previous) {
+          disposeTabPanel(id)
+          tabRecords.splice(tabRecords.indexOf(previous), 1)
+        }
+        tabRecords.push(record)
+        runtime.seenTabs[id] = true
+        notifyTabs('register')
+        scheduleSync()
+        var disposed = false
+        return function disposeTab() {
+          if (disposed) return
+          disposed = true
+          unregisterTab(id)
+        }
+      }
+
+      // Built-in groups only appear as pages in layout b. Layout a folds the
+      // two groups independently and layout c floats the panels, so a page
+      // switcher for them there would contradict what those layouts mean --
+      // third-party tabs still work in all three.
+      function tabEntries() {
+        var out = []
+        var showBuiltin = config.values.mode === 'b' && !!runtime.nav
+        if (showBuiltin) {
+          out.push({ id: 'ext', builtin: true, title: t('tab.ext'), icon: null, order: -20, badge: null })
+          out.push({ id: 'ws', builtin: true, title: t('tab.ws'), icon: null, order: -10, badge: null })
+        }
+        for (var i = 0; i < tabRecords.length; i++) {
+          var record = tabRecords[i]
+          if (record.hidden === true) continue
+          out.push({
+            id: record.id,
+            builtin: false,
+            title: tabTitle(record),
+            icon: record.icon,
+            order: record.order,
+            seq: record.seq,
+            badge: record.badge,
+          })
+        }
+        out.sort(function (left, right) {
+          if (left.builtin !== right.builtin) return left.builtin ? -1 : 1
+          if (left.order !== right.order) return left.order - right.order
+          return (left.seq || 0) - (right.seq || 0)
+        })
+        return out
+      }
+
+      function ensureTabStrip(fx) {
+        var strip = runtime.tabStrip
+        if (strip && strip.parentNode !== fx.root) {
+          try {
+            strip.parentNode.removeChild(strip)
+          } catch (error) {
+            void error
+          }
+          strip = null
+        }
+        if (!strip) {
+          strip = document.createElement('div')
+          strip.setAttribute('data-dsbs-tabs', '')
+          strip.setAttribute('role', 'tablist')
+          strip.setAttribute('aria-label', t('tabs.label'))
+          runtime.tabStrip = strip
+        }
+        // Sits under the control bar so the two read as one header. The
+        // anchor matters: the host rebuilds the groups, never the bar.
+        if (strip.parentNode === fx.root && runtime.bar && strip.previousSibling === runtime.bar) return strip
+        var anchor = runtime.bar ? runtime.bar.nextSibling : (fx.nav || fx.regionArea)
+        if (anchor && anchor.parentNode === fx.root && anchor !== strip) fx.root.insertBefore(strip, anchor)
+        else if (strip.parentNode !== fx.root) fx.root.appendChild(strip)
+        return strip
+      }
+
+      function buildTabButton(entry, selected) {
+        var button = document.createElement('button')
+        button.setAttribute('type', 'button')
+        button.setAttribute('data-dsbs-tabid', entry.id)
+        button.setAttribute('role', 'tab')
+        button.setAttribute('aria-selected', selected ? 'true' : 'false')
+        button.setAttribute('title', entry.title)
+        if (selected) button.setAttribute('data-dsbs-selected', 'true')
+        if (entry.builtin) button.setAttribute('data-dsbs-builtin', entry.id)
+
+        if (typeof entry.icon === 'string' && entry.icon) {
+          var glyph = document.createElement('span')
+          glyph.setAttribute('data-dsbs-tabicon', '')
+          glyph.setAttribute('aria-hidden', 'true')
+          button.setAttribute('data-dsbs-hasicon', '')
+          if (entry.icon.charAt(0) === '<') {
+            // A consumer-supplied mark. Plugins already run arbitrary code in
+            // this page, so this grants nothing new -- but the icon still gets
+            // its own element so the label stays a text node.
+            glyph.innerHTML = entry.icon
+          } else {
+            glyph.textContent = entry.icon
+            glyph.setAttribute('data-dsbs-tabicon-text', '')
+          }
+          button.appendChild(glyph)
+        }
+
+        var label = document.createElement('span')
+        label.setAttribute('data-dsbs-tablabel', '')
+        label.textContent = entry.title
+        button.appendChild(label)
+
+        if (entry.badge != null && entry.badge !== '') {
+          var badge = document.createElement('span')
+          badge.setAttribute('data-dsbs-tabbadge', '')
+          badge.textContent = String(entry.badge)
+          button.appendChild(badge)
+        }
+
+        button.addEventListener('click', function () {
+          if (entry.builtin) {
+            // Built-ins drive the existing group switcher, so a click keeps
+            // meaning what the same click meant before 0.3.0.
+            var tookOver = runtime.activeTab !== null
+            runtime.activeTab = null
+            writeActiveTab(null)
+            setField('tab', entry.id)
+            // A click here takes the column away from a consumer tab exactly
+            // like clicking another tab does, so subscribers hear about it the
+            // same way. Without this a consumer that trusts `subscribe` would
+            // keep believing it is still on screen.
+            if (tookOver) notifyTabs('active')
+          } else {
+            activateTab(entry.id)
+          }
+        })
+        return button
+      }
+
+      function renderTabStrip() {
+        var strip = runtime.tabStrip
+        if (!strip) return
+        var entries = tabEntries()
+        var hasPlugin = false
+        for (var p = 0; p < entries.length; p++) {
+          if (!entries[p].builtin) hasPlugin = true
+        }
+        // Nothing registered: stay out of the way entirely, so a profile with
+        // no tab consumers looks exactly like 0.2.x.
+        if (!hasPlugin) {
+          strip.setAttribute('hidden', '')
+          runtime.tabSignature = ''
+          return
+        }
+        strip.removeAttribute('hidden')
+
+        var activePlugin = runtime.activeTab && findTab(runtime.activeTab) ? runtime.activeTab : null
+        var signature = (activePlugin || '-') + '|' + config.values.mode + '|' + config.values.tab + '|'
+        for (var s = 0; s < entries.length; s++) {
+          signature += entries[s].id + ':' + entries[s].title + ':' + entries[s].icon + ':' + entries[s].badge + ';'
+        }
+        if (signature === runtime.tabSignature) return
+        runtime.tabSignature = signature
+
+        while (strip.firstChild) strip.removeChild(strip.firstChild)
+        for (var i = 0; i < entries.length; i++) {
+          var entry = entries[i]
+          var selected = entry.builtin
+            ? (!activePlugin && config.values.tab === entry.id)
+            : (activePlugin === entry.id)
+          strip.appendChild(buildTabButton(entry, selected))
+        }
+      }
+
+      function placeTabPanel(panel, fx) {
+        if (panel.parentNode === fx.root) return
+        var anchor = fx.nav || fx.regionArea
+        if (anchor && anchor.parentNode === fx.root) fx.root.insertBefore(panel, anchor)
+        else fx.root.appendChild(panel)
+      }
+
+      function syncTabPanels(fx, activeId) {
+        var i
+        // The container is created the first time its tab owns the column, not
+        // at registration: a tab that is never opened should cost nothing, and
+        // a display:none container has no geometry to measure anyway.
+        if (activeId && !runtime.tabPanels[activeId]) {
+          var owning = findTab(activeId)
+          if (owning) createTabPanel(owning)
+        }
+        // Panels that are no longer registered are gone already; the ones that
+        // remain are shown only while they own the column.
+        for (var id in runtime.tabPanels) {
+          var entry = runtime.tabPanels[id]
+          if (!entry || !entry.el) continue
+          if (id === activeId) {
+            placeTabPanel(entry.el, fx)
+            entry.el.setAttribute('data-dsbs-visible', 'true')
+            entry.el.removeAttribute('aria-hidden')
+            if (!entry.mounted) mountTabPanel(entry)
+          } else {
+            entry.el.setAttribute('data-dsbs-visible', 'false')
+            entry.el.setAttribute('aria-hidden', 'true')
+          }
+        }
+        void i
+      }
+
+      function activateTab(id) {
+        if (id != null && id !== '' && !findTab(id)) return false
+        var next = id == null || id === '' ? null : String(id)
+        // Clicking the tab that already owns the column returns to the groups,
+        // which is the only way back out of a tab in layouts a and c.
+        if (next && runtime.activeTab === next) next = null
+        runtime.activeTab = next
+        writeActiveTab(next)
+        notifyTabs('active')
+        scheduleSync()
+        return true
+      }
+
       function barButton(key) {
         if (key === 'temp') return tempButton
         if (!runtime.bar) return null
@@ -1271,6 +1837,8 @@ window.__ModuleLoader__.load({
 
         if (fx.nav && !fx.nav.hasAttribute('data-dsbs-ext')) fx.nav.setAttribute('data-dsbs-ext', '')
         ensureBar(fx)
+        ensureTabStrip(fx)
+        renderTabStrip()
         placeTempButton()
         applyTempButtonVisibility()
         loadTempStatus()
@@ -1339,7 +1907,28 @@ window.__ModuleLoader__.load({
 
         var extHidden
         var wsHidden
-        if (state.mode === 'a') {
+        // A registered tab owning the column outranks every layout rule: the
+        // two groups step aside and the tab's own container takes the space.
+        var pluginTab = null
+        if (runtime.activeTab) {
+          if (findTab(runtime.activeTab)) {
+            pluginTab = runtime.activeTab
+          } else if (runtime.seenTabs[runtime.activeTab]) {
+            // It registered once and is gone now: its owner unloaded while the
+            // page was open. Fall back instead of leaving an empty column with
+            // no way out of it.
+            runtime.activeTab = null
+            writeActiveTab(null)
+            notifyTabs('orphan')
+          }
+          // Not seen yet: another plugin may still be registering during
+          // startup, so the stored id is kept and retried on the next paint.
+        }
+        setFlag(html, 'data-dsbs-ptab', !!pluginTab)
+        if (pluginTab) {
+          extHidden = true
+          wsHidden = true
+        } else if (state.mode === 'a') {
           extHidden = state.foldExt === true
           wsHidden = state.foldWs === true
         } else if (state.mode === 'b') {
@@ -1352,6 +1941,13 @@ window.__ModuleLoader__.load({
         }
         setGroupHidden(fx.nav, 'ext', extHidden)
         setGroupHidden(fx.regionArea, 'ws', wsHidden)
+        syncTabPanels(fx, pluginTab)
+        // The strip is the only affordance that survives a hidden bar, so it
+        // is repainted on every sync rather than only when its content changed.
+        if (runtime.tabStrip && pluginTab) {
+          var selectedTab = runtime.tabStrip.querySelector('[data-dsbs-tabid="' + pluginTab + '"]')
+          if (selectedTab) selectedTab.setAttribute('aria-selected', 'true')
+        }
 
         observeRoot(fx.root)
         positionPop(fx)
@@ -2500,11 +3096,35 @@ window.__ModuleLoader__.load({
           } catch (error) {
             void error
           }
+          try {
+            // Unmount every live tab first: a consumer's disposer may still
+            // touch its container, so removing the DOM afterwards is safer
+            // than yanking it out from under a cleanup callback.
+            disposeAllTabPanels()
+            if (runtime.tabStrip && runtime.tabStrip.parentNode) runtime.tabStrip.parentNode.removeChild(runtime.tabStrip)
+          } catch (error) {
+            void error
+          }
+          try {
+            runtime.tabStrip = null
+            runtime.tabSignature = ''
+            tabListeners.length = 0
+            tabRecords.length = 0
+          } catch (error) {
+            void error
+          }
           try {
             if (window[OWNER_KEY] === owner) delete window[OWNER_KEY]
           } catch (error) {
             void error
           }
+          try {
+            // Only drop the handle if it is still ours: a newer generation may
+            // already have replaced it, and that one must keep working.
+            if (window.__dshSidebarSuite === sidebarService) delete window.__dshSidebarSuite
+          } catch (error) {
+            void error
+          }
           try {
             if (runtime.root) runtime.root.style.removeProperty('--dsbs-pop-top')
           } catch (error) {
@@ -2538,6 +3158,7 @@ window.__ModuleLoader__.load({
             'data-dsbs-narrow',
             'data-dsbs-temp-solo',
             'data-dsbs-temp-style',
+            'data-dsbs-ptab',
           ]
           for (var i = 0; i < attributes.length; i++) {
             html.removeAttribute(attributes[i])
@@ -2564,7 +3185,6 @@ window.__ModuleLoader__.load({
       }, 'sidebar-suite: teardown')
       owner.teardown = teardown
     }
-
     return { inject: ['locale'], apply: apply }
   },
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-sidebar-suite",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "license": "MIT",
   "author": "Yonan",
   "repository": {
@@ -27,7 +27,7 @@
   ],
   "type": "module",
   "scripts": {
-    "test": "node tests/test_020.mjs && node tests/test_022.mjs && node tests/test_023.mjs && node tests/test_024.mjs && node tests/test_025.mjs && node tests/test_028.mjs && node tests/test_029.mjs",
+    "test": "node tests/test_020.mjs && node tests/test_022.mjs && node tests/test_023.mjs && node tests/test_024.mjs && node tests/test_025.mjs && node tests/test_028.mjs && node tests/test_029.mjs && node tests/test_030.mjs && node tests/test_031.mjs",
     "check": "node --check lib/index.js && node --check lib/client.js && node --check lib/temp-session-host.mjs && npm pack --dry-run"
   },
   "main": "lib/index.js",

package//344/275/277/347/224/250/350/257/264/346/230/216.md

@@ -117,6 +117,29 @@
 
 ---
 
+### 3.4 第三方插件加的页签（0.3.0）
+
+这一版给**别的插件**开了一个口：它们可以往你侧栏里加自己的一页。
+
+你不需要做任何设置。什么时候会看到：
+
+- 装了某个使用这个接口的插件之后，**控制栏下面会多出一排页签**，比如 `扩展 │ 工作区 │ 那个插件的名字`。
+- 点哪个，侧栏中间那块就换成哪一页。
+- **再点一次当前页签**，就退回原来的会话列表 / 扩展列表。
+- 你在哪一页会被记住，下次打开还在那一页。
+
+三种布局下的差别：
+
+| 你选的布局 | 页签条长什么样 |
+|---|---|
+| 标签页（默认） | `扩展 / 工作区 / 插件页` 三种并排 |
+| 折叠 | 只有插件页进条；扩展和工作区还是用原来那两个折叠按钮 |
+| 浮层 | 只有插件页进条；扩展还是用「浮出面板」按钮 |
+
+**一个都没装的话，这排页签根本不会出现** —— 界面和 0.2.x 一模一样，不会平白多一行东西。
+
+> 想自己写一个？接口是 `ctx.sidebarSuite.registerTab({ id, title, icon, mount })`，`mount` 拿到一个空容器，你爱画什么画什么。完整示例在 README 和 DETAIL 里。
+
 ## 四、临时会话（重点）
 
 ### 4.1 它到底是什么