@deepseek-ai/dsh-client-ui-settings 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-settings/README.md
+README.md: 785f0417f00ec8eb1f8c9273b4d81f8ca5ca1810
+README.zh.md: 239987e379aaabd2edbfc9e09cd2fc8cef7a685e

package/README.md

@@ -0,0 +1,19 @@
+# @deepseek-ai/dsh-client-ui-settings
+
+English | [中文](README.zh.md)
+
+Settings shell plugin: a pure composition face. It occupies `sidebar.settings` with the trigger chrome and modal settings panel, and declares the slots registrants fill: `settings.trigger` / `settings.header` / `settings.close` (chrome content), `settings.action` (ordered content-header actions), `settings.section` (one page per feature), and `settings.onboarding` (ordered feature-owned pages in a full-viewport stage). The shell ships no copy of its own — all text arrives from registrants (ui-settings-general owns chrome, General, and the product notice; features own their actions, sections, rows, and conditional onboarding pages). Nav labels may be locale-following thunks, so the nav projection resolves them through `resolveSlotLabel` and re-renders on the section ledger bump or the locale revision (an optional `ctx.get('locale')` read; no hard locale dependency).
+
+The shell projects the onboarding ledger into ascending order and mounts exactly one page at a time; the takeover chrome (body-level stage, mask, app-root `inert`) belongs to the step itself through ui-primitives' `OnboardingSurface`, so a mounted step still resolving its private facts renders null and neither paints nor blocks anything — the shell shows no empty stage while a step decides. The active registrant receives its id, `complete()`, and an `openSection(id)` callback; completing or skipping transfers ownership to the next entry. Registrants own durable completion, capability readiness, copy, mutations, and the surface wrap, so independently registered flows cannot stack and the shell does not become a second configuration fact source.
+
+## Model Experience
+
+None, as the settings shell serves browser UI composition; 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 is browser-preference scope only** — host-side settings surfaces (permission mode, tool-call mode) have no RPC backing yet; their skeletons live in ui-settings-general.

package/README.zh.md

@@ -0,0 +1,19 @@
+# @deepseek-ai/dsh-client-ui-settings
+
+[English](README.md) | 中文
+
+设置外壳插件：一个纯组合表层。它以触发控件和模态设置面板占用 `sidebar.settings`，并声明由注册方填充的 slot：`settings.trigger`／`settings.header`／`settings.close`（界面框架内容）、`settings.action`（内容标题栏中的有序操作）、`settings.section`（每项功能一页）和 `settings.onboarding`（由各功能持有、显示在全视口展示层中的有序页面）。外壳不自带文案：所有文本都来自注册方（ui-settings-general 拥有界面框架、「通用」分区和产品声明；各功能拥有各自的操作、分区、行和条件式首次使用引导页面）。导航 label 可以是跟随语言的 thunk，因此导航投影经 `resolveSlotLabel` 解析，并在分区账本更新或 locale revision 变化时重新渲染（`ctx.get('locale')` 可选读取，无硬 locale 依赖）。
+
+外壳将首次使用引导记录按升序投影，每次只挂载一个页面；接管界面框架（body 层级的展示层、遮罩、应用根节点 `inert`）经 ui-primitives 的 `OnboardingSurface` 由步骤自身持有，因此已挂载但仍在判定私有事实的步骤渲染 null 时不绘制也不阻塞任何内容——步骤判定期间外壳不会露出空白展示层。当前注册方会收到该条目的 id、`complete()` 和 `openSection(id)` 回调；完成或跳过当前页面后，所有权转交给下一项。持久化完成状态、能力就绪状态、文案、变更操作以及展示层包装均由注册方持有，因此独立注册的流程无法堆叠，外壳也不会成为第二个配置事实来源。
+
+## 模型体验
+
+无。设置外壳为浏览器 UI 提供组合能力；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **面板仅涵盖浏览器偏好设置**：宿主侧设置表层（权限模式、工具调用模式）尚无 RPC 支撑；其骨架位于 ui-settings-general。

package/lib/client.js

@@ -0,0 +1,326 @@
+window.__ModuleLoader__.load({
+	id: "@deepseek-ai/dsh-client-ui-settings",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let _deepseek_ai_dsh_client_ui_slots = require("@deepseek-ai/dsh-client-ui-slots");
+		let react_jsx_runtime = require("react/jsx-runtime");
+		let react = require("react");
+		let _deepseek_ai_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
+		//#region ../../../node_modules/.pnpm/clsx@2.1.1/node_modules/clsx/dist/clsx.mjs
+		function r(e) {
+			var t, f, n = "";
+			if ("string" == typeof e || "number" == typeof e) n += e;
+			else if ("object" == typeof e) if (Array.isArray(e)) {
+				var o = e.length;
+				for (t = 0; t < o; t++) e[t] && (f = r(e[t])) && (n && (n += " "), n += f);
+			} else for (f in e) e[f] && (n && (n += " "), n += f);
+			return n;
+		}
+		function clsx() {
+			for (var e, t, f = 0, n = "", o = arguments.length; f < o; f++) (e = arguments[f]) && (t = r(e)) && (n && (n += " "), n += t);
+			return n;
+		}
+		//#endregion
+		//#region \0dsh-css:/home/runner/work/deepseek-harness/deepseek-harness/packages/client/ui-settings/src/client/SettingsRoot.module.css.mjs
+		const css = ".Gph0iW_trigger{cursor:pointer;width:100%;height:49px;color:var(--dsw-alias-label-primary);background:0 0;border:none;border-radius:12px;flex:none;align-items:center;gap:8px;margin:8px 0 0;padding:0 2px 0 6px;font-family:inherit;font-size:14px;display:flex;overflow:hidden}.Gph0iW_trigger:hover{background:var(--dsw-alias-interactive-bg-hover)}.Gph0iW_trigger.Gph0iW_rail{border-radius:50%;justify-content:center;gap:0;width:36px;height:36px;margin:18px 0 10px;padding:0}.Gph0iW_triggerLabel{white-space:nowrap;overflow:hidden}.Gph0iW_overlay{z-index:1000;justify-content:center;align-items:center;display:flex;position:fixed;inset:0}.Gph0iW_mask{background:var(--dsw-alias-bg-mask-1);backdrop-filter:var(--dsw-mask-blur);position:absolute;inset:0}.Gph0iW_panel{z-index:1;background:var(--dsw-alias-bg-layer-2);width:800px;max-width:calc(100vw - 48px);height:min(800px,100vh - 48px);box-shadow:var(--dsw-shadow-lv3);--dsh-scrollbar-thumb:var(--dsw-alias-scrollbar-bg-l2);--dsh-scrollbar-thumb-hover:var(--dsw-alias-scrollbar-hover-l2);border-radius:24px;display:flex;position:relative;overflow:hidden}.Gph0iW_nav{box-sizing:border-box;flex-direction:column;flex:none;gap:18px;width:188px;padding:22px 12px 0;display:flex}.Gph0iW_navTitle{color:var(--dsw-alias-label-primary);padding:0 12px;font-size:16px;font-weight:500;line-height:24px}.Gph0iW_navList{flex-direction:column;gap:4px;display:flex}.Gph0iW_navCell{box-sizing:border-box;cursor:pointer;height:40px;color:var(--dsw-alias-label-primary);text-align:left;background:0 0;border:none;border-radius:12px;align-items:center;gap:8px;padding:9px 16px 9px 12px;font-family:inherit;font-size:14px;font-weight:400;line-height:22px;display:flex}.Gph0iW_navCell:hover{background:var(--dsw-specific-sidebar-nav-item-hover)}.Gph0iW_navCell.Gph0iW_active{background:var(--dsw-specific-sidebar-nav-item-active)}.Gph0iW_navIcon{flex:none}.Gph0iW_navLabel{white-space:nowrap;text-overflow:ellipsis;flex:1;min-width:0;overflow:hidden}.Gph0iW_content{flex-direction:column;flex:1;min-width:0;display:flex}.Gph0iW_header{box-sizing:border-box;flex:none;justify-content:space-between;align-items:flex-start;gap:8px;height:54px;padding:20px 14px 8px 10px;display:flex}.Gph0iW_actions{justify-content:flex-end;align-items:center;gap:8px;min-width:0;margin-left:auto;display:flex}.Gph0iW_close{cursor:pointer;width:28px;height:28px;color:var(--dsw-alias-label-primary);background:0 0;border:none;border-radius:28px;justify-content:center;align-items:center;padding:0;display:inline-flex}.Gph0iW_close:hover{background:var(--dsw-alias-interactive-bg-hover)}.Gph0iW_options{flex:1;min-height:0;padding:0 24px 8px;overflow-y:auto}.Gph0iW_hiddenLabel{clip:rect(0 0 0 0);white-space:nowrap;width:1px;height:1px;position:absolute;overflow:hidden}";
+		const tagId = "@deepseek-ai/dsh-client-ui-settings/SettingsRoot.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-settings";
+			tag.dataset.pluginCss = tagId;
+			tag.textContent = css;
+			document.head.appendChild(tag);
+		}
+		var SettingsRoot_module_css_default = {
+			"hiddenLabel": "Gph0iW_hiddenLabel",
+			"active": "Gph0iW_active",
+			"panel": "Gph0iW_panel",
+			"navList": "Gph0iW_navList",
+			"header": "Gph0iW_header",
+			"nav": "Gph0iW_nav",
+			"trigger": "Gph0iW_trigger",
+			"navCell": "Gph0iW_navCell",
+			"content": "Gph0iW_content",
+			"rail": "Gph0iW_rail",
+			"overlay": "Gph0iW_overlay",
+			"navTitle": "Gph0iW_navTitle",
+			"triggerLabel": "Gph0iW_triggerLabel",
+			"mask": "Gph0iW_mask",
+			"navIcon": "Gph0iW_navIcon",
+			"actions": "Gph0iW_actions",
+			"close": "Gph0iW_close",
+			"navLabel": "Gph0iW_navLabel",
+			"options": "Gph0iW_options"
+		};
+		//#endregion
+		//#region lib/types/client/SettingsRoot.js
+		/**
+		* Settings shell root: the sidebar-foot trigger row plus the centered modal
+		* panel (figma 501:29947, 1080x700) with the section nav rail. The shell is
+		* a pure composition face — every piece of text (trigger label, panel title,
+		* close label, sections) arrives from registrants through slots; accessible
+		* names resolve to that content (trigger: its own text; dialog:
+		* aria-labelledby the title node; close: visually-hidden slot text). Modal
+		* open state and the active section id are component-local viewing state;
+		* the onboarding coordinator mounts exactly one ordered registrant while the
+		* sessions-derived empty-Hero fact is active — the takeover chrome
+		* (OnboardingSurface) belongs to the step, so a mounted-but-deciding step
+		* paints nothing here.
+		*/
+		/** Nav glyph by section id; unknown ids fall back to the settings gear. */
+		function navIcon(id) {
+			if (id === "models") return (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconDataOutline16, {
+				className: SettingsRoot_module_css_default.navIcon,
+				size: 16
+			});
+			if (id === "agent-presets") return (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconThinkOutline16, {
+				className: SettingsRoot_module_css_default.navIcon,
+				size: 16
+			});
+			return (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconSettingsOutline16, {
+				className: SettingsRoot_module_css_default.navIcon,
+				size: 16
+			});
+		}
+		/**
+		* The modal layer: full-viewport mask + centered panel. Close paths: the
+		* header button, a mask click, and document-level Escape (mounted only while
+		* open, so the listener lifetime is the panel's).
+		*/
+		function SettingsPanel({ rows, renderSlot, activeId, onSelect, onClose }) {
+			const active = rows.find((r) => r.id === activeId)?.id ?? rows[0]?.id;
+			const titleId = (0, react.useId)();
+			(0, react.useEffect)(() => {
+				const onKeyDown = (e) => {
+					if (e.key === "Escape") onClose();
+				};
+				document.addEventListener("keydown", onKeyDown);
+				return () => {
+					document.removeEventListener("keydown", onKeyDown);
+				};
+			}, [onClose]);
+			const closeButton = (0, react.useRef)(null);
+			(0, react.useEffect)(() => {
+				closeButton.current?.focus();
+			}, []);
+			return (0, react_jsx_runtime.jsxs)("div", {
+				className: SettingsRoot_module_css_default.overlay,
+				role: "presentation",
+				children: [(0, react_jsx_runtime.jsx)("div", {
+					className: SettingsRoot_module_css_default.mask,
+					"aria-hidden": "true",
+					onClick: onClose
+				}), (0, react_jsx_runtime.jsxs)("div", {
+					className: SettingsRoot_module_css_default.panel,
+					role: "dialog",
+					"aria-modal": "true",
+					"aria-labelledby": titleId,
+					children: [(0, react_jsx_runtime.jsxs)("nav", {
+						className: SettingsRoot_module_css_default.nav,
+						children: [(0, react_jsx_runtime.jsx)("div", {
+							className: SettingsRoot_module_css_default.navTitle,
+							id: titleId,
+							children: renderSlot("settings.header", {})
+						}), (0, react_jsx_runtime.jsx)("div", {
+							className: SettingsRoot_module_css_default.navList,
+							children: rows.map((row) => (0, react_jsx_runtime.jsxs)("button", {
+								type: "button",
+								className: clsx(SettingsRoot_module_css_default.navCell, row.id === active && SettingsRoot_module_css_default.active),
+								"aria-current": row.id === active ? "true" : void 0,
+								onClick: () => {
+									onSelect(row.id);
+								},
+								children: [navIcon(row.id), (0, react_jsx_runtime.jsx)("span", {
+									className: SettingsRoot_module_css_default.navLabel,
+									children: row.label
+								})]
+							}, row.id))
+						})]
+					}), (0, react_jsx_runtime.jsxs)("div", {
+						className: SettingsRoot_module_css_default.content,
+						children: [(0, react_jsx_runtime.jsxs)("div", {
+							className: SettingsRoot_module_css_default.header,
+							children: [(0, react_jsx_runtime.jsx)("div", {
+								className: SettingsRoot_module_css_default.actions,
+								children: renderSlot("settings.action", {})
+							}), (0, react_jsx_runtime.jsxs)("button", {
+								ref: closeButton,
+								type: "button",
+								className: SettingsRoot_module_css_default.close,
+								onClick: onClose,
+								children: [(0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconCloseOutline16, { size: 14 }), (0, react_jsx_runtime.jsx)("span", {
+									className: SettingsRoot_module_css_default.hiddenLabel,
+									children: renderSlot("settings.close", {})
+								})]
+							})]
+						}), (0, react_jsx_runtime.jsx)("div", {
+							className: SettingsRoot_module_css_default.options,
+							children: active !== void 0 && renderSlot("settings.section", { close: onClose }, { only: active })
+						})]
+					})]
+				})]
+			});
+		}
+		/**
+		* Render the settings trigger and panel.
+		* @param props - composed slot props (contract/slots.ts).
+		* @returns the settings shell element tree.
+		*/
+		function SettingsRoot(props) {
+			const { wide, useSections, useOnboardingSteps, useSessions, renderSlot } = props;
+			const [open, setOpen] = (0, react.useState)(false);
+			const [activeId, setActiveId] = (0, react.useState)(void 0);
+			const [completedOnboarding, setCompletedOnboarding] = (0, react.useState)(() => /* @__PURE__ */ new Set());
+			const close = (0, react.useCallback)(() => {
+				setOpen(false);
+				setActiveId(void 0);
+			}, []);
+			const openSection = (0, react.useCallback)((id) => {
+				setActiveId(id);
+				setOpen(true);
+			}, []);
+			const rows = useSections((s) => s);
+			const onboardingSteps = useOnboardingSteps((s) => s);
+			const onboardingActive = useSessions((state) => state.phase === "ready" && (state.current === void 0 || state.byId[state.current]?.blank === true));
+			const onboardingStep = onboardingActive ? onboardingSteps.find((step) => !completedOnboarding.has(step.id)) : void 0;
+			(0, react.useEffect)(() => {
+				if (onboardingActive) return;
+				setCompletedOnboarding(/* @__PURE__ */ new Set());
+			}, [onboardingActive]);
+			const completeOnboardingStep = (0, react.useCallback)((id) => {
+				setCompletedOnboarding((previous) => {
+					if (previous.has(id)) return previous;
+					return new Set([...previous, id]);
+				});
+			}, []);
+			return (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
+				(0, react_jsx_runtime.jsx)("button", {
+					type: "button",
+					className: clsx(SettingsRoot_module_css_default.trigger, !wide && SettingsRoot_module_css_default.rail),
+					"aria-haspopup": "dialog",
+					"aria-expanded": open,
+					onClick: () => {
+						setOpen(true);
+					},
+					children: renderSlot("settings.trigger", { wide })
+				}),
+				open && (0, react_jsx_runtime.jsx)(SettingsPanel, {
+					rows,
+					renderSlot,
+					activeId,
+					onSelect: setActiveId,
+					onClose: close
+				}),
+				onboardingStep !== void 0 && renderSlot("settings.onboarding", {
+					stepId: onboardingStep.id,
+					complete: () => {
+						completeOnboardingStep(onboardingStep.id);
+					},
+					openSection
+				}, { only: onboardingStep.id })
+			] });
+		}
+		//#endregion
+		//#region lib/types/client/index.js
+		/**
+		* Required services (cordis fiber inject). The target slot is declared by
+		* ui-sidebar's apply, whose activation order relative to this one is NOT
+		* constrained (dsh.client.inject edges are informational); registration
+		* depends on the slot through `slots.inject()`.
+		*/
+		const inject = ["slots"];
+		/**
+		* Register the settings shell into `sidebar.settings` once the declaration is
+		* on the ledger.
+		* @param ctx - client root context.
+		*/
+		function apply(ctx) {
+			let rowsVersion = -1;
+			let rowsRevision = -1;
+			let rows = [];
+			let onboardingVersion = -1;
+			let onboardingSteps = [];
+			const localeRevision = () => ctx.get("locale")?.getSnapshot().revision ?? 0;
+			const injected = () => ({ hooks: {
+				sections: {
+					getSnapshot: () => {
+						const version = ctx.slots.getVersion("settings.section");
+						const revision = localeRevision();
+						if (version !== rowsVersion || revision !== rowsRevision) {
+							rowsVersion = version;
+							rowsRevision = revision;
+							rows = ctx.slots.entries("settings.section").map((e) => ({
+								/* v8 ignore next -- list-slot registration requires id (SlotCore rejects an entry without one) */
+								id: e.options.id ?? "",
+								order: e.options.order ?? 0,
+								label: (0, _deepseek_ai_dsh_client_ui_slots.resolveSlotLabel)(e.options.label) ?? ""
+							})).sort((a, b) => a.order - b.order);
+						}
+						return rows;
+					},
+					subscribe: (listener) => {
+						const offLedger = ctx.slots.subscribe("settings.section", listener);
+						const offLocale = ctx.get("locale")?.subscribe(listener);
+						return () => {
+							offLedger();
+							offLocale?.();
+						};
+					}
+				},
+				onboardingSteps: {
+					getSnapshot: () => {
+						const version = ctx.slots.getVersion("settings.onboarding");
+						if (version !== onboardingVersion) {
+							onboardingVersion = version;
+							onboardingSteps = ctx.slots.entries("settings.onboarding").map((e) => ({
+								/* v8 ignore next -- list-slot registration requires id */
+								id: e.options.id ?? "",
+								order: e.options.order ?? 0
+							})).sort((a, b) => a.order - b.order);
+						}
+						return onboardingSteps;
+					},
+					subscribe: (listener) => ctx.slots.subscribe("settings.onboarding", listener)
+				}
+			} });
+			ctx.slots.inject("sidebar.settings", () => ctx.slots.register({
+				name: "sidebar.settings",
+				children: {
+					"settings.trigger": {
+						kind: "single",
+						scope: "root"
+					},
+					"settings.header": {
+						kind: "single",
+						scope: "root"
+					},
+					"settings.action": {
+						kind: "list",
+						scope: "root"
+					},
+					"settings.close": {
+						kind: "single",
+						scope: "root"
+					},
+					"settings.section": {
+						kind: "list",
+						scope: "root"
+					},
+					"settings.onboarding": {
+						kind: "list",
+						scope: "root"
+					}
+				},
+				inject: injected
+			}, SettingsRoot));
+		}
+		//#endregion
+		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 implementation exported from `./client`. */
+/** Host plugin body — no host-side behavior for the settings shell plugin. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-settings`.
+* @module @deepseek-ai/dsh-client-ui-settings/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-client-ui-settings";
+/** Cordis companion plugin name. */
+const name = "client-ui-settings-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: a presentation shell projecting the settings.section
+* ledger into navigation — it emits no cordis events and owns no cross-plugin
+* mutable relation; slot declaration/registration conflicts already fail loud
+* in the slot core at load time.
+*/
+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/SettingsRoot.d.ts

@@ -0,0 +1,8 @@
+import type { SettingsRootComponentProps } from './contract/slots.ts';
+/**
+ * Render the settings trigger and panel.
+ * @param props - composed slot props (contract/slots.ts).
+ * @returns the settings shell element tree.
+ */
+export declare function SettingsRoot(props: SettingsRootComponentProps): import("react").JSX.Element;
+//# sourceMappingURL=SettingsRoot.d.ts.map

package/lib/types/client/contract/slots.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Settings shell slot contract — the canonical home of every settings slot
+ * type. The shell is a pure composition face with zero copy of its own: it
+ * occupies the sidebar-owned `sidebar.settings` hole and declares the slots
+ * below; ALL text (trigger label, panel title, header actions, close aria,
+ * section content) arrives from registrants. A feature owns its settings surface — adding a
+ * setting never means editing the shell; copy that belongs to no single
+ * feature (chrome, the General section) is owned by ui-settings-general.
+ */
+import type { HostObservable, InjectFace, PropsRenderSlots, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface SlotMap {
+        /**
+         * The sidebar-foot trigger row content: icon + label, supplied as slot
+         * content (the accessible name comes from the content — rail state
+         * renders the label visually hidden). The shell renders the button
+         * chrome and owns open state. Absent contribution degrades to an
+         * icon-only button without an accessible name (broken-composition state;
+         * the shipped composition always registers the seat).
+         */
+        'settings.trigger': {
+            kind: 'single';
+            scope: 'root';
+            owner: SettingsTriggerOwnerProps;
+        };
+        /**
+         * The panel title text seat. Content renders inside the nav heading row;
+         * the dialog's accessible name points at that node via aria-labelledby.
+         * Absent contribution leaves the heading empty.
+         */
+        'settings.header': {
+            kind: 'single';
+            scope: 'root';
+            owner: SettingsHeaderOwnerProps;
+        };
+        /**
+         * Optional actions rendered in the content-column header before Close.
+         * Registrants own visibility, behavior, copy, and failure presentation;
+         * the shell supplies only the ordered render site.
+         */
+        'settings.action': {
+            kind: 'list';
+            scope: 'root';
+            owner: SettingsHeaderOwnerProps;
+        };
+        /**
+         * The close button's visually-hidden label text (the button itself —
+         * icon, geometry, focus — is shell chrome). Absent contribution leaves
+         * the button without an accessible name (broken-composition state).
+         */
+        'settings.close': {
+            kind: 'single';
+            scope: 'root';
+            owner: SettingsHeaderOwnerProps;
+        };
+        /**
+         * One settings page per list entry. Registrant options carry the nav
+         * identity: `id` (section key, drives `only` filtering), `order` (nav
+         * position), `label` (registrant-localized display text — the registrant
+         * re-registers with fresh text on locale change, so the shell never
+         * subscribes locale state; the ledger bump doubles as the shell's
+         * re-render trigger). Sections render inside the panel content column.
+         * (`settings.general.item`, declared by ui-settings-general's General
+         * entry, is typed in the locale package — the common dependency of every
+         * item registrant; the shell neither declares nor renders it.)
+         */
+        'settings.section': {
+            kind: 'list';
+            scope: 'root';
+            owner: SettingsSectionOwnerProps;
+        };
+        /**
+         * Root-scoped onboarding steps contributed by settings features. The
+         * shell mounts one ordered step at a time; the active registrant either
+         * completes itself or keeps ownership until the user completes its sole
+         * path. Registrants own readiness, copy, dialog behavior, AND the
+         * takeover chrome: a step wraps its visible content in the
+         * OnboardingSurface primitive (mask, opaque stage, `#root` inert) and
+         * renders null while its private facts are still loading — the shell
+         * paints no chrome of its own, so a mounted-but-deciding step shows and
+         * blocks nothing (prevents a white flash on reload: a bare unwrapped step
+         * would render without mask or stage).
+         */
+        'settings.onboarding': {
+            kind: 'list';
+            scope: 'root';
+            owner: SettingsOnboardingOwnerProps;
+        };
+    }
+}
+/** Owner share of the trigger content seat: the sidebar column state. */
+export interface SettingsTriggerOwnerProps {
+    /** Whether the sidebar renders wide content (false = 56px rail, icon only). */
+    wide: boolean;
+}
+/** Owner share of the header title seat (the shell supplies nothing). */
+export interface SettingsHeaderOwnerProps {
+    /** Marker field: header owner props are intentionally empty. */
+    children?: never;
+}
+/**
+ * Owner share of a settings section entry. The shell owns modal visibility
+ * and navigation; a section's data arrives through its own inject faces and
+ * stores. `close` is the one shell affordance a section receives, for flows
+ * that leave settings altogether (starting a session from a section) — the
+ * onboarding coordinator's `openSection`/`complete` precedent, inverted.
+ */
+export interface SettingsSectionOwnerProps {
+    /** Close the settings panel (the shell owns the open state). */
+    close: () => void;
+}
+/** Owner share of the currently active settings-backed onboarding step. */
+export interface SettingsOnboardingOwnerProps {
+    /** Stable id of the step currently selected by the coordinator. */
+    stepId: string;
+    /** Complete or skip this step and transfer ownership to the next entry. */
+    complete: () => void;
+    /** Open the settings panel directly on one registered section. */
+    openSection: (id: string) => void;
+}
+/** One nav row projected from a settings.section registration's options. */
+export interface SettingsSectionRow {
+    id: string;
+    order: number;
+    label: string;
+}
+/** One ordered onboarding step projected from a slot registration. */
+export interface SettingsOnboardingStep {
+    id: string;
+    order: number;
+}
+/**
+ * Registrant-private injected share of the settings shell (assembled in
+ * apply): the ledger's nav-row projection as a hooks-compartment source —
+ * the shell reads no locale state and subscribes through the bound hook.
+ */
+export type SettingsRootInjected = {
+    hooks: {
+        /** settings.section ledger projected into ordered nav rows. */
+        sections: HostObservable<readonly SettingsSectionRow[]>;
+        /** settings.onboarding ledger projected into coordinator order. */
+        onboardingSteps: HostObservable<readonly SettingsOnboardingStep[]>;
+    };
+};
+/**
+ * Full component props of the settings shell root: the sidebar owner share
+ * (wide/rail state) plus the declared render shares and the injected face
+ * (hooks compartment bound to useSections). No store is registered — modal
+ * open state and active section id are component-local viewing state.
+ */
+export type SettingsRootComponentProps = PropsRuntime<'sidebar.settings'> & PropsRenderSlots<'settings.trigger' | 'settings.header' | 'settings.action' | 'settings.close' | 'settings.section' | 'settings.onboarding'> & InjectFace<SettingsRootInjected>;
+//# sourceMappingURL=slots.d.ts.map

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

@@ -0,0 +1,25 @@
+/**
+ * Settings shell plugin, browser half. A pure composition face: occupies the
+ * sidebar-owned `sidebar.settings` hole with the trigger chrome + modal
+ * panel, declares its chrome, section, and onboarding slots, and projects the
+ * section ledger into panel navigation. The shell ships no copy; it reads the
+ * optional locale revision only to resolve registrant-owned nav-label thunks.
+ * ui-settings-general owns the chrome and General content; features own their
+ * rows, sections, and onboarding pages. Export discipline: packages/client/AGENTS.md.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+export type { SettingsHeaderOwnerProps, SettingsRootComponentProps, SettingsRootInjected, SettingsOnboardingOwnerProps, SettingsOnboardingStep, SettingsSectionOwnerProps, SettingsSectionRow, SettingsTriggerOwnerProps, } from './contract/slots.ts';
+/**
+ * Required services (cordis fiber inject). The target slot is declared by
+ * ui-sidebar's apply, whose activation order relative to this one is NOT
+ * constrained (dsh.client.inject edges are informational); registration
+ * depends on the slot through `slots.inject()`.
+ */
+export declare const inject: string[];
+/**
+ * Register the settings shell into `sidebar.settings` once the declaration is
+ * on the ledger.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Host loader entry for the browser implementation exported from `./client`. */
+/** Host plugin body — no host-side behavior for the settings shell plugin. */
+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-settings`.
+ * @module @deepseek-ai/dsh-client-ui-settings/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-ui-settings-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,77 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-settings",
+  "description": "Settings shell plugin: sidebar trigger, modal panel, feature sections, and an ordered full-page onboarding stage",
+  "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-settings"
+  },
+  "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-sidebar"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "clsx": "^2.0.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@types/react-dom": "~18.3.0",
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@deepseek-ai/dsh-client-locale": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^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"
+  }
+}