@fulate/tools 1.0.0

package/README.md

@@ -0,0 +1,356 @@
+# @fulate/tools Editor integration
+
+> 文档角色：`GUIDE`。权威来源：Tools 源码 TSDoc 与测试；Editor 的跨域长期契约见 [`docs/specs/editor-interaction.md`](../../docs/specs/editor-interaction.md)。
+
+每个活动 Root 只有一个 `EditorInteractionController`。它拥有 selection、输入仲裁、Transform/Point
+gesture、Content session、Line/LineTree branch draft 与 semantic History 边界；`Select` 只保留 command/paint
+surface，`LineTool` 只保留 command/preview surface。Transform 的每个已派发 pointer 输入都立即从
+frozen baseline 解析并提交一个 trusted batch；Point gesture 继续只在每个显示帧消费最后一个 intent。
+每个 owner 都把 world delta 交给同一个 Core reference-transform kernel；普通 transform 与显式
+reparent intent由该 intent决定写 pose、resize-owned geometry或preserve-owned geometry。Group手势只写
+Group，DirectChild手势只写该child；derived content bounds不形成command、History或补偿写入。
+Line/LineTree固定world paint padding只属于自身visual/render coverage，不进入Group selection、resize或
+snap bounds。所有工作复用现有`RootFrameRuntime`，Tools 不创建 RAF、timer 或第二 scheduler。
+`Select`、`Snap`、`Rule` 与 `LineTool` 都使用 Core 生成的普通 Node key。工具间协作由应用组合时交付
+的对象引用完成，不把固定 key 当作 Root 服务定位：
+
+```ts
+const snap = new Snap();
+const lineTool = new LineTool({ contentLayer });
+const select = new Select({ snap, lineTool });
+const rule = new Rule({ select });
+const editorLayer = new EditorLayer({
+  children: [select, snap, rule, lineTool]
+});
+```
+
+DirectChild开始axis Snap时，手势排除集按候选使用的同一selection-owner规则解析；包含该child的
+ancestor Group不会成为自身拖拽候选，Group外部元素仍正常参与对齐。
+
+LineTree Point改变一个anchor时，即使当前pose包含resize或反向scale，也在同一owner change内保持
+既有world matrix，未编辑points不发生位移；整树resize继续走O(1) pose路径。Group默认旋转中心与九点
+pivot吸附按当前local visual/content selection bounds解析；稳定layout reference只拥有Group pose。
+
+Selection controls 是一份 immutable `SelectionOverlayProjection`。paint、control/body hit 与 cursor
+仲裁读取同一对象；场景内容 hit/hover 仍由 Core `Root.hoverPath/currentElement` 唯一拥有。Tools 不写
+DOM cursor，不保存 `currentControl`、`hoverElement` 或第二份 selection frame。
+单选与多选的每个 selected owner 都由这份投影调用其唯一 `paintHover()` 绘制本体高亮，不依赖鼠标
+是否仍停留在图元上。
+`Rule` 也直接消费这份投影：它把当前单选或多选 frame 的 world AABB 在水平、垂直标尺上各绘制
+为一段区间，并标出两端坐标。尺寸、背景、角块、主/次刻度、边框、文字与选区颜色都可以在构造时
+配置，并可在挂载后通过一次 `setOptions()` 更新；实际变化只登记一次 Editor overlay 重绘，相同值为
+noop。主刻度与次刻度分别绘制。省略 `selectionColor` 时每次绘制读取当前
+`root.skin.selection`，自动跟随 Select 外框：
+
+```ts
+const rule = new Rule({
+  select,
+  rulerSize: 50,
+  backgroundColor: "#000000",
+  cornerBackgroundColor: "#0f0f0f",
+  majorTickColor: "#3f3f3f",
+  minorTickColor: "#3f3f3f",
+  borderColor: "#252525",
+  textColor: "#cccccc"
+});
+
+rule.setOptions({ rulerSize: 40, textColor: "#ffffff" });
+```
+
+Rule 是覆盖在 Root 顶部和左侧的 screen-space 编辑器层，不会平移 Viewport。活动 Rule 会把当前
+标尺占用提供给同一 Root；Workspace 在初始几何提交后、首个Canvas paint前执行首次无动画聚焦，
+Root尺寸变化后按最终尺寸执行一次无动画聚焦。两条路径都会读取标尺占用，并从可见区域的顶部和
+左侧扣除标尺尺寸：
+
+```ts
+const rule = new Rule({ select, rulerSize: 40 });
+const workspace = new Workspace({
+  width: 1920,
+  height: 1080
+});
+```
+
+这项组合信息只参与 Workspace 的首次与尺寸变化自动聚焦，不进入场景属性、History 或序列化结果。
+
+这些配置只属于 `EditorLayer` 中的 Rule，不进入 Scene History 或 FileData。移动、缩放、旋转、选择
+清空/重入与 viewport 变化随唯一 Root frame 更新；Rule 不重新遍历 selected elements、查询它们的
+geometry 或保存独立 range/resolved-color 状态。
+Ctrl/Meta拖拽是additive marquee：pointerup只执行一次visual area query，并且只有visual bounds被框完整
+包围的最终selection owner会加入结果；只包住Group内部child不会选中整个Group。普通无修饰marquee保留
+真实轮廓相交语义。marquee候选遵守`visible/selectable`且不受`silent`取值影响，`true/false`都可框选；
+`silent`仍阻止pointer target。pointermove期间只有ephemeral rectangle，零area query、owner write和History。
+
+Group dive每次只选择当前Group scope内命中的DirectChild。下钻后，若下一次raw content hit仍在当前
+单选owner分支内，无位移点击保持该owner，使连续双击可以继续进入更深Group、Text Content或当前已有的
+LineTree Point；点击该分支外的内容仍按普通selection owner规则解析，可以重新选中ancestor Group。
+这一交接只使用当前selection和raw ancestry，不保存第二份Group scope状态。
+
+`Select.arrange()`接受公开枚举`ArrangeType`：
+
+```ts
+import { ArrangeType } from "@fulate/tools";
+
+select.arrange(ArrangeType.LayerUp);
+select.arrange(ArrangeType.LayerDown);
+select.arrange(ArrangeType.Forward);
+select.arrange(ArrangeType.Backward);
+select.arrange(ArrangeType.Top);
+select.arrange(ArrangeType.Bottom);
+```
+
+Layer默认不参与排列；应用创建内容Layer时必须显式设置`elementArrangementEnabled: true`。
+跨Layer移动按当前`Root.layers`绘制顺序寻找相邻的已启用Layer，跳过未启用Layer；上移进入目标Layer
+的children开头，下移进入末尾，并通过既有reparent Transform writer保持world pose。
+`ArrangeType.Forward`/`ArrangeType.Backward`不读取Layer顺序，只让各元素直接parent内的selected
+sibling块移动一步；`ArrangeType.Top`/`ArrangeType.Bottom`同样只在直接parent内把selected siblings
+稳定移动到children末尾/开头。四种父级内操作均不拆Group或跨parent。一次有效命令只提交一个trusted
+batch和一个semantic History entry；边界noop为零batch/History。
+
+`Select.setProperties()` 把同一份 authored 顶层属性补丁应用到当前全部选中元素：
+
+```ts
+select.setProperties({
+  backgroundColor: "#ff0000",
+  opacity: 0.8
+});
+```
+
+面板需要具体元素字段检查时，可让该对象 `satisfies ShapeOptionPatch` 或自定义元素自己的 patch 类型，
+`setProperties()` 本身保持对第三方 authored 字段开放。
+
+省略字段保持不变，`undefined` 恢复该字段默认值，`null` 是属性自身的普通领域值。不做deep merge或
+deep patch；命令把同一份完整patch引用直接交给每个selected element。结构化字段按引用作为
+whole-value replacement；同一引用是普通noop，调用者需要独立副本时在交付前自行复制。标量相同值
+仍是noop。Tools不按元素类型过滤字段，
+属性面板负责只展示当前selection可编辑的属性。空selection不结束其他活动交互；非空selection
+先完成已经接受的交互，再从 live selection 以一次 trusted batch 提交，最多形成一条 History。
+`setProperties()` 不改变 selection，也不派发 `select:end`；影响 visual geometry 的属性可在稳定后触发
+既有 `select:update` 通知，纯 paint 属性不会触发该几何事件。只要最终 configured 值有净变化，命令就在
+History 安装后排队一次 `select:configured-change` 通知；标量 noop 不派发。表示 world 有效尺寸或位置的
+width/height/x/y 仍使用 `Select.resize()` 或其他 Transform 命令，不能用普通 authored patch 绕过
+父级矩阵反算。
+
+`Select.resize()` 是属性面板使用的公开尺寸命令：
+
+```ts
+const bounds = element.transform.getWorldVisualBoundsView();
+select.resize({
+  width: bounds.width * 0.8,
+  height: bounds.height * 0.8,
+  anchor: "top-left"
+});
+```
+
+`width` 或 `height` 省略时保持该轴当前的 selection frame 尺寸；对 `Text`，selection frame
+始终读取 authored/layout box，即使 `overflow="visible"` 且未换行的 glyph 超出该 box；`anchor` 省略等于
+`"top-left"`，支持九个 frame 固定点：`top-left`/`top`/`top-right`/`left`/`center`/`right`/
+`bottom-left`/`bottom`/`bottom-right`。这些值是 world logical 单位，不包含 Viewport 缩放；
+controller 会自动处理父级和多层 Group 变换，并通过同一个 trusted batch 和 History 记录。选中
+Group 时只改 Group pose/scale，不改写直接子元素的 authored width/height。
+
+`Select.flip()` 是同一 Transform 命令链上的镜像操作：
+
+```ts
+select.flip("horizontal");
+select.flip("vertical");
+```
+
+镜像轴经过当前 selection frame 中心。单选旋转元素沿其 frame 自身水平/垂直轴镜像；多选的
+aggregate frame 为 world 轴对齐，因此沿 world 水平/垂直轴镜像。命令遵守 selection 的 resize 轴
+策略，使用同一批 selected owner baseline、trusted batch 与 semantic History；选中 Group 时只写
+Group pose/scale，不 bake children authored geometry。空选择或被策略禁止的方向是普通 noop。
+
+## Keyboard、Clipboard 与应用命令 owner
+
+每个活动 Root 由当前 `EditorInteractionController` 安装一个 DOM `keydown` listener。应用若要接管
+`Ctrl/Meta+C`、`Ctrl/Meta+X`、`Ctrl/Meta+V`、`Delete` 或 `Backspace`，只绑定一个命令 owner：
+
+```ts
+const unbind = select.bindKeyboardCommands({
+  copy: () => select.copy(),
+  cut: () => {
+    select.copy();
+    select.delete();
+  },
+  paste: () => select.paste({ resolveParent, afterInstall }),
+  delete: () => select.delete(afterDelete)
+});
+```
+
+再次绑定直接替换当前引用；`unbind` 只会清除仍属于它的绑定。Controller 保留平台修饰键、form/Content
+排除、活动 gesture gate 与 `preventDefault()` 时机；未绑定或 gate 拒绝时不消费元素级按键，未绑定应用
+owner 时 Point target 仍由现有 Point owner 处理。Fulate 不提供额外的
+单键复制快捷键或独立 cut API；应用的 cut 只在上层按 Copy 后 Delete 编排。
+
+Clipboard v2 的唯一 payload 是 `elements`、`parentKeys` 和透明 `applicationData`。`select.copy(producer)`
+在不改 Canvas/selection/History 的前提下最多同步调用一次 producer，并把完整 source subtree keys 交给
+`CopyContext`。`select.paste(options)` 在 clone、parent placement 和新 selection 安装后、Root drain 与
+History finish 前调用 `afterInstall({ applicationData, keyMap, history })`；`keyMap` 是 clone codec 一次生成的
+完整旧/新 key 映射。应用 owner 先完成自己的首次 create/delete，再用 `history.record()` 登记 undo/redo，
+不调用首次 change 的 `redo()`。History 关闭时 hook 的 `history` 为 `undefined`，Canvas 操作仍照常执行。
+
+`PasteParentResolver` 对每个非 Layer 顶层副本调用一次；Fulate 先按 `parentKeys` 解析当前 live source
+parent，未提供 resolver 时只有 source parent 不存在才使用 Root 第一个 Layer。副本自身为 Layer 时直接放入
+当前 Root。`select.delete(afterInstall)` 在真实 Canvas 删除闭包安装后、drain/finish 前交付完整
+`DeleteContext`；Point 删除不调用该 hook。System Clipboard 读失败时使用同一 memory payload，不读取旧格式，
+不做版本协商或迁移。
+
+异步 paste 在 Clipboard 读取前捕获当前 controller、selection owner、interaction state 与本次 Promise
+引用。Clipboard 返回后，只要 controller 生命周期仍有效，合法文档就正常提交并形成实际 History；
+只有这些 selection/interaction/task 引用仍共同证明本次 paste 拥有选择意图时，才把 selection 改为新
+元素。等待期间建立的新选择或手势保持当前，旧 paste 不结束它也不派发虚假的 `select:end`；两个 paste
+倒序完成时两次文档提交都保留，较新的 paste 意图拥有最终 selection。
+
+属性面板应同时监听 selection 完成和已选几何更新：
+
+```ts
+function syncPanel() {
+  const element = select.selectedElements[0];
+  if (!element) return;
+  const { left, top, width, height } =
+    element.transform.getWorldVisualBoundsView();
+  updatePanel({ x: left, y: top, width, height });
+}
+
+const stopSelection = select.addEventListener("select:end", syncPanel);
+const stopGeometry = select.addEventListener("select:update", syncPanel);
+```
+
+场景持久化只监听 configured 语义完成事件：
+
+```ts
+const stopPersistence = select.addEventListener(
+  "select:configured-change",
+  () => saveToIndexedDB(serializeScene(root))
+);
+```
+
+`select:configured-change` 不携带 payload。一次 Transform/Point/Content/Line、`setProperties()`、
+resize/flip、align、group/ungroup、delete、copy/paste 或 History replay，只要最终 configured
+属性或结构确有净变化，就在最终状态和适用的唯一 History entry/stack 安装后排队恰好一次通知；连续手势中的
+多个内部 batch 不逐批派发，最终回到起点的净空操作也不派发。`setRuntimeOptions()` 与
+`clearRuntimeOptions()` 只改变 runtime override，因此不派发。选择、marquee、copy 等不写 configured
+状态的操作同样不派发。
+
+`select:update` 只在 `Select` 自身存在该事件的直接监听器时登记；没有监听器时 pending completion 和
+事件派发均为 0。它在当前 Root 的 geometry、spatial、selection projection、paint、hover 与既有
+`transformUpdated` completion 完成后同步派发，不携带 bounds 副本；监听器直接读取 live selection。
+同一显示帧内连续 move/resize/rotate/Point 或外部 selected geometry 变化合并为一次通知。监听器在
+completion 中再次写入时，新变化进入下一轮稳定后再通知。Viewport zoom 不改变 world logical bounds，
+因此不会单独触发该事件。对同步 `resize()/flip()` 命令，顺序是 frame稳定及`transformUpdated` phase
+→ `select:update` → History finish → 排队 `select:configured-change` → 排队 `select:end`；
+这些通知在同步命令返回后按同一顺序执行。
+`getWorldVisualBoundsView()` 是当前帧的 borrowed view，不应跨帧保存对象引用。`setProperties()` 若改变
+几何，则同样先稳定并同步派发`select:update`、再完成 History 与排队`select:configured-change`，但不派发
+`select:end`；纯paint patch按 batch → History → 排队 `select:configured-change` 完成。
+
+Transform、Point、`setProperties()`、align、group/ungroup、delete、copy/paste 与 Text editing
+都把最终 typed owner/structure effects 交给同一 trusted batch。`setProperties()`复用同一输入引用，
+Core batch不复制。History只在semantic scope完成时保存actual changed
+fields/placements 的 earliest-before/final-after，以及外部 owner 通过`HistoryScope.record()`登记的
+最小`HistoryChange`。`record()`只登记已经正常执行的change，不调用其`undo()`/`redo()`。History 关闭时
+不创建 History entry、完整
+Properties/tree snapshot、receipt 或结构化副本；仅当直接订阅`select:configured-change`时，semantic
+scope用已交付的actual before和最终live引用判断净变化。undo/redo把history-owned typed delta重新交给
+同一batch，并在Canvas安装后、drain前调用外部change的`undo()`/`redo()`；drain后恢复selection并转移
+History stack。回放是线性、非重入操作；当前 `undo()`/`redo()` 返回前，不得再次调用同一 manager 的
+`undo()`、`redo()`、`clear()`或`push()`，外部 `HistoryChange` 只恢复自己拥有的数据。只有Canvas
+configured存在实际变化时才先派发
+`select:configured-change`，再依次排队`select:end`与`select:undo`/`select:redo`；这些通知在 replay
+返回后按同一顺序执行。
+
+应用层可以在 Paste 的 Canvas 节点和新 selection 安装后、同一 semantic scope 尚未 finish 时补齐自己的 authored owner：
+
+```ts
+select.paste({
+  afterInstall: ({ applicationData, keyMap, history }) => {
+    const created = dataDocument.createDefinitions(applicationData, keyMap);
+    if (!history || created.length === 0) return;
+    history.record({
+      undo: () => dataDocument.removeDefinitions(created),
+      redo: () => dataDocument.restoreDefinitions(created)
+    });
+  }
+});
+```
+
+hook运行时Canvas副本和新selection已经安装，但frame drain、History finish与最终事件尚未发生。
+`history`在History关闭时为`undefined`，调用方因此不创建回放对象。首次Data提交由其owner正常完成，
+不能通过调用`redo()`代替。Canvas与Data最终只形成一条entry；Data-only entry同样可undo/redo，但不会把
+`HistoryScope.finish()`的返回值变成`true`，也不会单独触发`select:configured-change`。
+
+`select:end`是selection-producing操作的异步完成通知，不是通用Transform更新事件，也不是持久化
+合同：显式`select()`、点击/框选、selection-producing command与History replay都先结束旧交互、安装
+最终selection并完成当前selection projection；command还会先完成History及适用的
+`select:configured-change`。
+外部scene removal引起的selection修复复用唯一Root frame的completion phase，在geometry、spatial、
+overlay、RBush、paint与hit完成后排队通知。每次显式`select()`都独立完成并排队通知，包括再次传入同一个数组；
+不按数组内容或引用过滤。删除固定为structure/selection → drain → History →
+`select:configured-change` → hit refresh → 返回；完成通知只在返回后按顺序执行。Delete 不再派发
+专用 Delete 完成事件；应用需要在删除闭包安装后登记外部 owner 时使用 `afterInstall`。
+所有 Select 完成通知都只读取派发时的 live state，不参与、阻止或使已完成的内部操作失败；listener
+异常在异步通知任务中自然传播。
+
+公开`doGroup()`/`unGroup()`支持活动Transform中的程序化调用：先保留并结束已经接受的Transform，随后
+把group/ungroup记录为独立History命令；结构变化后旧pointer continuation失效，下一次真实Transform从
+live selection开始。明显不足的selection或非Group选择在`drain()`前直接noop；有效候选才drain，并在
+该可覆写边界返回后重新读取live selection。
+
+Line、LineTree、Polygon与VectorPath普通选择都只投影Transform frame，Point capability、controls、paint
+和hit为0；双击当前单选owner后才进入唯一显式Point state。进入后隐藏Transform外框和信息面板，只显示
+当前owner/scope轮廓与Point controls。Line、Polygon与VectorPath使用owner scope，
+LineTree只请求active branch scope。四类owner都从live canonical topology投影稳定`anchorId/segmentId`；
+VectorPath的cubic handle只用`segmentId + cubic-control-1|cubic-control-2`，与anchor/segment共用同一flat
+projection和gesture。所有Point control使用同一外径：anchor是实心圆，segment midpoint是菱形，cubic
+handle是由细线连接anchor的空心圆；guide只绘制、不命中。handle可自由移动、不可删除、不是endpoint，也不触发Port probe。Line保持open
+line-only；Polygon保持closed contour且至少三个anchors；VectorPath保留各subpath的open/closed状态并只
+编辑当前line/cubic记录。move、midpoint insert-and-drag、handle move与anchor delete/merge都不持久化
+authored array index，未受影响的records与IDs保持引用。负缩放Line拖点时同一owner change保持world pose和
+未编辑anchors稳定。
+
+Point control点击后会保持stable Delete target，移开鼠标再按Delete/Backspace仍处理该target；只有可删除
+anchor显示active删除反馈。不可删除或已失效target不显示该反馈，Delete是已处理noop，不会误删整个element。
+只有没有active/hover target时，
+LineTree active child branch通过capability产生一个topology change并进入parent scope；root branch以及
+owner-scope adopter返回`null`，随后复用普通Select element delete。dispatch不读取LineTree私有topology。
+
+LineTree按L直接把active branch tail视为已点击并进入draft；同一junction tail可以反复产生sibling
+branches。Transform状态下当前pointer已在tail时第一次L
+直达，否则进入只命中branch tail的source-pick，第二次L或click均可确认；树干segment和中间anchor
+不可作为source。keydown只消费Core唯一hover/cursor链已经解析的当前pointer来确认source，下一次真实
+pointermove才开始preview。source-pick或未提交branch-draw中双击真实branch会先取消当前session并进入
+该branch Point，随后L从active tail正常开始，不保留重叠状态。自由终点已经确认后Escape/Enter会像普通Line drawing一样提交，不会丢弃整段。draft确认前
+零document write；确认只安装一个最终topology change。`LineTool`的`resultType`与`tailDecoration`
+在drawing session开始时读取一次；`resultType`省略为`line`，也可创建单branch `lineTree`；
+`tailDecoration`省略为`arrow`，传`none`时新Line、LineTree root及新branch均不带尾装饰。
+
+LineTree Point/add/remove branch History只保存actual changed point/branch records；不深拷贝完整topology。
+source-pick、branch scope切换和取消都不创建History或cleanup batch。
+Standalone Line和LineTree都是EndpointRelation的source owner，不进入普通Port target索引；空白按L新建
+结果时不会为零frame LineTree投影默认Ports。Root默认关闭Port；只有显式`enablePorts: true`且元素
+自身显式配置`ports: true`或custom数组时，Ports才进入Root-scoped增量`PortIndex`和连接picker。未开启时LineTool不启动Port picker，
+Line和LineTree仍可正常绘制、编辑与选择，Point/Transform继续复用同一个Snap执行普通axis对齐。
+按L进入LineTool或开始endpoint连接手势时，picker立即显示当前Viewport内所有已声明且可作为pointer
+target的Port，不需要鼠标先接近或命中元素。鼠标进入固定10屏幕像素半径后，只把最近且同距时paint
+order最上层的一项设为active并用于吸附；离开半径只取消active，其他Port继续显示。取消或结束session
+才清空全部marker。marker不绘制owner矩形轮廓，也不写authored state或History。
+
+`Select`的`connectionGesture`只有`"auto" | false | callback`三种值。auto在pointerup把最终relation
+合入当前semantic History；callback在交互完全结束后只发布stable source/target refs和新的同步
+`connect()`命令，回调本身不写relation也不创建Connection History；false不探测Port。普通Point的
+pointercancel、Escape、selection switch与teardown会消费已经排队的latest accepted intent；endpoint派生的
+Port手势才丢弃尚未消费的intent/candidate、停止picker且不连接/回调。两者下一次手势都从当前live
+authored state重入，已正常安装的Point变化不回滚。
+启用Port手势时，Line/LineTree首端只接受`output | both`，尾端只接受`input | both`；方向不兼容或
+容量已满的候选只显示阻止反馈，不确认Line/branch point，也不提交endpoint移动。离开Port命中范围后
+仍可确认普通自由点。Port ownership只来自元素自身的`ports`；未声明的Text、Button或内部装饰默认
+没有Port。`PortIndex`再按当前Root的pointer-target语义过滤owner；`silent`和`pickable`只决定指针
+资格，不启用Port，也不改写authored配置。
+
+Clipboard copy 先同步生成独立 memory snapshot；系统 clipboard 是不阻塞 authored command 的
+best-effort 边界。paste 为 element 生成新 key，保留 owner-local path/Port IDs；source与
+target一起复制时只重映射element key，只复制source时把当前resolved source-local位置写入clone
+fallback并删除外部relation。所有结果通过一个trusted batch安装。Clipboard v2 只保存`elements`、
+`parentKeys`与透明`applicationData`；memory 与 system 使用同一 payload。非 Layer 副本先解析当前 live
+source parent；未提供`resolveParent`时使用该 parent，只有 parent 不存在时才落到 Root 第一个 Layer；提供
+resolver 时对每个非 Layer 顶层副本调用一次。v2 reader 不读取旧格式，不做版本协商或迁移。