@fulate/ui 1.0.0 → 1.0.2

package/README.md

@@ -1,199 +1,197 @@
-# @fulate/ui authored paths
-
-> 文档角色：`GUIDE`。权威来源：UI 源码 TSDoc 与测试；Path/Line 的跨域长期契约见 [`docs/specs/path-line-core.md`](../../docs/specs/path-line-core.md)。
-
-## Bitmap surface
-
-`Bitmap`唯一拥有主线程当前frame，并向位图producer提供`renderPixelRatio = Viewport scale × DPR`。
-producer保持authored-local布局；需要超采样时，在自己的backend中基于该倍率增加质量倍率和资源预算。
-`paintBitmap()`仍把最终位图绘制到图元authored宽高，再由Layer应用Viewport与DPR。
-
-位图、DPR和超采样质量都不改变逻辑坐标。鼠标与Worker返回的坐标保持authored-local，不经过
-`Bitmap`的scale换算。
-
-## Workspace fit
-
-`WorkspaceOption.fit`控制首次进入Root时的自动聚焦，`WorkspaceOption.fitOnResize`控制Root尺寸
-变化后的自动重新聚焦；两者默认都是`true`，也可以独立关闭。首次fit在Workspace的初始几何提交后、
-首个Canvas paint前直接安装最终Viewport，不播放动画。同一帧内连续发生的Root尺寸变化只按最终尺寸
-执行一次无动画fit。两条路径都读取当前Root提供的实时可见区insets。
-
-编辑器按钮、导入完成等外部流程直接调用同一公开函数，不复制Workspace bounds或Viewport focus规则：
-
-```ts
-import { fitWorkspace } from "@fulate/ui";
-
-await fitWorkspace(workspace, { padding: 0 });
-```
-
-显式调用不受`WorkspaceOption.fit`或`WorkspaceOption.fitOnResize`限制；传入的focus options会按原引用
-直接交给Workspace所属Root的Viewport。用户触发的fit需要动画时由调用者显式传入`animate`。
-
-`Line`、`Polygon` 和 `VectorPath` 都只有一份 live canonical authored owner：
-
-| 元素 | 普通创建输入 | live getter | topology |
-| --- | --- | --- | --- |
-| `Line` | `path: PointView[]` | `line.path` | 一个 open、line-only subpath |
-| `Polygon` | `contour: PointView[]` | `polygon.contour` | 一个 closed、line-only subpath |
-| `VectorPath` | `path: VectorPathCommand[]` | `vector.path.subpaths` | ordered open/closed line/cubic subpaths |
-
-普通输入只在入口解释一次。每个 canonical anchor record 直接保存 `anchorId`、原 `point` 引用，
-并在存在 outgoing segment 时共置 `segmentId` 与 `line | cubic` 数据；普通 line segment 没有
-独立 wrapper。Geometry resolver 让 `vertices` 和 `segmentShapes` 直接复用这些 records。
-
-```ts
-const line = new Line({
-  path: [{ x: 0, y: 0 }, { x: 80, y: 30 }]
-});
-
-const anchorId = line.headAnchor.anchorId;
-line.setLocalPoint(anchorId, { x: 10, y: 5 });
-```
-
-坐标更新、transform、History restore 保留既有 local IDs；insert 只创建新增 IDs，delete 保留
-未受影响 IDs。传入 canonical whole value 时按引用 identity 判断：同一引用是 noop，不同引用
-即使内容相同也会被采用。point/control 等结构化值不做 caller-isolation clone；需要隔离时由
-调用者在传入前复制。调用者在所有权移交后原地修改同一对象不会自动产生 commit、dirty、
-History 或 frame。
-
-## Connection、Port 与 Line endpoints
-
-Path authored `anchorId` 与 target owner-local `portId` 是两个概念。Line 首尾 endpoint 与
-LineTree root/leaf endpoint只保存source-owned relation：
-
-```ts
-interface EndpointRelation {
-  readonly kind: "endpoint-binding";
-  readonly target: {
-    readonly elementKey: string;
-    readonly portId: string;
-  };
-}
-```
-
-relation不保存坐标。`Line.path`与`LineTree.topology.points`保存authored fallback；paint、hit、bounds、
-query和controls从当前target Port解析effective geometry。target变化只通过Root唯一
-`EndpointRelationIndex`精确dirty dependents，不反写source authored值或History。
-
-Line的`relations` patch省略时两端保持；对象中省略一端也表示保持，own `undefined`清除该端，
-`EndpointRelation`建立或替换。程序化连接使用同步`connectEndpoint(root, source, target)`与
-`disconnectEndpoint(root, source)`；普通noop返回`void`且不创建结果状态机。
-
-Line首端/root endpoint的连接role是`output`，尾端/leaf是`input`；装饰不决定连接role。同步
-`connectEndpoint()`从live source与target Port读取role、`direction`和对应capacity；方向不兼容、容量
-已满或target Port不存在时保持noop。Tools picker复用同一规则，受阻Port不能降级成自由落点。
-
-`Element.ports`是`false | true | readonly ConnectionPortDefinition[]`的唯一authored owner。构造时
-省略等同`false`；`false`没有Port，`true`使用元素类型的默认schema，数组作为custom whole-value按
-原引用采用，`[]`表示当前custom配置为空。patch省略`ports`保持当前值；不支持`null`。数组同引用
-noop，不clone、freeze、normalize或deep-equal。
-`Root.enablePorts`默认`false`并可通过`setEnablePorts()`切换；关闭时不绘制、发现或Snap Port，也不
-允许`connectEndpoint()`新建relation。按已知Port ID解析和已有relation的target observer始终有效，
-因此Line/LineTree继续跟随目标；显式Port删除/替换仍物化当前fallback并detach。完整开关边界见
-[`path-line-core.md`](../../docs/specs/path-line-core.md#10-transformpointbinding-与-routing-边界)。
-
-JSON、clipboard和History的独立输出复制所需数据；restore直接安装canonical path/topology、IDs和
-source-owned relations。source与target一起复制时只重映射element key；只复制source时使用当前
-resolved source-local fallback并删除外部relation；完整owner的subpath/anchor/segment/Port IDs保留。
-
-## LineTree
-
-`LineTree`是一整个场景元素，不包含隐藏的`Line` child。`topology.points`唯一拥有坐标和可选
-EndpointRelation，`topology.branches`只通过稳定`SubpathId/AnchorId/
-SegmentId`引用这些points；非root branch用`parentSubpathId`表达同一owner内的唯一父分支。
-当前branch只有straight/polyline，不保存kind或Orthogonal/cubic预留variant。
-
-```ts
-const topology = createLineTreeTopology([
-  { x: 0, y: 0 },
-  { x: 120, y: 0 }
-]);
-const tree = new LineTree({ topology });
-const root = topology.branches[0];
-
-tree.replaceTopology(addLineTreeBranchAtTail(
-  tree.topology,
-  root.subpathId,
-  [{ x: 120, y: 80 }]
-).topology);
-```
-
-普通选择、hover、copy、delete、Transform、RBush和History owner始终只有`tree`一个。双击精确
-branch后Point projection只请求该subpath；删除父branch由`removeLineTreeBranch()`在一个owner-local
-delta中删除全部descendants和孤儿points。外部topology输入按原引用采用；domain edit只复制实际
-changed records及必要外层数组。新增branch只复用parent branch的尾点；Editor交互允许任意branch
-tail成为source，同一junction tail可重复产生sibling branches，但junction不绘制tail三角形。树干segment和中间anchor都不是branch source，也
-不会因扩展操作被插入junction。
-
-Line与LineTree的stroke和端点decoration在world空间按固定宽度绘制；自身visual bounds与render
-coverage覆盖同一完整绘制范围，反向近零Transform也不会缩掉dirty coverage。固定world paint padding
-不贡献ancestor content bounds；Group selection、resize与snap只消费Line/LineTree的effective path
-geometry。hover与active branch highlight复用同一polyline paint，箭头和线段保持同色。
-
-Rectangle、Triangle及其他Shape省略`backgroundColor`/`borderColor`时读取当前Root的
-`skin.shapeFill`/`skin.shapeStroke`；Line和LineTree branch省略`strokeColor`时读取
-`skin.lineStroke`。显式值始终优先，Shape的显式`null`关闭绘制，显式字段清回`undefined`后立即重新
-继承Skin。Skin改变只触发现有Root/Layer重绘，不改写element、branch topology或History。
-
-LineTree整体resize继续使用O(1) pose。随后Point移动或插入anchor时在同一owner change内保留当前
-world pose；包括反向scale在内，只有目标anchor改变world位置，其他points保持不动。
-
-## Text 尺寸与显示
-
-`Text` 未提供 `width`/`height` 时使用当前文字的 intrinsic 尺寸；提供尺寸后，该尺寸成为布局盒。
-`wordWrap` 只控制是否按布局宽度换行，`ellipsis` 只控制是否把被截断内容绘制为 `…`，`overflow`
-只控制是否裁剪绘制内容，三个选项可以独立组合。Text 默认使用 intrinsic 尺寸、`wordWrap=false`、
-`overflow="visible"` 且不启用省略号；组件若需要 Web 控件式的填满、裁剪或省略，应显式传入对应属性。
-
-Editor 的 Text selection/resize frame 使用布局盒，不使用可见溢出 glyph 的 visual bounds。因此
-`wordWrap={false}`、`overflow="visible"` 的文本被缩放后，取消选择再重新选择仍保持上一次 authored
-尺寸，下一次缩放也从该尺寸继续。
-
-### 原生 Canvas 文本 run
-
-组合型原生 Shape 可以直接传入 live resolved Skin，按 `Text` 相同的字体、行高、Canvas baseline
-和字符间距语义测量一段文本，不需要复制或整理 style：
-
-```ts
-import { measureTextRun } from "@fulate/ui";
-
-const metrics = measureTextRun(ctx, text, root.skin.text, 14, 500);
-```
-
-每次调用只执行一次 `ctx.measureText()`，返回 `font`、`width`、`lineHeight`、`drawY` 和
-`alphabeticBaseline`。空文本的 `width` 为 `0`，但仍测量一个空格以取得稳定基线。函数会把本次
-测量所需的文字状态写入 `ctx`，不会调用 `save()` 或 `restore()`；Canvas 生命周期以及业务特有的
-文字顺序、对齐和绘制仍由 Shape 自己拥有。
-
-## Editor capabilities
-
-UI 元素通过对象 identity token 直接提供 Selection、Transform、Snap、Point 与 Content capability；
-没有 registry、字符串 key、implicit default、layout writer 或 Tools duck fields。
-Selection 的闭集策略使用公开枚举：
-
-```ts
-import {
-  SelectionBehaviorMode,
-  SelectionDiveMode,
-  SelectionSnapMode
-} from "@fulate/ui";
-
-const behavior = {
-  mode: SelectionBehaviorMode.OwnerDirect,
-  dive: SelectionDiveMode.None,
-  snap: SelectionSnapMode.Disabled
-};
-```
-
-`OwnerDirect` 用于不绘制单选 frame、首次位移可直接提升 owner drag 的自定义对象；Group 使用
-`DirectChild` dive，普通 Shape/Line 使用 `Standard`。Transform provider 在 gesture start 捕获 frozen
-reference 与领域 owned state，每帧只纯解析最终 owner change；frame-authored Shape、pose-authored
-Group 与 authored-geometry Line/Polygon/VectorPath 共用 Core reference-transform primitive，结构化
-authored value 不为 caller isolation clone。Group 的稳定 reference 由创建时的 width/height/origin 与
-pose 拥有；当前 content bounds 是只读 local derived view。Line/LineTree 的
-固定world paint padding不贡献ancestor content bounds，但仍进入各自render coverage。group/ungroup
-只转换 local pose，保留 width/path/contour/topology、effect 与 relation 的值和引用。
-
-`selectable:false`只限制Editor交互选择，并对该owner分支生效：普通点击、marquee、Select All与
-Group DirectChild下钻都不能进入该分支。公开`Select.select(elements)`和History selection replay由
-调用者直接控制，不增加过滤；把已选owner改为`selectable:false`也不会自动清除当前selection。
+# @fulate/ui authored paths
+
+## Bitmap surface
+
+`Bitmap`唯一拥有主线程当前frame，并向位图producer提供`renderPixelRatio = Viewport scale × DPR`。
+producer保持authored-local布局；需要超采样时，在自己的backend中基于该倍率增加质量倍率和资源预算。
+`paintBitmap()`仍把最终位图绘制到图元authored宽高，再由Layer应用Viewport与DPR。
+
+位图、DPR和超采样质量都不改变逻辑坐标。鼠标与Worker返回的坐标保持authored-local，不经过
+`Bitmap`的scale换算。
+
+## Workspace fit
+
+`WorkspaceOption.fit`控制首次进入Root时的自动聚焦，`WorkspaceOption.fitOnResize`控制Root尺寸
+变化后的自动重新聚焦；两者默认都是`true`，也可以独立关闭。首次fit在Workspace的初始几何提交后、
+首个Canvas paint前直接安装最终Viewport，不播放动画。同一帧内连续发生的Root尺寸变化只按最终尺寸
+执行一次无动画fit。两条路径都读取当前Root提供的实时可见区insets。
+
+编辑器按钮、导入完成等外部流程直接调用同一公开函数，不复制Workspace bounds或Viewport focus规则：
+
+```ts
+import { fitWorkspace } from "@fulate/ui";
+
+await fitWorkspace(workspace, { padding: 0 });
+```
+
+显式调用不受`WorkspaceOption.fit`或`WorkspaceOption.fitOnResize`限制；传入的focus options会按原引用
+直接交给Workspace所属Root的Viewport。用户触发的fit需要动画时由调用者显式传入`animate`。
+
+`Line`、`Polygon` 和 `VectorPath` 都只有一份 live canonical authored owner：
+
+| 元素 | 普通创建输入 | live getter | topology |
+| --- | --- | --- | --- |
+| `Line` | `path: PointView[]` | `line.path` | 一个 open、line-only subpath |
+| `Polygon` | `contour: PointView[]` | `polygon.contour` | 一个 closed、line-only subpath |
+| `VectorPath` | `path: VectorPathCommand[]` | `vector.path.subpaths` | ordered open/closed line/cubic subpaths |
+
+普通输入只在入口解释一次。每个 canonical anchor record 直接保存 `anchorId`、原 `point` 引用，
+并在存在 outgoing segment 时共置 `segmentId` 与 `line | cubic` 数据；普通 line segment 没有
+独立 wrapper。Geometry resolver 让 `vertices` 和 `segmentShapes` 直接复用这些 records。
+
+```ts
+const line = new Line({
+  path: [{ x: 0, y: 0 }, { x: 80, y: 30 }]
+});
+
+const anchorId = line.headAnchor.anchorId;
+line.setLocalPoint(anchorId, { x: 10, y: 5 });
+```
+
+坐标更新、transform、History restore 保留既有 local IDs；insert 只创建新增 IDs，delete 保留
+未受影响 IDs。传入 canonical whole value 时按引用 identity 判断：同一引用是 noop，不同引用
+即使内容相同也会被采用。point/control 等结构化值不做 caller-isolation clone；需要隔离时由
+调用者在传入前复制。调用者在所有权移交后原地修改同一对象不会自动产生 commit、dirty、
+History 或 frame。
+
+## Connection、Port 与 Line endpoints
+
+Path authored `anchorId` 与 target owner-local `portId` 是两个概念。Line 首尾 endpoint 与
+LineTree root/leaf endpoint只保存source-owned relation：
+
+```ts
+interface EndpointRelation {
+  readonly kind: "endpoint-binding";
+  readonly target: {
+    readonly elementKey: string;
+    readonly portId: string;
+  };
+}
+```
+
+relation不保存坐标。`Line.path`与`LineTree.topology.points`保存authored fallback；paint、hit、bounds、
+query和controls从当前target Port解析effective geometry。target变化只通过Root唯一
+`EndpointRelationIndex`精确dirty dependents，不反写source authored值或History。
+
+Line的`relations` patch省略时两端保持；对象中省略一端也表示保持，own `undefined`清除该端，
+`EndpointRelation`建立或替换。程序化连接使用同步`connectEndpoint(root, source, target)`与
+`disconnectEndpoint(root, source)`；普通noop返回`void`且不创建结果状态机。
+
+Line首端/root endpoint的连接role是`output`，尾端/leaf是`input`；装饰不决定连接role。同步
+`connectEndpoint()`从live source与target Port读取role、`direction`和对应capacity；方向不兼容、容量
+已满或target Port不存在时保持noop。Tools picker复用同一规则，受阻Port不能降级成自由落点。
+
+`Element.ports`是`false | true | readonly ConnectionPortDefinition[]`的唯一authored owner。构造时
+省略等同`false`；`false`没有Port，`true`使用元素类型的默认schema，数组作为custom whole-value按
+原引用采用，`[]`表示当前custom配置为空。patch省略`ports`保持当前值；不支持`null`。数组同引用
+noop，不clone、freeze、normalize或deep-equal。
+`Root.enablePorts`默认`false`并可通过`setEnablePorts()`切换；关闭时不绘制、发现或Snap Port，也不
+允许`connectEndpoint()`新建relation。按已知Port ID解析和已有relation的target observer始终有效，
+因此Line/LineTree继续跟随目标；显式Port删除/替换仍物化当前fallback并detach。完整开关边界见
+[`path-line-core.md`](../../docs/specs/path-line-core.md#10-transformpointbinding-与-routing-边界)。
+
+JSON、clipboard和History的独立输出复制所需数据；restore直接安装canonical path/topology、IDs和
+source-owned relations。source与target一起复制时只重映射element key；只复制source时使用当前
+resolved source-local fallback并删除外部relation；完整owner的subpath/anchor/segment/Port IDs保留。
+
+## LineTree
+
+`LineTree`是一整个场景元素，不包含隐藏的`Line` child。`topology.points`唯一拥有坐标和可选
+EndpointRelation，`topology.branches`只通过稳定`SubpathId/AnchorId/
+SegmentId`引用这些points；非root branch用`parentSubpathId`表达同一owner内的唯一父分支。
+当前branch只有straight/polyline，不保存kind或Orthogonal/cubic预留variant。
+
+```ts
+const topology = createLineTreeTopology([
+  { x: 0, y: 0 },
+  { x: 120, y: 0 }
+]);
+const tree = new LineTree({ topology });
+const root = topology.branches[0];
+
+tree.replaceTopology(addLineTreeBranchAtTail(
+  tree.topology,
+  root.subpathId,
+  [{ x: 120, y: 80 }]
+).topology);
+```
+
+普通选择、hover、copy、delete、Transform、RBush和History owner始终只有`tree`一个。双击精确
+branch后Point projection只请求该subpath；删除父branch由`removeLineTreeBranch()`在一个owner-local
+delta中删除全部descendants和孤儿points。外部topology输入按原引用采用；domain edit只复制实际
+changed records及必要外层数组。新增branch只复用parent branch的尾点；Editor交互允许任意branch
+tail成为source，同一junction tail可重复产生sibling branches，但junction不绘制tail三角形。树干segment和中间anchor都不是branch source，也
+不会因扩展操作被插入junction。
+
+Line与LineTree的stroke和端点decoration在world空间按固定宽度绘制；自身visual bounds与render
+coverage覆盖同一完整绘制范围，反向近零Transform也不会缩掉dirty coverage。固定world paint padding
+不贡献ancestor content bounds；Group selection、resize与snap只消费Line/LineTree的effective path
+geometry。hover与active branch highlight复用同一polyline paint，箭头和线段保持同色。
+
+Rectangle、Triangle及其他Shape省略`backgroundColor`/`borderColor`时读取当前Root的
+`skin.shapeFill`/`skin.shapeStroke`；Line和LineTree branch省略`strokeColor`时读取
+`skin.lineStroke`。显式值始终优先，Shape的显式`null`关闭绘制，显式字段清回`undefined`后立即重新
+继承Skin。Skin改变只触发现有Root/Layer重绘，不改写element、branch topology或History。
+
+LineTree整体resize继续使用O(1) pose。随后Point移动或插入anchor时在同一owner change内保留当前
+world pose；包括反向scale在内，只有目标anchor改变world位置，其他points保持不动。
+
+## Text 尺寸与显示
+
+`Text` 未提供 `width`/`height` 时使用当前文字的 intrinsic 尺寸；提供尺寸后，该尺寸成为布局盒。
+`wordWrap` 只控制是否按布局宽度换行，`ellipsis` 只控制是否把被截断内容绘制为 `…`，`overflow`
+只控制是否裁剪绘制内容，三个选项可以独立组合。Text 默认使用 intrinsic 尺寸、`wordWrap=false`、
+`overflow="visible"` 且不启用省略号；组件若需要 Web 控件式的填满、裁剪或省略，应显式传入对应属性。
+
+Editor 的 Text selection/resize frame 使用布局盒，不使用可见溢出 glyph 的 visual bounds。因此
+`wordWrap={false}`、`overflow="visible"` 的文本被缩放后，取消选择再重新选择仍保持上一次 authored
+尺寸，下一次缩放也从该尺寸继续。
+
+### 原生 Canvas 文本 run
+
+组合型原生 Shape 可以直接传入 live resolved Skin，按 `Text` 相同的字体、行高、Canvas baseline
+和字符间距语义测量一段文本，不需要复制或整理 style：
+
+```ts
+import { measureTextRun } from "@fulate/ui";
+
+const metrics = measureTextRun(ctx, text, root.skin.text, 14, 500);
+```
+
+每次调用只执行一次 `ctx.measureText()`，返回 `font`、`width`、`lineHeight`、`drawY` 和
+`alphabeticBaseline`。空文本的 `width` 为 `0`，但仍测量一个空格以取得稳定基线。函数会把本次
+测量所需的文字状态写入 `ctx`，不会调用 `save()` 或 `restore()`；Canvas 生命周期以及业务特有的
+文字顺序、对齐和绘制仍由 Shape 自己拥有。
+
+## Editor capabilities
+
+UI 元素通过对象 identity token 直接提供 Selection、Transform、Snap、Point 与 Content capability；
+没有 registry、字符串 key、implicit default、layout writer 或 Tools duck fields。
+Selection 的闭集策略使用公开枚举：
+
+```ts
+import {
+  SelectionBehaviorMode,
+  SelectionDiveMode,
+  SelectionSnapMode
+} from "@fulate/ui";
+
+const behavior = {
+  mode: SelectionBehaviorMode.OwnerDirect,
+  dive: SelectionDiveMode.None,
+  snap: SelectionSnapMode.Disabled
+};
+```
+
+`OwnerDirect` 用于不绘制单选 frame、首次位移可直接提升 owner drag 的自定义对象；Group 使用
+`DirectChild` dive，普通 Shape/Line 使用 `Standard`。Transform provider 在 gesture start 捕获 frozen
+reference 与领域 owned state，每帧只纯解析最终 owner change；frame-authored Shape、pose-authored
+Group 与 authored-geometry Line/Polygon/VectorPath 共用 Core reference-transform primitive，结构化
+authored value 不为 caller isolation clone。Group 的稳定 reference 由创建时的 width/height/origin 与
+pose 拥有；当前 content bounds 是只读 local derived view。Line/LineTree 的
+固定world paint padding不贡献ancestor content bounds，但仍进入各自render coverage。group/ungroup
+只转换 local pose，保留 width/path/contour/topology、effect 与 relation 的值和引用。
+
+`selectable:false`只限制Editor交互选择，并对该owner分支生效：普通点击、marquee、Select All与
+Group DirectChild下钻都不能进入该分支。公开`Select.select(elements)`和History selection replay由
+调用者直接控制，不增加过滤；把已选owner改为`selectable:false`也不会自动清除当前selection。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fulate/ui",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",