Skip to content

feat(window): 实现 Windows 平台独立子窗口置顶治理与物理层级调度体系 - #211

Merged
lioensky merged 1 commit into
lioensky:mainfrom
Ldl-h:feat/window-pinning-and-hierarchy-scheduling
Sep 28, 2026
Merged

lioensky merged 1 commit into
lioensky:mainfrom
Ldl-h:feat/window-pinning-and-hierarchy-scheduling

Conversation

@Ldl-h

@Ldl-h Ldl-h commented Sep 28, 2026

Copy link
Copy Markdown
Contributor
  ### 💡 背景与目标
  在多窗口桌面交互中,多个独立子窗口(论坛、备忘录、日志中心、独立终端等)同时置顶时,容易出现小窗口被大窗口完全遮挡吞没、拖拽时层级闪烁冲突等交互痛点。
  本 PR 为客户端带来了一套**零侵入、跨隔离、手感稳定、兼顾临时查看与自动规整**的窗口置顶与 Z 序调度体系。

  ---

  ### 🛠️ 核心实现与架构亮点

  1. **物理聚类与面积密度加权调度(`modules/services/windowPinService.js`)**:
     - 基于 AABB 空间相交算法划分**独立连通分量(Connected Clusters)**,互不重叠的多屏幕或窗口群落独立排位,互不产生层级侧漏;
     - 群落内部按面积加权排序(小窗口自底向上依次声明置顶,确保小工具始终浮在大窗口上方)。

  2. **手势交互语义设计**:
     - **静态点击(惰性查看)**:用户点击下层窗口时遵循 Windows 原生激活,后台不强行抢占层级,彻底根除“反复横跳与抓空失焦”;
     - **动态拖拽(长按持续霸榜)**:拖拽或拉伸时即时插队独占最高层级,长按中途不松手持续锁定;
     - **松手落定(120ms 防抖)**:松开鼠标或窗口失焦后防抖规整,平滑重新归入连通分量重排。

  3. **异构窗口双轨装配**:
     - **标准受管窗口**:通过 `preloads/utility.js` 自动注入通用图钉按钮,自适应原生控制栏;
     - **沙箱隔离插件(PowerShell、BladeGame 等)**:通过主进程观察器接管,不侵入插件沙箱 Preload 与独立 IPC 契约。

  4. **严格的排除范围与契约收敛**:
     - 主聊天窗口(`main.html`)、桌面底座(`desktop.html`)及内嵌 iframe 严禁置顶;
     - 提取专用的 `WINDOW_PIN_KEYS`,遵循最小权限原则收敛于 `UTILITY_KEYS`。

  ---

  ### 🧪 验证与测试
  - [x] 新增自动化测试 `tests/window-pin-service.test.js` 验证通过(覆盖 AABB 碰撞聚类、排序弱序、拖拽防抖、IPC 双向同步与生命周期解绑);
  - [x] 既有隔离测试 `tests/powershell-window-ipc-isolation.test.js` 等 15 项集成测试 100% 通过;
  - [x] 已与 upstream 最新 main 分支(含 ProjectForge 等新模组)无冲突合流。

  配套详细设计文档见:`docs/WINDOW_PIN_ARCHITECTURE.md`。

…eduling

- Add WindowPinService for multi-window pin state and Z-order hierarchy scheduling (AABB overlap clustering, connected components, visual density ordering)
- Implement interaction ergonomics: inert static viewing (click to view), drag preemptive elevation with continuous hold, and 120ms debounce settle upon mouse release
- Implement dual-track mounting: Preload mounting via utility.js for standard child windows, and main-process observer fallback for isolated plugin sandboxes
- Enforce contract exclusion: strictly exclude main chat viewport, desktop base window, and embedded iframes from pinning
- Add comprehensive architecture document (WINDOW_PIN_ARCHITECTURE.md) and automated test suite (window-pin-service.test.js)
@lioensky
lioensky merged commit ddf5ea2 into lioensky:main Sep 28, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants