@manohub/app-kit 0.1.0

package/dist/entry/create-sub-app.d.ts

@@ -0,0 +1,45 @@
+import { QueryClient } from '@tanstack/vue-query';
+import { type App as VueApp, type Component, type Plugin } from 'vue';
+import { type RouteRecordRaw } from 'vue-router';
+export interface CreateSubAppOptions {
+    rootComponent: Component;
+    routes: RouteRecordRaw[];
+    i18n?: {
+        resources: Record<string, Record<string, unknown>>;
+        fallbackLng?: string;
+    };
+    /** 缺省由 createQueryClient() 提供；带全局错误缓存/自定义 retry 的应用自建后注入 */
+    queryClient?: QueryClient;
+    /** 额外插件（如 ContextMenu） */
+    extraPlugins?: Plugin[];
+    /** 额外样式（如 highlight.js 主题），mount 前动态加载 */
+    extraStyles?: () => Promise<unknown>;
+    /** 首帧路由重置到根路径（默认 true，刷新时不恢复 micro-app 传入的路由状态） */
+    resetToRootOnBoot?: boolean;
+    /** 允许的初始路径别名（宿主兼容前缀），命中不重置 */
+    rootPathAliases?: string[];
+    onReady?: (app: VueApp) => void;
+}
+/**
+ * 统一子应用入口工厂，替代各 app 手写的 main.ts 样板。
+ *
+ * 固定流程（顺序即契约）：
+ * createApp（外层自动包裹 .app-container）→ pinia → Farris → i18n → VueQuery
+ *   → router → mount(__MICRO_APP_CONTAINER__ || '#app') → 初始守卫 → window 挂载
+ *
+ * `.app-container` 包裹保证 reset / tokens / farris-bridge 的作用域在所有 app 一致。
+ *
+ * farris 插件（app.use(Farris)）注册在本工厂内部 —— farris 只允许存在于 app-kit，
+ * 应用侧不得 import '@farris/ui-vue'（oxlint 护栏）。
+ *
+ * @example
+ * export const { mount, unmount } = createSubApp({
+ *   rootComponent: Root,
+ *   routes,
+ *   i18n: { resources: { en: { translation: en }, zh: { translation: zh } } },
+ * })
+ */
+export declare function createSubApp(options: CreateSubAppOptions): {
+    mount: () => void;
+    unmount: () => void;
+};

package/dist/entry/create-sub-app.js

@@ -0,0 +1,110 @@
+import Farris from "@farris/ui-vue";
+import { VueQueryPlugin } from "@tanstack/vue-query";
+import { createPinia } from "pinia";
+import { defineComponent, ref, provide, h, createApp } from "vue";
+import { createRouter, createWebHistory } from "vue-router";
+import { installInitialGuard } from "./initial-guard.js";
+import { createQueryClient } from "./create-query-client.js";
+import { setupI18n } from "../providers/setup-i18n.js";
+import { setCurrentApp } from "../services/app-context.js";
+function createSubApp(options) {
+  const {
+    rootComponent,
+    routes,
+    i18n,
+    queryClient,
+    extraPlugins = [],
+    extraStyles,
+    resetToRootOnBoot = true,
+    rootPathAliases = [],
+    onReady
+  } = options;
+  let app = null;
+  let router = null;
+  let pinia = null;
+  let stopInitialGuard = null;
+  let removeGlobalDataListener = null;
+  let i18nInstance = null;
+  const mount = () => {
+    router = createRouter({ history: createWebHistory(), routes });
+    const ContainerRoot = defineComponent({
+      name: "AppKitRoot",
+      setup() {
+        const subAppContext = ref({});
+        provide("subAppContext", subAppContext);
+        return () => h("div", { class: "app-container" }, [h(rootComponent)]);
+      }
+    });
+    app = createApp(ContainerRoot);
+    pinia = createPinia();
+    app.use(pinia);
+    app.use(Farris);
+    if (i18n) {
+      i18nInstance = setupI18n(app, i18n);
+    }
+    app.use(VueQueryPlugin, { queryClient: queryClient ?? createQueryClient() });
+    for (const plugin of extraPlugins) {
+      app.use(plugin);
+    }
+    app.use(router);
+    const container = window.__MICRO_APP_CONTAINER__ || "#app";
+    app.mount(container);
+    const mountTarget = typeof container === "string" ? document.querySelector(container) : container;
+    setCurrentApp(app, mountTarget?.querySelector(".app-container") ?? null);
+    if (window.__MICRO_APP_ENVIRONMENT__) {
+      const microAppWindow = window;
+      const onGlobalData = (data) => {
+        if (data.language && i18nInstance) {
+          const normalizedLang = String(data.language).split("-")[0] === "zh" ? "zh" : "en";
+          if (normalizedLang !== i18nInstance.language) {
+            void i18nInstance.changeLanguage(normalizedLang);
+          }
+        }
+      };
+      microAppWindow.microApp.addGlobalDataListener(onGlobalData, true);
+      removeGlobalDataListener = () => microAppWindow.microApp.removeGlobalDataListener(onGlobalData);
+    }
+    if (resetToRootOnBoot && router) {
+      stopInitialGuard = installInitialGuard(router, rootPathAliases);
+    }
+    if (extraStyles) {
+      void extraStyles();
+    }
+    onReady?.(app);
+  };
+  const unmount = () => {
+    if (stopInitialGuard) {
+      stopInitialGuard();
+      stopInitialGuard = null;
+    }
+    if (removeGlobalDataListener) {
+      removeGlobalDataListener();
+      removeGlobalDataListener = null;
+    }
+    if (app) {
+      app.unmount();
+      app = null;
+    }
+    setCurrentApp(null);
+    router = null;
+    pinia = null;
+  };
+  exposeToHost(mount, unmount);
+  if (!window.__MICRO_APP_ENVIRONMENT__) {
+    mount();
+  }
+  return { mount, unmount };
+}
+function exposeToHost(mount, unmount) {
+  if (typeof window === "undefined") return;
+  const w = window;
+  w.mount = mount;
+  w.unmount = unmount;
+  w.__MICRO_APP__ = true;
+  w.microApp = w.microApp ?? {};
+  w.microApp.mount = mount;
+  w.microApp.unmount = unmount;
+}
+export {
+  createSubApp
+};

package/dist/entry/index.d.ts

@@ -0,0 +1,4 @@
+export { createSubApp, type CreateSubAppOptions } from './create-sub-app';
+export { installInitialGuard } from './initial-guard';
+export { createQueryClient } from './create-query-client';
+export { setupI18n, i18n, type SetupI18nOptions } from '../providers/setup-i18n';

package/dist/entry/index.js

@@ -0,0 +1,12 @@
+import { createSubApp } from "./create-sub-app.js";
+import { installInitialGuard } from "./initial-guard.js";
+import { createQueryClient } from "./create-query-client.js";
+import { setupI18n } from "../providers/setup-i18n.js";
+import { default as default2 } from "i18next";
+export {
+  createQueryClient,
+  createSubApp,
+  default2 as i18n,
+  installInitialGuard,
+  setupI18n
+};

package/dist/entry/initial-guard.d.ts

@@ -0,0 +1,12 @@
+import type { Router } from 'vue-router';
+/**
+ * 「首次导航重置」守卫：刷新浏览器时，micro-app 会从 URL 参数恢复子应用路由状态，
+ * 该守卫在首次非根导航发生前拦截并重定向到根路径，确保每次打开子应用都是初始状态。
+ * 导航在产生历史记录前即被取消，避免 afterEach 事后 replace 在快速连续导航时残留多余历史。
+ * 只执行一次，执行后立即移除自身，不影响后续正常导航。
+ *
+ * @param rootPathAliases 额外允许的初始路径（宿主兼容前缀，如 ['/aihub-skill']）；
+ *                        命中别名的首次导航不重置
+ * @returns 清理函数：应用卸载时调用，销毁守卫，防止内存泄漏
+ */
+export declare function installInitialGuard(router: Router, rootPathAliases?: string[]): () => void;

package/dist/entry/initial-guard.js

@@ -0,0 +1,23 @@
+function installInitialGuard(router, rootPathAliases = []) {
+  const allowed = /* @__PURE__ */ new Set(["/", ...rootPathAliases]);
+  let hasAppliedInitialReset = false;
+  let stop = null;
+  stop = router.beforeEach((to) => {
+    if (hasAppliedInitialReset) return true;
+    hasAppliedInitialReset = true;
+    stop?.();
+    if (!allowed.has(to.path)) {
+      return { path: "/", query: {} };
+    }
+    return true;
+  });
+  return () => {
+    if (stop) {
+      stop();
+      stop = null;
+    }
+  };
+}
+export {
+  installInitialGuard
+};

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @manohub/app-kit 对外导出白名单。
+ *
+ * 禁止 export *；禁止从 '@farris/ui-vue' re-export 任何东西（类型也不行）——
+ * farris 必须被挡在边界内（方案 §5.4 / 护栏 12）。
+ */
+export { AppShell, type AppShellCompound, type AppShellHeaderProps, type AppShellBodyProps, type AppShellSplitProps } from './shell/AppShell';
+export { AppButton, type AppButtonTone, type AppButtonShape, type AppControlSize } from './atoms/app-button';
+export { AppIconButton } from './atoms/app-icon-button';
+export { AppInput } from './atoms/app-input';
+export { AppSwitch } from './atoms/app-switch';
+export { AppCheckbox } from './atoms/app-checkbox';
+export { AppRadioCard, type AppRadioCardItem, type AppRadioCardValue } from './atoms/app-radio-card';
+export { AppNotice, type AppNoticeTone } from './atoms/app-notice';
+export { AppQueryState, type AppQueryStateKind, type AppQueryStateProps } from './atoms/app-query-state';
+export { AppStateIllustrationEmpty, AppStateIllustrationError } from './atoms/state-illustration';
+export { AppSelect, type AppSelectOption, type AppSelectValue } from './atoms/app-select';
+export { AppSearchBox } from './atoms/app-search-box';
+export { AppTextarea } from './atoms/app-textarea';
+export { AppTooltip, type AppTooltipPlacement, type AppTooltipTrigger } from './atoms/app-tooltip';
+export { AppPanel, type AppPanelProps, type AppPanelPadding, type AppPanelCompound, } from './components/app-panel';
+export { AppTree, type AppTreeNode } from './components/app-tree';
+export { AppTable, type AppTableColumn, type AppTableProps, type AppTableSelection } from './components/app-table';
+export { AppPagination } from './components/app-pagination';
+export { AppBadge, type AppBadgeTone, type AppBadgeShape, type AppBadgeSize, type AppBadgeDot } from './components/app-badge';
+export { AppDialog } from './components/app-dialog';
+export { AppTabs, type AppTabItem } from './components/app-tabs';
+export { AppForm, type AppFormProps, type AppFormItemProps, type AppFormLabelAlign, type AppFormCompound, } from './components/app-form';
+export { AppSection, type AppSectionProps } from './components/app-section';
+export { AppLayout, type AppLayoutGap, type AppLayoutAlign, type AppLayoutJustify, type AppLayoutColumns, type AppLayoutSpan, } from './atoms/app-layout';
+export { AppSteps, type AppStepItem } from './components/app-steps';
+export { AppFilter, appFilterSelect, appFilterInput, type AppFilterField, type AppFilterValues, type AppFilterEventMeta, } from './components/app-filter';
+export { useClientPagination, type UseClientPagination, type UseClientPaginationOptions, } from './composables/use-client-pagination';
+export { notify, type NotifyOverride, type NotifyPosition } from './services/notify';
+export { messageBox, type AppMessageBoxShowOptions, type AppMessageBoxConfirmOptions } from './services/message-box';
+export { loading } from './services/loading';
+export { modalService, type AppModalOptions, type AppModalButton, type AppModalHandle } from './services/modal';

package/dist/index.js

@@ -0,0 +1,67 @@
+import { AppShell } from "./shell/AppShell.js";
+import { AppButton } from "./atoms/app-button.js";
+import { AppIconButton } from "./atoms/app-icon-button.js";
+import { AppInput } from "./atoms/app-input.js";
+import { AppSwitch } from "./atoms/app-switch.js";
+import { AppCheckbox } from "./atoms/app-checkbox.js";
+import { AppRadioCard } from "./atoms/app-radio-card.js";
+import { AppNotice } from "./atoms/app-notice.js";
+import { AppQueryState } from "./atoms/app-query-state.js";
+import { AppStateIllustrationEmpty, AppStateIllustrationError } from "./atoms/state-illustration.js";
+import { AppSelect } from "./atoms/app-select.js";
+import { AppSearchBox } from "./atoms/app-search-box.js";
+import { AppTextarea } from "./atoms/app-textarea.js";
+import { AppTooltip } from "./atoms/app-tooltip.js";
+import { AppPanel } from "./components/app-panel.js";
+import { AppTree } from "./components/app-tree.js";
+import { AppTable } from "./components/app-table.js";
+import { AppPagination } from "./components/app-pagination.js";
+import { AppBadge } from "./components/app-badge.js";
+import { AppDialog } from "./components/app-dialog.js";
+import { AppTabs } from "./components/app-tabs.js";
+import { AppForm } from "./components/app-form.js";
+import { AppSection } from "./components/app-section.js";
+import { AppLayout } from "./atoms/app-layout.js";
+import { AppSteps } from "./components/app-steps.js";
+import { AppFilter, appFilterInput, appFilterSelect } from "./components/app-filter.js";
+import { useClientPagination } from "./composables/use-client-pagination.js";
+import { notify } from "./services/notify.js";
+import { messageBox } from "./services/message-box.js";
+import { loading } from "./services/loading.js";
+import { modalService } from "./services/modal.js";
+export {
+  AppBadge,
+  AppButton,
+  AppCheckbox,
+  AppDialog,
+  AppFilter,
+  AppForm,
+  AppIconButton,
+  AppInput,
+  AppLayout,
+  AppNotice,
+  AppPagination,
+  AppPanel,
+  AppQueryState,
+  AppRadioCard,
+  AppSearchBox,
+  AppSection,
+  AppSelect,
+  AppShell,
+  AppStateIllustrationEmpty,
+  AppStateIllustrationError,
+  AppSteps,
+  AppSwitch,
+  AppTable,
+  AppTabs,
+  AppTextarea,
+  AppTooltip,
+  AppTree,
+  appFilterInput,
+  appFilterSelect,
+  loading,
+  messageBox,
+  modalService,
+  notify,
+  useClientPagination
+};

package/dist/providers/setup-i18n.d.ts

@@ -0,0 +1,19 @@
+import i18next from 'i18next';
+import type { App } from 'vue';
+export interface SetupI18nOptions {
+    /** i18next resources 形态：{ en: { translation: {...} }, zh: { translation: {...} } } */
+    resources: Record<string, Record<string, unknown>>;
+    fallbackLng?: string;
+}
+/**
+ * i18n 初始化（每子应用一个 i18next 单例）。
+ *
+ * 各子应用以 IIFE 独立 bundle 加载，包内各持一份 i18next 模块实例，
+ * 单例模式天然按应用隔离。消费方（如 api-error 处理）可从本模块直接取 i18n 单例。
+ *
+ * ⚠️ micro-app 宿主语言切换监听不在本函数内，由 createSubApp 统一注册，
+ * 以保证「监听器在应用初始化前注册」的时序约束。
+ */
+export declare function setupI18n(app: App, options: SetupI18nOptions): import("i18next").i18n;
+/** i18n 单例出口：供组件树外取 t()/exists()/changeLanguage()（如 api-error 处理器） */
+export { i18next as i18n };

package/dist/providers/setup-i18n.js

@@ -0,0 +1,24 @@
+import i18next from "i18next";
+import { default as default2 } from "i18next";
+import LanguageDetector from "i18next-browser-languagedetector";
+import i18nextVue from "i18next-vue";
+function setupI18n(app, options) {
+  const { resources, fallbackLng = "en" } = options;
+  if (!i18next.isInitialized) {
+    i18next.use(LanguageDetector).init({
+      resources,
+      fallbackLng,
+      interpolation: { escapeValue: false },
+      detection: {
+        order: ["localStorage", "navigator"],
+        caches: ["localStorage"]
+      }
+    });
+  }
+  app.use(i18nextVue, { i18next });
+  return i18next;
+}
+export {
+  default2 as i18n,
+  setupI18n
+};

package/dist/services/app-container.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 子应用容器（`.app-container`）解析 —— `createSubApp` 统一包裹的作用域锚点。
+ *
+ * 令牌（`--ui-*`）、farris 主题桥接（`--f-theme-*`）与 reset 都挂在它上面；
+ * 微前端下应用侧 CSS 还会被 scopecss 前缀限定在容器内。
+ *
+ * 因此**任何 Teleport 出组件树的内容都必须落在这里**：
+ * 落到 `body` 上的节点既拿不到令牌（`var(--ui-*)` 全部失效 ⇒ 组件「样式全丢」），
+ * 也匹配不到被前缀化的应用侧样式（farris 弹窗的默认 host 就是 `"body"`，故调用方需要改写）。
+ *
+ * 取值优先级：**当前应用挂载时记录的容器**（精确，门户里多应用并存时不会串到别的应用）
+ * → 文档里第一个 `.app-container`（未经 createSubApp 的裸挂载场景）
+ * → `document.body`（兜底，行为与改写前一致，不会更差）。
+ */
+export declare function resolveAppContainer(): Element;

package/dist/services/app-container.js

@@ -0,0 +1,7 @@
+import { getCurrentAppContainer } from "./app-context.js";
+function resolveAppContainer() {
+  return getCurrentAppContainer() ?? document.querySelector(".app-container") ?? document.body;
+}
+export {
+  resolveAppContainer
+};

package/dist/services/app-context.d.ts

@@ -0,0 +1,4 @@
+import type { App } from 'vue';
+export declare function setCurrentApp(app: App | null, container?: Element | null): void;
+export declare function getCurrentApp(): App | null;
+export declare function getCurrentAppContainer(): Element | null;

package/dist/services/app-context.js

@@ -0,0 +1,17 @@
+let currentApp = null;
+let currentContainer = null;
+function setCurrentApp(app, container = null) {
+  currentApp = app;
+  currentContainer = container;
+}
+function getCurrentApp() {
+  return currentApp;
+}
+function getCurrentAppContainer() {
+  return currentContainer;
+}
+export {
+  getCurrentApp,
+  getCurrentAppContainer,
+  setCurrentApp
+};

package/dist/services/index.d.ts

@@ -0,0 +1,5 @@
+export { notify } from './notify';
+export { messageBox, type AppMessageBoxShowOptions, type AppMessageBoxConfirmOptions } from './message-box';
+export { loading } from './loading';
+export { modalService, type AppModalOptions, type AppModalButton, type AppModalHandle } from './modal';
+export { resolveAppContainer } from './app-container';

package/dist/services/loading.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 全局加载遮罩（收敛 FLoadingService 的 show/hide 成对 API，防漏关）。
+ *
+ * 推荐用 withLoading 自动配对；手动场景 open() 返回带 close 的句柄。
+ * 单例语义：重复 open 覆盖前一个（与现状各 app 行为一致，全局同时只有一个遮罩）。
+ *
+ * @example
+ * await loading.withLoading(() => mutation.mutateAsync(request), '提交中…')
+ * const mask = loading.open('导出中…'); try { ... } finally { mask.close() }
+ */
+export declare const loading: {
+    open(message?: string): {
+        close: () => void;
+    };
+    withLoading<T>(fn: () => Promise<T>, message?: string): Promise<T>;
+};

package/dist/services/loading.js

@@ -0,0 +1,27 @@
+import { FLoadingService } from "@farris/ui-vue";
+let current = null;
+function show(message) {
+  current = FLoadingService.show({ message });
+  return current;
+}
+function close() {
+  current?.value?.close();
+  current = null;
+}
+const loading = {
+  open(message) {
+    show(message);
+    return { close };
+  },
+  async withLoading(fn, message) {
+    show(message);
+    try {
+      return await fn();
+    } finally {
+      close();
+    }
+  }
+};
+export {
+  loading
+};

package/dist/services/message-box.d.ts

@@ -0,0 +1,84 @@
+export interface AppMessageBoxButton {
+    /** 按钮标识（消费方无需再引用，仅用于内部区分） */
+    name: string;
+    text: string;
+    /** 视觉角色；缺省为浅色普通按钮 */
+    variant?: 'primary' | 'default' | 'danger';
+    /** 点击处理；返回 false 阻止关闭（farris 契约） */
+    handle?: () => boolean | void | Promise<boolean | void>;
+}
+export interface AppMessageBoxShowOptions {
+    type?: 'info' | 'success' | 'warning' | 'error' | 'question';
+    /** 主文案（对话框第一行）。**传文本**；多行用 `\n`（换行在弹窗里生效） */
+    title: string;
+    /**
+     * 补充说明（主文案下方的灰色小字）。**传文本**，多行用 `\n`（服务内部先转义再交底层渲染，
+     * 所以文本里的 `<` `&` 不会被当标签解析）。
+     *
+     * HTML 只留给**静态长文说明**（「值映射说明」这种要分段/强调的须知）：这时置 `richText: true`，
+     * 内容必须来自静态语言包，**禁止拼接用户输入**。提示/确认/报错一律用文本，不要为了分段拼 `<div>`。
+     */
+    detail?: string;
+    /** `detail` 是否按 HTML 渲染；**缺省 false**（按文本：内部转义，`\n` 换行） */
+    richText?: boolean;
+    /** 弹窗宽度（px）；不传走底层默认宽度。长正文建议显式给宽（如 720）避免挤成窄条 */
+    width?: number;
+    /** 「确定」按钮文案；不传走底层默认（「确定」）。多语言场景应由调用方传入当前语言文案 */
+    okButtonText?: string;
+    /** 自定义按钮组（farris 多按钮弹窗）；不传即单「确定」按钮 */
+    buttons?: AppMessageBoxButton[];
+}
+export interface AppMessageBoxConfirmOptions {
+    /** 主文案：确认主题（如「确认删除」）；整句问句也可以放这里 */
+    title: string;
+    /** 补充说明：影响/后果这类补充（**文本**，可多行） */
+    description?: string;
+    /** 「确定」按钮文案；不传走底层默认（「确定」） */
+    confirmText?: string;
+    /** 「取消」按钮文案；不传走底层默认（「取消」） */
+    cancelText?: string;
+}
+/**
+ * 消息框（收敛 FMessageBoxService 的静态回调式 API）。
+ *
+ * ## 文案口径：**用文本传，尽量不用 HTML**
+ *
+ * farris 的字段落位：`title` → `.toast-msg-title`（第一行主文案）、`detail` → `.toast-msg-detail`
+ * （主文案下方的灰色小字）。两者底层都是 `innerHTML`，但**本服务默认把传入内容当文本**：
+ * 内部先转义、再交给底层（`\n` 已放开换行，见 farris-bridge.css 的 `white-space: pre-line`）。
+ * 于是"换行"用 `\n`、"嵌业务值"直接拼字符串即可 —— 不再需要调用方自己 `escapeHtml` 或拼 `<div>`；
+ * 拼 HTML 的老写法既容易漏转义（编码里的尖括号会被当标签），又把文案与排版耦合在代码里。
+ * 唯一例外是**静态长文说明**（如值映射说明的四段须知）需要分段/强调：显式 `richText: true`，
+ * 内容必须来自静态语言包，**禁止拼接用户输入**。
+ *
+ * - `confirm` 把确认语义 Promise 化（`resolve(true/false)`）
+ * - `show` 支持 `buttons` 自定义按钮组（如「应用 / 丢弃 / 取消」三按钮确认），
+ *   按钮角色在内部翻译为 farris 类名，消费方不写 `btn btn-*`
+ *
+ * @example
+ * const ok = await messageBox.confirm({ title: '删除分类', description: `确定删除「${name}」？` })
+ * if (ok) { ... }
+ * messageBox.show({ type: 'error', title: '删除失败', detail: error.message })
+ *
+ * @example 三按钮确认
+ * messageBox.show({ type: 'question', title: '有未应用的更改', detail: '是否先应用？',
+ *   buttons: [
+ *     { name: 'save', text: '立即应用', variant: 'primary', handle: () => finish('save') },
+ *     { name: 'discard', text: '丢弃', handle: () => finish('discard') },
+ *     { name: 'cancel', text: '取消', handle: () => finish('cancel') },
+ *   ] })
+ */
+export declare const messageBox: {
+    show(options: AppMessageBoxShowOptions): void;
+    /**
+     * 确认框：`resolve(true)` = 点确定，`resolve(false)` = 点取消。
+     *
+     * 走 `show`（而不是 `question`）：`question` 把按钮文案写死成「确定 / 取消」，
+     * 而确认框经常要给具体动作名（「继续编辑 / 确定退出」这类）。
+     * 字段落位与 `show` 一致：`title` → 主文案、`description` → 补充小字，都是**文本**（`\n` 生效）。
+     *
+     * 注意：右上角 ✕ / Esc 关闭只关窗、不触发回调（farris 行为，`show` / `question` 都一样），
+     * 此时 Promise 不落定 —— 调用方按"未确认"处理即可（`await` 之后什么都不做）。要拿到 false 得点「取消」。
+     */
+    confirm(options: AppMessageBoxConfirmOptions): Promise<boolean>;
+};

package/dist/services/message-box.js

@@ -0,0 +1,65 @@
+import { FMessageBoxService } from "@farris/ui-vue";
+function escapeHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function toRenderable(text, richText) {
+  const value = text ?? "";
+  return richText ? value : escapeHtml(value);
+}
+const BUTTON_CLASS = {
+  primary: "btn btn-primary",
+  default: "btn btn-secondary",
+  danger: "btn btn-danger"
+};
+const messageBox = {
+  show(options) {
+    FMessageBoxService.show({
+      type: options.type ?? "info",
+      title: toRenderable(options.title),
+      detail: toRenderable(options.detail, options.richText),
+      /*
+       * `show` 是**信息型**弹窗（无确认语义），固定单按钮。
+       * 底层 `show` 默认带「取消」（farris 组件的 showCancelButton 默认为 true），不显式关掉会多出一颗
+       * 无意义的取消按钮；需要确认语义请用 `confirm`。
+        */
+      showCancelButton: false,
+      ...options.width ? { width: options.width } : {},
+      ...options.okButtonText ? { okButtonText: options.okButtonText } : {},
+      ...options.buttons ? {
+        buttons: options.buttons.map((button) => ({
+          name: button.name,
+          text: button.text,
+          class: BUTTON_CLASS[button.variant ?? "default"],
+          handle: button.handle
+        }))
+      } : {}
+    });
+  },
+  /**
+   * 确认框：`resolve(true)` = 点确定，`resolve(false)` = 点取消。
+   *
+   * 走 `show`（而不是 `question`）：`question` 把按钮文案写死成「确定 / 取消」，
+   * 而确认框经常要给具体动作名（「继续编辑 / 确定退出」这类）。
+   * 字段落位与 `show` 一致：`title` → 主文案、`description` → 补充小字，都是**文本**（`\n` 生效）。
+   *
+   * 注意：右上角 ✕ / Esc 关闭只关窗、不触发回调（farris 行为，`show` / `question` 都一样），
+   * 此时 Promise 不落定 —— 调用方按"未确认"处理即可（`await` 之后什么都不做）。要拿到 false 得点「取消」。
+   */
+  confirm(options) {
+    return new Promise((resolve) => {
+      FMessageBoxService.show({
+        type: "question",
+        title: toRenderable(options.title),
+        detail: toRenderable(options.description),
+        showCancelButton: true,
+        ...options.confirmText ? { okButtonText: options.confirmText } : {},
+        ...options.cancelText ? { cancelButtonText: options.cancelText } : {},
+        acceptCallback: () => resolve(true),
+        rejectCallback: () => resolve(false)
+      });
+    });
+  }
+};
+export {
+  messageBox
+};