@done-coding/admin-core 0.27.0 → 0.27.1-alpha.0

package/src/components/list-layout/docs/README-ListLayout.md

@@ -58,6 +58,29 @@ const { listPageConfig } = useSpaceConfig({
 - **`showSwitchView`（双视图切换）：默认关（表格单一视图）。** 仅当需要「列表 / 卡片」双视图切换才开（配 `#custom-view-item` 卡片渲染）。
 - **`isAutoRefresh` / `refreshInterval`：默认关（不自动刷新）。** 仅当列表需轮询刷新（任务态实时变化等）才开。
 - **高度链 prop（`refine` / `viewportHeight` / `parentChannel`）：默认 ListLayout 内部已接管**（refine 默认 true）——常规无需干预，仅特殊高度场景覆写。
+- **两卡模型：默认已分配好，不用配。** 灰底上**两块白卡**：
+  ① **搜索 + 操作**（合并为一块，中间只有分段档，无缝）② **数据区**（toolbar + 表体 + 分页同属一块）。
+  **header 槽恒透明**（页面标题带，与正文一样露底）。
+  - 🔴 面**只有底色 + 呼吸 + 圆角，没有描边、没有投影** —— 层级由面/底一档色差表达。
+    [MUST NOT] 补描边或投影，也 [MUST NOT] 改用 `ElCard` 包（见下方反模式）。
+  - **为什么数据区也成面**：EP 表体自带白底（`--el-table-bg-color` = `--el-fill-color-blank`，
+    core 未接管）。壳不成面时，白表体浮在灰底上、而它上方的 toolbar 与下方的分页悬空在灰底
+    ⇒ 视觉断层。给壳上面色后三者收进同一块白面。
+- **`gap`（间距基数）：默认跟随布局 gap 体系，不用配。** 缺省取
+  `bridge.APP_LAYOUT_GAP_CONFIG.size`（核内默认 8）；取不到 bridge（脱离 AppLayout 挂载）退 8。
+  它是**一个基数派生四档**（`utils/gap-scale.ts`）：
+
+  | 档 | 倍率 | 默认值 | 用在哪 |
+  |---|---|---|---|
+  | 外圈 | ×2 | 16 | 内容 ↔ chrome / viewport 边（由 `AppBody` 给，不在本组件） |
+  | 呼吸 | ×1.5 | 12 | 卡片内边距 |
+  | 模块 | ×1 | 8 | 卡 ↔ 卡 |
+  | 分段 | ×0.5 | 4 | 合并卡内「搜索段 ↔ 操作段」 |
+
+  **改基数 = 四档按比例同步缩放**（单旋钮）；基数还随密度档缩放（compact ×.75 / cozy ×1 /
+  comfortable ×1.5），故**顺序在每个密度档都成立** —— 四档都是同一个数的倍数，不可能乱。
+  🔴 [MUST NOT] 让卡内呼吸改回读 `--dc-core-content-gap`：那是第二个来源，与 gap 各自随
+  不同轴变动，最松档实测会出现「卡内 ≥ 外圈」的乱序。
 - **完整能力演示**（toolbar 全形态 + 粘性三件套 + keepAlive 组合）：`apps/reference/src/pages/list-layout/guide/`（最佳实践）、`pages/list-layout/sticky/`（粘性）、`pages/list-layout/module-demo/`（keepAlive 模块组合）——能力展示，非推荐默认。
 
 ## 上下文默认值（直系父上下文）
@@ -67,11 +90,38 @@ const { listPageConfig } = useSpaceConfig({
 | 场景 | prop | 自动默认 |
 | --- | --- | --- |
 | AppPage `#left` / `#right` 窄栏 | `tableMainProps` | 分页窄栏化：`{ pageLayout: "prev, pager, next", paginationBackground: false }` |
-| 其他容器 / 独立使用 | `tableMainProps` | 不处理（透传 TableMain 默认分页） |
+| AppPage `#left` / `#right` 窄栏 | `formSearchProps.layoutByContainer` | `true`（搜索表单按**容器**断点定档）——窄栏里 `el-col` 按 window 断点解析必然挤爆，是结构性的、不是口味 |
+| 其他容器 / 独立使用 | 两者 | 不处理（透传各自默认） |
+
+> `formSearchProps` 的上下文默认**逐键合并**：显式传 `formSearchProps` 不会整袋覆盖掉 `layoutByContainer`，
+> 只有显式写 `formSearchProps: { layoutByContainer: false }` 才关掉它。
+> ⚠️ `maxRows` **不**参与上下文默认 —— 它是**内容量**的函数（收起态最多几行、且含操作区所在行），不是容器宽的函数；
+> 窄栏下 `maxRows: 1` 会把整块搜索区折叠塌成 0。该值 [MUST] 由消费方按页面内容判。
 
 > ⚠️ 需上下文动态默认的 prop 不写 `withDefaults` 默认（详见 spec：`docs/specs/2026-08-14-080509-moderate-usecontextdefaults直系父上下文默认/spec.md`）。
 > `ListLayout.refine` 默认恒 `true`（withDefaults），不参与上下文解析。
 
+## 各块的面由谁给
+
+- **搜索 + 操作合并卡**（`.list-layout-chrome`）：由 `ListLayout` 自己成面。
+- **header 槽**：不成面，露底（甲方定调）。
+- **数据区**（`TableMain` / `DataGridView` / `InfiniteListView`）：**由它们自己持有**，
+  `ListLayout` [MUST NOT] 再经 `:deep()` 伸手刷 padding / 背景。
+  要关掉数据区的面，走它们自己的 `:surface="false"`。
+
+🔴 原因：面与**可用高账**必须在同一个组件里闭环。此前 padding 由本组件从外面刷、
+可用高在 `TableMain` 里算，两边各管一半 ⇒ 每页恒漏一个 padding。
+
+同理，`.list-layout-chrome` 的高度由挂在**卡本身**的 `WatchSize` 量得（含卡自身
+padding 与内部分段档），[MUST NOT] 退回「量内部两段再拼」。
+
+## 标题（`title` / `#header`）
+
+**优先级：`#header` 插槽 > `title` prop > 不渲染**。常见场景传 `title` 即可，
+复杂头部用插槽接管。与 `ViewLayout.title` 同口径 —— 列表页与详情页头部结构对齐。
+
+标题行**露底不成面**（两卡模型里 header 不是卡），锚点类 `.dc-list-layout__header`。
+
 ## API
 > ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
 
@@ -107,6 +157,8 @@ const { listPageConfig } = useSpaceConfig({
 | `separateSearchConfig` | `Pick<SlotLayoutFlowAsideProps, "type"\|"gap"\|"asideWidth">` | 未设 | 分离侧栏布局 |
 | `searchSticky` / `toolbarSticky` / `pagerSticky` | `boolean` | 均 `false` | 三件套粘性（分离态下 searchSticky 被无视） |
 | `headerObserveResize` / `operationObserveResize` | `boolean` | 均 `false` | header/操作槽量高 ResizeObserver |
+| `gap` | `number` | `bridge.APP_LAYOUT_GAP_CONFIG.size`（核内 8） | **模块间距**（header / 搜索 / 操作区各自的下间距 px）。缺省跟随布局 gap 体系，改布局 gap 即同步；脱离 AppLayout 挂载时退 8 |
+| ~~`moduleBg`~~ | `boolean \| string` | `false` | 🚫 **已废弃**（`akw76r`）。它是**全开关**：一开四块全上色（**含数据区**），与「数据区恒透」直接冲突。它原本要解决的「让模块间距显出来」现已是**默认行为**（三块 chrome 默认成面）⇒ 无需再开。仍可用、行为不变（零 breaking），但 [MUST NOT] 用于新代码；移除走后续 breaking 窗口 |
 | `initialSearch` | `boolean` | `true` | 挂载后是否立即触发初始化查询（默认查）；关闭后表格空态显示「欢迎触发查询」、KeepAlive 激活不自动刷新（TableMain 经「已发生过查询」自判，见 table docs） |
 
 **v-model**：`isAutoRefresh`、`refreshInterval`、`customView`（配合 `#custom-view-item` 卡片渲染）、`activeId`（`string | number | undefined`）/ `activeData`（行对象 | undefined）—— **「当前项」双 model**（= 用户点击/激活的那一条，[MUST NOT] 与勾选 selection 混同）。两者**同生同灭**：`activeId` 有值 ⇒ `activeData` 必有值且恒为**列表数据原样**；列表刷新后当前项不在新数据内 → 两者一并清空；外部写入不在列表内的 id → 忽略 + `console.warn`（不清空既有选中）。⚠️ `activeId` 的 `string` / `number` **两种都是一等公民**：出口值**保业务数据里的原始类型**（`rowKey` 为字段名时即 `row[rowKey]`，数字 id 出数字）；外部用另一种类型写入（如 `"1"` 对数字 id）同样命中——比对时内部统一 `String()` 归一，且**保留调用方写入的原值**不回写覆盖。本组件是**纯透传层**，状态机在下游（table 态 → TableMain / DataListView；grid 态 → DataGridView）；⚠️ `viewMode` 切换会换载下游组件 → 当前项随之丢失（既有换载语义）
@@ -141,6 +193,14 @@ const { listPageConfig } = useSpaceConfig({
 - **keepAlive 页返回刷新**：core 内置（onActivated refresh 留页码），app 侧 [MUST NOT] 补偿
 - **formSearchProps 塞 staticQuery/compact**：类型已 Omit，编译即拦
 - 搜索/表格的双子 props 与 TableMain 直属 prop 重复时，**以 ListLayout 直属为准**（TableMain 恒收 refine=false）
+- 🔴 **[MUST NOT] 给数据区与 header 槽上背景色**（`.dc-table-main` / 网格视图 / `.list-layout-header`）。
+  数据区是**主内容区**、header 是**页面标题带**，两者都该让底透上来——成面是为了把
+  「要读的辅助块」（搜索 / 操作）从底上分出来，标题与正文不需要这件事，
+  给它们上色会让「哪块是辅助、哪块是正文」的视觉层级塌掉。已废弃的 `moduleBg` 正因此被废。
+- 🔴 **[MUST NOT] 用 `ElCard` 包这两块**（即便它看着正好是"卡片"）。三条实证理由：
+  ⓐ 它的底读 `--el-card-bg-color: var(--el-fill-color-blank)`，**是第四个色来源**，
+  绕开刚统一的底/面/浮层三档；ⓑ 自带 shadow / border / header 结构，逐条覆盖的成本
+  高于直接写两条 CSS；ⓒ 多一层 DOM，而本族已有 `dc-` 锚点类可直接定向。
 
 ## 关联
 

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

@@ -31,6 +31,7 @@
 - `#placeholder` / `#error` 插槽：仅当需要自定义加载中/失败兜底图（小图 / base64）时传；缺省 EP 默认观感（灰底加载中 + 失败图标）。
 - `lazy={false}`：仅当图片必须立即加载（首屏无滚动场景）时关。
 - `preview={false}`：关闭点击放大（纯展示缩略图）——仍保留懒加载 + 占位兜底。
+- **点击不冒泡（仅 `preview` 开启时）**：打开放大的同时 `stopPropagation`——缩略图常嵌在表格行 / 卡片里，点图看大图 [MUST NOT] 连带触发行点击 / 卡片跳转。`preview={false}`（纯展示）**不拦**，事件照常上抛给外层（此时组件不做任何事，吞事件反而会让外层行点击失效）。
 - **完整能力演示**：`apps/reference/src/pages/modal/preview/showcase/`——能力展示，非推荐默认。
 
 ## API
@@ -69,6 +70,7 @@
 - **`previewSrc` 才是预览路径**：`src` 是展示路径——缩略图/原图分离时别把大图塞 `src`（懒加载白拉全尺寸图）
 - **`#error` 是插槽不是属性**：传字符串路径是 EP 常见误区（加载失败显示空白）——兜底图放插槽内 `<img :src>`（或 base64）
 - **`preview=false` 只关放大**：仍渲染缩略图 + 懒加载 + 占位兜底——「图片展示」能力不随「预览」关掉
+- **[MUST NOT] 外层再包 `@click.stop` 兜底**：`preview` 开启时组件内部已阻止冒泡；外层再包会把**纯展示态**（`preview=false`）的点击一并吞掉，外层行点击 / 卡片跳转随之失效
 
 ## 关联
 

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

@@ -43,6 +43,8 @@
 - `coverUrl`：仅当业务有封面图（如上传时单独传了封面）时传——有封面走 img 路径白拿懒加载 + 图标叠加。
 - `frameCover`（默认 `true`）：无 `coverUrl` 时是否用 `video#t=0.01` 抠首帧作封面——开 = 首帧封面（视觉接近封面图，代价是**每实例一个 metadata 小请求**，`video` 无原生 lazy）；关 = 深色占位（**零请求**）。视频素材库大列表介意请求量 → 关掉或按需补懒加载（YAGNI，暂未内置）。
 - **`#default="{ open }"`**：整体自定义触发 UI（按钮 / 卡片 / 列表行）——`open` 即「打开预览弹窗」，核心决策链与兜底不变；`placeholder` / `error` 插槽仅内置封面内容使用。
+- **点击不冒泡（仅 `preview` 开启时）**：唤起预览的同时 `stopPropagation`——封面常嵌在表格行 / 卡片里，点封面看视频 [MUST NOT] 连带触发行点击 / 卡片跳转。`preview={false}`（纯展示）**不拦**，事件照常上抛。
+  **自定义默认插槽同样受益**：`open` 接收事件对象，`#default="{ open }"` 里写 `@click="open"` 即自动阻止冒泡（写成 `@click="() => open()"` 丢掉事件则不阻止，需自行 `.stop`）。
 - 弹窗端行为（`coverUrl` 为空时 `#t=0.01` 首帧兜底等）在 `ModalVideoPreview` 上，见 README-ModalVideoPreview——**触发端首帧由 `frameCover` 控制**。
 - **完整能力演示**：`apps/reference/src/pages/modal/preview/showcase/`——能力展示，非推荐默认。
 
@@ -70,7 +72,7 @@
 
 | 槽 | scope | 语义 |
 | --- | --- | --- |
-| `#default` | `{ open: () => void }` | **可整体自定义触发 UI**（按钮「播放」/卡片/列表行）：`open` = 打开预览弹窗（内部决策链 + 自带兜底不变）；缺省 = 封面图/占位 + 播放图标（两形态统一），自带点击唤起 |
+| `#default` | `{ open: (event?: Event) => void }` | **可整体自定义触发 UI**（按钮「播放」/卡片/列表行）：`open` = 打开预览弹窗（内部决策链 + 自带兜底不变）；缺省 = 封面图/占位 + 播放图标（两形态统一），自带点击唤起 |
 | `#placeholder` | 无 | 封面加载中占位（透传 ElImage；仅内置封面内容） |
 | `#error` | 无 | 封面加载失败兜底图（透传 ElImage；仅内置封面内容） |
 
@@ -85,6 +87,7 @@
 - **`$attrs` 只落封面层**：想配「弹窗端视频」（`autoplay` / `muted` 等）[MUST NOT] 经触发组件透传——去 `ModalVideoPreview` 上配
 - **决策链静默回退是硬行为**：任何环境（无遥控器/未注册/未开启全局）都不许报错——自带弹窗兜底保证触发组件永远可用
 - **`preview=false` 只关点击**：仍渲染封面/占位——「展示」能力不随「预览」关掉
+- **`open` 要把事件透给它**：`#default="{ open }"` 里写 `@click="open"`（自动阻止冒泡）优于 `@click="() => open()"`（丢事件 → 不阻止冒泡，外层行点击被连带触发）
 
 ## 关联
 

package/src/components/page-layout/docs/README-AppPageDetail.md

@@ -21,6 +21,16 @@
 
 **② 被门面内嵌（`embedded=true`）** —— 由 `AppPageListDetailLayout` 内部使用，宿主已有一层 `AppPage`，故透传不再套；门面下发完整 `ctx`（含序列导航句柄）。业务一般不直接这么用。
 
+## 标题渲染在哪（`detailTitle`）
+
+- **传了 `detailApi`**（内置 `ViewLayout`）⇒ 标题走 **`ViewLayout` 的 `#header` 槽**，
+  即「容器的标题位」，与 `ListLayout` 的 header 对齐、锚点 `.dc-view-layout__header`。
+- **没传 `detailApi`**（详情数据业务自持、无 `ViewLayout` 容器）⇒ 由本组件自画，
+  锚点 `.dc-app-page-detail__title`，排版与前者同口径。
+
+🔴 [MUST NOT] 退回「在 `#default` 里自画一个 div」：那样标题成了「内容的第一行」，
+位置与 `ListLayout` 对不齐、主题 persona 无从定向（原实现即如此，已归位）。
+
 ## API
 
 > ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
@@ -42,7 +52,7 @@
 
 | 槽        | scope                                                                                        | 语义                                                                               |
 | --------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `#detail` | `{ id, record, index, total, hasPrev, hasNext, goPrev, goNext, refreshList, data, loading }` | 详情内容。`data` / `loading` 仅在传了 `detailApi` 时有值；独立使用时序列字段为零值 |
+| `#detail` | `{ id, record, index, total, hasPrev, hasNext, goPrev, goNext, refreshList, data, loading, fetchSeq }` | 详情内容。`data` / `loading` / `fetchSeq` 仅在传了 `detailApi` 时有值（`fetchSeq` = 成功拉取次数，失败不递增，未传 `detailApi` 恒 0）；独立使用时序列字段为零值。⚠️ `resolvedMode` 只有门面下发，独立成页时无此键（没有形态概念） |
 | `#empty`  | `{ listEmpty }`                                                                              | 无当前项时的占位                                                                   |
 
 ## 反模式 / 注意

package/src/components/page-layout/docs/README-AppPageListDetailLayout.md

@@ -15,10 +15,10 @@
 AppPageListDetailLayout          【L1 门面】无 DOM 输出：持状态 + 形态定档 + provide 上下文
 ├─ split → AppPageListDetailSplit   【L2】AppPage：#left = 列表 · 默认槽 = 详情区
 └─ sheet → AppPageListDetailSheet   【L2】AppPage：默认槽 = 列表 · 抽屉 = 详情区
-                                     └─ AppPageListDetailPane 【L3】有当前项 → 详情；无 → 空态
+                                     └─ AppPageDetail 【L3】有当前项 → 详情；无 → 空态
 ```
 
-三个实现件（Split / Sheet / Pane）**不对外导出**，是门面的实现细节。
+两个形态件（Split / Sheet）**不对外导出**，是门面的实现细节；L3 的 `AppPageDetail` **对外导出**（可独立成页，见 [README-AppPageDetail.md](./README-AppPageDetail.md)）。
 
 ## 快速上手
 
@@ -118,11 +118,69 @@ watch(isOutOfSync, (v) => v && refreshList());
 
 | 槽                            | scope                                                                                        | 语义                                                                                           |
 | ----------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `#list`                       | `{ listProps }`                                                                              | 列表。`listProps` [MUST] 整体 `v-bind` 到列表组件                                              |
-| `#detail`                     | `{ id, record, index, total, hasPrev, hasNext, goPrev, goNext, refreshList, data, loading }` | 详情。`data` / `loading` 仅在传了 `detailApi` 时有值                                           |
-| `#empty`                      | `{ listEmpty }`                                                                              | 未选中占位。`listEmpty=true` 列表本身无数据 / `false` 有数据但未选中，**两种文案 [MUST] 分流** |
+| `#list`                       | `{ listProps, listLayoutRecommended, resolvedMode }`                                         | 列表。`listProps` [MUST] 整体 `v-bind` 到列表组件；`listLayoutRecommended` 是 `AppPage#left` 的窄栏推荐配置（split 档才有值，见下）                                              |
+| `#detail`                     | `{ id, record, index, total, hasPrev, hasNext, goPrev, goNext, refreshList, data, loading, fetchSeq, resolvedMode }` | 详情。`data` / `loading` / `fetchSeq` 仅在传了 `detailApi` 时有值                                           |
+| `#empty`                      | `{ listEmpty, resolvedMode }`                                                                | 未选中占位。`listEmpty=true` 列表本身无数据 / `false` 有数据但未选中，**两种文案 [MUST] 分流** |
 | `#top` / `#bottom` / `#right` | 无                                                                                           | 直通 `AppPage` 同名悬浮槽（**两形态都支持，`auto` 自动挡切档后依旧在**）                       |
 
+### `resolvedMode` —— 实际档位（三槽都有）
+
+`mode` 是**入参**（"我要什么"），`auto` 档实际落在哪一档只有门面知道。三个插槽 scope 都下发只读的
+`resolvedMode: "split" | "sheet"` ——**值是实际档位**，`mode="auto"` 下随视口跨过 `splitAt` 翻转，
+强制档恒为对应值。
+
+```vue
+<template #list="{ listProps, resolvedMode }">
+  <ListLayout v-bind="listProps" :api="api" :columns="resolvedMode === 'split' ? narrowCols : fullCols" />
+</template>
+```
+
+- **[MUST NOT] 自己再判一次视口宽** —— 与门面的 `splitAt` 形成两个事实源，调用方改 `splitAt` 时静默不一致。
+- **纯按宽度变现**（列数 / 间距）优先用 CSS `@container` 容器断点，不必经此值；`resolvedMode` 是给**行为分支**用的。
+
+### `fetchSeq` —— 详情重拉计数（`#detail`）
+
+传了 `detailApi` 时门面内置 `ViewLayout`，每次 `detailApi` **成功返回** `fetchSeq` +1（**失败不递增**）。
+详情里的懒加载下游块（点开才拉的 tab 等）`watch` 它即可选择性重拉：
+
+```vue
+<template #detail="{ data, fetchSeq }">
+  <ElTabs v-model="tab">
+    <ElTabPane name="trace" label="执行步骤">
+      <!-- tab 打开过才拉；详情整体刷新后跟着重拉 -->
+      <TracePanel v-if="tab === 'trace'" :id="data?.id" :refresh-token="fetchSeq" />
+    </ElTabPane>
+  </ElTabs>
+</template>
+```
+
+- **[MUST NOT] 用 `loading` 的 `true→false` 代替** —— 失败也会落回 `false`，下游会基于旧数据白拉一次。
+- **[MUST NOT] watch `data` 的对象身份** —— 「每次返回新引用」从不是承诺，内部一旦做缓存 / 就地合并即静默失效。
+- 未传 `detailApi` 时恒 `0`（无内置 `ViewLayout`、无拉取）。
+
+### ⚠️ `#list` 里包一层 div 会打断上下文默认
+
+`ListLayout` / `ViewLayout` / `TabsMain` 的上下文默认（`useContextDefaults`）读的是**直系父 DOM** 的槽位标记。
+门面已在 split 档的列宽容器上挂了 `AppPage#left` 的标记，**但消费方在 `#list` 内自己包一层**
+（做卡片网格几乎必然要包）就会把链打断 —— 表现是分页不窄栏化、搜索表单按 window 断点被挤爆，**且不报错**。
+
+两条出路，按场景选：
+
+- **ⓐ 不包裹**：直接把 `ListLayout` 作为 `#list` 的根，样式挂到 `ListLayout` 自己身上（`class` / `style` 原样透传）。
+- **ⓑ 包裹了就显式传**：用 `listLayoutRecommended`（split 档下发的窄栏推荐配置）+ 显式 `formSearchProps`：
+
+  ```vue
+  <template #list="{ listProps, listLayoutRecommended }">
+    <div class="card-grid">
+      <ListLayout v-bind="{ ...listProps, ...listLayoutRecommended }"
+                  :form-search-props="{ layoutByContainer: true }" :api="api" :columns="columns" />
+    </div>
+  </template>
+  ```
+
+🔴 **[MUST NOT] 自己在包裹层挂 `data-dc-slot`** —— 那个 attr 的契约是「宿主在槽内容直系父上挂」，
+消费方挂它等于冒充宿主；且上游一旦调整标记位置，这种写法**不报错、只是某天悄悄不生效**。
+
 > **为什么 `#right` 可用、`#left` 不可用**：门面对 `AppPage` 槽的占用是——Split 用 `#left` 放列表、**默认槽**放详情；Sheet 用**默认槽**放列表、**抽屉**放详情。两形态都**没占 `#right`**，故它原样开放给业务；`#left` 则是 Split 自用，不开放。
 >
 > ⚠️ **Sheet 形态下详情打开时抽屉会盖住右栏**：抽屉是 EP 弹层（z-index 2000+ 档）且默认 70% 宽，而 AppPage 悬浮槽是 `APP_PAGE_SLOT_Z_INDEX`=1。这是形态固有结果、**不视为缺陷**——侧栏承载的本就是次要信息（说明 / 辅助入口一类），被临时遮住无妨；[MUST NOT] 为此加避让或降级逻辑。
@@ -140,7 +198,7 @@ watch(isOutOfSync, (v) => v && refreshList());
 
 ## 关联
 
-- 内部件（不导出）：`AppPageListDetailSplit` / `AppPageListDetailSheet` / `AppPageListDetailPane` / `use-list-detail.ts`
+- 内部件（不导出）：`AppPageListDetailSplit` / `AppPageListDetailSheet` / `use-list-detail.ts`；L3 `AppPageDetail` 对外导出
 - 不变式内核：`hooks/use-active-record.ts`（`useActiveRecord`，列表族三家共用）
 - 上下文 key：`APP_PAGE_LIST_DETAIL_CONTEXT`（导航句柄 + `refreshList`，`ViewLayout` 可选 inject 探测）
 - 详情容器：`ViewLayout`（`refreshToken` 外部重拉口 + 内置导航 `showNavigation`）

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

@@ -55,6 +55,26 @@ const toolbarConfig: TableToolbarConfig<Row> = {
 - `showPager`/`pageSizeInit`/`pageSizeOptions`：仅分页形态不满足时调；常规列表不动。
 - **完整能力演示**（工具栏按钮组 + 骨架屏 + fillHeight + 网格视图）：`apps/reference/src/pages/table/toolbar/`、`apps/reference/src/pages/table/skeleton/`——能力展示，非推荐默认。
 
+## 自持面（`surface`）
+
+`TableMain` **自己持有那块面**（面色 `--el-bg-color` + 内呼吸 + 圆角），
+不依赖外层容器伸手来刷 —— 单独用 `TableMain`（不套 `ListLayout`）时观感一致。
+
+🔴 **内呼吸计入可用高**：`surface` 开启时自身 padding 会从数据区可用高里扣掉。
+这是「面归组件自己持有」的**根本理由** —— 样式与高度账在同一个组件内闭环。
+此前 padding 由 `ListLayout` 经 `:deep()` 从外面刷、可用高在 `TableMain` 里算，
+两边各管一半，结果每页恒漏一个 padding（甲方 2026-09-15 报障）。
+**[MUST NOT] 退回「外层刷面、内层算高」。**
+
+**弹窗内不二次成面**：置于 `ModalConfirm` 正文（`data-dc-slot=ModalConfirm_Body`）
+时，经 `useContextDefaults` 自动取 `false`。亮色下 `--el-bg-color` 与
+`--el-bg-color-overlay` 同为 `#fff`、**看不出区别**；暗色下 overlay `#1d1e1f`
+上盖 `#141414` 才会露出「弹窗里凹下去一块」。
+
+⚠️ **已知边界**：`useContextDefaults` 只读**直系父** DOM。若弹窗正文里放的是
+`ListLayout`（它包着 `TableMain`），直系父不是弹窗正文 ⇒ 推导不到、仍会成面，
+此时 [MUST] 显式传 `:surface="false"`。
+
 ## API
 > ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
 
@@ -66,6 +86,7 @@ const toolbarConfig: TableToolbarConfig<Row> = {
 | `columns` | `ElTableColumnProps<T,F>[]`（必传） | — | 列配置数组 |
 | `rowKey` | `Extract<keyof T,string> \| ((row:T)=>string)`（必传） | — | 行主键 |
 | `query` | `SQ` | — | 静态查询参数；变化时重置到第 1 页重新拉取 |
+| `surface` | `boolean` | `true` | **自持面**：面色 + 内呼吸 + 圆角。置于 `ModalConfirm` 正文里时经上下文自动转 `false`（那儿已是一块面）；显式传值恒优先。见下「自持面」 |
 | `showPager` | `boolean` | `true` | 展示分页器 |
 | `pageSizeInit` | `number` | `20` | 初始每页条数 |
 | `pageSizeOptions` | `number[]` | `[10,20,30,40]` | 分页器每页条数选项 |
@@ -132,6 +153,7 @@ const toolbarConfig: TableToolbarConfig<Row> = {
 - **`skeleton` 只覆盖冷启**：热刷不出骨架（外层遮罩盖旧数据），勿误判为骨架失效
 - **customView 需配套插槽**：`customView=true` 显式切 DataListView 时 [MUST] 配 `#custom-view-item` 插槽，否则无渲染
 - **组件 props 版列 scope 是 `_index`**：`$index` 仅插槽 scope 可用；组件 props 版 `$` 开头属性 vue 报错
+- **[MUST NOT] 从外面给 `.dc-table-main` 刷 padding / 背景**：面归组件自持，外面刷会让内呼吸游离在高度账之外（这正是被修掉的老毛病）。要关面用 `:surface="false"`
 - **TableSkeleton / TableToolbar / ToolbarButtons 是内部件**：index.ts 不导出，[MUST NOT] 外部直接消费；对外只认 `TableMain` + types/constants
 
 ## 关联

package/src/components/view-layout/docs/README-ViewLayout.md

@@ -8,7 +8,7 @@
 - **空间一等公民**：展示空间布局首选（页级数据展示的布局壳）——承接 PanelMain 废弃的页级展示场景
 - **何时用**：页级数据展示（详情 / 预览 / 摘要展示）——api 拉数 + 自动刷新 + 内容自由编排
 - **何时不用**：结构化详情字段面板用 `PanelMain`（仅表单预览 / 就地编辑保留场景）；列表用 `ListLayout`
-- 内部组合：`ActionBtnGroup`（左/右 extra 按钮，`default-size="small"` 对齐 table-toolbar 视觉惯例）+ `AutoRefreshGroup`（右侧，refreshFn=api 拉取，经 `HeightProvider` #header 槽 WatchSize 量高）+ 默认插槽（`{ data, loading, refresh, viewportHeight }` 注入）
+- 内部组合：`ActionBtnGroup`（左/右 extra 按钮，`default-size="small"` 对齐 table-toolbar 视觉惯例）+ `AutoRefreshGroup`（右侧，refreshFn=api 拉取，经 `HeightProvider` #header 槽 WatchSize 量高）+ 默认插槽（`{ data, loading, refresh, viewportHeight, fetchSeq }` 注入）
 
 ## 快速上手（最小可用）
 
@@ -54,6 +54,30 @@
 
 > ⚠️ 需上下文动态默认的 prop 不写 `withDefaults` 默认（详见 spec：`docs/specs/2026-08-14-080509-moderate-usecontextdefaults直系父上下文默认/spec.md`）。
 
+## 标题行（`title` / `#header`）
+
+标题渲染在**操作条之上的独立一行**，与 `ListLayout` 的 header 槽结构对齐 ——
+列表页与详情页头部一致，主题 persona 也只需定向一个锚点 `.dc-view-layout__header`。
+
+**优先级：`#header` 插槽 > `title` prop > 不渲染**（不渲染 = 不留空盒占高）。
+
+```vue
+<!-- 常见场景：一个字符串 -->
+<ViewLayout :api="api" title="订单详情" />
+
+<!-- 标题跟着详情数据走：用插槽，scope 带 data / loading -->
+<ViewLayout :api="api">
+  <template #header="{ data }">{{ data?.name ?? "加载中" }}</template>
+</ViewLayout>
+```
+
+🔴 为什么标题要交给容器、[MUST NOT] 在内容插槽里自画一个 div：自画的标题是
+「内容的第一行」而非「容器的标题位」——位置与 `ListLayout` 对不齐，主题也无从定向。
+`AppPageDetail` 原先即如此，已归位（见 migrations）。
+
+样式口径同 `ListLayout` 的 header：**露底不成面**（两卡模型里 header 不是卡），
+只给字号 / 字重 / 外距，[MUST NOT] 加背景与描边。
+
 ## API
 > ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
 
@@ -79,7 +103,7 @@
 
 | 槽 | scope | 语义 |
 | --- | --- | --- |
-| 默认 | `{ data, loading, refresh, viewportHeight }`（`ViewLayoutScope<R>`） | 展示内容；PanelMain 或自由编排皆可；viewportHeight refine 时给可用高、自然流 undefined |
+| 默认 | `{ data, loading, refresh, viewportHeight, fetchSeq }`（`ViewLayoutScope<R>`） | 展示内容；PanelMain 或自由编排皆可；viewportHeight refine 时给可用高、自然流 undefined；`fetchSeq` = **成功**拉取次数（失败不递增），供下游懒加载块判「该重拉了」 |
 
 ### 内置上/下一条导航（仅列表详情范式内出现）
 
@@ -99,6 +123,7 @@
 - **纯展示套 PanelMain 作页级根**：PanelMain 已废弃页级展示场景（见 panel 族文档）——纯展示在插槽内自由编排
 - **channel / parentChannel 响应式变更**：[MUST NOT]——setup 期快照，后续变更无效；缺 refine 的 channel 链静默失效
 - **api 抛错不吞**：api 内部自行处理错误（ViewLayout 只保证 loading 复位，不拦截异常）
+- **[MUST NOT] 用 `loading` 的 `true→false` 当「拉完了」的信号**：失败也会落回 `false`。要判「成功拉到新数据」用 `fetchSeq`（只在成功返回时 +1）
 - **要重拉不要改 `params` 指望它自动生效**：`params` 响应式变化**刻意**不重拉（防请求风暴的既有设计）。「换了参数要重拉」= 改 `params` **并**动 `refreshToken`（或调 `scope.refresh()`）
 - **[MUST NOT] 把触发值塞进 `params` 当刷新开关**：那会把纯前端的令牌发给后端、污染 API 契约——这正是 `refreshToken` 独立成 prop 的原因
 - **[MUST NOT] 用 `:key="token"` 重建来实现重拉**：会连 toolbar / 按钮一起重建，连续切换时闪烁，且语义错位（chrome 不该随内容重建）——用 `refreshToken`

package/src/hooks/docs/README.md

@@ -10,7 +10,7 @@
 | `useCustomBreakpoint` | 容器宽断点：`useCustomBreakpoint()` + `resolveBreakpointByWidth(width)` + `resolveRootEl`（EP 栅格同源阈值） | **容器断点**（非视口）：FormMain `layoutByContainer`、compact 搜索等 |
 | `useObserveSize` | 激活态感知 RO 观测原语：`getTarget` / `onResize` / `enabled` / `debounce`（默认 100ms，leading+trailing） | 需要「捕获渲染后尺寸变化」（CSS 折叠/异步撑开），WatchSize `observeResize` 底层 |
 | `useChannelViewportHeight` | 视口可用最大高解析：`viewportHeight` > scope 链（parentChannel 定向/就近）> fallback；返回 `viewportHeightFinal` + `nearestScope` | 列表/表格/弹窗的高度计算核心消费契约 |
-| `useCoreThemeApply` | 主题挂值：JS → root CSS var（`--dc-core-*` + `--el-*` 双命名空间）+ `buildRhythmCss`（density/motion 节奏） | 由 AppLayout 启动；业务一般不直接调 |
+| `useCoreThemeApply` | 主题挂值：JS → root CSS var（`--dc-core-*` + `--el-*` 双命名空间）+ **全局底**（`:root{background}`）+ elevation 三档（底 `--el-bg-color-page` / 面 `--el-bg-color`=bodyColor / 抬升面 `--dc-core-surface`+`--el-bg-color-overlay`）+ `buildRhythmCss`（density/motion 节奏） | 由 AppLayout 启动；业务一般不直接调 |
 | `useCoreViewportApply` | viewport 边框 CSS var 挂值（`--dc-core-viewport-*` / `--dc-core-gap`） | 由 AppLayout 启动 |
 | `useMenusDataDispatch` | 菜单数据分发：`menus` / `menuFlatList` / `extractLevel1ToHeader` + 当前路由聚焦菜单 | AppHeader/AppSidebar 消费；业务接 meta.menu 树 |
 | `useTimeout` | 定时器 `[setTimer, clearTimer]`，`autoClear` 随激活态/卸载清理 | 组件内延时逻辑（替代裸 setTimeout，防泄漏） |
@@ -47,3 +47,32 @@ const { viewportHeightFinal } = useChannelViewportHeight({ scope: "my-scope" });
 
 - `useActivated` 详细语义见 `docs/specs/` 相关任务文档与 CLAUDE.md 规则 21
 - 断点体系：`useBreakpoint`（视口）与 `useCustomBreakpoint`（容器）双源，见 FormMain `layoutByContainer` 文档
+
+## elevation 三档怎么取值（`useCoreThemeApply`）
+
+| 档 | CSS var | 取值 |
+|---|---|---|
+| **底**（layout ground） | `--el-bg-color-page`（＋ `--dc-core-ground`） | `ground` **显式优先**；缺省由 `bodyColor` 向黑压一步派生 |
+| **面**（surface / 默认背景色） | `--el-bg-color`（＋ `--dc-core-body-color`） | = `bodyColor` |
+| **抬升面**（overlay） | `--el-bg-color-overlay`（＋ `--dc-core-surface`） | `surface` **显式优先**；缺省暗色由面向白提一步、亮色 = 面 |
+
+⚠️ **`bodyColor` 是「面」不是「底」** —— 名字骗人（听起来像 `<body>` 的颜色），
+实际语义是**默认背景色**。要设底 [MUST] 用 `ground`，[MUST NOT] 改 `bodyColor` 去凑。
+
+### 近黑翻转（余量不足时的兜底）
+
+`bodyColor` 的最亮通道 `< 12` 时（如 `#000000` / `#060606`），"向黑压一步"没有余量可压
+（`#000` 压出来还是 `#000` ⇒ **底 = 面、缝彻底不可见**）。此时**翻转方向**：
+
+- 底 = `bodyColor` 原值（把它当地面看）
+- 面 = `bodyColor` **向白提一步**、抬升面再提一步
+
+并 `console.warn` 提示作者改用 `ground` 显式指定。**显式给了 `ground` 就不会触发翻转**
+（有显式值就不需要猜）。
+
+判据用**余量**（最亮通道）不用「亮/暗」：后者需要外部告知 `isDark`，且会在
+「深灰但不算暗色」的主题上判错；余量是纯可计算的。
+
+**方向不随亮暗翻转**：无论亮暗，**面恒比底亮** —— 这是业界共识（EP 亮 `#f2f3f5 < #fff`、
+EP 暗 `#0a0a0a < #141414 < #1d1e1f`、M2 白 overlay 递增、M3 surface-container tone 递增）。
+近黑翻转翻的是**谁来充当基准**，不是"底比面亮"。

package/types/bridge/index.d.ts

@@ -1,4 +1,4 @@
-import { App, CSSProperties, DeepReadonly, Ref } from 'vue';
+import { App, Component, CSSProperties, DeepReadonly, Ref, ShallowRef } from 'vue';
 import { RouteRecordRaw } from 'vue-router';
 import { createUseState } from './state';
 import { createGenerateRouteMetaRawTree } from './route';
@@ -46,6 +46,20 @@ export interface CoreBridgeRegisterOptions<UserInfo = unknown, LoginParams = unk
     getUserInfoApi?: () => Promise<Partial<UserInfo>>;
     /** 刷新 token api（#C 期签名最简化：core 不感知业务 shape，直传 refreshToken string；业务方 wrap 内自打包业务约定的入参 shape，如 `{Authorization: rt}`），增量可选 */
     refreshTokenApi?: (refreshToken: string) => Promise<string>;
+    /**
+     * AI 填充触发组件（gf9z3w 控制反转：注册一次全站根表单可用并驱动入口显隐）。
+     * core 渲染时喂 duck props（`getSchema` / `onData → { appliedCount, undo }`），
+     * 组件来源任意（如 forge-agent `LlmJsonTrigger` 经应用薄 wrapper 预绑定传输参数）——
+     * core 与提供方互不知晓。增量可选。
+     */
+    aiFillTrigger?: Component;
+    /**
+     * AI 填充策略位：表单未配 `description`（表单目标描述）时是否**不予出触点**
+     * （默认 `false` = 照出 + dev 提示——实证 description 是映射质量增强项而非可用性
+     * 前提，字段 label/类型/enum 已够模型映射）。严肃交付场景想强管控（逼业务写清
+     * 表单用途）→ 置 `true`。`FormSearch` 自报家门恒有描述，天然豁免。增量可选。
+     */
+    aiFillRequireDescription?: boolean;
 }
 export type { CoreBridgePlugin, CoreBridgePluginBridgeSlice, CoreBridgePluginContext, CoreBridgePluginInstall, CoreBridgePluginLike, } from './plugin';
 /**
@@ -102,8 +116,25 @@ export interface AppThemeColor {
     blur?: string;
     /** 聚焦环（风格可选；core 仅挂 --dc-core-focus-ring，EP 无对应） */
     focusRing?: string;
-    /** 表面色（风格可选；core 仅挂 --dc-core-surface，EP 无对应） */
+    /**
+     * 抬升面色（overlay 档，风格可选；挂 --dc-core-surface ＋ --el-bg-color-overlay）。
+     * 缺省由 bodyColor 派生（暗色向白一步、亮色 = bodyColor，见 use-theme-apply
+     * buildElevationDecls）；显式给值以显式为准。[MUST NOT] 与 bodyColor（面）语义重叠。
+     */
     surface?: string;
+    /**
+     * 布局底色（page 档，风格可选；挂 --dc-core-ground ＋ --el-bg-color-page）。
+     * 缺省由 bodyColor 向黑压一步派生（`themeScalePageColor`）；显式给值以显式为准。
+     *
+     * 🔴 [MUST NOT] 与 bodyColor 语义重叠：**bodyColor 是「面」（默认背景色），本字段是「底」**
+     * （页面地面 —— 模块间距的缝、header 上方滚动遮挡条露出的就是它）。
+     *
+     * 显式给值能解决派生的三个退化点（派生 Δ = min(0.5×最亮通道, 18)）：
+     * - 近黑（`#000000` ⇒ Δ=0、`#0c0c0c` ⇒ Δ=6）：底≈面、缝不可见 —— 不给 ground 时走近黑翻转兜底；
+     * - 非 hex 的 bodyColor（`var()` / `rgba()` / 渐变）：派生原样返回 ⇒ 底 = 面；
+     * - 品牌规范指定了具体的底色灰阶。
+     */
+    ground?: string;
 }
 /**
  * 布局模块 `style` 逃生舱排除的「引擎托管键」联合（甲方终锁键集）。
@@ -199,19 +230,43 @@ export interface AppConfig {
     };
     /** 应用布局-页面主体配置（store/app 仅取 shimPadding） */
     APP_LAYOUT_BODY_CONFIG: {
-        /** 页面主体 padding - 默认值(px) */
-        shimPadding: number;
+        /**
+         * @deprecated huhyx7 起**不再读取、不影响任何渲染**；配了非 0 值只会得到一条
+         * `console.warn`。字段保留一个版本供下游过渡，之后移除。
+         *
+         * **替代**：内容四周留白改由**间距阶梯的外圈档**（`APP_LAYOUT_GAP_CONFIG.size × 2`）
+         * 一处给出 —— 此前这段空白由 `gap + shimPadding` 两个来源各给一半，
+         * `akw76r` 让容器层露底后两者在视觉上就是同一段空白，冗余由此产生。
+         * 要调留白 ⇒ 改 `APP_LAYOUT_GAP_CONFIG.size`（一个旋钮按比例缩放
+         * 外圈 ×2 / 呼吸 ×1.5 / 模块 ×1 / 分段 ×0.5 四档，见 `utils/gap-scale.ts`）。
+         *
+         * 已由必填改为**可选**（类型放宽，非 breaking）：下游删掉该键即可，不会 TS 报错。
+         */
+        shimPadding?: number;
+        /**
+         * 内容主体背景（color / image / gradient 等 CSS background）。
+         *
+         * **缺省不铺**（akw76r）——`.app-body` 是容器、容器一律透明；布局底由全局 `html`
+         * 一处铺（core 在 `:root{}` 挂 `background: var(--el-bg-color-page)`），一路透到这里。
+         * **模块间距（`APP_LAYOUT_GAP_CONFIG`）的缝**与 **header 上方的滚动遮挡条**
+         * 露出的都是全局那层底。
+         *
+         * 显式给值 = 在 `.app-body` 这一层铺一块面（只影响内容区，不影响 chrome 模块与外框）。
+         * 🔴 [MUST NOT] 拿它铺「与全局底同色」的面 —— 那是把一个会变的值复制到第二处，
+         * 换底 / 换主题时必留补丁。要改底色 → 改**主题的 `ground` / `bodyColor`**（r8kge2）。
+         */
+        background?: string;
     };
     /**
-     * 应用布局-模块间距配置（内缝；模块间露 size px 底色条带，漏出 .app-body 的 bodyColor）。
+     * 应用布局-模块间距配置（内缝；模块间露 size px 条带，漏出 `.app-body` 的布局底）。
      *
-     * 与 viewport 边框（整体外框）正交：gap 是模块**之间**的缝。默认 `{ size: 0 }` = 模块贴合、
-     * 现状不变；`size>0` 时 store 几何 calc 在相邻模块间叠加该间距（缺位侧不留悬空缝）。
-     * 分离观感需模块 `background` 为 surface 色（≠ bodyColor），由 preset/消费方设。
-     * 布局插件经 `bridge.update("APP_LAYOUT_GAP_CONFIG", { size })` 设值。
+     * 与 viewport 边框（整体外框）正交：gap 是模块**之间**的缝。默认 `{ size: 8 }` = 开缝
+     * （底/面分离后缝天然可见：模块面 = bodyColor、`.app-body` 底 = 派生 page 档）；
+     * 要模块贴合显式传 `{ size: 0 }`。`size>0` 时 store 几何 calc 在相邻模块间叠加该间距
+     * （缺位侧不留悬空缝）。布局插件经 `bridge.update("APP_LAYOUT_GAP_CONFIG", { size })` 设值。
      */
     APP_LAYOUT_GAP_CONFIG: {
-        /** 模块间距(px)；缺省 0 = 贴合 */
+        /** 模块间距(px)；缺省 8 = 开缝，0 = 贴合 */
         size: number;
     };
     /**
@@ -533,6 +588,10 @@ export interface CoreBridge<UserInfo = unknown, LoginParams = unknown> {
     getUserInfoApi: () => Promise<Partial<UserInfo>>;
     /** 刷新 token api（createUserStore refreshTokenFn 内调；#C 期签名最简化：core 直传 refreshToken string，业务 wrap 内自打包业务 shape；未注册被调 reject 原生 Error） */
     refreshTokenApi: (refreshToken: string) => Promise<string>;
+    /** AI 填充触发组件槽位（**响应式** shallowRef 只读——表单入口显隐依赖；[MUST NOT] 学 auth 槽位裸闭包 let） */
+    readonly aiFillTrigger: Readonly<ShallowRef<Component | undefined>>;
+    /** AI 填充「无 description 不出触点」策略位（响应式只读，默认 false；见 register 选项注释） */
+    readonly aiFillRequireDescription: Readonly<Ref<boolean>>;
     /** 应用基础信息（per #2.5 期 REQ-1 直接挂载形态） */
     readonly APP_BASE_INFO: DeepReadonly<AppBaseInfo>;
     /** 应用环境信息（per #2.5 期 REQ-1） */

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

@@ -1,4 +1,3 @@
-import { AppPageListLayoutRecommended } from './types';
 type __VLS_Props = {
     /** 充满视口 */
     fullViewport?: boolean;
@@ -8,13 +7,18 @@ type __VLS_Props = {
     background?: string;
     /** 四向悬浮插槽与内容主体 / 插槽间的间隔（px），默认 8 */
     gap?: number;
-    /** top 插槽 shim 容器背景 */
+    /**
+     * 四向悬浮槽 shim 容器背景，**缺省即面色** `--el-bg-color`（akw76r）——
+     * 槽是 page 级 chrome **小块**，本就该浮在底上成一块面。传 `"transparent"` 可关。
+     * 🔴 与根 `background` 的分界：根是**容器**、恒缺省透明（容器一律不铺底）。
+     * [MUST NOT] 拿这几个去「对齐全局底色」补缝 —— 缝不是面，是真空。
+     */
     topBg?: string;
-    /** bottom 插槽 shim 容器背景 */
+    /** bottom 插槽 shim 容器背景（缺省面色，见 {@link topBg}） */
     bottomBg?: string;
-    /** left 插槽 shim 容器背景 */
+    /** left 插槽 shim 容器背景（缺省面色，见 {@link topBg}） */
     leftBg?: string;
-    /** right 插槽 shim 容器背景 */
+    /** right 插槽 shim 容器背景（缺省面色，见 {@link topBg}） */
     rightBg?: string;
     /**
      * 各向插槽尺寸量测是否启用 ResizeObserver（逐槽透传对应 WatchSize 的
@@ -50,10 +54,10 @@ declare function __VLS_template(): {
         top?(_: {}): any;
         bottom?(_: {}): any;
         left?(_: {
-            listLayoutRecommended: AppPageListLayoutRecommended;
+            listLayoutRecommended: import('./types').AppPageListLayoutRecommended;
         }): any;
         right?(_: {
-            listLayoutRecommended: AppPageListLayoutRecommended;
+            listLayoutRecommended: import('./types').AppPageListLayoutRecommended;
         }): any;
     };
     refs: {
@@ -67,6 +71,10 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}
     fullViewport: boolean;
     fullMode: "min-height" | "height";
     nextViewportMaxHeight: string;
+    topBg: string;
+    bottomBg: string;
+    leftBg: string;
+    rightBg: string;
     topObserveResize: boolean;
     bottomObserveResize: boolean;
     leftObserveResize: boolean;