@done-coding/admin-core 0.20.1-alpha.0 → 0.21.1-alpha.0

package/src/components/modal/docs/README-ModalShelf.md

@@ -42,6 +42,7 @@
 | name | type | 默认 | 语义 |
 | --- | --- | --- | --- |
 | `level` | `ModalLevel = "app"\|"page"\|"custom"`（必传） | — | 架子结构性身份，挂载后不变（setup 期快照非响应式） |
+| `v-model:remote` | `GlobalModalRemote`（可选） | 无默认 | 全局弹窗遥控器挂载面（**仅 app 级架子使用**）：架子把已注册的 app 级弹窗句柄（key → `{evoke, close, update}`）挂进该对象，`modalKey`（已注册 key 清单）同步维护；配置移除时同步移除对应 key 与清单项；AppLayout 内置 app 架子经它对接 `v-model:globalModalRemote`（page/custom 架子不传） |
 
 ### Slots
 
@@ -60,6 +61,8 @@
 
 > ⚠️ expose 实际另含 `items: Ref<ShelfItem[]>`（内部渲染用活跃实例列表；公开类型 `ShelfController` 不含——按公开类型使用）
 
+> **expose 与 `v-model:remote` 分工**：expose 的 `ShelfController` = **架子管理面**（程序员直接操作架子：evoke/remove/close/items）；`v-model:remote` = **应用根遥控面**（App.vue 拿在手里按 key 遥控弹窗）——一个管架子、一个遥控弹窗，勿混。
+
 ## 机制
 
 ### level 层级与合法性断言
@@ -97,6 +100,12 @@ declare module "@done-coding/admin-core" {
 
 `evoke` 返回 `EvokeHandle`：`close()` 关闭、`update(partialPayload)` 增量合并更新 payload（不 remount）。
 
+### remote 挂载（app 级全局遥控器）
+
+`v-model:remote` 是 **app 级架子**的全局遥控器挂载面（page/custom 不传）：架子收到专用 ModalPorter（`globalOnly` Symbol 模式）推送的 app 级弹窗配置后，把 **key → `{evoke, close, update}`** 句柄挂进 remote 对象，并同步维护 **`modalKey: string[]`**（已注册 key 清单——调用方以 `modalKey.includes(key)` 显式判断「该 key 是否已注册」，`evoke` 无返回值，未注册直接调会 TypeError）；配置移除（Porter 卸载）时同步移除对应 key 与清单项。`evoke` 不带 key——key 即 remote 对象上的键；重复 evoke 的行为由配置期 `sameKeyStrategy` 决定。**close 是关键能力**：全局弹窗不能只靠用户点击关闭（可能无关闭按钮 / 需外部编排），外部（App.vue）经 remote 按 key 关闭。
+
+**core 预置全局 key**：core 定义全局预览弹窗 key 常量 `APP_GLOBAL_IMAGE_PREVIEW_KEY` / `APP_GLOBAL_VIDEO_PREVIEW_KEY`（值即 remote 键与 `modalKey` 条目）——AppLayout `enableGlobalImagePreview` / `enableGlobalVideoPreview` 开启后以 `ModalImagePreview` / `ModalVideoPreview` 组件注册进 app 架子（拼接进 `globalModalConfig`），触发组件 `ImagePreviewTrigger` / `VideoPreviewTrigger` 经遥控器按此 key 唤起。
+
 ## 反模式 / 注意
 
 - **业务 [MUST NOT] 自声明 app/page 架子**：AppLayout/AppPage 已内置，重复挂载是层级污染
@@ -111,5 +120,5 @@ declare module "@done-coding/admin-core" {
 - 注册表入口：`ModalPorter`（modalList 注册表，内部自动对接 app/page 控制器并缓存）
 - 层级机制：`modal-shelf-hierarchy.ts`（assertLevelHierarchy 合法挂法断言）、`modal-shelf-core.ts`（实例注册表）、`modal-shelf-types.ts`（ModalLevel / ModalSameKeyStrategy / ShelfController / ShelfItem / ShelfInstance / EvokeHandle / RegisterEntry）
 - 内置挂载点：`AppLayout.vue`（level="app"）、`AppPage.vue`（level="page"）
-- 弹窗组件族：`ModalConfirm` / `ModalForm` / `ModalDetail`（可作架子注入的弹窗组件）
-- 范式页：`apps/reference/src/pages/modal/porter/showcase/`、`apps/reference/src/pages/modal/guide/`
+- 弹窗组件族：`ModalConfirm` / `ModalForm` / `ModalDetail`（可作架子注入的弹窗组件）；预览族 `ModalImagePreview` / `ModalVideoPreview` + 触发端 `ImagePreviewTrigger` / `VideoPreviewTrigger`（全局 key 常量 `APP_GLOBAL_*_PREVIEW_KEY` 预置，AppLayout 开关开启即注册）
+- 范式页：`apps/reference/src/pages/modal/porter/showcase/`、`apps/reference/src/pages/modal/guide/`、`apps/reference/src/pages/modal/preview/showcase/`

package/src/components/modal/docs/README-ModalVideoPreview.md

@@ -0,0 +1,89 @@
+# ModalVideoPreview（视频预览弹窗·lightbox 形态）
+
+> 视频预览原语：**ElDialog 直配黑底 lightbox**（业界 Video Lightbox 模式）+ 原生 `<video controls>` + 弹窗配置化契约。
+> 注册 key 建议 `modalVideoPreview`（ModalShelf/Porter 注册项）；全局预置 key = `APP_GLOBAL_VIDEO_PREVIEW_KEY`。
+> 范式页：`apps/reference/src/pages/modal/preview/showcase/`
+
+## 定位
+
+- **何时用**：任意「弹窗 + 视频播放」场景——上传文件预览、附件查看、素材核对；命令式 / 配置化唤起（全局遥控器 `evoke`、ModalPorter 注册）
+- **何时不用**：操作确认用 `ModalConfirm`；图片预览用 `ModalImagePreview`（ElImageViewer 薄适配）；需要播放器增强（倍速/字幕/流媒体协议）时——`<video>` 原生能力不足，接第三方播放器（Plyr / video.js），本组件不内置
+- **形态依据（业界）**：视频预览弹窗主流 = **Video Lightbox**——黑底沉浸遮罩 + 视频居中播放 + 遮罩/ESC/关闭按钮三通道关闭 + 打开即播、关闭暂停（图片 lightbox 的视频镜像）；组件库无通用视频 lightbox 组件，用 EP 弹层基座（ElDialog）配置出该形态是成本最低路径（**滚动锁 / ESC / 焦点管理 / 遮罩关闭 EP 内置白拿**，只覆盖样式层）
+- **底座 = ElDialog 直配**（[MUST NOT] 用 `ModalConfirm`——确认/表单弹窗体系（白底 + title + footer 按钮）与沉浸预览形态错配，已废弃）：遮罩深色压暗 + dialog 无卡片背景 + 无 header/footer + 居中 16:9 视频（`dc-modal-video-preview` 非 scoped 锚，照 ModalConfirm 先例）
+- **全宽弹窗 + 视频有界**：弹窗 `width: 100vw`（+ `align-center` 清 EP 默认 margin-top，dialog 恰为全屏——定位/滚动锁/ESC/焦点全归 ElDialog，不自造 fixed 定位）；body 内 `__stage`（`height: 100vh` 沉浸黑底 flex 居中）> `__shim`（**`width: min(960px, 100%)`** + 16:9）> video——视频固定 960px 宽（16:9 → 540 高）居中、四周黑边，小屏 `max-width: 100%` 收缩，**不直接撑满全屏容器**；关闭按钮 44px 圆灰底白叉 `top/right: 40px`（dialog 全宽后相对定位即视口角位，与 el-image-viewer 同位同款）
+- **封面兜底**：`coverUrl` 传则作为 `poster` 封面；**不传则 src 自动追加 `#t=0.01`**（Media Fragments URI）——浏览器加载时定位到 0.01s 渲染出视频首帧当封面，配合 `preload="metadata"` 只拉元数据不拉全片
+- `inheritAttrs: false` + 全量 `$attrs` 定向透传 **`<video>`**：未声明原生属性（`autoplay` / `muted` / `loop` / `playsinline` 等）直达 video 元素
+- **注册形态（ModalShelf/Porter）**：架子渲染只传 `show`/`payload`/`closeFn`/`removeFn`——业务值走 payload，双输入源：`url`/`coverUrl` = `props.url ?? payload.url` / `props.coverUrl ?? payload.coverUrl`
+- **全局预置**：core 预置 `APP_GLOBAL_VIDEO_PREVIEW_KEY`——AppLayout `enableGlobalVideoPreview` 开启后自动注册进全局弹窗（见 README-AppLayout）；触发端 `VideoPreviewTrigger` 经遥控器按此 key 唤起
+
+## 快速上手（最小可用）
+
+```vue
+<ModalVideoPreview
+  v-model:show="show"
+  url="https://example.com/a.mp4"
+/>
+```
+
+**要点**：
+
+- `show` 必传（`v-model:show`）；`url` 必传（视频地址）
+- 不传 `coverUrl` 也能出画面——`#t=0.01` 首帧兜底，无需单独准备封面图
+- 打开即黑底沉浸播放（业界 lightbox：遮罩压暗、视频是唯一焦点）；关闭走 ESC / 遮罩 / 关闭按钮
+- 打开自动播放（`autoPlay` 默认开，业界行为；关闭即暂停）——`autoPlay=false` 关闭
+
+## 能力边界 / 按需使用
+
+- **默认即够用：黑底 lightbox + controls 播放条 + 打开即播**——绝大多数预览只传 `show`/`url`。
+- `coverUrl`：仅当需要自定义封面（非首帧）时传；业务侧「上传带封面」场景传此值可省 `#t=0.01` 的一次 seek。
+- `autoPlay`：默认开（打开弹窗即播）；仅当需要「打开先看封面、手动点播」时关。
+- 第三方播放器增强（倍速/字幕/流媒体）：`<video>` 原生不足的场景不塞进本组件——消费方自拼（ElDialog 黑底 + 第三方播放器）。
+- **完整能力演示**：`apps/reference/src/pages/modal/preview/showcase/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（内联 defineProps，无 types.ts）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `show` | `boolean`（必传） | — | 可见性（v-model:show） |
+| `url` | `string`（必传） | — | 视频地址（`<video src>`） |
+| `coverUrl` | `string` | — | 封面图地址（`<video poster>`）；**空 → src 自动追加 `#t=0.01` + `preload="metadata"` 首帧兜底** |
+| `autoPlay` | `boolean` | `true` | 打开弹窗即自动播放（业界 lightbox 行为）；关闭即暂停 |
+| `payload` | `{ url?: string; coverUrl?: string }` | — | 注册形态注入（架子渲染只传 payload；原语用法无需传） |
+| `closeFn` / `removeFn` | `() => void` | — | 注册形态注入的关闭/移除出口（声明避免泄漏进 `$attrs`） |
+| `onClose` | `(status?: boolean) => void` | — | 关闭回调（ElDialog @close 触发） |
+
+> **video 原生属性全量透传**：除 `url` 外未声明属性（`autoplay` / `muted` / `loop` / `playsinline` / `preload` 等）经 `$attrs` 直达 `<video>`。**`controls` 内部固定 `true`**（预览必须可控制播放），外部不可关。
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `update:show` | `boolean` | 可见性同步（v-model） |
+
+### Slots
+
+无（lightbox 沉浸形态无标题/操作区语义——需要「弹窗 + 视频 + 操作按钮」的形态用 `ModalConfirm` + `<video>` 消费方自拼）
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **[MUST NOT] 用 `ModalConfirm` 底座**：白底确认/表单弹窗体系与沉浸预览形态错配（已废弃）——本组件 = ElDialog 直配黑底 lightbox + 契约
+- **无标题 / 无 footer 语义**：lightbox 不配 title/footer/确认取消——需要操作按钮的形态消费方自拼
+- **封面兜底的 `#t=0.01` 只处理「无封面」**：传了 `coverUrl` 就 [MUST NOT] 再追加（追加会覆盖 poster 显示）
+- **`$attrs` 只落 `<video>`**：弹层级 attrs（`draggable` / `destroy-on-close`）[MUST NOT] 混进 `$attrs` 直传——需弹层级能力显式扩展 props
+- **`controls` 不可关**：预览无操作语义但播放控制是基本人权，外部传 `controls=false` 无效（内部固定）
+- **播放器增强不塞本组件**：倍速/字幕/流媒体等原生不足能力——消费方自拼，本组件保持「ElDialog lightbox + 原生 video」薄壳
+
+## 关联
+
+- 弹层族：`ModalConfirm`（确认/表单弹窗体系——视频预览不再用它做底座）、`ModalForm`、`ModalDetail`
+- 预览族：`ModalImagePreview`（图片预览，同为 lightbox 形态；ElImageViewer 薄适配）
+- 触发端：`VideoPreviewTrigger`（封面/占位 + 播放图标两形态统一，点击经全局遥控/自带弹窗唤起本组件）
+- 命令式弹窗体系：`ModalShelf`（架子 + level 层级）+ `ModalPorter`（modalList 注册表）+ 全局遥控器（`globalModalRemote.evoke(APP_GLOBAL_VIDEO_PREVIEW_KEY, { url, coverUrl })`）
+- 范式页：`apps/reference/src/pages/modal/preview/showcase/`

package/src/components/modal/docs/README-VideoPreviewTrigger.md

@@ -0,0 +1,91 @@
+# VideoPreviewTrigger（视频预览触发组件）
+
+> 视频触发原语：封面图（`ElImage` 吃原生懒加载）或深色占位，**两形态统一叠加播放图标**（标识可播放）；**默认插槽可整体自定义**（吐 `open` fn 复用唤起逻辑）；点击经全局遥控器唤起 `ModalVideoPreview`，无全局则自带弹窗兜底。
+> 与 `ImagePreviewTrigger` 对等成对（图片触发端点击直达 ElImage 原生预览；视频无 el 原生预览，仍需弹窗决策链）。
+> 范式页：`apps/reference/src/pages/modal/preview/showcase/`
+
+## 定位
+
+- **何时用**：任意「视频卡片/缩略图可点开播放」场景——上传文件列表、视频素材库；与 `ModalVideoPreview` 成对（触发端 + 播放端）
+- **何时不用**：页面内直接播放 → 用 `<video>` 原生/第三方播放器；仅展示封面不点击 → `ElImage`
+- 关键机制：**核心 = 唤起预览弹窗的逻辑（决策链 + 自带弹窗兜底）内置**；**默认插槽 = 封面按有无分流 + 播放图标两形态统一**，并吐 `open` 供自定义内容复用——
+  - **有 `coverUrl`** → 落地 **`ElImage`**（`src=coverUrl`）→ **原生 `loading="lazy"` 直接可用** + `#placeholder`/`#error` 占位兜底，**封面图上叠加播放图标**（有播放按钮就知道是啥——两形态统一标识可播放）；
+  - **无 `coverUrl`** → **深色占位底 + 播放图标**——**不强行 `#t=0.01` 抠首帧**（业界结论：Safari/iOS 不可靠、blob: URL 失效、播放从偏移处开始、且 video 无原生 lazy——占位方案零请求零副作用，比抠帧省）
+- **默认插槽可整体自定义**：`#default="{ open }"` 接自定义内容（如按钮「播放」）——`open` = 唤起预览的 fn（内部决策链 + 自带弹窗兜底不变），组件不关心自定义内容形态；缺省用内置封面/占位 + 播放图标
+- **点击决策链（全局优先，自带兜底）**：
+  ```
+  if (remote?.value?.modalKey?.includes(APP_GLOBAL_VIDEO_PREVIEW_KEY)) {
+    remote.value[APP_GLOBAL_VIDEO_PREVIEW_KEY].evoke({ url, coverUrl });  // 全局遥控唤起
+  } else {
+    localShow = true;                                                     // 自带 ModalVideoPreview 兜底（v-if）
+  }
+  ```
+  `remote` = `inject(GLOBAL_MODAL_REMOTE_KEY)`（core 导出注入 key，消费方 App 根 provide 同一对象；未注入/未注册 → 静默回退自带弹窗，任何环境可用）
+- **`modalKey` 存在性判断**：遥控器对象上的 `modalKey: string[]`（架子 `registerConfig` 同步维护）——`includes(全局 key)` 显式判断，不依赖 `evoke` 返回值（evoke 无返回值，未注册直接调会 TypeError）
+
+## 快速上手（最小可用）
+
+```vue
+<VideoPreviewTrigger url="https://example.com/a.mp4" />
+```
+
+**要点**：
+
+- `url` 必传（视频地址）；无封面时深色占位 + 播放图标，**零请求**（连 metadata 都不拉）
+- 有封面：`coverUrl` 传封面图 → 缩略图吃原生懒加载
+- 点击后：AppLayout 开了 `enableGlobalVideoPreview`（全局 key 已注册）→ 全局遥控唤起；否则组件自带 `ModalVideoPreview` 本地弹窗
+
+## 能力边界 / 按需使用
+
+- **默认即够用：封面/占位 + 播放图标 + 点击弹播放**——绝大多数场景只传 `url`。
+- `coverUrl`：仅当业务有封面图（如上传时单独传了封面）时传——有封面走 img 路径白拿懒加载 + 图标叠加；无封面走占位路径更省（不抠首帧）。
+- **`#default="{ open }"`**：整体自定义触发 UI（按钮 / 卡片 / 列表行）——`open` 即「打开预览弹窗」，核心决策链与兜底不变；`placeholder` / `error` 插槽仅内置封面内容使用。
+- 弹窗端行为（`coverUrl` 为空时 `#t=0.01` 首帧兜底等）在 `ModalVideoPreview` 上，见 README-ModalVideoPreview——**触发组件不做首帧**。
+- **完整能力演示**：`apps/reference/src/pages/modal/preview/showcase/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（内联 defineProps，无 types.ts）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `url` | `string`（必传） | — | 视频地址（点击唤起预览弹窗的视频） |
+| `coverUrl` | `string` | — | 封面图地址；**空 → 深色占位 + 播放图标（零请求）**；有 → ElImage 封面（原生懒加载） |
+| `lazy` | `boolean` | `true` | 封面图懒加载（仅 `coverUrl` 有值时生效） |
+| `preview` | `boolean` | `true` | 是否可点击唤起预览（false = 纯展示封面/占位） |
+
+> **img 原生属性全量透传**：`$attrs` 直达自身 ElImage（`coverUrl` 路径）——`alt` / `fit` / `loading` 等均可用。
+> ⚠ **`width` / `height` 无效**：EP 2.13 的 ElImage 未声明 width/height props，透传会落根 div 的 HTML attribute（对 div 无渲染效果）。尺寸控制请用外层 CSS / `style`（配合 `fit="cover"` 居中裁切）。
+
+### Emits
+
+无
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#default` | `{ open: () => void }` | **可整体自定义触发 UI**（按钮「播放」/卡片/列表行）：`open` = 打开预览弹窗（内部决策链 + 自带兜底不变）；缺省 = 封面图/占位 + 播放图标（两形态统一），自带点击唤起 |
+| `#placeholder` | 无 | 封面加载中占位（透传 ElImage；仅内置封面内容） |
+| `#error` | 无 | 封面加载失败兜底图（透传 ElImage；仅内置封面内容） |
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **触发组件不做 `#t=0.01`**：无封面就占位 + 播放图标（业界主流，播放按钮即语义）——首帧兜底只存在于弹窗端 `ModalVideoPreview`（播放器场景才需要「不黑屏」）
+- **`$attrs` 只落封面层**：想配「弹窗端视频」（`autoplay` / `muted` 等）[MUST NOT] 经触发组件透传——去 `ModalVideoPreview` 上配
+- **无封面零请求是硬行为**：不预加载、不拉 metadata——触发组件在列表里挂几十个也不产生视频流量
+- **决策链静默回退是硬行为**：任何环境（无遥控器/未注册/未开启全局）都不许报错——自带弹窗兜底保证触发组件永远可用
+- **`preview=false` 只关点击**：仍渲染封面/占位——「展示」能力不随「预览」关掉
+
+## 关联
+
+- 播放端：`ModalVideoPreview`（视频预览弹窗，ModalConfirm 为底 + url/coverUrl，封面空 `#t=0.01` 首帧兜底）
+- 对等组件：`ImagePreviewTrigger`（图片触发端，同一决策链；ElImage 落地 + previewSrc 原图）
+- 全局遥控：`GlobalModalRemote` / `GlobalModalControl` / `modalKey`（modal-shelf-types）+ 注入 key `GLOBAL_MODAL_REMOTE_KEY`（core 导出）+ 全局 key 常量 `APP_GLOBAL_VIDEO_PREVIEW_KEY`
+- AppLayout 开关：`enableGlobalVideoPreview`（开启后自动注册全局视频预览弹窗，见 README-AppLayout）
+- 范式页：`apps/reference/src/pages/modal/preview/showcase/`

package/src/components/table/docs/README-TableMain.md

@@ -45,6 +45,8 @@ const toolbarConfig: TableToolbarConfig<Row> = {
 - **默认即够用：分页 + 骨架屏 + refine 布局 + 工具栏全开**——只传 `api`/`columns`/`rowKey` 即得标准数据表格。
 - **高度链三选一（判据）**：`refine` 默认开（按 viewport 高减 toolbar/pager 得出数据区高）即够用；`maxHeight` 显式定高仅当表格嵌定高容器（如固定高度卡片）时配；`viewportHeight` 显式指定视口可用高仅当 refine 计算不满足（嵌套弹层内消费外层 scope，优先级最高）时配。
 - `fillHeight`：默认关；仅当数据稀疏/为空时需要数据区撑满、分页器贴底（视觉稳定）时开——需已有 `maxHeight` 或 refine+viewportHeight 基准。
+- **空态双态**：非加载态空数据按「api 是否至少被调用过一次」区分——**从未调用过**（如 ListLayout 关 `initialSearch` 首屏）→ ElEmpty 自定义「欢迎触发查询」+ Search 图标；**已调用过但无数据** → 默认 ElEmpty「暂无数据」。
+- **激活刷新条件化**：`onActivated` 的自动 refresh 仅「已发生过查询」后生效（`hasRequested` 自判）——初始化查询关闭/从未查询时 KeepAlive 激活不自动刷新；手动查询过后恢复（有数据心智后保持刷新语义）。
 - `skeleton`：默认开（冷启行数自适应 3~8）；热刷不出骨架属设计语义（外层遮罩盖旧数据），勿改。
 - `customView`（v-model）：默认关；仅当需要网格/卡片视图替代表格（DataListView）时开，且 [MUST] 配 `#custom-view-item` 插槽。
 - `query`：仅当有静态查询参数（固定过滤条件）时传；变化自动重置第 1 页重拉。
@@ -105,6 +107,7 @@ const toolbarConfig: TableToolbarConfig<Row> = {
 | `#<column.prop>` | `TableColumnDefaultScope`：`{row, column, $index, injectInfo, exposeInfo}` | 覆盖列单元格 |
 | `#header-<column.prop>` | `TableColumnHeaderScope`：`{column, $index, injectInfo, exposeInfo}` | 覆盖列表头 |
 | `#custom-view-item` | `DataListViewItemScope<T>` | customView 模式单项渲染 |
+| `empty`（内部默认） | 无 | 空数据插槽——默认按 `hasRequested` 双态：未调用过 api →「欢迎触发查询」+ Search 图标；已调用无数据 → ElEmpty「暂无数据」 |
 
 ### Expose（`TableMainInstance`）
 

package/types/components/app-layout/AppLayout.vue.d.ts

@@ -1,4 +1,5 @@
 import { AppShellContentAnchor, AppLayoutAppStoreSlice, AppLayoutUserStoreSlice, AppLayoutBridgeSlice } from './types';
+import { GlobalModalRemote, RegisterEntry } from '../modal';
 import { WatermarkProps } from 'element-plus';
 type __VLS_Props = {
     /**
@@ -18,7 +19,30 @@ type __VLS_Props = {
      * 需要覆盖 header 区域的场景（如悬浮 logo/搜索框）。
      */
     sidebarAboveHeader?: boolean;
+    /**
+     * 全局弹窗配置数组（非必需；shelf 限定 "app"）——全局登录 / 配置等通用弹窗的
+     * 注册入口，直接传给 AppLayout 内部专用 ModalPorter（globalOnly Symbol 模式，
+     * 只收 app 级）。配置变化（增删条目）自动全量重推。
+     */
+    globalModalConfig?: RegisterEntry[];
+    /**
+     * 是否开启全局图片预览弹窗（默认 false）。开启后内部给 `globalModalConfig`
+     * **拼接**内置配置项 `{ key: APP_GLOBAL_IMAGE_PREVIEW_KEY, component:
+     * ModalImagePreview, shelf: "app" }`——消费方零配置拿全局图片预览，
+     * 触发端 `ImagePreviewTrigger` 经遥控器按此 key 唤起（见 README-AppLayout）。
+     */
+    enableGlobalImagePreview?: boolean;
+    /**
+     * 是否开启全局视频预览弹窗（默认 false）。开启后内部给 `globalModalConfig`
+     * **拼接**内置配置项 `{ key: APP_GLOBAL_VIDEO_PREVIEW_KEY, component:
+     * ModalVideoPreview, shelf: "app" }`——消费方零配置拿全局视频预览，
+     * 触发端 `VideoPreviewTrigger` 经遥控器按此 key 唤起（见 README-AppLayout）。
+     */
+    enableGlobalVideoPreview?: boolean;
 };
+type __VLS_PublicProps = {
+    "globalModalRemote"?: GlobalModalRemote;
+} & __VLS_Props;
 declare function __VLS_template(): {
     attrs: Partial<{}>;
     slots: Partial<Record<NonNullable<AppShellContentAnchor>, (_: {}) => any>>;
@@ -26,8 +50,14 @@ declare function __VLS_template(): {
     rootEl: HTMLDivElement;
 };
 type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
-declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+declare const __VLS_component: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:globalModalRemote": (value: GlobalModalRemote) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:globalModalRemote"?: ((value: GlobalModalRemote) => any) | undefined;
+}>, {
     sidebarAboveHeader: boolean;
+    enableGlobalImagePreview: boolean;
+    enableGlobalVideoPreview: boolean;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
 declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
 export default _default;

package/types/components/app-layout/AppPage.vue.d.ts

@@ -1,3 +1,4 @@
+import { AppPageListLayoutRecommended } from './types';
 type __VLS_Props = {
     /** 充满视口 */
     fullViewport?: boolean;
@@ -36,8 +37,12 @@ declare function __VLS_template(): {
         default?(_: {}): any;
         top?(_: {}): any;
         bottom?(_: {}): any;
-        left?(_: {}): any;
-        right?(_: {}): any;
+        left?(_: {
+            listLayoutRecommended: AppPageListLayoutRecommended;
+        }): any;
+        right?(_: {
+            listLayoutRecommended: AppPageListLayoutRecommended;
+        }): any;
     };
     refs: {
         appPageRef: HTMLDivElement;

package/types/components/app-layout/types.d.ts

@@ -156,3 +156,28 @@ export type AppShellSlots = {
 } & {
     [K in AppShellContentAnchor]?: (scope: AppShellAnchorScope) => VNode[];
 };
+/**
+ * AppPage `#left`/`#right` 插槽 scope 导出的窄栏 ListLayout 推荐配置。
+ *
+ * **性质**：固定内置推荐值（写死、非运行时开关、不做响应式探测），仅经
+ * `#left`/`#right` 插槽 scoped 带出。面向「列表放进 left/right 窄栏」的展示
+ * 形态推荐；消费者拿到后直接 `v-bind` 展开进 ListLayout，可按需 spread 覆盖
+ * （`v-bind="{ ...listLayoutRecommended, customView: false }"`）。
+ *
+ * **定向耦合**：AppPage 持有 ListLayout prop 形状的平铺子集（非泛型，与
+ * ListLayout 泛型 props 无关）——本能力设计使然（README 已声明）；该子集
+ * breaking 时 [MUST] 同步更新本类型与 README-AppPage.md。
+ */
+export interface AppPageListLayoutRecommended {
+    /** 开启自定义视图（DataListView 卡片形态替代 ElTable——窄栏过窄表格必崩）。需配套 ListLayout `#custom-view-item` 定义单项 */
+    customView: true;
+    /**
+     * 分页器最简形态（窄栏少占地）：
+     * - `pageLayout` 去掉 total/sizes/jumper，仅页码（`"prev, pager, next"`）
+     * - `paginationBackground: false` 页码不带背景框（EP 纯数字链接形态）
+     */
+    tableMainProps: {
+        pageLayout: "prev, pager, next";
+        paginationBackground: false;
+    };
+}

package/types/components/display/ShadowClone.vue.d.ts

@@ -0,0 +1,20 @@
+import { ShadowCloneProps } from './types';
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+        default?(_: {}): any;
+        clone?(_: {}): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<ShadowCloneProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<ShadowCloneProps> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/types/components/display/TabsTile.vue.d.ts

@@ -198,7 +198,7 @@ declare function __VLS_template(): {
              * 无单一"可用视口高度"语义)。
              */
             ?: string | undefined) => any) | undefined;
-        }>, "type" | "marker" | "offset" | "bound" | "duration" | "direction" | "scrollTo"> & {
+        }>, "offset" | "type" | "marker" | "scrollTo" | "direction" | "bound" | "duration"> & {
             scrollTo: (href
             /**
              * TabsTile —— TabsMain 平铺(tile)模式渲染分支(仅 TabsMain 内部经 `v-if=tile` 消费,不对外单独发布)。
@@ -407,7 +407,7 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_PublicProps,
          * 无单一"可用视口高度"语义)。
          */
         ?: string | undefined) => any) | undefined;
-    }>, "type" | "marker" | "offset" | "bound" | "duration" | "direction" | "scrollTo"> & {
+    }>, "offset" | "type" | "marker" | "scrollTo" | "direction" | "bound" | "duration"> & {
         scrollTo: (href
         /**
          * TabsTile —— TabsMain 平铺(tile)模式渲染分支(仅 TabsMain 内部经 `v-if=tile` 消费,不对外单独发布)。

package/types/components/display/index.d.ts

@@ -1,3 +1,4 @@
+import { default as ShadowClone } from './ShadowClone.vue';
 import { default as WatchSize } from './WatchSize.vue';
 import { default as TabsMain } from './TabsMain.vue';
 import { default as HeightProvider } from './HeightProvider.vue';
@@ -41,5 +42,11 @@ ActionBtnGroup,
  * boolean 只读展示为彩色标签（纯展示，无交互）：`value` → active/inactive 文本 + ElTag 色彩。
  * 编辑布尔用 ElSwitch；[MUST NOT] 给展示标签挂 onClick toggle 改数据（展示≠编辑，详见 paradigm §9）。
  */
-BooleanTag, };
+BooleanTag, 
+/**
+ * 影分身：零 DOM 输出双渲染位原语——同一插槽内容渲染两处（本体就地 + 分身 teleport 到 `to`，
+ * `disabled` 关闭分身仅就地）。两份 vnode 树 = 两个独立实例，只适合无内部状态的受控组件
+ * （v-model 绑同一 ref 即同源同步）；静态固定 id 双份会撞，消费方负责。
+ */
+ShadowClone, };
 export * from './types';

package/types/components/display/types.d.ts

@@ -239,3 +239,10 @@ export interface BooleanTagProps {
     /** false 时标签色彩，默认 info */
     inactiveTagType?: BooleanTagType;
 }
+/** ShadowClone 影分身 props——零 DOM 输出双渲染位原语（本体就地 + 分身 teleport） */
+export interface ShadowCloneProps {
+    /** 分身 teleport 目标（Vue Teleport to：CSS 选择器 / DOM 元素） */
+    to: string | Element;
+    /** 关闭分身（仅就地渲染单处）；目标容器晚渲染时先关、就绪后开 */
+    disabled?: boolean;
+}

package/types/components/display/use-shadow-target.d.ts

@@ -0,0 +1,9 @@
+export interface UseShadowTargetOptions {
+    /** 分身目标 getter（string selector / Element；空 = 无分身） */
+    to: () => string | Element | undefined;
+    /** 分身开关 getter（disabled 时不观察不激活） */
+    disabled: () => boolean;
+}
+export declare function useShadowTarget(options: UseShadowTargetOptions): {
+    targetValid: import('vue').Ref<boolean, boolean>;
+};

package/types/components/form/FormActiveFilter.vue.d.ts

@@ -0,0 +1,9 @@
+import { FormActiveFilterEntry, FormActiveFilterProps } from './types';
+declare const _default: import('vue').DefineComponent<FormActiveFilterProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    clear: () => any;
+    remove: (entry: FormActiveFilterEntry) => any;
+}, string, import('vue').PublicProps, Readonly<FormActiveFilterProps> & Readonly<{
+    onClear?: (() => any) | undefined;
+    onRemove?: ((entry: FormActiveFilterEntry) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/types/components/form/FormInput.vue.d.ts

@@ -0,0 +1,3 @@
+import { FormInputProps } from './types';
+declare const _default: import('vue').DefineComponent<FormInputProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<FormInputProps> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/types/components/form/FormInputShadowClone.vue.d.ts

@@ -0,0 +1,7 @@
+import { FormInputShadowCloneProps } from './types';
+declare const _default: import('vue').DefineComponent<FormInputShadowCloneProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    "update:modelValue": (value: string | number) => any;
+}, string, import('vue').PublicProps, Readonly<FormInputShadowCloneProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: string | number) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/types/components/form/FormSearch.vue.d.ts

@@ -4,7 +4,7 @@ declare const _default: <PO extends Record<string, any>, SO extends Record<strin
         readonly onSearch?: ((data: import('./types').ExcludeNeverProperties<import('./types').ExtractFormStringifyRawFromObject<PO, SO>> & SQ, type: FormSearchSearchType) => any) | undefined;
         readonly onHeightChange?: ((height: number) => any) | undefined;
         readonly onVisibleChange?: ((status: boolean) => any) | undefined;
-    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onHeightChange" | "onSearch" | "onVisibleChange"> & FormSearchProps<PO, SO, SQ> & Partial<{}>> & import('vue').PublicProps;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onSearch" | "onHeightChange" | "onVisibleChange"> & FormSearchProps<PO, SO, SQ> & Partial<{}>> & import('vue').PublicProps;
     expose(exposed: import('vue').ShallowUnwrapRef<FormSearchInstance<PO, SO>>): void;
     attrs: any;
     slots: Partial<Record<NonNullable<Extract<keyof PO, string>>, (_: any) => any>>;

package/types/components/form/FormSelectShadowClone.vue.d.ts

@@ -0,0 +1,39 @@
+import { OptionItem } from './types';
+type __VLS_Props = {
+    /** v-model（透传 FormSelect；本体与分身弹层同源） */
+    modelValue: OptionItem["value"];
+    /** 影分身开关（本体 + 表头漏斗分身双渲染位，点击漏斗 popover 弹选择器，同一 v-model 同源同步） */
+    shadowClone?: boolean;
+    /** 分身目标容器（表头预埋唯一选择器；shadowClone 时生效，未配置不分身） */
+    teleportTo?: string | Element;
+    /** 分身位字段文字（表头列名；label + 漏斗整块展示、高亮整块——表格 headerRender 只需留 teleportTo 容器） */
+    label?: string;
+    /** 分身高亮判定方法（非必传），入参 modelValue；默认 = 非 null/undefined/空字符串 → 高亮（label + 漏斗整块） */
+    isHighlighted?: (value: unknown) => boolean;
+};
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        option?(_: {
+            data: OptionItem;
+        }): any;
+        option?(_: {
+            data: OptionItem;
+        }): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    "update:modelValue": (value: string | number) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:modelValue"?: ((value: string | number) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/types/components/form/FormShadowCloneDispatch.vue.d.ts

@@ -0,0 +1,44 @@
+type __VLS_Props = {
+    /** 影分身开关（分身位 = label + 漏斗整块，点击漏斗 popover 弹层内渲染 clone 槽内容） */
+    shadowClone?: boolean;
+    /** 分身目标容器（表头预埋唯一选择器；未配置不分身） */
+    teleportTo?: string | Element;
+    /** 分身位字段文字（表头列名；label + 漏斗整块展示、高亮整块——不传仅漏斗，向后兼容） */
+    label?: string;
+    /** 分身整块高亮标识（外部判定后传入，如筛选有值；插槽作用域同步暴露） */
+    highlighted?: boolean;
+    /** popover 浮层宽度（表头空间内弹层，默认 220 容纳输入框/选择器） */
+    popoverWidth?: number | string;
+};
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {
+            highlighted: boolean;
+        }): any;
+        default?(_: {
+            highlighted: boolean;
+        }): any;
+        default?(_: {
+            highlighted: boolean;
+        }): any;
+        clone?(_: {
+            highlighted: boolean;
+        }): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    shadowClone: boolean;
+    highlighted: boolean;
+    popoverWidth: number | string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/types/components/form/FormSortSwitch.vue.d.ts

@@ -0,0 +1,17 @@
+import { FormSortMode, FormSortSwitchModelValue, FormSortSwitchProps } from './types';
+type __VLS_Props = FormSortSwitchProps;
+type __VLS_PublicProps = {
+    modelValue?: FormSortSwitchModelValue;
+} & __VLS_Props;
+declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: FormSortSwitchModelValue) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: FormSortSwitchModelValue) => any) | undefined;
+}>, {
+    mode: FormSortMode;
+    shadowClone: boolean;
+    textType: import('./types').FormSortTextType;
+    showOrder: boolean;
+    teleportMode: FormSortMode;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/types/components/form/FormSortSwitchGroup.vue.d.ts

@@ -0,0 +1,15 @@
+import { FormSortRule, FormSortSwitchGroupProps } from './types';
+type __VLS_Props = FormSortSwitchGroupProps;
+type __VLS_PublicProps = {
+    modelValue?: FormSortRule[];
+} & __VLS_Props;
+declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: FormSortRule[]) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: FormSortRule[]) => any) | undefined;
+}>, {
+    mode: import('./types').FormSortMode;
+    shadowClone: boolean;
+    teleportMode: import('./types').FormSortMode;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;