@fulate/core 1.0.0

package/dist/node/element.d.ts

@@ -0,0 +1,294 @@
+import type { Edge, PointView, Rect } from "@fulate/share";
+import { type EventOptionKey, type FulateEvent } from "../event";
+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 { Root } from "../root";
+import type { Layer } from "../layer";
+import type { OwnerPropertyChange } from "../mutation/change-batch";
+type ElementEventOptions<T> = {
+    [K in EventOptionKey]?: (this: T, event: FulateEvent<T>) => any;
+};
+/** 任意 Properties 和 Options 的 Element。 */
+export type AnyElement = Element<any, any, any>;
+/** 所有 Element 共用的构造选项。 */
+export interface BaseElementOption<T = Element> extends TransformableOptions, ElementEventOptions<T> {
+    /** hover 时写入 Root 容器的 CSS cursor。 */
+    cursor?: string;
+    /** 是否绘制并参与命中。 */
+    visible?: boolean;
+    /** 编辑器选择策略是否可选择该元素。 */
+    selectable?: boolean;
+    /** 是否让整个结构分支退出指针输入。 */
+    silent?: boolean;
+    /** 当前元素自身是否可成为指针命中目标。 */
+    pickable?: boolean;
+    /** children 是否可溢出自身边界；默认 `"visible"`。 */
+    overflow?: "visible" | "hidden";
+    /** Port whole-value；省略/`false` 无 Port，`true` 使用默认 schema，数组为 custom schema。 */
+    ports?: ConnectionPortConfiguration;
+    /** 初始 children。 */
+    children?: readonly AnyElement[];
+}
+/** `setOptions()` 接受的普通运行时补丁。 */
+export type ElementOptionPatch<O extends BaseElementOption<any> = BaseElementOption> = Partial<Omit<O, "key" | "children">>;
+type EventHandlerKey<O> = {
+    [K in keyof O]: K extends `on${string}` ? K : never;
+}[keyof O];
+/** Element 的可序列化属性和递归 children。 */
+export type ElementJSON<O extends BaseElementOption<any> = BaseElementOption<any>> = Omit<O, "children" | "key" | "type" | EventHandlerKey<O>> & {
+    /** 构造时确定并由 serializer 显式写出的节点 key。 */
+    readonly key: string;
+    /** 序列化节点类型。 */
+    type: string;
+    /** 递归序列化的 children。 */
+    children?: ElementJSON[];
+};
+/** @internal Core publisher 在零写入阶段完成的 owner commit 数据。 */
+export interface PreparedElementPropertyCommit {
+    readonly update: PreparedPropertyUpdate;
+    readonly impact: ChangeImpact;
+    readonly previousVisualBounds: Readonly<import("@fulate/share").BoundingBox> | null | undefined;
+}
+export { ChangeImpact } from "./properties";
+/** `animate()` 的 Tween 选项。 */
+export interface AnimateOptions<T = any> {
+    /** 持续时间，单位为毫秒，默认 `300`。 */
+    duration?: number;
+    /** 进度缓动函数。 */
+    easing?: (amount: number) => number;
+    /** 延迟时间，单位为毫秒，默认 `0`。 */
+    delay?: number;
+    /** 额外重复次数，默认 `0`。 */
+    repeat?: number;
+    /** 重复时是否反向播放，默认 `false`。 */
+    yoyo?: boolean;
+    /** 动画正常完成后的回调。 */
+    onComplete?: (v: T) => void;
+    /** 每次属性提交后的回调。 */
+    onUpdate?: (v: T) => void;
+}
+/** 从 Options 中选出可动画的数值与颜色属性。 */
+export type AnimateTarget<O> = {
+    [K in keyof O as K extends "key" ? never : NonNullable<O[K]> extends number ? K : K extends string ? Lowercase<K> extends `${string}color${string}` ? K : never : never]?: NonNullable<O[K]> extends number ? Extract<O[K], number> : O[K];
+};
+/** Element 事件选项合并到属性快照后的类型。 */
+export interface ElementProperties extends ElementEventOptions<Element> {
+}
+/** Element 的显示、输入、Port 和事件属性状态。 */
+export declare class ElementProperties extends TransformProperties {
+    /** hover 时使用的 CSS cursor。 */
+    cursor?: string;
+    /** 是否绘制并参与命中。 */
+    visible: boolean;
+    /** 编辑器选择策略是否可选择该元素。 */
+    selectable?: boolean;
+    /** 是否让整个结构分支退出指针输入。 */
+    silent: boolean;
+    /** 当前元素自身是否可成为指针命中目标。 */
+    pickable: boolean;
+    /** children 是否可溢出自身边界。 */
+    overflow: "visible" | "hidden";
+    /** 当前采用的 Port whole-value；默认不启用 Port。 */
+    ports: ConnectionPortConfiguration;
+    /** 创建 Element 属性；结构化字段直接采用输入引用。 */
+    constructor(options?: BaseElementOption);
+    /** @internal 合并显示、输入和事件属性的提交影响。 */
+    getImpact(changes: PropertyChanges): ChangeImpact;
+}
+/** 可变换、可绘制、可命中并支持事件和动画的场景节点。 */
+export declare class Element<P extends ElementProperties = ElementProperties, O extends BaseElementOption<any> = BaseElementOption<any>, Patch extends object = ElementOptionPatch<O>> extends Node<P, AnyElement> {
+    readonly type: string;
+    /** 当前 Element 唯一的变换与几何运行时。 */
+    readonly transform: ElementTransform<this>;
+    /** @internal Layer 内用于绘制顺序命中的已提交树序号。 */
+    committedPaintOrder: number;
+    /** hover 时使用的 CSS cursor。 */
+    get cursor(): string;
+    /** 是否绘制并参与命中。 */
+    get visible(): boolean;
+    /** 编辑器选择策略是否可选择该元素。 */
+    get selectable(): boolean;
+    /** 是否让整个结构分支退出指针输入。 */
+    get silent(): boolean;
+    /** 当前元素自身是否可成为指针命中目标。 */
+    get pickable(): boolean;
+    /** children 是否可溢出自身边界。 */
+    get overflow(): "visible" | "hidden";
+    /** 当前元素是否位于 Root 的 hover path 中。 */
+    get isHover(): boolean;
+    /** 相对 parent child 坐标空间的 x 位移。 */
+    get left(): number;
+    /** 相对 parent child 坐标空间的 y 位移。 */
+    get top(): number;
+    /** 顺时针旋转角度，单位为度。 */
+    get angle(): number;
+    /** x 轴缩放。 */
+    get scaleX(): number;
+    /** y 轴缩放。 */
+    get scaleY(): number;
+    /** x 轴错切角度，单位为度。 */
+    get skewX(): number;
+    /** y 轴错切角度，单位为度。 */
+    get skewY(): number;
+    /** x 方向变换原点。 */
+    get originX(): import("./properties").OriginX;
+    /** y 方向变换原点。 */
+    get originY(): import("./properties").OriginY;
+    /** Editor 旋转中心的 x 轴位置。 */
+    get rotationPivotX(): import("./properties").OriginX;
+    /** Editor 旋转中心的 y 轴位置。 */
+    get rotationPivotY(): import("./properties").OriginY;
+    /** 当前已解析宽度。 */
+    get width(): number;
+    /** 当前已解析高度。 */
+    get height(): number;
+    /** 未指定宽度时是否匹配 parent 宽度。 */
+    get fitWidth(): boolean;
+    /** 未指定高度时是否匹配 parent 高度。 */
+    get fitHeight(): boolean;
+    /** 当前采用的 Port whole-value；`true` 使用默认 schema。 */
+    get ports(): ConnectionPortConfiguration;
+    /** @internal 订阅实际 Ports authored commit；返回同一 observer 的注销函数。 */
+    observePortsCommit(observer: (element: Element) => void): () => void;
+    /**
+     * 采用 Port whole-value；数组由 Core 直接采用原引用。
+     * @param value `false`、`true` 或 custom definitions。
+     */
+    replacePorts(value: ConnectionPortConfiguration): this;
+    /**
+     * 恢复完整属性快照，并为 Port 变化派发事件。
+     * @param snapshot 之前由 `properties.snapshot()` 返回的快照。
+     */
+    restorePropertySnapshot(snapshot: Record<string, unknown>): this;
+    /** 首次创建动画时才安装的未结束任务集合。 */
+    private activeAnimations?;
+    /** 首次出现 `on*` handler 时才安装的监听 wrapper 映射。 */
+    private optionEventWrappers?;
+    /** 只在真实 dependent 存在时创建的内部 Ports commit observers。 */
+    private portsCommitObservers?;
+    private connectionPortProjectionReady;
+    private connectionPortProjectionSource;
+    private connectionPortProjectionRevision;
+    private connectionPortProjection;
+    private connectionPortSlots;
+    /** 创建带显示、输入、锚点和可选 children 的元素。 */
+    constructor(options?: NoInfer<O>, properties?: P, Transform?: ElementTransformClass);
+    /** raw parent link 变化只标记 transform local commit。 */
+    protected onParentChanged(): void;
+    /** raw children 完整安装后的 transform hook。 */
+    protected onChildrenChanged(): void;
+    /** raw children、lifecycle 和 hook 完成后的 transform dirty publication。 */
+    protected onStructureDirty(): void;
+    /** 激活时将未结束动画接入当前 Root。 */
+    protected onActivate(root: Root | null, layer: Layer | null): void;
+    /** 停用时从 Root 解除动画并结束未恢复的会话。 */
+    protected onDeactivate(root: Root | null, layer: Layer | null): void;
+    /** 卸载时停止当前元素的全部动画。 */
+    protected onUnmount(): void;
+    /** 让确有语义转换的派生元素在最终 patch 上处理一次。 */
+    protected resolveOptions(options: Patch): Patch;
+    /**
+     * 创建只借用 typed patch 的 owner effect；batch 合并完成前不解析或复制值。
+     */
+    protected createPropertyChange(options: Patch): OwnerPropertyChange;
+    /** @internal 在 live write 前一次完成 changed-key diff、impact 和旧 bounds。 */
+    preparePropertyCommit(patch: Record<string, unknown>): PreparedElementPropertyCommit | null;
+    /** 把 source/effective changed-key delta finalize 为 direct/batch 共用记录。 */
+    private finalizePropertyUpdate;
+    /** @internal 无 callback 地安装 finalize 后的 source/effective fields。 */
+    installPropertyCommit(commit: PreparedElementPropertyCommit): void;
+    /** @internal 在全部 owner/tree 安装后同步 option event wrapper。 */
+    syncPropertyCommitEvents(commit: PreparedElementPropertyCommit): void;
+    /** @internal 在全部 owner/tree 安装及 lifecycle 后运行 owner hook。 */
+    runPropertyCommitHook(commit: PreparedElementPropertyCommit): void;
+    /** @internal 在 owner hook 后通知依赖实际 Ports commit 的框架消费者。 */
+    notifyPortsCommit(commit: PreparedElementPropertyCommit): void;
+    /** @internal 在内部 publication 完成后派发 authored `portschange`。 */
+    dispatchPortsChange(commit: PreparedElementPropertyCommit): void;
+    /** @internal 使用 finalize 已有 impact 登记 dirty，并按 direct 语义通知场景。 */
+    publishPropertyCommit(commit: PreparedElementPropertyCommit, notifyScene: boolean, publishRootImpact?: boolean): void;
+    /** 应用一份 direct configured/runtime update 并完成一次成功路径 publication。 */
+    private commitPreparedProperty;
+    private commitConfiguredOptions;
+    private prepareRuntimeCommit;
+    /** 将 `on*` 属性变化同步到 EventEmitter listener。 */
+    private syncOptionEvents;
+    /** 属性提交后的派生类扩展点。 */
+    protected onPropertiesChanged(_current: P, _changes: PropertyChanges): void;
+    /** 把非 geometry impact 路由到绘制、Layer 顺序和 hover 队列。 */
+    private invalidate;
+    /** 返回在当前元素 local 坐标系中对 children 生效的裁剪区域。 */
+    getChildClipRect(): Readonly<Rect> | null;
+    /** 判断 local 点是否通过当前元素绘制 children 时使用的裁剪。 */
+    containsChildClipPoint(point: PointView): boolean;
+    /** 将当前元素绘制到给定上下文。 */
+    paint(ctx?: CanvasRenderingContext2D): void;
+    /** 按当前 Layer 提交状态绘制可见 children。 */
+    protected paintChildren(ctx: CanvasRenderingContext2D): void;
+    /** 将 Canvas 切换到当前元素的 local 绘制坐标系。 */
+    protected applyPaintTransform(ctx: CanvasRenderingContext2D): void;
+    /** 使用当前元素的矩形边界裁剪 children。 */
+    protected applyChildClip(ctx: CanvasRenderingContext2D): void;
+    /** 绘制默认 hover 轮廓。 */
+    paintHover(ctx: CanvasRenderingContext2D, scale: number): void;
+    /** 从当前 live owner 直接解析一次可连接 Ports。 */
+    getConnectionPorts(): readonly ResolvedConnectionPort[];
+    private resolveCurrentConnectionPortProjection;
+    /** 直接解析一个当前 Port，不 materialize 其余 Ports。 */
+    getConnectionPort(portId: string): ResolvedConnectionPort | undefined;
+    /** @internal 按给定 whole-value 解析 Port replacement 的最终投影。 */
+    resolveConnectionPorts(ports: ConnectionPortConfiguration): readonly ResolvedConnectionPort[];
+    /** 返回元素类型自有的默认 Port；`null` 使用通用四边 Ports。 */
+    protected getDefaultConnectionPortSchema(): readonly DerivedConnectionPort[] | null;
+    /** 返回 custom Ports 的当前 decoration slots。 @internal */
+    getResolvedConnectionPortSlots(): readonly ResolvedConnectionPortSlot[];
+    /**
+     * 返回矩形指定边和比例对应的 local Port 点。
+     * @param edge 要查询的逻辑边。
+     * @param ratio 从边起点到终点的比例，通常在 `0..1`。
+     */
+    getConnectionPortPosition(edge: Edge, ratio: number): PointView;
+    /** @internal 一次借用 owner 当前 configured source 的指定字段。 */
+    static readConfiguredPropertyValues(owner: Element, targets: ReadonlyMap<string, {
+        value: unknown;
+    }>): void;
+    /** @internal 借用 owner 当前 configured source 的单个字段。 */
+    protected static getConfiguredPropertyValue(owner: Element, key: string): any;
+    /**
+     * 提交需要持久化的配置属性补丁。
+     * @param options 要修改的属性；省略时不修改，字段为 `undefined` 时恢复默认值。
+     * 数组、对象等结构化字段按原引用采用；需要输入隔离时由调用者在传入前复制。
+     */
+    setOptions(options?: Patch): this;
+    /**
+     * 合并只影响当前显示、不会进入持久化结果的属性覆盖。
+     * @param patch 字段省略时保持现有覆盖；字段为 `undefined` 时清除该字段覆盖。
+     * 结构化字段与 configured writer 一样按原引用采用。
+     */
+    setRuntimeOptions(patch: Patch): this;
+    /** 显式清除指定或全部运行态属性覆盖。 */
+    clearRuntimeOptions<Key extends keyof Patch>(keys?: readonly Key[]): this;
+    /**
+     * 在当前 Root 动画组中补间数值和颜色属性。
+     * @param to 动画结束时的属性值。
+     * 结构化 target 会保留并在更新时采用同一引用，不生成调用方隔离快照。
+     * @param options 时长、缓动、重复和回调；省略时使用默认配置。
+     */
+    animate(to: AnimateTarget<O>, options?: AnimateOptions<this>): Promise<void> & {
+        /** 当前动画使用的底层 Tween。 */
+        tween: Tween<any>;
+    };
+    /** 停止并清除当前元素的全部动画。 */
+    stopAnimations(): void;
+    /** 将当前元素的全部动画推进到结束状态。 */
+    finishAnimations(): void;
+    /** 暂停当前元素的全部动画。 */
+    pauseAnimations(): void;
+    /** 恢复当前元素的全部动画。 */
+    resumeAnimations(): void;
+    /** 返回不含事件处理器的递归可序列化快照。 */
+    toJSON(): ElementJSON<O>;
+}

package/dist/node/node.d.ts

@@ -0,0 +1,156 @@
+import { EventEmitter } from "../event";
+import type { Root } from "../root/index";
+import type { Layer } from "../layer/index";
+import { NodeProperties } from "./properties";
+/** 所有 Node 共用的创建期身份选项。 */
+export interface NodeCreationOptions {
+    /** 场景内唯一 key；省略时由 Core 自动生成。 */
+    readonly key?: string;
+}
+/** Node 派发的非冒泡生命周期事件名。 */
+export declare enum NodeLifecycleEvent {
+    /** 首次完成 mount 初始化。 */
+    Mounted = "mounted",
+    /** 进入活动 Root/Layer 上下文。 */
+    Activated = "activated",
+    /** 离开活动 Root/Layer 上下文。 */
+    Deactivated = "deactivated",
+    /** 完成不可逆卸载。 */
+    Unmounted = "unmounted"
+}
+/** 提供场景树所有权、生命周期、key 索引和上下文继承的基础节点。 */
+export declare class Node<P extends NodeProperties = NodeProperties, Child extends Node<any, any> = Node<any, any>> extends EventEmitter {
+    #private;
+    /** 序列化使用的节点类型。 */
+    readonly type: string;
+    /** 返回构造期间确定的唯一场景 key。 */
+    get key(): string;
+    /** 当前由节点拥有的规范化属性状态。 */
+    protected readonly propertyState: P;
+    /** 当前属性的只读视图。 */
+    get properties(): Readonly<P>;
+    /** 结构 parent；只读使用，通过树操作修改。 */
+    parent: Node | undefined;
+    /** 当前节点直接拥有的 children 快照。 */
+    private childNodes;
+    /** 当前稳定生命周期状态。 */
+    private lifecycleState;
+    /** 当前正在执行的生命周期阶段。 */
+    private lifecycleCommand;
+    /** 按结构顺序排列的只读 children 快照。 */
+    get children(): readonly Child[];
+    /** 下一个 sibling；只读使用，通过树操作维护。 */
+    nextSibling: Node | null;
+    /** 上一个 sibling；只读使用，通过树操作维护。 */
+    previousSibling: Node | null;
+    /** 是否已完成首次 mount 且尚未卸载。 */
+    get isMounted(): boolean;
+    /** 是否处于活动 Root/Layer 上下文。 */
+    get isActive(): boolean;
+    /** 是否已进入或完成不可逆卸载。 */
+    get isUnmounted(): boolean;
+    /** 当前节点提供并沿 parent 原型链继承的上下文。 */
+    provides: Record<PropertyKey, any>;
+    /** 当前活动 Root；非 active 时为 `null`。 @internal */
+    activeRoot: Root | null;
+    /** 当前活动 Layer；普通读取通过 `layer` getter。 */
+    private activeLayer;
+    /** 当前节点所属 Layer。 */
+    get layer(): Layer;
+    /** 当前节点所属 Root。 */
+    get root(): Root;
+    /** @internal 判断当前节点是否为 Layer。 */
+    isLayerNode(): this is Layer;
+    /** 第一个 child，没有时为 `null`。 */
+    get firstChild(): Child | null;
+    /** 最后一个 child，没有时为 `null`。 */
+    get lastChild(): Child | null;
+    /** 创建持有指定 Properties 和可选 children 的结构节点。 */
+    constructor(options?: NodeCreationOptions, properties?: P, children?: readonly Child[]);
+    /** 安装最终 children 引用，并在一次循环内更新全部 raw links。 */
+    private installChildren;
+    /** 建立结构所有权、上下文原型链和事件冒泡 parent。 */
+    private linkChild;
+    /** 解除结构所有权、sibling、上下文和事件冒泡关系。 */
+    private unlinkFromParent;
+    /** raw parent link 改变后的派生 owner 接缝。 */
+    protected onParentChanged(): void;
+    /** 直接 children 事务提交后的扩展点；构造期 children 不触发。 */
+    protected onChildrenChanged(): void;
+    /** 全部 raw links 安装后的结构 dirty publication 扩展点。 */
+    protected onStructureDirty(): void;
+    /** 在 children 提交后通知扩展点、Root 和 dirty 路径。 */
+    private markStructureDirty;
+    /** 安装一次最终 children，并在当前提交仍有效时发布结构变化。 */
+    private commitChildren;
+    /** @internal trusted batch 解除真实变化节点的旧 placement。 */
+    detachBatchParent(): void;
+    /** @internal 接收 trusted batch 转移所有权的最终 children 快照。 */
+    installBatchChildren(children: readonly Node[]): void;
+    /** @internal 在全部 tree placement 安装后同步最终 lifecycle context。 */
+    syncBatchPlacementLifecycle(): void;
+    /** @internal tree 已完整安装后登记当前 owner 的 dirty path。 */
+    publishBatchStructureDirty(): void;
+    /** @internal raw links 与 placement lifecycle 同步完成后运行结构 hook。 */
+    runBatchStructureHook(): void;
+    /** 从当前 owner 移除一个直接 child，可选择同时停用它。 */
+    private removeOwnChild;
+    /** 从旧 owner 分离 incoming child，并确认同步回调没有再次接管它。 */
+    private detachFromParent;
+    /** 分离 incoming nodes；只有同步回调改写归属时才创建过滤后的数组。 */
+    private adoptIncoming;
+    /** 统一实现 append/prepend/before/after 的移动和插入事务。 */
+    private insertAt;
+    /** 将节点移动或追加到 children 尾部。 */
+    append(...children: Child[]): this;
+    /** 将节点移动或插入到 children 头部。 */
+    prepend(...children: Child[]): this;
+    /** 将节点插入指定 child 之前；`null` 表示追加。 */
+    insertBefore(newChild: Child, refChild: Child | null): this;
+    /** 将节点插入指定 child 之后。 */
+    insertAfter(newChild: Child, refChild: Child): this;
+    /** 用一个可复用节点替换指定 child。 */
+    replaceChild(newChild: Child, oldChild: Child): this;
+    /** 原子替换完整 children 序列。 */
+    replaceChildren(...children: Child[]): this;
+    /** 将节点移动到当前节点之前。 */
+    before(...nodes: Node[]): this;
+    /** 将节点移动到当前节点之后。 */
+    after(...nodes: Node[]): this;
+    /** 移除但不卸载指定 children，使其仍可复用。 */
+    removeChild(...children: Child[]): this;
+    /** 在稳定状态间同步转换；同一 Node 转换期间的再次请求立即报错。 */
+    private transitionLifecycle;
+    /** 执行首次初始化和 Mounted 事件。 */
+    private mountNode;
+    /** 只有无 parent 或 parent 已 active 时才允许进入 active。 */
+    private canBeActivatedByOwner;
+    /** 首次挂载并在 owner 允许时激活当前子树；已卸载节点不可恢复。 */
+    mount(): void;
+    /** 首次 mount 扩展点；不得再次转换当前 Node 的生命周期。 */
+    protected onMount(): void;
+    /** 建立 Root/Layer 上下文、注册 key，并递归激活 children。 */
+    private activateNode;
+    /** 进入活动上下文的扩展点；不得再次转换当前 Node 的生命周期。 */
+    protected onActivate(_activeRoot: Root | null, _layer: Layer | null): void;
+    /** 清理输入、key、Layer 空间项、children 和派生类 active 状态。 */
+    private leaveActiveContext;
+    /** 离开 active 上下文并派发 Deactivated。 */
+    private deactivateNode;
+    /** 离开活动上下文的扩展点；不得再次转换当前 Node 的生命周期。 */
+    protected onDeactivate(_activeRoot: Root | null, _layer: Layer | null): void;
+    /** children 卸载前调用；不得再次转换当前 Node 的生命周期。 */
+    protected onBeforeUnmount(): void;
+    /** 释放派生 owner 前调用；不得再次转换当前 Node 的生命周期。 */
+    protected onUnmount(): void;
+    /** 递归执行不可逆卸载，并释放结构、上下文和监听器。 */
+    private unmountNode;
+    /** 只在本节点存在监听器时创建同步生命周期事件。 */
+    private dispatchLifecycleEvent;
+    /** 不可逆卸载当前子树并清理监听器；重复调用不执行额外工作。 */
+    unmount(): void;
+    /** 在当前节点上下文中提供值。 */
+    provide(key: PropertyKey, value: any): this;
+    /** 从当前节点或最近 ancestor 上下文读取值。 */
+    inject<T = any>(key: PropertyKey): T | undefined;
+}

package/dist/node/properties.d.ts

@@ -0,0 +1,174 @@
+import type { NodeCreationOptions } from "./node";
+declare const CONFIGURED_STATE: unique symbol;
+declare const RUNTIME_OVERRIDE_STATE: unique symbol;
+/** x 方向变换原点；数值 `0` 为中心，`-0.5/0.5` 为左右边。 */
+export type OriginX = "center" | "left" | "right" | number;
+/** y 方向变换原点；数值 `0` 为中心，`-0.5/0.5` 为上下边。 */
+export type OriginY = "center" | "top" | "bottom" | number;
+/** 将 origin 枚举或数值解析为以中心为零点的轴向比例。 */
+export declare function resolveOrigin(origin: OriginX | OriginY): number;
+/** 属性变化对下一次提交产生的按位影响。 */
+export declare enum ChangeImpact {
+    /** 无运行时影响。 */
+    None = 0,
+    /** 仅需重绘。 */
+    Paint = 1,
+    /** canonical local geometry 或 layout reference bounds 变化。 */
+    LocalGeometry = 2,
+    /** world 矩阵变化。 */
+    WorldTransform = 4,
+    /** 绘制边界或轮廓变化。 */
+    VisualBounds = 8,
+    /** 需要重新执行指针命中。 */
+    Hover = 16,
+    /** 内容或 border 的命中几何变化。 */
+    HitBounds = 32,
+    /** Layer zIndex 或 Root Canvas 顺序变化。 */
+    LayerOrder = 64
+}
+export declare function clonePropertyValue<T>(value: T): T;
+/** 属性名到修改前值的只读变化表。 */
+export type PropertyChanges = ReadonlyMap<string, unknown>;
+/** 属性名到本次提交最终值的只读变化表。 */
+export type PropertyUpdates = ReadonlyMap<string, unknown>;
+/** 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;
+/** @internal 一次借用同一 owner 多个字段的当前 configured source。 */
+export declare function readConfiguredPropertyValues(properties: NodeProperties, targets: ReadonlyMap<string, {
+    value: unknown;
+}>): void;
+/** @internal 只为动画读取 requested keys 的 configured start 与 target 引用。 */
+export declare function preparePropertyAnimationValues(properties: NodeProperties, patch: Record<string, unknown>, keys: readonly string[]): {
+    start: Record<string, unknown>;
+    target: Record<string, unknown>;
+};
+export type PropertySource = "configured" | "runtime";
+/** @internal 一项 source/effective changed-key 的 install-ready 数据。 */
+export interface PreparedPropertyField {
+    readonly key: string;
+    readonly sourceRecordBefore: boolean;
+    readonly sourceRecordAfter: boolean;
+    readonly beforeSource: unknown;
+    readonly afterSource: unknown;
+    readonly sourceChanged: boolean;
+    readonly beforeValue: unknown;
+    readonly afterValue: unknown;
+    readonly valueChanged: boolean;
+    readonly installValue: boolean;
+}
+/** @internal direct 与 trusted batch 共用的最小 owner property delta。 */
+export interface PreparedPropertyUpdate {
+    readonly source: PropertySource;
+    readonly fields: readonly PreparedPropertyField[];
+    readonly changes: PropertyChanges;
+    readonly updates: PropertyUpdates;
+}
+/** @internal 解释 configured merge/reset，但不复制完整 source 或 Properties。 */
+export declare function prepareConfiguredPropertyUpdate(properties: NodeProperties, patch: Record<string, unknown>): PreparedPropertyUpdate;
+/** @internal 解释 runtime merge 与 own-undefined clear。 */
+export declare function prepareRuntimePropertyUpdate(properties: NodeProperties, patch: Record<string, unknown>): PreparedPropertyUpdate;
+/** @internal 把指定或全部 runtime keys 解释为同一 clear delta。 */
+export declare function prepareRuntimePropertyClear(properties: NodeProperties, keys?: readonly PropertyKey[]): PreparedPropertyUpdate;
+/** @internal 安装已经 finalize 的 changed source fields 与 effective values。 */
+export declare function installPropertyUpdate(properties: NodeProperties, update: PreparedPropertyUpdate): void;
+/** Element 的作者变换和尺寸选项。 */
+export interface TransformableOptions extends NodeCreationOptions {
+    /** parent child 坐标中的 x 位移，默认 `0`。 */
+    left?: number;
+    /** parent child 坐标中的 y 位移，默认 `0`。 */
+    top?: number;
+    /** 顺时针旋转角度，单位为度，默认 `0`。 */
+    angle?: number;
+    /** 作者宽度；未设置时可由布局解析。 */
+    width?: number;
+    /** 作者高度；未设置时可由布局解析。 */
+    height?: number;
+    /** x 轴缩放，默认 `1`。 */
+    scaleX?: number;
+    /** y 轴缩放，默认 `1`。 */
+    scaleY?: number;
+    /** x 方向变换原点，默认 `center`。 */
+    originX?: OriginX;
+    /** y 方向变换原点，默认 `center`。 */
+    originY?: OriginY;
+    /** Editor 旋转中心的 x 轴位置，默认 `center`。 */
+    rotationPivotX?: OriginX;
+    /** Editor 旋转中心的 y 轴位置，默认 `center`。 */
+    rotationPivotY?: OriginY;
+    /** x 轴错切角度，单位为度，默认 `0`。 */
+    skewX?: number;
+    /** y 轴错切角度，单位为度，默认 `0`。 */
+    skewY?: number;
+    /** 未指定宽度时是否匹配 parent 宽度。 */
+    fitWidth?: boolean;
+    /** 未指定高度时是否匹配 parent 高度。 */
+    fitHeight?: boolean;
+}
+/** Element 的作者变换属性状态。 */
+export declare class TransformProperties extends NodeProperties {
+    /** parent child 坐标中的 x 位移。 */
+    left: number;
+    /** parent child 坐标中的 y 位移。 */
+    top: number;
+    /** 顺时针旋转角度，单位为度。 */
+    angle: number;
+    /** 作者宽度；未设置时由布局解析。 */
+    width?: number;
+    /** 作者高度；未设置时由布局解析。 */
+    height?: number;
+    /** x 轴缩放。 */
+    scaleX: number;
+    /** y 轴缩放。 */
+    scaleY: number;
+    /** x 方向变换原点。 */
+    originX: OriginX;
+    /** y 方向变换原点。 */
+    originY: OriginY;
+    /** Editor 旋转中心的 x 轴位置。 */
+    rotationPivotX: OriginX;
+    /** Editor 旋转中心的 y 轴位置。 */
+    rotationPivotY: OriginY;
+    /** x 轴错切角度，单位为度。 */
+    skewX: number;
+    /** y 轴错切角度，单位为度。 */
+    skewY: number;
+    /** 未指定宽度时是否匹配 parent 宽度。 */
+    fitWidth: boolean;
+    /** 未指定高度时是否匹配 parent 高度。 */
+    fitHeight: boolean;
+    /** 创建带声明默认值的作者变换属性。 */
+    constructor(options?: TransformableOptions);
+    /** @internal 将尺寸和标量变换变化映射为几何影响。 */
+    getImpact(changes: PropertyChanges): ChangeImpact;
+}
+export {};