From 5dee9fa153a2fced011876eddf2b188bcbe54b1c Mon Sep 17 00:00:00 2001
From: klarkxy <278370456@qq.com>
Date: Sat, 21 Nov 2026 13:56:17 +0800
Subject: [PATCH 1/3] Cascade snapshot 2026-11-21T05:56:17.198Z
From ba09e7bca5eb95faecca17ce2557f30b239915c2 Mon Sep 17 00:00:00 2001
From: klarkxy <278370456@qq.com>
Date: Sat, 21 Nov 2026 16:52:03 +0800
Subject: [PATCH 2/3] Sidebar Layout: switch the right sidebar between push,
drawer and body
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
New client-only plugin @klarkxy/dsh-sidebar-layout. It tags the host
AppFrame and its centre column with plugin-owned attributes (a tagged
node instead of a :has() selector — better-sidebar documents the restyle
cost during streaming), and one injected stylesheet drives the layouts:
- drawer: centre spans the right track so the panel overlays a
conversation that keeps full width; an ::after mask dims it and a
click on the mask collapses the panel via ctx.sidebarRight.
- swap ("正文"): the columns trade grid positions — the panel fills the
centre as the body, the conversation becomes the right column, and
the host's drag handle resizes the conversation. Windows/macOS chrome
radii and macOS leading clearance follow the surfaces.
Mode persists browser-local (localStorage) and is shared by three
entry points: a header utilities menu, a Settings > General row
(id sidebar-layout/40), and the sidebar.layout.cycle command bound to
primary+alt+shift+B on every admissible profile. Fullscreen and the
<768px auto-fullscreen are excluded everywhere. Compatible with
dsh-better-sidebar's native tabs and centre-column rules.
Generated with [Devin](https://devin.ai)
Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
README.en.md | 1 +
README.md | 1 +
plugins/AGENTS.md | 1 +
plugins/dsh-sidebar-layout/LICENSE | 42 ++
plugins/dsh-sidebar-layout/README.en.md | 36 ++
plugins/dsh-sidebar-layout/README.md | 36 ++
plugins/dsh-sidebar-layout/cordis.patch.yml | 5 +
plugins/dsh-sidebar-layout/icon.svg | 13 +
plugins/dsh-sidebar-layout/locale/en.json | 6 +
plugins/dsh-sidebar-layout/locale/zh.json | 6 +
plugins/dsh-sidebar-layout/package.json | 129 +++++
.../dsh-sidebar-layout/src/client.spec.tsx | 334 +++++++++++++
plugins/dsh-sidebar-layout/src/client.tsx | 463 ++++++++++++++++++
.../dsh-sidebar-layout/src/contracts.spec.ts | 91 ++++
plugins/dsh-sidebar-layout/src/contracts.ts | 121 +++++
plugins/dsh-sidebar-layout/src/index.ts | 18 +
plugins/dsh-sidebar-layout/tsconfig.json | 16 +
plugins/dsh-sidebar-layout/tsdown.config.ts | 15 +
pnpm-lock.yaml | 45 ++
scripts/editor-plugins/boundaries.spec.mjs | 3 +-
scripts/editor-plugins/ui-primitives-stub.tsx | 3 +-
scripts/editor-plugins/ui-scope.spec.mjs | 1 +
scripts/plugin-release-states.json | 8 +
23 files changed, 1392 insertions(+), 2 deletions(-)
create mode 100644 plugins/dsh-sidebar-layout/LICENSE
create mode 100644 plugins/dsh-sidebar-layout/README.en.md
create mode 100644 plugins/dsh-sidebar-layout/README.md
create mode 100644 plugins/dsh-sidebar-layout/cordis.patch.yml
create mode 100644 plugins/dsh-sidebar-layout/icon.svg
create mode 100644 plugins/dsh-sidebar-layout/locale/en.json
create mode 100644 plugins/dsh-sidebar-layout/locale/zh.json
create mode 100644 plugins/dsh-sidebar-layout/package.json
create mode 100644 plugins/dsh-sidebar-layout/src/client.spec.tsx
create mode 100644 plugins/dsh-sidebar-layout/src/client.tsx
create mode 100644 plugins/dsh-sidebar-layout/src/contracts.spec.ts
create mode 100644 plugins/dsh-sidebar-layout/src/contracts.ts
create mode 100644 plugins/dsh-sidebar-layout/src/index.ts
create mode 100644 plugins/dsh-sidebar-layout/tsconfig.json
create mode 100644 plugins/dsh-sidebar-layout/tsdown.config.ts
diff --git a/README.en.md b/README.en.md
index 43d31a90..e7244abd 100644
--- a/README.en.md
+++ b/README.en.md
@@ -78,6 +78,7 @@ The code is the developer documentation. Releases follow the [release guide](REL
| [@klarkxy/dsh-secret-manager](plugins/dsh-secret-manager/README.en.md) | Published (`published`) | Published on npm; subsequent versions follow the normal update workflow. |
| [@klarkxy/dsh-session-manager](plugins/dsh-session-manager/README.en.md) | Published (`published`) | Published on npm; fixes, testing and version updates keep the Published lifecycle. |
| [@klarkxy/dsh-shortcuts](plugins/dsh-shortcuts/README.en.md) | Draft (`draft`) | New shortcut manager and extensible command palette; awaiting first-release acceptance. |
+| [@klarkxy/dsh-sidebar-layout](plugins/dsh-sidebar-layout/README.en.md) | Draft (`draft`) | New right-sidebar layout switcher (push, drawer, body); awaiting first-release acceptance. |
| [@klarkxy/dsh-unrestricted](plugins/dsh-unrestricted/README.en.md) | Published (`published`) | Published on npm; fixes, testing and version updates keep the Published lifecycle. |
| [@klarkxy/dsh-update](plugins/dsh-update/README.en.md) | Published (`published`) | Published on npm; subsequent versions follow the normal update workflow. |
| [@klarkxy/dsh-web-search-manager](plugins/dsh-web-search-manager/README.en.md) | Published (`published`) | Published on npm; fixes, testing and version updates keep the Published lifecycle. |
diff --git a/README.md b/README.md
index 2a13cdc4..74eeb404 100644
--- a/README.md
+++ b/README.md
@@ -78,6 +78,7 @@ pnpm check
| [@klarkxy/dsh-secret-manager](plugins/dsh-secret-manager/README.md) | 已发布 (`published`) | 已有 npm 发布记录;后续版本按正常更新流程维护。 |
| [@klarkxy/dsh-session-manager](plugins/dsh-session-manager/README.md) | 已发布 (`published`) | 已有 npm 发布记录;后续修复、测试和版本更新保持已发布。 |
| [@klarkxy/dsh-shortcuts](plugins/dsh-shortcuts/README.md) | 草稿 (`draft`) | 新增快捷键管理与可扩展命令面板,待完成首次发布验收。 |
+| [@klarkxy/dsh-sidebar-layout](plugins/dsh-sidebar-layout/README.md) | 草稿 (`draft`) | 新增右侧边栏布局切换(常规、抽屉、正文),待完成首次发布验收。 |
| [@klarkxy/dsh-unrestricted](plugins/dsh-unrestricted/README.md) | 已发布 (`published`) | 已有 npm 发布记录;后续修复、测试和版本更新保持已发布。 |
| [@klarkxy/dsh-update](plugins/dsh-update/README.md) | 已发布 (`published`) | 已有 npm 发布记录;后续版本按正常更新流程维护。 |
| [@klarkxy/dsh-web-search-manager](plugins/dsh-web-search-manager/README.md) | 已发布 (`published`) | 已有 npm 发布记录;后续修复、测试和版本更新保持已发布。 |
diff --git a/plugins/AGENTS.md b/plugins/AGENTS.md
index dc9c2b7f..0cea13d6 100644
--- a/plugins/AGENTS.md
+++ b/plugins/AGENTS.md
@@ -39,6 +39,7 @@
| 席位 | id / order |
| --- | --- |
+| `settings.general.item` | `sidebar-layout`/40 |
| `settings.models.footer` | `magpie`/100 |
| `settings.section` | `font`/5 |
| 共享栏目「会话管理」 | `auxiliary-model`/55、`session-manager.composer`/60、`session-manager.auto-continue`/62、`session-manager.return`/64、`session-manager.handoff`/66、`session-manager.agent-actions`/68、`current-title`/70、`safe-auto`/80 |
diff --git a/plugins/dsh-sidebar-layout/LICENSE b/plugins/dsh-sidebar-layout/LICENSE
new file mode 100644
index 00000000..abc9aeef
--- /dev/null
+++ b/plugins/dsh-sidebar-layout/LICENSE
@@ -0,0 +1,42 @@
+ The Star And Thank Author License (SATA)
+ Version 2.1, September 2026
+
+Copyright © 2026 Klarkxy(278370456@qq.com)
+
+Project Url: https://github.com/klarkxy/dsh-editor
+ https://github.com/klarkxy/sata-license
+ https://github.com/klarkxy/dsh-plugins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+And wait, one more thing — an invitation, not a condition: it would be best if
+you star/+1/like the project(s) in the project url section above, and thank the
+author(s) in the Copyright section. You may, and arguably you should — but the
+permissions above hold either way, star or no star.
+
+Here are some suggested ways:
+
+ - Email the authors a thank-you letter, and make friends with him/her/them.
+ - Report bugs or issues.
+ - Tell friends what a wonderful project this is.
+ - And, sure, you can just express thanks in your mind without telling the world.
+
+Contributors of this project by forking have the option to add his/her name and
+forked project url at copyright and project url sections, but shall not delete
+or modify anything else in these two sections.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
diff --git a/plugins/dsh-sidebar-layout/README.en.md b/plugins/dsh-sidebar-layout/README.en.md
new file mode 100644
index 00000000..82b13a96
--- /dev/null
+++ b/plugins/dsh-sidebar-layout/README.en.md
@@ -0,0 +1,36 @@
+# Sidebar Layout
+
+
+
+[简体中文](README.md) / English
+
+Switch the DeepSeek Harness right Sidebar between three presentations:
+
+- **Push**: the native default — the open panel squeezes the conversation column.
+- **Drawer**: the panel floats over the conversation, which keeps its full width; a dim mask covers the conversation while the panel is open, and clicking the mask closes the panel.
+- **Body**: the panel moves into the centre column as the main body and the conversation moves to the right (IDE style); the host's right-edge drag handle then resizes the conversation column.
+
+## Install
+
+```sh
+dsh plugin --profile web add @klarkxy/dsh-sidebar-layout
+```
+
+Replace `web` with your profile name and restart the profile when DSH asks. The plugin is enabled after installation and can be turned off in the plugin list.
+
+## Use
+
+The layout is a global setting; all three entry points drive the same state:
+
+- **Session header button**: the “Sidebar layout” icon in the session header's utility strip opens a menu with Push / Drawer / Body; the active mode is checked. Choosing Drawer or Body while the panel is collapsed expands it.
+- **Settings row**: the “Sidebar layout” row under Settings → General offers the same three options in a select.
+- **Shortcut**: `Ctrl/Cmd + Alt + Shift + B` cycles Push → Drawer → Body → Push (the web build on Linux ships no default binding — assign one in the Shortcuts settings).
+
+The choice is stored in the current browser and restored on the next visit.
+
+## Limitations
+
+- The panel's fullscreen mode is untouched and keeps native host behaviour in all three layouts.
+- The host still auto-collapses the panel when there is not enough room for a normal-width track — in drawer mode too.
+- The plugin works alongside `dsh-better-sidebar`; neither affects the other.
+- Disabling or uninstalling the plugin returns the sidebar to the native Push behaviour.
diff --git a/plugins/dsh-sidebar-layout/README.md b/plugins/dsh-sidebar-layout/README.md
new file mode 100644
index 00000000..eb021138
--- /dev/null
+++ b/plugins/dsh-sidebar-layout/README.md
@@ -0,0 +1,36 @@
+# 侧栏布局
+
+
+
+简体中文 / [English](README.en.md)
+
+让 DeepSeek Harness 的右侧边栏在三种呈现方式之间切换:
+
+- **常规**:宿主默认行为,展开面板时挤压对话区域。
+- **抽屉**:面板悬浮覆盖在对话之上,对话保持完整宽度;面板打开时对话区域出现一层遮罩,点击遮罩即可收起面板。
+- **正文**:面板移入中间列作为正文,对话移到右侧(IDE 式布局),原有的右侧拖拽手柄此时调整的是对话列的宽度。
+
+## 安装
+
+```sh
+dsh plugin --profile web add @klarkxy/dsh-sidebar-layout
+```
+
+把 `web` 换成你的 profile 名,DSH 提示时重启 profile。安装后默认启用,可在插件列表中关闭。
+
+## 使用
+
+布局是全局设置,三处入口改的是同一份状态:
+
+- **会话头部按钮**:会话头部右侧工具条上的「侧栏布局」图标按钮,点击弹出菜单选择常规 / 抽屉 / 正文,当前方式有勾选标记。选择抽屉或正文时若面板处于收起状态会自动展开。
+- **设置项**:「设置 → 通用」中的「侧栏布局」一行,下拉选择同一种方式。
+- **快捷键**:`Ctrl/Cmd + Alt + Shift + B` 按「常规 → 抽屉 → 正文 → 常规」循环切换(网页版 Linux 不预置该快捷键,可在快捷键设置中自行绑定)。
+
+选择会被保存在当前浏览器中,重新打开时恢复。
+
+## 主要限制
+
+- 面板的全屏模式不受本插件影响,三种布局下都保持宿主原样。
+- 宿主在空间不足以容纳正常宽度的面板轨道时仍会自动收起面板,抽屉模式下同样如此。
+- 本插件与 `dsh-better-sidebar` 可以同时使用,互不影响。
+- 停用或卸载本插件后,侧栏恢复宿主默认的「常规」行为。
diff --git a/plugins/dsh-sidebar-layout/cordis.patch.yml b/plugins/dsh-sidebar-layout/cordis.patch.yml
new file mode 100644
index 00000000..dd158ebb
--- /dev/null
+++ b/plugins/dsh-sidebar-layout/cordis.patch.yml
@@ -0,0 +1,5 @@
+# Enabled when installed. Purely additive; touches no built-in row.
+- insert:
+ - id: sidebar-layout
+ name: '@klarkxy/dsh-sidebar-layout'
+ disabled: false
diff --git a/plugins/dsh-sidebar-layout/icon.svg b/plugins/dsh-sidebar-layout/icon.svg
new file mode 100644
index 00000000..b1092c71
--- /dev/null
+++ b/plugins/dsh-sidebar-layout/icon.svg
@@ -0,0 +1,13 @@
+
diff --git a/plugins/dsh-sidebar-layout/locale/en.json b/plugins/dsh-sidebar-layout/locale/en.json
new file mode 100644
index 00000000..a924af87
--- /dev/null
+++ b/plugins/dsh-sidebar-layout/locale/en.json
@@ -0,0 +1,6 @@
+{
+ "meta": {
+ "title": "Sidebar Layout",
+ "description": "Switch the right Sidebar between push, drawer overlay and body-swap layouts."
+ }
+}
diff --git a/plugins/dsh-sidebar-layout/locale/zh.json b/plugins/dsh-sidebar-layout/locale/zh.json
new file mode 100644
index 00000000..78b4b049
--- /dev/null
+++ b/plugins/dsh-sidebar-layout/locale/zh.json
@@ -0,0 +1,6 @@
+{
+ "meta": {
+ "title": "侧栏布局",
+ "description": "切换右侧边栏的呈现方式:常规挤压、抽屉覆盖与正文互换三种布局。"
+ }
+}
diff --git a/plugins/dsh-sidebar-layout/package.json b/plugins/dsh-sidebar-layout/package.json
new file mode 100644
index 00000000..9d9ba420
--- /dev/null
+++ b/plugins/dsh-sidebar-layout/package.json
@@ -0,0 +1,129 @@
+{
+ "name": "@klarkxy/dsh-sidebar-layout",
+ "version": "0.1.0",
+ "description": "Sidebar Layout: switch the right Sidebar between push, drawer overlay and body-swap layouts in the DeepSeek Harness Web GUI.",
+ "icon": "./icon.svg",
+ "license": "SEE LICENSE IN LICENSE",
+ "type": "module",
+ "engines": {
+ "node": ">=22",
+ "dsh": ">=0.2.2-rc.5"
+ },
+ "main": "./lib/index.js",
+ "types": "./lib/index.d.ts",
+ "exports": {
+ ".": {
+ "types": "./lib/index.d.ts",
+ "import": "./lib/index.js",
+ "default": "./lib/index.js"
+ },
+ "./contracts": {
+ "types": "./lib/contracts.d.ts",
+ "import": "./lib/contracts.js",
+ "default": "./lib/contracts.js"
+ },
+ "./client": {
+ "default": "./lib/client.js"
+ },
+ "./package.json": "./package.json",
+ "./locale/*.json": "./locale/*.json"
+ },
+ "files": [
+ "icon.svg",
+ "locale/*.json",
+ "lib",
+ "cordis.patch.yml",
+ "README.md",
+ "README.en.md",
+ "LICENSE"
+ ],
+ "dsh": {
+ "bundle": {
+ "patch": "./cordis.patch.yml"
+ },
+ "client": {
+ "platform": "web",
+ "inject": [
+ "@deepseek-ai/dsh-client-locale",
+ "@deepseek-ai/dsh-client-ui-slots",
+ "@deepseek-ai/dsh-client-ui-layout",
+ "@deepseek-ai/dsh-client-ui-sidebar-right",
+ "@deepseek-ai/dsh-client-shortcuts",
+ "@deepseek-ai/dsh-client-ui-primitives"
+ ]
+ }
+ },
+ "scripts": {
+ "build": "tsdown && node ../../scripts/editor-plugins/wrap-client.mjs @klarkxy/dsh-sidebar-layout",
+ "typecheck": "tsc --noEmit -p tsconfig.json",
+ "test": "vitest run --root ../.. --config vitest.editor-plugins.config.ts --maxWorkers=2 plugins/dsh-sidebar-layout/src"
+ },
+ "peerDependencies": {
+ "@deepseek-ai/cordis": ">=4.0.4",
+ "@deepseek-ai/dsh-client-shortcuts": ">=0.2.2-rc.5",
+ "@deepseek-ai/dsh-client-locale": ">=0.2.2-rc.5",
+ "@deepseek-ai/dsh-client-ui-layout": ">=0.2.2-rc.5",
+ "@deepseek-ai/dsh-client-ui-sidebar-right": ">=0.2.2-rc.5",
+ "@deepseek-ai/dsh-client-ui-slots": ">=0.2.2-rc.5"
+ },
+ "devDependencies": {
+ "@klarkxy/dsh-plugin-kit": "workspace:*",
+ "@deepseek-ai/cordis": "4.1.0",
+ "@deepseek-ai/dsh-client-shortcuts": "0.2.2-rc.5",
+ "@deepseek-ai/dsh-client-locale": "0.2.2-rc.5",
+ "@deepseek-ai/dsh-client-ui-layout": "0.2.2-rc.5",
+ "@deepseek-ai/dsh-client-ui-sidebar-right": "0.2.2-rc.5",
+ "@deepseek-ai/dsh-client-ui-slots": "0.2.2-rc.5",
+ "@deepseek-ai/dsh-client-ui-primitives": "0.2.2-rc.5",
+ "react": "^18.2.0",
+ "@types/react": "18.3.31",
+ "react-dom": "^18.2.0",
+ "@types/react-dom": "^18.3.1",
+ "jsdom": "29.1.1",
+ "@types/jsdom": "28.0.3"
+ },
+ "keywords": [
+ "dsh",
+ "dsh-plugin",
+ "dsh-plugins",
+ "deepseek-harness",
+ "deepseek-harness-plugin",
+ "drawer",
+ "layout",
+ "sidebar",
+ "ui-customization"
+ ],
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/klarkxy/dsh-plugins.git",
+ "directory": "plugins/dsh-sidebar-layout"
+ },
+ "bugs": {
+ "url": "https://github.com/klarkxy/dsh-plugins/issues"
+ },
+ "publishConfig": {
+ "access": "public",
+ "registry": "https://registry.npmjs.org/"
+ },
+ "homepage": "https://klarkxy.github.io/dsh-plugins/plugins/sidebar-layout/",
+ "peerDependenciesMeta": {
+ "@deepseek-ai/cordis": {
+ "optional": true
+ },
+ "@deepseek-ai/dsh-client-shortcuts": {
+ "optional": true
+ },
+ "@deepseek-ai/dsh-client-locale": {
+ "optional": true
+ },
+ "@deepseek-ai/dsh-client-ui-layout": {
+ "optional": true
+ },
+ "@deepseek-ai/dsh-client-ui-sidebar-right": {
+ "optional": true
+ },
+ "@deepseek-ai/dsh-client-ui-slots": {
+ "optional": true
+ }
+ }
+}
diff --git a/plugins/dsh-sidebar-layout/src/client.spec.tsx b/plugins/dsh-sidebar-layout/src/client.spec.tsx
new file mode 100644
index 00000000..1cc1b925
--- /dev/null
+++ b/plugins/dsh-sidebar-layout/src/client.spec.tsx
@@ -0,0 +1,334 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { JSDOM } from 'jsdom'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { OFFICIAL_THEME_TOKEN_NAMES } from '@klarkxy/dsh-plugin-kit/official-ui'
+import {
+ CENTER_ATTRIBUTE, FRAME_ATTRIBUTE, PLUGIN_NAME, STORAGE_KEY,
+ type SidebarLayoutMode,
+} from './contracts.ts'
+import {
+ SidebarLayoutAction, SidebarLayoutRow, apply, inject, sidebarLayoutStyles,
+} from './client.tsx'
+
+/* Host-published variables the layout rules legitimately consume: the mask's
+ * host transition tokens, the Windows-caption radius and macOS leading
+ * clearance the swap mode mirrors, and plugin-kit's code-font token. */
+const HOST_PUBLISHED_VARS = new Set([
+ '--ds-ease-in-out',
+ '--ds-font-family-code',
+ '--ds-transition-duration-slow',
+ '--dsh-dockkit-strip-inline-start',
+ '--dsh-frame-leading-clearance',
+ '--dsh-windows-content-radius',
+])
+
+const FRAME_HTML = `
+
+`
+
+function mountClient(options: {
+ html?: string
+ locale?: string
+ storage?: Record
+ sidebarRight?: { isExpanded(): boolean; toggleExpanded(): void }
+ shortcuts?: { catalog: { getSnapshot(): readonly unknown[]; subscribe(fn: () => void): () => void }; register(command: unknown): () => void }
+} = {}) {
+ const dom = new JSDOM(options.html ?? FRAME_HTML, { url: 'https://local.test/', pretendToBeVisual: true })
+ vi.stubGlobal('window', dom.window)
+ vi.stubGlobal('document', dom.window.document)
+ vi.stubGlobal('localStorage', dom.window.localStorage)
+ vi.stubGlobal('requestAnimationFrame', dom.window.requestAnimationFrame?.bind(dom.window))
+ vi.stubGlobal('cancelAnimationFrame', dom.window.cancelAnimationFrame?.bind(dom.window))
+ vi.stubGlobal('MutationObserver', dom.window.MutationObserver)
+ for (const [key, value] of Object.entries(options.storage ?? {})) dom.window.localStorage.setItem(key, value)
+ const effects: Array<{ label?: string; dispose: (() => void) | void }> = []
+ const injected: string[] = []
+ const registrations: Array<{ spec: Record; render: unknown }> = []
+ const registeredCommands: Array> = []
+ const context = {
+ effect(run: () => (() => void) | void, label?: string) {
+ effects.push({ label, dispose: run() })
+ },
+ slots: {
+ inject(key: string, callback: () => unknown) { injected.push(key); callback(); return () => {} },
+ register(spec: Record, render: unknown) { registrations.push({ spec, render }); return () => {} },
+ },
+ locale: {
+ getSnapshot: () => ({ active: options.locale ?? 'zh-CN' }),
+ subscribe: () => () => {},
+ register: () => () => {},
+ },
+ layout: {},
+ sidebarRight: options.sidebarRight ?? { isExpanded: () => false, toggleExpanded: vi.fn() },
+ shortcuts: options.shortcuts ?? {
+ catalog: { getSnapshot: () => [], subscribe: () => () => {} },
+ register(command: Record) { registeredCommands.push(command); return () => {} },
+ },
+ }
+ apply(context as never)
+ const disposeAll = () => { for (const effect of [...effects].reverse()) effect.dispose?.() }
+ return {
+ dom, effects, injected, registrations, registeredCommands, disposeAll,
+ selectMode: (mode: SidebarLayoutMode) => {
+ const injectFace = (registrations[0].spec.inject as () => { selectMode: (mode: SidebarLayoutMode) => void })()
+ injectFace.selectMode(mode)
+ },
+ storeMode: () => dom.window.localStorage.getItem(STORAGE_KEY) ?? 'push',
+ }
+}
+
+afterEach(() => vi.unstubAllGlobals())
+
+describe('sidebar layout client contract', () => {
+ it('injects exactly the services it consumes', () => {
+ expect([...inject]).toEqual(['slots', 'locale', 'layout', 'sidebarRight', 'shortcuts'])
+ })
+
+ it('keeps every referenced colour/radius token on the official whitelist', () => {
+ const tokens = new Set()
+ for (const match of sidebarLayoutStyles.matchAll(/var\((--[\w-]+)/g)) tokens.add(match[1])
+ const whitelist = new Set(OFFICIAL_THEME_TOKEN_NAMES)
+ const offenders = [...tokens].filter(name => !whitelist.has(name) && !HOST_PUBLISHED_VARS.has(name))
+ expect(offenders).toEqual([])
+ })
+
+ it('mounts one owned stylesheet and removes it with the effects', () => {
+ const { dom, disposeAll } = mountClient()
+ const style = dom.window.document.head.querySelector(`style[data-plugin="${PLUGIN_NAME}"]`)
+ expect(style?.textContent).toContain("[data-dsh-sidebar-layout='swap']")
+ disposeAll()
+ expect(dom.window.document.head.querySelector(`style[data-plugin="${PLUGIN_NAME}"]`)).toBeNull()
+ })
+})
+
+describe('sidebar layout frame locator', () => {
+ it('tags the frame and its centre column with the current mode', () => {
+ const { dom } = mountClient()
+ const frame = dom.window.document.getElementById('frame')!
+ const centre = dom.window.document.querySelector('.centre')!
+ expect(frame.getAttribute(FRAME_ATTRIBUTE)).toBe('push')
+ expect(centre.hasAttribute(CENTER_ATTRIBUTE)).toBe(true)
+ })
+
+ it('restores a persisted mode onto the frame attribute', () => {
+ const { dom } = mountClient({ storage: { [STORAGE_KEY]: 'swap' } })
+ expect(dom.window.document.getElementById('frame')!.getAttribute(FRAME_ATTRIBUTE)).toBe('swap')
+ })
+
+ it('updates the frame attribute when the mode changes', () => {
+ const { dom, selectMode } = mountClient()
+ const frame = dom.window.document.getElementById('frame')!
+ selectMode('drawer')
+ expect(frame.getAttribute(FRAME_ATTRIBUTE)).toBe('drawer')
+ })
+
+ it('retags a replaced frame', async () => {
+ const { dom } = mountClient()
+ const root = dom.window.document.getElementById('root')!
+ const old = dom.window.document.getElementById('frame')!
+ const next = old.cloneNode(true) as Element
+ next.id = 'frame-2'
+ old.replaceWith(next)
+ // The MutationObserver delivery is asynchronous.
+ await new Promise(resolve => setTimeout(resolve, 0))
+ expect(next.getAttribute(FRAME_ATTRIBUTE)).toBe('push')
+ expect(next.querySelector('.centre')!.hasAttribute(CENTER_ATTRIBUTE)).toBe(true)
+ expect(root.contains(old)).toBe(false)
+ })
+
+ it('locates a frame that mounts after the effect', async () => {
+ const { dom } = mountClient({ html: '' })
+ expect(dom.window.document.querySelector(`[${FRAME_ATTRIBUTE}]`)).toBeNull()
+ const frame = dom.window.document.createElement('div')
+ frame.innerHTML = ''
+ dom.window.document.getElementById('root')!.appendChild(frame)
+ // The rAF retry picks up the late frame.
+ await new Promise(resolve => dom.window.requestAnimationFrame(() => setTimeout(resolve, 0)))
+ await new Promise(resolve => setTimeout(resolve, 0))
+ expect(frame.getAttribute(FRAME_ATTRIBUTE)).toBe('push')
+ })
+
+ it('removes attributes and stops on dispose', () => {
+ const { dom, disposeAll, selectMode } = mountClient()
+ const frame = dom.window.document.getElementById('frame')!
+ const centre = dom.window.document.querySelector('.centre')!
+ disposeAll()
+ expect(frame.hasAttribute(FRAME_ATTRIBUTE)).toBe(false)
+ expect(centre.hasAttribute(CENTER_ATTRIBUTE)).toBe(false)
+ selectMode('drawer')
+ expect(frame.hasAttribute(FRAME_ATTRIBUTE)).toBe(false)
+ })
+})
+
+describe('drawer mask click', () => {
+ function mountDrawer(options: { expanded?: boolean } = {}) {
+ const toggle = vi.fn()
+ const mounted = mountClient({
+ sidebarRight: {
+ isExpanded: () => options.expanded ?? true,
+ toggleExpanded: toggle,
+ },
+ })
+ mounted.selectMode('drawer')
+ const centre = mounted.dom.window.document.querySelector('.centre')!
+ return { toggle, centre, window: mounted.dom.window }
+ }
+
+ it('toggles the panel once when the mask itself is clicked while expanded', () => {
+ const { toggle, centre, window } = mountDrawer()
+ centre.dispatchEvent(new window.MouseEvent('click', { bubbles: true }))
+ expect(toggle).toHaveBeenCalledTimes(1)
+ })
+
+ it('does not toggle when a centre child is clicked', () => {
+ const { toggle, centre, window } = mountDrawer()
+ const child = centre.ownerDocument.createElement('button')
+ centre.appendChild(child)
+ child.dispatchEvent(new window.MouseEvent('click', { bubbles: true }))
+ expect(toggle).not.toHaveBeenCalled()
+ })
+
+ it('does not toggle when the panel is collapsed', () => {
+ const { toggle, centre, window } = mountDrawer({ expanded: false })
+ // Selecting drawer already attempted the expansion; the mask click itself
+ // must not toggle while the panel is closed.
+ toggle.mockClear()
+ centre.dispatchEvent(new window.MouseEvent('click', { bubbles: true }))
+ expect(toggle).not.toHaveBeenCalled()
+ })
+
+ it('does not toggle in a non-drawer mode', () => {
+ const toggle = vi.fn()
+ const mounted = mountClient({ sidebarRight: { isExpanded: () => true, toggleExpanded: toggle } })
+ const centre = mounted.dom.window.document.querySelector('.centre')!
+ centre.dispatchEvent(new mounted.dom.window.MouseEvent('click', { bubbles: true }))
+ expect(toggle).not.toHaveBeenCalled()
+ })
+})
+
+describe('sidebar layout cycle command', () => {
+ it('registers sidebar.layout.cycle and cycles the modes', () => {
+ const toggle = vi.fn()
+ const mounted = mountClient({ sidebarRight: { isExpanded: () => true, toggleExpanded: toggle } })
+ expect(mounted.registeredCommands).toHaveLength(1)
+ const command = mounted.registeredCommands[0] as unknown as {
+ id: string
+ defaults: Record
+ regions: string[]
+ modals: string[]
+ resolve(context: unknown): { status: string; run(): void }
+ }
+ expect(command.id).toBe('sidebar.layout.cycle')
+ expect(command.regions).toEqual(['page', 'editable', 'terminal'])
+ expect(command.modals).toEqual([])
+ // One triple-modifier default per admitted profile; web:linux admits no
+ // three-modifier Web binding, so it stays unbound like the native commands.
+ for (const profile of ['desktop:macos', 'desktop:windows', 'desktop:linux', 'web:macos', 'web:windows']) {
+ expect(command.defaults[profile]).toEqual({ code: 'KeyB', modifiers: ['primary', 'alt', 'shift'] })
+ }
+ expect(command.defaults['web:linux']).toBeUndefined()
+ const resolution = command.resolve({})
+ expect(resolution.status).toBe('handled')
+ resolution.run()
+ expect(mounted.storeMode()).toBe('drawer')
+ resolution.run()
+ expect(mounted.storeMode()).toBe('swap')
+ resolution.run()
+ expect(mounted.storeMode()).toBe('push')
+ })
+
+ it('expands the panel when cycling into a non-push mode', () => {
+ const toggle = vi.fn()
+ const mounted = mountClient({ sidebarRight: { isExpanded: () => false, toggleExpanded: toggle } })
+ const command = mounted.registeredCommands[0] as unknown as { resolve(context: unknown): { run(): void } }
+ command.resolve({}).run()
+ expect(mounted.storeMode()).toBe('drawer')
+ expect(toggle).toHaveBeenCalledTimes(1)
+ // Swap expands too (the double never reports expanded), and cycling back
+ // to push leaves the panel alone.
+ command.resolve({}).run()
+ expect(toggle).toHaveBeenCalledTimes(2)
+ command.resolve({}).run()
+ expect(mounted.storeMode()).toBe('push')
+ expect(toggle).toHaveBeenCalledTimes(2)
+ })
+
+ it('still cycles when isExpanded throws (no mounted session)', () => {
+ const mounted = mountClient({
+ sidebarRight: {
+ isExpanded: () => { throw new Error('no session') },
+ toggleExpanded: () => { throw new Error('no session') },
+ },
+ })
+ const command = mounted.registeredCommands[0] as unknown as { resolve(context: unknown): { run(): void } }
+ expect(() => command.resolve({}).run()).not.toThrow()
+ expect(mounted.storeMode()).toBe('drawer')
+ })
+})
+
+describe('sidebar layout slot registrations', () => {
+ it('waits on the two seats and registers both entries', () => {
+ const mounted = mountClient()
+ expect(mounted.injected).toEqual(['conversation.session.header.utilities', 'settings.general.item'])
+ expect(mounted.registrations).toHaveLength(2)
+ const header = mounted.registrations[0]
+ expect(header.spec).toMatchObject({
+ name: 'conversation.session.header.utilities',
+ id: 'sidebar-layout',
+ order: 10,
+ locale: 'dsh-sidebar-layout',
+ })
+ const settings = mounted.registrations[1]
+ expect(settings.spec).toMatchObject({
+ name: 'settings.general.item',
+ id: 'sidebar-layout',
+ order: 40,
+ locale: 'dsh-sidebar-layout',
+ })
+ // Both entries inject the shared store and one selectMode action.
+ for (const registration of mounted.registrations) {
+ const face = (registration.spec.inject as () => Record)()
+ expect(typeof face.selectMode).toBe('function')
+ expect((face.hooks as Record).mode).toBeDefined()
+ }
+ })
+})
+
+describe('sidebar layout components', () => {
+ const dict: Record = {
+ 'trigger.label': '侧栏布局',
+ 'mode.push': '常规',
+ 'mode.drawer': '抽屉',
+ 'mode.swap': '正文',
+ 'settings.title': '侧栏布局',
+ 'settings.description': '右侧边栏的呈现方式。',
+ }
+ const t = (key: string) => dict[key] ?? key
+
+ it('renders the settings row with title, description and a select', () => {
+ const html = renderToStaticMarkup(
+ selector('drawer')} selectMode={() => {}} />,
+ )
+ expect(html).toContain('sl-root sl-row')
+ expect(html).toContain('侧栏布局')
+ expect(html).toContain('dsh-ui-select')
+ expect(html).toContain('常规')
+ expect(html).toContain('抽屉')
+ expect(html).toContain('正文')
+ expect(html).toContain('value="drawer"')
+ })
+
+ it('renders the header trigger with the mode menu', () => {
+ const html = renderToStaticMarkup(
+ selector('push')} selectMode={() => {}} />,
+ )
+ expect(html).toContain('aria-label="侧栏布局"')
+ expect(html).toContain('aria-haspopup="menu"')
+ })
+})
diff --git a/plugins/dsh-sidebar-layout/src/client.tsx b/plugins/dsh-sidebar-layout/src/client.tsx
new file mode 100644
index 00000000..710f3645
--- /dev/null
+++ b/plugins/dsh-sidebar-layout/src/client.tsx
@@ -0,0 +1,463 @@
+import type { Context } from '@deepseek-ai/cordis'
+import { Button, IconPanelLeftOutlineRegular, Menu, Tooltip } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { MenuEntry } from '@deepseek-ai/dsh-client-ui-primitives'
+import { officialUiCss } from '@klarkxy/dsh-plugin-kit/official-ui'
+import { installClientPluginLogger } from '@klarkxy/dsh-plugin-kit/client-logger'
+import { useId, useState } from 'react'
+import {
+ CENTER_ATTRIBUTE, FRAME_ATTRIBUTE, PLUGIN_NAME, STORAGE_KEY,
+ createSidebarLayoutStore, nextMode,
+ type SidebarLayoutMode, type SidebarLayoutStorage, type SidebarLayoutStore,
+} from './contracts.ts'
+
+export const name = 'dsh-sidebar-layout-client'
+export const inject = ['slots', 'locale', 'layout', 'sidebarRight', 'shortcuts'] as const
+
+const NS = 'dsh-sidebar-layout'
+const ROOT_CLASS = 'sl-root'
+
+const zh = {
+ 'trigger.label': '侧栏布局',
+ 'mode.push': '常规',
+ 'mode.drawer': '抽屉',
+ 'mode.swap': '正文',
+ 'settings.title': '侧栏布局',
+ 'settings.description': '右侧边栏的呈现方式:常规挤压对话,抽屉覆盖对话,正文将面板移入中间列、对话移到右侧。',
+ 'command.cycle': '切换侧栏布局',
+} as const
+const en: Record = {
+ 'trigger.label': 'Sidebar layout',
+ 'mode.push': 'Push',
+ 'mode.drawer': 'Drawer',
+ 'mode.swap': 'Body',
+ 'settings.title': 'Sidebar layout',
+ 'settings.description': 'How the right Sidebar presents: Push squeezes the conversation, Drawer overlays it, Body moves the panel into the centre column and the conversation to the right.',
+ 'command.cycle': 'Cycle sidebar layout',
+}
+
+/* Every rule is anchored on the frame attribute the locator writes (or, for
+ * the header trigger and settings row, the plugin root class) — the
+ * stylesheet scope guard and the token whitelist both read this sheet.
+ * [data-rightbar-fullscreen] is excluded everywhere: fullscreen (including the
+ * <768px auto-fullscreen) keeps native host behaviour in every mode. */
+const layoutCss = `
+/* Drawer: the conversation column spans the right track as well, so the
+ * panel's open/close track animation never reflows it — the panel overlays.
+ * The tag attribute, not a :has() selector, keeps this match stable while the
+ * streaming chat mutates the subtree (better-sidebar documents the cost). */
+[data-dsh-sidebar-layout='drawer']:not([data-rightbar-fullscreen]) [data-dsh-sidebar-layout-center] {
+ grid-column: 2 / 4;
+ position: relative;
+ isolation: isolate;
+}
+[data-dsh-sidebar-layout='drawer']:not([data-rightbar-fullscreen]) [data-dsh-sidebar-layout-center]::after {
+ content: '';
+ position: absolute;
+ inset: 0;
+ z-index: 90;
+ background: var(--dsw-alias-bg-mask-1);
+ opacity: 0;
+ pointer-events: none;
+ transition: opacity var(--ds-transition-duration-slow) var(--ds-ease-in-out);
+}
+[data-dsh-sidebar-layout='drawer']:not([data-rightbar-collapsed]):not([data-rightbar-fullscreen]) [data-dsh-sidebar-layout-center]::after {
+ opacity: 1;
+ pointer-events: auto;
+}
+/* A soft left edge keeps the overlay panel legible over the dimmed column:
+ * overflow-clip-margin lets the shadow escape the panel's own right clip.
+ * No filter or transform on the panel — either would break its fixed
+ * floating windows. */
+[data-dsh-sidebar-layout='drawer']:not([data-rightbar-collapsed]):not([data-rightbar-fullscreen]) [data-sidebar-right-panel] {
+ overflow-clip-margin: 0px 0px 0px 24px;
+ box-shadow: var(--dsw-elevation-soft);
+}
+@media (prefers-reduced-motion: reduce) {
+ [data-dsh-sidebar-layout='drawer']:not([data-rightbar-fullscreen]) [data-dsh-sidebar-layout-center]::after { transition: none; }
+}
+/* Swap ("正文"): only while the panel is open — the collapsed state keeps the
+ * native push geometry so closing lands back on host behaviour. The
+ * conversation column becomes the right track and the panel column the
+ * centre; the host's right-edge drag handle then resizes the conversation. */
+[data-dsh-sidebar-layout='swap']:not([data-rightbar-collapsed]):not([data-rightbar-fullscreen]) {
+ & [data-dsh-sidebar-layout-center] {
+ grid-column: 3;
+ border-left: 0.5px solid var(--dsw-alias-border-l3);
+ }
+ & [data-rightbar-col] {
+ grid-column: 2;
+ }
+ /* The panel fills its column: host writes inline width + --dsh-sidebar-width,
+ * both overridden so the body surface tracks the frame instead of the
+ * stored drag width. */
+ & [data-sidebar-right-panel] {
+ width: 100% !important;
+ --dsh-sidebar-width: 100% !important;
+ }
+ /* Track drags resize the panel instantly; the docked items' slide
+ * transforms would lag a frame behind the pointer. */
+ & [data-sidebar-right-panel] [data-dockkit-host='dock'],
+ & [data-sidebar-right-panel] [data-dockkit-empty],
+ & [data-sidebar-right-panel] [data-dockkit-divider] {
+ transition: none;
+ }
+ /* Windows caption mode: the 16px content radius belongs to the body surface
+ * — swap moves it from the conversation column to the panel's first pane,
+ * mirroring the host's own fullscreen rule. */
+ html[data-windows-titlebar] & [data-dockkit-column='0'][data-dockkit-pane] {
+ border-radius: var(--dsh-windows-content-radius) 0 0 0;
+ corner-shape: round;
+ }
+ html[data-windows-titlebar] & [data-dsh-sidebar-layout-center] {
+ border-radius: 0;
+ }
+ /* macOS: the panel's first dock strip takes over the leading clearance the
+ * conversation column held (traffic lights / shell.leading seat). */
+ html[data-platform='darwin'] & [data-dockkit-host='dock'][data-dockkit-column='0'] {
+ --dsh-dockkit-strip-inline-start: var(--dsh-frame-leading-clearance, 10px);
+ }
+ html[data-platform='darwin'] & [data-dsh-sidebar-layout-center] {
+ --dsh-frame-leading-clearance: 0px;
+ }
+}
+`
+
+/* The settings row mirrors the native Settings → General item geometry (16px
+ * padding, 0.5px l2 hairline, 14/22 title over a 12/18 description, a 240px
+ * trailing control); the header trigger keeps the utilities strip's 28px
+ * ghost-button shape. */
+const rowCss = `
+.sl-root.sl-row { display: flex; align-items: center; flex-wrap: wrap; gap: 8px; padding: 16px 0; border-bottom: 0.5px solid var(--dsw-alias-border-l2); }
+.sl-root .sl-row-text { flex: 1; display: flex; flex-direction: column; gap: 4px; min-width: 0; padding-right: 40px; }
+.sl-root .sl-row-title { font-size: 14px; line-height: 22px; color: var(--dsw-alias-label-primary); }
+.sl-root .sl-row-desc { font-size: 12px; line-height: 18px; color: var(--dsw-alias-label-tertiary); }
+.sl-root .sl-row-control { display: inline-flex; align-items: center; gap: 8px; min-width: 0; }
+.sl-root .sl-select { flex: 0 1 240px; width: auto; }
+.sl-root.sl-trigger { display: inline-flex; align-items: center; justify-content: center; padding: 0; line-height: 0; }
+@media (max-width: 767px) {
+ .sl-root .sl-row-text { padding-right: 16px; }
+ .sl-root .sl-select { flex: 0 1 auto; width: 240px; max-width: 100%; }
+}
+`
+
+/** One sheet: shared UI recipes under the plugin root class, the settings-row
+ * geometry, then the frame-attribute layout rules. */
+export const sidebarLayoutStyles = `${officialUiCss(ROOT_CLASS)}
+` + rowCss + layoutCss
+
+/** The client services the bundle declares. `layout` is injected for the
+ * AppFrame contract (its DOM is the tagging target); nothing on its service
+ * face is called. */
+interface SidebarRightFace {
+ isExpanded(): boolean
+ toggleExpanded(): void
+}
+interface ShortcutCatalogEntryLike {
+ readonly id: string
+ readonly keys: readonly string[]
+ readonly aria: string | undefined
+}
+interface ShortcutBindingLike {
+ code: string
+ modifiers: readonly string[]
+}
+type ShortcutResolutionLike = {
+ status: 'handled'
+ run(): void
+} | {
+ status: 'blocked'
+ reason: string
+} | {
+ status: 'pass'
+}
+interface ShortcutCommandLike {
+ id: string
+ label: () => string
+ aliases: readonly string[]
+ defaults: Readonly>>
+ regions: readonly string[]
+ modals: readonly string[]
+ resolve(context: unknown): ShortcutResolutionLike
+}
+type Client = {
+ locale: {
+ getSnapshot(): { active: string }
+ subscribe(fn: () => void): () => void
+ register(ns: string, dicts: Record>): () => void
+ }
+ slots: {
+ inject(key: string, callback: () => unknown): () => void
+ register(spec: Record, render: unknown): () => void
+ }
+ layout: unknown
+ sidebarRight: SidebarRightFace
+ shortcuts: {
+ catalog: { getSnapshot(): readonly ShortcutCatalogEntryLike[]; subscribe(fn: () => void): () => void }
+ register(command: ShortcutCommandLike): () => void
+ }
+}
+
+function readStorage(): SidebarLayoutStorage | undefined {
+ try {
+ return typeof localStorage === 'undefined' ? undefined : localStorage
+ } catch {
+ return undefined
+ }
+}
+
+/** Drawer and body modes show the panel, so choosing one while it is
+ * collapsed expands it. `isExpanded`/`toggleExpanded` throw when no session
+ * is mounted — the mode change must survive that. */
+function ensureExpanded(client: Client): void {
+ try {
+ if (!client.sidebarRight.isExpanded()) client.sidebarRight.toggleExpanded()
+ } catch {
+ /* no mounted session surface: the mode still applies once one exists */
+ }
+}
+
+/** Selector hook share produced by the slot framework from `inject.hooks`,
+ * plus the action face the registrations hand down. */
+interface InjectedProps {
+ useMode?: (selector: (mode: SidebarLayoutMode) => T) => T
+ selectMode?: (mode: SidebarLayoutMode) => void
+ t(key: string): string
+}
+
+/** The session-header utility: an icon button that opens the three-mode
+ * primitives Menu, current mode checked. The shortcut catalog hook feeds the
+ * tooltip's keycap and the menu row's visible binding. */
+export function SidebarLayoutAction(props: InjectedProps & {
+ useShortcuts?: (selector: (entries: readonly ShortcutCatalogEntryLike[]) => T) => T
+}) {
+ const mode = props.useMode ? props.useMode(value => value) : 'push'
+ const shortcut = props.useShortcuts?.(entries => entries.find(entry => entry.id === 'sidebar.layout.cycle'))
+ const [open, setOpen] = useState(false)
+ const { t } = props
+ const items: MenuEntry[] = ['push', 'drawer', 'swap'].map(id => ({ id, label: t(`mode.${id}`) }))
+ return (
+