# ZufyUI 1.29.1 Documentation snapshot. Source files remain authoritative. --- # Source: AGENTS.md # AGENTS / 开发原则 ## 协作流程规则(必须遵守) - **提交/推送前必须先经用户同意**:不要自动 `git commit` / `git push`(含 Gitee/GitHub/gh-pages),等到用户明确说“提交/推送”再执行。 - **不要自动更新文档**:API 文档、README、更新日志等,只有用户明确指定时才更新;不要顺手自动改。 - 每次提交信息要如实描述本次改动。 ## Bug 处理原则(最高优先级) 遇到任何 bug(无论轻重缓急),**先定位根源,再从根源修复**: 1. 绝不允许用“新机制”让 bug 无法触发,来掩盖问题(那是掩盖,不是修复)。 2. 如果根源确实在外部(Windows API / 系统 / 第三方库),才考虑绕过它,并在文档中明确标注“这是对外部问题的规避”。 3. 如果根源在本项目内部代码,必须**找到它并从根源修复**。 4. 如果找不到根源:**如实说明“找不到,未定位”**,交由用户(或用户的其他分析)定位;找到后再修复。**绝不猜测、绝不用“最可疑”下结论、绝不靠引入机制来掩盖。** ## 布局 / UIA / 动画事故教训(必须遵守) - **显式尺寸是契约**:`GridLayout` 的 `width_/height_` 必须进入测量范围,不能“返回 260、内部按 274 排”。禁止用裁剪掩盖排布溢出;先修测量契约。 - **UIA provider 是多线程边界**:UIA 方法可能从 COM/RPC 线程进入,`UiaContexts`、`elements`、provider 的 `elem_`/`ctx_` 不能无锁读写。缓存必须持有明确生命周期;context 不能在 UIA 仍可能持有 provider 时被 erase/析构;provider 内不要保存会失效的裸 context/元素指针。 - **动画不要写用户尺寸属性**:不要在 `UpdateAnimation` 每帧 `SetHeight`/重复 `InvalidateLayout`。用独立动画状态驱动测量,每帧最多一次布局失效;内容显隐要同步 `childrenDirty_`。 - **展开容器不能只看动画进度决定子元素是否入列**:`expanded_ == true` 时内容必须进入 `childrenView_`,不能只靠 `expandProg_ > 0`;否则首次展开后动画起点为 0,`childrenDirty_` 不再变化,折叠再展开会永久不显示内容。 - **初始折叠也要测量一次内容**:否则内容子树从未 Measure,首次展开可能沿用未初始化/旧尺寸,出现文字偏右、下拉框被裁剪,直到窗口 resize 才恢复。 - **崩溃码要读对**:`c0000409` 只是“安全检测失败”的总码;`Subcode 0xA = FAST_FAIL_GUARD_ICALL_CHECK_FAILURE`(CFG 间接调用校验失败),不是 Stack Cookie,也不是 TDR。必须用 minidump 的 `!analyze`/`k` 定位,不能凭 WER 主码猜。 - **可访问性对象生命周期**:`Release`/`ForgetAccessibleElement`/窗口关闭必须与 UIA 回调串行化;不得留下仍可被 UIA 调用的已释放对象或悬垂 context。 - **新增并发/动画/UIA 相关修复必须附回归测试或可复现验证**;没有证据时按“未定位”处理,不要用 try/catch、延时或限幅掩盖。 - **自定义边框 / DWM frame**:Win10 不要设置 `DWMWA_WINDOW_CORNER_PREFERENCE`、不要用 `SetWindowRgn` 裁圆角;Win10/Win11 自定义边框都保留 `DwmExtendFrameIntoClientArea({1,1,1,1})`,并在 `WM_SIZE` / `WM_WINDOWPOSCHANGED` / 背景重载后重新挂 frame 状态,否则 Snap 会丢边框/阴影。圆角只由 Win11 DWM 处理。 - **公开圆角 API 已删除**:`WindowCorner`/`SetWindowCorner`/`GetWindowCorner`/DSL `corner()` 不再提供;需要自定义圆角的用户自行调用 Win32 DWM API,并承担 Win10/Snap 边框阴影风险。 - **渲染驱动是进程级开关**:`SetRenderDriver` 必须在第一次 `Window::Create`/D3D 设备创建之前调用;WARP 只改变应用自己的 D3D11/D2D 内容渲染,不保证 DWM/Compositor 不用 GPU,不能把“省内存”宣传成“零 GPU”。 ## 依赖与约束(避免埋雷) - `UIElement::GetChildren()` 返回的是**元素内部缓冲的引用**,其有效期为“该元素的子列表或可视状态发生变化 / 再次调用该元素的 `GetChildren()` 之前”。遍历期间**不得对同一个元素再次调用 `GetChildren()`**(容器递归自己子元素时用的是各自独立的缓冲,安全)。 - 元素内部用**窗口 id**(不是裸指针)记录所属窗口;窗口销毁后 `GetWindow()` 返回 `nullptr`。 - `UIElement` / `Window` 继承 `ConnectionOwner`,`Connect(signal, slot)` 返回 `Connection`;连接登记在接收者 `ConnectionGroup`,随接收者析构自动断开。成员函数指针用自由 `Connect(receiver, signal, &Class::Method)` 或 `ConnectWeak`,**不要**写 `elem->Connect(sig, &Class::Method)`。 - 所有与窗口相关的全局信号(`UIZSignals::*`)都携带 `Window*`;订阅者必须用 `GetWindow()` 过滤,禁止跨窗口处理。 - 数据视图(List/Table/Tree)的按项/按行元数据要么绑定到项目对象、要么在排序/增删时重映射,禁止用会失效的下标或裸指针悬挂。 ## 链式构造 / API 约定(保持调用侧一致,别让用户猜) - **`.with(&T::Method, args...)`**:只用于**无默认参数、无重载、非初始化列表**的成员函数。 - 带默认参数的成员函数,成员指针含全部形参 → `.with(&X::F, a)` 报“参数太少”。**不要**再往库里加这种函数;新函数若需要可选行为,拆成**两个无默认参数的重载**(如 `SetCheckable(bool)` + `SetCheckableShallow(bool)`)。 - 需要显式给非默认值时用拆分后的具名重载(如 `...Recursive` / `...Selected` / `...Radio` / `...Full` / `...Impl`)。 - **`.apply([](T& x){ ... })`**:逃生舱 —— 仅用于初始化列表、重载歧义、或多步条件逻辑。不要当主写法。 - **`->SetXxx(...)`**:在 DSL 链中尽量不用;需要时用 `.with`;确实不行才 `->`。 - **DSL 短工厂统一 `Z` 前缀**:`ZLbl` / `ZBtn` / `ZSlider` / `ZCard` / `ZPage` / `ZMenu` …;因此同时 `using namespace ZufyUI; using namespace ZufyUI::dsl;` 也不会再和类名冲突。 - **主题钩子**:`ThemeManager::RegisterHook/RegisterSubtreeApplier` 返回 RAII `HookHandle`(析构自动断开);想长期有效就**持有**它;库内部固定钩子用 `RegisterHookPermanent`。 - **整页滚动**:`page->SetScrollableContent(content)` 一行搞定(别再手写 `GridLayout + ScrollViewer` 样板)。 - 更完整的易错点集中在 **`docs/pitfalls.md`**(改库前先扫一遍)。 ## 双语文档规则(API.md / API.en.md) - 两版**同一章节的代码块必须逐行对齐**:**行数相同、顺序相同**(函数签名集合也自然一致)。叙述、注释、示例的**文字**可以各自不同,但**代码块的行数与顺序必须一致**——**行数不匹配 = 一定有一边漏了**。 - 改动任一版后运行校验(退出码 0 = 一致): ```powershell python tools/check_api_parity.py ``` 脚本校验“每章代码块的方法名集合 + 非空行数”;任一项不一致即报错。 - 文档(`.md` / `.tex`)保存为 **UTF-8 无 BOM**;C++ 源文件(`.h`/`.cpp`)保存为 **UTF-8 带 BOM**(中文宽字面量需要)。需要无 BOM / 纯 ASCII 副本时,用 `tools/export_ascii.py` 生成 `dist/ascii`(不提交)。 ## 构建 ```powershell powershell -ExecutionPolicy Bypass -File tools/build.ps1 ``` - 脚本通过 `vswhere` 自动探测 Visual Studio / MSBuild,**不写死安装路径**;构建前会杀掉占用进程。 - 可选:`-Configuration Debug`、`-Platform x86`、`-SkipDebugger`、`-SkipTests`、`-VsRoot `。 - 纯 ASCII 分发副本:`python tools/export_ascii.py`(输出到 `dist/ascii`,见生成目录的 `README.md`)。 - 文档站点:`python tools/build_docs.py`(ZufyUI 包装;通用转换器在 `../md2html`,**不要把库专用逻辑写进它**)。 --- # Source: CHANGELOG.en.md # Changelog > Full history with per-item details. README keeps a concise version history. > Current version: **1.29.1** (source of truth is `ZufyUI_VERSION_STRING` in `ZufyUI.h`; this changelog and the API doc header both derive from that macro). ### 2026-11-20 — PageHost animation and pointer-cancel fixes (v1.29.1) - **PageHost reverse transition**: restored the EaseOut inverse to `1 - cbrt(EasedProgress())`, removing the reverse jump. - **PageHost hit testing**: during animation, points are inverse-translated with each page's `GetChildRenderTransform` before hit testing; hover/click/right-click no longer hit an element at its unshifted position. - **PageHost page removal**: `RemovePage` adjusts or cancels `fromIndex_` / `toIndex_` during animation and leaves no stale indices. - **OnPointerCancel wiring**: `WM_CANCELMODE` / `WM_CAPTURECHANGED` now cancel `pressedElement_` / `mouseCaptureElement_` and clear capture; OLE drag-out is exempt so file drag-out keeps working. - **Show events**: `Opening` / `Opened` now fire for menus and other `WantDwmChrome()==false` windows, and `PresentationState` reaches `Open`. - **Regression tests**: added headless PageHost checks for reverse animation, transformed hit testing and page removal; updated the `TODO.md` baseline to `1.29.1`. - **Verification**: x64 / x86 Release + ZufyUIDebugger builds and full self-tests pass. ### 2026-11-20 — Pointer/focus feedback, window transitions and docs (v1.29.0) - **Pointer / focus / input feedback**: added `SetPointerCursors` / `GetPointerCursorAt` / `OnPointerCancel`; TextBox gained focus background/border, caret colour/thickness, indicator and password-eye fixes; ComboBox supports keyboard expand and up/down selection; Slider commits the final release coordinate; ListView/TableView/TreeView, ScrollBar, Expander, SettingsList and NumberBox gained cursor/cancel handling. - **Layout / font fixes**: Expander, SettingsList, ChartBase/PieChart now inherit the effective font; MenuBar reserves fractional glyph width; Button `FillWidth` measurement is fixed; ListView defers `EnsureVisible` before first Arrange; title-bar active title colour is fixed. - **Window transitions**: added `PresentationState`, `SetTransitionDurations`, `GetPresentationState`, `GetPresentationProgress`, `IsTransitionActive` and `DefaultWindowSetup`; normal windows fade with DComp, default duration remains 0, and menu-owned opacity animation is unaffected. - **Menus / PageHost**: menu click callbacks use `QueueToUIThread` so a menu cannot be destroyed on the WndProc stack; PageHost supports reversing mid-transition and fixes the EaseOut reverse progress calculation. - **Docs**: fixed chapter 8 title mojibake, the companion README link and four API doc lines; regenerated the Chinese and English API docs. - **Verification**: x64 / x86 Release + ZufyUIDebugger builds and full self-tests pass. ### 2026-11-19 — Nonblocking Present, high-refresh pacing, private fonts, UIA lifetime (v1.28.0) - **Nonblocking Present**: opt-in `Window::SetNonBlockingPresent`. When enabled, `Present1(0, DXGI_PRESENT_DO_NOT_WAIT)`; a busy queue is retried by the existing timer/frame clock without blocking or busy-spinning. - **High-refresh pacing**: `SetDisplayFramePacing` / `GetDisplayRefreshHz` and `ZufyUIFrameClock.h`. The worker only arms a timer and posts a message; layout/drawing/Present stay on the UI thread. Off by default; menus enable it by default. - **Menu sync**: `MenuWindowBase` uses nonblocking Present + frame pacing by default; `UseNonBlockingPresent` / `UseFramePacing` are static opt-outs. Hide, close, `WM_DESTROY` and destruction call `Stop()` on the clock. - **Private fonts**: `FontManager::SetAppFontCollection`; install before any format/layout, the manager holds a reference. Menu paths that call `CreateTextFormat` directly still use system fonts. - **UIA lifetime**: root and child providers share `DetachElement + UiaDisconnectProvider`; `WM_DESTROY` calls `UiaReturnRawElementProvider(hwnd,0,0,nullptr)`; `UiaDisconnectProvider` runs outside `UiaMutex`; `SetRootLayout` / `SetAccessibilityEnabled(false)` release consistently. - **Demo**: window-properties page gained nonblocking Present / pacing toggles; popup page covers placement, follow, bounds, close policy and event logs. - **Verification**: x64 `7408` / x86 `7425` self-tests pass. ### 2026-11-19 — Popup window behavior (v1.27.3) - **Window placement**: `Window::Placement` (system default / center on owner / center on screen) plus `CenterOnOwner/CenterOnScreen`. - **Owner follow and move bounds**: `SetFollowOwner` and `MoveBounds` (unrestricted / owner client / monitor work area); owned child windows follow owner movement and are constrained. - **Close policy**: `CloseReason`, `RequestClose`, `ForceClose`, and `Opening/Opened/CloseRequested/CloseAccepted/CloseCancelled`; supports disabled close, Escape close, close veto, and forced close. - **Title bar integration**: the custom title bar close button uses `RequestClose(Caption)`; `BehaviorChanged` keeps the maximize button disabled in owner-client mode. - **Popup first frame**: `RenderNowSync` advances layout and renders a frame on first `Show`, reducing blank first frames. - **Attribution**: the popup behavior was adapted from **whrct22**'s ZufyUI fork (MIT, commit `33c9d7e`); see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). - **Verification**: x64/x86 Release + ZufyUIDebugger builds and self-tests pass. ### 2026-11-19 — Fluent gallery and structured debugging (v1.28.0) - **Demo release**: standalone x64 `demo.exe`, redesigned home, component search, icon navigation and live control playground; all 26 demo pages retained. Light/dark themes, shared Acrylic backdrop through the title/status bars, and 180 ms page transitions. - **Assets**: original multi-resolution application icon; MiSans VF regular design frozen and subsetted for source text, embedded in the executable with system glyph fallback for open-ended input. - **Interaction fixes**: defer ListView scrolling until a viewport exists; measure fill-width rich Button content at its allocated width; reserve fractional-glyph rounding space in MenuBar. Added layout regression assertions. - **Version resources**: library and executable metadata share `ZufyUIVersion.h`; export and documentation build scripts use the same source. - **Included work**: header-only core/widget module extraction; opt-in unified styles and live style edit/undo; JSON CLI and 18 MCP debug tools with verified window identity and structured errors. - **Runtime validation fixes**: commit the slider release coordinate even when the last move message is coalesced; update active title text with the theme; refresh Gallery input/progress colors in dark mode. Packaging validates executable versions and the embedded font hash. - **Real font weights**: embed actual Regular and Semibold MiSans faces with normalized static metadata, eliminating simulated bold. Component entry titles/descriptions use Regular. Settings rows, expander headings and default chart fonts respect the application font. - **Compound controls**: draw password eyes with cached, uniformly scaled curves. `GetPointerCursorAt` resolves text and action regions separately. Add pointer feedback for number-field actions, sliders, standalone scrollbars and scrollbars painted inside lists/tables/trees. Disabling IME no longer changes the number field's text cursor. Capture cancellation clears drag state; regressions cover regions, disabled state, cancellation and rendering resources. - **Readability review**: settings rows and expander headers use action cursors. Advanced inputs and eight actions on the input/scroll page use two columns so labels remain readable. Constructing the environment test page no longer overrides the requested startup theme. ### 2026-11-14 — Stability, control interaction and full-pane transition patch (v1.27.2) - **Window raw-pointer / UIA crashes**: added `Window::ForgetElement` to clear focus, pressed, capture, hover, tooltip, pending-repaint and UIA provider caches in one place; `UIElement::SetParent` detaches window-side references before `ClearChildren()` releases the shared pointer, and `~UIElement` remains the fallback. UIA providers now call `UiaDisconnectProvider` before release, fixing the AV and CFG `FAST_FAIL_GUARD_ICALL_CHECK_FAILURE` crashes after list/member rebuilds. - **TreeView column width**: added `SetStretchLastColumn(bool)` / `GetStretchLastColumn()` (default on); when total content width is narrower than the viewport, the last column receives the remaining width, fixing Chinese labels truncated to `...` by the 40px minimum column width. - **R7 selection consistency**: ListView `GetSelectedIndices` now includes `selectedIndex_`; `SelectAll`/toggle/shift/marquee emit multi-selection signals; clear APIs clear current state. TableView gained `SelectAll`, `GetSelected*` includes the current cell, and clear/marquee emit signals. TreeView `SetSelectedNode` replaces instead of accumulating in multi-select mode. - **ViewCore scaffolding**: added `viewcore::ScrollAxis/ScrollViewport`, `RecyclePool` and `FetchFlow`; ListView now uses `ScrollAxis` for vertical scroll state and has `SetItemProvider(count, fetch)` and `SetAsyncItemProvider(count, fetcher)` for virtual text; the demo exercises 200k pseudo-random rows asynchronously. - **SplitView**: expand buttons now follow the splitter direction; when both minimum sizes cannot fit, the button stays visible but is greyed out and non-interactive. Added `SwitchToFirst/Second/Pane` full-pane slide transitions (PageHost-style easing); they play even when both panes cannot fit and commit the collapse state with `ActivePaneChanged` when finished. - **Async tasks**: added `RunAsync` / `AsyncTask` / `AsyncCancelToken` / `AsyncProgress` / `AsyncOwner`; background execution, cooperative cancellation, coalesced UI progress, ordered completion/failure/cancel callbacks on the UI thread, and callback drop after the weak owner expires; added basic, exception, cancellation, lifetime, 1000 cancellation/completion races and 1000-task randomized stress self-tests. - **Image / window events**: `Image::FromHBITMAP` reads 32bpp DIB pixels and preserves alpha (optional premultiplied flag); `Window::SizeChanged` / `DpiChanged` added; multi-select and HBITMAP-alpha self-tests added. - **SplitView collapse/drag**: unified `ClampFirstLen`, fixing minimum-width conflicts, reverse drags and expansion with insufficient space; added insufficient-space default-side/auto-collapse configuration. - **TrayIcon**: handles both NOTIFYICON_VERSION_4 and v3 `WM_LBUTTONUP`/`WM_RBUTTONUP`/`WM_LBUTTONDBLCLK` fallbacks, fixing unresponsive left/right click and hover; added `SetClickImmediate`. - **Drawer**: on close completion, recursively invalidate content layout and repaint, fixing stale content after clicking the overlay scrim. - **Card**: content measure/arrange now includes the child layout margin, fixing ignored top/bottom margins in Card → ColumnBox. - **TextBox password field**: added a vector eye button on the right in password mode; hidden by default, click toggles plain/masked text; added `TogglePasswordReveal` and `SetPasswordRevealButtonVisible`. - **MessageBox**: compute content size and call `SetSize` before disabling resize, so `WM_GETMINMAXINFO` no longer clamps the height and clips the bottom button; measurement width now subtracts the root margin. - **Verification**: x64 Release + ZufyUIDebugger build; full self-test (including 1000 cancellation races / randomized stress) passes. ### 2026-10-31 — Menu/title-bar/resize fixes and independent render thread disabled (v1.27.1) - **Independent render thread**: disabled and cleaned up the experimental `ZUFYUI_RENDER_THREAD` path; stable single-thread rendering and the VBLANK frame-sync code remain. README/API no longer expose the experiment. - **Context menu**: non-DWM chrome popups skip DWM frame/corner processing, use no rounding and no DWM border, removing the extra border around menus. - **Top menu bar**: closing a menu now clears both `openIndex_` and `hoverIndex_`, preventing a stale half-hover/open highlight. - **Title bar**: `AdvanceFrame` uses the title bar's actual `IsVisible()` state; `SetTitleBarVisible(false)` clears the title-bar height and invalidates layout immediately, fixing menus pushed down after hiding the title bar or returning to the native frame. - **Resize**: after `WM_SIZE` resizes the swap chain it now submits a frame immediately, and `Present1` does not wait for vblank while dragging, avoiding a layout that is already new while the picture is stale/transparent. - **Verification**: x64 Release + ZufyUIDebugger build; 280 self-test checks pass. ### 2026-10-29 — Windows 10 backdrop/frame, Snap, render driver and API cleanup (v1.27.0) - **Windows 10 Acrylic**: enable `ACCENT_ENABLE_HOSTBACKDROP` before creating the HostBackdropBrush, preserving the custom blur/saturation/tint/noise chain; stop writing Win11-only DWM attributes on Win10, avoiding the gray translucent result and lost border/shadow. - **Custom frame / Snap**: keep `DwmExtendFrameIntoClientArea({1,1,1,1})` for custom frames on both Win10 and Win11; reapply frame state after `WM_SIZE`, `WM_WINDOWPOSCHANGED`, and backdrop reloads, fixing lost borders/shadows after Win11 Snap. - **Title bar**: Windows 10 caption glyphs fall back to `Segoe MDL2 Assets`; the maximize/restore button refreshes after system Snap, title-bar double-click, Win+Up, etc.; UI animation updates pause during drag/resize so low-end devices stay responsive. - **Render driver**: added `RenderDriver`, `SetRenderDriver()`, `GetActiveRenderDriver()` and `GetRenderDeviceName()`; `Auto` prefers hardware and falls back to WARP. The demo supports `--warp` / `--gpu` and a restart-based home-page switcher, with the status bar showing the actual driver/adapter. WARP changes only application content rendering; DWM/Compositor may still use the GPU. - **Breaking API cleanup**: removed public `WindowCorner`, `SetWindowCorner()`, `GetWindowCorner()` and DSL `corner()`. Win10 stays square, Win11 follows DWM; custom corners require calling Win32 DWM APIs directly and accepting the risks. - **Verification**: Win10/Win11 normal windows, Snap 1/2 and 1/4, maximize/restore; x64 Release build passes, 280 self-test checks pass. ### 2026-10-27 — Layout measurement contract, UIA lifetime fix, control polish (v1.26.0) - **Layout · explicit size contract**: an explicit `GridLayout` width/height now also constrains cell measurement, so it no longer reports 260 while arranging rows at 274+; `RowBox/ColumnBox` allocate finite main-axis space to Fill children; `Card/Page/ScrollViewer` honour explicit sizes with no content; `Button` measures its content even with autoSize disabled; `Label` explicit width participates in wrapping; `TabView` tab Labels are measured during Measure and arranged in Arrange/Update; `ScrollViewer` no longer re-measures content in Arrange. - **UIA · CFG crash fix**: the minidump confirms `c0000409` + `Subcode 0xA FAST_FAIL_GUARD_ICALL_CHECK_FAILURE` (not Stack Cookie/TDR). `UiaContexts` now uses shared contexts, all UIA context/provider caches share a recursive lock, providers no longer keep raw contexts, `ReleaseAccessibility`/`ForgetAccessibleElement` are serialized with callbacks, and notification paths keep providers alive. Verified with 100 UIA tree walks + 300 `ElementFromPoint` queries. - **Expander**: content is measured once even while initially collapsed; expanded content always stays in `childrenView_`, so collapse/re-expand no longer loses it; animation no longer calls `SetHeight`/duplicates invalidation every frame; content clipping keeps at least a 4 px bleed; fixes first-expand right-shifted text and clipped drop-downs. - **ToggleSwitch**: click toggles on mouse-up; press-drag left/right makes the knob follow the pointer and commits by drag progress; mouse capture; default animation duration 0.18 s. - **Slider**: added `GetDisplayValue()`; normal dragging is immediate, while clicking the track or snapping eases the display value; UIA RangeValue retained. - **Demo**: layout-stress page fixes for Grid height/input-row width/label wrapping; added the "all controls" page; HwndView overlay is hidden by default with a toggle. - **Docs**: API zh/en synced (Grid/Expander/ToggleSwitch/Slider/UIA); README history and feature bullets; AGENTS records the layout/UIA/animation/crash-code lessons. - **Verification**: x64 Release build passes; ZufyUI self-test **280** checks pass; UIA stress queries pass. ### 2026-10-25 — Drawer side panel, temporary key handlers, signal tests (v1.25.0) - **New · `Drawer`**: left/right/top/bottom × Overlay / Push / Permanent. Overlay uses a rounded scrim; Push makes room; Permanent stays open with no animation/scrim and ignores `Close`. Rounded panel, border, and a real outer shadow (shadow first, opaque panel background covers its inner layers, border painted last). - **New · `Window::AddKeyHandler / RemoveKeyHandler`**: temporary window-level key handlers, called after `OnWindowKeyDown` and before the focused element; `Drawer` uses one for Esc while open and removes it on close/detach/destruction. - **New · Drawer demo**: side/mode selectors, open/close, panel-top X, search/category/active-only/result count/filter list; content includes BarChart, Slider, Toggle, CheckBox and ListView. - **Improvement · `ScrollViewer` bleed**: content clip bleed follows `GetBleed()` (default 4px) instead of a fixed 1px, so control borders/shadows inside the drawer are not clipped. - **Tooling · test rename**: `tests/dsl_tests.cpp` → `tests/zufyui_tests.cpp`, `tools/run_dsl_tests.ps1` → `tools/run_tests.ps1`. - **Tests**: signal reentrancy/slot exceptions/`NewThread` weak keep-alive/`UIThread` cancellation, Drawer layout/animation/scrim/Push/Permanent/vertical sides; ZufyUI self-test **213**. - **Demo default backdrop**: reapply Acrylic after `Show()` so the first DWM application always takes effect. - **Verification**: x64 Debug/Release and x86 Release builds pass; 213 self-test assertions pass. ### 2026-10-25 — Signal lifetime, receiver context, ConnectWeak (v1.24.0) - **Breaking · `ZSignal` is non-movable**: removed its move constructor/assignment; signals are control/window members, so do not put them in movable containers. Old code that moves a `ZSignal` now fails to compile. - **Breaking · member-function pointer connections**: `elem->Connect(sig, &Class::Method)` is no longer supported; use `Connect(elem, sig, &Class::Method)` (compile-time checked) or `ConnectWeak(elem, sig, &Class::Method)`. - **Breaking · `Connection` semantics**: `disconnect()` now logically cancels pending `UIThread` / `NewThread` tasks; it does not interrupt a slot already running. - **Fix · signal liveness race**: `ConnectionState::alive` is now atomic; `disconnect` runs its internal removal callback under the state lock; signal destruction `kill()`s states before releasing them, fixing the `alive` data race and the check-then-call UAF. - **Fix · queued tasks**: `UIThread` / `NewThread` tasks capture the connection state and check liveness before running; they no longer execute after receiver destruction or a manual disconnect. - **New · receiver context**: a `ConnectionOwner` base class; `UIElement` / `Window` derive from it. `elem->Connect(...)`, free `Connect(elem, ...)` and `sig.connect(elem, ...)` follow the receiver's lifetime, not the signal owner's. - **New · `ConnectWeak`**: weakly-referenced receiver; the slot's first parameter is `T*` / `T&` or a member-function pointer; the receiver stays alive while the slot runs, and the slot is skipped after destruction. Useful for `NewThread` or uncertain lifetimes. - **Improvement**: `Window`'s `ReloadAcrylic` / `ThemeChanged` / `ThemeReapply` global connections now go through `Window::ConnectionGroup`; manual `Connection` members were removed. `ConnectionGroup::size()` counts live connections only and periodically prunes dead weak references. - **Scope**: `Menu` / `MenuItem` / `Timer` still use `signal.connect` and do not auto-disconnect. - **Tests**: ZufyUI self-test 140 → **175**; added receiver-destruction disconnect, free `Connect`, `ConnectWeak`, `Connection` copy/move, signal-destroyed-first, reentrancy, slot exceptions, `NewThread` weak keep-alive and `UIThread` cancellation regressions. - **Verification**: x64 Debug/Release and x86 Debug builds pass; DSL 175 assertions pass. x86 Release was not rerun this round. ### 2026-10-23 — Button rich content/split, SetBackdrop fix, ListView division (v1.23.3) - **New · Button rich content**: the internal `Label` is a real child now, so `GetLabel()->AddChild(...)` is laid out/composited/drawn; `SetContent(shared_ptr)` / `ClearContent()` replace the content entirely. - **New · Button drop 2x2**: `SetDropWriteBack(bool)` x `SetDropOpenOnClick(bool)`. A button click **always fires `Clicked`**; when opening, the callback runs first, then the menu appears. The menu is **single-select** (the previous choice is marked); selecting fires `DropSelected(index)`, readable via `GetDropSelectedIndex/GetDropSelectedText`; `SetDropItems` builds a text list, `SetDropMenu` accepts a custom menu, and `ShowDropMenu()` opens it when `DropOpenOnClick=false`. The menu appears below the button without a MessageBox. - **Fix ? drop-menu position**: `GetDpiScale()` returns 96/144 (not 1.0/1.5); the old multiplier sent the menu to the screen bottom-right. Dividing by 96 places it under the button, and the demo no longer shows a MessageBox on split click. - **Fix · `SetBackdrop`**: with no explicit tint, `SetBackdrop(Acrylic/Mica)` no longer applies an opaque white overlay (the old default `backdropFollowAlpha_=0xFF` covered the system material); `None` keeps the opaque white default, and explicit tints (including alpha) are preserved. Added `GetBackdropColor()` for diagnostics. - **Fix · `ListView`**: `SetItemHeight` is clamped to >=1px; `Draw` / hit-testing guard against a non-positive row height, avoiding the `SetItemHeight(0)` divide-by-zero and `int` conversion UB. - **Docs/cleanup**: documented the `HwndView` cross-process `SetParent` risks (input queue coupling, blocked messages, intermittent instability); removed the redundant `WM_ACTIVATE` check; added `` to `ZDataViewer.h`; removed the demo's empty `ScrollChanged` callback. - **Demo**: the buttons page now shows a rich-content button and a split button. ### 2026-10-22 — Debug builds: add `/bigobj` (v1.23.2) - **Build**: added `/bigobj` to the **Debug|Win32** and **Debug|x64** configurations of `ZufyUI.vcxproj` / `ZufyUIDebugger.vcxproj` (Release already had it). Full Debug builds previously failed in `ZufyUI.cpp` / `ZufyUIDebugger.cpp` with `C1128: number of sections exceeded object file format limit`. - **Verification**: Release / Debug × x64 / x86 demo + Debugger + ZufyUI self-test all pass. - **Docs**: README / AGENTS / API now document the ASCII-only export and the encoding rule; `dist/ascii` is gitignored and never committed. ### 2026-10-22 — PageHost page measurement + docs & tooling (v1.23.1) - **Fix (layout / hit-testing)**: `PageHost` used to only `Arrange` its pages and **never `Measure` them**, while `Page::Arrange` re-measures only when the arranged size changes. When a page element becomes visible at runtime (typically an `Expander` card shown by `SetVisible(true)` after a combo-box selection), the dirty measure never reached the page → the newly shown element kept a zero `desiredSize`/`arrangedRect` → it was drawn but had no border and failed `HitTest`, until the user resized the window (a size change) once. `PageHost::MeasureOverride` now measures every page; clean pages hit the `Measure` cache, so no duplicate work is added. - **Docs**: the README first screen now leads with positioning, differentiators, the Release link, a screenshot and a one-line experimental note; the full feature list is collapsed; added issue/PR templates; sources moved to `docs/src/` with a new `docs/README.md`; Chinese and English first screens aligned. - **Engineering**: `ZufyUIDebugger` moved into this repository and the solution; `tools/build.ps1` / `run_tests.ps1` locate Visual Studio via `vswhere` (no hard-coded paths) and map x86 to the Win32 output correctly; added `tools/export_ascii.py` (ASCII-only, BOM-free export), `tools/build_docs.py` (ZufyUI docs wrapper) and `tools/make_icon.py` (icons: `docs/icon.*` plus the app icons `ZufyUI.ico` / `small.ico`). - **Docs tooling**: the generic `md2html` no longer probes for ZufyUI; it accepts `--var KEY=VALUE` and `--icon`; ZufyUI version/icon injection lives in `tools/build_docs.py`. - **Repo hygiene**: `TODO.md` is no longer published (removed from the index and gitignored); `dist/` build outputs are ignored. ### 2026-10-13 — Native window host, external visual attachment, overlay sync/performance, NumberBox error state, data-view fill (v1.23.0) - **New**: `ZufyUIHwndView.h` (`HwndView`) — embeds a WebView2 HWND controller / camera / third-party control / out-of-process window into the layout. The host is a top-level owned popup; the external HWND is embedded as a `WS_CHILD` (cross-process allowed). Moving the host moves the child natively; clipping = host client + `SetWindowRgn` (element rect ∩ window client ∩ ancestor `GetClipRect`). - **New**: `Window::CreateExternalVisual / SetExternalVisualBounds / RemoveExternalVisual` (a WinRT `ContainerVisual` attached to the root visual, for WebView2 CompositionController / video); `Window::AddOverlaySync / RemoveOverlaySync / SyncOverlays` (unified overlay sync). - **Performance**: overlay sync is a single window-level point (`WM_MOVE/WM_SIZE/WM_DPICHANGED` immediate + one shared 16ms fallback), removing per-instance timers; DPI/client cached; redundant `SetWindowPos` skipped and `SWP_NOSIZE/NOMOVE` used as appropriate; the demo's color pattern is cached into a DIB. - **Fix (NumberBox)**: a valid number clears the empty-text error state; `ResetToDefault` force-clears the error after notifying the app; step/clear buttons fire on press (no second rect check). - **Fix (data views)**: `ListView`/`TableView`/`TreeView` `MeasureOverride` honours `SetFillWidth/SetFillHeight`. - **Demo**: new "Native HWND" page (GDI color pattern + multiple layouts + an out-of-process `--outproc` window hosted by `HwndView`). ### 2026-10-13 — Tier 0 fixes: layout overflow/alignment, IME, accessibility, visuals/engineering (v1.22.1) - **Fix (layout)**: `RowBox`/`ColumnBox` didn't clamp each child's `base` to min/max → a child with `SetMinWidth/Height` pushed its extra space onto a stretching sibling and overflowed the row/column (the slider spilling outside its card). Now `base = clamp(base, min, max)`. - **Behaviour**: `ColumnBox`/`RowBox`/`GridLayout` **no longer shrink content** — overflow is left to an outer `ScrollViewer`. - **Fix (alignment)**: `GridLayout`'s `SetHorizontalAlignment/SetVerticalAlignment` used `.empty()` (always false) → never applied; now checks "all zero", so `Center/End` work. - **Fix (text/IME)**: `TextBox`/`TextEdit` merge **UTF-16 surrogate pairs** (emoji / beyond-BMP) and insert them as one unit; cursor/backspace/delete span the whole pair; **on losing focus** the control clears its own composition state and `Window::ResetImeState()` cancels the program-side IME composition. `SetImeEnabled(false)` also clears composition. - **Fix (accessibility)**: `GetAutomationIdOrAuto()` now uses a **per-window** counter (no cross-window collisions); `ElementProviderFromPoint` descends child-before-parent to the deepest hit. - **Fix**: data view item/cell `bleedY` reads each element's `GetBleed()`; `indicatorY_` initialised to `-1` (indicator snaps on frame 1); focus ring uses `ThemeRole::FocusRing` + `Theme::cornerRadius`; title-bar buttons take priority over the resize border in `WM_NCHITTEST` (Snap Layouts can appear). - **Engineering**: `pch.h` no longer includes the library headers; added `UIElement::MarkUserColor()`; removed dead `ListView::FindEnabledFrom`. - **Docs**: `docs/API.md`/`API.en.md`, `docs/pitfalls.md`, `AGENTS.md` synced. ### 2026-10-12 — API debt cleanup (P0–P3): `.with` usability, collision-free factories, RAII theme hooks, one-line scrollable page (v1.22.0) - **Breaking · member functions with default arguments split into non-defaulted overloads** (so `.with()` is usable): `TreeView::SetCheckable(bool)` + `SetCheckableShallow(bool)`; `SetNodeCheckable` + `SetNodeCheckableRecursive`; `SetNodeEnabled` + `SetNodeEnabledRecursive`; `SetNodeCheckState` + `SetNodeCheckStateFull`; `ListView::AddItem(text)` and rich-item **`AddItemWidget(shared_ptr