@fulate/core 1.0.0

package/dist/root/scene-registry.d.ts

@@ -0,0 +1,45 @@
+import type { Node } from "../node/node";
+/** 监听一个 key 对应节点的注册和注销。 */
+export type NodeKeyObserver = (node: Node, registered: boolean) => void;
+/** 监听当前 Root 中节点进入或离开 active 生命周期。 */
+export type NodeRegistrationObserver = (node: Node, registered: boolean) => void;
+/** 监听会影响场景查询或工具缓存的变化；省略 node 表示批量结构变化。 */
+export type SceneChangeObserver = (node?: Node, affected?: readonly Node[]) => void;
+/** 管理活动场景的节点 key 索引和轻量变化观察器。 */
+export declare class SceneRegistry {
+    /** 活动节点的 key 索引。 */
+    readonly keyElements: Map<string, Node<import("..").NodeProperties, Node<any, any>>>;
+    /** 按 key 保存观察注册和注销的回调。 */
+    private readonly nodeKeyObservers;
+    /** 监听结构、geometry 和命中策略变化的回调。 */
+    private readonly sceneChangeObservers;
+    /** 监听 active registration 的轻量观察器。 */
+    private readonly nodeRegistrationObservers;
+    /** 创建注册表；可注入已有 Map 以共享或测试已经成立的 key 索引。 */
+    constructor(
+    /** 活动节点的 key 索引。 */
+    keyElements?: Map<string, Node<import("..").NodeProperties, Node<any, any>>>);
+    /** 订阅场景变化并返回注销函数。 */
+    observeSceneChanges(observer: SceneChangeObserver): () => boolean;
+    /** @internal 当前是否存在真实 scene change consumer。 */
+    get hasSceneChangeObservers(): boolean;
+    /** 订阅节点 active registration 并返回注销函数。 */
+    observeNodeRegistrations(observer: NodeRegistrationObserver): () => boolean;
+    /** @internal 通知场景观察器；node 省略时表示整批变化。 */
+    notifySceneChange(node?: Node, affected?: readonly Node[]): void;
+    /** 订阅指定 key 的注册状态变化并返回注销函数。 */
+    observeNodeKey(key: string, observer: NodeKeyObserver): () => void;
+    /** 按当前索引状态通知指定 key 的观察者。 */
+    private notifyNodeKeyObservers;
+    /** @internal 节点进入 active 状态后发送 key 注册通知。 */
+    notifyNodeRegistered(node: Node): void;
+    /** @internal 写入活动身份；producer 违约时只做 O(1) 诊断。 */
+    registerNodeKey(node: Node): void;
+    /** @internal 从索引移除停用节点并通知 key 观察器。 */
+    unregisterNodeKey(node: Node): void;
+    private notifyNodeRegistrationObservers;
+    /** 返回活动场景中指定 key 对应的节点。 */
+    getByKey(key: string): Node<import("..").NodeProperties, Node<any, any>>;
+    /** @internal 清空 key 索引和全部观察器。 */
+    clear(): void;
+}

package/dist/root/viewport.d.ts

@@ -0,0 +1,165 @@
+import type { Root } from "./index";
+import type { Rect, RectWithCenter } from "@fulate/share";
+import { type PointView } from "@fulate/share";
+import type { Layer } from "../layer";
+/** 可序列化的 Viewport 平移和缩放快照。 */
+export interface ViewportSnapshot {
+    /** Root 容器 CSS 像素中的水平平移。 */
+    readonly x: number;
+    /** Root 容器 CSS 像素中的垂直平移。 */
+    readonly y: number;
+    /** world 到容器 CSS 像素的缩放倍率。 */
+    readonly scale: number;
+}
+/** `focus()` 在四边预留的 client 像素。 */
+export interface ViewportInsets {
+    /** 顶部预留的 client 像素。 */
+    top?: number;
+    /** 右侧预留的 client 像素。 */
+    right?: number;
+    /** 底部预留的 client 像素。 */
+    bottom?: number;
+    /** 左侧预留的 client 像素。 */
+    left?: number;
+}
+/** 管理 Root 的平移、缩放、DPR、坐标换算和 CSS 快速预览。 */
+export declare class Viewport {
+    /** 当前 Viewport 所属的 Root。 */
+    private readonly activeRoot;
+    /** 当前 Root 的平移、缩放和 DPR。 */
+    private viewportState;
+    /** 复用的可见 world 矩形返回对象。 */
+    private readonly worldRectView;
+    /** Root 创建时固定的缩放下限。 */
+    private readonly minimumScale;
+    /** Root 创建时固定的缩放上限。 */
+    private readonly maximumScale;
+    /** 当前 focus 动画；新的平移或缩放会停止它。 */
+    private focusTween?;
+    /** 每个 Layer 最近一次真实绘制所使用的 Viewport 快照。 */
+    private renderedViewports;
+    /** CSS 预览的自动刷新定时器。 */
+    private cssTransformTimer;
+    /** 是否仍有未提交的 CSS 预览。 */
+    private cssPreviewActive;
+    /** 是否已安装宿主窗口的 DPR resize 监听。 */
+    private resizeListening;
+    /** 创建 Root 拥有的 Viewport，并设置允许的缩放范围。 */
+    constructor(
+    /** 当前 Viewport 所属的 Root。 */
+    activeRoot: Root, options?: {
+        /** 最小缩放倍率，默认 `0.1`。 */
+        minScale?: number;
+        /** 最大缩放倍率，默认 `10`。 */
+        maxScale?: number;
+    });
+    /** 从宿主窗口读取最新 DPR，并重设所有 Layer surface。 */
+    private readonly onDevicePixelRatioChange;
+    /** @internal Root 激活时开始监听宿主窗口的 DPR 变化。 */
+    activate(): void;
+    /** @internal Root 停用时移除宿主窗口监听。 */
+    deactivate(): void;
+    /** Root 容器 CSS 像素中的水平平移。 */
+    get x(): number;
+    /** Root 容器 CSS 像素中的垂直平移。 */
+    get y(): number;
+    /** 当前 world 到容器 CSS 像素的缩放倍率。 */
+    get scale(): number;
+    /** 当前 Canvas backing store 使用的设备像素比。 */
+    get dpr(): number;
+    /** Root 创建时确定的最小缩放倍率。 */
+    get minScale(): number;
+    /** Root 创建时确定的最大缩放倍率。 */
+    get maxScale(): number;
+    /** 是否正在用 CSS transform 预览尚未真实绘制的 Viewport。 */
+    get isCssTransforming(): boolean;
+    /** @internal 返回复用的可见 world 矩形；调用方不能修改或保存。 */
+    getWorldRectView(): Readonly<Rect>;
+    /** 返回当前可见 world 矩形的独立副本。 */
+    getWorldRect(): Rect;
+    /**
+     * 将浏览器 client 坐标转换为 Root world 坐标。
+     * @param clientX DOM 指针事件的 `clientX`。
+     * @param clientY DOM 指针事件的 `clientY`。
+     */
+    getLogicalPosition(clientX: number, clientY: number): PointView;
+    /**
+     * 将 DPR、Viewport 和可选 own world matrix 写入 Canvas Context。
+     * @param ctx 要更新 transform 的 Layer 2D Context。
+     * @param ownMatrix 元素已提交的 own world matrix；绘制 Layer 本身时省略。
+     */
+    applyTransform(ctx: CanvasRenderingContext2D, ownMatrix?: DOMMatrixReadOnly): void;
+    /** 将倍率限制在 Root 创建时的 min/max 范围内。 */
+    private clampScale;
+    /** 提交 Viewport 状态，并决定走 CSS 预览还是完整 Canvas 重绘。 */
+    private commit;
+    /** 根据实际变化派发 zoom、translation 和 viewportchange。 */
+    private emitChange;
+    /** @internal 更新 DPR、重设 Layer surface 并完整重绘，不派发 Viewport 事件。 */
+    setDevicePixelRatio(dpr: number): boolean;
+    /**
+     * 按容器 CSS 像素增量平移，可选择使用 CSS 快速预览。
+     * @param dx 水平 CSS 像素增量。
+     * @param dy 垂直 CSS 像素增量。
+     * @param useCssTransform 是否先用 CSS transform 预览，默认 `false`。
+     */
+    translateBy(dx: number, dy: number, useCssTransform?: boolean): void;
+    /**
+     * 以容器 CSS 像素点为中心按倍率缩放，并返回约束后的实际 scale。
+     * @param delta 相对当前 scale 的倍率；`1.2` 表示放大 20%，不是目标 scale。
+     * @param center Root 容器内的 CSS 像素坐标；省略时使用容器中心。
+     * @param useCssTransform 是否先用 CSS transform 预览，默认 `false`。
+     */
+    zoom(delta: number, center?: PointView, useCssTransform?: boolean): number;
+    /** 将平移恢复为 0、缩放恢复为受 min/max 约束的 1。 */
+    reset(): void;
+    /** 恢复 `captureSnapshot()` 返回的状态，scale 会经过 min/max 约束。 */
+    restore(snapshot: ViewportSnapshot): void;
+    /**
+     * 将 world 矩形适配到可见区域，可选动画、padding 和 client 像素 insets。
+     * 目标倍率不会因小矩形主动放大到 1 以上，之后仍受 min/max 约束。
+     * @param rect 要显示的 world 坐标矩形。
+     * @param options 适配留白、动画和四边预留。
+     */
+    focus(rect: RectWithCenter, options?: {
+        /** 矩形四周的容器 CSS 像素留白，默认 `10`。 */
+        padding?: number;
+        /** 启用 Tween；duration 单位为毫秒。 */
+        animate?: {
+            duration?: number;
+            easing?: (amount: number) => number;
+        };
+        /** 从可见区域四边扣除的容器 CSS 像素。 */
+        insets?: number | ViewportInsets;
+    }): Promise<void>;
+    /** 返回当前 x、y 和 scale 的独立快照。 */
+    captureSnapshot(): ViewportSnapshot;
+    /** @internal 记录 Layer 最近真实绘制的 Viewport，供 CSS 预览计算相对变换。 */
+    commitLayerPaint(layer: Layer, snapshot?: ViewportSnapshot): void;
+    /** @internal Layer 停用时删除它最近的真实绘制快照。 */
+    forgetLayer(layer: Layer): void;
+    /** 为已有真实绘制的 Layer 应用短暂 CSS 预览。 */
+    private applyCssTransform;
+    /** 结束 CSS 快速预览并请求真实 Canvas 重绘。 */
+    flushCssTransform(): void;
+    /** 清除所有 Layer 的 CSS 预览和自动刷新定时器。 */
+    private clearCssTransform;
+    private cancelCssTransformTimer;
+    /** 停止当前 focus Tween，但不改变已有 Viewport 状态。 */
+    private stopFocusAnimation;
+    /** @internal 清理 CSS 预览计时器和 focus Tween。 */
+    dispose(): void;
+    /** 导出 Viewport 平移、缩放和缩放范围。 */
+    toJSON(): {
+        /** 水平平移，单位为容器 CSS 像素。 */
+        x: number;
+        /** 垂直平移，单位为容器 CSS 像素。 */
+        y: number;
+        /** world 到容器 CSS 像素的缩放倍率。 */
+        scale: number;
+        /** 允许的最小缩放倍率。 */
+        minScale: number;
+        /** 允许的最大缩放倍率。 */
+        maxScale: number;
+    };
+}

package/dist/skin.d.ts

@@ -0,0 +1,117 @@
+import type { BackgroundColor } from "@fulate/share";
+import type { ShadowOption } from "./node/shape";
+import type { Root } from "./root";
+/** Core 文本组件共享的皮肤配置。 */
+export interface TextStyleConfig {
+    /** 文本填充颜色或渐变，默认 `"#000000"`。 */
+    color?: BackgroundColor;
+    /** 字号，单位为逻辑像素，默认 `14`。 */
+    fontSize?: number;
+    /** CSS 字体族，默认 `"Arial"`。 */
+    fontFamily?: string;
+    /** CSS 字重，默认 `"normal"`。 */
+    fontWeight?: string | number;
+    /** CSS 字体样式，默认 `"normal"`。 */
+    fontStyle?: string;
+    /** 文本行的水平对齐方式，默认 `"center"`。 */
+    textAlign?: "left" | "center" | "right";
+    /** Canvas 文本基线，默认 `"top"`。 */
+    textBaseline?: CanvasTextBaseline;
+    /** 文本块在元素内的垂直对齐方式，默认 `"middle"`。 */
+    verticalAlign?: "top" | "middle" | "bottom";
+    /** 是否绘制下划线，默认 `false`。 */
+    underline?: boolean;
+    /** 是否绘制删除线，默认 `false`。 */
+    strikethrough?: boolean;
+    /** 字号的行高倍数，默认 `1.5`。 */
+    lineHeight?: number;
+    /** 是否按可用宽度换行，默认 `false`。 */
+    wordWrap?: boolean;
+    /** 最大显示行数；`0` 表示不限制，默认 `0`。 */
+    maxLines?: number;
+    /** 字符间距，单位为逻辑像素，默认 `0`。 */
+    letterSpacing?: number;
+    /** 文字描边颜色或渐变，空字符串表示不描边。 */
+    textStrokeColor?: BackgroundColor;
+    /** 文字描边宽度，单位为逻辑像素，默认 `0`。 */
+    textStrokeWidth?: number;
+    /** 文字阴影；`null` 表示无阴影，默认 `null`。 */
+    textShadow?: ShadowOption | null;
+}
+/** Skin 构造参数；省略字段使用 Fulate 当前默认外观。 */
+export interface SkinOptions {
+    /** Shape 未显式配置时使用的填充，默认 `null`。 */
+    shapeFill?: BackgroundColor | null;
+    /** Shape 未显式配置时使用的描边，默认 `null`。 */
+    shapeStroke?: BackgroundColor | null;
+    /** Line 和 LineTree 未显式配置时使用的线色，默认 `"#333333"`。 */
+    lineStroke?: string;
+    /** 选择、hover、控制点和编辑器确认态共用的颜色，默认 `"#4F81FF"`。 */
+    selection?: string;
+    /** Text 未显式配置时使用的完整文字样式。 */
+    text?: TextStyleConfig;
+}
+/** 当前版本唯一的内置皮肤默认值。 */
+export declare const SKIN_DEFAULTS: {
+    readonly shapeFill: any;
+    readonly shapeStroke: any;
+    readonly lineStroke: "#333333";
+    readonly selection: "#4F81FF";
+    readonly text: {
+        readonly color: "#000000";
+        readonly fontSize: 14;
+        readonly fontFamily: "Arial";
+        readonly fontWeight: "normal";
+        readonly fontStyle: "normal";
+        readonly textAlign: "center";
+        readonly textBaseline: "top";
+        readonly verticalAlign: "middle";
+        readonly underline: false;
+        readonly strikethrough: false;
+        readonly lineHeight: 1.5;
+        readonly wordWrap: false;
+        readonly maxLines: 0;
+        readonly letterSpacing: 0;
+        readonly textStrokeColor: "";
+        readonly textStrokeWidth: 0;
+        readonly textShadow: any;
+    };
+};
+/** Skin 变化影响的消费范围。 */
+export type SkinChange = "paint" | "text";
+/** Root 共享且可继承的皮肤；直接修改属性会通知所有当前 consumer。 */
+export declare class Skin {
+    private shapeFillValue;
+    private shapeStrokeValue;
+    private lineStrokeValue;
+    private selectionValue;
+    /** @internal 当前直接采用此 Skin 的 Root。 */
+    root: Root | null;
+    /** 可直接修改并自动更新文字布局和绘制的 Text 默认样式。 */
+    readonly text: Required<TextStyleConfig>;
+    /** 创建一份独立 Skin；各结构化字段值按原引用采用。 */
+    constructor(options?: SkinOptions);
+    /** Shape 未显式配置时使用的填充。 */
+    get shapeFill(): BackgroundColor;
+    /** 安装 Shape 默认填充并触发当前 consumer 重绘。 */
+    set shapeFill(value: BackgroundColor);
+    /** Shape 未显式配置时使用的描边。 */
+    get shapeStroke(): BackgroundColor;
+    /** 安装 Shape 默认描边并触发当前 consumer 重绘。 */
+    set shapeStroke(value: BackgroundColor);
+    /** Line 和 LineTree 未显式配置时使用的线色。 */
+    get lineStroke(): string;
+    /** 安装 Line 默认线色并触发当前 consumer 重绘。 */
+    set lineStroke(value: string);
+    /** 选择、hover、控制点和编辑器确认态共用的颜色。 */
+    get selection(): string;
+    /** 安装选择颜色并触发当前 consumer 重绘。 */
+    set selection(value: string);
+    /** 子类 setter 在安装自己的新值后调用，默认只影响绘制。 */
+    protected changed(change?: SkinChange): void;
+    /**
+     * 返回可独立持久化的当前内置 Skin 字段。
+     * 子类新增的持久化字段由子类覆写并追加。
+     */
+    toJSON(): Required<SkinOptions>;
+}

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

@@ -0,0 +1,79 @@
+import type { Edge, PointView } from "@fulate/share";
+import type { Element } from "../node/element";
+/** Element owner 内稳定、由调用者直接提供的普通字符串 Port ID。 */
+export type ConnectionPortId = string;
+/** Port 在连接关系中的可用方向。 */
+export type ConnectionPortDirection = "input" | "output" | "both";
+/** 一个方向允许单连接或多连接。 */
+export type ConnectionPortLimit = "single" | "multiple";
+/** Port 入、出方向各自的连接数量限制。 */
+export interface ConnectionPortLimits {
+    readonly input?: ConnectionPortLimit;
+    readonly output?: ConnectionPortLimit;
+}
+/** Port 标签的可选文字样式。 */
+export interface ConnectionPortLabelStyle {
+    readonly fontSize?: number;
+    readonly color?: string;
+    readonly fontFamily?: string;
+    readonly fontWeight?: string | number;
+}
+/** 当前产品支持的边位置。 */
+export interface EdgeConnectionPortPosition {
+    readonly edge: Edge;
+    readonly ratio: number;
+}
+/** 由业务数据声明的 owner-local custom Port。 */
+export interface ConnectionPortDefinition {
+    readonly id: ConnectionPortId;
+    readonly position: EdgeConnectionPortPosition;
+    readonly name?: string;
+    readonly label: string;
+    readonly labelWidth?: number;
+    readonly labelStyle?: ConnectionPortLabelStyle;
+    readonly multiLine?: boolean;
+    readonly direction?: ConnectionPortDirection;
+    readonly connectionLimit?: ConnectionPortLimits;
+    readonly keepLabelUpright?: boolean;
+}
+/** Element authored Port 配置；默认 Port 必须显式启用。 */
+export type ConnectionPortConfiguration = false | true | readonly ConnectionPortDefinition[];
+/** 跨元素引用一个稳定 Port。 */
+export interface ConnectionPortRef {
+    readonly elementKey: string;
+    readonly portId: ConnectionPortId;
+}
+/** Element 类型自有的 derived Port 定位器。 @internal */
+export interface DerivedConnectionPort {
+    readonly id: ConnectionPortId;
+    /** 按当前 Element 的本地几何返回 Port 位置。 */
+    localPosition(element: Element): PointView;
+}
+/** owner 当前一次直接解析出的 Port。 */
+export interface ResolvedConnectionPort {
+    readonly ref: ConnectionPortRef;
+    readonly kind: "endpoint-binding";
+    readonly localPosition: PointView;
+    readonly origin: "builtin" | "custom";
+    readonly definition?: ConnectionPortDefinition;
+}
+/** custom Port decoration 需要的边布局信息。 @internal */
+export interface ResolvedConnectionPortSlot extends ResolvedConnectionPort {
+    readonly origin: "custom";
+    readonly definition: ConnectionPortDefinition;
+    readonly edge: Edge;
+    readonly ratio: number;
+    readonly edgeCount: number;
+}
+/** top、right、bottom、left 四条逻辑边中点组成的默认 Port。 */
+export declare const DEFAULT_CONNECTION_PORT_SCHEMA: readonly DerivedConnectionPort[];
+/** 直接从 custom definitions 解析当前 local Port；不缓存、复制或改写输入。 */
+export declare function resolveConnectionPortSlots(element: Element, definitions: readonly ConnectionPortDefinition[]): readonly ResolvedConnectionPortSlot[];
+/** 将 local 点投影到当前已提交 world matrix。 */
+export declare function projectConnectionPortPoint(matrix: DOMMatrixReadOnly, point: PointView): PointView;
+/** 按 owner-local ID 读取一个已知 Port；不受发现开关影响。 */
+export declare function getElementConnectionPort(element: Element, portId: ConnectionPortId): ResolvedConnectionPort | undefined;
+/** 返回一个 Port 的当前 committed world 坐标。 */
+export declare function getElementConnectionPortPoint(element: Element, portId: ConnectionPortId): PointView | undefined;
+/** 返回 owner 全部 Port 的当前 committed world 投影。 */
+export declare function getElementConnectionPortPoints(element: Element): Array<ResolvedConnectionPort & PointView>;

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@fulate/core",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --config vitest.config.ts"
+  },
+  "dependencies": {
+    "@fulate/share": "*",
+    "@tweenjs/tween.js": "^25.0.0",
+    "lodash-es": "^4.17.22",
+    "rbush": "^4.0.1"
+  },
+  "devDependencies": {
+    "@types/rbush": "^4.0.0"
+  }
+}