@eum-agent/personalization 0.0.0-stage → 1.0.0

package/dist/index.js

@@ -0,0 +1,13 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+//#region src/index.ts
+/** Owns this optional client feature and its browser activation. */
+const plugin = {
+	name: "@eum-agent/personalization",
+	apply(ctx) {
+		const module = fileURLToPath(new URL("../ui/ui.js", import.meta.url));
+		if (existsSync(module)) ctx.client.registerUi({ module });
+	}
+};
+//#endregion
+export { plugin as default };

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@eum-agent/personalization",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "displayName": {
+    "en-US": "Personalization",
+    "zh-CN": "个性化"
+  },
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Theme, typography and interface preferences",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "ui"
+  ],
+  "dependencies": {
+    "zod": "^4.4.3",
+    "i18next": "^26.4.1"
+  },
+  "devDependencies": {
+    "@eum-agent/plugin": "1.0.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "vite": "^8.2.2",
+    "@eum-agent/protocol": "1.0.0",
+    "@eum-agent/kernel": "1.0.0",
+    "@types/ws": "^8.18.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.6",
+    "zustand": "^5.0.15",
+    "react-i18next": "^17.0.13",
+    "lucide-react": "^1.40.0",
+    "@types/semver": "7.8.0"
+  },
+  "yaoguang": {
+    "kind": "extension",
+    "description": {
+      "en-US": "Theme, typography and interface preferences",
+      "zh-CN": "主题、文字排版与界面显示偏好"
+    },
+    "dependencies": {}
+  },
+  "scripts": {
+    "build": "tsdown && vite build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.ui.json"
+  }
 }

package/ui/ui.js

@@ -0,0 +1,613 @@
+import { Dialog, DialogContent, DialogHeader, DialogTitle, FALLBACK_LANGUAGE, LANGUAGES, LANGUAGE_FLAGS, Picker, Segmented, SlotOutlet, ThemeColorPicker, i18next, localeLeaves, themeSwatchColor, useTranslation } from "@eum-agent/host/framework";
+import React, { useId } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region ui-src/i18n.ts
+/** Platform browser strings share the host's language and React translation runtime. */
+var translations;
+/** Binds this activation's registered namespace without reconstructing the owner's namespace. */
+function configureTranslations(ctx) {
+	translations = ctx.i18n;
+}
+/** Observes the shared language while resolving platform-owned copy. */
+function useTranslation$1() {
+	const shared = useTranslation();
+	if (!translations) throw new Error("platform browser translations are not registered");
+	return {
+		...shared,
+		t: translations.t
+	};
+}
+var en_US_default = {
+	settings: {
+		"personalization": "Personalization",
+		"close": "Close",
+		"colorMode": "Color scheme",
+		"systemMode": "System",
+		"lightMode": "Light",
+		"darkMode": "Dark",
+		"brand": "Theme colour",
+		"contentWidth": "Content width",
+		"contentWidthDefault": "Default",
+		"contentWidthWide": "Wide",
+		"contentWidthFull": "Full",
+		"interfaceLanguage": "Interface language"
+	},
+	brand: {
+		"violet": "Violet",
+		"alkaid": "Azure",
+		"celadon": "Teal",
+		"moss": "Green",
+		"honey": "Amber",
+		"lotus": "Rose"
+	},
+	language: {
+		"zh-CN": "简体中文",
+		"en-US": "English"
+	}
+};
+var zh_CN_default = {
+	settings: {
+		"personalization": "个性化设置",
+		"close": "关闭",
+		"colorMode": "显示模式",
+		"systemMode": "跟随系统",
+		"lightMode": "浅色",
+		"darkMode": "深色",
+		"brand": "主题色",
+		"contentWidth": "内容宽度",
+		"contentWidthDefault": "默认",
+		"contentWidthWide": "宽屏",
+		"contentWidthFull": "全宽",
+		"interfaceLanguage": "界面语言"
+	},
+	brand: {
+		"violet": "鸢紫",
+		"alkaid": "澄蓝",
+		"celadon": "湖青",
+		"moss": "松绿",
+		"honey": "琥珀",
+		"lotus": "玫瑰"
+	},
+	language: {
+		"zh-CN": "简体中文",
+		"en-US": "English"
+	}
+};
+//#endregion
+//#region ui-src/catalogues.ts
+/** Registers this owner's localized client copy for its activation. */
+function registerTranslations(ctx) {
+	configureTranslations(ctx);
+	ctx.i18n.register({
+		"en-US": localeLeaves(en_US_default),
+		"zh-CN": localeLeaves(zh_CN_default)
+	}, "zh-CN");
+}
+//#endregion
+//#region ../../../node_modules/.pnpm/zustand@5.0.15_@types+react@19.2.18_react@19.2.8_use-sync-external-store@1.7.0_react@19.2.8_/node_modules/zustand/esm/vanilla.mjs
+var createStoreImpl = (createState) => {
+	let state;
+	const listeners = /* @__PURE__ */ new Set();
+	const setState = (partial, replace) => {
+		const nextState = typeof partial === "function" ? partial(state) : partial;
+		if (!Object.is(nextState, state)) {
+			const previousState = state;
+			state = (replace != null ? replace : typeof nextState !== "object" || nextState === null) ? nextState : Object.assign({}, state, nextState);
+			listeners.forEach((listener) => listener(state, previousState));
+		}
+	};
+	const getState = () => state;
+	const getInitialState = () => initialState;
+	const subscribe = (listener) => {
+		listeners.add(listener);
+		return () => listeners.delete(listener);
+	};
+	const api = {
+		setState,
+		getState,
+		getInitialState,
+		subscribe
+	};
+	const initialState = state = createState(setState, getState, api);
+	return api;
+};
+var createStore = ((createState) => createState ? createStoreImpl(createState) : createStoreImpl);
+//#endregion
+//#region ../../../node_modules/.pnpm/zustand@5.0.15_@types+react@19.2.18_react@19.2.8_use-sync-external-store@1.7.0_react@19.2.8_/node_modules/zustand/esm/react.mjs
+var identity = (arg) => arg;
+function useStore(api, selector = identity) {
+	const slice = React.useSyncExternalStore(api.subscribe, React.useCallback(() => selector(api.getState()), [api, selector]), React.useCallback(() => selector(api.getInitialState()), [api, selector]));
+	React.useDebugValue(slice);
+	return slice;
+}
+var createImpl = (createState) => {
+	const api = createStore(createState);
+	const useBoundStore = (selector) => useStore(api, selector);
+	Object.assign(useBoundStore, api);
+	return useBoundStore;
+};
+var create = ((createState) => createState ? createImpl(createState) : createImpl);
+//#endregion
+//#region ../../../node_modules/.pnpm/zustand@5.0.15_@types+react@19.2.18_react@19.2.8_use-sync-external-store@1.7.0_react@19.2.8_/node_modules/zustand/esm/middleware.mjs
+function createJSONStorage(getStorage, options) {
+	let storage;
+	try {
+		storage = getStorage();
+	} catch (e) {
+		return;
+	}
+	return {
+		getItem: (name) => {
+			var _a;
+			const parse = (str2) => {
+				if (str2 === null) return null;
+				return JSON.parse(str2, options == null ? void 0 : options.reviver);
+			};
+			const str = (_a = storage.getItem(name)) != null ? _a : null;
+			if (str instanceof Promise) return str.then(parse);
+			return parse(str);
+		},
+		setItem: (name, newValue) => storage.setItem(name, JSON.stringify(newValue, options == null ? void 0 : options.replacer)),
+		removeItem: (name) => storage.removeItem(name)
+	};
+}
+var toThenable = (fn) => (input) => {
+	try {
+		const result = fn(input);
+		if (result instanceof Promise) return result;
+		return {
+			then(onFulfilled) {
+				return toThenable(onFulfilled)(result);
+			},
+			catch(_onRejected) {
+				return this;
+			}
+		};
+	} catch (e) {
+		return {
+			then(_onFulfilled) {
+				return this;
+			},
+			catch(onRejected) {
+				return toThenable(onRejected)(e);
+			}
+		};
+	}
+};
+var persistImpl = (config, baseOptions) => (set, get, api) => {
+	let options = {
+		storage: createJSONStorage(() => window.localStorage),
+		partialize: (state) => state,
+		version: 0,
+		merge: (persistedState, currentState) => ({
+			...currentState,
+			...persistedState
+		}),
+		...baseOptions
+	};
+	let hasHydrated = false;
+	let hydrationVersion = 0;
+	const hydrationListeners = /* @__PURE__ */ new Set();
+	const finishHydrationListeners = /* @__PURE__ */ new Set();
+	let storage = options.storage;
+	if (!storage) return config((...args) => {
+		console.warn(`[zustand persist middleware] Unable to update item '${options.name}', the given storage is currently unavailable.`);
+		set(...args);
+	}, get, api);
+	const setItem = () => {
+		const state = options.partialize({ ...get() });
+		return storage.setItem(options.name, {
+			state,
+			version: options.version
+		});
+	};
+	const savedSetState = api.setState;
+	api.setState = (state, replace) => {
+		savedSetState(state, replace);
+		return setItem();
+	};
+	const configResult = config((...args) => {
+		set(...args);
+		return setItem();
+	}, get, api);
+	api.getInitialState = () => configResult;
+	let stateFromStorage;
+	const hydrate = () => {
+		var _a, _b;
+		if (!storage) return;
+		const currentVersion = ++hydrationVersion;
+		hasHydrated = false;
+		hydrationListeners.forEach((cb) => {
+			var _a2;
+			return cb((_a2 = get()) != null ? _a2 : configResult);
+		});
+		const postRehydrationCallback = ((_b = options.onRehydrateStorage) == null ? void 0 : _b.call(options, (_a = get()) != null ? _a : configResult)) || void 0;
+		return toThenable(storage.getItem.bind(storage))(options.name).then((deserializedStorageValue) => {
+			if (deserializedStorageValue) {
+				if (typeof deserializedStorageValue.version === "number" && deserializedStorageValue.version !== options.version) {
+					if (options.migrate) {
+						const migration = options.migrate(deserializedStorageValue.state, deserializedStorageValue.version);
+						if (migration instanceof Promise) return migration.then((result) => [true, result]);
+						return [true, migration];
+					}
+					console.error(`State loaded from storage couldn't be migrated since no migrate function was provided`);
+				} else return [false, deserializedStorageValue.state];
+			}
+			return [false, void 0];
+		}).then((migrationResult) => {
+			var _a2;
+			if (currentVersion !== hydrationVersion) return;
+			const [migrated, migratedState] = migrationResult;
+			stateFromStorage = options.merge(migratedState, (_a2 = get()) != null ? _a2 : configResult);
+			set(stateFromStorage, true);
+			if (migrated) return setItem();
+		}).then(() => {
+			if (currentVersion !== hydrationVersion) return;
+			postRehydrationCallback?.(get(), void 0);
+			stateFromStorage = get();
+			hasHydrated = true;
+			finishHydrationListeners.forEach((cb) => cb(stateFromStorage));
+		}).catch((e) => {
+			if (currentVersion !== hydrationVersion) return;
+			postRehydrationCallback?.(void 0, e);
+		});
+	};
+	api.persist = {
+		setOptions: (newOptions) => {
+			options = {
+				...options,
+				...newOptions
+			};
+			if (newOptions.storage) storage = newOptions.storage;
+		},
+		clearStorage: () => {
+			++hydrationVersion;
+			storage?.removeItem(options.name);
+		},
+		getOptions: () => options,
+		rehydrate: () => hydrate(),
+		hasHydrated: () => hasHydrated,
+		onHydrate: (cb) => {
+			hydrationListeners.add(cb);
+			return () => {
+				hydrationListeners.delete(cb);
+			};
+		},
+		onFinishHydration: (cb) => {
+			finishHydrationListeners.add(cb);
+			return () => {
+				finishHydrationListeners.delete(cb);
+			};
+		}
+	};
+	if (!options.skipHydration) hydrate();
+	return stateFromStorage || configResult;
+};
+var persist = persistImpl;
+//#endregion
+//#region ui-src/lib/theme.ts
+/** Applies a palette atomically, including portals and pseudo-elements, without persisting it. */
+function applyDocumentTheme(mode, brand) {
+	const root = document.documentElement;
+	if (!(root.dataset.uiTheme !== mode || brand !== void 0 && (root.style.getPropertyValue("--brand-h") !== String(brand.hue) || root.style.getPropertyValue("--brand-c") !== String(brand.chroma)))) return;
+	root.dataset.themeChanging = "";
+	try {
+		root.dataset.uiTheme = mode;
+		root.classList.toggle("dark", mode === "dark");
+		if (brand) {
+			root.style.setProperty("--brand-h", String(brand.hue));
+			root.style.setProperty("--brand-c", String(brand.chroma));
+		}
+		root.offsetHeight;
+	} finally {
+		delete root.dataset.themeChanging;
+	}
+}
+//#endregion
+//#region ui-src/store/theme.ts
+/** Browser-local solid color scheme and brand preferences. */
+/** 瑶光 is Alkaid, the star at the end of the Plough's handle, and a B-type
+*  star is blue-white — which is where the default hue comes from. */
+var ALKAID = {
+	id: "alkaid",
+	labelKey: "brand.alkaid",
+	hue: 255,
+	chroma: .15
+};
+/** Ordered brand presets; Alkaid supplies the default presentation. */
+var BRANDS = [
+	ALKAID,
+	{
+		id: "violet",
+		labelKey: "brand.violet",
+		hue: 295,
+		chroma: .15
+	},
+	{
+		id: "celadon",
+		labelKey: "brand.celadon",
+		hue: 185,
+		chroma: .095
+	},
+	{
+		id: "moss",
+		labelKey: "brand.moss",
+		hue: 150,
+		chroma: .12
+	},
+	{
+		id: "honey",
+		labelKey: "brand.honey",
+		hue: 70,
+		chroma: .12
+	},
+	{
+		id: "lotus",
+		labelKey: "brand.lotus",
+		hue: 355,
+		chroma: .15
+	}
+];
+/** Resolves persisted color values to a preset, selecting Alkaid for unmatched values. */
+function resolveBrand(stored) {
+	return BRANDS.find((one) => one.hue === stored.hue && one.chroma === stored.chroma) ?? ALKAID;
+}
+var CONTENT_WIDTHS = [
+	"default",
+	"wide",
+	"full"
+];
+var useTheme = create()(persist((set) => ({
+	mode: "system",
+	setMode: (mode) => set({ mode }),
+	hue: ALKAID.hue,
+	chroma: ALKAID.chroma,
+	setBrand: ({ hue, chroma }) => set({
+		hue,
+		chroma
+	}),
+	contentWidth: "default",
+	setContentWidth: (contentWidth) => set({ contentWidth })
+}), {
+	name: "yaoguang.theme",
+	partialize: ({ hue, chroma, mode, contentWidth }) => ({
+		hue,
+		chroma,
+		mode,
+		contentWidth
+	}),
+	merge: (persisted, current) => {
+		const stored = persisted;
+		const brand = resolveBrand({
+			hue: stored?.hue ?? current.hue,
+			chroma: stored?.chroma ?? current.chroma
+		});
+		return {
+			...current,
+			hue: brand.hue,
+			chroma: brand.chroma,
+			mode: stored?.mode === "dark" || stored?.mode === "light" ? stored.mode : "system",
+			contentWidth: CONTENT_WIDTHS.find((width) => width === stored?.contentWidth) ?? "default"
+		};
+	}
+}));
+/** Applies the scheme, brand and content width to the document, including portalled components. */
+function applyTheme(state) {
+	document.documentElement.dataset.contentWidth = state.contentWidth ?? "default";
+	applyDocumentTheme(state.mode === "system" ? window.matchMedia?.("(prefers-color-scheme: dark)").matches ? "dark" : "light" : state.mode, state);
+}
+var themeActivation;
+/**
+* Applies the stored brand once and keeps it applied. Called before the first
+* feature renders. Withdrawal removes its listeners and restores the host defaults
+* while retaining stored preferences for the next activation.
+*/
+function initTheme() {
+	const activation = Symbol();
+	themeActivation = activation;
+	applyTheme(useTheme.getState());
+	const unsubscribe = useTheme.subscribe((state) => {
+		if (themeActivation === activation) applyTheme(state);
+	});
+	const preference = window.matchMedia?.("(prefers-color-scheme: dark)");
+	const onChange = () => {
+		const state = useTheme.getState();
+		if (themeActivation === activation && state.mode === "system") applyTheme(state);
+	};
+	preference?.addEventListener("change", onChange);
+	return () => {
+		unsubscribe();
+		preference?.removeEventListener("change", onChange);
+		if (themeActivation !== activation) return;
+		themeActivation = void 0;
+		document.documentElement.dataset.contentWidth = "default";
+		document.documentElement.style.removeProperty("--brand-h");
+		document.documentElement.style.removeProperty("--brand-c");
+		applyDocumentTheme("light");
+	};
+}
+//#endregion
+//#region ui-src/components/settings/appearance.tsx
+/** Browser-local language, color scheme and brand preferences. */
+function PreferenceRow({ id, label, children }) {
+	return /* @__PURE__ */ jsxs("div", {
+		className: "flex min-w-0 flex-wrap items-center justify-between gap-x-5 gap-y-3",
+		children: [/* @__PURE__ */ jsx("p", {
+			id,
+			className: "min-w-0 text-sm font-normal",
+			children: label
+		}), /* @__PURE__ */ jsx("div", {
+			className: "flex min-w-0 max-w-full items-center justify-end",
+			children
+		})]
+	});
+}
+/** Preferences apply immediately and persist in this browser without gateway writes. */
+function AppearancePanel() {
+	const { t, i18n } = useTranslation$1();
+	const languageLabel = useId();
+	const current = i18n.resolvedLanguage ?? i18n.language;
+	const { mode, setMode, hue, setBrand, contentWidth, setContentWidth } = useTheme();
+	return /* @__PURE__ */ jsxs("div", {
+		className: "flex min-w-0 flex-col gap-6",
+		children: [
+			/* @__PURE__ */ jsx(PreferenceRow, {
+				label: t("settings.colorMode"),
+				children: /* @__PURE__ */ jsx(Segmented, {
+					label: t("settings.colorMode"),
+					value: mode,
+					onSelect: setMode,
+					options: [
+						{
+							value: "system",
+							label: t("settings.systemMode")
+						},
+						{
+							value: "light",
+							label: t("settings.lightMode")
+						},
+						{
+							value: "dark",
+							label: t("settings.darkMode")
+						}
+					]
+				})
+			}),
+			/* @__PURE__ */ jsx(PreferenceRow, {
+				label: t("settings.brand"),
+				children: /* @__PURE__ */ jsx(ThemeColorPicker, {
+					label: t("settings.brand"),
+					value: BRANDS.find((brand) => brand.hue === hue)?.id ?? "alkaid",
+					options: BRANDS.map((brand) => ({
+						value: brand.id,
+						label: t(brand.labelKey),
+						color: themeSwatchColor(brand)
+					})),
+					onValueChange: (value) => {
+						const brand = BRANDS.find((brand) => brand.id === value);
+						if (brand) setBrand(brand);
+					}
+				})
+			}),
+			/* @__PURE__ */ jsx(PreferenceRow, {
+				label: t("settings.contentWidth"),
+				children: /* @__PURE__ */ jsx(Segmented, {
+					label: t("settings.contentWidth"),
+					value: contentWidth,
+					onSelect: setContentWidth,
+					options: [
+						{
+							value: "default",
+							label: t("settings.contentWidthDefault")
+						},
+						{
+							value: "wide",
+							label: t("settings.contentWidthWide")
+						},
+						{
+							value: "full",
+							label: t("settings.contentWidthFull")
+						}
+					]
+				})
+			}),
+			/* @__PURE__ */ jsx(SlotOutlet, {
+				slot: "shell.personalization.section",
+				props: {}
+			}),
+			/* @__PURE__ */ jsx(PreferenceRow, {
+				id: languageLabel,
+				label: t("settings.interfaceLanguage"),
+				children: /* @__PURE__ */ jsx(Picker, {
+					labelledBy: languageLabel,
+					slot: "language-picker",
+					value: current,
+					options: LANGUAGES.map((language) => ({
+						value: language,
+						label: t(language === "en-US" ? "language.en-US" : "language.zh-CN"),
+						prefix: LANGUAGE_FLAGS[language]
+					})),
+					onSelect: (language) => {
+						i18n.changeLanguage(language);
+					}
+				})
+			})
+		]
+	});
+}
+//#endregion
+//#region ui-src/components/personalization-dialog.tsx
+/** Compact browser-local preferences, independent of gateway settings and their drafts. */
+function PersonalizationDialog({ open, onOpenChange: setOpen }) {
+	const { t } = useTranslation$1();
+	return /* @__PURE__ */ jsx(Dialog, {
+		open,
+		onOpenChange: setOpen,
+		children: /* @__PURE__ */ jsxs(DialogContent, {
+			closeLabel: t("settings.close"),
+			className: "personalization-dialog max-h-[calc(100dvh-4rem)] max-w-lg gap-5 overflow-y-auto p-6 sm:max-w-lg",
+			children: [/* @__PURE__ */ jsx(DialogHeader, { children: /* @__PURE__ */ jsx(DialogTitle, { children: t("settings.personalization") }) }), /* @__PURE__ */ jsx(AppearancePanel, {})]
+		})
+	});
+}
+//#endregion
+//#region ui-src/lib/language.ts
+/** Browser-local language preference and document metadata owned by the platform activation. */
+/** Browser preference key shared with the platform language editor. */
+var STORAGE_KEY = "yaoguang.lang";
+var languageActivation;
+/** Restores the same saved/navigator language choice and retains changes locally. */
+function initLanguage() {
+	const activation = Symbol();
+	languageActivation = activation;
+	let saved;
+	try {
+		saved = localStorage.getItem("yaoguang.lang") ?? void 0;
+	} catch {}
+	const selected = (saved ? [saved] : [...navigator.languages]).map((value) => LANGUAGES.find((language) => language.toLowerCase() === value.toLowerCase()) ?? LANGUAGES.find((language) => language.split("-")[0] === value.split("-")[0])).find(Boolean);
+	if (selected) i18next.changeLanguage(selected);
+	const changed = () => {
+		if (languageActivation !== activation) return;
+		const language = i18next.resolvedLanguage ?? "zh-CN";
+		document.documentElement.lang = language;
+		try {
+			localStorage.setItem(STORAGE_KEY, language);
+		} catch {}
+	};
+	changed();
+	i18next.on("languageChanged", changed);
+	return () => {
+		i18next.off("languageChanged", changed);
+		if (languageActivation !== activation) return;
+		languageActivation = void 0;
+		document.documentElement.lang = FALLBACK_LANGUAGE;
+		i18next.changeLanguage(FALLBACK_LANGUAGE);
+	};
+}
+//#endregion
+//#region ui-src/index.tsx
+/** Browser module version understood by the host. */
+var runtimeVersion = 5;
+/** Personalization contributes presentation without exposing capability-specific state. */
+var provides = [];
+/** Applies preferences and owns their settings, listeners and document presentation. */
+function register(ctx) {
+	registerTranslations(ctx);
+	const stops = [initLanguage(), initTheme()];
+	ctx.slots.register("shell.dialog.surface", {
+		id: "personalization",
+		component: PersonalizationDialog
+	});
+	ctx.slots.register("shell.nav.action", {
+		id: "personalization-action",
+		icon: "palette",
+		label: () => ctx.i18n.t("settings.personalization"),
+		order: 20,
+		onSelect: () => ctx.navigation.openDialog("personalization")
+	});
+	ctx.signal.addEventListener("abort", () => {
+		for (const stop of stops.toReversed()) stop();
+	}, { once: true });
+}
+//#endregion
+export { provides, register, runtimeVersion };

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.