# 更新日志 (Changelog) [English](CHANGELOG.md) | [中文](CHANGELOG_zh.md) 本文件记录 `moon-egui` 项目的所有重要版本变更。 本格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)， 并且本项目严格遵循 [语义化版本规范](https://semver.org/lang/zh-CN/)。 --- ## [Unreleased] ## [0.5.5] - 2026-09-20 ### 新增功能与优化 - **数据表格二维虚拟化滚动与交互式滚动条系统 (`src/composite/table.mbt`)**： - 支持完整的水平滚动状态持久化（`scroll_x` 写入 `Memory`），支持滚轮水平增量与 Shift+垂直滚轮映射。 - 支持键盘左右方向键平滑横向滚动，并在表格获得焦点时严格消费按键事件（`consume_key`）。 - 增加表头独立视口剪裁保护（`push_clip(header_rect)`），大列宽水平平移时表头与数据单元格严格对齐无文字溢漏。 - 水平与垂直滚动条升级为交互式实体，支持基于 `grab_offset` 的鼠标拖拽滑块、`pointer` 悬停光标指示及 DPI 缩放保护。 - **离散输入控件按键消费与焦点环指示 (`src/composite/knob.mbt`, `src/widgets/segmented_control.mbt`)**： - `Knob` 与 `SegmentedControl` 全面消费处理的导航按键（上下左右、Home、End、退格、删除），杜绝外层容器视口意外滚动。 - `SegmentedControl` 支持焦点状态检测（`resp.has_focus() || ctx.has_focus(id)`）与外层动态焦点高亮环绘制。 - **TextEdit 单行输入框水平滚动跟随 (`src/widgets/text_edit.mbt`)**： - 引入 `scroll_x` 偏移并写入 `Memory`，超长文字输入时自动横向滚动视口保持光标可见，点击定位计算动态计入滚动量。 - **VirtualList 交互式滚动条与键盘可达性 (`src/widgets/virtual_list.mbt`)**： - 实现滑块交互拖拽、焦点注册、焦点环绘制以及键盘上下箭头/翻页键滚动支持。 - **ColorPicker 无彩色相记忆与纯矢量渐变 (`src/composite/color_picker.mbt`)**： - 色相角度持久化至 `Memory`（`"hue"` 标签），在饱和度或明度拉为零（黑白灰）时完整保留用户选中的色相角。 - 2D 选色表面升级为双层矢量线性渐变（`LinearGradient`），消除阶梯色块并将图元渲染指令减少 90%。 - **公共 API 设计规范文档全面同步 (`docs/API_DESIGN.md`, `docs/API_DESIGN_zh.md`)**： - 同步最新 v0.5.x 签名（`Response.id : Id`，焦点感知与次级点击方法），将 `toggle` 标为已实现并补充 Fluent/Ref 绑定范式。 - 全面补全 10 大核心组件与子系统规范：`VirtualList`, `Table`, `Plot`, `BarChart`, `Knob`, `Fader`, `DockArea`, `Mesh`, `SvgExporter`, `Spring`。 - **自动化测试用例扩充**： - 自动化无头白盒与黑盒测试套件扩展至 348 项（100% 通过）。 ### 修复 - **图表与柱状图悬停命中检测与光标指示 (`src/composite/plot.mbt`)**： - 移除裸 `rect.contains` 检测，接入 `ctx.is_hovered(rect)` 统一命中机制；折线图上报 `crosshair` 准星光标，柱体上报 `pointer` 手型光标。 - **输入防重复与状态同步 (`src/core/input.mbt`, `src/core/context.mbt`)**： - 根除浏览器 IME 组合输入与原生按键的重复摄入冲突；修复外部按键释放丢失导致的修饰键粘滞；修复 Frame 0 鼠标突跳。 - **图层管理器嵌套前景栈作用域 (`src/core/layers.mbt`)**： - 修复多层嵌套前景层时提前退出的扁平状态，防范非配对前景层调用的死循环。 - **弹簧模拟数值健壮性 (`src/math/spring.mbt`)**： - 增加最大子步数上限截断与 NaN/非正数时间步长守卫，防范超大帧时间造成的无限卡死。 - **色彩插值参数边界校验 (`src/color/color.mbt`)**： - 在 `Color::lerp` 中严格限制插值参数在 `[0.0, 1.0]` 有限数值区间，杜绝非法浮点数扩散。 - **SVG 导出基线垂直对齐 (`src/draw/svg_exporter.mbt`)**： - `` 标签补充 `dominant-baseline="hanging"` 规范对齐属性，消除 SVG 导出文字向上漂移错位。 - **Studio IDE 架构示例代码漂移修复 (`examples/canvas/studio_ide.mbt`)**： - 同步源码展示查看器为解耦后的模块化架构代码（`LayoutEngine`, `FocusManager`, `LayerManager`, `WindowManager`, `Memory`, `Painter`）。 ## [0.5.1] - 2026-09-19 ### 新增功能与优化 - **100% 纯 MoonBit 单 Canvas 工作台 Studio IDE (`examples/canvas/studio_ide.mbt`, `code_workspace.html`)**： - 彻底去除任何 HTML/CSS DOM 仿真，完全由纯 MoonBit 即时模式 GUI 在单个 `` 视口中渲染。 - 集成顶部菜单栏（文件/编辑/视图/终端/帮助菜单下拉、快捷操作按钮）、左侧活动栏与可折叠调节面板（`@composite.Dock`、项目文件树 `@composite.TreeView`）、支持多标签与行号的高级代码编辑器、底部交互式终端面板、快捷命令面板浮层（`@composite.CommandPalette`）与状态栏。 - 采用几何纯矢量推导的月相新月 Logo 与精致徽标排版。 - **技术与几何 Unicode 字符测量宽度支持 (`src/core/context.mbt`)**： - 扩展 `char_width_ratio` 测量字典，支持技术符号、杂项符号与箭头图元（`0x2300` - `0x27BF`：`▶`, `⌘`, `●`, `✓` 等）宽度比率（1.05），根治按钮内文字重叠与边界溢出问题。 - **动态视口全屏遮罩防截断 (`src/composite/command_palette.mbt`)**： - 为 `CommandPalette` 引入 `viewport_size? : @math.Vec2` 参数，自适应任意视口分辨率，消除大屏（高 > 800px）下遮罩半截断的几何缺陷。 - **TreeView 树控件语义化主题色标重构 (`src/composite/tree_view.mbt`)**： - 全面使用动态主题色标（`ctx.theme.bg_window`、`border_focus`、`border_muted`、`bg_hover`、`text_primary`、`text_body`），彻底解决暗黑模式下误显纯白背景的视觉割裂。 ### 修复 - **Button 自动宽度排版与负内边距防护 (`src/widgets/button.mbt`)**： - 修正按钮尺寸推导逻辑，基于文字实际宽度叠加主题内边距自适应扩展，杜绝显式尺寸过小时内边距计算为负导致的布局错位。 - **全屏模态遮罩截断修复**： - 修复命令面板与模态浮层在 800px 以上屏幕高度时遮罩被硬编码截断的缺陷。 ## [0.5.0] - 2026-09-19 ### 新增功能与优化 - **Steps 步骤条居中几何矢量对勾与叉号 (`src/widgets/steps.mbt`)**： - 将原本依赖字体字形的 `"✓"` 与 `"✕"` 字符替换为纯数学推导的几何线段图元 (`add_line`)，中心点与拐点基于圆心和半径严格对称计算。 - 彻底杜绝跨平台字体基线偏移与高分屏缩放下的偏心缺陷，保证在任何分辨率与 DPI 下像素级居中。 - **谐波弹簧物理动力学模型 (`src/math/spring.mbt`)**： - 实现一维 `Spring` 与二维 `Spring2D` 物理简谐振荡器，支持质量、刚度与阻尼系数调节。 - 基于半隐式欧拉子步数值积分，具备平衡静止检测（`is_settled`）与常用预设（`default_spring`, `stiff`, `gentle`, `bouncy`）。 - **几何矢量 SVG 导出器 (`src/draw/svg_exporter.mbt`)**： - 实现 `SvgExporter` 与 `DrawList::to_svg`，支持将图元序列（矩形、描边、圆、文字、折线、渐变与 `` 裁剪栈）无损导出为标准 `.svg` 矢量文件。 - **核心浮层提示气泡控件 (`src/widgets/tooltip.mbt`)**： - 独立 `Tooltip` 控件，通过前景层渲染，具备环境软阴影、语义背景色与外轮廓。 - 支持四向停靠（`Top`, `Bottom`, `Left`, `Right`）、视口边界防溢出翻转与悬停延迟计数器。 - 提供 `on_hover_text` 响应扩展函数与语义调色板色标 `Color::tooltip_bg()`、`Color::tooltip_border()`。 - **一维数据虚拟化列表容器 (`src/widgets/virtual_list.mbt`)**： - `VirtualList` 容器根据滚动偏移与视口高度仅计算并排版可视窗口区间（`first_visible..=last_visible`）及缓冲区，大幅优化海量行数据排版开销。 - 集成鼠标滚轮位移响应与按比例缩放的交互式滚动条指示器。 - **WebGL 2.0 连续网格剖分与顶点缓冲管线 (`src/draw/mesh.mbt`)**： - 实现顶点数据结构 `Vertex`（2D 坐标 `x, y`、UV 坐标 `u, v`、归一化色彩通道 `r, g, b, a`）与网格连续缓冲 `Mesh`。 - 核心几何图元三角网格化算法：`tessellate_rect`（直角与圆角扇形剖分）、`tessellate_circle`（圆弧三角扇）与 `tessellate_line`（沿法线方向挤出带状四边形）。 - 合批生成器 `DrawList::to_mesh()` 与连续内存序列化函数 `Mesh::write_vertex_floats`，支持无拷贝直传 WebGL VBO 缓冲。 - **官网展厅全景升级与代码工作区演进 (`examples/canvas/`)**： - 官网展厅全景接入 `VirtualList`（10,000 行列表视口切片）、`Spring Physics`（2D 阻尼弹簧小球回弹沙盒）与 `SvgExporter`（即时图元转标准 SVG）。 - 全面升级 `code_workspace.html` 为纯粹全幅暗黑 IDE 风格，集成项目资源管理树、多标签实时代码编辑与交互式终端。 - **纯正引擎自举与界面纯净度规范 (`AGENTS.md`, `docs/DESIGN_SYSTEM*.md`)**： - 正式确立强制性规范：所有官方交互展示与工作台必须 100% 由纯 MoonBit 编写并通过 Canvas/Wasm 管线渲染，严禁 HTML/CSS DOM 仿真伪造，严禁无意义、脱节或色彩割裂的内嵌预览框。 - **自动化测试扩充**： - 新增 24 项白盒测试用例，覆盖物理模型、SVG 导出、气泡生命周期、虚拟列表切片、网格三角剖分以及 Steps 矢量几何对勾。 - 全量自动化测试用例扩充至 **335 项，100% 验证通过**。 ## [0.4.0] - 2026-09-16 ### 新增功能与优化 - **离散步进调节输入器 (`Stepper`, `src/widgets/stepper.mbt`)**： - 即时模式步进控件，具备 `[+]` 和 `[-]` 步进按钮、数值边界范围约束（`min`/`max`）、格式化精度输出、前缀/后缀文本与鼠标滚轮微调。 - 支持修饰键步长加速：按住 Shift 为 10× 步长，按住 Ctrl 为 0.1× 步长。 - 全键盘方向键无障碍操作（`ArrowLeft`, `ArrowRight`, `Home`, `End`）与焦点环指示。 - 提供 `StepperRef` 绑定器与链式流式 API（`Stepper::from_ref`）。 - **星标评分评级控件 (`Rating`, `src/widgets/rating.mbt`)**： - 星级评分控件，基于矢量局部 Scissor 剪裁实现 0.5 半星精细打分。 - 支持悬停实时预览（Live Hover Preview），在点击提交前直观预显分值。 - 提供只读展示模式、自定义星标尺寸、间隙与最大星数。 - 键盘方向键分值调节与 `RatingRef` 双向绑定支持。 - **流程与步骤导航条 (`Steps`, `src/widgets/steps.mbt`)**： - 方向性流程步骤导航控件，支持动态步骤标题、副描述文本与高亮连接轨道。 - 支持 `Wait`、`Process`、`Finish`、`Error` 四态自动推导与显式覆盖。 - 支持鼠标点击跳转步骤与键盘方向键无障碍导航。 - **数据分页控制条 (`Pagination`, `src/widgets/pagination.mbt`)**： - 数据分页控件，具备智能折叠省略号算法（如 `1 ... 4 [5] 6 ... 20`）。 - 前进/后退按钮步进翻页与极值边界自动禁用保护。 - 支持 Tab 聚焦后使用 `ArrowLeft`、`ArrowRight`、`Home`、`End` 键盘快捷翻页。 - **节点拓扑流连线编辑器原型 (`NodeEditor`, `src/composite/node_editor.mbt`)**： - 达成开发路线图里程碑 7 目标：无限/有界画布、细点阵网格光栅化与视口 Scissor 剪裁隔离。 - 可拖拽节点卡片，基于泛型 `Memory` 隔离记录位移锚点与选中状态。 - 独立的输入/输出端口系统，支持就近碰撞判定与 `"crosshair"` 十字光标反馈。 - 多步自适应平滑三次贝塞尔导线光栅化算法，支持从输出端口至输入端口的交互式实时拉线与连接。 - **自动化测试套件扩充**： - 新增 `stepper_wbtest.mbt`、`rating_wbtest.mbt`、`steps_wbtest.mbt`、`pagination_wbtest.mbt` 与 `node_editor_wbtest.mbt` 共 31 项多帧白盒/黑盒测试。 - 自动化测试用例总数由 280 项扩展至 **311 项**（**100% 通过率**）。 - **Web 官方展厅全面集成 (`examples/canvas/`)**： - 在 `gallery.html`、`js/gallery-data.js` 与 `js/i18n.js` 中新增上述 5 个组件的在线演示、交互逻辑与中英双语代码范例。 - 重新编译输出纯 MoonBit JavaScript 运行时 `examples/canvas/canvas.js`。 ## [0.3.2] - 2026-09-15 ### 新增功能与优化 - **高性能流式表格与数据解析工具 (`src/widgets/table.mbt`)**： - 高性能流式表格数据结构：支持分隔符自动探测（逗号、制表符、分号）、带引号字段转义以及列数据类型自动推断（`INT`, `FLOAT`, `STR`）。 - 零拷贝行间接索引表（`row_indices : Array[Int]`），实现 $O(1)$ 拷贝开销的多列就地快速排序与微秒级视口剔除虚拟滚动。 - **大规模数据基准测试套件**： - 新增 10,000 行与 50,000 行自生成基准测试用例，全流程验证数据加载、多列排序与全局过滤性能，100% 测试通过。 ### 问题修复 - **快排最坏情况退化优化**：增加中位数基准元选择机制，防止预排序大数据集下递归退化为 $O(N^2)$。 - **零内存分配搜索匹配**：过滤匹配改用零分配字符扫描函数 `contains_ignore_case`，消除按键过滤时的瞬时垃圾回收开销。 ## [0.3.1] - 2026-09-13 ### 新增功能与优化 - **键盘可达性（`FEAT-A11Y-01`）**：菜单栏（触发器开合、下拉项遍历、Escape 关闭）、数据表格（方向键移动高亮行并自动滚入可视窗口、Enter 激活）、右键菜单（打开时方向键导航、跳过禁用项、Enter 展开子菜单）、DockArea（标签切换、分栏把手方向键调整）与独立 splitter、scroll_area、tag、breadcrumb、window 的键盘操作；新增 15 个多帧帧序列测试。 - **交互测试基建**：新增拖拽序列（press→drag→release）与受控组件回喂测试；`AGENTS.md` 固化「Widget Interaction Standard」规范（光标契约、命中测试、弹层前景作用域、全局缩放、键盘可达性、受控组件、多帧测试模式）。 ### 问题修复 - 无（本版本为可访问性与测试覆盖补强）。 ### 其他 - **README 重组**：主 `README.md` 改为英文（mooncakes.io 与 GitHub 默认展示），中文版迁移至 `README_zh.md`，双语切换链接保留。 - 测试总数 246 → 263（100% 通过）。 ## [0.3.0] - 2026-09-13 ### 破坏性变更 (Breaking Changes) - **控件调用全面迁移到分层命名空间**：`ctx.button(...)` 等 `UIContext` 点方法移除，改为 `@widgets.button(ctx, ...)` / `@composite.knob(ctx, ...)`；控件导入从 `src/core` 迁至 `src/widgets` / `src/composite`；`src/lib.mbt` 门面保留全部类型重导出。详见 `docs/API_DESIGN.md` 与 `ARCH-06`。 ### 问题修复 - **光标契约落地**：全部可交互表面按语义上报光标（按钮/标签/标签页 = `pointer`，滑杆 = `ew-resize` / `ns-resize`，分栏 = `col-resize` / `row-resize`，窗口标题栏 = `move`，文本 = `text`，HSV 取色区 = `crosshair`）；修复 ColorPicker、窗口标题栏、DockArea 标签、Toast 关闭钮、Sparkline 悬停五处缺失；**CAD 画板页（benchmark.html）宿主此前从不应用光标**，现经 `FrameOutput.cursor` 全帧同步。 - **命中测试统一走 `is_hovered`**：清除 21 处原始 `rect.contains(mouse_pos)` 命中测试，控件在 `scroll_area` 裁剪外或被窗口/前景层遮挡时不再误响应（刻意保留三处 modal「点卡片外部关闭」的原始几何判定）。 - **弹层自遮挡修复**：context menu / command palette / toast 此前会用自己的 hover blocker 在第二帧起吞掉自身 `is_hovered`——表现为菜单选不中行、面板滚轮失灵、toast 关闭钮点不掉；现将弹层交互阶段置于前景作用域，并附第二帧回归测试。 - **全局缩放覆盖补全**：`Knob` 与 `ColorPicker` 此前不随 `WidgetStyle.scale` 缩放（几何为硬编码字面量），现全部跟随，并以「scale 2 几何恰为 scale 1 两倍」的回归测试锁定。 - **构建脚本入口符号锚定**：`scripts/build_demo.*` 此前的模糊匹配会把 `window.moon_step` 错绑到 `Knob::step` 导致画板页静默失效，现锚定 `examples/canvas` 模块并重建产物。 - **文档与官网示例 API 迁移**：README（中英）、`docs/API_DESIGN*`、`docs/ARCHITECTURE*`、`docs/README_en` 与官网四页（docs / wiki / index / gallery）共约 160 处示例全部迁移至新命名空间 API。 ### 新增功能与优化 - **即时模式工程图表套件 (`Plot` & `BarChart`)**： - `UIContext::plot`：支持折线（`Line`）、散点（`Scatter`）、面积（`Area`）多系列同图混排，支持边界自适应计算、网格细分刻度线、双轴数值标签、准心十字光标与数据浮窗。 - `UIContext::bar_chart`：支持自适应柱条宽度与间隙计算、分类轴标签、悬停高亮色彩反馈与数值胶囊指示器。 - **数值微调器 (`DragValue`) 键盘流转与步进导航**： - 支持获得焦点时的方向键（ArrowLeft/Down 减少，ArrowRight/Up 增加）微调控制。 - 支持快捷倍率：按住 Shift 实现 0.1x 精细步进，按住 Ctrl 实现 10x 快速步进。 - 支持显式高对比焦点光环（`@color.Color::border_focus()`）。 - **控件几何与尺寸设计令牌规范化**： - 全面规范化 `WidgetStyle` 几何维度，引入进度条、气泡提示、标题栏、下拉框、折叠面板、标签栏、数值微调、调色盘、面包屑及图表的一级样式字段。 - 在 `@color.Color` 中引入语义令牌 `Color::grid_line()`、`Color::guideline_wash()` 与 `Color::plot_crosshair()`。 - **垂直通道推子调节器 (`Fader` & `FaderInt`)**： - 新增 `UIContext::fader` 与 `UIContext::fader_int`，专用于音频调音台与连续参数控制。 - 支持下陷导轨背景、双侧物理刻度线标尺、中心荧光指示线推子帽、垂直鼠标拖拽、滚轮微调、Shift（0.1x）/ Ctrl（10x）倍率修饰、键盘方向键/Home/End 导航与 Alt+Click 复位。 - 补充设计令牌 `Color::fader_track_bg()`、`Color::fader_tick()`、`Color::fader_cap_line()` 及 `WidgetStyle` 字段 `fader_w`、`fader_h`、`fader_track_w`、`fader_cap_w`、`fader_cap_h`、`fader_cap_radius`。 - **底层图元文本字体与字重元数据补全 (`BUG-DRAW-03`)**： - 在 `DrawCmd::Text` 与 `DrawList::add_text` 中增加字体族名 (`font_family`) 与字重 (`font_weight`) 字段。 - 支持 `RichText` 粗体真实应用 700 字重，支持 `CodeEditor` 声明等宽字体族名。 - 更新 Web 渲染驱动（`gallery_runner.js` 与 `run.js`），支持动态装配与 LRU 字体缓存。 - **自动化测试套件扩展**：新增 `Fader` 完整白盒单元测试，使无头白盒与黑盒自动化测试总数增至 221 项（100% 通过率）。 - **分层包结构重构 (`ARCH-06`)**： - 依据 `ARCH-06` 将原 59 文件的 `src/core` 单体包拆分为 `src/core`（纯即时模式运行时）、`src/widgets`（标准控件）与 `src/composite`（高级组件）三层物理包，依赖方向严格单向：`math -> color -> draw -> core -> widgets -> composite -> src`。 - `src/core` 仅保留引擎运行时（`context`、`id`、`input`、`memory`、`layout_engine`、`focus_manager`、`window_manager`、`layer_manager`、`painter`、`theme`、`response`、`unicode`、`widget`、`text_layout`）。 - 跨包契约：控件以 `@core.Widget` 实现并经由 `ctx.add(...)` 派发，调用方使用 `@widgets.*` / `@composite.*` 命名空间函数；`WidgetStyle` 等只读结构体通过 `WidgetStyle::scaled(factor)` 等流式构建器派生，而非跨包结构体更新语法。 - `src/lib.mbt` 作为总门面重导出全部公开类型，并通过 `pub using @core { trait Widget }` 转出引擎 trait。 --- ## [0.2.0] - 2026-09-12 ### 新增功能与优化 - **全自宿主 Pure Canvas Studio 工作台 (`gallery.html`)**：将组件展厅完全迁移至画布内即时模式工作台，内置分段主题切换（`studio_light` 白瓷、`slate_dark` 岩灰、`high_contrast` 高对比）、50/50 可拖拽分栏幕布（`split_horizontal`）、行号代码查看器（`code_editor`），以及覆盖 32 个组件的示例源码库。 - **输入无障碍与多指针引擎升级**：在 `RawInput` 中新增次级指针（鼠标右键）支持；实现贯穿全量交互控件的完整 Tab 焦点循环导航链；支持 Space/Enter 键盘激活与高对比焦点描边光环；新增帧事件消费机制（`consume_key`）。 - **排版与字素簇遍历引擎**：在 `rich_text.mbt` 中实现 CJK 汉字自动折行与标点避头尾换行规则；支持原子化 UTF-16 代理对字素边界双向导航（`prev_char_boundary`、`next_char_boundary`）；引入 LRU 排版度量缓存；新增浏览器原生隐藏式 IME 输入法 `