@manohub/kit 0.6.0

package/README.md

@@ -0,0 +1,158 @@
+# @manohub/kit
+
+AIHub 子应用**入口编排层**：`createSubApp` 统一挂载、i18n 单实例，
+外加随包分发的接入契约（`CONTRACT.md`：五层闭集条款 + §7 自检清单）与三个 AI 技能包（`skills/`）。
+
+**组件与命令式服务不在本包** —— 它们来自 [`@manohub/ui`](https://www.npmjs.com/package/@manohub/ui)；
+**全局令牌（值）不在本包** —— 它来自 [`@manohub/theme`](https://www.npmjs.com/package/@manohub/theme)；
+**本包也不发布任何样式** —— 上面两行由消费方直接引。几个包并列安装。
+
+> **0.6.0 是破坏性变更**（上一个已发布版本是 `@manohub/app-kit@0.4.3`）：本包不再提供任何组件
+> （`App*` 前缀名与 `.ak-*` 类名全部退场、farris 依赖移除）、**主题层独立为 `@manohub/theme`**
+> （容器锚改名 `data-manohub-ui`）、**本包内的样式全部删除**（`reset.css` 与 `.app-markdown`
+> 富文本预设不再提供）、**消费侧机器规则整批下线**（原 `kit lint` 三条护栏不再发布，
+> 合规改为「契约条款 + §7 自检清单」）。
+> 这些是**同一次重构**，一次性做完 —— 迁移对照与步骤见 `CONTRACT.md` §12。
+
+## 新项目接入（快速开始）
+
+### 1. 安装
+
+```bash
+pnpm add @manohub/kit @manohub/ui @manohub/theme
+```
+
+peer（由应用提供，缺一个都装不上）：
+
+```bash
+pnpm add vue vue-router pinia vue-i18n @tanstack/vue-query
+```
+
+`@manohub/ui` 自带图标包依赖（`@manohub/icon`），不必单独声明。
+
+### 2. 样式：两行 + 应用自己一行（顺序即契约）
+
+**本包不发布任何样式**：设计令牌（值）在 `@manohub/theme`、组件面（类 + 组件令牌基础值）在
+`@manohub/ui`，两行由消费方直接引；本包不再提供 reset、富文本预设与样式汇总入口。
+
+```css
+@import "@manohub/theme/default.css";   /* ① 令牌（值）—— 换主题只换这一行 */
+@import "@manohub/ui/styles.css";   /* ② 组件面（类 + 组件令牌基础值） */
+@import "./app.css";                    /* ③ 应用自身（只写布局） */
+```
+
+**顺序不可换**：先值（令牌）后面（组件面）—— 反过来的话组件面里的 `var(--ui-*)` 全是空值。
+
+改用非兜底主题：把 ① 换成对应主题入口 + 给容器属性 ——
+
+```css
+@import "@manohub/theme/farris.css";  /* 替换 ① 那一行 */
+```
+
+```ts
+createSubApp({ /* … */ theme: 'farris' })    // 写到容器的 data-theme 上
+```
+
+主题套锚在容器属性上（`default` 不带主题属性、其余套锚 `[data-manohub-ui][data-theme='<名>']`），
+所以换皮不动类名、不动组件代码、不重打包。
+
+### 3. 入口：统一走 createSubApp
+
+```ts
+// src/main.ts
+import { createSubApp } from '@manohub/kit/entry'
+import Root from './root'
+import { routes } from './router'
+
+export const { mount, unmount } = createSubApp({
+  rootComponent: Root,
+  routes,
+  i18n: { messages: { zh, en } }, // vue-i18n 形态：{ zh: {...}, en: {...} }，无 translation 包装层
+})
+```
+
+它替你做完：`div.app-container` 包裹与 `data-manohub-ui` 锚点、pinia / vue-router / vue-query 装配、
+宿主挂载协议（`window.mount/unmount` + `microApp.mount/unmount`）、宿主语言同步、首帧路由重置。
+
+`data-manohub-ui` 是**跨包唯一的作用域锚点**（主题令牌、组件令牌、微前端 scopecss 都锚在它上面，
+组件库服务层也按它解析宿主）—— 别改名；若自建容器（不走 `createSubApp`）必须自己带上。
+类名 `.app-container` 只是本包内部命名（调试自查用），不是契约。
+
+### 4. 第一个页面用模板 A
+
+```tsx
+import { Button, Input, Page, Panel, Table } from '@manohub/ui'
+
+export default function SkillList() {
+  return (
+    <Page>
+      <Page.Header title="技能列表" extra={<Input placeholder="搜索" />} />
+      <Page.Body mode="plain">
+        <Panel title="技能列表" actions={<Button variant="primary">新建</Button>}>
+          <Table data={rows} columns={columns} />
+          <Panel.Footer>分页放这里</Panel.Footer>
+        </Panel>
+      </Page.Body>
+    </Page>
+  )
+}
+```
+
+三种页面模板、四种操作位、两级滚动归属、分页归属 —— 见 `CONTRACT.md` §5（L2 结构）。
+
+### 5. 自检（0.6.0 起没有自动扫描）
+
+本包**不再发布消费侧机器规则**。合规靠契约条款 + 自检清单在写作与评审时把关：
+
+1. 写代码前按契约 §0 权威源表去取值 / 查件名 / 查词表（不要抄一份会过期的副本）；
+2. 收工前人工过 `CONTRACT.md` §7 自检清单（24 问，五层各一组）；
+3. 类型与构建照常跑：
+
+```bash
+pnpm exec vue-tsc --noEmit
+pnpm build
+```
+
+类名命名空间表放本仓 `docs/kit-namespaces.md`（per-app 文件，格式见技能包的
+`kit-migrate/references/migration-playbook.md`）—— 原 `appkit-guardrails.config.json` 不再被读取。
+
+### 6. 技能包落盘（AI 代理用）
+
+```bash
+pnpm exec kit install            # 把三个技能落到本工程的技能目录
+pnpm exec kit install --dry-run  # 先看会写什么
+```
+
+### 7. 验收
+
+- 应用能挂载（`window.mount()` / micro-app 容器）；
+- 类型检查 0 错、构建成功；
+- 命令式提示落回应用容器（`toast('success', 'ok')` 后检查 DOM 里 `[data-manohub-ui]` 内有 `.mh-toast`）；
+- `CONTRACT.md` §7 自检清单逐条过完。
+
+## 分发形态
+
+预编译产物：`exports` 指向 `dist`。公开入口（改名即破坏性变更）：
+
+| 入口 | 内容 |
+| --- | --- |
+| `@manohub/kit` | `useClientPagination`、`resolveAppContainer` / `resolveAppContainerSelector` |
+| `@manohub/kit/entry` | `createSubApp`、`installInitialGuard`、`createQueryClient`、`applyLocale` / `getLocale` / `i18n` / `setupI18n` |
+| `@manohub/kit/CONTRACT.md` | 接入契约（权威规范：五层闭集条款 + §7 自检清单） |
+
+**本包没有任何样式出口**（0.6.0 起）：`./styles.css`、`./reset.css`、`./markdown.css` 都已删除。
+样式请引 `@manohub/theme` 与 `@manohub/ui` 的公开入口（见上面 §2）。
+
+## 技能包（AI 代理用，随包分发）
+
+| 技能 | 什么时候用 |
+| --- | --- |
+| `kit` | 不确定该用哪个子技能、问骨架层总体规范、要接入步骤与升级口径 |
+| `kit-dev` | 写/改页面：选模板、选组件与 prop、样式纪律、收工前自检 |
+| `kit-migrate` | 存量应用改造：按契约分层盘点、划批次、逐文件替换、逐层收口 |
+
+## 来源
+
+包内实现由 `gsp-cloud-ds/dip/ibp/aihub/aihub-frontend` 的 `kit` 分支首提交导入
+（commit `315b60f`），再按「组件与服务独立成 `@manohub/ui`、本包只留入口编排」拆分而成。
+迁移来源 commit 只作留档，不要据此回改本包实现。

package/bin/kit.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * `kit` —— 接入方（消费方）命令行入口。
+ *
+ * 存在的理由：接入方不该被要求记住 `node node_modules/@manohub/kit/skills/install.mjs`
+ * 这类路径。本命令是**薄壳**：把子命令映射到包内既有脚本，透传参数与退出码。
+ *
+ * 用法（在**应用包根**执行）：
+ *   pnpm exec kit install             # 把随包分发的 AI 技能落到本工程
+ *   pnpm exec kit install --also-claude
+ *   pnpm exec kit install --target .x/skills
+ *   pnpm exec kit install --dry-run
+ *   pnpm exec kit help
+ *
+ * npm 消费方把 `pnpm exec` 换成 `npx`（两者都解析本地 node_modules/.bin）。
+ * package.json 的 scripts 里可以省略前缀（npm/pnpm 会把 .bin 加进 PATH）：
+ *   "skills:sync": "kit install"
+ *
+ * 0.6.0 起 `lint` / `lint:style` / `lint:component` / `lint:structure` 四个子命令**已下线**
+ * （消费侧机器规则整批退场，合规改为「CONTRACT.md 条款 + §7 自检清单」）。
+ * 旧脚本若还写着 `kit lint`，会得到「未知命令」并附帮助 —— 不是静默通过。
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+// 复用安装器里已测过的「是否被直接执行」判定：pnpm 把包放在 .pnpm 下、消费方引用的是软链，
+// 直接比较 argv[1] 与 import.meta.url 会字面不等 → CLI 静默不执行（同一个坑踩过两次不值得）。
+import { isDirectRun } from '../skills/install.mjs'
+
+/** 包根（本文件在 <pkg>/bin/ 下，发布物里 skills/ 是它的兄弟目录） */
+const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
+
+/** 子命令表：命令名 → 包内脚本与说明（新增子命令只需在这里加一行） */
+export const COMMANDS = {
+  install: {
+    script: 'skills/install.mjs',
+    summary: '把随包分发的三个 AI 技能落到本工程（--also-claude / --target <dir> / --dry-run）',
+  },
+}
+
+/**
+ * 解析命令行：只认 `COMMANDS` 里的子命令，未知子命令**显式报错**
+ * （静默忽略会让人以为命令生效了，而它其实什么都没做）。
+ */
+export function parseCommand(argv = []) {
+  const [first = '', ...rest] = argv
+  if (!first || first === 'help' || first === '--help' || first === '-h') return { kind: 'help' }
+  if (first === '--version' || first === '-v') return { kind: 'version' }
+  const command = COMMANDS[first]
+  if (!command) return { kind: 'unknown', command: first }
+  return { kind: 'run', name: first, script: command.script, args: rest }
+}
+
+export function usage(version = readVersion()) {
+  const lines = [
+    `kit ${version} —— @manohub/kit 命令入口（在应用包根执行；npm 消费方用 npx 代替 pnpm exec）`,
+    '',
+    '用法：',
+    '  pnpm exec kit <命令> [参数]',
+    '',
+    '命令：',
+  ]
+  for (const [name, command] of Object.entries(COMMANDS)) {
+    lines.push(`  ${name.padEnd(16)}${command.summary}`)
+  }
+  lines.push('  help            显示本帮助')
+  lines.push('  --version       显示版本号')
+  lines.push('')
+  lines.push('参数会原样透传给对应脚本（如 `kit install --dry-run`）；退出码同样是脚本的退出码。')
+  return lines.join('\n')
+}
+
+/** 读包自身版本（`kit --version` 用） */
+export function readVersion() {
+  try {
+    return JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8')).version ?? 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}
+
+function main() {
+  const parsed = parseCommand(process.argv.slice(2))
+
+  if (parsed.kind === 'help') {
+    console.log(usage())
+    return
+  }
+  if (parsed.kind === 'version') {
+    console.log(readVersion())
+    return
+  }
+  if (parsed.kind === 'unknown') {
+    console.error(`[kit] 未知命令：${parsed.command}\n\n${usage()}`)
+    process.exitCode = 1
+    return
+  }
+
+  const script = join(PKG_ROOT, parsed.script)
+  if (!existsSync(script)) {
+    console.error(`[kit] 包内缺少脚本 ${parsed.script}（安装不完整？请重新安装 @manohub/kit）`)
+    process.exitCode = 1
+    return
+  }
+
+  // stdio 继承：脚本输出是给人看的（含彩色/实时输出），不要在这里再包一层缓冲
+  const result = spawnSync(process.execPath, [script, ...parsed.args], {
+    cwd: process.cwd(),
+    stdio: 'inherit',
+  })
+  process.exitCode = result.status ?? 1
+}
+
+// 仅在被直接执行时跑；被测试 import 时只取纯函数
+if (isDirectRun(process.argv[1], import.meta.url)) {
+  main()
+}

package/dist/composables/use-client-pagination.d.ts

@@ -0,0 +1,43 @@
+import { type MaybeRefOrGetter, type Ref } from 'vue';
+export interface UseClientPaginationOptions {
+    /** 初始页大小；缺省取 `pageSizeOptions[0]` */
+    pageSize?: number;
+    /** 页大小候选；缺省 `[10, 20, 50]`（与 `Pagination` 的缺省一致） */
+    pageSizeOptions?: number[];
+}
+export interface UseClientPagination<T = unknown> {
+    /** 当前页码（**1 基**，与 `Pagination.modelValue` 同一口径） */
+    page: Ref<number>;
+    pageSize: Ref<number>;
+    /** 总条数（切片前） */
+    total: Ref<number>;
+    /** 总页数（至少 1） */
+    pageCount: Ref<number>;
+    /** 当前页数据（已切片，直接喂给 `Table` 的 `data`） */
+    pageRows: Ref<T[]>;
+    pageSizeOptions: number[];
+    setPage: (page: number) => void;
+    setPageSize: (size: number) => void;
+}
+/**
+ * 客户端分页状态（切片 + 越界回退），与 `Pagination` 同契约（**1 基**页码）。
+ *
+ * **为什么不在 `Table` 内建切片**：`data` 始终是「当前页数据」——
+ * 组件自己切片会把「服务端分页」与「客户端分页」两套口径藏进同一个 prop 里。
+ * 本 composable 把「切片 + 越界回退 + 页大小切换回首页」这三件样板事收起来，
+ * 页面只负责把 `page` / `pageSize` 交给 `Pagination`、把 `pageRows` 交给 `Table.data`。
+ *
+ * **1 基是硬口径**：`Pagination.modelValue`、`Table` 的 `pagination.current` 都是 1 基，
+ * 本 composable 跟着它们；写成 0 基会让每处调用都差 1（那正是迁移里最容易漏的一类缺陷）。
+ *
+ * 越界回退：数据变少（过滤 / 删除）导致当前页超出范围时，自动回退到最后一页，
+ * 避免出现「空白页但分页器显示有数据」。
+ *
+ * @example
+ * const list = useClientPagination(() => filtered.value)
+ * <Table :data="list.pageRows.value" :columns="columns" row-key="id" />
+ * <Pagination v-model="list.page.value" v-model:page-size="list.pageSize.value" :total="list.total.value" />
+ *
+ * @example 服务端分页时不用本 composable：`page` / `pageSize` 交给请求参数，`data` 给当前页结果
+ */
+export declare function useClientPagination<T>(rows: MaybeRefOrGetter<T[]>, options?: UseClientPaginationOptions): UseClientPagination<T>;

package/dist/composables/use-client-pagination.js

@@ -0,0 +1,28 @@
+import { ref, computed, toValue, watch } from "vue";
+function useClientPagination(rows, options = {}) {
+  const pageSizeOptions = options.pageSizeOptions ?? [10, 20, 50];
+  const pageSize = ref(options.pageSize ?? pageSizeOptions[0]);
+  const page = ref(1);
+  const total = computed(() => toValue(rows).length);
+  const pageCount = computed(() => Math.max(1, Math.ceil(total.value / pageSize.value)));
+  watch([total, pageSize], () => {
+    if (page.value > pageCount.value) page.value = pageCount.value;
+    if (page.value < 1) page.value = 1;
+  });
+  const pageRows = computed(() => {
+    const start = (page.value - 1) * pageSize.value;
+    return toValue(rows).slice(start, start + pageSize.value);
+  });
+  const setPage = (next) => {
+    page.value = Math.min(Math.max(1, Math.trunc(next) || 1), pageCount.value);
+  };
+  const setPageSize = (size) => {
+    if (!(size > 0)) return;
+    pageSize.value = size;
+    page.value = 1;
+  };
+  return { page, pageSize, total, pageCount, pageRows, pageSizeOptions, setPage, setPageSize };
+}
+export {
+  useClientPagination
+};

package/dist/entry/create-query-client.d.ts

@@ -0,0 +1,8 @@
+import { QueryClient } from '@tanstack/vue-query';
+/**
+ * 缺省 QueryClient：createSubApp 未显式传入 queryClient 时使用。
+ *
+ * 与各子应用现状 providers.tsx 的公共默认一致（staleTime 30s、不因窗口聚焦重取）；
+ * 带全局错误缓存/自定义 retry 的应用应自建 QueryClient 后经 createSubApp 注入。
+ */
+export declare function createQueryClient(): QueryClient;

package/dist/entry/create-query-client.js

@@ -0,0 +1,14 @@
+import { QueryClient } from "@tanstack/vue-query";
+function createQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 30 * 1e3,
+        refetchOnWindowFocus: false
+      }
+    }
+  });
+}
+export {
+  createQueryClient
+};

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

@@ -0,0 +1,81 @@
+import { QueryClient } from '@tanstack/vue-query';
+import { type App as VueApp, type Component, type Plugin } from 'vue';
+import { type RouterHistory, type RouteRecordRaw } from 'vue-router';
+import { type SetupI18nOptions } from '../providers/setup-i18n';
+/**
+ * 路由历史模式：
+ * - `'history'`（缺省）：正常 history，micro-app 以 baseroute 隔离子应用路由；
+ * - `'hash'`：宿主**不支持深路径 fallback**（刷新深路径 404）、或门户不允许子应用改写地址栏时用；
+ * - 传 `RouterHistory` 实例（如 `createWebHistory('/subapp/x/')`）：自行定制 base 等细节。
+ */
+export type CreateSubAppHistory = 'history' | 'hash' | RouterHistory;
+export interface CreateSubAppOptions {
+    rootComponent: Component;
+    routes: RouteRecordRaw[];
+    /** 路由历史模式（缺省 `'history'`）。宿主是否支持深路径 fallback 见 `CONTRACT.md` §9 第 13 条 */
+    history?: CreateSubAppHistory;
+    /**
+     * vue-i18n 装配选项：`messages` 形态（**不是** i18next 的 `resources`）——见 `CONTRACT.md` §10。
+     *
+     * 实例由本包唯一创建，应用侧不得自行 `createI18n`。传本选项才会注册 i18n 插件并开启
+     * 宿主语言同步；不传则不注册插件（`@manohub/kit/entry` 的 `i18n` 出口是模块级单例，
+     * 与应用是否传本选项无关，组件树外可照常消费）。
+     */
+    i18n?: SetupI18nOptions;
+    /** 缺省由 createQueryClient() 提供；带全局错误缓存/自定义 retry 的应用自建后注入 */
+    queryClient?: QueryClient;
+    /** 额外插件（如 ContextMenu） */
+    extraPlugins?: Plugin[];
+    /** 额外样式（如 highlight.js 主题），mount 前动态加载 */
+    extraStyles?: () => Promise<unknown>;
+    /**
+     * 主题名：写到容器的 `data-theme` 属性上。
+     *
+     * `@manohub/theme` 的主题套锚在容器的 `[data-manohub-ui]` 属性上（`default` 套不带主题属性、
+     * 其余套锚 `[data-manohub-ui][data-theme='<名>']`），故给属性即整包换皮 ——
+     * 不动类名、不动组件代码、不重打包。
+     * 缺省**不写属性**，于是用主题包的兜底套 `default`。
+     */
+    theme?: string;
+    /** 首帧路由重置到根路径（默认 true，刷新时不恢复 micro-app 传入的路由状态） */
+    resetToRootOnBoot?: boolean;
+    /** 允许的初始路径别名（宿主兼容前缀），命中不重置 */
+    rootPathAliases?: string[];
+    onReady?: (app: VueApp) => void;
+}
+/**
+ * 统一子应用入口工厂，替代各 app 手写的 main.ts 样板。
+ *
+ * 固定流程（顺序即契约）：
+ * createApp（外层自动包裹 `.app-container`）→ pinia → i18n → vue-query
+ *   → 额外插件 → router → mount(`__MICRO_APP_CONTAINER__` || `#app`) → 初始守卫 → window 挂载
+ *
+ * ## 它到底管哪四件事
+ *
+ * 1. **作用域容器**：外层包一层 `div.app-container`（`app-` 是本包自己的命名前缀），
+ *    并补两个属性 ——
+ *    `data-manohub-ui`（**跨包唯一作用域锚**，由本工厂**无条件**写：主题令牌、组件令牌、
+ *    以及组件库服务层的宿主解析全锚它一个。取「库品牌属性」而不是本包的
+ *    `app-` 私有类名，是为了让主题包不欠本包一个命名空间；门户里同时挂着多个子应用时，
+ *    服务层据此把命令式浮层落回**本应用**的容器，不串到别人的应用）与
+ *    可选的 `data-theme`（换肤入口）。**本包不 import 组件库/主题包**：几个包并列安装，
+ *    这两个属性就是它们之间唯一的约定。
+ * 2. **i18n**：创建全应用唯一的 vue-i18n 实例并注册（`legacy: false`），随后由宿主语言下发驱动切换。
+ * 3. **路由 / 状态 / 请求**：pinia、vue-router、`@tanstack/vue-query` 三件装配，外加首帧路由重置。
+ * 4. **宿主挂载协议**：`window.mount/unmount` 与 `window.microApp.mount/unmount` 一并暴露。
+ *
+ * 路由历史模式由 `history` 决定：缺省 `'history'`（micro-app 以 baseroute 隔离），
+ * 宿主不支持深路径 fallback 时传 `'hash'`，需要自定义 base 等细节时直接传 `RouterHistory` 实例。
+ *
+ * @example
+ * export const { mount, unmount } = createSubApp({
+ *   rootComponent: Root,
+ *   routes,
+ *   i18n: { messages: { en, zh } },   // vue-i18n 形态：{ en: {...}, zh: {...} }，无 translation 包装层
+ *   theme: 'farris',                  // 可选：写到容器 data-theme 上，整包换肤（缺省用兜底主题）
+ * })
+ */
+export declare function createSubApp(options: CreateSubAppOptions): {
+    mount: () => void;
+    unmount: () => void;
+};

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

@@ -0,0 +1,111 @@
+import { VueQueryPlugin } from "@tanstack/vue-query";
+import { createPinia } from "pinia";
+import { defineComponent, ref, provide, h, createApp } from "vue";
+import { createRouter, createWebHistory, createWebHashHistory } from "vue-router";
+import { installInitialGuard } from "./initial-guard.js";
+import { createQueryClient } from "./create-query-client.js";
+import { setupI18n, applyLocale } from "../providers/setup-i18n.js";
+import { setCurrentApp } from "../services/app-context.js";
+function createSubApp(options) {
+  const {
+    rootComponent,
+    routes,
+    history: historyMode = "history",
+    i18n,
+    queryClient,
+    extraPlugins = [],
+    extraStyles,
+    theme,
+    resetToRootOnBoot = true,
+    rootPathAliases = [],
+    onReady
+  } = options;
+  let app = null;
+  let router = null;
+  let pinia = null;
+  let stopInitialGuard = null;
+  let removeGlobalDataListener = null;
+  const mount = () => {
+    router = createRouter({ history: resolveRouterHistory(historyMode), routes });
+    const ContainerRoot = defineComponent({
+      name: "KitRoot",
+      setup() {
+        const subAppContext = ref({});
+        provide("subAppContext", subAppContext);
+        return () => h("div", { class: "app-container", "data-manohub-ui": "", "data-theme": theme }, [
+          h(rootComponent)
+        ]);
+      }
+    });
+    app = createApp(ContainerRoot);
+    pinia = createPinia();
+    app.use(pinia);
+    if (i18n) 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("[data-manohub-ui]") ?? null);
+    if (window.__MICRO_APP_ENVIRONMENT__) {
+      const microAppWindow = window;
+      const onGlobalData = (data) => {
+        if (data.language && i18n) {
+          applyLocale(data.language, i18n.storageKey);
+        }
+      };
+      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();
+    router = null;
+    pinia = null;
+  };
+  exposeToHost(mount, unmount);
+  if (!window.__MICRO_APP_ENVIRONMENT__) {
+    mount();
+  }
+  return { mount, unmount };
+}
+function resolveRouterHistory(value) {
+  if (value === "history") return createWebHistory();
+  if (value === "hash") return createWebHashHistory();
+  return value;
+}
+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 CreateSubAppHistory, type CreateSubAppOptions } from './create-sub-app';
+export { installInitialGuard } from './initial-guard';
+export { createQueryClient } from './create-query-client';
+export { applyLocale, getLocale, i18n, setupI18n, type AppI18n, type SetupI18nOptions, } from '../providers/setup-i18n';

package/dist/entry/index.js

@@ -0,0 +1,13 @@
+import { createSubApp } from "./create-sub-app.js";
+import { installInitialGuard } from "./initial-guard.js";
+import { createQueryClient } from "./create-query-client.js";
+import { applyLocale, getLocale, i18n, setupI18n } from "../providers/setup-i18n.js";
+export {
+  applyLocale,
+  createQueryClient,
+  createSubApp,
+  getLocale,
+  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,19 @@
+/**
+ * `@manohub/kit` 对外导出白名单。
+ *
+ * 禁止 `export *`；禁止 re-export 任何第三方 UI 库的东西（组件与类型都不行）。
+ *
+ * ## 0.6.0 起本包**不再提供组件**
+ *
+ * 组件与命令式服务一律来自 **`@manohub/ui`**（消费方直引，几个包并列安装）——
+ * 本包不再转出、也不做 `App*` 前缀的别名，避免「同一件两处名字、两套 prop」长期并存。
+ * 回归入口件见子路径 `@manohub/kit/entry`（`createSubApp` 等）。
+ *
+ * 本包剩下的三件事：
+ * 1. **入口编排**（`/entry`）：`div.app-container` 包裹与 `data-manohub-ui` 锚点、
+ *    pinia / vue-query / router 装配、宿主挂载协议、语言探测与切换；
+ * 2. **应用容器记账**（下面的 `resolveAppContainer`）：回答「本应用自己的容器是哪一个」；
+ * 3. **契约分发**：`CONTRACT.md`（五层闭集 + §7 自检清单）与 `skills/` 三个技能包。
+ */
+export { useClientPagination, type UseClientPagination, type UseClientPaginationOptions, } from './composables/use-client-pagination';
+export { resolveAppContainer, resolveAppContainerSelector } from './services/app-container';

package/dist/index.js

@@ -0,0 +1,7 @@
+import { useClientPagination } from "./composables/use-client-pagination.js";
+import { resolveAppContainer, resolveAppContainerSelector } from "./services/app-container.js";
+export {
+  resolveAppContainer,
+  resolveAppContainerSelector,
+  useClientPagination
+};