@fulate/core 1.0.2 → 1.0.3

package/dist/geometry/common.d.ts

@@ -69,7 +69,13 @@ export interface GeometryNearestPoint extends GeometryPathPoint {
 /** 针对一个 immutable snapshot 的统一 exact query。 */
 export interface GeometryQuery {
     readonly snapshot: GeometrySnapshot;
-    /** 返回所有 subpath line/cubic 的精确 local AABB；无顶点时为 `null`。 */
+    /**
+     * 返回所有 subpath line/cubic 的精确 local AABB；无顶点时为 `null`。
+     *
+     * 返回值是 query-owned 的 borrowed view：同一 query 在其 snapshot
+     * 生命周期内重复返回同一引用，不会 clone 或 freeze。需要独立修改的
+     * 调用者必须在消费边界自行复制。
+     */
     getBounds(): Readonly<Rect> | null;
     /** 判断 local 点是否位于闭合 subpath 的指定填充内或边界上。 */
     contains(point: PointView, fillRule?: CanvasFillRule): boolean;

package/dist/geometry/rectangle.d.ts

@@ -16,6 +16,7 @@ export declare function createRectangleGeometrySnapshot(elementKey: string, revi
 export declare function rectangleSubpathsMaterializedForTest(snapshot: GeometrySnapshot): boolean;
 /** @internal 同一 canonical query 的普通矩形 O(1) 实现。 */
 export declare class RectangleSnapshotGeometryQuery extends SnapshotGeometryQuery {
+    private normalizedBounds;
     getBounds(): Readonly<Rect>;
     contains(point: PointView): boolean;
     hit(point: PointView, tolerance?: number): boolean;

package/dist/index.js

@@ -250,7 +250,7 @@ var ChangeImpact = /* @__PURE__ */ function(ChangeImpact) {
 function clonePropertyValue(value) {
 	return isObjectLike(value) ? structuredClone(value) : value;
 }
-/** 快照 API 需要比较独立副本的结构内容。 */
+/** snapshot/serialization 边界按结构内容比较独立值。 */
 function sameSnapshotValue(left, right) {
 	if (!isObjectLike(left) || !isObjectLike(right)) return Object.is(left, right);
 	return Object.is(left, right) || isEqual(left, right);
@@ -261,47 +261,17 @@ function samePropertyValue(left, right) {
 }
 var NO_PROPERTY_CHANGES = /* @__PURE__ */ new Map();
 var NO_PROPERTY_UPDATES = /* @__PURE__ */ new Map();
-/** Node 持有的属性状态，以及显式生成独立结果的快照操作。 */
+/** Node 持有的属性状态，并提供显式独立快照。 */
 var NodeProperties = class {
 	[CONFIGURED_STATE] = null;
 	[RUNTIME_OVERRIDE_STATE] = null;
-	/** 在新 Properties 实例上应用 patch，并返回旧值变化表。 */
-	with(patch) {
-		const next = this.create({
-			...this.values(),
-			...patch
-		});
-		const changes = /* @__PURE__ */ new Map();
-		for (const key of new Set([...Object.keys(this), ...Object.keys(next)])) {
-			if (key === "key") continue;
-			if (!sameSnapshotValue(this[key], next[key])) changes.set(key, this[key]);
-		}
-		return {
-			changes,
-			properties: next
-		};
-	}
 	/** 返回可独立修改的完整属性快照。 */
 	snapshot() {
 		return this.configuredValues();
 	}
-	/** 判断快照与当前属性是否语义相同。 */
-	matches(snapshot) {
-		if (!this[RUNTIME_OVERRIDE_STATE]) return this.with(snapshot).changes.size === 0;
-		const current = this.configuredValues();
-		const next = this.create({
-			...current,
-			...snapshot
-		});
-		for (const key of new Set([...Object.keys(this), ...Object.keys(next)])) {
-			if (key === "key") continue;
-			if (!sameSnapshotValue(current[key], next[key])) return false;
-		}
-		return true;
-	}
 	/** 返回省略默认值和函数的可序列化属性。 */
 	toJSON() {
-		const defaults = this.create({});
+		const defaults = createPropertiesLike(this, {});
 		const json = {};
 		for (const key of Object.keys(this)) {
 			if (key === "key") continue;
@@ -314,10 +284,6 @@ var NodeProperties = class {
 	getImpact(_changes, _updates = NO_PROPERTY_UPDATES) {
 		return ChangeImpact.None;
 	}
-	/** 返回当前属性的独立完整值对象。 */
-	values() {
-		return Object.fromEntries(Object.entries(this).filter(([key]) => key !== "key").map(([key, value]) => [key, clonePropertyValue(value)]));
-	}
 	/** 读取把 runtime 字段还原为 configured 后的当前作者值。 */
 	configuredValue(key) {
 		return getConfiguredPropertyValue(this, key);
@@ -326,12 +292,6 @@ var NodeProperties = class {
 	configuredValues() {
 		return Object.fromEntries(Object.keys(this).filter((key) => key !== "key").map((key) => [key, clonePropertyValue(this.configuredValue(key))]));
 	}
-	/** 使用当前运行时构造器创建同类型 Properties。 */
-	create(values) {
-		const Constructor = this.constructor;
-		const { key: _key, ...ordinaryValues } = values;
-		return new Constructor(ordinaryValues);
-	}
 };
 /** @internal 借用单个字段当前的 configured source 值。 */
 function getConfiguredPropertyValue(properties, key) {
@@ -1582,8 +1542,7 @@ var SnapshotGeometryQuery = class {
 		return { ...this.debugStats };
 	}
 	getBounds() {
-		const bounds = this.getBoundsData().bounds;
-		return bounds ? { ...bounds } : null;
+		return this.getBoundsData().bounds;
 	}
 	getPathPoint(position) {
 		if (position.revision !== this.snapshot.revision || position.t < 0 || position.t > 1) return void 0;
@@ -1767,13 +1726,15 @@ function hitRectangle(point, bounds, tolerance) {
 }
 /** @internal 同一 canonical query 的普通矩形 O(1) 实现。 */
 var RectangleSnapshotGeometryQuery = class extends SnapshotGeometryQuery {
+	normalizedBounds;
 	getBounds() {
+		if (this.normalizedBounds) return this.normalizedBounds;
 		const bounds = this.snapshot.layoutReferenceBounds;
 		const right = bounds.left + bounds.width;
 		const bottom = bounds.top + bounds.height;
 		const left = Math.min(bounds.left, right);
 		const top = Math.min(bounds.top, bottom);
-		return {
+		return this.normalizedBounds = {
 			left,
 			top,
 			width: Math.max(bounds.left, right) - left,
@@ -2775,27 +2736,26 @@ function resolveConnectionPortSlots(element, definitions) {
 	for (const { position } of definitions) edgeCounts.set(position.edge, (edgeCounts.get(position.edge) ?? 0) + 1);
 	return definitions.map((definition) => {
 		const { edge, ratio } = definition.position;
+		const geometry = element.getConnectionPortGeometry(edge, ratio);
 		return {
 			ref: {
 				elementKey: element.key,
 				portId: definition.id
 			},
 			kind: "endpoint-binding",
-			localPosition: element.getConnectionPortPosition(edge, ratio),
+			localPosition: geometry.position,
 			origin: "custom",
 			definition,
 			edge,
 			ratio,
-			edgeCount: edgeCounts.get(edge)
+			edgeCount: edgeCounts.get(edge),
+			geometry
 		};
 	});
 }
 /** 将 local 点投影到当前已提交 world matrix。 */
 function projectConnectionPortPoint(matrix, point) {
-	return {
-		x: matrix.a * point.x + matrix.c * point.y + matrix.e,
-		y: matrix.b * point.x + matrix.d * point.y + matrix.f
-	};
+	return transformPoint(matrix, point);
 }
 /** 按 owner-local ID 读取一个已知 Port；不受发现开关影响。 */
 function getElementConnectionPort(element, portId) {
@@ -3547,6 +3507,16 @@ var Element = class extends Node {
 	getConnectionPortPosition(edge, ratio) {
 		return rectEdgePosition(this.width ?? 0, this.height ?? 0, edge, ratio);
 	}
+	/** @internal 一次产出 custom Port position、法线与 label edge 长度。 */
+	getConnectionPortGeometry(edge, ratio) {
+		const resolved = rectEdgePosition(this.width ?? 0, this.height ?? 0, edge, ratio);
+		return {
+			position: this.getConnectionPortPosition(edge, ratio),
+			nx: resolved.nx,
+			ny: resolved.ny,
+			edgeLength: edge === "top" || edge === "bottom" ? Math.abs(this.width ?? 0) : Math.abs(this.height ?? 0)
+		};
+	}
 	/** @internal 一次借用 owner 当前 configured source 的指定字段。 */
 	static readConfiguredPropertyValues(owner, targets) {
 		readConfiguredPropertyValues(owner.propertyState, targets);
@@ -4012,9 +3982,12 @@ var Shape = class extends Element {
 	/**
 	* 返回某条逻辑边上 ratio 处的局部坐标和朝外法线。
 	* 默认实现基于 getEdgeSegment 做线性插值；圆形等曲线形状可直接覆写。
+	* Core owner 已取得 segment 时可传入它，避免重复遍历；普通调用省略该参数。
 	*/
-	getEdgePosition(edge, ratio) {
-		const seg = this.getEdgeSegment(edge);
+	getEdgePosition(edge, ratio, segment = this.getEdgeSegment(edge)) {
+		return this.getEdgePositionFromSegment(segment, ratio);
+	}
+	getEdgePositionFromSegment(seg, ratio) {
 		const pos = createPointView(seg.start.x + (seg.end.x - seg.start.x) * ratio, seg.start.y + (seg.end.y - seg.start.y) * ratio);
 		const dx = seg.end.x - seg.start.x;
 		const dy = seg.end.y - seg.start.y;
@@ -4035,8 +4008,20 @@ var Shape = class extends Element {
 			ny
 		};
 	}
-	getConnectionPortPosition(edge, ratio) {
-		return this.getEdgePosition(edge, ratio).pos;
+	/** @internal 一次产出 custom Port 的位置、法线与 label edge 长度。 */
+	getConnectionPortGeometry(edge, ratio) {
+		const segment = this.getEdgeSegment(edge);
+		const edgePosition = this.getEdgePosition(edge, ratio, segment);
+		return {
+			position: this.getConnectionPortPosition(edge, ratio, edgePosition),
+			nx: edgePosition.nx,
+			ny: edgePosition.ny,
+			edgeLength: Math.hypot(segment.end.x - segment.start.x, segment.end.y - segment.start.y)
+		};
+	}
+	/** 在组合 Port geometry 时可复用同一轮已解析的 edge position。 */
+	getConnectionPortPosition(edge, ratio, edgePosition) {
+		return (edgePosition ?? this.getEdgePosition(edge, ratio)).pos;
 	}
 	/** Replay the committed line/cubic snapshot into the current Canvas path. */
 	buildResolvedPath(ctx) {
@@ -4110,7 +4095,6 @@ var Shape = class extends Element {
 		const root = this.activeRoot;
 		const borderColor = isUndefined(configured) ? root ? root.skin.shapeStroke : SKIN_DEFAULTS.shapeStroke : configured;
 		if (!borderColor || !this.borderWidth) return;
-		this.buildBorderPath(ctx);
 		if (isGradient(borderColor)) ctx.strokeStyle = createCanvasGradient(ctx, borderColor, this.width ?? 0, this.height ?? 0);
 		else ctx.strokeStyle = borderColor;
 		ctx.save();

package/dist/node/element.d.ts

@@ -4,7 +4,7 @@ import { Node } from "./node";
 import { ElementTransform, type ElementTransformClass } from "./element-transform";
 import { ChangeImpact, TransformProperties, type PropertyChanges, type PreparedPropertyUpdate, type TransformableOptions } from "./properties";
 import { Tween } from "@tweenjs/tween.js";
-import type { ConnectionPortConfiguration, DerivedConnectionPort, ResolvedConnectionPort, ResolvedConnectionPortSlot } from "../utils/connection-port";
+import type { ConnectionPortConfiguration, ConnectionPortGeometry, DerivedConnectionPort, ResolvedConnectionPort, ResolvedConnectionPortSlot } from "../utils/connection-port";
 import type { Root } from "../root";
 import type { Layer } from "../layer";
 import type { OwnerPropertyChange } from "../mutation/change-batch";
@@ -251,6 +251,8 @@ export declare class Element<P extends ElementProperties = ElementProperties, O
      * @param ratio 从边起点到终点的比例，通常在 `0..1`。
      */
     getConnectionPortPosition(edge: Edge, ratio: number): PointView;
+    /** @internal 一次产出 custom Port position、法线与 label edge 长度。 */
+    getConnectionPortGeometry(edge: Edge, ratio: number): ConnectionPortGeometry;
     /** @internal 一次借用 owner 当前 configured source 的指定字段。 */
     static readConfiguredPropertyValues(owner: Element, targets: ReadonlyMap<string, {
         value: unknown;

package/dist/node/properties.d.ts

@@ -31,35 +31,20 @@ export declare function clonePropertyValue<T>(value: T): T;
 export type PropertyChanges = ReadonlyMap<string, unknown>;
 /** 属性名到本次提交最终值的只读变化表。 */
 export type PropertyUpdates = ReadonlyMap<string, unknown>;
-/** Node 持有的属性状态，以及显式生成独立结果的快照操作。 */
+/** Node 持有的属性状态，并提供显式独立快照。 */
 export declare class NodeProperties {
     [CONFIGURED_STATE]: Record<string, unknown> | null;
     [RUNTIME_OVERRIDE_STATE]: Record<string, unknown> | null;
-    /** 在新 Properties 实例上应用 patch，并返回旧值变化表。 */
-    with<T extends NodeProperties>(this: T, patch: Record<string, unknown>): {
-        /** 属性名到修改前值的变化表。 */
-        changes: Map<string, unknown>;
-        /** 应用 patch 后的新 Properties。 */
-        properties: T;
-    };
     /** 返回可独立修改的完整属性快照。 */
     snapshot(): Record<string, unknown>;
-    /** 判断快照与当前属性是否语义相同。 */
-    matches(snapshot: Record<string, unknown>): boolean;
     /** 返回省略默认值和函数的可序列化属性。 */
     toJSON(): Record<string, unknown>;
     /** 将属性变化映射为提交影响，供派生 Properties 扩展。 */
     getImpact(_changes: PropertyChanges, _updates?: PropertyUpdates): ChangeImpact;
-    /** 返回当前属性的独立完整值对象。 */
-    protected values(): {
-        [k: string]: any;
-    };
     /** 读取把 runtime 字段还原为 configured 后的当前作者值。 */
     private configuredValue;
     /** 返回把 runtime 字段还原为 configured 后的独立完整值。 */
     private configuredValues;
-    /** 使用当前运行时构造器创建同类型 Properties。 */
-    private create;
 }
 /** @internal 借用单个字段当前的 configured source 值。 */
 export declare function getConfiguredPropertyValue(properties: NodeProperties, key: string): any;

package/dist/node/shape.d.ts

@@ -3,6 +3,7 @@ import { ElementTransform, type ElementTransformClass } from "./element-transfor
 import { ChangeImpact, type PropertyChanges } from "./properties";
 import { type BackgroundColor, type Edge, type PointView } from "@fulate/share";
 import { type GeometryQuery, type GeometrySnapshot } from "../geometry";
+import type { ConnectionPortGeometry } from "../utils/connection-port";
 /** border 相对内容轮廓的绘制位置。 */
 export type BorderPosition = "inside" | "outside";
 /** Shape 阴影样式。 */
@@ -113,8 +114,14 @@ export declare class Shape<P extends ShapeProperties = ShapeProperties, O extend
     /**
      * 返回某条逻辑边上 ratio 处的局部坐标和朝外法线。
      * 默认实现基于 getEdgeSegment 做线性插值；圆形等曲线形状可直接覆写。
+     * Core owner 已取得 segment 时可传入它，避免重复遍历；普通调用省略该参数。
      */
-    getEdgePosition(edge: Edge, ratio: number): {
+    getEdgePosition(edge: Edge, ratio: number, segment?: {
+        /** 线段起点。 */
+        readonly start: PointView;
+        /** 线段终点。 */
+        readonly end: PointView;
+    }): {
         /** ratio 对应的边上位置。 */
         pos: PointView;
         /** 朝外法线的 x 分量。 */
@@ -122,7 +129,15 @@ export declare class Shape<P extends ShapeProperties = ShapeProperties, O extend
         /** 朝外法线的 y 分量。 */
         ny: number;
     };
-    getConnectionPortPosition(edge: Edge, ratio: number): PointView;
+    private getEdgePositionFromSegment;
+    /** @internal 一次产出 custom Port 的位置、法线与 label edge 长度。 */
+    getConnectionPortGeometry(edge: Edge, ratio: number): ConnectionPortGeometry;
+    /** 在组合 Port geometry 时可复用同一轮已解析的 edge position。 */
+    getConnectionPortPosition(edge: Edge, ratio: number, edgePosition?: {
+        readonly pos: PointView;
+        readonly nx: number;
+        readonly ny: number;
+    }): PointView;
     /** Replay the committed line/cubic snapshot into the current Canvas path. */
     protected buildResolvedPath(ctx: CanvasRenderingContext2D): void;
     paint(ctx?: CanvasRenderingContext2D): void;

package/dist/utils/connection-port.d.ts

@@ -1,4 +1,4 @@
-import type { Edge, PointView } from "@fulate/share";
+import { type Edge, type PointView } from "@fulate/share";
 import type { Element } from "../node/element";
 /** Element owner 内稳定、由调用者直接提供的普通字符串 Port ID。 */
 export type ConnectionPortId = string;
@@ -57,6 +57,13 @@ export interface ResolvedConnectionPort {
     readonly origin: "builtin" | "custom";
     readonly definition?: ConnectionPortDefinition;
 }
+/** 一次解析 Port 时由几何 owner 产出的 label 所需 edge facts。 @internal */
+export interface ConnectionPortGeometry {
+    readonly position: PointView;
+    readonly nx: number;
+    readonly ny: number;
+    readonly edgeLength: number;
+}
 /** custom Port decoration 需要的边布局信息。 @internal */
 export interface ResolvedConnectionPortSlot extends ResolvedConnectionPort {
     readonly origin: "custom";
@@ -64,6 +71,8 @@ export interface ResolvedConnectionPortSlot extends ResolvedConnectionPort {
     readonly edge: Edge;
     readonly ratio: number;
     readonly edgeCount: number;
+    /** 与 `localPosition` 同一份 owner-produced geometry 结果。 */
+    readonly geometry: ConnectionPortGeometry;
 }
 /** top、right、bottom、left 四条逻辑边中点组成的默认 Port。 */
 export declare const DEFAULT_CONNECTION_PORT_SCHEMA: readonly DerivedConnectionPort[];

package/package.json

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