dsh-sidebar-drawer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1dustycy
+
+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.
+
+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.

package/README.en.md

@@ -0,0 +1,82 @@
+# dsh-sidebar-drawer
+
+English | [简体中文](README.md)
+
+An edge-hover drawer for the left sidebar: while the sidebar is collapsed, moving the pointer into **the leftmost 10 px of the screen and holding it there for 500 ms** pulls the sidebar out; it stays out the whole time the pointer remains inside the drawer, and retracts by itself once the pointer leaves.
+
+A pure browser-behavior plugin (the host half is empty). It only borrows DSH's own sidebar toggling and changes no built-in file.
+
+![Revealing and retracting the drawer](docs/drawer-demo.gif)
+
+## What it does
+
+- **Dwelling is what counts** — the pointer must stay inside the leftmost 10 px for 500 ms before anything happens; sweeping past the edge never triggers it by accident.
+- **Inside the drawer means staying** — while the pointer rests inside the drawer (reading, clicking, idling) the drawer stays out and nothing rushes you.
+- **No interrupting an animation** — a second toggle is never issued while an open/close transition is in flight, so the drawer neither jumps nor vanishes mid-flight.
+- **Slides, not jumps** — the shipped frame writes the column width first and publishes its transition marker afterwards, so a plain toggle is instantaneous (a retraction looks like the drawer simply disappearing); before requesting a toggle the plugin pre-arms the frame's own marker, so both the reveal and the retraction really slide.
+- **A hand-opened sidebar is left alone** — a sidebar you opened yourself with the button, Cmd+B, or a width drag is never touched and never retracted.
+- **Yields** — width drags, window blur, and page scroll each have their own yield rule.
+
+Row-by-row scenarios, state-machine invariants, and known gaps: **[docs/behavior.md](docs/behavior.md)** (Chinese).
+
+## Install
+
+This is a DSH **plugin bundle**: it ships its own `cordis.patch.yml` and declares `dsh.bundle.patch` in `package.json`, so Plugin Manager installs it and owns the mount row — **you never hand-edit the profile's patch file**.
+
+```bash
+# From npm (recommended: pins the version)
+dsh plugin --profile desktop add dsh-sidebar-drawer@0.1.0
+
+# From GitHub (also version-pinned, through the repo's v0.1.0 tag)
+dsh plugin --profile desktop add "github:1dustycy/dsh-sidebar-drawer#v0.1.0"
+
+# Track the latest commit on main (to pick up behavior changes early)
+dsh plugin --profile desktop add github:1dustycy/dsh-sidebar-drawer
+
+# From a local directory (for development: writes a link: dependency, edits take effect immediately)
+dsh plugin --profile desktop add /path/to/dsh-sidebar-drawer
+```
+
+Replace `desktop` with the profile you want (e.g. `web`, `tui`). The command does two things: it adds the package to `dependencies` in `~/.dsh/profiles/<name>/package.json`, and adds `dsh-sidebar-drawer` to that profile's `dsh.profile.bundles`. Once installed, **refresh the page** and it is live — no app restart needed (the client half is hot-loaded through the bundle's mtime polling plus `/plugins/events`).
+
+Uninstall:
+
+```bash
+dsh plugin --profile desktop remove dsh-sidebar-drawer
+```
+
+> Why not just add a row to the profile's `cordis.patch.yml`? That file is shared with other sessions, and when it gets overwritten the symptom is a plugin that looks installed but does nothing — with nothing in the plugin itself to show for it. Rationale in [ADR-0003](docs/adr/0003-bundle-patch-ownership.md).
+
+**Requirements**: DSH Desktop (or any profile with a Web GUI). The client half injects `@deepseek-ai/dsh-client-ui-layout`, so the target profile must already mount the Web layout bundle. `peerDependencies` is `@deepseek-ai/cordis >=4.0.4 <5` — when installing from a registry, Plugin Manager checks that range first and refuses before anything is downloaded if it does not match.
+
+## Development and verification
+
+```bash
+node test/client.test.mjs    # unit suite: vm + DOM doubles + an advancing virtual clock, no browser needed
+node test/browser.test.mjs   # browser suite: real Chromium + CDP real mouse events and real CSS animations
+npm test                     # runs both suites, in that order
+node tools/probe.mjs         # diagnostic tool: prints the decision trail of one edge hover
+npm pack --dry-run           # confirm what gets published
+```
+
+After editing `lib/client.js`, **refresh the page** and the change is live (provided the profile's `hmr` row is enabled, which the desktop profile does by default).
+
+`test/browser.test.mjs` brings its own HTTP server and browser process and exits when it is done; it needs Chromium on the machine (it skips itself when none is found). `SHOT=<path> node test/browser.test.mjs` saves the final "drawer open" frame as a PNG (that is where `docs/harness-open.png` comes from). The animation at the top is the other way round — a **screen recording of the real GUI**, not the fixture — and `node tools/demo-gif.mjs <recording>` regenerates it, which needs ffmpeg on the machine. `test/harness.html` is a faithful replica of the shipped three-column frame: open it in a browser with `?plugin=<URL of client.js>` to try the behavior by hand.
+
+> **Read [docs/implementation.md](docs/implementation.md#测试夹具必须与出厂契约同步) before touching the test fixtures.**
+> Both fixtures must model the shipped shell's anchor contract exactly: once a fixture renders a conditional anchor unconditionally, it goes all-green on a broken bundle — which is precisely how this plugin once shipped a defect where a pointer resting motionless on the edge toggled the drawer forever.
+
+## Docs
+
+| Document | Contents |
+|---|---|
+| [docs/behavior.md](docs/behavior.md) | Behavior spec: row-by-row scenarios, state-machine invariants, known gaps |
+| [docs/implementation.md](docs/implementation.md) | Implementation notes: shipped anchor contract, decision logic, tunable constants |
+| [docs/adr/](docs/adr/) | Decision records (why it is built this way) |
+| [CONTEXT.md](CONTEXT.md) | Glossary: Chinese wording mapped to code identifiers |
+
+> The detailed docs are Chinese-only for now; this file is the English entry point.
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,95 @@
+# dsh-sidebar-drawer
+
+[English](README.en.md) | 简体中文
+
+左侧栏边缘抽屉：侧栏收起时，把鼠标移到**屏幕最左边 10px 内并停留 500ms** 就会抽出侧栏；鼠标停在抽屉里期间一直保持抽出；鼠标离开抽屉后自动收回。
+
+一个纯浏览器行为插件（Host 半边是空的），只借用 DSH 自己的侧栏开合，不改动任何内置文件。
+
+![抽屉抽出与收回的演示](docs/drawer-demo.gif)
+
+## 它会做什么
+
+- **停留才算数** —— 指针要在左侧 10px 内连续待够 500ms 才抽出；扫过边缘不会误触。
+- **在抽屉里就保持** —— 指针停在抽屉内（阅读、点击、停留）期间一直抽出，不催你。
+- **动画期不打断** —— 开合过渡进行中绝不发第二次开合，所以不会跳变，也不会突然消失。
+- **滑动而不是跳变** —— 出厂 frame 是"先写列宽、后发布过渡标记"，直接开合会瞬变（收回看起来
+  就是一下子消失）；插件在请求开合前先把框架自己的标记预置上，所以抽出与收回都真的滑动。
+- **手开的侧栏不碰** —— 你用按钮、Cmd+B 或拖拽调宽开出来的侧栏（手开），插件完全不碰、从不收回。
+- **让路** —— 拖拽列宽、窗口失焦、页面滚动都有对应的让路逻辑。
+
+逐条场景、状态机不变量与已知缺口见 **[docs/behavior.md](docs/behavior.md)**。
+
+## 安装
+
+这是一个 DSH **plugin bundle**：包内自带 `cordis.patch.yml`，`package.json` 里声明了
+`dsh.bundle.patch`，所以它由 Plugin Manager 安装并托管挂载行 —— **不需要你手改 profile 的补丁文件**。
+
+```bash
+# 从 npm 安装（推荐，带版本钉住）
+dsh plugin --profile desktop add dsh-sidebar-drawer@0.1.0
+
+# 从 GitHub 安装（同样钉住版本，走仓库的 v0.1.0 tag）
+dsh plugin --profile desktop add "github:1dustycy/dsh-sidebar-drawer#v0.1.0"
+
+# 跟随 main 最新提交（便于拿到最新行为改动）
+dsh plugin --profile desktop add github:1dustycy/dsh-sidebar-drawer
+
+# 从本地目录安装（开发用：写入 link: 依赖，改动即时生效）
+dsh plugin --profile desktop add /path/to/dsh-sidebar-drawer
+```
+
+把 `desktop` 换成你要装的 profile 名（如 `web`、`tui`）。这条命令做两件事：把包装进
+`~/.dsh/profiles/<name>/package.json` 的 `dependencies`，并把 `dsh-sidebar-drawer` 加进该 profile 的
+`dsh.profile.bundles`。装完后**刷新页面**即可生效，不需要重启 App（客户端半边由 bundle 的 mtime
+轮询 + `/plugins/events` 热加载）。
+
+卸载：
+
+```bash
+dsh plugin --profile desktop remove dsh-sidebar-drawer
+```
+
+> 为什么不直接往 profile 的 `cordis.patch.yml` 里加一行？那是与其他会话共享的文件，被覆盖时
+> 症状是插件"装了但没生效"，且从插件自身看不出任何异常。理由见
+> [ADR-0003](docs/adr/0003-bundle-patch-ownership.md)。
+
+**要求**：DSH Desktop（或任何带 Web GUI 的 profile）。客户端半边注入
+`@deepseek-ai/dsh-client-ui-layout`，所以目标 profile 必须已挂载 Web 布局 bundle。
+`peerDependencies` 为 `@deepseek-ai/cordis >=4.0.4 <5` —— 从 registry 安装时 Plugin Manager 会先
+核对这一条，不兼容就在下载之前拒绝。
+
+## 开发与验证
+
+```bash
+node test/client.test.mjs    # 单元套件：vm + DOM 替身 + 会推进的虚拟时钟，不需要浏览器
+node test/browser.test.mjs   # 浏览器套件：真实 Chromium + CDP 真实鼠标事件与真实 CSS 动画
+npm test                     # 依次跑上面两套
+node tools/probe.mjs         # 诊断工具：打印一次边缘悬停的决策轨迹
+npm pack --dry-run           # 确认发布内容
+```
+
+改 `lib/client.js` 后**刷新页面**即可生效（前提是 profile 的 `hmr` 行处于启用状态，桌面 profile 默认启用）。
+
+`test/browser.test.mjs` 自带 HTTP 服务与浏览器进程，跑完即退出；需要本机有 Chromium（找不到会自动跳过）。
+`SHOT=<路径> node test/browser.test.mjs` 会把最后"抽屉打开"的画面存成 PNG（`docs/harness-open.png`
+即由此生成）。顶部那张动图反过来 —— 它是**真实 GUI 的屏幕录制**，不是夹具 —— 用
+`node tools/demo-gif.mjs <录屏文件>` 重新生成，需要本机有 ffmpeg。`test/harness.html` 是内置三栏
+框架的等价复刻，用浏览器直接打开并加 `?plugin=<client.js 的 URL>` 也能手工试。
+
+> **改测试夹具前请先读** [docs/implementation.md](docs/implementation.md#测试夹具必须与出厂契约同步)。
+> 两套夹具必须精确建模出厂 shell 的锚点契约：夹具一旦把条件锚点写成常驻，就会在一个已损坏的
+> bundle 上全绿 —— 本插件正是这样发布过一个"指针停在边缘不动就无限开合"的缺陷。
+
+## 文档
+
+| 文档 | 内容 |
+|---|---|
+| [docs/behavior.md](docs/behavior.md) | 行为规格：逐条场景、状态机不变量、已知缺口 |
+| [docs/implementation.md](docs/implementation.md) | 实现要点：出厂锚点契约、判定逻辑、可调参数 |
+| [docs/adr/](docs/adr/) | 决策记录（为什么这样做） |
+| [CONTEXT.md](CONTEXT.md) | 术语表：中文措辞与代码标识符的对应 |
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# The bundle layer this package contributes to a profile: one row mounting the
+# plugin itself. Kept as a bundle patch (rather than an entry in the profile's
+# own cordis.patch.yml) so Plugin Manager owns the row across installs,
+# updates, and other writes to the profile's user layer.
+- insert:
+    - id: ui-sidebar-drawer
+      name: dsh-sidebar-drawer

package/lib/client.js

@@ -0,0 +1,791 @@
+window.__ModuleLoader__.load({
+	id: "dsh-sidebar-drawer",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+
+		/**
+		 * Edge-hover drawer for the left sidebar.
+		 *
+		 * The sidebar keeps its shipped open/close semantics; this behavior only
+		 * drives `toggleSidebar()` from pointer position:
+		 *
+		 *  - the pointer entering the left edge strip while the sidebar is closed
+		 *    opens it (hover-to-reveal);
+		 *  - the pointer inside the revealed drawer keeps it open, so the user can
+		 *    read and click without hurry (each move is checked against the drawer's
+		 *    live box, and every "outside" verdict is confirmed by a second check
+		 *    after the grace delay, which also absorbs the open animation);
+		 *  - the pointer leaving the drawer retracts it, but only when this
+		 *    behavior is the one that opened it — a sidebar the user opened by
+		 *    hand (button, shortcut, width drag, or `narrowExpanded`) is left alone.
+		 *
+		 * Every toggle it issues is preceded by arming the frame's own
+		 * `data-animating` marker, because that marker is what puts the shell's
+		 * column transition in effect — and the shell publishes it one pass too
+		 * late for its own write to be covered by it (see {@link armFrameMarker}).
+		 *
+		 * The drawer's geometry is read from the live DOM instead of the layout
+		 * store, so width drags, the collapsed rail, an open right panel, and the
+		 * frame's open/close animation are all honored without mirroring layout
+		 * math.
+		 */
+
+		/** Width of the left screen-edge strip a pointer must rest in to reveal the drawer. */
+		const EDGE_SIZE = 10;
+		/**
+		 * How long the pointer must stay in that strip. Revealing on contact alone made a
+		 * pointer merely crossing the edge — on its way to the content, or flicked there —
+		 * throw the drawer open; the dwell makes the reveal deliberate, and leaves the
+		 * strip before it elapses.
+		 */
+		const DWELL_MS = 500;
+		/** Grace before a pointer found outside the drawer retracts it. */
+		const CLOSE_DELAY_MS = 260;
+		/** Slack allowed past the drawer's outer edge, in px. */
+		const POINTER_MARGIN = 4;
+		/**
+		 * Selector of the sidebar's column drag handle, treated as part of the drawer.
+		 * The shipped handle publishes its side and is mounted only while the sidebar is
+		 * open, so this deliberately matches nothing in the collapsed state — where the
+		 * collapsed column is the reveal strip itself and must stay unclaimed.
+		 */
+		const HANDLE_SELECTOR = '[data-side="sidebar"]';
+		/**
+		 * How far past the reveal strip a pointer must travel before leaning back to it
+		 * counts as leaving. The drawer grows over one animation from 0 to its full
+		 * width, so "outside the box" is not yet a verdict while it is still growing:
+		 * a pointer that stepped a little way in is waiting for the drawer to reach it,
+		 * and retracting there would make the reveal feel like it snaps shut.
+		 */
+		const RETAIN_MARGIN = 48;
+		/** Width at which a column counts as a settled open drawer rather than a moving edge. */
+		const OPEN_SETTLED_WIDTH = 56;
+		/**
+		 * How often a deferred retraction re-checks whether the shell is still animating.
+		 * The frame publishes its own `data-animating` marker around a discrete column
+		 * change (and clears it on `transitionend`, self-capped at 600ms), so the
+		 * retraction polls that marker instead of assuming any duration — a slower
+		 * animation simply defers longer. Note a viewport-driven collapse publishes no
+		 * marker at all, so its absence must never be read as "a transition just ended".
+		 */
+		const ANIMATION_POLL_MS = 120;
+		/**
+		 * Ceiling on that polling, in case the marker is never cleared. The shell caps its
+		 * own marker at 600ms, so this sits deliberately far above any real transition:
+		 * the poll, not this bound, is what ends the wait.
+		 */
+		const ANIMATION_CEILING_MS = 2500;
+		/** Absolute cap on a deferred retraction, whatever the markers claim. */
+		const ANIMATION_HARD_STOP_MS = 3500;
+		/** Marker set on the document element while this behavior is mounted. */
+		const MARK = "dsh-sidebar-drawer";
+		/** The frame publishes this marker while a column transition is running. */
+		const ANIMATING_ATTR = "data-animating";
+		/**
+		 * Value written into that marker when this behavior arms the frame ahead of a
+		 * toggle. The shell writes `"true"`, and a value of its own is what lets the
+		 * withdrawal below tell a marker this behavior armed from one the shell owns —
+		 * a distinction that keeps the withdrawal from cutting a transition the shell
+		 * is running short (dropping the transition property mid-flight snaps the
+		 * column to its target).
+		 */
+		const PREARMED = "drawer";
+		/** The frame publishes this marker while the sidebar is closed. */
+		const COLLAPSED_ATTR = "data-sidebar-collapsed";
+		/** The frame publishes this marker while the user drags a column handle. */
+		const DRAGGING_ATTR = "data-dragging";
+		/**
+		 * The frame's window-chrome seat. Mounted only while the sidebar is collapsed
+		 * (the shipped shell gates it on `darwin && sidebarCollapsed`), so it is a
+		 * fallback anchor and never the one that always exists.
+		 */
+		const LEADING_ATTR = "data-shell-leading";
+		/**
+		 * The frame's overlay layer: an unconditional child of the frame, and one of only
+		 * two frame markers the shipped shell renders in every state (the rightbar column
+		 * carries the other). It is the one that identifies the frame itself, so the frame
+		 * lookup tries it first. See `docs/adr/0001-frame-anchor-contract.md`.
+		 */
+		const OVERLAY_ATTR = "data-shell-overlay";
+
+		/**
+		 * Resolve the frame element that carries the layout markers.
+		 *
+		 * The overlay layer is asked first because it is the only anchor the shipped
+		 * shell renders unconditionally. Every other anchor here is conditional:
+		 * `data-sidebar-collapsed` and `data-shell-leading` both leave the document the
+		 * moment the sidebar opens, so anchoring on them alone loses the frame in
+		 * exactly the state the drawer is used in — which reads as "the pointer is not
+		 * over the drawer" and retracts it on every check. See
+		 * `docs/adr/0001-frame-anchor-contract.md`.
+		 * @param doc - document to query.
+		 * @returns the frame element, or null while the shell is not mounted.
+		 */
+		function frameOf(doc) {
+			const overlay = doc.querySelector("[" + OVERLAY_ATTR + "]");
+			const overlayFrame = overlay !== null ? overlay.parentElement : null;
+			if (overlayFrame !== null) return overlayFrame;
+			const collapsed = doc.querySelector("[" + COLLAPSED_ATTR + "]");
+			if (collapsed !== null) return collapsed;
+			const leading = doc.querySelector("[" + LEADING_ATTR + "]");
+			const seatAnchored = leading !== null ? leading.parentElement : null;
+			if (seatAnchored !== null) return seatAnchored;
+			const column = doc.querySelector("[data-sidebar-col]");
+			return column !== null ? column.parentElement : null;
+		}
+
+		/**
+		 * The frame's first grid child: the shipped sidebar column.
+		 *
+		 * This holds only because the shipped frame's first entry in its children array,
+		 * `DocumentTitle`, renders `null` and therefore creates no element. A real element
+		 * placed ahead of the sidebar column would silently make this measure the wrong
+		 * node, so re-check it against the shell before trusting the box.
+		 */
+		function columnOf(frame) {
+			return frame === null ? null : frame.firstElementChild;
+		}
+
+		/**
+		 * Whether the frame reports a closed sidebar.
+		 * @param frame - frame element, or null.
+		 * @returns true while the sidebar is collapsed.
+		 */
+		function isCollapsed(frame) {
+			return frame !== null && frame.getAttribute(COLLAPSED_ATTR) === "true";
+		}
+
+		/**
+		 * Whether a column drag is in flight (a drag must never be interrupted).
+		 * @param frame - frame element, or null.
+		 * @returns true while the frame reports dragging.
+		 */
+		function isDragging(frame) {
+			return frame !== null && frame.hasAttribute(DRAGGING_ATTR);
+		}
+
+		/**
+		 * Mount the edge-hover drawer behavior.
+		 * @param deps - injectable document, window, and layout service (tests pass doubles).
+		 * @returns a disposer removing every listener, timer, and DOM mark.
+		 */
+		function install(deps) {
+			const doc = deps.document;
+			const win = deps.window;
+			const layout = deps.layout;
+
+			/** True while this behavior opened the drawer and no other actor has touched it. */
+			let weOpened = false;
+			/** Live handle of the pending close, or null. */
+			let closeTimer = null;
+			/** Last pointer position seen by a move event; -1 while no sample is live. */
+			let lastX = -1;
+			let lastY = -1;
+			/** False once a leave event reports the pointer gone; re-judged from the sample. */
+			let pointerLeftWindow = false;
+			/** Set while a move is queued, so moves coalesce into one check per frame. */
+			let frameQueued = false;
+			/**
+			 * True from the moment this behavior asks to close until that transition has
+			 * settled. It is what tells a half-grown column apart from a half-shrunk one:
+			 * both read as "narrow", and only this flag says which way it is going.
+			 */
+			let retracting = false;
+			/** True while the shell's transition is still running for our last toggle. */
+			let togglePending = false;
+			let pendingTimer = null;
+			/** Start of the current toggle's transition, for the ceiling on deferral. */
+			let pendingSince = 0;
+			/** Set when the pointer waits on the strip through a retraction. */
+			let revealNextCheck = false;
+			/** Live handle of the pending dwell in the reveal strip, or null. */
+			let dwellTimer = null;
+			/** Live handle of a reveal waiting out someone else's transition, or null. */
+			let revealTimer = null;
+			/** Start of the current reveal deferral, or 0 while no intent is waiting. */
+			let revealWaitSince = 0;
+			/** Live handle of the withdrawal armed for a pre-armed frame marker, or null. */
+			let prearmTimer = null;
+			let disposed = false;
+
+			function cancelClose() {
+				if (closeTimer === null) return;
+				win.clearTimeout(closeTimer);
+				closeTimer = null;
+			}
+
+			/** Cancel a dwell that has not fired yet. */
+			function cancelDwell() {
+				if (dwellTimer === null) return;
+				win.clearTimeout(dwellTimer);
+				dwellTimer = null;
+			}
+
+			/** Cancel the settled-check armed by the last toggle. */
+			function cancelPending() {
+				if (pendingTimer === null) return;
+				win.clearTimeout(pendingTimer);
+				pendingTimer = null;
+			}
+
+			/** Cancel a reveal waiting out someone else's transition. */
+			function cancelRevealWait() {
+				if (revealTimer === null) return;
+				win.clearTimeout(revealTimer);
+				revealTimer = null;
+			}
+
+			/** Stop waiting for a pre-armed frame marker to settle. */
+			function cancelPrearm() {
+				if (prearmTimer === null) return;
+				win.clearTimeout(prearmTimer);
+				prearmTimer = null;
+			}
+
+			/**
+			 * Withdraw a pre-armed marker the shell never claimed, and stop listening for
+			 * its transition.
+			 *
+			 * A marker still carrying {@link PREARMED} means the shell published none of
+			 * its own — its toggle changed nothing it animates, or a viewport change made
+			 * it skip the marker deliberately. Leaving it behind would be a lie every
+			 * later check reads as "a column is moving", so a reveal would be deferred
+			 * against a transition that is not running. A marker the shell owns is left
+			 * exactly as it is, whatever brings us here.
+			 */
+			function withdrawPrearm() {
+				cancelPrearm();
+				const frame = frameOf(doc);
+				if (frame === null) return;
+				frame.removeEventListener("transitionend", onFrameSettled);
+				if (frame.getAttribute(ANIMATING_ATTR) !== PREARMED) return;
+				frame.removeAttribute(ANIMATING_ATTR);
+			}
+
+			/**
+			 * The frame finished a column transition.
+			 *
+			 * For a pre-armed marker this is the moment it has done its job: it is the
+			 * only thing that held the transition open (the shell marked nothing of its
+			 * own), and withdrawn any earlier it would cut that transition short. Its
+			 * own descendants' transitions bubble past here too, hence the target check —
+			 * the shell's own settle does exactly the same.
+			 * @param event - the frame's `transitionend`.
+			 */
+			function onFrameSettled(event) {
+				if (event.target !== event.currentTarget) return;
+				if (event.propertyName !== "grid-template-columns") return;
+				withdrawPrearm();
+			}
+
+			/**
+			 * Arm the frame's own transition marker *before* asking for a toggle.
+			 *
+			 * The shell writes the new columns first and publishes this marker in a second
+			 * pass, and the layout read the app performs in between — its tab strip
+			 * measures itself in a layout effect inside the same commit — makes the browser
+			 * adopt the new track sizes while no transition is in effect. The frame's
+			 * transition property is only published by this marker, so the column then
+			 * snaps: measured in the shipped app, `transitionend` never fires for the
+			 * column and the marker is left to the shell's own 600ms cap, in both
+			 * directions. Writing the marker first puts the transition in effect for the
+			 * write the shell is about to make, which is what makes the track travel
+			 * instead of jumping. The shell claims the marker as its own (it renders
+			 * `"true"`) and clears it when that transition ends.
+			 *
+			 * A marker already on the frame is left alone: the shell owns it, and a
+			 * transition already in effect is the whole point.
+			 */
+			function armFrameMarker() {
+				const frame = frameOf(doc);
+				if (frame === null || frame.hasAttribute(ANIMATING_ATTR)) return;
+				frame.setAttribute(ANIMATING_ATTR, PREARMED);
+				frame.addEventListener("transitionend", onFrameSettled);
+				cancelPrearm();
+				prearmTimer = win.setTimeout(withdrawPrearm, ANIMATION_CEILING_MS);
+			}
+
+			/**
+			 * Mark our toggle as transitioning and settle the state once the shell stops
+			 * animating. The marker is polled rather than awaited: it is the frame's own
+			 * `data-animating` attribute, which covers the whole transition and is cleared
+			 * on `transitionend`, so no duration has to be guessed here.
+			 */
+			function markToggle() {
+				togglePending = true;
+				pendingSince = win.performance.now();
+				cancelPending();
+				const settle = () => {
+					const frame = frameOf(doc);
+					const animating = frame !== null && frame.hasAttribute(ANIMATING_ATTR);
+					if (animating && win.performance.now() - pendingSince < ANIMATION_CEILING_MS) {
+						pendingTimer = win.setTimeout(settle, ANIMATION_POLL_MS);
+						return;
+					}
+					pendingTimer = null;
+					togglePending = false;
+					retracting = false;
+					/* One more look once the geometry stops moving: a pointer that waited
+					   on the strip is revealed there, and one that walked off is not. */
+					checkPointer();
+					/* A close that was deferred for this transition is not forgotten: the
+					   same verdict is applied again against the settled geometry — but only
+					   where a verdict exists (see {@link pointerProvenOutside}). */
+					if (weOpened && pointerProvenOutside()) armClose();
+				};
+				pendingTimer = win.setTimeout(settle, ANIMATION_POLL_MS);
+			}
+
+			/**
+			 * Ask the layout service for the shipped sidebar toggle.
+			 *
+			 * The frame is armed first (see {@link armFrameMarker}) so the columns the
+			 * shell is about to write land on a transition that is already in effect.
+			 * @returns true when a toggle was issued; false when a previous one is still
+			 * animating, because a second flip mid-transition cancels the shell's own
+			 * animation and the drawer snaps instead of sliding.
+			 */
+			function toggleSidebar() {
+				if (togglePending) return false;
+				markToggle();
+				armFrameMarker();
+				try {
+					layout.toggleSidebar();
+				} catch (error) {
+					/* Nothing was written, so nothing will claim the marker: withdraw it
+					   instead of leaving a transition that is not running standing. */
+					withdrawPrearm();
+					console.error("sidebar drawer: toggleSidebar failed", error);
+				}
+				return true;
+			}
+
+			/**
+			 * Whether the reveal wish holds right now: a pointer resting in the trigger
+			 * strip over a sidebar this behavior is allowed to reveal. Whether the
+			 * pointer is still *there* at all is a separate, evidence question the
+			 * callers settle first — absence of a sample proves nothing either way.
+			 */
+			function revealWanted() {
+				const frame = frameOf(doc);
+				if (lastX > EDGE_SIZE || isDragging(frame)) return false;
+				if (weOpened || togglePending) return false;
+				return drawerIsClosed() || drawerBarelyOpen();
+			}
+
+			/**
+			 * Keep a reveal intent alive behind a column transition that is not ours.
+			 *
+			 * The wait is driven by the frame's own `data-animating` marker and never by
+			 * a guessed duration — the same polling the deferred retraction uses, so no
+			 * new timeout constants appear and a slower machine simply waits longer.
+			 * When the marker clears, the intent is re-judged against the settled state
+			 * (deferred, not discarded): a live sample that still holds reveals at once;
+			 * a window-level leave — real evidence — drops the intent; and no live
+			 * sample is **not** evidence of leaving (see `docs/behavior.md` row 16), so
+			 * the intent parks on {@link revealNextCheck} and lands on the next fresh
+			 * strip sample.
+			 */
+			function deferReveal() {
+				if (revealTimer !== null || disposed) return;
+				if (revealWaitSince === 0) revealWaitSince = win.performance.now();
+				const wait = () => {
+					revealTimer = null;
+					if (disposed) return;
+					const frame = frameOf(doc);
+					const animating = frame !== null && frame.hasAttribute(ANIMATING_ATTR);
+					if (animating && win.performance.now() - revealWaitSince < ANIMATION_CEILING_MS) {
+						revealTimer = win.setTimeout(wait, ANIMATION_POLL_MS);
+						return;
+					}
+					revealTimer = null;
+					if (pointerLeftWindow) {
+						revealWaitSince = 0;
+						return;
+					}
+					if (!positionIsCurrent()) {
+						revealNextCheck = true;
+						revealWaitSince = 0;
+						return;
+					}
+					revealWaitSince = 0;
+					if (revealWanted()) reveal();
+				};
+				revealTimer = win.setTimeout(wait, ANIMATION_POLL_MS);
+			}
+
+			/**
+			 * Open the drawer and take ownership of it.
+			 *
+			 * A column transition already in flight gets the right of way first: a
+			 * second flip mid-animation cancels the frame's own transition and the
+			 * sidebar snaps instead of sliding. That gate covers every caller's intent,
+			 * and the intent is deferred rather than dropped (see {@link deferReveal}).
+			 * A marker that outlives every real transition is a lie, and
+			 * {@link ANIMATION_HARD_STOP_MS} stops believing it.
+			 */
+			function reveal() {
+				if (togglePending) return;
+				if (drawerIsAnimating() && (revealWaitSince === 0 || win.performance.now() - revealWaitSince < ANIMATION_HARD_STOP_MS)) {
+					deferReveal();
+					return;
+				}
+				revealWaitSince = 0;
+				cancelClose();
+				cancelDwell();
+				revealNextCheck = false;
+				weOpened = true;
+				toggleSidebar();
+			}
+
+			/** Whether the shell's transition is still running for our last toggle. */
+			function toggleInFlight() {
+				return togglePending;
+			}
+
+			/**
+			 * Whether the pointer is inside the viewport, judged by the sample itself.
+			 *
+			 * A `mouseleave` (or a window blur) marks the pointer as gone, but the only
+			 * thing that marks it back is another move — and a pointer resting perfectly
+			 * still after the drawer reveals sends no such event. So the sample is asked
+			 * directly: a point inside the viewport that still hits an element is a
+			 * pointer this page can see, whatever the last leave event claimed.
+			 */
+			function pointerInViewport() {
+				if (lastX < 0) return false;
+				if (lastX < win.innerWidth && lastY < win.innerHeight) return true;
+				const hit = doc.elementFromPoint(lastX, lastY);
+				return hit !== null && hit !== undefined;
+			}
+
+			/** Whether a live pointer sample exists. */
+			function positionIsCurrent() {
+				return lastX >= 0;
+			}
+
+			/**
+			 * Live box of the sidebar column, which is the drawer itself.
+			 * @returns the column's rect, or null while the shell is not mounted.
+			 */
+			function drawerRect() {
+				const column = columnOf(frameOf(doc));
+				return column === null ? null : column.getBoundingClientRect();
+			}
+
+			/**
+			 * Whether the shell reports a column transition in progress, for this behavior
+			 * or for anyone else. `data-animating` is the frame's own marker around every
+			 * discrete column change, so it covers slow transitions without any guess.
+			 * @returns true while the frame is animating a column.
+			 */
+			function drawerIsAnimating() {
+				const frame = frameOf(doc);
+				return frame !== null && frame.hasAttribute(ANIMATING_ATTR);
+			}
+
+			/**
+			 * Whether the sidebar is collapsed, per the frame's own marker.
+			 *
+			 * Deliberately not width-based: a narrow column also means "still opening",
+			 * and reading that as closed would cancel retractions the pointer asked for.
+			 * {@link drawerBarelyOpen} carries the width signal for the reveal gate, while
+			 * retractions already wait out the frame's transitions.
+			 */
+			function drawerIsClosed() {
+				return isCollapsed(frameOf(doc));
+			}
+
+			/**
+			 * Whether the pointer should count as off the drawer while it is still
+			 * growing: a column narrower than the closed rail is not a drawer anyone can
+			 * be "inside" yet, so it is only usable as a hint, never as a close verdict.
+			 */
+			function drawerBarelyOpen() {
+				const rect = drawerRect();
+				return rect !== null && rect.width <= OPEN_SETTLED_WIDTH;
+			}
+
+			/**
+			 * Whether the pointer is over the drawer, using the drawer's live box.
+			 *
+			 * The box is taken as it is, even mid-transition: while the drawer grows, the
+			 * strip it grows from is already part of it, so a pointer resting there is
+			 * inside and must never be read as having left. (Refusing "inside" for a narrow
+			 * column is exactly what made a resting pointer loop the drawer open/closed.)
+			 *
+			 * The left edge takes no slack: the column's own left edge is screen x = 0, so
+			 * slack there would swallow part of the reveal strip. Only the right edge takes
+			 * {@link POINTER_MARGIN}, because the width handle sits on it and a pointer
+			 * resting on the handle is still a pointer on the drawer.
+			 */
+			function pointerOverDrawer() {
+				if (!positionIsCurrent()) return false;
+				const column = columnOf(frameOf(doc));
+				if (column === null) return false;
+				const rect = column.getBoundingClientRect();
+				if (rect.width <= 0.5 || rect.height <= 0.5) return false;
+				/* The box alone never claims the reveal strip: a closed column is a 0px
+				   strip at x = 0, so even {@link POINTER_MARGIN} past its right edge would
+				   swallow the strip and the dwell could never arm. The hit test is what
+				   covers the width handle sitting just outside that edge. */
+				if (
+					lastX >= rect.left &&
+					lastX <= rect.right + POINTER_MARGIN &&
+					lastY >= rect.top - POINTER_MARGIN &&
+					lastY <= rect.bottom + POINTER_MARGIN
+				) {
+					return true;
+				}
+				/* Consult the element under the pointer, but only where the drawer can
+				   actually be reached: a closed sidebar keeps a full-width content box
+				   inside its clipping column, so an unguarded hit test would report that
+				   hidden content as "inside" and make the strip unusable. The handle is
+				   part of the drawer, so it counts even while the column is collapsed. */
+				const handle = column.parentElement !== null ? column.parentElement.querySelector(HANDLE_SELECTOR) : null;
+				if (rect.width <= OPEN_SETTLED_WIDTH && handle === null) return false;
+				const hit = doc.elementFromPoint(lastX, lastY);
+				if (hit === null || hit === undefined) return false;
+				if (hit === handle || (handle !== null && handle.contains(hit))) return true;
+				return hit === column || column.contains(hit);
+			}
+
+			/**
+			 * Whether the pointer is proven to be off the drawer — the only footing a
+			 * retraction may stand on.
+			 *
+			 * A window-level leave is final. Otherwise a *live* sample must measure
+			 * outside: after a viewport change the sample is dropped, and with no live
+			 * sample nothing is proven either way. Absence of evidence is not evidence
+			 * of leaving, so the drawer keeps its state until a fresh sample arrives.
+			 */
+			function pointerProvenOutside() {
+				return pointerLeftWindow || (positionIsCurrent() && !pointerOverDrawer());
+			}
+
+			/**
+			 * Retract the drawer this behavior opened.
+			 * @returns true when the retraction was issued or was already unnecessary.
+			 */
+			function retract() {
+				if (!weOpened || disposed) return true;
+				weOpened = false;
+				if (drawerIsClosed()) return true;
+				retracting = true;
+				toggleSidebar();
+				return true;
+			}
+
+			/**
+			 * Arm the grace timer; the pointer must still be outside when it expires.
+			 *
+			 * The verdict the grace expires into is never "not inside" but "proven
+			 * outside" (see {@link pointerProvenOutside}): a sample invalidated by a
+			 * reflow proves nothing, so such a grace expires quietly and the drawer
+			 * waits for a fresh sample instead of retracting on absent evidence.
+			 *
+			 * While the frame is animating a column it has no settled box to be judged
+			 * against, so the timer arms but expires into another arming instead of a
+			 * retraction. That is what keeps the reveal from closing behind a pointer that
+			 * simply moved a little way in: the drawer is still coming to it. The wait is
+			 * bounded so a frame that never clears its marker cannot pin the drawer open.
+			 */
+			function armClose() {
+				if (closeTimer !== null || !weOpened) return;
+				const armedAt = win.performance.now();
+				closeTimer = win.setTimeout(() => {
+					closeTimer = null;
+					if (!weOpened) return;
+					if (!pointerProvenOutside()) return;
+					const waiting = win.performance.now() - armedAt < ANIMATION_HARD_STOP_MS;
+					if (waiting && (drawerIsAnimating() || toggleInFlight())) {
+						armClose();
+						return;
+					}
+					retract();
+				}, CLOSE_DELAY_MS);
+			}
+
+			/** One coalesced pointer check. */
+			function checkPointer() {
+				frameQueued = false;
+				if (disposed || !positionIsCurrent()) return;
+				/* Ownership ends where the drawer ends: a sidebar the frame reports
+				   collapsed is not the one this behavior opened, whoever closed it — a
+				   hand-close, or the viewport-driven auto-collapse below the narrow
+				   threshold. Holding the flag past that would park a pointer in the
+				   strip at "leaning on the reveal strip" and the dwell could never arm
+				   again. (`!togglePending` guards the render lag right after our own
+				   reveal: the marker leaves the DOM a tick after the store flips.) */
+				if (weOpened && !togglePending && drawerIsClosed()) {
+					weOpened = false;
+				}
+				const frame = frameOf(doc);
+				const over = pointerOverDrawer();
+				/* While the window reports the pointer gone, every recorded position is
+				   stale: no reveal, no dwell, no verdict may be based on it. */
+				const onStrip = !pointerLeftWindow && lastX <= EDGE_SIZE && !isDragging(frame);
+				/* The pointer must rest in the strip: leaving it — usually by walking on
+				   into the window — cancels a reveal that has not fired yet. */
+				if (!onStrip) cancelDwell();
+				/* A pointer that waited on the strip — through a retraction, or parked
+				   behind someone else's transition — gets its reveal now, but only while
+				   it is still there. Fresh evidence of leaving drops the intent; a merely
+				   dropped sample does not (row 16: absence of evidence is not leaving). */
+				if (revealNextCheck) {
+					if (onStrip && !pointerLeftWindow) {
+						revealNextCheck = false;
+						reveal();
+						return;
+					}
+					if (pointerLeftWindow || lastX > EDGE_SIZE) revealNextCheck = false;
+				}
+				if (onStrip && retracting) {
+					/* On its way out with the pointer back on the strip: keep the wish and
+					   decide again once that transition has settled. */
+					if (!weOpened) revealNextCheck = true;
+					return;
+				}
+				/* While nothing of the drawer is shown, the strip *is* the trigger: no
+				   "is the pointer over the drawer" question applies, because there is no
+				   drawer yet. (Asking it let the collapsed column's clipped content box —
+				   full-width inside a zero-width column — answer "yes" and block the
+				   reveal. The drag handle is *not* the culprit: the shipped shell does not
+				   mount it at all while the sidebar is collapsed.) See
+				   `docs/adr/0002-collapsed-strip-is-the-trigger.md`. */
+				if (onStrip && !weOpened && (drawerIsClosed() || drawerBarelyOpen())) {
+					/* Arm the dwell once; the timer fires only if the pointer stays. */
+					if (dwellTimer === null) {
+						dwellTimer = win.setTimeout(() => {
+							dwellTimer = null;
+							if (!pointerInViewport()) return;
+							/* The premise the dwell was armed under must still hold — in
+							   particular a hand-open that settled while the pointer waited
+							   leaves a normal open sidebar, not a drawer to reveal over. */
+							if (!revealWanted()) return;
+							reveal();
+						}, DWELL_MS);
+					}
+					return;
+				}
+				if (!weOpened) return;
+				if (over) {
+					cancelClose();
+					return;
+				}
+				if (lastX <= RETAIN_MARGIN) {
+					/* Still leaning on the reveal strip while the drawer grows: hold it. */
+					cancelClose();
+					return;
+				}
+				armClose();
+			}
+
+			function onPointerMove(event) {
+				lastX = event.clientX;
+				lastY = event.clientY;
+				/* A move that lands in the viewport is itself evidence the pointer is
+				   present, whatever the last leave/enter pair claimed. */
+				if (pointerInViewport()) pointerLeftWindow = false;
+				if (frameQueued) return;
+				frameQueued = true;
+				win.requestAnimationFrame(checkPointer);
+			}
+
+			/** A pointer that left the window is outside the drawer by definition. */
+			/**
+			 * The window reports the pointer leaving or entering. Only these events — not a
+			 * guessed position — decide whether the sample is still meaningful, which is
+			 * what separates a pointer that really left from one that merely stopped
+			 * moving (and whose last sample still looks like it is inside the drawer).
+			 */
+			function onPointerLeave() {
+				pointerLeftWindow = true;
+				cancelDwell();
+				if (!weOpened) return;
+				armClose();
+			}
+
+			/** The pointer is back on the page: its next move supplies a fresh sample. */
+			function onPointerEnter() {
+				pointerLeftWindow = false;
+			}
+
+			/**
+			 * A reflow moves the drawer under a pointer that never moved, so the live
+			 * sample is dropped and the next move re-establishes it.
+			 *
+			 * A viewport change **only invalidates evidence, never draws a conclusion**:
+			 * it discards the stale sample and cancels whatever was still waiting on it
+			 * (a pending dwell, a queued grace close) — but it must not retract a drawer
+			 * the pointer may well still be in, nor pin one it has left. Both verdicts
+			 * wait for the next real sample. See `docs/behavior.md` row 16.
+			 */
+			function onViewportChange() {
+				lastX = -1;
+				lastY = -1;
+				cancelDwell();
+				cancelClose();
+			}
+
+			const listeners = [];
+			function listen(target, type, handler) {
+				target.addEventListener(type, handler);
+				listeners.push([target, type, handler]);
+			}
+
+			listen(doc, "pointermove", onPointerMove);
+			listen(doc, "pointerleave", onPointerLeave);
+			listen(doc, "pointerenter", onPointerEnter);
+			listen(win, "blur", onPointerLeave);
+			listen(win, "focus", onPointerEnter);
+			listen(win, "resize", onViewportChange);
+			listen(win, "scroll", onViewportChange);
+			doc.documentElement.setAttribute(MARK, "");
+
+			return () => {
+				disposed = true;
+				cancelClose();
+				cancelPending();
+				cancelDwell();
+				cancelRevealWait();
+				/* Also cancels the withdrawal timer and detaches the frame listener. */
+				withdrawPrearm();
+				for (const [target, type, handler] of listeners) target.removeEventListener(type, handler);
+				listeners.length = 0;
+				doc.documentElement.removeAttribute(MARK);
+			};
+		}
+
+		/** Required services: the layout service that owns the sidebar toggle. */
+		const inject = ["layout"];
+
+		/**
+		 * Client plugin body: mount the edge-hover drawer over the shipped sidebar.
+		 * @param ctx - client root context.
+		 */
+		function apply(ctx) {
+			const layout = ctx.get("layout");
+			if (layout === undefined || layout === null) {
+				console.error("sidebar drawer: layout service unavailable");
+				return;
+			}
+			ctx.effect(
+				() =>
+					install({
+						document: document,
+						window: window,
+						layout: layout
+					}),
+				"sidebar drawer: edge-hover reveal"
+			);
+		}
+
+		exports.install = install;
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});

package/lib/index.js

@@ -0,0 +1,10 @@
+/**
+ * Host half of the sidebar edge-hover drawer. This package is a pure browser
+ * behavior: the empty `apply` exists so the row appears in the profile's
+ * cordis.patch.yml and the Loader mounts it, while the browser half ships
+ * through `exports["./client"]`, discovered from the package.json `dsh.client`
+ * declaration.
+ */
+
+/** Host plugin body — no host-side behavior for this surface plugin. */
+export function apply() {}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "dsh-sidebar-drawer",
+  "description": "Edge-hover drawer for the Web GUI left sidebar: reveal it by moving the pointer to the left screen edge, keep it while the pointer stays inside, retract it when the pointer leaves",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "scripts": {
+    "test": "node test/client.test.mjs && node test/browser.test.mjs"
+  },
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "cordis.patch.yml",
+    "docs/drawer-demo.gif"
+  ],
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "cordis",
+    "plugin",
+    "bundle",
+    "sidebar",
+    "drawer",
+    "web-gui"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1dustycy/dsh-sidebar-drawer.git"
+  },
+  "homepage": "https://github.com/1dustycy/dsh-sidebar-drawer#readme",
+  "bugs": {
+    "url": "https://github.com/1dustycy/dsh-sidebar-drawer/issues"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-layout"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.4 <5"
+  }
+}