@deepseek-ai/dsh-client-ui-layout 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/ui-layout/README.md
+README.md: fa60520a20ac8a7f25d494879c68efb06a28998f
+README.zh.md: 2ce3d1972d39013d84216596dc57d48ab2d245d9

package/README.md

@@ -0,0 +1,23 @@
+# @deepseek-ai/dsh-client-ui-layout
+
+English | [中文](README.zh.md)
+
+Shell plugin: three-column AppFrame (drag handles and concession chain) plus the `ctx.layout` panel-geometry service; it registers into the runtime-owned `root` slot and declares `sidebar`, `conversation`, `details`, and `conversation.empty`. The sidebar resize boundary is an invisible hit strip, while the details boundary retains its floating pill; only details shrinks during concession and then auto-closes. A closed sidebar retains a 56px control rail while details closes to zero width. The package also seats the theme presenter: it consumes resolved `ctx.theme` snapshots and projects them onto the document (`html { color-scheme }` for native UA chrome, `body[data-ds-dark-theme]` from the active color scheme, the theme's alias tokens as inline variables on body, and one owned `<meta name="theme-color">` whose content follows the computed body background). Measuring after palette and token application keeps the rendered background as the single color authority; disposing the presenter removes its metadata node with its other global writes.
+
+AppFrame always mounts the conversation and details columns; a connected Session renders through `SessionProvider`. The transient layout store starts the sidebar at its default width and details closed, and it never reads or writes `localStorage`. Hero and other unselected states also derive a zero rendered details width without changing that stored preference. AppFrame retains the last non-blank Session id across those states: the first Session remains closed, an explicit details action opens the contract default width, returning to the same Session restores its unchanged width, and selecting a different Session closes details before paint. The conversation owner share is empty, while the sidebar owner share contains only `collapsed` and `width`; registrants obtain business data from standard hooks and actions from their own inject faces.
+
+The `/client` export surface is the plugin body (`apply`/`inject`), `LayoutService`, and the four owner-share interfaces. AppFrame, the panel store, and the concession solver remain package-internal.
+
+## Model Experience
+
+None, as the layout shell manages browser viewing state; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Panel geometry is transient** — reload restores the sidebar default and details closed; switching between distinct Session ids also closes details and forgets its dragged width, while unselected surfaces render details at zero width without modifying geometry.
+- **Concession-chain auto-close derives a zero width without touching the preferred width** — the panel restores itself when the window widens; consumers must not read the stored details width as the rendered truth.
+- **No scroll anchoring during squeeze reflow** — layout changes may move the reader's viewport.

package/README.zh.md

@@ -0,0 +1,23 @@
+# @deepseek-ai/dsh-client-ui-layout
+
+[English](README.md) | 中文
+
+外壳插件：三栏 AppFrame（拖动手柄与让步链）加 `ctx.layout` 面板几何服务；它注册到运行时拥有的 `root` slot，并声明 `sidebar`、`conversation`、`details` 和 `conversation.empty`。侧边栏的缩放边界是不可见命中条带，详情栏边界则保留其浮动胶囊；让步期间只有详情栏会收缩并随后自动关闭。关闭的侧边栏仍保留 56px 控制栏，详情栏则关闭到零宽度。该包还提供主题呈现器：它消费解析后的 `ctx.theme` 快照，并将其投影到 document（用 `html { color-scheme }` 驱动原生 UA 控件，依据当前配色方案设置 `body[data-ds-dark-theme]`，并将主题的别名 token 设为 body 上的内联变量，同时拥有一个 `<meta name="theme-color">`，其内容随计算后的 body 背景色更新）。在应用调色板和 token 后进行测量，可确保渲染后的背景成为唯一的颜色依据；呈现器在 dispose（资源释放）时会移除其自有的元数据节点，并一并清除其写入的其他全局状态。
+
+AppFrame 始终挂载会话栏和详情栏；已连接 Session 通过 `SessionProvider` 渲染。布局 store 是瞬时状态，侧边栏以默认宽度启动，详情栏则保持关闭，且该 store 从不读写 `localStorage`。hero 和其他未选中状态也会将详情栏的渲染宽度派生为零，但不会改变存储的宽度偏好。AppFrame 会跨越这些状态保留最后一个非 blank 会话 id：首个会话保持关闭；显式打开详情栏的操作会使用约定默认宽度；返回同一会话时恢复其未改变的宽度；选择不同会话时，详情栏会在绘制前关闭。会话 owner share 为空，侧边栏 owner share 只包含 `collapsed` 和 `width`；注册方通过标准钩子获取业务数据，并从各自的 inject 接口获取操作。
+
+`/client` 导出表层包含插件主体（`apply`／`inject`）、`LayoutService` 和四个 owner-share 接口。AppFrame、面板 store 与让步求解器仍属于包内部。
+
+## 模型体验
+
+无。布局外壳管理浏览器查看状态；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **面板几何信息是瞬时状态**：重新加载会恢复侧边栏默认值，并使详情栏保持关闭；在不同会话 id 之间切换同样会关闭详情栏，并忘记拖动后的宽度，而未选中表面会以零宽度渲染详情栏，但不会修改几何信息。
+- **让步链自动关闭通过推导零宽度实现，不会改动宽度偏好**：窗口变宽时面板会自行恢复；消费方禁止把 store 中的详情宽度当作实际渲染状态。
+- **挤压重排期间不提供滚动锚定**：布局变化可能移动读者的 viewport。

package/lib/client.js

@@ -0,0 +1,446 @@
+window.__ModuleLoader__.load({
+	id: "@deepseek-ai/dsh-client-ui-layout",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let react_jsx_runtime = require("react/jsx-runtime");
+		let react = require("react");
+		let _deepseek_ai_dsh_client_runtime_client = require("@deepseek-ai/dsh-client-runtime/client");
+		/** Viewport width below which the sidebar auto-collapses to the rail (deepsuite
+		* LG breakpoint); a manual toggle below it re-expands over the squeezed center
+		* (stores.ts narrowExpanded). */
+		const SIDEBAR_AUTO_COLLAPSE = 1024;
+		/**
+		* Clamp a panel width into its contract range.
+		* @param px - requested width.
+		* @param min - range lower bound.
+		* @param max - range upper bound.
+		* @returns the clamped width.
+		*/
+		function clampWidth(px, min, max) {
+			return Math.min(max, Math.max(min, Math.round(px)));
+		}
+		/**
+		* Solve the three column widths for one viewport frame. Pure: no hysteresis —
+		* the output is a function of (viewport, preferences) only, so recovery on
+		* re-widening is automatic. Preferences re-clamp here because they cross the
+		* store boundary and callers may still supply stale ranges.
+		* @param viewport - available frame width in px.
+		* @param sidebar - sidebar width preference in px (0 = closed).
+		* @param details - details width preference in px (0 = closed).
+		* @returns resolved widths; details 0 means visually closed (never unmounted), while a closed sidebar keeps its compact rail.
+		*/
+		function computeColumns(viewport, sidebar, details) {
+			const s = sidebar === 0 ? 56 : clampWidth(sidebar, 280, 420);
+			const d0 = details === 0 ? 0 : clampWidth(details, 300, 520);
+			if (s + d0 + 640 <= viewport) return {
+				sidebar: s,
+				center: viewport - s - d0,
+				details: d0
+			};
+			const d1 = d0 === 0 ? 0 : Math.max(300, viewport - s - 640);
+			if (s + d1 + 640 <= viewport) return {
+				sidebar: s,
+				center: 640,
+				details: d1
+			};
+			return {
+				sidebar: s,
+				center: Math.max(0, viewport - s),
+				details: 0
+			};
+		}
+		//#endregion
+		//#region \0dsh-css:/home/runner/work/deepseek-harness/deepseek-harness/packages/client/ui-layout/src/client/AppFrame.module.css.mjs
+		const css = ".pI_x6G_frame{background:var(--dsw-alias-bg-base);height:100%;transition:grid-template-columns var(--ds-transition-duration-slow) var(--ds-ease-in-out);grid-template-rows:100%;display:grid;position:relative;overflow:hidden}.pI_x6G_frame[data-dragging]{transition:none}@media (prefers-reduced-motion:reduce){.pI_x6G_frame{transition:none}}.pI_x6G_sidebarCol{background:var(--dsw-specific-sidebar-fill);border-right:1px solid var(--dsw-alias-border-l1);min-width:0;overflow:hidden}.pI_x6G_centerCol{flex-direction:column;min-width:0;display:flex;overflow:hidden}.pI_x6G_detailsCol{border-left:1px solid var(--dsw-alias-border-l2);min-width:0;overflow:hidden}.pI_x6G_frame[data-details-collapsed] .pI_x6G_detailsCol{border-left:none}.pI_x6G_handle{cursor:col-resize;z-index:2;touch-action:none;width:8px;transition:left var(--ds-transition-duration-slow) var(--ds-ease-in-out);margin-left:-4px;position:absolute;top:0;bottom:0}.pI_x6G_frame[data-dragging] .pI_x6G_handle{transition:none}@media (prefers-reduced-motion:reduce){.pI_x6G_handle{transition:none}}.pI_x6G_handle[data-side=details]:after{content:\"\";box-sizing:border-box;background:var(--dsw-alias-button-floating-fill);border:1px solid var(--dsw-alias-border-l2-darkmode-thin);opacity:0;width:12px;height:32px;transition:opacity var(--ds-transition-duration-slow) var(--ds-ease-in-out), background var(--ds-transition-duration-slow) var(--ds-ease-in-out);border-radius:10px;position:absolute;top:50%;left:50%;transform:translate(-50%,-50%)}.pI_x6G_detailsCol:hover~.pI_x6G_handle[data-side=details]:after,.pI_x6G_handle[data-side=details]:hover:after,.pI_x6G_handle[data-side=details][data-dragging=true]:after{opacity:1}.pI_x6G_handle[data-side=details]:hover:after,.pI_x6G_handle[data-side=details][data-dragging=true]:after{background:var(--dsw-alias-button-floating-hover);border-color:var(--dsw-alias-border-l3)}";
+		const tagId = "@deepseek-ai/dsh-client-ui-layout/AppFrame.module.css";
+		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
+			const tag = document.createElement("style");
+			tag.dataset.plugin = "@deepseek-ai/dsh-client-ui-layout";
+			tag.dataset.pluginCss = tagId;
+			tag.textContent = css;
+			document.head.appendChild(tag);
+		}
+		var AppFrame_module_css_default = {
+			"sidebarCol": "pI_x6G_sidebarCol",
+			"detailsCol": "pI_x6G_detailsCol",
+			"frame": "pI_x6G_frame",
+			"centerCol": "pI_x6G_centerCol",
+			"handle": "pI_x6G_handle"
+		};
+		//#endregion
+		//#region lib/types/client/AppFrame.js
+		/**
+		* Three-column shell frame, registered into the built-in 'root' slot (the web
+		* shell renders only 'root'). Owns the grid tracks (sidebar | center |
+		* details), the drag handles (pointer capture + rAF throttle), the concession
+		* chain (columns.ts), and the child-slot render decisions: the sidebar slot
+		* renders HERE with live parameters from the concession solve, and the
+		* session-aware occupants render in fixed column positions; strict entries
+		* gate themselves on current-session availability while session-maybe
+		* entries retain identity. Pure component: everything arrives
+		* through the three framework shares — zero cordis or framework imports,
+		* zero self-made hooks.
+		*/
+		/** Center column grid item (session-body building block). */
+		function CenterColumn(props) {
+			return (0, react_jsx_runtime.jsx)("div", {
+				className: AppFrame_module_css_default.centerCol,
+				children: props.children
+			});
+		}
+		/** Details column grid item; width 0 keeps the subtree mounted (never unmount on close). */
+		function DetailsColumn(props) {
+			return (0, react_jsx_runtime.jsx)("div", {
+				className: AppFrame_module_css_default.detailsCol,
+				children: props.children
+			});
+		}
+		/**
+		* One drag handle: pointer capture, rAF-throttled dx reports against the drag-start origin.
+		* `side` keys the hover-reveal CSS to the owning column.
+		*/
+		function DragHandle(props) {
+			const [dragging, setDragging] = (0, react.useState)(false);
+			const origin = (0, react.useRef)(0);
+			const latest = (0, react.useRef)(0);
+			const frame = (0, react.useRef)(null);
+			const callbacks = (0, react.useRef)({
+				onStart: props.onStart,
+				onDrag: props.onDrag,
+				onEnd: props.onEnd
+			});
+			callbacks.current = {
+				onStart: props.onStart,
+				onDrag: props.onDrag,
+				onEnd: props.onEnd
+			};
+			const onPointerDown = (0, react.useCallback)((e) => {
+				e.preventDefault();
+				e.currentTarget.setPointerCapture(e.pointerId);
+				origin.current = e.clientX;
+				latest.current = e.clientX;
+				callbacks.current.onStart();
+				setDragging(true);
+			}, []);
+			const onPointerMove = (0, react.useCallback)((e) => {
+				if (!e.currentTarget.hasPointerCapture(e.pointerId)) return;
+				latest.current = e.clientX;
+				frame.current ??= requestAnimationFrame(() => {
+					frame.current = null;
+					callbacks.current.onDrag(latest.current - origin.current);
+				});
+			}, []);
+			const onPointerUp = (0, react.useCallback)((e) => {
+				if (!e.currentTarget.hasPointerCapture(e.pointerId)) return;
+				e.currentTarget.releasePointerCapture(e.pointerId);
+				if (frame.current !== null) {
+					cancelAnimationFrame(frame.current);
+					frame.current = null;
+				}
+				callbacks.current.onDrag(latest.current - origin.current);
+				setDragging(false);
+				callbacks.current.onEnd();
+			}, []);
+			return (0, react_jsx_runtime.jsx)("div", {
+				className: AppFrame_module_css_default.handle,
+				style: { left: props.left },
+				"data-side": props.side,
+				"data-dragging": dragging || void 0,
+				onPointerDown,
+				onPointerMove,
+				onPointerUp
+			});
+		}
+		/** The three-column frame (see module doc). */
+		function AppFrame({ useStore, useSessions, actions, renderSlot }) {
+			const panels = useStore((s) => s);
+			const detailsSession = useSessions((s) => {
+				const current = s.current;
+				return current !== void 0 && s.byId[current]?.blank === false ? current : void 0;
+			});
+			const frameRef = (0, react.useRef)(null);
+			const [viewport, setViewport] = (0, react.useState)(() => window.innerWidth);
+			const lastSession = (0, react.useRef)(detailsSession);
+			(0, react.useLayoutEffect)(() => {
+				if (detailsSession === void 0) return;
+				if (lastSession.current !== void 0 && lastSession.current !== detailsSession) actions.closeDetails();
+				lastSession.current = detailsSession;
+			}, [actions, detailsSession]);
+			(0, react.useEffect)(() => {
+				const el = frameRef.current;
+				/* v8 ignore next -- the ref is always attached by effect time: the frame div renders unconditionally. */
+				if (el === null) return;
+				let raf = null;
+				const observer = new ResizeObserver(() => {
+					raf ??= requestAnimationFrame(() => {
+						raf = null;
+						const width = el.getBoundingClientRect().width;
+						if (width > 0) setViewport(width);
+					});
+				});
+				observer.observe(el);
+				return () => {
+					observer.disconnect();
+					if (raf !== null) cancelAnimationFrame(raf);
+				};
+			}, []);
+			const narrow = viewport < SIDEBAR_AUTO_COLLAPSE;
+			(0, react.useEffect)(() => {
+				actions.setNarrow(narrow);
+			}, [actions, narrow]);
+			const sidebarCollapsed = narrow ? !panels.narrowExpanded : panels.sidebar === 0;
+			const cols = computeColumns(viewport, sidebarCollapsed ? 0 : panels.sidebar === 0 ? 280 : panels.sidebar, detailsSession === void 0 ? 0 : panels.details);
+			const colsRef = (0, react.useRef)(cols);
+			colsRef.current = cols;
+			const sidebarBase = (0, react.useRef)(0);
+			const detailsBase = (0, react.useRef)(0);
+			const [dragging, setDragging] = (0, react.useState)(false);
+			const onDragEnd = (0, react.useCallback)(() => {
+				setDragging(false);
+			}, []);
+			const onSidebarStart = (0, react.useCallback)(() => {
+				sidebarBase.current = colsRef.current.sidebar;
+				setDragging(true);
+			}, []);
+			const onDetailsStart = (0, react.useCallback)(() => {
+				detailsBase.current = colsRef.current.details;
+				setDragging(true);
+			}, []);
+			const onSidebarDrag = (0, react.useCallback)((dx) => {
+				actions.setSidebar(sidebarBase.current + dx);
+			}, [actions]);
+			const onDetailsDrag = (0, react.useCallback)((dx) => {
+				actions.setDetails(detailsBase.current - dx);
+			}, [actions]);
+			return (0, react_jsx_runtime.jsxs)("div", {
+				ref: frameRef,
+				className: AppFrame_module_css_default.frame,
+				style: { gridTemplateColumns: `${cols.sidebar}px minmax(0, 1fr) ${cols.details}px` },
+				"data-sidebar-collapsed": sidebarCollapsed || void 0,
+				"data-details-collapsed": cols.details === 0 || void 0,
+				"data-dragging": dragging || void 0,
+				children: [
+					(0, react_jsx_runtime.jsx)("div", {
+						className: AppFrame_module_css_default.sidebarCol,
+						children: renderSlot("sidebar", {
+							collapsed: sidebarCollapsed,
+							width: cols.sidebar
+						})
+					}),
+					(0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [(0, react_jsx_runtime.jsx)(CenterColumn, { children: renderSlot("conversation", {}) }), (0, react_jsx_runtime.jsx)(DetailsColumn, { children: renderSlot("details", {}) })] }),
+					!sidebarCollapsed && (0, react_jsx_runtime.jsx)(DragHandle, {
+						side: "sidebar",
+						left: cols.sidebar,
+						onStart: onSidebarStart,
+						onDrag: onSidebarDrag,
+						onEnd: onDragEnd
+					}),
+					cols.details > 0 && (0, react_jsx_runtime.jsx)(DragHandle, {
+						side: "details",
+						left: viewport - cols.details,
+						onStart: onDetailsStart,
+						onDrag: onDetailsDrag,
+						onEnd: onDragEnd
+					})
+				]
+			});
+		}
+		//#endregion
+		//#region lib/types/client/stores.js
+		/**
+		* The root entry's transient layout store: panel geometry as plain widths in
+		* px (0 = closed). Module level exports the factory only — a module-level
+		* handle would pin the store's identity in the module
+		* cache (a de-facto singleton surviving plugin reloads). register() receives
+		* the factory (exclusive use: the framework instantiates per entry), AppFrame
+		* derives its PropsStore share from the return type, and the service face
+		* receives the bound actions through the registration's inject hook.
+		*/
+		/**
+		* Create the layout panel store handle. The preference IS the width, so
+		* closing a panel forgets its drag width — reopening restores the contract
+		* default. Actions are the complete write set: drag writes clamp
+		* into the panel's contract range and never cross the open/closed line;
+		* open/close transitions write 0 / the default explicitly. Below the
+		* auto-collapse breakpoint (AppFrame feeds setNarrow) the sidebar toggle
+		* flips the narrowExpanded override instead of the preference.
+		* @returns the store handle (spec + type + identity + factory in one).
+		*/
+		function createLayoutStore() {
+			return (0, _deepseek_ai_dsh_client_runtime_client.defineStore)({
+				init: () => ({
+					sidebar: 280,
+					details: 0,
+					narrow: false,
+					narrowExpanded: false
+				}),
+				actions: {
+					setSidebar: (d, px) => {
+						d.sidebar = clampWidth(px, 280, 420);
+					},
+					setDetails: (d, px) => {
+						d.details = clampWidth(px, 300, 520);
+					},
+					toggleSidebar: (d) => {
+						if (d.narrow) d.narrowExpanded = !d.narrowExpanded;
+						else d.sidebar = d.sidebar === 0 ? 280 : 0;
+					},
+					setNarrow: (d, narrow) => {
+						if (d.narrow === narrow) return;
+						d.narrow = narrow;
+						d.narrowExpanded = false;
+					},
+					openDetails: (d) => {
+						if (d.details === 0) d.details = 360;
+					},
+					closeDetails: (d) => {
+						d.details = 0;
+					}
+				}
+			});
+		}
+		//#endregion
+		//#region lib/types/client/service.js
+		/** Cross-plugin panel-action face (ctx.layout). */
+		var LayoutService = class {
+			#panels;
+			/**
+			* Adopt the root entry's bound store actions. Called from the root
+			* registration's inject hook (a sanctioned assembly side effect), so the
+			* face is live from the entry's first render; on entry re-register the
+			* fresh actions overwrite the stale set.
+			* @param actions - bound actions of the entry's layout store instance.
+			*/
+			attachPanels(actions) {
+				this.#panels = actions;
+			}
+			/** Toggle the sidebar panel (closed ⟷ contract default width). */
+			toggleSidebar() {
+				this.#require().toggleSidebar();
+			}
+			/** Open the details panel (no-op when already open). */
+			openDetails() {
+				this.#require().openDetails();
+			}
+			/** Close the details panel. */
+			closeDetails() {
+				this.#require().closeDetails();
+			}
+			#require() {
+				if (this.#panels === void 0) throw new Error("layout: panel actions not wired (root entry not mounted)");
+				return this.#panels;
+			}
+		};
+		//#endregion
+		//#region lib/types/client/theme-presenter.js
+		/** Body attribute selecting the dark base palette in the token stylesheets. */
+		const DARK_ATTRIBUTE = "data-ds-dark-theme";
+		/** Applies theme snapshots to the document; one instance per plugin fiber. */
+		var ThemePresenter = class {
+			/** Token names this presenter wrote in the last apply (its retraction set). */
+			appliedTokens = [];
+			/** The single metadata node this presenter inserts and removes. */
+			themeColorMeta;
+			/** Create the presenter-owned metadata node before the first snapshot arrives. */
+			constructor() {
+				this.themeColorMeta = document.createElement("meta");
+				this.themeColorMeta.name = "theme-color";
+			}
+			/**
+			* Project a snapshot onto the document: set root `color-scheme` and the body
+			* palette attribute from `active.colorScheme` (never the id — `system` is
+			* resolved upstream), then replace the previously applied token variables
+			* with `active.tokens`. Browser theme-color metadata follows the computed
+			* body background after those writes, so the rendered palette remains the
+			* color authority.
+			* @param snapshot - resolved theme snapshot from ctx.theme.
+			*/
+			apply(snapshot) {
+				const scheme = snapshot.active.colorScheme;
+				document.documentElement.style.colorScheme = scheme;
+				const body = document.body;
+				if (scheme === "dark") body.setAttribute(DARK_ATTRIBUTE, "");
+				else body.removeAttribute(DARK_ATTRIBUTE);
+				for (const name of this.appliedTokens) body.style.removeProperty(name);
+				this.appliedTokens = [];
+				for (const [name, value] of Object.entries(snapshot.active.tokens)) {
+					body.style.setProperty(name, value);
+					this.appliedTokens.push(name);
+				}
+				this.themeColorMeta.content = getComputedStyle(body).backgroundColor;
+				if (!this.themeColorMeta.isConnected) document.head.append(this.themeColorMeta);
+			}
+			/** Retract root color-scheme, the palette attribute, token variables, and the owned metadata node. */
+			dispose() {
+				document.documentElement.style.removeProperty("color-scheme");
+				const body = document.body;
+				body.removeAttribute(DARK_ATTRIBUTE);
+				for (const name of this.appliedTokens) body.style.removeProperty(name);
+				this.appliedTokens = [];
+				this.themeColorMeta.remove();
+			}
+		};
+		//#endregion
+		//#region lib/types/client/index.js
+		/** Required services (cordis fiber inject — the loader passes the whole export surface as an object plugin). */
+		const inject = ["slots", "theme"];
+		/**
+		* Client plugin body: provide ctx.layout, then one register() call — AppFrame
+		* into 'root' with the four child-slot declarations, the layout store seat,
+		* and the inject hook that hands the store's bound actions to the service.
+		* @param ctx - client root context.
+		*/
+		function apply(ctx) {
+			const layout = new LayoutService();
+			ctx.effect(() => {
+				const disposeService = ctx.reflect.provide("layout", layout);
+				const disposeRegistration = ctx.slots.register({
+					name: "root",
+					children: {
+						"sidebar": {
+							kind: "single",
+							scope: "root"
+						},
+						"conversation": {
+							kind: "single",
+							scope: "session-maybe"
+						},
+						"details": {
+							kind: "single",
+							scope: "session"
+						}
+					},
+					store: createLayoutStore,
+					inject: (actions) => {
+						layout.attachPanels(actions);
+						return {};
+					}
+				}, AppFrame);
+				return () => {
+					disposeRegistration();
+					disposeService();
+				};
+			}, "ui-layout: service + root registration");
+			ctx.effect(() => {
+				const presenter = new ThemePresenter();
+				presenter.apply(ctx.theme.getTheme());
+				const off = ctx.on("theme/change", (snapshot) => {
+					presenter.apply(snapshot);
+				});
+				return () => {
+					off();
+					presenter.dispose();
+				};
+			}, "ui-layout: theme presenter");
+		}
+		//#endregion
+		exports.LayoutService = LayoutService;
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/index.js

@@ -0,0 +1,6 @@
+//#region lib/types/index.js
+/** Host loader entry for the browser-only layout plugin. */
+/** Provides no host-side behavior. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-layout`.
+* @module @deepseek-ai/dsh-client-ui-layout/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-client-ui-layout";
+/** Cordis companion plugin name. */
+const name = "client-ui-layout-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the shell viewing-state store behind ctx.layout emits
+* no cordis events; clamp/prune/concession-chain
+* sequencing is asserted directly by this package's columns and service specs.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/client/AppFrame.d.ts

@@ -0,0 +1,7 @@
+import type { PropsRenderSlots, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots';
+import type { createLayoutStore } from './stores.ts';
+/** Full composed props: runtime share + child-slot render share + store share. */
+export type AppFrameProps = PropsRuntime<'root'> & PropsRenderSlots<'sidebar' | 'conversation' | 'details'> & PropsStore<ReturnType<typeof createLayoutStore>>;
+/** The three-column frame (see module doc). */
+export declare function AppFrame({ useStore, useSessions, actions, renderSlot, }: AppFrameProps): import("react").JSX.Element;
+//# sourceMappingURL=AppFrame.d.ts.map

package/lib/types/client/columns.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure concession-chain column solver for the three-column AppFrame.
+ * Chain order is fixed by contract: keep center >= CENTER_MIN by shrinking
+ * details, then auto-closing it (derived zero width — preferred width
+ * preferences are never rewritten, so widening the window restores them).
+ * The sidebar never concedes: its rendered width is always the drag
+ * preference (or the collapsed rail), and center absorbs any remaining
+ * deficit as the last resort. Inputs are the layout store's plain width
+ * preferences (0 = closed); a closed sidebar resolves to the fixed
+ * SIDEBAR_COLLAPSED control rail while closed details resolve to zero width.
+ * The SIDEBAR_AUTO_COLLAPSE breakpoint is consumed by AppFrame, which decides
+ * the effective sidebar preference before solving; the solver itself stays
+ * breakpoint-free.
+ */
+/** Resolved widths for one frame; center may drop below CENTER_MIN only at the final fallback. */
+export interface Columns {
+    sidebar: number;
+    center: number;
+    details: number;
+}
+/** Center column floor; only the final fallback may go below it. */
+export declare const CENTER_MIN = 640;
+/** Sidebar drag clamp floor. */
+export declare const SIDEBAR_MIN = 280;
+/** Sidebar drag clamp ceiling. */
+export declare const SIDEBAR_MAX = 420;
+/** Sidebar width before any user drag (= the drag floor). */
+export declare const SIDEBAR_DEFAULT = 280;
+/** Closed-sidebar rail: a 24px icon column between 16px horizontal paddings. */
+export declare const SIDEBAR_COLLAPSED = 56;
+/** Viewport width below which the sidebar auto-collapses to the rail (deepsuite
+ * LG breakpoint); a manual toggle below it re-expands over the squeezed center
+ * (stores.ts narrowExpanded). */
+export declare const SIDEBAR_AUTO_COLLAPSE = 1024;
+/** Details drag clamp floor. */
+export declare const DETAILS_MIN = 300;
+/** Details drag clamp ceiling. */
+export declare const DETAILS_MAX = 520;
+/** Details width before any user drag. */
+export declare const DETAILS_DEFAULT = 360;
+/**
+ * Clamp a panel width into its contract range.
+ * @param px - requested width.
+ * @param min - range lower bound.
+ * @param max - range upper bound.
+ * @returns the clamped width.
+ */
+export declare function clampWidth(px: number, min: number, max: number): number;
+/**
+ * Solve the three column widths for one viewport frame. Pure: no hysteresis —
+ * the output is a function of (viewport, preferences) only, so recovery on
+ * re-widening is automatic. Preferences re-clamp here because they cross the
+ * store boundary and callers may still supply stale ranges.
+ * @param viewport - available frame width in px.
+ * @param sidebar - sidebar width preference in px (0 = closed).
+ * @param details - details width preference in px (0 = closed).
+ * @returns resolved widths; details 0 means visually closed (never unmounted), while a closed sidebar keeps its compact rail.
+ */
+export declare function computeColumns(viewport: number, sidebar: number, details: number): Columns;
+//# sourceMappingURL=columns.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Layout plugin, browser half: one register() call contributes AppFrame into
+ * the runtime's built-in 'root' slot and, in the same breath, declares the
+ * four child slots (declaration = exclusive render authority), seats the
+ * layout store (panel geometry), and wires the panel-action service face.
+ * ctx.layout is the cross-plugin panel-action contract; navigation state lives
+ * with the runtime sessions service. A second effect seats the theme
+ * presenter, which projects ctx.theme snapshots onto document.body.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+export { LayoutService } from './service.ts';
+export type { ILayout } from './service.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** The outward face only; the concrete service stays inside this plugin. */
+        layout: import('./service.ts').ILayout;
+    }
+}
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface SlotMap {
+        'sidebar': {
+            kind: 'single';
+            scope: 'root';
+            owner: SidebarOwnerProps;
+        };
+        'conversation': {
+            kind: 'single';
+            scope: 'session-maybe';
+            owner: ConvOwnerProps;
+        };
+        'details': {
+            kind: 'single';
+            scope: 'session';
+            owner: DetailsOwnerProps;
+        };
+    }
+}
+/** Sidebar owner share: live column state from the frame's concession solve. */
+export interface SidebarOwnerProps {
+    /** True when the sidebar is closed (the column renders the compact control rail). */
+    collapsed: boolean;
+    /** Rendered column width in px (SIDEBAR_COLLAPSED when collapsed). */
+    width: number;
+}
+/** Conversation owner share: business state and actions belong to the registrant. */
+export interface ConvOwnerProps {
+}
+/** Details owner share: empty — sessionId arrives as a framework-standard prop. */
+export interface DetailsOwnerProps {
+}
+/** Required services (cordis fiber inject — the loader passes the whole export surface as an object plugin). */
+export declare const inject: string[];
+/**
+ * Client plugin body: provide ctx.layout, then one register() call — AppFrame
+ * into 'root' with the four child-slot declarations, the layout store seat,
+ * and the inject hook that hands the store's bound actions to the service.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/service.d.ts

@@ -0,0 +1,47 @@
+/**
+ * LayoutService: the cross-plugin panel-action face behind ctx.layout.
+ * Panel geometry itself lives in the root entry's layout store (stores.ts);
+ * the current-session selection lives with the runtime sessions service, and
+ * the per-session active view dissolved into ui-conversation's session store
+ * (its only consumer). What remains here is the contract other plugins'
+ * apply worlds reach for panel transitions (sidebar toggle from ui-sidebar,
+ * details open/close from ui-conversation) — writes stay inside the store's
+ * declared action set, delivered as the registration's bound actions.
+ */
+import type { BoundActions } from '@deepseek-ai/dsh-client-ui-slots';
+import type { createLayoutStore } from './stores.ts';
+/** The layout store's bound action set (framework-baked, draft params peeled). */
+export type PanelActions = BoundActions<ReturnType<typeof createLayoutStore>>;
+/**
+ * The outward layout face (`ctx.layout`): the panel transitions other
+ * plugins may trigger — and exactly what a test fake must supply. The
+ * attachPanels wiring hook stays on the concrete class (root-entry assembly
+ * only).
+ */
+export interface ILayout {
+    /** Toggle the sidebar panel (closed ⟷ contract default width). */
+    toggleSidebar(): void;
+    /** Open the details panel (no-op when already open). */
+    openDetails(): void;
+    /** Close the details panel. */
+    closeDetails(): void;
+}
+/** Cross-plugin panel-action face (ctx.layout). */
+export declare class LayoutService implements ILayout {
+    #private;
+    /**
+     * Adopt the root entry's bound store actions. Called from the root
+     * registration's inject hook (a sanctioned assembly side effect), so the
+     * face is live from the entry's first render; on entry re-register the
+     * fresh actions overwrite the stale set.
+     * @param actions - bound actions of the entry's layout store instance.
+     */
+    attachPanels(actions: PanelActions): void;
+    /** Toggle the sidebar panel (closed ⟷ contract default width). */
+    toggleSidebar(): void;
+    /** Open the details panel (no-op when already open). */
+    openDetails(): void;
+    /** Close the details panel. */
+    closeDetails(): void;
+}
+//# sourceMappingURL=service.d.ts.map

package/lib/types/client/stores.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The root entry's transient layout store: panel geometry as plain widths in
+ * px (0 = closed). Module level exports the factory only — a module-level
+ * handle would pin the store's identity in the module
+ * cache (a de-facto singleton surviving plugin reloads). register() receives
+ * the factory (exclusive use: the framework instantiates per entry), AppFrame
+ * derives its PropsStore share from the return type, and the service face
+ * receives the bound actions through the registration's inject hook.
+ */
+import { type EngineStoreHandle } from '@deepseek-ai/dsh-client-runtime/client';
+/**
+ * Layout store state: panel width preferences in px (0 = closed), plus the
+ * narrow-viewport pair — `narrow` mirrors AppFrame's breakpoint reading
+ * (viewport < SIDEBAR_AUTO_COLLAPSE) so toggleSidebar can pick semantics, and
+ * `narrowExpanded` is the manual override that re-expands the auto-collapsed
+ * sidebar over the squeezed center without rewriting the width preference.
+ */
+type LayoutState = {
+    sidebar: number;
+    details: number;
+    narrow: boolean;
+    narrowExpanded: boolean;
+};
+/**
+ * Annotation twin of the actions literal below (the export needs a declared
+ * return type); drift fails assignability at the defineStore call.
+ */
+type LayoutActions = {
+    setSidebar: (draft: LayoutState, px: number) => void;
+    setDetails: (draft: LayoutState, px: number) => void;
+    toggleSidebar: (draft: LayoutState) => void;
+    setNarrow: (draft: LayoutState, narrow: boolean) => void;
+    openDetails: (draft: LayoutState) => void;
+    closeDetails: (draft: LayoutState) => void;
+};
+/**
+ * Create the layout panel store handle. The preference IS the width, so
+ * closing a panel forgets its drag width — reopening restores the contract
+ * default. Actions are the complete write set: drag writes clamp
+ * into the panel's contract range and never cross the open/closed line;
+ * open/close transitions write 0 / the default explicitly. Below the
+ * auto-collapse breakpoint (AppFrame feeds setNarrow) the sidebar toggle
+ * flips the narrowExpanded override instead of the preference.
+ * @returns the store handle (spec + type + identity + factory in one).
+ */
+export declare function createLayoutStore(): EngineStoreHandle<LayoutState, LayoutActions>;
+export {};
+//# sourceMappingURL=stores.d.ts.map

package/lib/types/client/theme-presenter.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Global theme DOM applier: projects the resolved ThemeSnapshot onto the
+ * document — `html { color-scheme }` for native UA chrome (scrollbars, form
+ * controls), `body[data-ds-dark-theme]` for the token palette, the active
+ * theme's alias-token overrides as inline CSS variables on body, and one
+ * presenter-owned `meta[name="theme-color"]` for surrounding browser UI. Pure
+ * DOM writes, no React involvement; the presenter only ever retracts what it
+ * wrote itself, so foreign attributes, metadata, and inline styles survive.
+ */
+import type { ThemeSnapshot } from '@deepseek-ai/dsh-client-ui-theme/client';
+/** Body attribute selecting the dark base palette in the token stylesheets. */
+export declare const DARK_ATTRIBUTE = "data-ds-dark-theme";
+/** Applies theme snapshots to the document; one instance per plugin fiber. */
+export declare class ThemePresenter {
+    /** Token names this presenter wrote in the last apply (its retraction set). */
+    private appliedTokens;
+    /** The single metadata node this presenter inserts and removes. */
+    private readonly themeColorMeta;
+    /** Create the presenter-owned metadata node before the first snapshot arrives. */
+    constructor();
+    /**
+     * Project a snapshot onto the document: set root `color-scheme` and the body
+     * palette attribute from `active.colorScheme` (never the id — `system` is
+     * resolved upstream), then replace the previously applied token variables
+     * with `active.tokens`. Browser theme-color metadata follows the computed
+     * body background after those writes, so the rendered palette remains the
+     * color authority.
+     * @param snapshot - resolved theme snapshot from ctx.theme.
+     */
+    apply(snapshot: ThemeSnapshot): void;
+    /** Retract root color-scheme, the palette attribute, token variables, and the owned metadata node. */
+    dispose(): void;
+}
+//# sourceMappingURL=theme-presenter.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Host loader entry for the browser-only layout plugin. */
+/** Provides no host-side behavior. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-layout`.
+ * @module @deepseek-ai/dsh-client-ui-layout/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-ui-layout-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-layout",
+  "description": "Shell plugin: three-column AppFrame with drag handles, ctx.layout viewing-state service (navigation + panels)",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-layout"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-theme"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-theme": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-theme": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}