# Ebox

Ebox 是一个独立的 Emacs Text/Box 布局引擎，负责文本测量、Box 几何、
row/column/flex/Grid 布局、retained 渲染和增量 buffer 发布。应用还需要
Component、响应式状态、behavior 或生命周期时，使用同级 ETAF 包。

## 安装

源码仓库为 [geekinney/ebox](https://gitea.gklazycat.heiyu.space/geekinney/ebox)。
当前 `3.0.0` 更新日志仍标记为未发布；源码 checkout 不代表已经发布的包归档或稳定版本 tag。

| 依赖 | 使用条件 |
| --- | --- |
| Emacs 29.1 或更高版本 | 所有 Ebox 使用场景。 |
| ECSS 0.1.0 或更高版本 | 样式计算和选择器语义；即使不使用样式表也需要。 |
| TP 2.0.0 或更高版本 | retained 发布、原生属性策略与事务；加载 Ebox 时需要。 |
| [EKP 1.0.0 或更高版本](https://github.com/Kinneyzhang/emacs-kp) | 可选，仅使用 `:wrap-mode kp` 时需要。 |

ECSS 与 TP 是包声明的必需依赖。EKP 保持可选，普通 `word`、`char`、`none` 换行不需要它。
使用同级源码 checkout 时，把必需的目录加入 `load-path` 后加载 Ebox：

```elisp
(add-to-list 'load-path "/path/to/ecss")
(add-to-list 'load-path "/path/to/tp")
(add-to-list 'load-path "/path/to/ebox")
(require 'ebox)
```

加载 Ebox 不会创建 buffer，也不会构建 native 模块。

使用 Knuth–Plass 段落排版时，先额外将 EKP 源码目录加入 `load-path`，或安装它的包，
然后在 Box 上设置 `:wrap-mode kp`：

```elisp
(add-to-list 'load-path "/path/to/ekp")
(ebox-render
 (ebox-build '(box :width (ch 40) :wrap-mode kp :overflow hidden
                   "A paragraph laid out with Knuth–Plass line breaking.")))
```

Ebox 在使用该换行模式时加载 EKP。EKP 缺失或不兼容时会提示安装或更新；请安装 EKP，
或显式选择其他换行模式。Ebox 不会静默改用 `word`。EKP 自己的可选加速器与
Ebox 的可选 Rust 模块是两回事。

### 构建并验证可安装归档

在本仓库中运行：

```sh
make release-check EMACS=emacs RELEASE_DIR=/tmp/ebox-release-3.0.0
```

该入口按 [`release-dependencies.json`](release-dependencies.json) 获取精确的依赖提交，
构建可重复的 `package.el` 源码归档，在临时干净配置中安装并验证渲染、更新和选择器。
归档目录与 `manifest.json` 会保留，其中记录校验和、源码提交及工作区是否有修改；
它不会发布归档或修改你的 Emacs 配置。每次使用新的输出目录，不覆盖已有目录。

需要同时包含并测试可选 KP 排版时，换一个输出目录并加上 `RELEASE_OPTIONS=--with-ekp`。
归档验证通过后，可以作为本地包归档安装：

```elisp
(require 'package)
(add-to-list 'package-archives '("ebox-local" . "/tmp/ebox-release-3.0.0/"))
(package-refresh-contents)
(package-install 'ebox)
;; 可选，仅当归档构建时使用了 --with-ekp：
;; (package-install 'ekp)
```

工具输入、清理、离线复用与 native 验证见
[维护者指南](docs/maintainer/ebox-current-implementation-reference.zh.md#源码包分发)。

## 第一次渲染

普通用户只需理解七个 author 入口：字符串、`text`、`box`、`row`、`column`、
`flex` 和 `grid`。子节点直接嵌套，不存在第二套 field-based child 语法。

```elisp
(require 'ebox)

(ebox-render-to-buffer
 "*Ebox Example*"
 (ebox-build
  '(column :padding ((lh 1) (ch 2))
           :border ((px 1) solid "#8A93A6")
           (text :color "#263244" "Hello Ebox")
           (row :item-gap (ch 1)
                (box "Left")
                (box "Right")))))
```

普通 author DSL 统一通过 `ebox-build`。框架集成可以用一个
`ebox-source-builder` 组合 typed node，再把 forest 与同一代 source facts 封装为一个
`CanonicalEboxInput`；这个 evaluated API 不是第二套 author 语法。

已求值的 Box 构造包含 `ebox-child-range` 时，通过 `:source-builder`
显式传入开放的 builder。它必须拥有 Box 及所有直接子节点的 source handle；
空 Range 同样需要开放的 builder。builder 只参与构造，不保留在节点中。
组合已有 canonical input 时，使用 `ebox-canonical-input-roots` 与
`ebox-canonical-input-import-roots`，框架不应读取私有字段或绑定私有动态上下文。

## 如何选择布局

- `box` 创建普通视觉盒子；
- `row` 和 `column` 用于简单的一维组合；
- `flex` 用于空间分配和换行；
- `grid` 用于二维轨道与放置；
- 裸字符串是 `(text "...")` 的简写。

Flex/Grid participation property 直接属于子 `box`，不需要额外 wrapper 节点。

Box 几何统一写成 `(单位 数值)`，支持 `px`、`%`、`vw`、`vh`、`ch`、`lh`。
例如 `:width (ch 80)` 表示 80 个 `0` 字形的前进宽度，
`:height (calc (- (vh 100) (lh 1)))` 表示视口高度减一个行高。
`calc`、`min`、`max`、`clamp` 在布局时组合长度；`auto`、裸 `fit-content` 等
尺寸关键词仍直接写符号。旧的裸长度、单元素像素列表和视口关键词会报错。
构造时按属性方向检查单位，包括尺寸函数的所有分支。允许的组合、关键词默认值、
百分比参照及纵向行粒度限制见[统一单位约束表](docs/user/ebox-user-guide.zh.md#size-unit-constraints)。
空 Box 的自动内容高度为零；需要一行空白时写 `(box :height (lh 1))`。

## 原生交互

Text 与所有 Box form 都接受四种显式节点能力：`:help-echo` 提供字符串或原生帮助
函数，`:pointer` 选择原生鼠标指针形状，`:hover-style` 设置受限的颜色与文本装饰
绘制，`:keymap` 接收原生 Emacs keymap。Box 的帮助、指针和 keymap 范围包含内容、
padding 和 border，不包含该 Box 的 margin 和结构性换行符。悬停在文字与 padding
间共享声明节点的绘制，不包含物理左右边框。嵌套节点的显式值覆盖外层能力；
显式 `nil` 清除对应能力。

使用 `ebox-help-create` 将零参数业务函数适配为原生帮助，并提供悬停 buffer 上下文。
使用 `ebox-keymap-create` 将普通零参数回调绑定到激活键或自定义按键；鼠标命令会
自动在被点击窗口的 buffer 中运行。`ebox-region-update` 可以使用当前已挂载 buffer
中的语义 ID，或显式 region handle，替换或清除节点能力。原生 keymap 可用于
独立的 Ebox 交互；可选的 `ebox-next-interaction`、`ebox-previous-interaction` 命令
在渲染后的 keymap owner 之间移动 point，不添加默认按键绑定。应用状态与命令行为
由作者管理。参见
[交互指南](docs/user/ebox-user-guide.zh.md#native-node-interaction)和 Playground 的
[交互实验室](../ebox-playground/README.zh-CN.md#native-interaction-lab)。

## 渲染与更新

- `ebox-render` 返回带属性文本，不发布 live buffer；
- `ebox-render-to-buffer` 挂载 retained surface；
- `ebox-display-buffer` 先完成渲染，再按 Emacs 显示规则与可选 action 显示结果，返回 buffer；
- `ebox-commit` 原子发布重新构建的 canonical input；
- `ebox-buffer-update-report` 返回最近一次成功更新报告；
- `ebox-rerender-buffer-with-context` 应用显式 viewport 变化。
- `ebox-surface-buffer-snapshot` 显式导出当前提交的 `:input`、`:revision`
  与 `:mount-id`，以一个 plist 返回。

Ebox 会在分配 runtime identity 前复制 canonical input，因此同一个 built value 可以
挂载到多个 buffer，而不会共享 live ownership。

快照只在显式查询时遍历导出数据和 TP 最近的诊断报告，普通更新不会创建快照。其 canonical input 在后续
更新、卸载后仍可使用；节点中的可变数据与交互 keymap 独立复制，不可变 source facts
与不透明能力（回调、record）保留身份。快照不冻结显示环境或外部能力。TP 事务期间、
卸载后查询会报错。识别提交版本时同时比较 mount ID 与 revision，避免重新挂载后
revision 从头计数导致混淆。

Ebox 只通过 TP 2.0.0 的公开 structured participant API 与最终 v2 协议注册可回滚状态。
旧的过渡版本不具备本版本要求的原生属性所有权与 hover identity 保证。structured
participant capability 缺失或格式错误时，Ebox 会停止加载，不会选择兼容 writer。

## 可选 native 模块

Rust 模块只加速符合条件的 reflow；它不是正确性的依赖，并有完全等价的 Elisp
fallback。Ebox 加载时不会自动构建它。

```elisp
(ebox-native-status)
(ebox-native-build)
```

## 显示与文本边界

每个已挂载 buffer 只有一套视口布局。同一个 buffer 同时出现在不同宽度的两个窗口中，
不会产生两套独立布局。需要各自宽度时，分别挂载到不同 buffer；同一份 canonical input
可以挂载多次。

纵向几何按完整行生成。文本处理保留常见组合音标、变体选择符、Emoji 修饰符、ZWJ 与
旗帜序列，但不实现完整 Unicode 字素分段，也不承诺浏览器级字体排版和双向布局。
可用字体、原生指针和帮助显示由 Emacs 与窗口系统决定；终端输出无法复现全部 GUI
像素或指针效果。

`:overflow hidden` 将内容限制在盒子测量后的宽度与完整行高度内，保留自身 padding 和
边框。横向裁剪保留完整的受支持文本簇，用空白补齐剩余像素，不显示半个字形，也不
添加省略号。`scroll` 仍是纵向滚动。

CI 配置覆盖 Linux 上的 Emacs 29.1、30.2，以及 Linux、macOS、Windows 上使用
Emacs 30.2 的源码包安装和 native 模块加载、执行。这些任务定义验证矩阵，不代表
所有平台的 GUI 渲染都已做视觉实测；请查看待安装提交对应的 workflow 结果。

## 验证

```sh
make load EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs
make compile EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs
make docs-contract-tests EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs
make interaction-tests EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs
make c1b-contract-tests EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs
make check EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs
make native-rust-tests
```

继续阅读[用户指南](docs/user/ebox-user-guide.zh.md)、[公共 API
参考](docs/user/ebox-api-reference.zh.md)，以及同级
[ebox-playground](../ebox-playground/README.md) 示例。

## 许可证

Ebox 自有代码按 GPL-3.0-or-later 分发，详见 [LICENSE](LICENSE)。第三方文件保留各自的
许可证声明。