@h-ai/ui 0.1.0-alpha.67 → 0.1.0-alpha.68

package/dist/guide-types.d.ts

@@ -1,6 +1,23 @@
 import type { NavAdapter } from './components/scenes/crud/nav-adapter.js';
-/** 业务文案使用函数延迟求值，切换语言时重新读取应用翻译。 */
+/**
+ * 业务文案使用函数延迟求值，切换语言时重新读取应用翻译。
+ *
+ * @example
+ * ```ts
+ * import type { GuideText } from '@h-ai/ui'
+ * const example: GuideText = () => '开始使用'
+ * ```
+ */
 export type GuideText = string | (() => string);
+/**
+ * 导览步骤；目标缺失时按 optional 决定跳过或停止，准备动作接受取消信号。
+ *
+ * @example
+ * ```ts
+ * import type { GuideStep } from '@h-ai/ui'
+ * const example: GuideStep = { target: 'save', title: '保存', description: '点击保存资料', side: 'bottom' }
+ * ```
+ */
 export interface GuideStep {
     /** data-guide 的值；复杂定位可传入返回元素的函数。 */
     target: string | (() => Element | null);
@@ -12,6 +29,15 @@ export interface GuideStep {
     /** 可选元素缺失时跳过，必要元素缺失时停止并显示提示。 */
     optional?: boolean;
 }
+/**
+ * 具备稳定 id 和版本的导览定义；enabled 仅控制界面是否提供此导览。
+ *
+ * @example
+ * ```ts
+ * import type { GuideTour } from '@h-ai/ui'
+ * const example: GuideTour = { id: 'profile', title: '完善资料', version: 1, steps: [{ target: 'save', title: '保存', description: '保存当前资料' }] }
+ * ```
+ */
 export interface GuideTour {
     id: string;
     title: GuideText;
@@ -23,6 +49,15 @@ export interface GuideTour {
     /** 按当前权限或功能开关决定是否提供此导览。 */
     enabled?: () => boolean;
 }
+/**
+ * 帮助中心文章；业务文案可延迟翻译，Markdown 按组件安全策略渲染。
+ *
+ * @example
+ * ```ts
+ * import type { GuideArticle } from '@h-ai/ui'
+ * const example: GuideArticle = { id: 'start', title: '开始使用', content: '# 操作说明', category: '入门' }
+ * ```
+ */
 export interface GuideArticle {
     id: string;
     title: GuideText;
@@ -33,11 +68,29 @@ export interface GuideArticle {
     tourId?: string;
     enabled?: () => boolean;
 }
+/**
+ * 非敏感的导览偏好记录；版本变化后可重新向用户提供导览。
+ *
+ * @example
+ * ```ts
+ * import type { GuideProgress } from '@h-ai/ui'
+ * const example: GuideProgress = { version: 1, status: 'completed', updatedAt: 1790812800000 }
+ * ```
+ */
 export interface GuideProgress {
     version: number;
     status: 'completed' | 'dismissed' | 'deferred';
     updatedAt: number;
 }
+/**
+ * 导览控制器配置；持久化仅存 UI 偏好，不保存凭证或服务端业务状态。
+ *
+ * @example
+ * ```ts
+ * import type { GuideOptions } from '@h-ai/ui'
+ * const example: GuideOptions = { tours: [{ id: 'intro', title: '入门', steps: [{ target: 'save', title: '保存', description: '提交当前资料' }] }], persistence: 'memory', persistKey: 'demo-guide' }
+ * ```
+ */
 export interface GuideOptions {
     tours: readonly GuideTour[];
     articles?: readonly GuideArticle[];
@@ -48,7 +101,19 @@ export interface GuideOptions {
     /** 每个目标元素的等待上限，默认 3000 毫秒。 */
     waitTimeout?: number;
 }
-/** 浏览器 UI 控制器，操作失败返回 false 并设置 error，不抛业务异常。 */
+/**
+ * 浏览器 UI 控制器，操作失败返回 false 并设置 error，不抛业务异常。
+ *
+ * @example
+ * ```ts
+ * import { createGuide } from '@h-ai/ui'
+ * import type { GuideController } from '@h-ai/ui'
+ * const guide: GuideController = createGuide({ tours: [], articles: [{ id: 'start', title: '开始', content: '# 操作说明' }], persistence: 'memory' })
+ * guide.openHelp('start')
+ * guide.closeHelp()
+ * guide.stop()
+ * ```
+ */
 export interface GuideController {
     readonly tours: readonly GuideTour[];
     readonly articles: readonly GuideArticle[];

package/dist/guide.svelte.d.ts

@@ -1,8 +1,29 @@
 import type { GuideController, GuideOptions, GuideText } from './guide-types.js';
-/** 解析业务文案；既支持普通字符串，也支持应用 i18n 函数。 */
+/**
+ * 解析业务文案；既支持普通字符串，也支持应用 i18n 函数。
+ * @param text - 待处理文本。
+ * @returns 业务字符串或延迟翻译函数的当前文本；空输入为空字符串。
+ *
+ * @example
+ * ```ts
+ * import { resolveGuideText } from '@h-ai/ui'
+ * const title = resolveGuideText(() => '操作说明')
+ * ```
+ */
 export declare function resolveGuideText(text?: GuideText): string;
 /**
  * 创建应用独享的新手引导控制器。SSR 可创建，DOM 操作只在客户端启动时发生。
  * 配置和控制器应在布局组件内创建，避免在 SSR 模块级共享用户状态。
+ * @param options - 本次操作的行为与显示选项。
+ * @returns 导览与帮助中心控制器；交互失败使用 false/error 表达。
+ *
+ * @example
+ * ```ts
+ * import { createGuide } from '@h-ai/ui'
+ * const guide = createGuide({ tours: [{ id: 'intro', title: '入门', steps: [{ target: 'save', title: '保存', description: '提交当前资料' }] }], persistence: 'memory' })
+ * const offered = guide.startIfNeeded('intro')
+ * if (offered) guide.openHelp()
+ * guide.stop()
+ * ```
  */
 export declare function createGuide(options: GuideOptions): GuideController;

package/dist/guide.svelte.js

@@ -5,7 +5,17 @@ import { createGuideStorage } from './guide-storage.js';
 import { getUILocale, uiM } from './messages.js';
 /** 同一浏览器页面只允许一个导览拥有遮罩和键盘监听。 */
 let stopActiveGuide;
-/** 解析业务文案；既支持普通字符串，也支持应用 i18n 函数。 */
+/**
+ * 解析业务文案；既支持普通字符串，也支持应用 i18n 函数。
+ * @param text - 待处理文本。
+ * @returns 业务字符串或延迟翻译函数的当前文本；空输入为空字符串。
+ *
+ * @example
+ * ```ts
+ * import { resolveGuideText } from '@h-ai/ui'
+ * const title = resolveGuideText(() => '操作说明')
+ * ```
+ */
 export function resolveGuideText(text) {
     return typeof text === 'function' ? text() : text ?? '';
 }
@@ -71,6 +81,17 @@ function waitForTarget(step, signal, timeout, ready) {
 /**
  * 创建应用独享的新手引导控制器。SSR 可创建，DOM 操作只在客户端启动时发生。
  * 配置和控制器应在布局组件内创建，避免在 SSR 模块级共享用户状态。
+ * @param options - 本次操作的行为与显示选项。
+ * @returns 导览与帮助中心控制器；交互失败使用 false/error 表达。
+ *
+ * @example
+ * ```ts
+ * import { createGuide } from '@h-ai/ui'
+ * const guide = createGuide({ tours: [{ id: 'intro', title: '入门', steps: [{ target: 'save', title: '保存', description: '提交当前资料' }] }], persistence: 'memory' })
+ * const offered = guide.startIfNeeded('intro')
+ * if (offered) guide.openHelp()
+ * guide.stop()
+ * ```
  */
 export function createGuide(options) {
     const storage = createGuideStorage(options);

package/dist/i18n.svelte.d.ts

@@ -7,19 +7,71 @@
 import type { Locale, LocaleInfo } from '@h-ai/core';
 import { changeUILocale as setGlobalLocale } from './internal/locale.js';
 declare const DEFAULT_LOCALE: string, DEFAULT_LOCALES: LocaleInfo[];
+/**
+ * 检查语言是否匹配应用支持列表，允许区域回退，不把默认值计作命中。
+ * @param locale - 显式语言代码；省略时使用当前上下文。
+ * @param supportedLocales - 应用支持的语言列表。
+ * @returns 是否存在真实支持项。
+ * @example
+ * ```ts
+ * import { isLocaleSupported } from '@h-ai/ui/i18n'
+ * const supported = isLocaleSupported('en-GB')
+ * ```
+ */
 declare function isLocaleSupported(locale: Locale, supportedLocales?: LocaleInfo[]): boolean;
+/**
+ * 将候选语言归一化为支持列表中的实际代码，无命中时使用默认值。
+ * @param locale - 显式语言代码；省略时使用当前上下文。
+ * @param supportedLocales - 应用支持的语言列表。
+ * @param defaultLocale - 无候选命中时的默认语言。
+ * @returns 归一化后的文本。
+ * @example
+ * ```ts
+ * import { resolveLocale } from '@h-ai/ui/i18n'
+ * const locale = resolveLocale('unsupported', undefined, 'zh-CN')
+ * ```
+ */
 declare function resolveLocale(locale: Locale, supportedLocales?: LocaleInfo[], defaultLocale?: Locale): Locale;
+/**
+ * 依浏览器语言顺序选择实际支持项；SSR 或无匹配项返回 null。
+ * @param supportedLocales - 应用支持的语言列表。
+ * @returns 规范的语言代码或 null。
+ * @example
+ * ```ts
+ * import { detectBrowserLocale } from '@h-ai/ui/i18n'
+ * const locale = detectBrowserLocale()
+ * ```
+ */
 declare function detectBrowserLocale(supportedLocales?: LocaleInfo[]): Locale | null;
+/**
+ * 替换消息模板中的命名参数；缺少的参数保留原占位符。
+ * @param template - 包含命名占位符的消息模板。
+ * @param params - 消息插值参数。
+ * @returns 归一化后的文本。
+ * @example
+ * ```ts
+ * import { interpolate } from '@h-ai/ui/i18n'
+ * const message = interpolate('你好，{name}', { name: 'Ada' })
+ * ```
+ */
 declare function interpolate(template: string, params?: Record<string, string | number | boolean>): string;
 /**
  * 创建 locale 状态管理器
  *
  * @param options - 配置选项
- * @param options.defaultLocale - 默认 locale
+ * @param options.defaultLocale - 全部候选不支持后的默认 locale；不在列表时使用首个支持项。
  * @param options.supportedLocales - 支持的 locale 列表
- * @param options.detectBrowser - 是否检测浏览器语言
+ * @param options.detectBrowser - 是否按完整 navigator.languages 顺序匹配；全部失败才回退默认值。
  * @param options.persistKey - localStorage key
  * @returns locale 状态对象
+ *
+ * @example
+ * ```ts
+ * import { createLocaleStore } from '@h-ai/ui'
+ * const locale = createLocaleStore({ defaultLocale: 'zh-CN', detectBrowser: false, persistKey: 'demo-locale' })
+ * locale.set('en-US')
+ * const selected = locale.current
+ * ```
  */
 export declare function createLocaleStore(options?: {
     defaultLocale?: Locale;
@@ -33,7 +85,7 @@ export declare function createLocaleStore(options?: {
     readonly supported: LocaleInfo[];
     /**
      * 设置当前语言
-     * 会同步到 @h-ai/core 的全局 locale 管理器
+     * 浏览器同步到 @h-ai/core；SSR 仅改变当前 store，消息语言由 runWithLocale 绑定。
      * 注意：你还需要调用 Paraglide 的 setLocale 来更新 UI 翻译
      */
     set(locale: Locale): void;
@@ -42,4 +94,13 @@ export declare function createLocaleStore(options?: {
 };
 export type { InterpolationParams, Locale, LocaleInfo } from '@h-ai/core';
 export { DEFAULT_LOCALE, DEFAULT_LOCALES, detectBrowserLocale, interpolate, isLocaleSupported, resolveLocale, setGlobalLocale, };
+/**
+ * 读取 core 当前请求或浏览器上下文的语言，不由 UI store 隐式改写服务端默认值。
+ *
+ * @example
+ * ```ts
+ * import { getGlobalLocale } from '@h-ai/ui'
+ * const currentLocale = getGlobalLocale()
+ * ```
+ */
 export declare const getGlobalLocale: () => Locale;

package/dist/i18n.svelte.js

@@ -9,30 +9,91 @@ import { readStoredValue, writeStoredValue } from './internal/browser-safety.js'
 import { changeUILocale as setGlobalLocale } from './internal/locale.js';
 // 从 core.i18n 解构常用函数
 const { DEFAULT_LOCALE, DEFAULT_LOCALES, } = core.i18n;
+/** 匹配实际支持项；区域/脚本逐级回退，始终返回列表中的原始代码，不执行默认回退。 */
+function matchSupportedLocale(locale, supportedLocales) {
+    const normalize = (value) => value.trim().replaceAll('_', '-').toLowerCase();
+    let candidate = normalize(locale);
+    while (candidate) {
+        const exact = supportedLocales.find(item => normalize(item.code) === candidate);
+        if (exact)
+            return exact.code;
+        const variant = supportedLocales.find(item => normalize(item.code).startsWith(`${candidate}-`));
+        if (variant)
+            return variant.code;
+        const separator = candidate.lastIndexOf('-');
+        candidate = separator < 0 ? '' : candidate.slice(0, separator);
+    }
+    return null;
+}
+/**
+ * 检查语言是否匹配应用支持列表，允许区域回退，不把默认值计作命中。
+ * @param locale - 显式语言代码；省略时使用当前上下文。
+ * @param supportedLocales - 应用支持的语言列表。
+ * @returns 是否存在真实支持项。
+ * @example
+ * ```ts
+ * import { isLocaleSupported } from '@h-ai/ui/i18n'
+ * const supported = isLocaleSupported('en-GB')
+ * ```
+ */
 function isLocaleSupported(locale, supportedLocales = DEFAULT_LOCALES) {
-    const normalized = locale === 'en' ? 'en-US' : locale === 'zh' ? 'zh-CN' : locale;
-    return supportedLocales.some(item => item.code === normalized);
+    return matchSupportedLocale(locale, supportedLocales) !== null;
 }
+/**
+ * 将候选语言归一化为支持列表中的实际代码，无命中时使用默认值。
+ * @param locale - 显式语言代码；省略时使用当前上下文。
+ * @param supportedLocales - 应用支持的语言列表。
+ * @param defaultLocale - 无候选命中时的默认语言。
+ * @returns 归一化后的文本。
+ * @example
+ * ```ts
+ * import { resolveLocale } from '@h-ai/ui/i18n'
+ * const locale = resolveLocale('unsupported', undefined, 'zh-CN')
+ * ```
+ */
 function resolveLocale(locale, supportedLocales = DEFAULT_LOCALES, defaultLocale = DEFAULT_LOCALE) {
-    const normalized = locale === 'en' ? 'en-US' : locale === 'zh' ? 'zh-CN' : locale;
-    return isLocaleSupported(normalized, supportedLocales) ? normalized : defaultLocale;
+    return matchSupportedLocale(locale, supportedLocales)
+        ?? matchSupportedLocale(defaultLocale, supportedLocales)
+        ?? supportedLocales[0]?.code
+        ?? defaultLocale;
 }
+/**
+ * 依浏览器语言顺序选择实际支持项；SSR 或无匹配项返回 null。
+ * @param supportedLocales - 应用支持的语言列表。
+ * @returns 规范的语言代码或 null。
+ * @example
+ * ```ts
+ * import { detectBrowserLocale } from '@h-ai/ui/i18n'
+ * const locale = detectBrowserLocale()
+ * ```
+ */
 function detectBrowserLocale(supportedLocales = DEFAULT_LOCALES) {
-    if (typeof navigator === 'undefined') {
+    if (typeof window === 'undefined' || typeof navigator === 'undefined') {
         return null;
     }
     const browserCandidates = [
-        navigator.language,
         ...(navigator.languages ?? []),
+        navigator.language,
     ];
     for (const candidate of browserCandidates) {
-        const resolved = resolveLocale(candidate, supportedLocales, DEFAULT_LOCALE);
-        if (isLocaleSupported(resolved, supportedLocales)) {
+        const resolved = matchSupportedLocale(candidate, supportedLocales);
+        if (resolved) {
             return resolved;
         }
     }
     return null;
 }
+/**
+ * 替换消息模板中的命名参数；缺少的参数保留原占位符。
+ * @param template - 包含命名占位符的消息模板。
+ * @param params - 消息插值参数。
+ * @returns 归一化后的文本。
+ * @example
+ * ```ts
+ * import { interpolate } from '@h-ai/ui/i18n'
+ * const message = interpolate('你好，{name}', { name: 'Ada' })
+ * ```
+ */
 function interpolate(template, params = {}) {
     return template.replace(/\{(\w+)\}/g, (_, key) => {
         const value = params[key];
@@ -46,21 +107,30 @@ const LOCALE_STORAGE_KEY = 'hai-locale';
  * 创建 locale 状态管理器
  *
  * @param options - 配置选项
- * @param options.defaultLocale - 默认 locale
+ * @param options.defaultLocale - 全部候选不支持后的默认 locale；不在列表时使用首个支持项。
  * @param options.supportedLocales - 支持的 locale 列表
- * @param options.detectBrowser - 是否检测浏览器语言
+ * @param options.detectBrowser - 是否按完整 navigator.languages 顺序匹配；全部失败才回退默认值。
  * @param options.persistKey - localStorage key
  * @returns locale 状态对象
+ *
+ * @example
+ * ```ts
+ * import { createLocaleStore } from '@h-ai/ui'
+ * const locale = createLocaleStore({ defaultLocale: 'zh-CN', detectBrowser: false, persistKey: 'demo-locale' })
+ * locale.set('en-US')
+ * const selected = locale.current
+ * ```
  */
 export function createLocaleStore(options = {}) {
     const { defaultLocale = DEFAULT_LOCALE, supportedLocales = DEFAULT_LOCALES, detectBrowser = true, persistKey = LOCALE_STORAGE_KEY, } = options;
     // 初始化 locale
-    let initialLocale = defaultLocale;
+    let initialLocale = resolveLocale(defaultLocale, supportedLocales, defaultLocale);
     if (typeof window !== 'undefined') {
         // 1. 优先从 localStorage 读取
         const savedLocale = readStoredValue(persistKey);
-        if (savedLocale && isLocaleSupported(savedLocale, supportedLocales)) {
-            initialLocale = savedLocale;
+        const supportedSavedLocale = savedLocale ? matchSupportedLocale(savedLocale, supportedLocales) : null;
+        if (supportedSavedLocale) {
+            initialLocale = supportedSavedLocale;
         }
         // 2. 其次检测浏览器语言
         else if (detectBrowser) {
@@ -70,8 +140,9 @@ export function createLocaleStore(options = {}) {
             }
         }
     }
-    // 同步初始 locale 到 @h-ai/core 的全局管理器
-    setGlobalLocale(initialLocale);
+    // SSR store 属于当前组件树，不能修改另一个请求的默认语言。
+    if (typeof window !== 'undefined')
+        setGlobalLocale(initialLocale);
     // 使用 Svelte 5 runes 创建响应式状态
     let currentLocale = $state(initialLocale);
     return {
@@ -85,14 +156,15 @@ export function createLocaleStore(options = {}) {
         },
         /**
          * 设置当前语言
-         * 会同步到 @h-ai/core 的全局 locale 管理器
+         * 浏览器同步到 @h-ai/core；SSR 仅改变当前 store，消息语言由 runWithLocale 绑定。
          * 注意：你还需要调用 Paraglide 的 setLocale 来更新 UI 翻译
          */
         set(locale) {
             const resolved = resolveLocale(locale, supportedLocales, defaultLocale);
             currentLocale = resolved;
-            // 同步到 @h-ai/core 的全局 locale 管理器
-            setGlobalLocale(resolved);
+            // 服务端语言由外层 runWithLocale 明确绑定，store 只在浏览器同步应用状态。
+            if (typeof window !== 'undefined')
+                setGlobalLocale(resolved);
             // 持久化到 localStorage
             if (typeof window !== 'undefined') {
                 writeStoredValue(persistKey, resolved);
@@ -107,4 +179,13 @@ export function createLocaleStore(options = {}) {
 // 重导出常用常量和函数（便于应用层使用）
 export { DEFAULT_LOCALE, DEFAULT_LOCALES, detectBrowserLocale, interpolate, isLocaleSupported, resolveLocale, setGlobalLocale, };
 // 导出额外的便捷函数
+/**
+ * 读取 core 当前请求或浏览器上下文的语言，不由 UI store 隐式改写服务端默认值。
+ *
+ * @example
+ * ```ts
+ * import { getGlobalLocale } from '@h-ai/ui'
+ * const currentLocale = getGlobalLocale()
+ * ```
+ */
 export const getGlobalLocale = core.i18n.getGlobalLocale;

package/dist/index.d.ts

@@ -8,7 +8,8 @@ export * from './components/index.js';
 export * from './guide-types.js';
 export * from './guide.svelte.js';
 export * from './i18n.svelte.js';
-export * from './internal/browser-safety.js';
+export type { ClipboardHostWriter } from './internal/browser-safety.js';
+export { registerClipboardHostWriter, writeTextToClipboard } from './internal/browser-safety.js';
 export * from './message.svelte.js';
 export * from './messagebox.svelte.js';
 export * from './theme-config.js';

package/dist/index.js

@@ -10,8 +10,7 @@ export * from './guide-types.js';
 export * from './guide.svelte.js';
 // ─── i18n 国际化（Paraglide 辅助工具） ───
 export * from './i18n.svelte.js';
-// ─── 浏览器能力安全辅助（剪贴板、localStorage 等降级方案） ───
-export * from './internal/browser-safety.js';
+export { registerClipboardHostWriter, writeTextToClipboard } from './internal/browser-safety.js';
 // ─── Message 轻量消息提示（类似 ElementUI Message） ───
 export * from './message.svelte.js';
 // ─── MessageBox 命令式弹框（类似 ElementUI MessageBox） ───

package/dist/internal/browser-safety.d.ts

@@ -4,15 +4,38 @@
  * 统一封装容易在受限 WebView、隐私模式或不安全上下文中失败的浏览器 API，
  * 让组件在能力缺失时优雅降级而不是抛出运行时错误。
  */
-/** 宿主页面剪贴板写入器（跨域 iframe 场景由嵌入方注入）。 */
+/**
+ * 宿主页面剪贴板写入器（跨域 iframe 场景由嵌入方注入）。
+ *
+ * @example
+ * ```ts
+ * import type { ClipboardHostWriter } from '@h-ai/ui'
+ * const writer: ClipboardHostWriter = async text => {
+ *   try { await navigator.clipboard.writeText(text); return true }
+ *   catch { return false }
+ * }
+ * ```
+ */
 export type ClipboardHostWriter = (text: string) => Promise<boolean>;
 /**
  * 注册宿主页面剪贴板写入器。
  *
  * 当 iframe 内 Clipboard API 与 execCommand 都不可用时，把文本交给宿主页面写入。
- * 宿主页面是顶层文档，始终聚焦且持有完整剪贴板权限，是跨域 iframe 场景的最终兜底。
+ * 宿主仍须满足自身权限、焦点与用户激活要求；返回 false 表示实际写入未成功，不能保证兜底一定可用。
  *
  * @param writer - 宿主写入器；传入 null 注销
+ * @returns {void} 无返回值；替换宿主写入器，null 用于注销。
+ *
+ * @example
+ * ```ts
+ * import { registerClipboardHostWriter } from '@h-ai/ui'
+ * registerClipboardHostWriter(async text => {
+ *   try { await navigator.clipboard.writeText(text); return true }
+ *   catch { return false }
+ * })
+ * // 宿主销毁时注销，避免保留过期窗口闭包。
+ * registerClipboardHostWriter(null)
+ * ```
  */
 export declare function registerClipboardHostWriter(writer: ClipboardHostWriter | null): void;
 /**
@@ -20,12 +43,29 @@ export declare function registerClipboardHostWriter(writer: ClipboardHostWriter
  *
  * 某些浏览器隐私模式或嵌入式 WebView 会在访问 localStorage 时直接抛出 SecurityError，
  * 这里统一吞掉异常并回退为 null。
+ * @param key - 要读取的条目或消息键。
+ * @returns 偏好值；未保存、SSR 或读取失败时返回 null。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const savedTheme = readStoredValue('demo-theme')
+ * // 只保存非敏感偏好；不可用于认证 Token。
+ * ```
  */
 export declare function readStoredValue(key: string): string | null;
 /**
  * 安全写入 localStorage。
  *
  * 返回值显式告诉调用方持久化是否成功，方便调用方在失败时继续使用内存态而不必中断交互。
+ * @param key - 要读取的条目或消息键。
+ * @param value - 待处理或校验的值。
+ * @returns 持久化是否成功；失败时调用方可继续保留非敏感内存偏好。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const persisted = writeStoredValue('demo-theme', 'dark')
+ * if (!persisted) { const memoryTheme = 'dark' }
+ * ```
  */
 export declare function writeStoredValue(key: string, value: string): boolean;
 /**
@@ -35,5 +75,14 @@ export declare function writeStoredValue(key: string, value: string): boolean;
  * 或浏览器策略禁用时回退到 `document.execCommand('copy')`；
  * 跨域 iframe 中上述两种方式都可能被权限/聚焦策略拒绝时，再回退到宿主页面写入器，
  * 确保尽可能多的环境下复制操作可用。
+ * @param text - 待处理文本。
+ * @returns 任一实际写入路径是否成功。
+ *
+ * @example
+ * ```ts
+ * import { writeTextToClipboard } from '@h-ai/ui'
+ * const copied = await writeTextToClipboard('https://example.com/help')
+ * if (!copied) throw new Error('Clipboard is unavailable')
+ * ```
  */
 export declare function writeTextToClipboard(text: string): Promise<boolean>;

package/dist/internal/browser-safety.js

@@ -9,9 +9,21 @@ let clipboardHostWriter = null;
  * 注册宿主页面剪贴板写入器。
  *
  * 当 iframe 内 Clipboard API 与 execCommand 都不可用时，把文本交给宿主页面写入。
- * 宿主页面是顶层文档，始终聚焦且持有完整剪贴板权限，是跨域 iframe 场景的最终兜底。
+ * 宿主仍须满足自身权限、焦点与用户激活要求；返回 false 表示实际写入未成功，不能保证兜底一定可用。
  *
  * @param writer - 宿主写入器；传入 null 注销
+ * @returns {void} 无返回值；替换宿主写入器，null 用于注销。
+ *
+ * @example
+ * ```ts
+ * import { registerClipboardHostWriter } from '@h-ai/ui'
+ * registerClipboardHostWriter(async text => {
+ *   try { await navigator.clipboard.writeText(text); return true }
+ *   catch { return false }
+ * })
+ * // 宿主销毁时注销，避免保留过期窗口闭包。
+ * registerClipboardHostWriter(null)
+ * ```
  */
 export function registerClipboardHostWriter(writer) {
     clipboardHostWriter = writer;
@@ -21,12 +33,20 @@ export function registerClipboardHostWriter(writer) {
  *
  * 某些浏览器隐私模式或嵌入式 WebView 会在访问 localStorage 时直接抛出 SecurityError，
  * 这里统一吞掉异常并回退为 null。
+ * @param key - 要读取的条目或消息键。
+ * @returns 偏好值；未保存、SSR 或读取失败时返回 null。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const savedTheme = readStoredValue('demo-theme')
+ * // 只保存非敏感偏好；不可用于认证 Token。
+ * ```
  */
 export function readStoredValue(key) {
-    if (typeof localStorage === 'undefined') {
-        return null;
-    }
     try {
+        if (typeof localStorage === 'undefined') {
+            return null;
+        }
         return localStorage.getItem(key);
     }
     catch {
@@ -37,12 +57,21 @@ export function readStoredValue(key) {
  * 安全写入 localStorage。
  *
  * 返回值显式告诉调用方持久化是否成功，方便调用方在失败时继续使用内存态而不必中断交互。
+ * @param key - 要读取的条目或消息键。
+ * @param value - 待处理或校验的值。
+ * @returns 持久化是否成功；失败时调用方可继续保留非敏感内存偏好。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const persisted = writeStoredValue('demo-theme', 'dark')
+ * if (!persisted) { const memoryTheme = 'dark' }
+ * ```
  */
 export function writeStoredValue(key, value) {
-    if (typeof localStorage === 'undefined') {
-        return false;
-    }
     try {
+        if (typeof localStorage === 'undefined') {
+            return false;
+        }
         localStorage.setItem(key, value);
         return true;
     }
@@ -57,6 +86,15 @@ export function writeStoredValue(key, value) {
  * 或浏览器策略禁用时回退到 `document.execCommand('copy')`；
  * 跨域 iframe 中上述两种方式都可能被权限/聚焦策略拒绝时，再回退到宿主页面写入器，
  * 确保尽可能多的环境下复制操作可用。
+ * @param text - 待处理文本。
+ * @returns 任一实际写入路径是否成功。
+ *
+ * @example
+ * ```ts
+ * import { writeTextToClipboard } from '@h-ai/ui'
+ * const copied = await writeTextToClipboard('https://example.com/help')
+ * if (!copied) throw new Error('Clipboard is unavailable')
+ * ```
  */
 export async function writeTextToClipboard(text) {
     // 现代 Clipboard API（仅安全上下文可用）