@qilin-agent/client-ui-brand 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,31 @@
+# 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-brand/README.md
+/:
+  en: 0849adcc1b77677c
+  zh: 330bdb3cd1a3dda4
+/qilin-agent-client-ui-brand:
+  en: 3bbc99c223e49c43
+  zh: 7a8af4db92f101f7
+/qilin-agent-client-ui-brand/summary:
+  en: 95377ff450c656ff
+  zh: a9908aa55d89e35f
+/qilin-agent-client-ui-brand/table-of-contents:
+  en: 4e53164159b5ce41
+  zh: 024420bdbdd3e0ac
+/qilin-agent-client-ui-brand/use-this-package:
+  en: 6f4d483895bfadef
+  zh: 6d63376599a90894
+/qilin-agent-client-ui-brand/dev-note:
+  en: f3c698886ef928a7
+  zh: eaac63c14c20b932
+/qilin-agent-client-ui-brand/model-experience:
+  en: 4d7eb90e99c59ab9
+  zh: da60e592bccf5a3c
+/qilin-agent-client-ui-brand/model-experience/kv-cache-effect:
+  en: 8cef18f4fc036de1
+  zh: fa4d629e49531593
+/qilin-agent-client-ui-brand/known-limitations-and-deferred-work:
+  en: b9339c6577080908
+  zh: a4ba753a1f9bd502

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+---
+description: "QiLin occupants for the Web client sidebar, conversation-hero, and settings brand slots: the cinnabar 麒麟 seal stamp, drawn from embedded outlines."
+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-brand
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Mount this plugin beside [`ui-sidebar`](../ui-sidebar/README.md), [`ui-conversation`](../ui-conversation/README.md), and [`ui-settings-general`](../ui-settings-general/README.md) to replace generic fallbacks with the QiLin seal: a cinnabar rounded square, gold ring, and warm-white 麒 and 麟 outlines. The embedded SVG needs no font and keeps the stamp legible on light and dark surfaces. The sidebar name and version badge remain shell-owned; the settings About page receives the same seal through a root-scoped slot.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [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` profile mounts this package through its bundle patch, so no configuration is required. The plugin waits for each declaring chain before it occupies its paired slots, and unloading it restores the shell fallbacks. The settings marks are registered independently from the sidebar and conversation hero chain.
+
+| Slot | Occupant |
+|---|---|
+| `sidebar.brand.mark` | the seal at the sidebar's requested size |
+| `conversation.hero.brand.mark` | the seal at the hero's requested size and placement class |
+| `settings.about.mark` | the seal in the shell-owned About page |
+
+The two character outlines and the body, ring, and glyph-cell geometry now live in [`@qilin-agent/client-ui-primitives`](../ui-primitives/README.md) (`seal-glyphs.ts`, `seal-geometry.ts`), so the shell's unbranded fallbacks draw the same stamp; [`Seal.tsx`](src/client/Seal.tsx) occupies the brand slots with it, one gradient id per instance.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the seal is browser presentation and never enters a model request or the session log.
+
+#### KV Cache effect
+
+None; the seal contributes no prompt text.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- The seal is authored from a text-face outline, not from a designer's seal-script drawing. A commissioned 篆书 mark would replace the two path constants without touching the component.
+- The seal's body gradient, glyph fill, and ring colour are fixed constants rather than theme tokens: the brand stamp must read identically on a light and a dark surface, so a themed variant needs a deliberate second artwork instead of a token swap.
+- No browser-level assertion covers the fully assembled settings surface yet; the shipped specs exercise the slot registry, mark rendering, and the settings shell separately.

package/README.zh.md

@@ -0,0 +1,56 @@
+---
+description: "QiLin 在 Web 客户端侧边栏、会话 hero 与设置品牌槽位的占位实现：由内嵌轮廓绘制的朱红麒麟印章。"
+kind: "package-reference"
+---
+
+# @qilin-agent/client-ui-brand
+
+[English](README.md) | 中文
+
+## 概述
+
+把本插件挂在 [`ui-sidebar`](../ui-sidebar/README.zh.md)、[`ui-conversation`](../ui-conversation/README.zh.md) 与 [`ui-settings-general`](../ui-settings-general/README.zh.md) 旁边，即可用麒麟印章替换通用回退：朱红圆角方框、金色圆环，以及暖白色并排的麒与麟轮廓。内嵌 SVG 无需字体，在浅色与深色表面保持清晰。侧边栏品牌名与版本徽章仍由外壳拥有；设置 About 页面与桌面摘要卡通过根作用域槽位收到同一枚印章。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [模型体验](#model-experience)
+- [已知限制与待办](#known-limitations-and-deferred-work)
+- [开发说明](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+`qilin` profile 通过其 bundle 补丁挂载本包，无需配置。插件会等待每条声明链就绪后再占用对应的一组槽位，卸载后恢复外壳回退。设置标识链独立于侧边栏与会话 hero 链。
+
+| 槽位 | 占用内容 |
+|---|---|
+| `sidebar.brand.mark` | 按侧边栏请求尺寸渲染的印章 |
+| `conversation.hero.brand.mark` | 按 hero 请求尺寸与摆放类渲染的印章 |
+| `settings.about.mark` | 外壳 About 页面中的印章 |
+
+两个字形轮廓与印身、圆环、字形格子的几何现在位于 [`@qilin-agent/client-ui-primitives`](../ui-primitives/README.zh.md)（`seal-glyphs.ts`、`seal-geometry.ts`），让外壳的无品牌兜底画出同一枚印章；[`Seal.tsx`](src/client/Seal.tsx) 用它占据品牌槽位，并为每个实例生成独立的渐变 id。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。
+
+<a id="model-experience"></a>
+## 模型体验
+
+无；印章属于浏览器呈现，不进入模型请求或会话日志。
+
+#### KV Cache 影响
+
+无；印章不贡献任何提示文本。
+
+## 已知限制与待办
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 印章取自正文字体轮廓，而非设计师的篆书稿。委托绘制的篆书标记只需替换两个路径常量，无需改动组件。
+- 印身渐变、字形填充与圆环颜色是固定常量而非主题令牌：品牌印章必须在浅色与深色表面上读起来一致，因此主题化变体需要一份刻意的第二版图形，而不是替换令牌。
+- 完整组装的设置表层尚无浏览器级断言；随附规格分别覆盖槽位注册、标识渲染和设置外壳。

package/lib/client.js

@@ -0,0 +1,54 @@
+window.__ModuleLoader__.load({
+	id: "@qilin-agent/client-ui-brand",
+	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 _qilin_agent_client_ui_primitives = require("@qilin-agent/client-ui-primitives");
+		//#region lib/types/client/Seal.js
+		/**
+		* Occupy the sidebar brand-mark slot.
+		* @param props - host-supplied mark presentation.
+		* @returns the seal at the sidebar's requested size.
+		*/
+		function QilinSealMark({ size }) {
+			return (0, react_jsx_runtime.jsx)(_qilin_agent_client_ui_primitives.QilinSeal, { size });
+		}
+		/**
+		* Occupy the conversation hero's brand-mark slot.
+		* @param props - host-supplied mark presentation.
+		* @returns the seal at the hero's requested size and placement class.
+		*/
+		function QilinSealHeroMark({ size, className }) {
+			return (0, react_jsx_runtime.jsx)(_qilin_agent_client_ui_primitives.QilinSeal, {
+				size,
+				className
+			});
+		}
+		//#endregion
+		//#region lib/types/client/index.js
+		/** QiLin occupants for the generic sidebar and conversation brand slots. */
+		/** Required service: the UI slot registry. */
+		const inject = ["slots"];
+		/**
+		* Fill the sidebar and hero brand-mark slots as one declaration-aware
+		* registration set. The sidebar brand name keeps the shell's own fallback, so
+		* the QiLin label and its build badge stay owned by the shell.
+		* @param ctx - Client root context.
+		*/
+		function apply(ctx) {
+			ctx.slots.inject("sidebar.brand.mark", () => ctx.slots.inject("conversation.hero.brand.mark", function* () {
+				yield ctx.slots.register({ name: "sidebar.brand.mark" }, QilinSealMark);
+				yield ctx.slots.register({ name: "conversation.hero.brand.mark" }, QilinSealHeroMark);
+			}));
+			ctx.slots.inject("settings.about.mark", () => ctx.slots.register({ name: "settings.about.mark" }, _qilin_agent_client_ui_primitives.QilinSeal));
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/index.js

@@ -0,0 +1,9 @@
+//#region lib/types/index.js
+/**
+* QiLin brand plugin, node half. The empty apply gives Loader a host-side row
+* while the browser half ships through `exports["./client"]`.
+*/
+/** Host plugin body — this package contributes browser presentation only. */
+function apply() {}
+//#endregion
+export { apply };

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

@@ -0,0 +1,21 @@
+/**
+ * The QiLin seal slot occupants. The drawing itself lives in
+ * `@qilin-agent/client-ui-primitives` so the shell's unbranded fallbacks render the
+ * same stamp; this module owns the brand slots that place it.
+ */
+import type { HeroBrandMarkOwnerProps } from '@qilin-agent/client-ui-conversation/client';
+import type { SidebarBrandMarkOwnerProps } from '@qilin-agent/client-ui-sidebar/client';
+export { QilinSeal as QilinSealArtist } from '@qilin-agent/client-ui-primitives';
+/**
+ * Occupy the sidebar brand-mark slot.
+ * @param props - host-supplied mark presentation.
+ * @returns the seal at the sidebar's requested size.
+ */
+export declare function QilinSealMark({ size }: SidebarBrandMarkOwnerProps): import("react").JSX.Element;
+/**
+ * Occupy the conversation hero's brand-mark slot.
+ * @param props - host-supplied mark presentation.
+ * @returns the seal at the hero's requested size and placement class.
+ */
+export declare function QilinSealHeroMark({ size, className }: HeroBrandMarkOwnerProps): import("react").JSX.Element;
+//# sourceMappingURL=Seal.d.ts.map

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

@@ -0,0 +1,12 @@
+/** QiLin occupants for the generic sidebar and conversation brand slots. */
+import type { Context as ClientContext } from '@qilin-agent/kylin';
+/** Required service: the UI slot registry. */
+export declare const inject: string[];
+/**
+ * Fill the sidebar and hero brand-mark slots as one declaration-aware
+ * registration set. The sidebar brand name keeps the shell's own fallback, so
+ * the QiLin label and its build badge stay owned by the shell.
+ * @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,7 @@
+/**
+ * QiLin brand plugin, node half. The empty apply gives Loader a host-side row
+ * while the browser half ships through `exports["./client"]`.
+ */
+/** Host plugin body — this package contributes browser presentation only. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@qilin-agent/client-ui-brand",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "QiLin brand occupants for the Web client's sidebar and conversation-hero brand slots: the 麒麟 seal mark",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/ui-brand"
+  },
+  "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-renderer",
+        "@qilin-agent/client-ui-sidebar",
+        "@qilin-agent/client-ui-conversation"
+      ],
+      "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-test-runtime": "3.1.4",
+    "@qilin-agent/client-ui-conversation": "3.1.4",
+    "@qilin-agent/client-ui-renderer": "3.1.4",
+    "@qilin-agent/client-ui-primitives": "3.1.4",
+    "@qilin-agent/client-ui-sidebar": "3.1.4",
+    "@qilin-agent/client-ui-settings": "3.1.4"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }