@fulate/core 1.0.19 → 3.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,18 +1,20 @@
1
+ import { type PaintContext } from "../paint-context";
2
+ import { type PNGExportOptions, type PNGExportResult } from "../export-png";
1
3
  import type { Edge, PointView, Rect } from "@fulate/share";
2
4
  import { type EventOptionKey, type FulateEvent } from "../event";
3
5
  import { Node } from "./node";
4
6
  import { ElementTransform, type ElementTransformClass } from "./element-transform";
5
7
  import { ChangeImpact, TransformProperties, type PropertyChanges, type PreparedPropertyUpdate, type TransformableOptions } from "./properties";
6
8
  import { Tween } from "@tweenjs/tween.js";
7
- import type { ConnectionPortConfiguration, ConnectionPortGeometry, DerivedConnectionPort, ResolvedConnectionPort, ResolvedConnectionPortSlot } from "../utils/connection-port";
9
+ import type { ConnectionPortConfiguration, ConnectionPortGeometry, ResolvedConnectionPort, ResolvedConnectionPortSlot } from "../utils/connection-port";
8
10
  import type { Root } from "../root";
9
11
  import type { Layer } from "../layer";
10
12
  import type { OwnerPropertyChange } from "../mutation/change-batch";
11
13
  type ElementEventOptions<T> = {
12
- [K in EventOptionKey]?: (this: T, event: FulateEvent<T>) => any;
14
+ [K in EventOptionKey]?: (this: T, event: FulateEvent<K extends `on${string}Capture` ? AnyElement : T>) => any;
13
15
  };
14
16
  /** 任意 Properties 和 Options 的 Element。 */
15
- export type AnyElement = Element<any, any, any>;
17
+ export type AnyElement = Element<any, any, any, any>;
16
18
  /** 所有 Element 共用的构造选项。 */
17
19
  export interface BaseElementOption<T = Element> extends TransformableOptions, ElementEventOptions<T> {
18
20
  /** hover 时写入 Root 容器的 CSS cursor。 */
@@ -32,32 +34,27 @@ export interface BaseElementOption<T = Element> extends TransformableOptions, El
32
34
  /** 初始 children。 */
33
35
  children?: readonly AnyElement[];
34
36
  }
35
- /** `setOptions()` 接受的普通运行时补丁。 */
37
+ /** `setOptions()` 接受的 configured 属性补丁。 */
36
38
  export type ElementOptionPatch<O extends BaseElementOption<any> = BaseElementOption> = Partial<Omit<O, "key" | "children">>;
37
- type EventHandlerKey<O> = {
38
- [K in keyof O]: K extends `on${string}` ? K : never;
39
- }[keyof O];
40
- /** Element 的可序列化属性和递归 children。 */
41
- export type ElementJSON<O extends BaseElementOption<any> = BaseElementOption<any>> = Omit<O, "children" | "key" | "type" | EventHandlerKey<O>> & {
42
- /** 构造时确定并由 serializer 显式写出的节点 key。 */
39
+ /** One element's independent authored payload. Scene codecs own child recursion. */
40
+ export interface ElementPayload {
43
41
  readonly key: string;
44
- /** 序列化节点类型。 */
45
- type: string;
46
- /** 递归序列化的 children。 */
47
- children?: ElementJSON[];
48
- };
42
+ readonly type: string;
43
+ [property: string]: unknown;
44
+ }
49
45
  /** @internal Core publisher 在零写入阶段完成的 owner commit 数据。 */
50
46
  export interface PreparedElementPropertyCommit {
51
47
  readonly update: PreparedPropertyUpdate;
52
48
  readonly impact: ChangeImpact;
53
- readonly previousVisualBounds: Readonly<import("@fulate/share").BoundingBox> | null | undefined;
54
49
  }
55
50
  export { ChangeImpact } from "./properties";
56
51
  /** `animate()` 的 Tween 选项。 */
57
52
  export interface AnimateOptions<T = any> {
58
53
  /** 持续时间,单位为毫秒,默认 `300`。 */
59
54
  duration?: number;
60
- /** 进度缓动函数。 */
55
+ /**
56
+ * 只根据进度返回缓动结果;不提交场景或改变动画任务。
57
+ */
61
58
  easing?: (amount: number) => number;
62
59
  /** 延迟时间,单位为毫秒,默认 `0`。 */
63
60
  delay?: number;
@@ -65,12 +62,19 @@ export interface AnimateOptions<T = any> {
65
62
  repeat?: number;
66
63
  /** 重复时是否反向播放,默认 `false`。 */
67
64
  yoyo?: boolean;
68
- /** 动画正常完成后的回调。 */
65
+ /**
66
+ * 动画正常完成后的 R0 业务回调,可从当前状态发起下一合法操作。
67
+ */
69
68
  onComplete?: (v: T) => void;
70
- /** 每次属性提交后的回调。 */
69
+ /**
70
+ * 每次配置属性提交后的 R0 业务回调,可按动画 API 停止/完成当前任务。
71
+ */
71
72
  onUpdate?: (v: T) => void;
72
73
  }
73
- /** 从 Options 中选出可动画的数值与颜色属性。 */
74
+ type RuntimePropertyKeys<Patch> = {
75
+ [K in keyof Patch]-?: [Required<Patch>[K]] extends [never] ? never : K;
76
+ }[keyof Patch];
77
+ /** 从允许的属性输入中选出可动画的数值与颜色字段,保留显式禁用字段的 never 约束。 */
74
78
  export type AnimateTarget<O> = {
75
79
  [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];
76
80
  };
@@ -98,8 +102,8 @@ export declare class ElementProperties extends TransformProperties {
98
102
  /** @internal 合并显示、输入和事件属性的提交影响。 */
99
103
  getImpact(changes: PropertyChanges): ChangeImpact;
100
104
  }
101
- /** 可变换、可绘制、可命中并支持事件和动画的场景节点。 */
102
- export declare class Element<P extends ElementProperties = ElementProperties, O extends BaseElementOption<any> = BaseElementOption<any>, Patch extends object = ElementOptionPatch<O>> extends Node<P, AnyElement> {
105
+ /** 可变换、可绘制、可命中并支持事件和动画的场景节点。属性 writer 在 R0 安装输入。 */
106
+ export declare class Element<P extends ElementProperties = ElementProperties, O extends BaseElementOption<any> = BaseElementOption<any>, Patch extends object = ElementOptionPatch<O>, RuntimePatch extends object = Patch> extends Node<P, AnyElement> {
103
107
  readonly type: string;
104
108
  /** 当前 Element 唯一的变换与几何运行时。 */
105
109
  readonly transform: ElementTransform<this>;
@@ -135,22 +139,12 @@ export declare class Element<P extends ElementProperties = ElementProperties, O
135
139
  get originX(): import("./properties").OriginX;
136
140
  /** y 方向变换原点。 */
137
141
  get originY(): import("./properties").OriginY;
138
- /** Editor 旋转中心的 x 轴位置。 */
139
- get rotationPivotX(): import("./properties").OriginX;
140
- /** Editor 旋转中心的 y 轴位置。 */
141
- get rotationPivotY(): import("./properties").OriginY;
142
142
  /** 当前已解析宽度。 */
143
143
  get width(): number;
144
144
  /** 当前已解析高度。 */
145
145
  get height(): number;
146
- /** 未指定宽度时是否匹配 parent 宽度。 */
147
- get fitWidth(): boolean;
148
- /** 未指定高度时是否匹配 parent 高度。 */
149
- get fitHeight(): boolean;
150
146
  /** 当前采用的 Port whole-value;`true` 使用默认 schema。 */
151
147
  get ports(): ConnectionPortConfiguration;
152
- /** @internal 订阅实际 Ports authored commit;返回同一 observer 的注销函数。 */
153
- observePortsCommit(observer: (element: Element) => void): () => void;
154
148
  /**
155
149
  * 采用 Port whole-value;数组由 Core 直接采用原引用。
156
150
  * @param value `false`、`true` 或 custom definitions。
@@ -163,10 +157,6 @@ export declare class Element<P extends ElementProperties = ElementProperties, O
163
157
  restorePropertySnapshot(snapshot: Record<string, unknown>): this;
164
158
  /** 首次创建动画时才安装的未结束任务集合。 */
165
159
  private activeAnimations?;
166
- /** 首次出现 `on*` handler 时才安装的监听 wrapper 映射。 */
167
- private optionEventWrappers?;
168
- /** 只在真实 dependent 存在时创建的内部 Ports commit observers。 */
169
- private portsCommitObservers?;
170
160
  private connectionPortProjectionReady;
171
161
  private connectionPortProjectionSource;
172
162
  private connectionPortProjectionRevision;
@@ -174,76 +164,99 @@ export declare class Element<P extends ElementProperties = ElementProperties, O
174
164
  private connectionPortSlots;
175
165
  /** 创建带显示、输入、锚点和可选 children 的元素。 */
176
166
  constructor(options?: NoInfer<O>, properties?: P, Transform?: ElementTransformClass);
177
- /** raw parent link 变化只标记 transform local commit。 */
178
- protected onParentChanged(_previousParent?: Node): void;
179
- /** raw children 完整安装后的 transform hook。 */
180
- protected onChildrenChanged(): void;
181
- /** raw children、lifecycle 和 hook 完成后的 transform dirty publication。 */
182
- protected onStructureDirty(): void;
167
+ /** raw parent link 安装后登记当前路径的 transform 失效。 */
168
+ protected onParentInstalled(_previousParent?: Node): void;
169
+ /** @internal raw placement 改变前保留当前场景中的旧贡献。 */
170
+ captureBeforeDetach(): void;
171
+ /** raw children 安装后同步 Transform 派生输入与 dirty。 */
172
+ protected onChildrenInstalled(): void;
183
173
  /** 激活时将未结束动画接入当前 Root。 */
184
174
  protected onActivate(root: Root | null, layer: Layer | null): void;
185
175
  /** 停用时从 Root 解除动画并结束未恢复的会话。 */
186
176
  protected onDeactivate(root: Root | null, layer: Layer | null): void;
187
177
  /** 卸载时停止当前元素的全部动画。 */
188
178
  protected onUnmount(): void;
189
- /** 让确有语义转换的派生元素在最终 patch 上处理一次。 */
179
+ /**
180
+ * 从最终 typed patch 纯计算不可省略的语义转换;每次提交只解释一次。
181
+ * 此时 live state 尚未安装最终值;不能在解释中提交属性、改树或调用应用。
182
+ */
190
183
  protected resolveOptions(options: Patch): Patch;
191
184
  /**
192
185
  * 创建只借用 typed patch 的 owner effect;batch 合并完成前不解析或复制值。
193
186
  */
194
187
  protected createPropertyChange(options: Patch): OwnerPropertyChange;
195
- /** @internal 在 live write 前一次完成 changed-key diff、impact 和旧 bounds。 */
188
+ /** @internal 在 live write 前一次完成 changed-key diff 和 impact。 */
196
189
  preparePropertyCommit(patch: Record<string, unknown>): PreparedElementPropertyCommit | null;
197
190
  /** 把 source/effective changed-key delta finalize 为 direct/batch 共用记录。 */
198
191
  private finalizePropertyUpdate;
199
- /** @internal 无 callback 地安装 finalize 后的 source/effective fields。 */
192
+ /** @internal 全部 final delta 已确定、任何字段与结构链接安装前捕获一次旧贡献。 */
193
+ capturePropertyCommit(commit: PreparedElementPropertyCommit): void;
194
+ /** @internal 无 callback 地安装 source/effective fields。 */
200
195
  installPropertyCommit(commit: PreparedElementPropertyCommit): void;
201
- /** @internal 在全部 owner/tree 安装后同步 option event wrapper。 */
196
+ /** @internal 在全部 owner/tree 安装后同步 option event listener。 */
202
197
  syncPropertyCommitEvents(commit: PreparedElementPropertyCommit): void;
203
198
  /** @internal 在全部 owner/tree 安装及 lifecycle 后运行 owner hook。 */
204
199
  runPropertyCommitHook(commit: PreparedElementPropertyCommit): void;
205
- /** @internal 在 owner hook 后通知依赖实际 Ports commit 的框架消费者。 */
206
- notifyPortsCommit(commit: PreparedElementPropertyCommit): void;
207
200
  /** @internal 在内部 publication 完成后派发 authored `portschange`。 */
208
201
  dispatchPortsChange(commit: PreparedElementPropertyCommit): void;
209
- /** @internal 使用 finalize 已有 impact 登记 dirty,并按 direct 语义通知场景。 */
210
- publishPropertyCommit(commit: PreparedElementPropertyCommit, notifyScene: boolean, publishRootImpact?: boolean): boolean;
202
+ /** @internal 全部字段与链接安装后,先同步派生输入并登记失效;此轮不运行应用回调。 */
203
+ invalidatePropertyCommit(commit: PreparedElementPropertyCommit, publishRootImpact?: boolean): boolean;
211
204
  /** 应用一份 direct configured/runtime update 并完成一次成功路径 publication。 */
212
205
  private commitPreparedProperty;
213
- private commitConfiguredOptions;
206
+ /** Configured entry shared by setOptions, Port replacement and snapshot restore. */
207
+ protected commitConfiguredOptions(options: Patch): void;
214
208
  private prepareRuntimeCommit;
215
- /** 将 `on*` 属性变化同步到 EventEmitter listener。 */
209
+ /** 将实际 changed keys 同步到事件层,复用提交已有的修改前值。 */
216
210
  private syncOptionEvents;
217
- /** 属性提交后的派生类扩展点。 */
211
+ /**
212
+ * @internal 同步属性所依赖的本地缓存、原生布局输入和订阅。
213
+ * 所有 owner 完成本轮安装后才运行各自的变更 hooks;本接缝不得推进阶段或派发应用回调。
214
+ */
215
+ protected onPropertiesInstalled(_current: P, _changes: PropertyChanges): void;
216
+ /**
217
+ * R0 消费已安装的 effective 变化,处理本 owner 的领域状态与资源。
218
+ * 需要当前几何时可显式准备;真实领域应用事件按其独立合同执行。
219
+ */
218
220
  protected onPropertiesChanged(_current: P, _changes: PropertyChanges): void;
219
221
  /**
220
222
  * 作者配置实际变化后的扩展点,在 effective 属性 hook 之后运行。
221
223
  * runtime 遮罩不阻止此通知;runtime-only 更新和相同配置不触发。
222
224
  * changedKeys 只包含本次实际改变的 configured 字段;通过 configured reader 读取当前值。
223
- * direct、batch 和 History replay 使用同一阶段;可在此更新当前数据的 runtime 显示。
225
+ * direct、batch 和 History replay 使用同一阶段;可在此更新自身当前数据的 runtime 显示。
224
226
  */
225
227
  protected onConfiguredPropertiesChanged?(changedKeys: readonly string[]): void;
226
228
  /** 把非 geometry impact 路由到绘制、Layer 顺序和 hover 队列。 */
227
229
  private invalidate;
228
- /** 返回在当前元素 local 坐标系中对 children 生效的裁剪区域。 */
230
+ /** 返回 local children 裁剪区域。null 表示当前没有裁剪,包括空几何。 */
229
231
  getChildClipRect(): Readonly<Rect> | null;
230
232
  /** 判断 local 点是否通过当前元素绘制 children 时使用的裁剪。 */
231
233
  containsChildClipPoint(point: PointView): boolean;
232
234
  /** 将当前元素绘制到给定上下文。 */
233
- paint(ctx?: CanvasRenderingContext2D): void;
235
+ paint(paint: PaintContext): void;
234
236
  /** 按当前 Layer 提交状态绘制可见 children。 */
235
- protected paintChildren(ctx: CanvasRenderingContext2D): void;
236
- /** 将 Canvas 切换到当前元素的 local 绘制坐标系。 */
237
- protected applyPaintTransform(ctx: CanvasRenderingContext2D): void;
237
+ protected paintChildren(paint: PaintContext): void;
238
+ /** 同步内容接缝;Element 内容自行选择 local/world 变换,Shape 已建立 local 变换。 */
239
+ protected paintContent?(paint: PaintContext): void;
240
+ /**
241
+ * 导出当前活动子树;等待已有几何工作,复用当前内容与 bitmap,不等待资源加载或 Worker 新帧。
242
+ * 默认倍率 1、padding 0;未激活、不可见或无绘制区域返回 undefined。
243
+ * signal 取消和绘制/编码错误原样传播。已绘入 Canvas 的像素不再依赖 live 生命周期。
244
+ */
245
+ exportPNG(options?: PNGExportOptions): Promise<PNGExportResult | undefined>;
246
+ /** @internal 仅应用祖先对子树的裁剪/样式;不绘制祖先或兄弟。 */
247
+ protected applyExportAncestor(paint: PaintContext): void;
248
+ /** @internal 在已准备几何和资源上同步绘制;不交接屏幕像素责任。 */
249
+ paintExport(paint: PaintContext): void;
238
250
  /** 使用当前元素的矩形边界裁剪 children。 */
239
251
  protected applyChildClip(ctx: CanvasRenderingContext2D): void;
240
252
  /** 绘制默认 hover 轮廓。 */
241
253
  paintHover(ctx: CanvasRenderingContext2D, scale: number): void;
242
254
  /**
243
- * @internal 把与 `paintHover()` 等价的轮廓追加到当前 path,由调用方统一描边。
244
- * 返回 `false` 时调用方改用 `paintHover()` 独立绘制。
255
+ * @internal 把与 `paintHover()` 等价的世界坐标轮廓追加到调用方提供的 path。
256
+ * 本方法只追加轮廓;调用方负责合并路径并在 Viewport 变换下统一描边。
257
+ * 返回 `false` 时保持 path 不变,由调用方改用 `paintHover()` 独立绘制。
245
258
  */
246
- traceHoverOutline(_ctx: CanvasRenderingContext2D, _scale: number): boolean;
259
+ traceHoverOutline(_ctx: CanvasPath, _scale: number): boolean;
247
260
  /** 从当前 live owner 直接解析一次可连接 Ports。 */
248
261
  getConnectionPorts(): readonly ResolvedConnectionPort[];
249
262
  private resolveCurrentConnectionPortProjection;
@@ -251,8 +264,10 @@ export declare class Element<P extends ElementProperties = ElementProperties, O
251
264
  getConnectionPort(portId: string): ResolvedConnectionPort | undefined;
252
265
  /** @internal 只解释显式 Port replacement 的 IDs;patch 是同批最终 owner fields。 */
253
266
  resolveConnectionPortIds(ports: ConnectionPortConfiguration, patch?: Readonly<Record<string, unknown>>): readonly string[];
254
- /** 返回元素类型自有的默认 Port;`null` 使用通用四边 Ports。 */
255
- protected getDefaultConnectionPortSchema(_patch?: Readonly<Record<string, unknown>>): readonly DerivedConnectionPort[] | null;
267
+ /** 列出类型自有的默认 Port IDs;patch 是同批最终 owner fields。 */
268
+ protected getDefaultConnectionPortIds(_patch?: Readonly<Record<string, unknown>>): readonly string[];
269
+ /** 从 live geometry 纯计算一个默认 Port;不存在的 ID 返回 undefined。 */
270
+ protected getDefaultConnectionPortGeometry(portId: string): Pick<ResolvedConnectionPort, "localPosition" | "localNormal"> | undefined;
256
271
  /** 返回 custom Ports 的当前 decoration slots。 @internal */
257
272
  getResolvedConnectionPortSlots(): readonly ResolvedConnectionPortSlot[];
258
273
  /**
@@ -268,14 +283,14 @@ export declare class Element<P extends ElementProperties = ElementProperties, O
268
283
  * 读取包含默认值的 configured 结果,不读取 runtime 覆盖;保留 null/undefined。
269
284
  * cells 可复用;借用值不得原地修改并期待自动提交,需要独立值时由 caller 复制。
270
285
  */
271
- static readConfiguredPropertyValues(owner: Element, targets: ReadonlyMap<string, {
286
+ static readConfiguredPropertyValues(owner: AnyElement, targets: ReadonlyMap<string, {
272
287
  value: unknown;
273
288
  }>): void;
274
289
  /**
275
290
  * 借用当前字段的 configured/default 值,忽略 runtime 覆盖,保留 null/undefined。
276
291
  * 返回结构化原引用,不表示该字段是否曾被显式配置;需要独立值时由 caller 复制。
277
292
  */
278
- static getConfiguredPropertyValue(owner: Element, key: string): unknown;
293
+ static getConfiguredPropertyValue(owner: AnyElement, key: string): unknown;
279
294
  /**
280
295
  * 提交需要持久化的配置属性补丁。
281
296
  * @param options 要修改的属性;省略时不修改,字段为 `undefined` 时恢复默认值。
@@ -287,27 +302,29 @@ export declare class Element<P extends ElementProperties = ElementProperties, O
287
302
  * @param patch 字段省略时保持现有覆盖;字段为 `undefined` 时清除该字段覆盖。
288
303
  * 结构化字段与 configured writer 一样按原引用采用。
289
304
  */
290
- setRuntimeOptions(patch: Patch): this;
305
+ setRuntimeOptions(patch: RuntimePatch): this;
291
306
  /** 显式清除指定或全部运行态属性覆盖。 */
292
- clearRuntimeOptions<Key extends keyof Patch>(keys?: readonly Key[]): this;
307
+ clearRuntimeOptions<Key extends RuntimePropertyKeys<RuntimePatch>>(keys?: readonly Key[]): this;
293
308
  /**
294
309
  * 在当前 Root 动画组中补间数值和颜色属性。
295
310
  * @param to 动画结束时的属性值。
296
311
  * 结构化 target 会保留并在更新时采用同一引用,不生成调用方隔离快照。
297
312
  * @param options 时长、缓动、重复和回调;省略时使用默认配置。
298
313
  */
299
- animate(to: AnimateTarget<O>, options?: AnimateOptions<this>): Promise<void> & {
314
+ animate(to: AnimateTarget<RuntimePatch>, options?: AnimateOptions<this>): Promise<void> & {
300
315
  /** 当前动画使用的底层 Tween。 */
301
316
  tween: Tween<any>;
302
317
  };
303
318
  /** 停止并清除当前元素的全部动画。 */
304
319
  stopAnimations(): void;
305
- /** 将当前元素的全部动画推进到结束状态。 */
320
+ /** 将调用开始时的动画推进到结束状态;完成回调新建的动画继续正常运行。 */
306
321
  finishAnimations(): void;
307
322
  /** 暂停当前元素的全部动画。 */
308
323
  pauseAnimations(): void;
309
324
  /** 恢复当前元素的全部动画。 */
310
325
  resumeAnimations(): void;
311
- /** 返回不含事件处理器的递归可序列化快照。 */
312
- toJSON(): ElementJSON<O>;
326
+ /** The authored children included by scene serialization and clipboard. */
327
+ getPersistentChildren(): readonly AnyElement[];
328
+ /** Return this owner's independent authored payload, excluding events and children. */
329
+ toJSON(): ElementPayload;
313
330
  }
@@ -7,6 +7,8 @@ export interface NodeCreationOptions {
7
7
  /** 场景内唯一 key;省略时由 Core 自动生成。 */
8
8
  readonly key?: string;
9
9
  }
10
+ /** Node 与离线场景 producer 共用的唯一 key 生成器。 */
11
+ export declare function generateNodeKey(): string;
10
12
  /**
11
13
  * @internal 按同一棵树的 preorder 比较两个节点;祖先排在后代之前。只沿两条 parent 链走到
12
14
  * 最近公共祖先,比较其下两个 child 的 sibling 标签。
@@ -23,14 +25,29 @@ export declare enum NodeLifecycleEvent {
23
25
  /** 完成不可逆卸载。 */
24
26
  Unmounted = "unmounted"
25
27
  }
26
- /** 提供场景树所有权、生命周期、key 索引和上下文继承的基础节点。 */
28
+ declare module "../event" {
29
+ interface FulateEventMap {
30
+ mounted: CustomEvent<{
31
+ target: Node;
32
+ }>;
33
+ activated: CustomEvent<{
34
+ target: Node;
35
+ }>;
36
+ deactivated: CustomEvent<{
37
+ target: Node;
38
+ }>;
39
+ unmounted: CustomEvent<{
40
+ target: Node;
41
+ }>;
42
+ }
43
+ }
44
+ /** 提供场景树所有权、生命周期、key 索引和上下文继承。结构与生命周期入口在 R0 执行。 */
27
45
  export declare class Node<P extends NodeProperties = NodeProperties, Child extends Node<any, any> = Node<any, any>> extends EventEmitter {
28
- #private;
29
46
  /** 序列化使用的节点类型。 */
30
47
  readonly type: string;
31
- /** 返回构造期间确定的唯一场景 key。 */
32
- get key(): string;
33
- /** 当前由节点拥有的规范化属性状态。 */
48
+ /** Root 场景索引使用的构造期只读节点 key。 */
49
+ readonly key: string;
50
+ /** 当前由节点拥有的唯一属性状态,字段读取 effective 值。 */
34
51
  protected readonly propertyState: P;
35
52
  /** 当前属性的只读视图。 */
36
53
  get properties(): Readonly<P>;
@@ -40,8 +57,8 @@ export declare class Node<P extends NodeProperties = NodeProperties, Child exten
40
57
  private childNodes;
41
58
  /** 当前稳定生命周期状态。 */
42
59
  private lifecycleState;
43
- /** 当前正在执行的生命周期阶段。 */
44
- private lifecycleCommand;
60
+ /** 不可逆卸载已开始,children 和资源清理尚未完成。 */
61
+ private unmounting;
45
62
  /** 按结构顺序排列的只读 children 快照。 */
46
63
  get children(): readonly Child[];
47
64
  /** 下一个 sibling;只读使用,通过树操作维护。 */
@@ -83,23 +100,33 @@ export declare class Node<P extends NodeProperties = NodeProperties, Child exten
83
100
  private linkChild;
84
101
  /** 解除结构所有权、sibling、上下文和事件冒泡关系。 */
85
102
  private unlinkFromParent;
86
- /** raw parent link 改变后的派生 owner 接缝。 */
103
+ /** @internal 结构安装前由具有绘制贡献的节点保存旧范围。 */
104
+ captureBeforeDetach(): void;
105
+ /** @internal 所有 raw links 安装后同步本地派生输入;不得推进阶段或调用应用回调。 */
106
+ protected onParentInstalled(_previousParent?: Node): void;
107
+ /** @internal 所有 raw links 安装后同步 children 派生输入和 dirty。 */
108
+ protected onChildrenInstalled(): void;
109
+ /**
110
+ * R0 消费已安装的 parent 与派生输入,维护所属依赖、订阅和失效。
111
+ * 可显式准备几何后读取;不得在此同步重新挂载当前节点。
112
+ */
87
113
  protected onParentChanged(_previousParent?: Node): void;
88
- /** 直接 children 事务提交后的扩展点;构造期 children 不触发。 */
114
+ /**
115
+ * R0 消费已安装的 children,维护所属依赖;构造期 children 不触发。
116
+ * 可显式准备几何后读取;不得同步改写正在通知的 children/placement。
117
+ */
89
118
  protected onChildrenChanged(): void;
90
- /** 全部 raw links 安装后的结构 dirty publication 扩展点。 */
91
- protected onStructureDirty(): void;
92
- /** 在 children 提交后通知扩展点、Root 和 dirty 路径。 */
119
+ /** 在全部结构输入安装后运行结构通知并发布变化。 */
93
120
  private markStructureDirty;
94
121
  /**
95
- * 向 Root 发布已安装的 placement 变化。hook 重入提交更新 children 后,外层提交仍发布
96
- * 自己已安装的变化;Root 按每个节点当前的 parent 与 lifecycle 过滤。
122
+ * 向 Root 发布已安装的 placement 变化。稳定生命周期事件可能建立新的关系,
123
+ * Root 按每个节点当前的 parent 与 lifecycle 消费实际变化。
97
124
  */
98
125
  private publishStructureChange;
99
126
  /** 安装一次最终 children,并在当前提交仍有效时发布结构变化。 */
100
127
  private commitChildren;
101
128
  /**
102
- * 同步本次进入与离开节点的 lifecycle。lifecycle 回调可以同步重入修改结构,因此每个节点都按
129
+ * 同步本次进入与离开节点的 lifecycle。稳定生命周期事件可发起下一结构操作,因此每个节点都按
103
130
  * 自己与当前 owner 的实时 parent 和 lifecycle 判断,不因 children 被新提交替换而遗漏其余节点。
104
131
  */
105
132
  private syncCommittedLifecycles;
@@ -107,17 +134,24 @@ export declare class Node<P extends NodeProperties = NodeProperties, Child exten
107
134
  detachBatchParent(): void;
108
135
  /** @internal 接收 trusted batch 转移所有权的最终 children 与其变化窗口。 */
109
136
  installBatchChildren(children: readonly Node[], start: number, end: number): void;
110
- /** @internal 完整安装后的 parent hook;重入提交已改写归属时跳过旧结果。 */
137
+ /** @internal 完整安装后的 parent 通知;先前稳定生命周期事件已改写归属时跳过旧结果。 */
111
138
  notifyBatchParentChanged(previousParent: Node | undefined, expectedParent: Node | undefined): void;
112
139
  /** @internal 按当前 parent 同步最终 lifecycle context。 */
113
140
  syncPlacementLifecycle(): void;
114
- /** @internal tree 已完整安装后登记当前 owner 的 dirty path。 */
115
- publishBatchStructureDirty(): void;
141
+ /** @internal 全部字段和 raw links 安装后同步结构派生输入。 */
142
+ installBatchStructureInputs(): void;
143
+ /**
144
+ * @internal raw links 已改变后,在任何可重入回调前移交旧 Layer 的空间与像素责任。
145
+ * 活动上下文仍由 lifecycle owner 完成;新 Layer 在激活后接收新的绘制贡献。
146
+ */
147
+ releasePreviousLayer(): void;
148
+ /** @internal 全部 raw links 安装后同步 placement 派生输入。 */
149
+ installBatchParentInput(previousParent: Node | undefined): void;
116
150
  /** @internal raw links 与 placement lifecycle 同步完成后运行结构 hook。 */
117
151
  runBatchStructureHook(): void;
118
152
  /** 从当前 owner 移除一个直接 child,可选择同时停用它。 */
119
153
  private removeOwnChild;
120
- /** 构造期采用 children,回调已建立的新归属不再由旧输入接管。 */
154
+ /** 构造期采用 children;停用期间稳定事件已建立的新归属不再由旧输入接管。 */
121
155
  private adoptIncoming;
122
156
  /** 统一实现 append/prepend/before/after 的移动和插入事务。 */
123
157
  private insertAt;
@@ -139,7 +173,7 @@ export declare class Node<P extends NodeProperties = NodeProperties, Child exten
139
173
  after(...nodes: Node[]): this;
140
174
  /** 移除但不卸载指定 children,使其仍可复用。 */
141
175
  removeChild(...children: Child[]): this;
142
- /** 在稳定状态间同步转换;同一 Node 转换期间的再次请求立即报错。 */
176
+ /** 按当前状态执行生命周期操作;终态不再接收操作。 */
143
177
  private transitionLifecycle;
144
178
  /** 执行首次初始化和 Mounted 事件。 */
145
179
  private mountNode;
@@ -147,26 +181,24 @@ export declare class Node<P extends NodeProperties = NodeProperties, Child exten
147
181
  private canBeActivatedByOwner;
148
182
  /** 首次挂载并在 owner 允许时激活当前子树;已卸载节点不可恢复。 */
149
183
  mount(): void;
150
- /** 首次 mount 扩展点;不得再次转换当前 Node 的生命周期。 */
184
+ /** 初始化自身资源和自有渲染 children;不得再次转换当前 Node 的生命周期。 */
151
185
  protected onMount(): void;
152
186
  /** 建立 Root/Layer 上下文、注册 key,并递归激活 children。 */
153
187
  private activateNode;
154
- /** 进入活动上下文的扩展点;不得再次转换当前 Node 的生命周期。 */
188
+ /** 激活自身资源、订阅和自有渲染输出;不得再次转换当前 Node 的生命周期或改写 host 归属。 */
155
189
  protected onActivate(_activeRoot: Root | null, _layer: Layer | null): void;
156
190
  /** 清理输入、key、Layer 空间项、children 和派生类 active 状态。 */
157
191
  private leaveActiveContext;
158
192
  /** 离开 active 上下文并派发 Deactivated。 */
159
193
  private deactivateNode;
160
- /** 离开活动上下文的扩展点;不得再次转换当前 Node 的生命周期。 */
194
+ /** 释放本节点活动资源和自有渲染输出;不得再次转换当前 Node 的生命周期。 */
161
195
  protected onDeactivate(_activeRoot: Root | null, _layer: Layer | null): void;
162
- /** children 卸载前调用;不得再次转换当前 Node 的生命周期。 */
196
+ /** children 卸载前释放自身资源;不得转移待卸载 children 或再次转换当前 Node 生命周期。 */
163
197
  protected onBeforeUnmount(): void;
164
198
  /** 释放派生 owner 前调用;不得再次转换当前 Node 的生命周期。 */
165
199
  protected onUnmount(): void;
166
- /** 递归执行不可逆卸载,并释放结构、上下文和监听器。 */
200
+ /** 递归执行不可逆卸载,并释放本节点的结构、上下文和监听器。 */
167
201
  private unmountNode;
168
- /** 只在本节点存在监听器时创建同步生命周期事件。 */
169
- private dispatchLifecycleEvent;
170
202
  /** 不可逆卸载当前子树并清理监听器;重复调用不执行额外工作。 */
171
203
  unmount(): void;
172
204
  /** 在当前节点上下文中提供值。 */
@@ -1,6 +1,5 @@
1
1
  import type { NodeCreationOptions } from "./node";
2
2
  declare const CONFIGURED_STATE: unique symbol;
3
- declare const RUNTIME_OVERRIDE_STATE: unique symbol;
4
3
  /** x 方向变换原点;数值 `0` 为中心,`-0.5/0.5` 为左右边。 */
5
4
  export type OriginX = "center" | "left" | "right" | number;
6
5
  /** y 方向变换原点;数值 `0` 为中心,`-0.5/0.5` 为上下边。 */
@@ -33,18 +32,17 @@ export type PropertyChanges = ReadonlyMap<string, unknown>;
33
32
  export type PropertyUpdates = ReadonlyMap<string, unknown>;
34
33
  /** Node 持有的属性状态,并提供显式独立快照。 */
35
34
  export declare class NodeProperties {
35
+ /** runtime 覆盖期间保存 configured 值,own-key 同时表示覆盖存在。 */
36
36
  [CONFIGURED_STATE]: Record<string, unknown> | null;
37
- [RUNTIME_OVERRIDE_STATE]: Record<string, unknown> | null;
38
37
  /** 返回可独立修改的完整属性快照。 */
39
38
  snapshot(): Record<string, unknown>;
40
39
  /** 返回省略默认值和函数的可序列化属性。 */
41
40
  toJSON(): Record<string, unknown>;
42
- /** 将属性变化映射为提交影响,供派生 Properties 扩展。 */
41
+ /**
42
+ * 从安装前的当前 Properties、before changes 与最终 effective updates 纯计算提交影响。
43
+ * 扩展只返回影响位,不提交属性、结构或应用回调。
44
+ */
43
45
  getImpact(_changes: PropertyChanges, _updates?: PropertyUpdates): ChangeImpact;
44
- /** 读取把 runtime 字段还原为 configured 后的当前作者值。 */
45
- private configuredValue;
46
- /** 返回把 runtime 字段还原为 configured 后的独立完整值。 */
47
- private configuredValues;
48
46
  }
49
47
  /** @internal 借用单个字段当前的 configured source 值。 */
50
48
  export declare function getConfiguredPropertyValue(properties: NodeProperties, key: string): any;
@@ -68,7 +66,6 @@ export interface PreparedPropertyField {
68
66
  readonly sourceChanged: boolean;
69
67
  readonly beforeValue: unknown;
70
68
  readonly afterValue: unknown;
71
- readonly valueChanged: boolean;
72
69
  readonly installValue: boolean;
73
70
  }
74
71
  /** @internal direct 与 trusted batch 共用的最小 owner property delta。 */
@@ -78,13 +75,22 @@ export interface PreparedPropertyUpdate {
78
75
  readonly changes: PropertyChanges;
79
76
  readonly updates: PropertyUpdates;
80
77
  }
81
- /** @internal 解释 configured merge/reset,但不复制完整 source 或 Properties。 */
78
+ /**
79
+ * @internal 只计算 configured merge/reset 的 final delta,不安装或复制完整 Properties。
80
+ */
82
81
  export declare function prepareConfiguredPropertyUpdate(properties: NodeProperties, patch: Record<string, unknown>): PreparedPropertyUpdate;
83
- /** @internal 解释 runtime merge 与 own-undefined clear。 */
82
+ /**
83
+ * @internal 只计算 runtime merge 与 own-undefined clear 的 final delta,不安装状态。
84
+ */
84
85
  export declare function prepareRuntimePropertyUpdate(properties: NodeProperties, patch: Record<string, unknown>): PreparedPropertyUpdate;
85
- /** @internal 把指定或全部 runtime keys 解释为同一 clear delta。 */
86
+ /**
87
+ * @internal 把指定或全部 runtime keys 解释为同一 clear delta,不安装状态。
88
+ */
86
89
  export declare function prepareRuntimePropertyClear(properties: NodeProperties, keys?: readonly PropertyKey[]): PreparedPropertyUpdate;
87
- /** @internal 安装已经 finalize 的 changed source fields 与 effective values。 */
90
+ /**
91
+ * @internal 由完整 R0 writer 安装已经 finalize 的 source/effective fields。
92
+ * hook、dirty 与 History 交由同一提交管线在必要字段安装后处理。
93
+ */
88
94
  export declare function installPropertyUpdate(properties: NodeProperties, update: PreparedPropertyUpdate): void;
89
95
  /** Element 的作者变换和尺寸选项。 */
90
96
  export interface TransformableOptions extends NodeCreationOptions {
@@ -106,18 +112,10 @@ export interface TransformableOptions extends NodeCreationOptions {
106
112
  originX?: OriginX;
107
113
  /** y 方向变换原点,默认 `center`。 */
108
114
  originY?: OriginY;
109
- /** Editor 旋转中心的 x 轴位置,默认 `center`。 */
110
- rotationPivotX?: OriginX;
111
- /** Editor 旋转中心的 y 轴位置,默认 `center`。 */
112
- rotationPivotY?: OriginY;
113
115
  /** x 轴错切角度,单位为度,默认 `0`。 */
114
116
  skewX?: number;
115
117
  /** y 轴错切角度,单位为度,默认 `0`。 */
116
118
  skewY?: number;
117
- /** 未指定宽度时是否匹配 parent 宽度。 */
118
- fitWidth?: boolean;
119
- /** 未指定高度时是否匹配 parent 高度。 */
120
- fitHeight?: boolean;
121
119
  }
122
120
  /** Element 的作者变换属性状态。 */
123
121
  export declare class TransformProperties extends NodeProperties {
@@ -139,18 +137,10 @@ export declare class TransformProperties extends NodeProperties {
139
137
  originX: OriginX;
140
138
  /** y 方向变换原点。 */
141
139
  originY: OriginY;
142
- /** Editor 旋转中心的 x 轴位置。 */
143
- rotationPivotX: OriginX;
144
- /** Editor 旋转中心的 y 轴位置。 */
145
- rotationPivotY: OriginY;
146
140
  /** x 轴错切角度,单位为度。 */
147
141
  skewX: number;
148
142
  /** y 轴错切角度,单位为度。 */
149
143
  skewY: number;
150
- /** 未指定宽度时是否匹配 parent 宽度。 */
151
- fitWidth: boolean;
152
- /** 未指定高度时是否匹配 parent 高度。 */
153
- fitHeight: boolean;
154
144
  /** 创建带声明默认值的作者变换属性。 */
155
145
  constructor(options?: TransformableOptions);
156
146
  /** @internal 将尺寸和标量变换变化映射为几何影响。 */
@@ -1,6 +1,8 @@
1
1
  import { type PointView, type ReadonlyMatrix2D, type Rect } from "@fulate/share";
2
- import type { ElementOptionPatch } from "./element";
2
+ import { Element, type ElementOptionPatch } from "./element";
3
3
  import { type OriginX, type OriginY } from "./properties";
4
+ /** @internal 捕获已准备的场景几何和当前 authored 状态;离线对象独立计算变换。 */
5
+ export declare function captureElementTransformReference(owner: Element, writeMode: ReferenceTransformBaseline["writeMode"]): ReferenceTransformBaseline;
4
6
  /** 交互开始时直接借用的作者 frame 标量。 */
5
7
  export interface ReferenceTransformFrame {
6
8
  readonly left: number;
@@ -54,13 +56,15 @@ export interface ReferenceTransformTarget {
54
56
  export interface ReferenceTransformResolution {
55
57
  readonly framePatch: Readonly<ElementOptionPatch>;
56
58
  readonly authoredLocalDelta: ReadonlyMatrix2D;
59
+ /** authoredLocalDelta 后用于求 frame 的 reference AABB,由 resolver 直接交付。 */
60
+ readonly authoredReferenceBounds: Readonly<Rect>;
57
61
  }
58
62
  /**
59
63
  * 用 owner 已算出的精确 authored bounds 修正 bake frame 的位置。
60
64
  * AABB 经过旋转/错切后不能由原 bounds 四角精确推出;owner 在生成
61
65
  * 新几何后把真实 bounds 交回这里,保持 frame world matrix 与目标一致。
62
66
  */
63
- export declare function resolveAuthoredGeometryFramePatch(baseline: Readonly<Pick<ReferenceTransformBaseline, "referenceBounds" | "frame">>, resolution: Readonly<ReferenceTransformResolution>, authoredBounds: Readonly<Rect>): Readonly<ElementOptionPatch>;
67
+ export declare function resolveAuthoredGeometryFramePatch(baseline: Readonly<Pick<ReferenceTransformBaseline, "frame">>, resolution: Readonly<ReferenceTransformResolution>, authoredBounds: Readonly<Rect>): Readonly<ElementOptionPatch>;
64
68
  /** @internal reference bounds 改变时修正 origin 位移,保留给定最终 frame 的仿射。 */
65
69
  export declare function resolveReferenceBoundsTranslation(frame: Readonly<ElementOptionPatch>, before: Readonly<Rect>, after: Readonly<Rect>): Readonly<Pick<ElementOptionPatch, "left" | "top">>;
66
70
  /** 判断变换意图是否包含跨父级重挂载所需的目标父级矩阵。 */