@qilin-agent/client-ui-account 0.0.0-stage → 3.1.4

package/LICENSE

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

@@ -0,0 +1,34 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/ui-account/README.md
+/:
+  en: 745f3bb029ae3a78
+  zh: ae8a5ee520f28f85
+/qilin-agent-client-ui-account:
+  en: 612cafd6a0630fe0
+  zh: f4fbc88c6a82302e
+/qilin-agent-client-ui-account/summary:
+  en: 4561df8d1dc63d4c
+  zh: d54d893571090b7f
+/qilin-agent-client-ui-account/table-of-contents:
+  en: 76368b6b1da79c80
+  zh: 52384aee991ac542
+/qilin-agent-client-ui-account/use-this-package:
+  en: af042f14e4c37707
+  zh: fcea82ad20718480
+/qilin-agent-client-ui-account/understand-the-implementation:
+  en: 660a673252b8b067
+  zh: 5ee8c0f9e9516c21
+/qilin-agent-client-ui-account/model-experience:
+  en: 21ae98ac31e1c62a
+  zh: b7e2842cbcec0851
+/qilin-agent-client-ui-account/model-experience/kv-cache-effect:
+  en: 2a2706075f9729cd
+  zh: 91f306246e59762c
+/qilin-agent-client-ui-account/known-limitations-and-deferred-work:
+  en: 3c5eb8128c5f064b
+  zh: da5bebdc9da2b5d5
+/qilin-agent-client-ui-account/known-limitations-and-deferred-work/dev-note:
+  en: ec656e8eba292940
+  zh: 52d3225942ce28e7

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+---
+description: "Account menu in the Web client sidebar footer: the theme and language switches, the Settings entry, and sign-out."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/client-ui-account
+
+English | [中文](README.zh.md)
+
+## Summary
+
+The account menu is the footer's account row: the signed-in username's first letter in an avatar. One dropdown carries the username, Settings, Appearance and Language submenus, and Sign out; it is the Web surface for theme and language and the only way to sign out. Its facts come from `GET /api/auth/status`, so a deployment without accounts renders the row under the localized label with no session to end; when the transport reports the device session's operator, the menu names them instead of the account identity. It provides no service, owns no dialog, and contributes one list entry.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+The `qilin` Web profile mounts this package through the `web-app` bundle patch; unloading the plugin removes its footer entry and restores the foot without an account surface.
+
+| Row | Present when | Effect |
+|---|---|---|
+| the signed-in username | the gate answered with an account | a menu heading; the name is not a link |
+| Settings | the settings panel is mounted | reveals the settings panel |
+| Appearance | always | opens the Light / Dark / Follow system submenu |
+| Language | always | opens one row per registered locale, each labelled in that locale |
+| Sign out | the account gate is enabled | ends the session, then lands on the public landing page |
+
+The identity and the sign-out row arrive with the status answer, so a menu opened before that answer shows neither; the rows below them are there from the first paint. The theme row matching the current preference and the language row matching the active locale are the marked ones.
+
+A refused or unreachable sign-out navigates nowhere: the page stays where it is, and the menu keeps the rows usable instead of closing over a request that never landed.
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+The plugin fills one list entry in `sidebar.footer.action`, the sidebar's own footer hole, and waits for that declaration through `slots.inject`; the sidebar hands the entry only its column state (`wide`). Copy lives in this package's `account` dictionaries and reaches the component through the framework's `t` seat.
+
+The entry declares `createAccountMenuStore()`: the dropdown's open state plus the account facts one status read resolved. The component reads that snapshot through `props.useStore` and writes through `props.actions`; nothing else mutates it, and the specs build the same store handle directly.
+
+`createAccountMenuInjected` assembles the component's inject face inside `apply`: the two browser reads (`readAccountStatus`, `endSession`), the service calls (`ctx.settingsShell.open`, `ctx.theme.setTheme`, `ctx.locale.setLocale`), and the theme, locale, and settings-panel sources the renderer binds as `useTheme`, `useLocale`, and `useSettingsPanel`. Components reach no service themselves, and the sidecar reads keep their own request paths and navigation target local. The panel is an optional neighbour: `settingsShell` is read through `ctx.get` and its presence is published on the `useSettingsPanel` source from a scoped injection, so a composition that mounts no settings panel still mounts this menu and simply offers no Settings row.
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the account menu renders browser chrome and registers nothing model-facing.
+
+#### KV Cache effect
+
+None of its own; the menu adds nothing to a request and subscribes to no cached prefix.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Submenu rows draw their own selection mark** — the shared `Menu` marks the top-level rows named in `selectedIds` and renders submenu rows unmarked, so this package draws the check for the active theme and locale row itself and still passes both ids to the primitive. Drop the local mark once the primitive marks submenu rows.
+- **The account is read once per mount** — the status read runs when the footer entry mounts, so a session that changed in another tab keeps showing the previous address until the page reloads.
+- **A refused sign-out is silent** — the menu stays open and the page stays put, but nothing tells the user the request failed; an error surface would need copy this package does not have.
+- **No browser-level assertion covers the assembled foot** — the shipped specs drive the component with fed props and the plugin against a real slot registry; the assembled-surface check is manual.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is working context for maintainers: open design questions and directions that are not decided. It is explicitly non-authoritative — shipped behavior, limits, and accepted rationale live in the sections above, the package code, and the linked Agent Notes.
+
+- Whether the menu should show a display name or an avatar image is open; the account record behind the status read carries an address and a creation time only.
+- An enabled gate on a browser that carries no session still offers Sign out, because the sign-in document reads the same status answer; distinguishing "signed out" from "gate on" would need a field the status read does not report today.
+- Flattening the theme and language rows out of their submenus for a narrow column has not been asked for; the submenus keep the dropdown short while the sidebar holds a rail width.
+
+</details>

package/README.zh.md

@@ -0,0 +1,82 @@
+---
+description: "Web 客户端侧边栏底部的账户菜单：主题与语言切换、设置入口，以及退出登录。"
+kind: "package-reference"
+---
+
+# @qilin-agent/client-ui-account
+
+[English](README.md) | 中文
+
+## 概述
+
+账户菜单是页脚的账号行：头像中携带已登录用户名的首字母。一个下拉菜单承载已登录用户名、设置、外观与语言子菜单以及退出登录；它是 Web 端切换主题与语言的入口，也是唯一退出登录的方式。账户事实来自 `GET /api/auth/status`，因此在未启用账户的部署上渲染出同一个本地化标签下的行，也没有可结束的会话；当传输层上报设备会话的操作者时，菜单以该名称替代账户身份展示。它不提供任何服务、不持有对话框，只贡献一个列表条目。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+`qilin` Web profile 通过 `web-app` bundle 补丁挂载本包；卸载插件会移除它在底部的条目，让侧边栏底部回到没有账户入口的状态。
+
+| 行 | 出现条件 | 效果 |
+|---|---|---|
+| 已登录地址 | 门禁应答中带有账户 | 菜单标题行；地址不是链接 |
+| 设置 | 已挂载设置面板 | 展开设置面板 |
+| 主题样式 | 始终 | 打开浅色／深色／跟随系统子菜单 |
+| 语言 | 始终 | 每个已注册语言一行，各自以自己的语言标注 |
+| 退出登录 | 账户门禁已启用 | 结束会话，然后落到公开 landing 页 |
+
+身份行与退出登录行随状态应答一同到达，因此在应答之前打开的菜单不会显示这两行；它们下方的行从首帧起就在。当前主题偏好对应的那行、以及当前语言对应的那行，是带选中标记的行。
+
+被拒绝或无法到达的退出登录不会跳转：页面停在原处，菜单保持可用，而不是在一个从未落地的请求上关闭。
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+插件填充 `sidebar.footer.action` 中的一个列表条目，也就是侧边栏自己的底部洞口，并通过 `slots.inject` 等待该声明出现；侧边栏只把列状态（`wide`）交给它。文案存在本包的 `account` 字典中，经框架的 `t` 座位抵达组件。
+
+条目声明了 `createAccountMenuStore()`：下拉菜单的展开状态，以及一次状态读取解析出的账户事实。组件通过 `props.useStore` 读取该快照、通过 `props.actions` 写入；没有其他写入方，用例也直接构造同一个 store 句柄。
+
+`createAccountMenuInjected` 在 `apply` 中组装组件的注入面：两个浏览器读取（`readAccountStatus`、`endSession`）、服务调用（`ctx.settingsShell.open`、`ctx.theme.setTheme`、`ctx.locale.setLocale`），以及渲染器绑定为 `useTheme`、`useLocale` 与 `useSettingsPanel` 的主题、语言与设置面板来源。组件自身不接触任何服务，两个请求各自的路径与跳转目标都留在本包内。设置面板是可选的邻居：`settingsShell` 经 `ctx.get` 读取，其存在与否由一处作用域注入发布到 `useSettingsPanel` 来源上，因此没有挂载设置面板的组合仍会挂载本菜单，只是不提供设置行。
+
+<a id="model-experience"></a>
+## 模型体验
+
+None, as the account menu renders browser chrome and registers nothing model-facing.
+
+#### KV Cache 影响
+
+本身没有；菜单既不向请求添加内容，也不订阅任何缓存前缀。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+这些限制描述本菜单目前做不到什么、以及什么时候需要留意。它们是当前约束，不是与其他账户界面之间的对比，也不是任务清单。
+
+- **子菜单行自己绘制选中标记**——共享的 `Menu` 只为 `selectedIds` 中点名的顶层行绘制标记，子菜单行不带标记，因此本包自己为主题与语言当前行绘制对勾，同时仍把两个 id 交给该基础组件。等到基础组件为子菜单行也绘制标记后，应删除本地标记。
+- **账户只在挂载时读取一次**——状态读取发生在底部条目挂载时，因此在另一个标签页里换了会话的浏览器，会继续显示此前的地址，直到页面重新加载。
+- **被拒绝的退出登录是静默的**——菜单保持展开、页面停在原处，但没有任何提示告诉用户请求失败了；要给出错误提示，需要一个本包目前没有的文案位。
+- **没有覆盖装配后底部的浏览器级断言**——随包发布的用例以直接喂入的 props 驱动组件、以真实槽位注册表驱动插件；装配面的检查目前是手工的。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文：尚未决定的开放问题与方向。它明确不具备权威性——已发布行为、限制与已接受的取舍见上文各节、包代码以及链接的 Agent Note。
+
+- 菜单是否应显示昵称或头像仍待定；状态读取背后的账户记录目前只有地址与创建时间。
+- 门禁已启用但没有会话的浏览器仍会看到「退出登录」，因为登录文档读取的是同一份状态应答；要把「未登录」与「门禁开启」区分开，需要一个状态读取目前不报告的字段。
+- 是否为窄列把主题与语言两行从子菜单中摊平，目前无人提出；子菜单让下拉菜单保持紧凑，而侧边栏还留着 rail 宽度。
+
+</details>

package/lib/client.js

@@ -0,0 +1,437 @@
+window.__ModuleLoader__.load({
+	id: "@qilin-agent/client-ui-account",
+	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 _qilin_agent_client_ui_primitives = require("@qilin-agent/client-ui-primitives");
+		let _qilin_agent_client_store = require("@qilin-agent/client-store");
+		//#region \0qilin-css:/home/runner/work/QiLin/QiLin/packages/client/ui-account/src/client/AccountMenu.module.css.mjs
+		const css = ".Ixy6Ia_slot{width:100%;display:flex}.Ixy6Ia_trigger{box-sizing:border-box;width:100%;height:40px;color:var(--qilin-alias-label-primary);text-align:left;cursor:pointer;background:0 0;border:none;border-radius:10px;align-items:center;gap:8px;padding:0 8px;font-family:inherit;font-size:14px;font-weight:400;line-height:22px;display:flex}.Ixy6Ia_trigger.Ixy6Ia_rail{corner-shape:round;border-radius:50%;justify-content:center;gap:0;width:36px;height:36px;padding:0}.Ixy6Ia_trigger:hover{background:var(--qilin-alias-interactive-bg-hover)}.Ixy6Ia_avatar{corner-shape:round;background:color-mix(in srgb, var(--qilin-alias-brand-primary) 16%, transparent);width:22px;height:22px;color:var(--qilin-alias-brand-primary);border-radius:50%;flex:none;place-items:center;font-size:11px;font-weight:600;line-height:1;display:grid}.Ixy6Ia_name{text-overflow:ellipsis;white-space:nowrap;min-width:0;overflow:hidden}.Ixy6Ia_option{align-items:center;gap:8px;display:flex}.Ixy6Ia_optionText{text-overflow:ellipsis;white-space:nowrap;flex:1;min-width:0;overflow:hidden}.Ixy6Ia_check{color:var(--qilin-alias-label-primary);flex:none}";
+		const tagId = "@qilin-agent/client-ui-account/AccountMenu.module.css";
+		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
+			const tag = document.createElement("style");
+			tag.dataset.plugin = "@qilin-agent/client-ui-account";
+			tag.dataset.pluginCss = tagId;
+			tag.textContent = css;
+			document.head.appendChild(tag);
+		}
+		var AccountMenu_module_css_default = {
+			"avatar": "Ixy6Ia_avatar",
+			"check": "Ixy6Ia_check",
+			"name": "Ixy6Ia_name",
+			"option": "Ixy6Ia_option",
+			"optionText": "Ixy6Ia_optionText",
+			"rail": "Ixy6Ia_rail",
+			"slot": "Ixy6Ia_slot",
+			"trigger": "Ixy6Ia_trigger"
+		};
+		//#endregion
+		//#region lib/types/client/AccountMenu.js
+		/**
+		* Sidebar-footer account button: the round trigger plus the menu that switches
+		* theme and language, opens Settings, and signs out. The account facts come
+		* from the menu store, live theme and locale state from the injected sources,
+		* and every write goes through the injected callbacks — the component reaches
+		* no service itself.
+		*/
+		/** Row id of the Settings entry. */
+		const SETTINGS_ID = "settings";
+		/** Row id of the sign-out entry. */
+		const SIGN_OUT_ID = "sign-out";
+		/** Prefix marking one theme option row; the remainder is the theme id. */
+		const THEME_ROW_PREFIX = "theme:";
+		/** Prefix marking one language option row; the remainder is the locale id. */
+		const LOCALE_ROW_PREFIX = "locale:";
+		/** The built-in theme preferences, in menu order. */
+		const THEME_ROWS = [
+			{
+				id: "light",
+				labelKey: "appearance.light",
+				Icon: _qilin_agent_client_ui_primitives.IconLightOutline16
+			},
+			{
+				id: "dark",
+				labelKey: "appearance.dark",
+				Icon: _qilin_agent_client_ui_primitives.IconDarkOutline16
+			},
+			{
+				id: "system",
+				labelKey: "appearance.system",
+				Icon: _qilin_agent_client_ui_primitives.IconFollowsystemOutline16
+			}
+		];
+		/**
+		* Wrap one option row's label with its selection marker. The primitive draws
+		* the check for the top-level rows named in `selectedIds` only, so a submenu
+		* row that is the active choice carries its own.
+		* @param label - the row's localized text.
+		* @param selected - whether this row is the active choice.
+		* @returns the row label node.
+		*/
+		function optionLabel(label, selected) {
+			return (0, react_jsx_runtime.jsxs)("span", {
+				className: AccountMenu_module_css_default.option,
+				children: [(0, react_jsx_runtime.jsx)("span", {
+					className: AccountMenu_module_css_default.optionText,
+					children: label
+				}), selected && (0, react_jsx_runtime.jsx)(_qilin_agent_client_ui_primitives.IconCheckOutline16, { className: AccountMenu_module_css_default.check })]
+			});
+		}
+		/**
+		* Render the account button and its dropdown.
+		* @param props - composed slot props.
+		* @returns the sidebar-footer trigger with its anchored menu.
+		*/
+		function AccountMenu({ wide, useStore, actions, loadAccount, signOut, openSettings, setTheme, setLocale, useTheme, useLocale, useSettingsPanel, t }) {
+			const open = useStore((state) => state.open);
+			const accountName = useStore((state) => state.accountName);
+			const signOutAvailable = useStore((state) => state.signOutAvailable);
+			const settingsMounted = useSettingsPanel((mounted) => mounted);
+			const preference = useTheme((snapshot) => snapshot.preference);
+			const activeLocale = useLocale((snapshot) => snapshot.active);
+			const locales = useLocale((snapshot) => snapshot.locales);
+			(0, react.useEffect)(() => {
+				loadAccount();
+			}, [loadAccount]);
+			const selected = [];
+			const items = [];
+			if (accountName !== null) items.push({
+				type: "label",
+				id: "account",
+				text: accountName
+			});
+			if (settingsMounted) items.push({
+				id: SETTINGS_ID,
+				label: t("settings"),
+				icon: (0, react_jsx_runtime.jsx)(_qilin_agent_client_ui_primitives.IconSettingsOutline16, {})
+			});
+			items.push({
+				id: "appearance",
+				label: t("appearance"),
+				icon: (0, react_jsx_runtime.jsx)(_qilin_agent_client_ui_primitives.IconPersonalizationOutline16, {}),
+				submenu: THEME_ROWS.map((row) => {
+					const id = `${THEME_ROW_PREFIX}${row.id}`;
+					const isSelected = row.id === preference;
+					if (isSelected) selected.push(id);
+					return {
+						id,
+						label: optionLabel(t(row.labelKey), isSelected),
+						icon: (0, react_jsx_runtime.jsx)(row.Icon, {})
+					};
+				})
+			});
+			items.push({
+				id: "language",
+				label: t("language"),
+				icon: (0, react_jsx_runtime.jsx)(_qilin_agent_client_ui_primitives.IconGlobeOutline14, {}),
+				submenu: locales.map((entry) => {
+					const id = `${LOCALE_ROW_PREFIX}${entry.id}`;
+					const isSelected = entry.id === activeLocale;
+					if (isSelected) selected.push(id);
+					return {
+						id,
+						label: optionLabel(entry.label, isSelected)
+					};
+				})
+			});
+			if (signOutAvailable) {
+				items.push({
+					type: "separator",
+					id: "sign-out-separator"
+				});
+				items.push({
+					id: SIGN_OUT_ID,
+					label: t("signOut"),
+					icon: (0, react_jsx_runtime.jsx)(_qilin_agent_client_ui_primitives.IconLogoutOutline16, {}),
+					danger: true
+				});
+			}
+			const select = (id) => {
+				if (id === SIGN_OUT_ID) {
+					signOut();
+					return;
+				}
+				actions.setOpen(false);
+				if (id === SETTINGS_ID) {
+					openSettings();
+					return;
+				}
+				if (id.startsWith(THEME_ROW_PREFIX)) {
+					setTheme(id.slice(6));
+					return;
+				}
+				setLocale(id.slice(7));
+			};
+			const label = t("label");
+			const name = accountName ?? label;
+			const initial = accountName === null ? void 0 : Array.from(accountName)[0]?.toUpperCase();
+			return (0, react_jsx_runtime.jsx)(_qilin_agent_client_ui_primitives.Menu, {
+				className: AccountMenu_module_css_default.slot,
+				open,
+				align: "end",
+				side: "top",
+				portal: true,
+				items,
+				selectedIds: selected,
+				onSelect: select,
+				onClose: () => {
+					actions.setOpen(false);
+				},
+				anchor: (0, react_jsx_runtime.jsx)(_qilin_agent_client_ui_primitives.Tooltip, {
+					label,
+					delayMs: 500,
+					disabled: wide,
+					children: (0, react_jsx_runtime.jsxs)("button", {
+						type: "button",
+						className: `${AccountMenu_module_css_default.trigger} ${wide ? AccountMenu_module_css_default.wide : AccountMenu_module_css_default.rail}`,
+						"aria-label": wide ? void 0 : label,
+						"aria-haspopup": "menu",
+						"aria-expanded": open,
+						onClick: () => {
+							actions.setOpen(!open);
+						},
+						children: [(0, react_jsx_runtime.jsx)("span", {
+							className: AccountMenu_module_css_default.avatar,
+							"aria-hidden": "true",
+							children: initial ?? (0, react_jsx_runtime.jsx)(_qilin_agent_client_ui_primitives.IconUserOutline16, { size: 14 })
+						}), wide && (0, react_jsx_runtime.jsx)("span", {
+							className: AccountMenu_module_css_default.name,
+							children: name
+						})]
+					})
+				})
+			});
+		}
+		//#endregion
+		//#region lib/types/client/account-api.js
+		/**
+		* Document-relative form of {@link AUTH_STATUS_PATH} the account menu addresses; see
+		* .agents/notes/implemented/architecture/2026-09-14-web-document-relative-app-routes.md.
+		*/
+		const AUTH_STATUS_ROUTE = "/api/auth/status".slice(1);
+		/** Document-relative form of {@link AUTH_LOGOUT_PATH} the account menu addresses. */
+		const AUTH_LOGOUT_ROUTE = "/api/auth/logout".slice(1);
+		/** Page the browser lands on once its session is gone: the public entry surface. */
+		const LANDING_PATH = "/";
+		/** The answer for a deployment with no reachable account surface. */
+		const NO_ACCOUNT = Object.freeze({
+			accountName: null,
+			signOutAvailable: false
+		});
+		/**
+		* Read the account gate's status.
+		*
+		* A mounted gate names the session's account and offers sign-out. A disabled
+		* gate has no account facts, but the transport can still name the operator of
+		* its device session — a display-only identity with no session to end. An
+		* unreachable gate stays one answer with both rows empty.
+		* @returns the account facts of the current browser session.
+		*/
+		async function readAccountStatus() {
+			try {
+				const response = await fetch(AUTH_STATUS_ROUTE);
+				if (!response.ok) return NO_ACCOUNT;
+				const status = await response.json();
+				if (!status.enabled) return {
+					accountName: status.accountName ?? null,
+					signOutAvailable: false
+				};
+				return {
+					accountName: (status.authenticated ? status.user : null)?.username ?? null,
+					signOutAvailable: true
+				};
+			} catch {
+				return NO_ACCOUNT;
+			}
+		}
+		/**
+		* End this browser's session and land on the product's public page.
+		*
+		* The navigation happens only after the Host accepted the sign-out: a refused
+		* or unreachable call leaves the page where it is, so the menu that offered
+		* the row keeps working instead of stranding the user on a dead page.
+		* @returns whether the session ended (false keeps the current page).
+		*/
+		async function endSession() {
+			try {
+				if (!(await fetch(AUTH_LOGOUT_ROUTE, { method: "POST" })).ok) return false;
+				location.assign(LANDING_PATH);
+				return true;
+			} catch {
+				return false;
+			}
+		}
+		//#endregion
+		//#region lib/types/client/injected.js
+		/**
+		* Build one entry's injected share.
+		* @param sources - the store actions and service calls this instance routes to.
+		* @returns the inject face the component receives.
+		*/
+		function createAccountMenuInjected(sources) {
+			return {
+				loadAccount: async () => {
+					sources.actions.resolveAccount(await readAccountStatus());
+				},
+				signOut: async () => {
+					await endSession();
+				},
+				openSettings: sources.openSettings,
+				setTheme: sources.setTheme,
+				setLocale: sources.setLocale,
+				hooks: {
+					theme: sources.theme,
+					locale: sources.locale,
+					settingsPanel: sources.settingsPanel
+				}
+			};
+		}
+		//#endregion
+		//#region lib/types/client/settings-panel.js
+		/**
+		* Whether the neighbouring settings panel is mounted. The account menu's
+		* Settings row is that panel's entry point, and a composition may omit the
+		* panel entirely — a fixture surface that serves no settings traffic mounts the
+		* menu alone — so the row follows this flag instead of the menu's own
+		* activation waiting on the panel's service.
+		*/
+		/** Live availability of the settings panel behind the menu's Settings row. */
+		var SettingsPanelPresence = class {
+			/** Reactive presence flag; false until the panel provides its open channel. */
+			mounted = (0, _qilin_agent_client_store.createSnapshotStore)(false);
+			/**
+			* Publish whether the panel's open channel resolves.
+			* @param mounted - whether the settings shell is mounted in this composition.
+			*/
+			publish(mounted) {
+				if (this.mounted.getSnapshot() === mounted) return;
+				this.mounted.set(mounted);
+			}
+		};
+		//#endregion
+		//#region lib/types/client/store.js
+		/**
+		* Account menu store: whether the dropdown is open and what the status read
+		* resolved about the signed-in account. The plugin body owns the reads and
+		* publishes their results here; the component reads through props.useStore.
+		*/
+		/**
+		* Declare the account menu state and write surface.
+		* @returns a fresh handle — each registration instance owns its own open state
+		* and account facts, so no module-level handle can leak across plugin reloads.
+		*/
+		function createAccountMenuStore() {
+			return (0, _qilin_agent_client_store.defineStore)({
+				init: () => ({
+					open: false,
+					accountName: null,
+					signOutAvailable: false
+				}),
+				actions: {
+					setOpen: (draft, open) => {
+						draft.open = open;
+					},
+					resolveAccount: (draft, facts) => {
+						draft.accountName = facts.accountName;
+						draft.signOutAvailable = facts.signOutAvailable;
+					}
+				}
+			});
+		}
+		//#endregion
+		//#region lib/types/client/locales.js
+		/** Copy dictionaries for the sidebar account menu. */
+		/** English strings (the key-set source of truth for this pair). */
+		const en = {
+			label: "Account",
+			settings: "Settings",
+			appearance: "Appearance",
+			"appearance.light": "Light",
+			"appearance.dark": "Dark",
+			"appearance.system": "Follow system",
+			language: "Language",
+			signOut: "Sign out"
+		};
+		/** Chinese strings for the same key set. */
+		const zh = {
+			label: "账户",
+			settings: "设置",
+			appearance: "主题样式",
+			"appearance.light": "浅色",
+			"appearance.dark": "深色",
+			"appearance.system": "跟随系统",
+			language: "语言",
+			signOut: "退出登录"
+		};
+		//#endregion
+		//#region lib/types/client/index.js
+		/** Dictionary namespace owned by this plugin. */
+		const NS = "account";
+		/** Services required by the account menu: the slot it fills and the two
+		* preference services behind its rows. The settings panel is an optional
+		* neighbour — see the scoped injection in {@link apply}. */
+		const inject = [
+			"slots",
+			"locale",
+			"theme"
+		];
+		/**
+		* Register the account menu into the sidebar foot's account row, once the
+		* sidebar declares that seat, and hand it the one store its entry shares.
+		* @param ctx - client root context.
+		*/
+		function apply(ctx) {
+			ctx.effect(() => ctx.locale.register(NS, {
+				zh,
+				en
+			}), "ui-account: dictionaries");
+			const store = createAccountMenuStore();
+			const settingsPanel = new SettingsPanelPresence();
+			const injected = (actions) => createAccountMenuInjected({
+				actions,
+				openSettings: () => {
+					ctx.get("settingsShell")?.open();
+				},
+				setTheme: (id) => {
+					ctx.theme.setTheme(id);
+				},
+				setLocale: (id) => {
+					ctx.locale.setLocale(id);
+				},
+				theme: {
+					getSnapshot: () => ctx.theme.getTheme(),
+					subscribe: (listener) => ctx.on("theme/change", listener)
+				},
+				locale: {
+					getSnapshot: () => ctx.locale.getSnapshot(),
+					subscribe: (listener) => ctx.locale.subscribe(listener)
+				},
+				settingsPanel: settingsPanel.mounted
+			});
+			ctx.slots.inject("sidebar.account", () => ctx.slots.register({
+				name: "sidebar.account",
+				locale: NS,
+				store,
+				inject: injected
+			}, AccountMenu));
+			ctx.inject(["settingsShell"], (scope) => {
+				scope.effect(() => {
+					settingsPanel.publish(true);
+					return () => {
+						settingsPanel.publish(false);
+					};
+				}, "ui-account: settings row availability");
+			});
+		}
+		//#endregion
+		exports.NS = NS;
+		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 sidebar account menu exported from `./client`. */
+/** Host plugin body — the account menu is browser-only. */
+function apply() {}
+//#endregion
+export { apply };

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

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+import type { HostObservable, InjectFace, PropsLocale, PropsRuntime, PropsStore } from '@qilin-agent/client-ui-slots';
+import type { LocaleSnapshot } from '@qilin-agent/client-locale/client';
+import type { ThemeSnapshot } from '@qilin-agent/client-ui-theme/client';
+import type { AccountMenuStoreHandle } from './store.ts';
+/** Injected dependencies of {@link AccountMenu} (the plugin's inject face). */
+export interface AccountMenuInjected {
+    /** Read the account gate's status once and publish what it resolved. */
+    loadAccount: () => Promise<void>;
+    /** End the session; a refused call navigates nowhere and leaves the menu open. */
+    signOut: () => Promise<void>;
+    /** Reveal the settings panel. */
+    openSettings: () => void;
+    /** Switch the theme preference to a built-in id. */
+    setTheme: (id: string) => void;
+    /** Switch the active locale to a registered id. */
+    setLocale: (id: string) => void;
+    hooks: {
+        /** Theme state source, bound by the renderer as useTheme. */
+        theme: HostObservable<ThemeSnapshot>;
+        /** Locale state source, bound by the renderer as useLocale. */
+        locale: HostObservable<LocaleSnapshot>;
+        /** Settings-panel presence, bound by the renderer as useSettingsPanel. */
+        settingsPanel: HostObservable<boolean>;
+    };
+}
+/** Full component props: sidebar column state, store share, inject face, and copy seat. */
+export type AccountMenuProps = PropsRuntime<'sidebar.account'> & PropsStore<AccountMenuStoreHandle> & InjectFace<AccountMenuInjected> & PropsLocale<'account'>;
+/**
+ * Render the account button and its dropdown.
+ * @param props - composed slot props.
+ * @returns the sidebar-footer trigger with its anchored menu.
+ */
+export declare function AccountMenu({ wide, useStore, actions, loadAccount, signOut, openSettings, setTheme, setLocale, useTheme, useLocale, useSettingsPanel, t, }: AccountMenuProps): ReactNode;
+//# sourceMappingURL=AccountMenu.d.ts.map

package/lib/types/client/account-api.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The `/api/auth` reads behind the account menu. The session cookie is HttpOnly
+ * and same-origin, so neither request states a credentials option: the browser
+ * attaches the cookie on its own.
+ */
+/** The signed-in account, as `/api/auth/status` reports it. */
+export interface AccountUser {
+    /** Account id. */
+    readonly id: string;
+    /** Name the account signs in with; the menu's heading text. */
+    readonly username: string;
+    /** Address the account carries, or null when it registered without one. */
+    readonly email: string | null;
+    /** Account creation time in epoch milliseconds. */
+    readonly createdAt: number;
+}
+/** The fields of one `/api/auth/status` answer this menu reads. */
+export interface AccountStatus {
+    /** Whether the account gate is active for this deployment. */
+    readonly enabled: boolean;
+    /** Whether the request carried a verified session. */
+    readonly authenticated: boolean;
+    /** Account behind the session; null when the request carried none. */
+    readonly user: AccountUser | null;
+    /**
+     * Operator name the transport reports for a gate-less deployment's device
+     * session; absent on a mounted gate, whose identity is the account's.
+     */
+    readonly accountName?: string | null;
+}
+/** What the menu knows about the signed-in account. */
+export interface AccountFacts {
+    /** Name shown as the menu heading; null when no account is known. */
+    readonly accountName: string | null;
+    /** Whether the menu offers the sign-out row. */
+    readonly signOutAvailable: boolean;
+}
+/**
+ * Read the account gate's status.
+ *
+ * A mounted gate names the session's account and offers sign-out. A disabled
+ * gate has no account facts, but the transport can still name the operator of
+ * its device session — a display-only identity with no session to end. An
+ * unreachable gate stays one answer with both rows empty.
+ * @returns the account facts of the current browser session.
+ */
+export declare function readAccountStatus(): Promise<AccountFacts>;
+/**
+ * End this browser's session and land on the product's public page.
+ *
+ * The navigation happens only after the Host accepted the sign-out: a refused
+ * or unreachable call leaves the page where it is, so the menu that offered
+ * the row keeps working instead of stranding the user on a dead page.
+ * @returns whether the session ended (false keeps the current page).
+ */
+export declare function endSession(): Promise<boolean>;
+//# sourceMappingURL=account-api.d.ts.map

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

@@ -0,0 +1,31 @@
+/**
+ * Account menu plugin, browser half: the sidebar footer's account button and
+ * its menu — the one surface that switches theme and language, opens Settings,
+ * and signs out. It joins the sidebar's footer action list, reads the account
+ * gate's status itself, and owns no other state.
+ */
+import type { Context as ClientContext } from '@qilin-agent/kylin';
+import { type AccountLocaleKey } from './locales.ts';
+export type { AccountMenuInjected, AccountMenuProps } from './AccountMenu.tsx';
+export type { AccountFacts, AccountStatus, AccountUser } from './account-api.ts';
+export type { AccountMenuActions, AccountMenuState, AccountMenuStoreHandle } from './store.ts';
+export type { AccountLocaleKey } from './locales.ts';
+declare module '@qilin-agent/client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Sidebar account menu copy. */
+        account: AccountLocaleKey;
+    }
+}
+/** Dictionary namespace owned by this plugin. */
+export declare const NS = "account";
+/** Services required by the account menu: the slot it fills and the two
+ * preference services behind its rows. The settings panel is an optional
+ * neighbour — see the scoped injection in {@link apply}. */
+export declare const inject: string[];
+/**
+ * Register the account menu into the sidebar foot's account row, once the
+ * sidebar declares that seat, and hand it the one store its entry shares.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,35 @@
+/**
+ * The account menu's injected share: the browser reads and service calls the
+ * component may make, taken from the plugin body's own context. Building the
+ * face here keeps `apply` and the specs that drive the real status and
+ * sign-out requests on one wiring.
+ */
+import type { BoundActions, HostObservable } from '@qilin-agent/client-ui-slots';
+import type { LocaleSnapshot } from '@qilin-agent/client-locale/client';
+import type { ThemeSnapshot } from '@qilin-agent/client-ui-theme/client';
+import type { AccountMenuInjected } from './AccountMenu.tsx';
+import type { AccountMenuStoreHandle } from './store.ts';
+/** Services and sources one account menu instance is wired to. */
+export interface AccountMenuSources {
+    /** Baked write set of the entry's own store instance. */
+    readonly actions: BoundActions<AccountMenuStoreHandle>;
+    /** Reveal the settings panel. */
+    readonly openSettings: () => void;
+    /** Switch the theme preference to a built-in id. */
+    readonly setTheme: (id: string) => void;
+    /** Switch the active locale to a registered id. */
+    readonly setLocale: (id: string) => void;
+    /** Live theme state; the renderer binds it as useTheme. */
+    readonly theme: HostObservable<ThemeSnapshot>;
+    /** Live locale state; the renderer binds it as useLocale. */
+    readonly locale: HostObservable<LocaleSnapshot>;
+    /** Live settings-panel presence; the renderer binds it as useSettingsPanel. */
+    readonly settingsPanel: HostObservable<boolean>;
+}
+/**
+ * Build one entry's injected share.
+ * @param sources - the store actions and service calls this instance routes to.
+ * @returns the inject face the component receives.
+ */
+export declare function createAccountMenuInjected(sources: AccountMenuSources): AccountMenuInjected;
+//# sourceMappingURL=injected.d.ts.map

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

@@ -0,0 +1,17 @@
+/** Copy dictionaries for the sidebar account menu. */
+/** English strings (the key-set source of truth for this pair). */
+export declare const en: {
+    label: string;
+    settings: string;
+    appearance: string;
+    'appearance.light': string;
+    'appearance.dark': string;
+    'appearance.system': string;
+    language: string;
+    signOut: string;
+};
+/** Chinese strings for the same key set. */
+export declare const zh: Record<keyof typeof en, string>;
+/** Key set of one account menu dictionary. */
+export type AccountLocaleKey = keyof typeof en;
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/settings-panel.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Whether the neighbouring settings panel is mounted. The account menu's
+ * Settings row is that panel's entry point, and a composition may omit the
+ * panel entirely — a fixture surface that serves no settings traffic mounts the
+ * menu alone — so the row follows this flag instead of the menu's own
+ * activation waiting on the panel's service.
+ */
+import { type SnapshotStore } from '@qilin-agent/client-store';
+/** Live availability of the settings panel behind the menu's Settings row. */
+export declare class SettingsPanelPresence {
+    /** Reactive presence flag; false until the panel provides its open channel. */
+    readonly mounted: SnapshotStore<boolean>;
+    /**
+     * Publish whether the panel's open channel resolves.
+     * @param mounted - whether the settings shell is mounted in this composition.
+     */
+    publish(mounted: boolean): void;
+}
+//# sourceMappingURL=settings-panel.d.ts.map

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

@@ -0,0 +1,32 @@
+/**
+ * Account menu store: whether the dropdown is open and what the status read
+ * resolved about the signed-in account. The plugin body owns the reads and
+ * publishes their results here; the component reads through props.useStore.
+ */
+import { type EngineStoreHandle } from '@qilin-agent/client-store';
+import type { AccountFacts } from './account-api.ts';
+/** What the account menu renders at any moment. */
+export interface AccountMenuState {
+    /** Whether the dropdown is showing. */
+    open: boolean;
+    /** Signed-in name shown as the menu heading; null when none is known. */
+    accountName: string | null;
+    /** Whether the menu offers the sign-out row. */
+    signOutAvailable: boolean;
+}
+/** Declared action shape giving the exported factory a stable return type. */
+export type AccountMenuActions = {
+    /** Open or close the dropdown. */
+    setOpen: (draft: AccountMenuState, open: boolean) => void;
+    /** Publish what one status read resolved. */
+    resolveAccount: (draft: AccountMenuState, facts: AccountFacts) => void;
+};
+/** The declared handle one registration instance is created from. */
+export type AccountMenuStoreHandle = EngineStoreHandle<AccountMenuState, AccountMenuActions>;
+/**
+ * Declare the account menu state and write surface.
+ * @returns a fresh handle — each registration instance owns its own open state
+ * and account facts, so no module-level handle can leak across plugin reloads.
+ */
+export declare function createAccountMenuStore(): AccountMenuStoreHandle;
+//# sourceMappingURL=store.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Host loader entry for the sidebar account menu exported from `./client`. */
+/** Host plugin body — the account menu is browser-only. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@qilin-agent/client-ui-account",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Account menu in the Web client sidebar footer: theme, language, Settings, and sign-out",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/ui-account"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "qilin": {
+    "client": {
+      "inject": [
+        "@qilin-agent/client-ui-sidebar",
+        "@qilin-agent/client-locale",
+        "@qilin-agent/client-ui-theme",
+        "@qilin-agent/client-ui-settings-general",
+        "@qilin-agent/client-ui-renderer"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/client-store": "3.1.4",
+    "@qilin-agent/client-ui-primitives": "3.1.4",
+    "@qilin-agent/client-ui-renderer": "3.1.4",
+    "@qilin-agent/client-locale": "3.1.4",
+    "@qilin-agent/client-test-runtime": "3.1.4",
+    "@qilin-agent/client-ui-settings-general": "3.1.4",
+    "@qilin-agent/client-ui-sidebar": "3.1.4",
+    "@qilin-agent/client-ui-slots": "3.1.4",
+    "@qilin-agent/client-ui-theme": "3.1.4"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }