@icen.ai/ui 0.9.0 → 0.10.0

package/dist/behaviors/theme.d.mts

@@ -1,21 +1,26 @@
+/** Theme = palette + dark mode + primitive. 现代、像素、中式、苏式 are independent primitives.
+ * data-icen-preset selects color; data-icen-style selects the primitive.
+ * Geometry/materials never replace the selected color theme. */
 interface ThemeState {
     preset: string;
     dark: boolean;
     style: string;
 }
-declare const PRESETS: readonly ["clay", "piano", "art", "vangogh", "ink", "retro"];
-declare const STYLES: readonly ["modern", "retro", "terminal"];
+declare const PRESETS: string[];
+declare const PRIMITIVES: readonly ["modern", "chinese", "soviet", "pixel"];
+declare function registerPrimitive(name: string): boolean;
+declare function listPrimitives(): string[];
 declare const STORAGE_KEY = "icen.ui.theme";
 /**
- * 注册宿主自建预设（宿主先在自家 CSS 写好 `.<name>` 与 `.<name>.dark` 完整 token 面，
- * 仿照 colors.css 现有 6 套）。名字须命中 /^[a-z][a-z0-9-]{1,20}$/ 且不与
+ * 注册宿主自建预设（宿主先在自家 CSS 写好 `.<name>` 与 `.<name>[data-icen-theme="dark"]` 完整 token 面，
+ * 仿照 colors.css 的既有主题）。名字须命中 /^[a-z][a-z0-9-]{1,20}$/ 且不与
  * dark / style-* 保留字冲突；注册只影响 listThemePresets() 枚举（UI 切换器用），
  * 不注册的自建预设同样可以 setTheme（校验同样放行）。返回是否接受注册。
  */
 declare function registerThemePreset(name: string): boolean;
 /** 全部可用预设名：内置 6 套 + 已注册的自建预设（UI 切换器枚举用，顺序稳定）。 */
 declare function listThemePresets(): string[];
-/** 默认主题：clay + 跟随系统明暗 + modern。SSR 下返回离线兜底值。 */
+/** 默认主题：现代主题 + 跟随系统明暗 + 现代原语。SSR 下返回离线兜底值。 */
 declare function getDefaultTheme(): ThemeState;
 /** 读 localStorage 中的持久化主题；缺失或坏数据回退默认。 */
 declare function getTheme(): ThemeState;
@@ -23,14 +28,16 @@ declare function getTheme(): ThemeState;
 declare function applyTheme(t: ThemeState): void;
 /** 合并当前主题与 patch，应用并持久化，返回新态。patch 中的非法枚举值回退默认。 */
 declare function setTheme(patch: Partial<ThemeState>): ThemeState;
+/** 当前实际生效的外观；applyTheme 或存储不可写时仍准确。getTheme 专门读取持久化偏好。 */
+declare function getCurrentTheme(): ThemeState;
 /** 切换明暗，返回新态。 */
 declare function toggleDark(): ThemeState;
-/** 只切风格 profile（modern / retro / terminal；非法值回退 modern），返回新态。 */
-declare function setStyle(style: string): ThemeState;
+/** 只切原语（现代 / 中式 / 苏式 / 像素；非法值回退现代），返回新态。 */
+declare function setPrimitive(primitive: string): ThemeState;
 /** 页面加载早期调用：读持久化主题并应用，防闪烁。
  *  无持久化偏好时，自动跟随系统的 prefers-color-scheme 变化（实时）；
  *  一旦用户显式 setTheme / toggleDark，跟随停止（持久化优先）。
  *  重复调用幂等（系统监听不会重复挂）。 */
 declare function initTheme(): ThemeState;
 
-export { PRESETS, STORAGE_KEY, STYLES, type ThemeState, applyTheme, getDefaultTheme, getTheme, initTheme, listThemePresets, registerThemePreset, setStyle, setTheme, toggleDark };
+export { PRESETS, PRIMITIVES, STORAGE_KEY, type ThemeState, applyTheme, getCurrentTheme, getDefaultTheme, getTheme, initTheme, listPrimitives, listThemePresets, registerPrimitive, registerThemePreset, setPrimitive, setTheme, toggleDark };

package/dist/behaviors/theme.mjs

@@ -1,3 +1,313 @@
+// src/tokens/themes.json
+var themes_default = [
+  {
+    id: "modern",
+    name: "\u73B0\u4EE3",
+    label: "\u73B0\u4EE3",
+    summary: "\u74F7\u767D\u4E0E\u51B7\u84DD\uFF0C\u8BA9\u5185\u5BB9\u6E05\u695A\uFF0C\u8BA9\u64CD\u4F5C\u8F7B\u76C8\u3002",
+    material: "\u6E05\u900F\u74F7\u9762 \xB7 \u51B7\u8C03\u67D4\u5149",
+    light: {
+      bg: "#f5f6f8",
+      surface: "#ffffff",
+      raised: "#edf0f5",
+      ink: "#202124",
+      muted: "#606773",
+      faint: "#626c79",
+      accent: "#087bf5",
+      accentStrong: "#0062cc",
+      accentText: "#0059b8",
+      onAccent: "#ffffff",
+      cold: "#58758f",
+      success: "#247347",
+      warning: "#846000",
+      error: "#b02d36",
+      info: "#336c91",
+      shadowColor: "#182337",
+      glassOpacity: 84,
+      shadowStrength: 10,
+      edgeStrength: 11,
+      highlightStrength: 76
+    },
+    dark: {
+      bg: "#15171b",
+      surface: "#22272f",
+      raised: "#2c333e",
+      ink: "#f1f4f9",
+      muted: "#b1bbca",
+      faint: "#9faabd",
+      accent: "#8cbdff",
+      accentStrong: "#91bfff",
+      accentText: "#9dc6ff",
+      onAccent: "#10223c",
+      cold: "#9bb4cb",
+      success: "#8bd3a6",
+      warning: "#e4c373",
+      error: "#f2a1a5",
+      info: "#97c8e8",
+      shadowColor: "#000000",
+      glassOpacity: 90,
+      shadowStrength: 27,
+      edgeStrength: 13,
+      highlightStrength: 8
+    }
+  },
+  {
+    id: "dongyun",
+    name: "\u4E1C\u97F5",
+    label: "dongyun \u4E1C\u97F5",
+    summary: "\u7EE2\u767D\u7559\u51FA\u547C\u5438\uFF0C\u9752\u74F7\u4E0E\u6C89\u58A8\u76F8\u6620\uFF0C\u6E29\u6DA6\u800C\u6709\u5206\u5BF8\u3002",
+    material: "\u7EE2\u672C\u4E0E\u9752\u74F7 \xB7 \u6E29\u6DA6\u7EC6\u5149",
+    light: {
+      bg: "#f4f1e9",
+      surface: "#fffdf7",
+      raised: "#e9e6db",
+      ink: "#293a34",
+      muted: "#60695c",
+      faint: "#626957",
+      accent: "#477668",
+      accentStrong: "#305c4e",
+      accentText: "#315748",
+      onAccent: "#fffdf7",
+      cold: "#85724d",
+      success: "#3b6544",
+      warning: "#795517",
+      error: "#a33e37",
+      info: "#426477",
+      shadowColor: "#343c2e",
+      glassOpacity: 97,
+      shadowStrength: 7,
+      edgeStrength: 14,
+      highlightStrength: 40
+    },
+    dark: {
+      bg: "#181e1b",
+      surface: "#242e28",
+      raised: "#334037",
+      ink: "#f0eee0",
+      muted: "#bfc8b6",
+      faint: "#b2bea9",
+      accent: "#a0c5ac",
+      accentStrong: "#b0d0b6",
+      accentText: "#bdd9c1",
+      onAccent: "#24382b",
+      cold: "#d0bd8d",
+      success: "#accd9e",
+      warning: "#e1c68d",
+      error: "#edada2",
+      info: "#accbda",
+      shadowColor: "#080e0a",
+      glassOpacity: 98,
+      shadowStrength: 25,
+      edgeStrength: 17,
+      highlightStrength: 5
+    }
+  },
+  {
+    id: "jugou",
+    name: "\u5DE8\u6784",
+    label: "jugou \u5DE8\u6784",
+    summary: "\u77F3\u7070\u767D\u3001\u94C1\u7070\u4E0E\u6DF1\u6731\u7EA2\uFF0C\u4EE5\u6E05\u695A\u7684\u7ED3\u6784\u6258\u4F4F\u6709\u5206\u91CF\u7684\u5185\u5BB9\u3002",
+    material: "\u6DF7\u51DD\u571F\u4E0E\u642A\u74F7 \xB7 \u5B9E\u4F53\u627F\u91CD",
+    light: {
+      bg: "#edece6",
+      surface: "#faf9f3",
+      raised: "#e1e0d8",
+      ink: "#252723",
+      muted: "#5e625b",
+      faint: "#62645b",
+      accent: "#b53c2d",
+      accentStrong: "#9e3025",
+      accentText: "#912e24",
+      onAccent: "#fffaf0",
+      cold: "#596d75",
+      success: "#3d6141",
+      warning: "#765413",
+      error: "#9a3138",
+      info: "#3c6078",
+      shadowColor: "#242821",
+      glassOpacity: 100,
+      shadowStrength: 16,
+      edgeStrength: 24,
+      highlightStrength: 20
+    },
+    dark: {
+      bg: "#1b1d1c",
+      surface: "#2a2e2c",
+      raised: "#393e3b",
+      ink: "#f4f0e3",
+      muted: "#c3c6ba",
+      faint: "#b8bdae",
+      accent: "#ed9d86",
+      accentStrong: "#f1ac92",
+      accentText: "#f6bba3",
+      onAccent: "#3c211b",
+      cold: "#b1c5ce",
+      success: "#aecb9f",
+      warning: "#e6c88b",
+      error: "#f0b1ad",
+      info: "#accbdc",
+      shadowColor: "#090d0b",
+      glassOpacity: 100,
+      shadowStrength: 38,
+      edgeStrength: 25,
+      highlightStrength: 4
+    }
+  },
+  {
+    id: "piano",
+    name: "\u94A2\u7434",
+    label: "piano \u94A2\u7434",
+    summary: "\u8C61\u7259\u767D\u4E0E\u4E4C\u6728\u9ED1\u4FDD\u6301\u4E3B\u6B21\uFF0C\u91D1\u68D5\u53EA\u843D\u5728\u5173\u952E\u52A8\u4F5C\u3002",
+    material: "\u8C61\u7259\u7434\u952E \xB7 \u4E4C\u6728\u4E0E\u6F06\u9762\u5FAE\u5149",
+    light: {
+      bg: "#f5f3ed",
+      surface: "#fffefb",
+      raised: "#ece8df",
+      ink: "#252522",
+      muted: "#69685f",
+      faint: "#6a675c",
+      accent: "#94713f",
+      accentStrong: "#765424",
+      accentText: "#72501f",
+      onAccent: "#fffefb",
+      cold: "#657386",
+      success: "#3d6e4b",
+      warning: "#805d17",
+      error: "#a53d39",
+      info: "#456984",
+      shadowColor: "#24231e",
+      glassOpacity: 89,
+      shadowStrength: 12,
+      edgeStrength: 14,
+      highlightStrength: 90
+    },
+    dark: {
+      bg: "#131416",
+      surface: "#222427",
+      raised: "#303338",
+      ink: "#f4f1e8",
+      muted: "#b8b5aa",
+      faint: "#aaa89e",
+      accent: "#d2b278",
+      accentStrong: "#d8ba85",
+      accentText: "#e3c48c",
+      onAccent: "#292215",
+      cold: "#a5b3c6",
+      success: "#a4cfb0",
+      warning: "#e2c57f",
+      error: "#e9aaa7",
+      info: "#a5c5e3",
+      shadowColor: "#000000",
+      glassOpacity: 93,
+      shadowStrength: 33,
+      edgeStrength: 17,
+      highlightStrength: 11
+    }
+  },
+  {
+    id: "monet",
+    name: "\u83AB\u5948",
+    label: "monet \u83AB\u5948",
+    summary: "\u6C34\u9762\u84DD\u7EFF\u53E0\u51FA\u67D4\u5149\uFF0C\u7D2B\u8C03\u542B\u84C4\uFF0C\u5B89\u9759\u800C\u4E0D\u5BE1\u6DE1\u3002",
+    material: "\u7761\u83B2\u6C34\u9762 \xB7 \u84DD\u7EFF\u67D4\u5149\u4E0E\u542B\u84C4\u7D2B\u8C03",
+    light: {
+      bg: "#f4f7f4",
+      surface: "#fcfdfb",
+      raised: "#e8eeea",
+      ink: "#20332e",
+      muted: "#5b6f65",
+      faint: "#5b6e64",
+      accent: "#2b675c",
+      accentStrong: "#245c50",
+      accentText: "#24574c",
+      onAccent: "#ffffff",
+      cold: "#667c8a",
+      success: "#307449",
+      warning: "#805f1b",
+      error: "#a43d42",
+      info: "#3d6a82",
+      shadowColor: "#23372f",
+      glassOpacity: 93,
+      shadowStrength: 8,
+      edgeStrength: 12,
+      highlightStrength: 52
+    },
+    dark: {
+      bg: "#121d1a",
+      surface: "#1d2d27",
+      raised: "#2c3d34",
+      ink: "#e6f0e7",
+      muted: "#a7c0b1",
+      faint: "#9cb1a4",
+      accent: "#93c9ad",
+      accentStrong: "#a0d2b7",
+      accentText: "#a5d8bd",
+      onAccent: "#173328",
+      cold: "#a1baca",
+      success: "#91d2a2",
+      warning: "#dac487",
+      error: "#e8a7ad",
+      info: "#9bc4da",
+      shadowColor: "#06100b",
+      glassOpacity: 95,
+      shadowStrength: 27,
+      edgeStrength: 14,
+      highlightStrength: 6
+    }
+  },
+  {
+    id: "vangogh",
+    name: "\u68B5\u9AD8",
+    label: "vangogh \u68B5\u9AD8",
+    summary: "\u65E5\u95F4\u662F\u9EA6\u7530\u91CC\u7684\u94B4\u84DD\uFF0C\u5165\u591C\u662F\u6DF1\u84DD\u4E0A\u7684\u661F\u5149\u91D1\u3002",
+    material: "\u4E9A\u9EBB\u753B\u5E03 \xB7 \u94B4\u84DD\u4E0E\u9EA6\u7A57\u91D1",
+    light: {
+      bg: "#f8f3e4",
+      surface: "#fffdf3",
+      raised: "#efe5c9",
+      ink: "#253650",
+      muted: "#5c6580",
+      faint: "#5e667b",
+      accent: "#275ea0",
+      accentStrong: "#224e83",
+      accentText: "#234c7b",
+      onAccent: "#fffdf3",
+      cold: "#a0711e",
+      success: "#416b3a",
+      warning: "#855a15",
+      error: "#a83c31",
+      info: "#356b85",
+      shadowColor: "#463d27",
+      glassOpacity: 92,
+      shadowStrength: 11,
+      edgeStrength: 13,
+      highlightStrength: 62
+    },
+    dark: {
+      bg: "#111e32",
+      surface: "#1c2d46",
+      raised: "#2a3f5b",
+      ink: "#f8efcf",
+      muted: "#c2c4b5",
+      faint: "#afb7bd",
+      accent: "#e5be54",
+      accentStrong: "#ebc568",
+      accentText: "#efd181",
+      onAccent: "#2b2617",
+      cold: "#88a5d6",
+      success: "#b3d29b",
+      warning: "#f0cd7b",
+      error: "#efaaa0",
+      info: "#a1c9e8",
+      shadowColor: "#050b15",
+      glassOpacity: 93,
+      shadowStrength: 30,
+      edgeStrength: 16,
+      highlightStrength: 7
+    }
+  }
+];
+
 // src/behaviors/events.ts
 function emitIcen(source, type, detail) {
   return source.dispatchEvent(
@@ -5,14 +315,44 @@ function emitIcen(source, type, detail) {
   );
 }
 
+// src/behaviors/design.ts
+var appearanceFrame;
+function prepareDesignChange() {
+  if (typeof document === "undefined" || typeof window.requestAnimationFrame !== "function") return;
+  const root = document.documentElement;
+  root.setAttribute("data-icen-design-changing", "");
+  void root.offsetWidth;
+  if (appearanceFrame !== void 0) window.cancelAnimationFrame(appearanceFrame);
+  appearanceFrame = window.requestAnimationFrame(() => {
+    appearanceFrame = window.requestAnimationFrame(() => {
+      void root.offsetWidth;
+      root.removeAttribute("data-icen-design-changing");
+      appearanceFrame = void 0;
+    });
+  });
+}
+
 // src/behaviors/theme.ts
-var PRESETS = ["clay", "piano", "art", "vangogh", "ink", "retro"];
-var STYLES = ["modern", "retro", "terminal"];
+var PRESETS = themes_default.map((theme) => theme.id);
+var PRIMITIVES = ["modern", "chinese", "soviet", "pixel"];
+var customPrimitives = /* @__PURE__ */ new Set();
+function registerPrimitive(name) {
+  if (!/^[a-z][a-z0-9-]{1,20}$/.test(name)) return false;
+  if (PRIMITIVES.includes(name)) return true;
+  customPrimitives.add(name);
+  return true;
+}
+function listPrimitives() {
+  return [...PRIMITIVES, ...customPrimitives];
+}
+function normalizePrimitive(name) {
+  return typeof name === "string" && listPrimitives().includes(name) ? name : "modern";
+}
 var STORAGE_KEY = "icen.ui.theme";
 var PRESET_NAME_RE = /^[a-z][a-z0-9-]{1,20}$/;
-var RESERVED_PRESET_NAMES = /* @__PURE__ */ new Set(["dark", ...STYLES.map((s) => `style-${s}`)]);
+var RESERVED_PRESET_NAMES = /* @__PURE__ */ new Set(["dark"]);
 var customPresets = /* @__PURE__ */ new Set();
-var FALLBACK = { preset: "clay", dark: false, style: "modern" };
+var FALLBACK = { preset: "modern", dark: false, style: "modern" };
 function isBrowser() {
   return typeof document !== "undefined";
 }
@@ -25,14 +365,14 @@ function registerThemePreset(name) {
   return true;
 }
 function listThemePresets() {
-  return [...PRESETS, ...customPresets];
+  return [.../* @__PURE__ */ new Set([...PRESETS, ...customPresets])];
 }
 function getDefaultTheme() {
   if (!isBrowser() || typeof window.matchMedia !== "function") {
     return { ...FALLBACK };
   }
   return {
-    preset: "clay",
+    preset: "modern",
     dark: window.matchMedia("(prefers-color-scheme: dark)").matches,
     style: "modern"
   };
@@ -41,7 +381,7 @@ function isThemeState(v) {
   if (typeof v !== "object" || v === null) return false;
   const t = v;
   return typeof t.preset === "string" && /* 持久化路径与 setTheme 同一开放白名单：自建预设跨刷新存活 */
-  isValidPreset(t.preset) && typeof t.dark === "boolean" && typeof t.style === "string" && STYLES.includes(t.style);
+  isValidPreset(t.preset) && typeof t.dark === "boolean" && typeof t.style === "string";
 }
 function getTheme() {
   if (!isBrowser()) return getDefaultTheme();
@@ -50,7 +390,14 @@ function getTheme() {
     if (!raw) return getDefaultTheme();
     const parsed = JSON.parse(raw);
     if (!isThemeState(parsed)) return getDefaultTheme();
-    return { preset: parsed.preset, dark: parsed.dark, style: parsed.style };
+    const normalized = { preset: parsed.preset, dark: parsed.dark, style: normalizePrimitive(parsed.style) };
+    if (normalized.style !== parsed.style || normalized.preset !== parsed.preset) {
+      try {
+        window.localStorage.setItem(STORAGE_KEY, JSON.stringify(normalized));
+      } catch {
+      }
+    }
+    return normalized;
   } catch {
     return getDefaultTheme();
   }
@@ -58,17 +405,14 @@ function getTheme() {
 var lastApplied = null;
 function apply(t) {
   if (!isBrowser()) return;
-  const cls = document.documentElement.classList;
-  if (lastApplied && !PRESETS.includes(lastApplied.preset)) {
-    cls.remove(lastApplied.preset);
-  }
-  for (const p of PRESETS) cls.remove(p);
-  for (const s of STYLES) cls.remove(`style-${s}`);
-  cls.remove("dark");
-  cls.add(t.preset);
-  if (t.dark) cls.add("dark");
-  cls.add(`style-${t.style}`);
-  const changed = lastApplied !== null && (lastApplied.preset !== t.preset || lastApplied.dark !== t.dark || lastApplied.style !== t.style);
+  prepareDesignChange();
+  const root = document.documentElement;
+  const hadAppearance = root.hasAttribute("data-icen-style");
+  root.setAttribute("data-icen-preset", t.preset);
+  if (t.dark) root.setAttribute("data-icen-theme", "dark");
+  else root.removeAttribute("data-icen-theme");
+  root.setAttribute("data-icen-style", t.style);
+  const changed = hadAppearance && lastApplied !== null && (lastApplied.preset !== t.preset || lastApplied.dark !== t.dark || lastApplied.style !== t.style);
   lastApplied = { ...t };
   if (changed) {
     emitIcen(document.documentElement, "icen:theme-change", {
@@ -79,34 +423,49 @@ function apply(t) {
   }
 }
 function applyTheme(t) {
-  apply(t);
+  apply({ ...t, style: normalizePrimitive(t.style) });
 }
 function setTheme(patch) {
-  const merged = { ...getTheme(), ...patch };
+  const merged = { ...getCurrentTheme(), ...patch };
   const next = {
     preset: isValidPreset(merged.preset) ? merged.preset : FALLBACK.preset,
     dark: merged.dark === true,
-    style: STYLES.includes(merged.style) ? merged.style : FALLBACK.style
+    style: normalizePrimitive(merged.style)
   };
-  apply(next);
   if (isBrowser()) {
     try {
       window.localStorage.setItem(STORAGE_KEY, JSON.stringify(next));
     } catch {
     }
   }
+  apply(next);
   return next;
 }
+function getCurrentTheme() {
+  if (!isBrowser()) return getDefaultTheme();
+  const root = document.documentElement;
+  const preset = root.getAttribute("data-icen-preset");
+  const style = root.getAttribute("data-icen-style");
+  if (!preset || !style) return getTheme();
+  return { preset, style: normalizePrimitive(style), dark: root.getAttribute("data-icen-theme") === "dark" };
+}
 function toggleDark() {
-  return setTheme({ dark: !getTheme().dark });
+  return setTheme({ dark: !getCurrentTheme().dark });
 }
-function setStyle(style) {
-  return setTheme({ style });
+function setPrimitive(primitive) {
+  return setTheme({ style: primitive });
 }
 var systemListenerAttached = false;
+var storageListenerAttached = false;
 function initTheme() {
   const t = getTheme();
   applyTheme(t);
+  if (isBrowser() && !storageListenerAttached) {
+    storageListenerAttached = true;
+    window.addEventListener("storage", (event) => {
+      if (event.key === STORAGE_KEY || event.key === null) applyTheme(getTheme());
+    });
+  }
   if (isBrowser() && typeof window.matchMedia === "function" && !systemListenerAttached && !hasPersistedPreference()) {
     systemListenerAttached = true;
     let lastDark = t.dark;
@@ -138,15 +497,18 @@ function hasPersistedPreference() {
 }
 export {
   PRESETS,
+  PRIMITIVES,
   STORAGE_KEY,
-  STYLES,
   applyTheme,
+  getCurrentTheme,
   getDefaultTheme,
   getTheme,
   initTheme,
+  listPrimitives,
   listThemePresets,
+  registerPrimitive,
   registerThemePreset,
-  setStyle,
+  setPrimitive,
   setTheme,
   toggleDark
 };

package/dist/behaviors/toast.d.mts

@@ -1,45 +1,44 @@
-type ToastKind = 'ok' | 'err' | 'warn' | 'info' | 'success' | 'error';
+import { FeedbackAction } from './feedback.js';
+import { IconName } from './icons.js';
+
+type ToastKind = 'warn' | 'info' | 'success' | 'error';
 interface ToastOptions {
-    /** 保留时长（毫秒），默认 2600；带 action 时默认 6000 */
+    /** 保留时长（毫秒），默认 2600；action 默认 6000；0 常驻。焦点/hover/后台/忙碌时暂停。 */
     ms?: number;
     /** 配合 action：可撤销 / 重试 / 查看等 */
     actionLabel?: string;
-    /** action 触发回调；返回 false 阻止 toast 关闭 */
-    onAction?: () => void | Promise<void> | boolean;
-    /** 内联 SVG 字符串图标（消毒后渲染为 .toast-icon）；非 <svg> 开头或解析失败静默忽略 */
+    /** 等待同步/异步操作；false 保持打开，reject 保留重试反馈。关闭会 abort 传入的 signal。 */
+    onAction?: FeedbackAction;
+    /** Inline retry feedback on thrown/rejected actions; defaults to localized text. */
+    actionError?: string;
+    /** 内联 SVG 字符串图标（消毒后渲染为 .icen-toast-icon）；非 <svg> 开头或解析失败静默忽略 */
     icon?: string;
-    /** 显示右上角关闭按钮（.toast-close，点击即关闭本条），默认 false */
+    iconName?: IconName;
+    /** 显示右上角关闭按钮（.icen-toast-close，点击即关闭本条），默认 false */
     closable?: boolean;
-    /** 显示底部超时进度条（.toast-progress，动画时长 = 本条保留时长），默认 false */
+    /** 显示底部超时进度条（.icen-toast-progress，动画时长 = 本条保留时长），默认 false */
     progress?: boolean;
 }
 /** 单条 toast 句柄：dismiss() 立即关闭本条（幂等，可重复调用）。 */
 interface ToastHandle {
     dismiss(): void;
+    pause(): void;
+    resume(): void;
 }
 interface ToastConfig {
     /** 同屏最大堆叠，默认 5；超出从最早的开始移除 */
     maxStack?: number;
 }
+type ToastTiming = number | ToastOptions;
 interface ToastFn {
-    (message: string, kind?: ToastKind, ms?: number): ToastHandle;
-    /** success 语义（.toast--success），规范词表入口 */
-    success(message: string, ms?: number): ToastHandle;
-    /**
-     * success 语义（.toast--success）。
-     * @deprecated 词表统一：改用 toast.success()，本别名下个大版本删除。
-     */
-    ok(message: string, ms?: number): ToastHandle;
-    /** error 语义（.toast--error），规范词表入口 */
-    error(message: string, ms?: number): ToastHandle;
-    /**
-     * error 语义（.toast--error）。
-     * @deprecated 词表统一：改用 toast.error()，本别名下个大版本删除。
-     */
-    err(message: string, ms?: number): ToastHandle;
-    warn(message: string, ms?: number): ToastHandle;
-    info(message: string, ms?: number): ToastHandle;
-    action(message: string, actionLabel: string, onAction: () => void, ms?: number): ToastHandle;
+    (message: string, kind?: ToastKind, ms?: ToastTiming): ToastHandle;
+    /** success 语义（.icen-toast--success） */
+    success(message: string, ms?: ToastTiming): ToastHandle;
+    /** error 语义（.icen-toast--error） */
+    error(message: string, ms?: ToastTiming): ToastHandle;
+    warn(message: string, ms?: ToastTiming): ToastHandle;
+    info(message: string, ms?: ToastTiming): ToastHandle;
+    action(message: string, actionLabel: string, onAction: FeedbackAction, ms?: ToastTiming): ToastHandle;
     dismiss(): void;
     config(opts: ToastConfig): void;
 }