# Deshab 桌面设计文档

> desktop.elf（Winux-Kate结构）的页面、应用、视觉、渲染与性能设计。事实以`CODE/desktop/main.c`与`CODE/UTSM/include/utsm/deshab_ui.h`为准。

---

## 1. 概述

`desktop.elf`是B4锚点加载的桌面管理器，全屏独占framebuffer，复刻Winux-Kate布局。直接轮询PS/2键盘/鼠标，通过boot context获取内核服务，EXIT返回DSK。

Kate之外的桌面特性：RTC+UP计时；VOL/BRIGHT可拖滑块（BRIGHT真实调暗）；开机打字机Boot屏；FILES双击载入EDITOR（FAT32读写+SAVE）；窗口单实例聚焦；Linux应用图标集成（LINUXAPP.CNF→兼容层委托执行）。

---

## 2. 整体布局

```text
app-shell
├── topbar (34px)：品牌+工作区切换+页面切换+PG时钟
├── page-host
│   ├── 1·DASHBOARD：TERM-01/TERM-02/EDITOR/FILES四面板+StatusBar(32px)
│   ├── 2·IDE：标签栏+编辑宿主
│   ├── 3·DESKTOP：图标网格+窗口+任务栏
│   └── 4+/CUSTOM：外部.elf全屏宿主(≤4页，可增删)
└── task-view overlay（工作区卡片）
```

布局常量：KATE_TOPBAR_H=34, KATE_STATUSBAR_H=32, KATE_PAGE_PAD=8, 图标104×90, 网格gap=18, pad=24。

---

## 3. 页面系统

| 页 | 名称 | 内容 |
|----|------|------|
| 1 | DASHBOARD | 四面板(TERM-01+TERM-02+EDITOR+FILES)+StatusBar(时钟/UP/VOL/BRIGHT) |
| 2 | IDE | 标签栏+编辑宿主，多标签+新建 |
| 3 | DESKTOP | 图标网格+浮动窗口+任务栏 |
| 4+ | CUSTOM | 外部.elf全屏宿主，MAX_CPAGES=4 |

- 工作区MAX_WS=6，记录离开时页面；窗口MAX_WINDOWS=8，支持拖拽/聚焦/最小化/关闭
- RTC秒tick仅在DASHBOARD页且非任务视图时触发状态栏重绘

---

## 4. 应用机制（app_descriptor）

所有应用以`app_descriptor`注册（MAX_APPS=16 = 6内置+≤8 Linux应用+余量）：

```c
typedef struct {
    const char *name, *display_name;
    u32 default_w, default_h;
    app_create_fn  on_create;    // 内置应用
    app_event_fn   on_event;
    app_draw_fn    on_draw;
    app_destroy_fn on_destroy;
    const char *elf_name;        // 外部ELF全屏宿主(8.3名)
    const char *linux_cmd;       // Linux兼容层命令
} app_descriptor;
```

`elf_name`与`linux_cmd`互斥（elf_name优先）；仅设linux_cmd时须提供on_create（内置终端窗口承载）。

内置应用：shell(SHELL.ELF)、cmd(CMD.ELF)、editor(内置)、fileman(FILEMAN.ELF)、calc(内置)、browser(BROWSER.ELF)。

单实例策略：固定地址ADDR_TERM1=0x4000000/ADDR_TERM2=0x4100000/ADDR_TERMWIN=0x4200000/ADDR_EDDASH=0x5000000/ADDR_EDWIN=0x5100000/ADDR_CALC=0x6000000。

独立工具应用共享`CODE/tools/desktop_app.h`：dsk_entry入口+da_app_context(fb+block read/write+kernel_api)，block API从kernel_api+0xA8取(read@+0x10,write@+0x18)。

---

## 5. 视觉系统

### 5.1 "Sealed Arc"设计语言

三隐喻：Arc(弧)——圆角/弧形边框；Seal(封)——卡片容器/发光边缘；Flow(流)——渐变/平滑过渡。

### 5.2 设计令牌

| 层 | 内容 |
|----|------|
| L0 原始色板 | Abyss Blue(900–100九级)/Seal Cyan(主操作)/Arc Violet(次级)/Neutral 0–900/语义色/渐变三色 |
| L1 语义色值 | 暗色主题(Shell: BG=DP_ABYSS_900, 主文字=DP_NEUTRAL_700, 强调=DP_SEAL_500)；亮色(FirstInit/DSK) |
| L2 组件令牌 | 圆角/高度/内边距/边框，引用L1 |

约定：色值0xAARRGGBB；**所有UI组件必须经deshab_ui.h取参数，禁止硬编码**。

### 5.3 落地决策

- DU_RADIUS_MD/LG改为0(直角)，仅小按钮4px/模态框16px/药丸全圆角
- 简化面板渲染/窗口光晕/不必要渐变；hover提亮，active反转色

---

## 6. 渲染架构

### 6.1 双缓冲

渲染到sprite buffer(SPRITE_BUF_ADDR=0x7000000, 112MB, identity-mapped)，完成后flip到真实framebuffer。flip_buffer()全屏拷贝；flip_rect(x,y,w,h)仅拷贝指定矩形。

### 6.2 脏矩形

MAX_DIRTY_RECTS=16，mark_dirty记录变化区域，溢出降级全屏重绘。每帧合并为包围盒→redraw_all+flip_rect(合并区域)。终端面板有行级脏标记(dirty_rows+any_dirty)。

### 6.3 光标

软光标24×24，移动时save/restore背景+两次局部flip_rect(旧位置+新位置)。动画延时期间持续轮询鼠标。

### 6.4 主循环

```text
轮询PS/2鼠标→滑块拖拽→排空键盘缓冲→handle_key→RTC tick→
  need_redraw? 全屏重绘+flip / 脏矩形→redraw_all+flip_rect(包围盒)
  moved? 光标save/restore+局部flip
```

---

## 7. FILES面板与FAT32集成

- 经f32_list_root枚举FAT32根目录(MAX_FILES=24)
- 过滤：跳过子目录、.ELF可执行、FIRSTINI*(系统模块)
- 显示名↔8.3内部名双向转换
- 双击：f32_read_root_file读入EDITOR(过滤不可打印字符，保留\n/\t)，聚焦EDITOR；SAVE经FAT32写路径回写
- 无块设备时降级为空态

---

## 8. 桌面图标来源（.lnk快捷方式 + LINUXAPP.CNF Linux应用）

### 8.1 .lnk快捷方式

`setup_desktop_icons()`先上架4个用户快捷方式（编辑器/文件管理/浏览器/终端），`shortcuts_refresh()`当前为硬编码列表（SYSTEM/user/desktop/*.lnk已随镜像分发，解析留待后续）；快捷方式图标`app_id=-1`，双击经`launch_external_elf()`加载对应工具ELF全屏宿主。

### 8.2 LINUXAPP.CNF Linux应用

快捷方式之后追加Linux应用图标。**无论Linux兼容层服务是否可用都注册**：桌面启动时读FAT32根目录LINUXAPP.CNF(8.3名LINUXAPPCNF)，每行一条：`显示名|linux命令`。规则：空行/#注释忽略；显示名≤11字符(DA_LINUXAPP_NAME_CAP=12)，命令≤63字符(DA_LINUXAPP_CMD_CAP=64)；按空格分词(首token为程序路径，绝对路径直接用，裸命令补/bin/前缀)；DA_LINUXAPP_MAX=8。CNF缺失/无有效行时回退内置默认3条（HELLO=/bin/echo、UNAME=/bin/uname -a、LS=/bin/ls -l /，均为Arch rootfs与initramfs busybox共有命令）。

- 图标：`draw_icon_linux`暗底终端+霓虹绿`>_`；服务不可用(VMX缺失/guest未驻留)时改用KS_TEXT_DIM置灰（`g_lnx_svc_up=0`）
- 双击：内置终端窗口承载（720×480，标题`NAME . Linux`）→回显`$ <cmd>`→`lnx_on_create`运行时复查服务：
  - 可用：`linux_compat_service.exec()`同步委托执行（UI冻结），输出经ANSI CSI剥离/`^M`忽略/`\t`展开一次性追加，`[exit N]`按退出码绿/琥珀
  - 不可用：红色提示`linux: compat service unavailable`+`[exit -1]`，绝不panic
- 串口打点：`linux apps: loaded LINUXAPP.CNF`/`builtin defaults`/`service unavailable (icons greyed)`、`linux app registered: <名>`、`linux exec`、`app launched`

---

## 9. 输入系统

- 事件模型：EV_MOUSE_MOVE/DOWN/UP, EV_KEY_DOWN/UP（坐标/按键/scancode/修饰态）
- 鼠标：PS/2轮询3字节包(g_mouse_buf)，按下/释放边沿标志
- 键盘：排空0x60缓冲，处理0xE0前缀+修饰键
- 双击：g_last_click_tsc+位置阈值(TSC计时)
- 交互控件：窗口拖拽、任务栏项、VOL/BRIGHT滑块(slider_set拖拽)、亮度延迟应用

---

## 10. 性能设计

| 瓶颈 | 对策 | 状态 |
|------|------|------|
| 全屏flip拷贝 | 双缓冲+脏矩形合并，仅flip包围盒 | ✅ |
| 圆角/渐变栅格化 | DU_RADIUS_MD/LG改直角、简化光晕 | ✅ |
| 亮度调整 | 延迟应用(g_bright_applied) | ✅ |
| 终端/编辑器重绘 | 行级脏标记增量渲染 | ✅ |
| redraw_all全屏绘制 | 真正局部重绘 | 🔶 |
| memcpy效率 | SIMD/ERMS加速 | 🔶(需SSE启用) |

---

> 相关文档：[ARCHITECTURE.md](ARCHITECTURE.md)、[BOOT_SEQUENCE.md](BOOT_SEQUENCE.md)、[兼容层设计.md](兼容层设计.md)