@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,8 +1,9 @@
1
+ import { PaintContext } from "../paint-context";
1
2
  import { Element, ElementProperties, type AnyElement } from "../node/element";
2
- import { ElementTransform } from "../node/element-transform";
3
+ import type { DirtyBoundsMemo } from "../node/element-transform";
3
4
  import { type PropertyChanges } from "../node/properties";
4
5
  import type { BaseElementOption, ElementOptionPatch } from "../node/element";
5
- import { Bound, type Rect, type RectWithCenter } from "@fulate/share";
6
+ import { Bound, type PointView, type Rect, type RectWithCenter } from "@fulate/share";
6
7
  import type { Root } from "../root";
7
8
  /** 一轮 Layer 几何和绘制提交所消费的工作快照。
8
9
  *
@@ -18,6 +19,16 @@ export interface LayerFrameWork {
18
19
  /** 是否跳过脏矩形并完整重绘整层。 */
19
20
  forceFullRepaint: boolean;
20
21
  }
22
+ /** R2 已确定的清除范围和有序候选,供同帧 R3 直接消费。 @internal */
23
+ export interface LayerPaintWork {
24
+ readonly frame: LayerFrameWork;
25
+ readonly children: Map<AnyElement, AnyElement[]> | null;
26
+ readonly rectangles: {
27
+ screen: Rect[];
28
+ debugOutlines: readonly (readonly PointView[])[] | undefined;
29
+ } | null;
30
+ readonly boundsMemo: DirtyBoundsMemo | undefined;
31
+ }
21
32
  /** Layer 的构造选项。 */
22
33
  export interface LayerOption extends Omit<BaseElementOption, "layer"> {
23
34
  /** Root 中的图层顺序,默认 `1`,可通过 `setOptions()` 更新。 */
@@ -50,10 +61,6 @@ export declare class LayerProperties extends ElementProperties {
50
61
  /** 将 `zIndex` 变化映射为 Layer 排序和 hover 更新。 */
51
62
  getImpact(changes: PropertyChanges): number;
52
63
  }
53
- /** Layer 以 Root 逻辑尺寸解析 fit,并作为 transform ancestry 终点。 */
54
- export declare class LayerTransform<E extends Layer = Layer> extends ElementTransform<E> {
55
- protected resolveFitSize(): void;
56
- }
57
64
  /** Root 直接拥有的 Canvas 图层及其帧提交状态。 */
58
65
  export declare class Layer<P extends LayerProperties = LayerProperties, O extends LayerOption = LayerOption> extends Element<P, O, LayerOptionPatch<O>> {
59
66
  /** 序列化使用的节点类型。 */
@@ -62,6 +69,8 @@ export declare class Layer<P extends LayerProperties = LayerProperties, O extend
62
69
  canvasEl: HTMLCanvasElement;
63
70
  /** `canvasEl` 的 2D 绘制上下文。 */
64
71
  ctx: CanvasRenderingContext2D;
72
+ get width(): number;
73
+ get height(): number;
65
74
  /** 当前 Root 图层顺序。 */
66
75
  get zIndex(): number;
67
76
  /** 当前 Layer 中的元素是否可以参与层级排列。 */
@@ -76,18 +85,8 @@ export declare class Layer<P extends LayerProperties = LayerProperties, O extend
76
85
  private spatialItems;
77
86
  /** 下一轮 frame runtime 要取走的 Layer 工作。 */
78
87
  private pendingWork;
79
- /** 已保存提交前 visual bounds、等待绘制后清理的节点。 */
88
+ /** 已保存提交前 visual bounds、等待清除前消费的节点。 */
80
89
  private previousVisualBoundsNodes;
81
- /** 当前局部绘制按 parent 选中的直接 children;只在一次 `paint()` 内有效。
82
- *
83
- * @internal
84
- */
85
- dirtyPaintChildren: ReadonlyMap<AnyElement, readonly AnyElement[]> | null;
86
- /** 当前绘制所属的 Root;只在一次帧提交内有效。
87
- *
88
- * @internal
89
- */
90
- paintOwner: Root | null;
91
90
  /** 声明当前节点具有 Layer 结构语义。 */
92
91
  isLayerNode(): this is Layer;
93
92
  /** 是否显示脏矩形调试层。 */
@@ -121,7 +120,7 @@ export declare class Layer<P extends LayerProperties = LayerProperties, O extend
121
120
  /** 从 DOM 移除主 Canvas 和可选调试 Canvas。 */
122
121
  private removeCanvases;
123
122
  /** 属性提交后同步 Layer 自有的 Canvas 显示状态。 */
124
- protected onPropertiesChanged(current: P, changes: PropertyChanges): void;
123
+ protected onPropertiesInstalled(current: P, changes: PropertyChanges): void;
125
124
  /**
126
125
  * 按逻辑像素尺寸和 DPR 更新 Canvas backing store,并返回像素尺寸是否变化。
127
126
  * @param width Canvas CSS/逻辑宽度。
@@ -134,12 +133,12 @@ export declare class Layer<P extends LayerProperties = LayerProperties, O extend
134
133
  * @internal
135
134
  */
136
135
  queueSpatialUpdate(node: Element): void;
137
- /** 记录已捕获旧 visual bounds 的元素,以便绘制后清理缓存。
136
+ /** 记录持有旧 visual bounds 的元素,以便在清除区域确定后移交。
138
137
  *
139
138
  * @internal
140
139
  */
141
140
  registerPreviousVisualBounds(node: Element): void;
142
- /** 绘制覆盖旧区域后清除节点的提交前 visual bounds。 */
141
+ /** 清除已经交给本帧清除区域的旧贡献。 */
143
142
  private clearPreviousVisualBounds;
144
143
  /** 从 pending 集合、item map 和 RBush 移除节点。 */
145
144
  private removeSpatialItem;
@@ -165,7 +164,9 @@ export declare class Layer<P extends LayerProperties = LayerProperties, O extend
165
164
  private searchCommittedItems;
166
165
  /** 将本帧积累的 visual bounds 更新批量提交到 RBush。 */
167
166
  flushRbush(): void;
168
- /** 以节点当前 world visual bounds 创建或更新空间项。 */
167
+ /** 停用通知可以同步提交帧;只读取仍由本 Layer 拥有的活动节点范围。 */
168
+ private getSpatialBounds;
169
+ /** 消费已读取的 world visual bounds,创建、更新或移除空间项。 */
169
170
  private updateSpatialItem;
170
171
  /** 标记元素需要重新提交布局、几何、空间索引和绘制。 */
171
172
  invalidateLayout(node: Element): void;
@@ -189,10 +190,8 @@ export declare class Layer<P extends LayerProperties = LayerProperties, O extend
189
190
  * @internal
190
191
  */
191
192
  flushGeometry(work: LayerFrameWork): void;
192
- /** 判断节点或其 ancestor 是否仍有下一帧 damage。 */
193
- private hasPendingDamage;
194
- /** 清理本次已覆盖且没有再次失效的提交前 visual bounds。 */
195
- private clearPaintedDamage;
193
+ /** 清除区域已确定后、进入 paint 前消费受影响分支;回调的新记录属于下一帧。 */
194
+ private consumeDamage;
196
195
  /**
197
196
  * 清空并重新绘制整个 Layer Canvas。dirty-rect Layer 的元素只绘制在 visual bounds 内,
198
197
  * 因此直接用 viewport 的 RBush 候选组织绘制树;候选密度达到阈值时逐 child 判断可见性。
@@ -206,17 +205,19 @@ export declare class Layer<P extends LayerProperties = LayerProperties, O extend
206
205
  private ensureDebugSurface;
207
206
  /** 在调试 Canvas 上短暂显示脏矩形和命中轮廓。 */
208
207
  private flashRects;
209
- /** 绘制几何稳定后积累的工作,并返回是否产生了真实 Canvas 绘制。
210
- *
211
- * @internal
212
- */
213
- flushPaint(work: LayerFrameWork): boolean;
208
+ /** R2 确定本轮 damage 与有序候选,暂缓绘制的 Layer 保留旧像素责任。 @internal */
209
+ preparePaint(work: LayerFrameWork): LayerPaintWork | null;
210
+ private prepareFullPaint;
211
+ /** R3 消费已准备的范围与候选,完成实际清除、绘制和像素责任交接。 @internal */
212
+ flushPaint(work: LayerPaintWork): void;
214
213
  /** 将 world damage 转为覆盖完整像素的 backing-store 矩形。 */
215
214
  private worldToScreenRects;
216
215
  /** 在调试层标记本次完整重绘。 */
217
216
  private flashFullRepaint;
218
- /** 使用已提交顺序绘制 children。 */
219
- paint(ctx?: CanvasRenderingContext2D): void;
217
+ /** 建立本轮屏幕绘制输入;候选直接采用 R2 的同一邻接表。 */
218
+ createPaintContext(ctx?: CanvasRenderingContext2D, children?: ReadonlyMap<AnyElement, readonly AnyElement[]> | null): PaintContext;
219
+ /** 使用本轮上下文绘制 children。 */
220
+ paint(paint: PaintContext): void;
220
221
  /** 清空整个 Canvas backing store,不改变场景树或待提交状态。 */
221
222
  clear(): void;
222
223
  }
@@ -8,9 +8,9 @@ export interface OwnerPropertyChange {
8
8
  readonly patch: Readonly<Record<string, unknown>>;
9
9
  }
10
10
  /**
11
- * 可选 semantic History owner 消费的 actual changed fields 与 affected parents。
12
- * before 是 finalize 已有的 raw configured source 或被替换下来的 children 原引用;
13
- * sink 在语义操作结束时读取 live final,并决定是否持久化复制。
11
+ * 可选 semantic History owner 记录 actual changed fields 与 affected parents 的接缝。
12
+ * before 借用 raw configured source 或被替换的 children 原引用;语义结束时读取 live final。
13
+ * sink 只记录,不在回调中修改场景、重放或递归操纵 History 栈。
14
14
  */
15
15
  export interface ChangeHistorySink {
16
16
  /** 记录一个 owner/key 首次触及批次提供的 raw configured before。 */
@@ -19,12 +19,12 @@ export interface ChangeHistorySink {
19
19
  recordStructureChange(owner: Node, before: readonly Node[]): void;
20
20
  }
21
21
  /** @internal 合并 raw owner effects;单个 patch 直接借用,仅合并同 owner 字段时分配。 */
22
- export declare function mergeOwnerPropertyChanges(ownerEffects: readonly OwnerPropertyChange[]): Map<Element<import("..").ElementProperties, import("..").BaseElementOption<any>, Partial<Omit<import("..").BaseElementOption<any>, "key" | "children">>>, Readonly<Record<string, unknown>>>;
22
+ export declare function mergeOwnerPropertyChanges(ownerEffects: readonly OwnerPropertyChange[]): Map<Element<import("..").ElementProperties, import("..").BaseElementOption<any>, Partial<Omit<import("..").BaseElementOption<any>, "key" | "children">>, Partial<Omit<import("..").BaseElementOption<any>, "key" | "children">>>, Readonly<Record<string, unknown>>>;
23
23
  /**
24
24
  * 同步应用一份 trusted change batch。
25
25
  *
26
26
  * owner effects 先按对象身份合并最终 patch;所有 fields/raw links 安装完成后才运行
27
- * History、lifecycle、hooks、dirty 和最多一次 scene delivery;纯 paint 变化不通知 scene。
27
+ * 内部派生输入与 dirty,随后运行 History、lifecycle、各 owner 的 hooks 和最多一次 scene delivery。
28
28
  * 本函数不提供 rollback、
29
29
  * retry、receipt 或 rejected 结果。返回本批次是否实际安装属性或结构变化。
30
30
  */
@@ -1,5 +1,3 @@
1
- import { Bound, type ReadonlyMatrix2D, type Rect } from "@fulate/share";
2
- /** Project a local rectangle into a matrix space and return its AABB. */
3
- export declare function projectBounds(matrix: ReadonlyMatrix2D, bounds: Readonly<Rect> | null): Bound;
1
+ import type { ReadonlyMatrix2D } from "@fulate/share";
4
2
  /** Compare a committed matrix with a previous scalar matrix sample. */
5
3
  export declare function matrixChanged(matrix: ReadonlyMatrix2D, previousA: number, previousB: number, previousC: number, previousD: number, previousE: number, previousF: number): boolean;
@@ -5,8 +5,8 @@ import type { Element } from "./element";
5
5
  import { ChangeImpact } from "./properties";
6
6
  /** 几何缓存内部借出的只读世界边界。 @internal */
7
7
  export type GeometryBoundsView = Readonly<Rect & BoundingBox>;
8
- /** 一次 Layer damage 收集共享的子树 visual bounds memo。 @internal */
9
- export type DirtyBoundsMemo = Map<ElementTransform, Bound | null>;
8
+ /** 一次 Layer damage 收集共享的子树旧可见范围 memo。 @internal */
9
+ export type DirtyBoundsMemo = Map<Element, GeometryBoundsView | null>;
10
10
  /**
11
11
  * Element 继承构造链内部使用的 companion constructor。默认参数保留
12
12
  * existential 入口;具体 Element 子类可以同时声明 owner 与 Transform。
@@ -15,7 +15,9 @@ export type ElementTransformClass<E extends Element = Element, T extends Element
15
15
  /**
16
16
  * 一个 Element 唯一的变换、几何、damage 与子树派生状态 owner。
17
17
  *
18
- * 具体 Element 类型通过 companion subclass 覆写 protected 几何、尺寸或矩阵方法。
18
+ * R1 提交 resolved frame 和矩阵;活动场景读取前由调用者等待 Root.nextTick()。
19
+ * geometry/matrix builder、getter 与 predicate 只生成结果或更新所属计算缓存,不提交场景。
20
+ * commitResolvedFrame 由 R1 布局 owner 安装派生值。
19
21
  */
20
22
  export declare class ElementTransform<E extends Element = Element> {
21
23
  protected readonly element: E;
@@ -31,10 +33,6 @@ export declare class ElementTransform<E extends Element = Element> {
31
33
  needsCommit: boolean;
32
34
  /** descendant 是否仍有待提交变换。 @internal */
33
35
  hasDirtyDescendant: boolean;
34
- /** 当前 transform 提交是否正在解析 fitWidth/fitHeight。 */
35
- private resolvingFitSize;
36
- /** 本轮是否只失效 hit bounds、仍保留旧 visual 几何。 */
37
- private hitOnlyInvalidation;
38
36
  /** 自身 reference 或 child world space 是否要求 descendants 重算布局。 */
39
37
  private childLayoutDirty;
40
38
  /** 当前最后一次提交的 own world matrix。 */
@@ -61,13 +59,13 @@ export declare class ElementTransform<E extends Element = Element> {
61
59
  private worldHitBounds;
62
60
  /** localVisualBounds 变换后的 world AABB。 */
63
61
  private worldVisualBounds;
64
- /** 属性失效前最后一次提交的 world visual bounds。 */
62
+ /** undefined:绘制后尚可捕获;Bound:旧擦除责任;null:未绘制、空或已移交。 */
65
63
  private previousVisualBounds;
66
64
  /** 稳定状态下缓存的当前子树 world render coverage。 */
67
65
  private currentRenderCoverageBounds;
68
66
  /** 当前 content subtree 在直接 parent child reference 中的只读 AABB。 */
69
67
  private contentBoundsInParent;
70
- /** 只在真实 dependent 存在时创建的内部 transform commit observers。 */
68
+ /** 只在真实订阅存在时创建的 transform commit observers。 */
71
69
  private transformCommitObservers?;
72
70
  /**
73
71
  * 创建指定 Element 的唯一 companion runtime。
@@ -76,7 +74,7 @@ export declare class ElementTransform<E extends Element = Element> {
76
74
  constructor(element: E);
77
75
  /** Element 进入 active 上下文时要求重新提交自身和空间项。 @internal */
78
76
  activate(): void;
79
- /** raw parent link 改变后只标记本地 world commit;publication 在结构阶段统一执行。 @internal */
77
+ /** raw parent link 安装后登记本地 world commit 和新 ancestor 路径。 @internal */
80
78
  markParentChanged(): void;
81
79
  /** children hook 的 companion Transform 扩展入口。 @internal */
82
80
  runChildrenChanged(): void;
@@ -111,8 +109,11 @@ export declare class ElementTransform<E extends Element = Element> {
111
109
  /** 构建用于精确世界投影的 local 绘制轮廓。 */
112
110
  protected buildVisualOutline(snapshot: GeometrySnapshot): readonly PointView[];
113
111
  /** 构建权威 local 绘制边界。 */
114
- protected buildVisualBounds(snapshot: GeometrySnapshot): Readonly<Rect> | null;
115
- /** 覆盖后可直接提供完整 world 矩阵;返回 `null` 使用标量变换。 */
112
+ protected buildVisualBounds(snapshot: GeometrySnapshot, _includeShadow?: boolean): Readonly<Rect> | null;
113
+ /**
114
+ * 从当前有效输入纯计算完整 world matrix;返回 null 使用标量变换。
115
+ * 该扩展也供 reference/content 查询调用,不因此获得场景提交或阶段推进权限。
116
+ */
116
117
  protected buildWorldMatrix(): ReadonlyMatrix2D | null;
117
118
  /** 返回标量 world matrix 计算使用的 transform reference bounds。 */
118
119
  protected getWorldMatrixReferenceBounds(): Readonly<Rect> | null;
@@ -134,15 +135,17 @@ export declare class ElementTransform<E extends Element = Element> {
134
135
  getLocalGeometryRevision(): number;
135
136
  /** 返回复用当前快照的几何查询对象。 */
136
137
  getGeometryQuery(): GeometryQuery;
137
- /** 立即提交自身 world 矩阵并返回副本。 */
138
+ /** @internal R1 提交自身 world 矩阵并返回副本。 */
138
139
  updateWorldMatrix(): Matrix2D;
139
140
  /** 清除 world 投影;world-dependent local geometry 只在矩阵实际变化时失效。 */
140
141
  private finishWorldMatrixCommit;
141
- /** 以给定 parent reference 组合当前 authored scalar matrix。 */
142
+ /**
143
+ * 把当前标量变换写入调用方提供的结果 matrix,不安装场景矩阵或推进阶段。
144
+ */
142
145
  protected writeScalarMatrix(matrix: Matrix2D, parentMatrix?: ReadonlyMatrix2D): Matrix2D;
143
146
  /** 提交作者 world matrix 并清除依赖它的投影。 */
144
147
  private commitWorldMatrix;
145
- /** 返回已提交的 world 矩阵副本,不包含 Viewport 和 DPR。 */
148
+ /** 返回已提交的元素 world 矩阵副本;Canvas 最终观察变换由 PaintContext 叠加。 */
146
149
  getWorldMatrix(): Matrix2D;
147
150
  /** 借用已提交矩阵;调用方不得修改或保留。 @internal */
148
151
  getWorldMatrixView(): ReadonlyMatrix2D;
@@ -160,6 +163,8 @@ export declare class ElementTransform<E extends Element = Element> {
160
163
  containsWorldPoint(point: PointView): boolean;
161
164
  /** 借用已提交的 world 命中 AABB。 @internal */
162
165
  getWorldHitBoundsView(): GeometryBoundsView;
166
+ /** Own world-space hit coverage, including content with its own orientation. */
167
+ protected buildWorldHitBounds(): Bound;
163
168
  /** 返回 world 绘制轮廓的独立点数组。 */
164
169
  getWorldVisualPoints(): PointView[];
165
170
  /** 返回 world 绘制 AABB 的独立副本。 */
@@ -171,7 +176,7 @@ export declare class ElementTransform<E extends Element = Element> {
171
176
  /** 借用已提交的 world 绘制 AABB。 @internal */
172
177
  getWorldVisualBoundsView(): GeometryBoundsView;
173
178
  /** 构建当前 owner 的完整 world 绘制 AABB。 */
174
- protected buildWorldVisualBounds(): Bound;
179
+ protected buildWorldVisualBounds(includeShadow?: boolean): Bound;
175
180
  /** 将 local AABB 四角投影为当前 own world matrix 下的 world AABB。 */
176
181
  private toWorldBounds;
177
182
  /** 将 local AABB 四角投影到指定 reference matrix。 */
@@ -180,64 +185,97 @@ export declare class ElementTransform<E extends Element = Element> {
180
185
  private getVisualOutline;
181
186
  /** 借用已提交的 world 绘制轮廓。 @internal */
182
187
  getWorldVisualPointsView(): readonly PointView[];
183
- /** 在清理 visual 缓存前保存最后一次提交的 world 绘制范围。 */
184
- private captureCurrentVisualBounds;
185
- /** 将旧 visual bounds交给当前 transform 和所属 Layer 的 damage 跟踪。 */
186
- private captureVisualBounds;
187
- /** 返回累积旧 visual bounds 的独立副本。 @internal */
188
- getPreviousVisualBounds(): Bound | null;
188
+ /** 在字段、结构或派生几何变化前,接管尚未捕获的旧绘制贡献。 @internal */
189
+ captureBeforeChange(): void;
190
+ private static hasUncapturedPaint;
191
+ /** 实际 paint 准入建立当前贡献;旧责任已由 Layer 在清除前消费。 @internal */
192
+ beginPaint(): void;
193
+ /** 借用首次变化前的旧可见范围;清除后或移交给 Layer 后不再持有。 @internal */
194
+ getPreviousVisualBounds(): GeometryBoundsView | null;
189
195
  /** 是否保存了失效前的 visual bounds。 @internal */
190
196
  hasPreviousVisualBounds(): boolean;
191
197
  /** 清除失效前的 visual bounds。 @internal */
192
198
  clearPreviousVisualBounds(): void;
193
- /** @internal 按影响范围失效几何并安排 Layer 提交。 */
194
- invalidate(impact: ChangeImpact, previousBounds?: Readonly<BoundingBox> | null): void;
199
+ /** @internal 清理几何缓存并登记工作;旧贡献由变化入口先行捕获。 */
200
+ invalidate(impact: ChangeImpact): void;
195
201
  /** A derived layout can change visual bounds during an already pending commit. @internal */
196
- invalidateLayoutBounds(): void;
202
+ invalidateLayoutBounds(impact?: ChangeImpact): void;
197
203
  /** 标记 local 几何需要重新构建。 */
198
204
  markGeometryNeedsLayout(notifyScene?: boolean): void;
199
205
  /** 安排当前元素所属 Layer 重绘。 @internal */
200
206
  markPaintDirty(): void;
201
207
  /** 标记 world 变换失效并安排 Layer 提交。 */
202
208
  markNeedsLayout(notifyScene?: boolean): void;
203
- /** @internal 订阅实际 world transform commit;返回同一 observer 的注销函数。 */
209
+ /**
210
+ * @internal 订阅 R1 自身 world commit,返回同一 observer 的注销函数。
211
+ * 用于真实派生依赖失效、projection 登记及 R2 前的首次布局定位。
212
+ * 不得改变 authored、parent、活动 Root 或嵌套推进帧。
213
+ */
204
214
  observeTransformCommit(observer: (transform: ElementTransform) => void): () => void;
215
+ /**
216
+ * 订阅自身 Transform 更新完成,每次真实 commit 等待当时活动 Root 的 nextTick 后交付。
217
+ * observer 接收同一 Transform 引用;未挂载对象在微任务中交付。返回值只取消后续 commit
218
+ * 订阅,已等待的交付继续完成。observer 的异常或 Promise rejection 原样进入异步任务。
219
+ */
220
+ observeTransformUpdated(observer: (transform: ElementTransform) => void | Promise<void>): () => void;
205
221
  /** 安装一次最终 resolved frame delta,并只发布一次合并后的几何影响。 */
206
222
  private installResolvedFrame;
207
- /** @internal 提交由布局解析得到的尺寸。 */
223
+ /**
224
+ * @internal R1 布局 owner 安装所属 resolved size,不反写 authored 尺寸。
225
+ */
208
226
  commitResolvedSize(width: number | undefined, height: number | undefined): boolean;
209
- /** @internal 提交一个布局 owner 最终解析出的完整 frame。 */
227
+ /**
228
+ * @internal R1 布局 owner 安装所属完整 resolved frame,不反写 authored pose/size。
229
+ */
210
230
  commitResolvedFrame(frame: Readonly<Rect> | null): boolean;
211
- /** 根据 parent 尺寸解析 fitWidth 和 fitHeight。 */
212
- protected resolveFitSize(): void;
213
- /** 立即提交当前节点所在的最高脏变换链。 */
231
+ /** @internal R1 提交当前节点所在的最高脏变换链。独立对象使用 updateDetachedTransformChain。 */
214
232
  bubbleUpdateTransform(): void;
215
- /** @internal 仅在祖先变换脏时同步提交当前 world 变换链。 */
216
- updateWorldTransformChain(): void;
233
+ /**
234
+ * 为未挂载的独立对象计算其变换依赖链。活动场景由 Root 帧管线统一计算,
235
+ * 调用者在读取 world geometry 前等待 Root.nextTick()。
236
+ */
237
+ updateDetachedTransformChain(): void;
217
238
  /** 找到当前节点上方、Layer 以内最高的脏 Transform。 */
218
239
  private findHighestDirtyAncestor;
219
240
  /** 提交自身尺寸、world matrix 和空间索引更新,不递归 children。 */
220
241
  private commitOwnTransform;
221
- /** @internal 立即提交当前脏子树的变换和几何。 */
242
+ /** @internal R1 提交当前脏子树的变换和几何。 */
222
243
  updateTransform(parentLayoutDirty?: boolean): void;
223
- /** 返回本次失效前后覆盖到的 world 脏区域。 */
224
- getDirtyRect(): Bound;
225
- /** @internal 复用当前 Layer damage 收集已经解析的子树范围。 */
226
- getDirtyRect(memo: DirtyBoundsMemo): Bound | null;
244
+ /** 返回旧可见范围和最终场景 coverage 的 world damage;没有范围时返回 null。 */
245
+ getDirtyRect(memo?: DirtyBoundsMemo): Bound | null;
227
246
  /** 返回自身与可见 descendants 的已提交 world render coverage。 */
228
247
  getRenderCoverageBounds(): Bound;
229
248
  /** 返回排除 decoration boundary 后的 world content subtree bounds。 */
230
249
  getContentBounds(): Bound;
250
+ /** 将 local bounds 投影到直接 parent 的 child 坐标,标量变换直接使用 local matrix。 */
251
+ projectBoundsToParent(bounds: Readonly<Rect>): Bound;
231
252
  /** 在指定 reference 中沿 canonical local matrices 解析 content subtree。 */
232
253
  protected collectContentBoundsInReference(parentMatrix: ReadonlyMatrix2D, referenceWorldInverse: ReadonlyMatrix2D): Bound | null;
233
254
  /** 返回当前 content subtree 在直接 parent child reference 中的 AABB。 */
234
255
  getContentBoundsInParentView(): GeometryBoundsView | null;
235
256
  /** 借用排除 decoration boundary 后的已提交 world content bounds。 */
236
257
  getWorldContentBoundsView(): GeometryBoundsView | null;
237
- /** 借用自身与可见 descendants 的已提交 world render coverage。 @internal */
238
- getRenderCoverageBoundsView(): Readonly<BoundingBox & Rect> | null;
239
- /** 合并子树每个节点提交前后的 visual bounds,形成 damage 区域。 */
240
- private collectDirtySubtreeBounds;
258
+ /** 自身的绘制贡献;子树聚合型 geometry 不重复作为 own contribution。 */
259
+ protected getOwnRenderCoverageBoundsView(includeShadow?: boolean): GeometryBoundsView | null;
260
+ /**
261
+ * 自身 PNG 的 world 绘制边界,不含 children 或默认阴影扩边。
262
+ * 自定义 Transform 可覆写以扩展装饰范围;返回借用 view 只在同步读取中有效。
263
+ */
264
+ protected getOwnPNGExportBounds(): GeometryBoundsView | null;
265
+ /** 当前可见子树含装饰、裁剪后的 world 导出范围;几何须已由 Root 稳定。 */
266
+ getPNGExportBounds(): GeometryBoundsView | null;
267
+ /**
268
+ * @internal 借用自身与可见 descendants 的 committed world coverage,忽略自身与祖先 visible。
269
+ * include 只筛选当前 Transform,不提交场景或推进阶段。
270
+ */
271
+ getRenderCoverageBoundsView(include?: (transform: ElementTransform) => boolean, forExport?: boolean): GeometryBoundsView | null;
272
+ /**
273
+ * @internal 借用当前子树通过 ancestor visibility/clip 后的场景 coverage。
274
+ * include 只筛选当前 Transform,不提交场景或推进阶段。
275
+ */
276
+ getSceneRenderCoverageBoundsView(include?: (transform: ElementTransform) => boolean, forExport?: boolean): GeometryBoundsView | null;
277
+ /** 旧范围已按变化前的场景可见性捕获,不能再用当前 clip 或 visibility 裁掉。 */
278
+ private collectPreviousSubtreeBounds;
241
279
  /** 将当前 owner local child clip 转换成保守的 world AABB。 */
242
280
  private getWorldChildClipBounds;
243
281
  /** 借用精确命中前使用的 world AABB。 @internal */