@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,3 +1,4 @@
1
+ import type { PaintContext } from "../paint-context";
1
2
  import { Element, BaseElementOption, ElementProperties, type ElementOptionPatch } from "./element";
2
3
  import { ElementTransform, type ElementTransformClass } from "./element-transform";
3
4
  import { ChangeImpact, type PropertyChanges } from "./properties";
@@ -76,10 +77,10 @@ export declare class ShapeTransform<E extends Shape = Shape> extends ElementTran
76
77
  /** 构建包含绘制外扩的保守 local 轮廓。 */
77
78
  protected buildVisualOutline(snapshot: GeometrySnapshot): PointView[];
78
79
  /** 构建空间索引使用的 local 绘制 AABB。 */
79
- protected buildVisualBounds(snapshot: GeometrySnapshot): Readonly<import("@fulate/share").Rect>;
80
+ protected buildVisualBounds(snapshot: GeometrySnapshot, includeShadow?: boolean): Readonly<import("@fulate/share").Rect>;
80
81
  }
81
82
  /** 提供填充、border、阴影及对应命中几何的可绘制元素。 */
82
- export declare class Shape<P extends ShapeProperties = ShapeProperties, O extends ShapeOption<any> = ShapeOption<any>> extends Element<P, O> {
83
+ export declare class Shape<P extends ShapeProperties = ShapeProperties, O extends ShapeOption<any> = ShapeOption<any>, RuntimePatch extends object = ElementOptionPatch<O>> extends Element<P, O, ElementOptionPatch<O>, RuntimePatch> {
83
84
  readonly type: string;
84
85
  /** 当前 Canvas 填充和裁剪规则。 */
85
86
  get fillRule(): CanvasFillRule;
@@ -100,7 +101,7 @@ export declare class Shape<P extends ShapeProperties = ShapeProperties, O extend
100
101
  /** 返回 outside border 对 local hit/visual 边界的单侧外扩量。 */
101
102
  getBorderOutset(): number;
102
103
  /** 返回包含 outside border 和 shadow 的四向视觉外扩量。 */
103
- getVisualOutset(): Outset;
104
+ getVisualOutset(includeShadow?: boolean): Outset;
104
105
  /**
105
106
  * 返回逻辑边对应的局部坐标线段(不含 visual outset)。
106
107
  * 多边形 / 三角形等子类覆写此方法即可让锚点贴着实际轮廓。
@@ -140,13 +141,14 @@ export declare class Shape<P extends ShapeProperties = ShapeProperties, O extend
140
141
  }): PointView;
141
142
  /** Replay committed geometry without expanding ordinary rectangle subpaths. */
142
143
  protected buildResolvedPath(ctx: CanvasRenderingContext2D): void;
143
- paint(ctx?: CanvasRenderingContext2D): void;
144
+ paint(paint: PaintContext): void;
144
145
  /** 定义形状路径(width × height),hover 复用此路径 */
145
146
  protected buildPath(ctx: CanvasRenderingContext2D): void;
146
147
  /** 构建 border 描边路径 */
147
148
  protected buildBorderPath(ctx: CanvasRenderingContext2D): void;
148
149
  /**
149
150
  * canonical geometry 是普通矩形时,向当前 path 追加向内偏移 `inset` 的等距矩形。
151
+ * 提供 world 矩阵时直接追加世界坐标,不切换 Canvas 坐标系。
150
152
  * 直边内缩描边与轮廓裁剪逐像素一致;其他几何返回 `false`,由调用方使用轮廓裁剪。
151
153
  */
152
154
  private traceInsetRectangle;
@@ -154,8 +156,7 @@ export declare class Shape<P extends ShapeProperties = ShapeProperties, O extend
154
156
  protected applyChildClip(ctx: CanvasRenderingContext2D): void;
155
157
  /** Shape 的 child clip 与其实际填充 path 使用同一 canonical query。 */
156
158
  containsChildClipPoint(point: PointView): boolean;
157
- /** 绘制元素自身内容(文字、图片等),默认为空 */
158
- protected paintContent(_ctx: CanvasRenderingContext2D): void;
159
+ protected applyExportAncestor(paint: PaintContext): void;
159
160
  /** 绘制 Shape 的填充背景。 */
160
161
  protected paintBackground(ctx: CanvasRenderingContext2D): void;
161
162
  /** 按当前 border 样式绘制内容轮廓。 */
@@ -166,8 +167,8 @@ export declare class Shape<P extends ShapeProperties = ShapeProperties, O extend
166
167
  paintHover(ctx: CanvasRenderingContext2D, scale: number): void;
167
168
  /**
168
169
  * @internal 普通矩形几何且 world 矩阵保持长度时,把与 `paintHover()` 相同的内侧轮廓追加到
169
- * 当前 path;调用方随后在 Viewport 变换下以 `1 / scale` 线宽统一描边。
170
+ * 当前 path,坐标为世界坐标;调用方在 Viewport 变换下以 `1 / scale` 线宽统一描边。
170
171
  * 覆写 `paintHover()` 的子类同时覆写本方法,返回 `false` 或追加自身的等价轮廓。
171
172
  */
172
- traceHoverOutline(ctx: CanvasRenderingContext2D, scale: number): boolean;
173
+ traceHoverOutline(ctx: CanvasPath, scale: number): boolean;
173
174
  }
@@ -0,0 +1,34 @@
1
+ import { type GeometrySnapshot } from "../geometry";
2
+ import { type VectorPathCommand, type VectorPathGeometry } from "../geometry/path";
3
+ import type { ElementOptionPatch } from "./element";
4
+ import type { ElementTransformClass } from "./element-transform";
5
+ import { type PropertyChanges } from "./properties";
6
+ import { Shape, ShapeProperties, ShapeTransform, type ShapeOption } from "./shape";
7
+ /** Path creation input; subclasses may specialize the input while storing the same canonical geometry. */
8
+ export interface VectorPathOption<Input = readonly VectorPathCommand[], T = VectorPath<any, any, any>> extends ShapeOption<T> {
9
+ /** Commands at creation/update boundaries, or the canonical path adopted by reference. */
10
+ path?: Input | VectorPathGeometry;
11
+ }
12
+ /** The scene element's single authored path owner. */
13
+ export declare class VectorPathProperties extends ShapeProperties {
14
+ /** Canonical path adopted by reference. */
15
+ path: VectorPathGeometry;
16
+ /** Interpret commands once, or directly adopt canonical geometry. */
17
+ constructor(options?: VectorPathOption<readonly VectorPathCommand[], any>);
18
+ getImpact(changes: PropertyChanges): number;
19
+ }
20
+ /** Derives the shared geometry snapshot directly from authored anchors. */
21
+ export declare class VectorPathTransform<E extends VectorPath<any, any, any> = VectorPath> extends ShapeTransform<E> {
22
+ protected buildGeometrySnapshot(revision: number): GeometrySnapshot;
23
+ }
24
+ /** Core path element: scene, styling, geometry queries, drawing and serialization. */
25
+ export declare class VectorPath<P extends VectorPathProperties = VectorPathProperties, O extends VectorPathOption<unknown, any> = VectorPathOption, RuntimePatch extends object = ElementOptionPatch<O>> extends Shape<P, O, RuntimePatch> {
26
+ readonly type: string;
27
+ /** Borrow the current canonical path; structured input is adopted without copying. */
28
+ get path(): VectorPathGeometry;
29
+ /** Create a path with the final Properties and Transform supplied by its owner. */
30
+ constructor(options?: NoInfer<O>, properties?: P, Transform?: ElementTransformClass);
31
+ /** Interpret only the final consumed patch, after owner delta merging. */
32
+ protected resolveOptions(options: ElementOptionPatch<O>): Partial<Omit<O, "key" | "children">>;
33
+ protected buildPath(ctx: CanvasRenderingContext2D): void;
34
+ }
@@ -0,0 +1,30 @@
1
+ import type { ReadonlyMatrix2D } from "@fulate/share";
2
+ import type { AnyElement } from "./node/element";
3
+ /** @internal 没有本轮候选的节点共享同一个空列表。 */
4
+ export declare const EMPTY_PAINT_CHILDREN: readonly AnyElement[];
5
+ /**
6
+ * 一次同步绘制的输入。Layer 与图片导出分别建立,整条子树复用同一个对象。
7
+ * 只借用本轮稳定输入,不推进布局、帧或场景提交,不跨 await 保存。
8
+ */
9
+ export declare class PaintContext {
10
+ /** 本次输出的原生 Canvas 上下文。 */
11
+ readonly ctx: CanvasRenderingContext2D;
12
+ /** world 到输出像素的缩放和平移。 */
13
+ private readonly projection;
14
+ /** 是否建立屏幕像素贡献并绘制编辑态。 */
15
+ readonly screen: boolean;
16
+ /** 本轮已准备的候选邻接表;null 按现有 children 顺序遍历。 */
17
+ readonly children: ReadonlyMap<AnyElement, readonly AnyElement[]> | null;
18
+ /** 采用本次输出映射与已经准备的候选,不复制场景数据。 */
19
+ constructor(
20
+ /** 本次输出的原生 Canvas 上下文。 */
21
+ ctx: CanvasRenderingContext2D,
22
+ /** world 到输出像素的缩放和平移。 */
23
+ projection: Pick<ReadonlyMatrix2D, "a" | "d" | "e" | "f">,
24
+ /** 是否建立屏幕像素贡献并绘制编辑态。 */
25
+ screen: boolean,
26
+ /** 本轮已准备的候选邻接表;null 按现有 children 顺序遍历。 */
27
+ children?: ReadonlyMap<AnyElement, readonly AnyElement[]> | null);
28
+ /** 切换到 world 坐标,或组合给定的 local → world 矩阵。 */
29
+ applyTransform(matrix?: ReadonlyMatrix2D): void;
30
+ }
@@ -3,37 +3,44 @@ import type { Layer } from "../layer";
3
3
  import type { ElementTransform } from "../node/element-transform";
4
4
  import type { Root } from "./index";
5
5
  import type { PointView } from "@fulate/share";
6
- import { Element } from "../node/element";
7
- /** Root 唯一 frame runtime 可安装的单 participant 基础协议。 */
6
+ import type { Element } from "../node/element";
7
+ /**
8
+ * Root 唯一 runtime 的分阶段 consumer 协议。
9
+ * pending、resolveCursor 与 getDirtyOwnerKeys 只读当前事实;各 flush 只写所属阶段的 owner。
10
+ */
8
11
  export interface RootFrameParticipant {
9
- /** authored mutation work 是否仍需进入 stabilization round。 */
12
+ /** 是否有在下一次 R0 消费的 authored intent。 */
10
13
  hasPendingWork(): boolean;
11
14
  /** 消费本轮唯一 queued authored intent。 */
12
15
  flushMutationPhase(): void;
13
16
  /** stabilization 后是否有待更新的 Editor spatial projection。 */
14
17
  hasPendingSpatialWork?(): boolean;
15
- /** stabilization 后、overlay/RBush/paint 前更新 Editor spatial projection。 */
18
+ /**
19
+ * R2 消费稳定 geometry 更新所属 spatial projection,不提交 authored/结构或推进阶段。
20
+ */
16
21
  flushSpatialProjection?(): void;
17
22
  /** stabilization 后是否需要重建唯一 Editor overlay projection。 */
18
23
  hasPendingOverlayWork?(): boolean;
19
- /** stabilization 后、RBush/paint 前重建唯一 Editor overlay projection。 */
24
+ /**
25
+ * R2 更新所属 overlay projection,保持本轮场景与 Viewport 输入固定。
26
+ */
20
27
  flushOverlayProjection?(): void;
21
- /** frame 派生工作和 transform completion 后是否还有完成通知。 */
22
- hasPendingCompletionWork?(): boolean;
23
- /** 在 geometry/spatial/overlay/RBush/paint/hover 后发布完成通知。 */
24
- flushCompletionWork?(): void;
25
28
  /** 使用当前 overlay projection 仲裁 content cursor。 */
26
29
  resolveCursor?(point: PointView | undefined, contentCursor: string): string;
27
30
  /** stabilization failure 时报告仍 dirty 的 owner keys。 */
28
31
  getDirtyOwnerKeys?(): readonly string[];
29
32
  }
30
- /** 在唯一 Root frame 中提交派生布局的稳定 owner。 */
33
+ /**
34
+ * 唯一 Root runtime 的 R1 布局 owner,只安装所属 resolved frame 与真实派生影响。
35
+ */
31
36
  export interface RootFrameLayoutOwner {
32
37
  readonly key: string;
33
38
  /** 在当前 stabilization round 安装该 owner 的最终派生布局。 */
34
39
  flushLayout(): void | readonly Element[];
35
40
  }
36
- /** Root frame-final 内部 work;相同函数引用在同一轮只执行一次。 */
41
+ /**
42
+ * R4 完成通知工作,相同函数引用在同一轮执行一次;后续语义意图使用 scheduleMutation。
43
+ */
37
44
  export type RootFrameCompletionWork = () => void;
38
45
  /** stabilization 超过统一轮次上限时暴露仍 dirty 的 owner keys。 */
39
46
  export declare class FrameStabilizationError extends Error {
@@ -46,25 +53,21 @@ export declare class RootFrameRuntime {
46
53
  private readonly root;
47
54
  readonly animationGroup: Group;
48
55
  private pendingLayers;
56
+ private frameWork;
49
57
  private pendingLayouts;
50
58
  private pendingDirtyTransforms;
51
- private pendingTransformCompletions;
52
- private transformCompletionScratch;
53
59
  private hoverRefreshPending;
54
- private geometryStabilizing;
55
- private publishingTransformCompletions;
56
- private completionFollowUpFrameRequested;
57
60
  private animationFrameScheduled;
58
61
  private animationFrameId;
59
62
  private participant;
63
+ private mutationWork;
64
+ private projectionWork;
60
65
  private completionWork;
61
66
  private nextTickPromise;
62
67
  private nextTickResolve;
63
68
  private nextTickReject;
64
69
  /** 创建绑定指定 Root 生命周期的唯一 frame runtime。 */
65
70
  constructor(root: Root);
66
- /** 当前是否正在同步运行 geometry stabilization rounds。 */
67
- get isStabilizingGeometry(): boolean;
68
71
  /** 安装或移除 Root 生命周期内唯一的无调度 participant。 */
69
72
  setParticipant(participant: RootFrameParticipant | null): void;
70
73
  /** 判断 Layer 是否仍由当前活动 Root 拥有。 */
@@ -75,35 +78,42 @@ export declare class RootFrameRuntime {
75
78
  forgetLayer(layer: Layer): void;
76
79
  /** 合并一个活动 Layer 的 geometry/paint 提交请求。 */
77
80
  scheduleLayerCommit(layer: Layer): void;
78
- /** 登记 stabilization round 结束时需要重置的 dirty transform。 */
81
+ /** 登记在 Layer geometry 提交前需要重置的 dirty transform。 */
79
82
  registerDirtyTransform(transform: ElementTransform): void;
80
83
  /** 合并一个派生布局 owner;同一稳定对象在一轮只提交一次。 */
81
84
  scheduleLayout(owner: RootFrameLayoutOwner): void;
82
85
  /** owner 离开当前 Root 时丢弃其尚未消费的布局工作。 */
83
86
  forgetLayout(owner: RootFrameLayoutOwner): void;
84
- /** @internal 合并实际完成 world transform commit 的 element identity。 */
85
- recordTransformCommit(element: Element): void;
86
- /** 把内部 work 合并到当前 Root 唯一 frame 的 completion phase。 */
87
+ /**
88
+ * 把完成通知合并到 Root 唯一 frame 的 R4;callback 只消费完成事实与登记后续意图。
89
+ */
87
90
  requestCompletion(work: RootFrameCompletionWork): void;
91
+ /** 登记业务 owner 的后续意图,仅在下一次 RAF 的 R0 消费。新登记不进入当前帧。 */
92
+ scheduleMutation(work: () => void): void;
93
+ /** 业务 owner 取消尚未被下一次 RAF 接收的意图。 */
94
+ forgetMutation(work: () => void): void;
95
+ /**
96
+ * R2 更新实际 owner 的 DOM/交互投影,相同函数引用合并一次。
97
+ * callback 消费稳定 geometry,不改变 authored、结构或本轮 Viewport 输入。
98
+ */
99
+ scheduleProjection(work: () => void): void;
100
+ /** 投影 owner 结束时释放尚未消费的登记。 */
101
+ forgetProjection(work: () => void): void;
88
102
  /** 请求推进当前 animation group。 */
89
103
  scheduleAnimation(): void;
90
104
  /** 请求在 geometry、spatial index 和 paint 提交后刷新 hover。 */
91
105
  scheduleHoverRefresh(): void;
92
- /**
93
- * 合并到当前 Root 唯一待执行 RAF。重复调用幂等,且不直接执行任何 phase。
94
- */
106
+ /** 合并到当前 Root 唯一待执行 RAF,重复请求只保留一个登记。 */
95
107
  requestFrame(): void;
96
108
  /**
97
- * 唯一同步稳定入口。取消尚未执行的 RAF,并使用与 RAF 相同的 phase 实现清空工作。
109
+ * @internal 仅供 RAF 的 R0 中真实依赖当前布局的 producer(Scroll clamp)使用。
110
+ * 准备当前帧的布局、几何和查询投影,不绘制或发布完成通知。
98
111
  */
99
- drain(): void;
100
- private hasPendingSynchronousWork;
112
+ prepareMutationGeometry(): void;
101
113
  private needsAnotherFrame;
102
114
  private runFrame;
103
- /** 在 geometry/spatial/overlay/RBush/paint/hover 后派发实际 transform completion。 */
104
- private publishTransformCompletions;
105
- /** callback 边界后只发布当前 Root 和当前 transform 关系仍证明有效的完成事实。 */
106
- private isCurrentTransformCompletion;
115
+ /** 当前 RAF 的唯一 R1/R2 管线。 */
116
+ private prepareScene;
107
117
  /** Core hit path 使用当前唯一 participant 仲裁 overlay/content cursor。 */
108
118
  get hasCursorResolver(): boolean;
109
119
  /** Core hit path 使用当前唯一 participant 仲裁 overlay/content cursor。 */
@@ -116,6 +126,6 @@ export declare class RootFrameRuntime {
116
126
  stop(): void;
117
127
  private resolveNextTick;
118
128
  private rejectNextTick;
119
- /** 返回在当前帧及其同步新增工作稳定后结算的共享 Promise;持续动画不阻塞。 */
129
+ /** 等待当前已接收工作的完成。下一 RAF 才接收的意图有独立完成边界。 */
120
130
  nextTick(): Promise<void>;
121
131
  }
@@ -19,8 +19,8 @@ export interface IteratePointOptions {
19
19
  /** Only strict descendants of this active container key are considered. */
20
20
  readonly scopeRootKey?: string;
21
21
  }
22
- /** 判断元素是否符合当前 Root 的 pointer target 语义。@internal */
23
- export declare function isPointerTarget(root: Root, element: Element): boolean;
22
+ /** 判断 pointer target;给定 world 点时,在同一次祖先遍历中检查 child clips。@internal */
23
+ export declare function isPointerTarget(root: Root, element: Element, point?: PointView): boolean;
24
24
  /**
25
25
  * Yield the single canonical ordered point candidate stream. Broad-phase
26
26
  * Layer/RBush work happens per yielded Layer; filters and precise geometry
@@ -29,6 +29,4 @@ export declare function isPointerTarget(root: Root, element: Element): boolean;
29
29
  export declare function iteratePointElements(root: Root, point: PointView, options?: IteratePointOptions): IterableIterator<Element>;
30
30
  /** Consume and close exactly the first item from Root's canonical stream. */
31
31
  export declare function firstPointElement(root: Root, point: PointView, options?: IteratePointOptions): any;
32
- export declare function checkHit(root: Root, point?: PointView, sourceEvent?: MouseEvent): void;
33
- export declare function clearHit(root: Root, point?: PointView, sourceEvent?: MouseEvent): void;
34
32
  export declare function queryAreaElements(root: Root, area: RectWithCenter, options?: QueryAreaOptions): Element[];
@@ -1,14 +1,14 @@
1
+ import type { PNGExportOptions, PNGExportResult } from "../export-png";
1
2
  import { Node } from "../node/node";
2
3
  import type { NodeProperties } from "../node/properties";
3
4
  import type { Layer } from "../layer";
4
5
  import { Element } from "../node/element";
5
- import { CustomEvent, type EventName, type FulateEventDetail } from "../event";
6
6
  import type { PointView } from "@fulate/share";
7
7
  import { RectWithCenter } from "@fulate/share";
8
8
  import { RootInputController } from "./input-controller";
9
9
  import { Viewport } from "./viewport";
10
10
  import { type QueryAreaOptions, type IteratePointOptions } from "./hit-test";
11
- import { Skin, type SkinChange } from "../skin";
11
+ import { Skin, type SkinChange, type TextStyleConfig } from "../skin";
12
12
  import { RootFrameRuntime } from "./frame-runtime";
13
13
  import { SceneRegistry } from "./scene-registry";
14
14
  import { type ChangeHistorySink, type OwnerPropertyChange, type StructureChange } from "../mutation/change-batch";
@@ -25,7 +25,7 @@ export declare class Root extends Node<NodeProperties, Layer> {
25
25
  private skinTextCommitObservers?;
26
26
  /** Root 的平移、缩放、DPR 和坐标换算对象。 */
27
27
  readonly viewport: Viewport;
28
- /** Root 拥有的输入控制器,提供只读查询、交互范围注册和指针操作取消。 */
28
+ /** Root 拥有的输入控制器,拥有指针与 hover 状态、交互范围注册和指针操作取消。 */
29
29
  readonly input: RootInputController;
30
30
  /** 当前活动节点的只读索引及增量场景订阅。 */
31
31
  readonly sceneRegistry: SceneRegistry;
@@ -33,10 +33,6 @@ export declare class Root extends Node<NodeProperties, Layer> {
33
33
  readonly frameRuntime: RootFrameRuntime;
34
34
  /** Port 绘制、发现、Snap 和新建连接的全局开关;不影响已有 relation。 */
35
35
  enablePorts: boolean;
36
- /** 当前 hover 路径中最深的元素。 */
37
- get currentElement(): Element<import("..").ElementProperties, import("..").BaseElementOption<any>, Partial<Omit<import("..").BaseElementOption<any>, "key" | "children">>>;
38
- /** @internal 当前命中元素从祖先到叶子的 hover 路径。 */
39
- hoverPath: Element[];
40
36
  /** 当前 Root 逻辑宽度。 */
41
37
  private widthValue;
42
38
  /** 当前 Root 逻辑高度。 */
@@ -78,8 +74,11 @@ export declare class Root extends Node<NodeProperties, Layer> {
78
74
  setEnablePorts(enabled: boolean): void;
79
75
  /** @internal Skin setter 安装新值后直接提交到当前 Root。 */
80
76
  commitSkinChange(change: SkinChange): void;
81
- /** @internal 订阅 Skin text commit;返回同一 observer 的注销函数。 */
82
- observeSkinTextCommit(observer: () => void): () => void;
77
+ /**
78
+ * @internal 消费已安装的文字字段;回调返回几何受影响的 owner,Root 合并发布一次。
79
+ * 回调不递归修改 Skin 或场景结构。
80
+ */
81
+ observeSkinTextCommit(observer: (key: keyof TextStyleConfig) => Element | void): () => void;
83
82
  /** @internal 激活 Root 的输入、Viewport 和帧运行时。 */
84
83
  protected onActivate(root: Root | null, layer: Layer | null): void;
85
84
  /** @internal 停用 Root 拥有的输入、Viewport 和帧运行时。 */
@@ -95,8 +94,8 @@ export declare class Root extends Node<NodeProperties, Layer> {
95
94
  registerLayer(layer: Layer): void;
96
95
  /** 按 zIndex 和 Root children 顺序重排 Layer 及其 Canvas DOM。 */
97
96
  private sortLayers;
98
- /** @internal 在 children 事务提交后刷新 Layer 顺序、布局、绘制和 hover。 */
99
- commitStructureChange(owner: Node, changed: readonly Node[]): void;
97
+ /** @internal direct 结构安装与结构 hooks 完成后通知 scene consumers。 */
98
+ notifyStructureChange(owner: Node, changed: readonly Node[]): void;
100
99
  /**
101
100
  * @internal 只消费受影响 owners/subgraph,并合并 Layer 工作。离开的节点已在停用时
102
101
  * 登记旧区域;仍在 owner 下的进入或移动节点只重绘自身子树。绘制顺序由安装期的 sibling
@@ -123,10 +122,14 @@ export declare class Root extends Node<NodeProperties, Layer> {
123
122
  /** 请求动画帧以推进 animationGroup;本方法不会注册 Tween。 */
124
123
  scheduleAnimation(): void;
125
124
  /**
126
- * 等待当前 frame-final completion 及其监听器同步新增的帧工作。
127
- * 持续动画不延迟本次完成。监听器抛错时以同一个 error reject;没有待处理帧时立即完成。
125
+ * 等待当前帧(或下一帧接收的已有工作)完成。空闲时不额外请求 RAF。
126
+ * 帧内新登记给下一 RAF 的意图、持续动画不延长本次等待。
127
+ * callback 等价于 nextTick().then(callback),在帧栈退出后的微任务执行;
128
+ * 返回值、异常与异步结果按原生 Promise 传播。同一回调每次注册分别执行。
129
+ * callback 产生的变化需要另一次等待;停止或未激活时结束等待,不表示已绘制。
128
130
  */
129
131
  nextTick(): Promise<void>;
132
+ nextTick<T>(callback: () => T): Promise<Awaited<T>>;
130
133
  /**
131
134
  * 同步应用领域已经决定的 owner/structure effects。
132
135
  * 同 owner 只 finalize/install 一次,全部 fields/raw links 安装后统一发布。
@@ -134,18 +137,8 @@ export declare class Root extends Node<NodeProperties, Layer> {
134
137
  applyChangeBatch(owners: readonly OwnerPropertyChange[], structure?: readonly StructureChange[], history?: ChangeHistorySink): boolean;
135
138
  /** 按活动场景中的唯一 key 查询节点;key 来自 `node.key`。 */
136
139
  getByKey(key: string): Node | undefined;
137
- /**
138
- * @internal 立即按给定 world 点或最近指针位置刷新 hover。
139
- * @param point world 坐标;省略时转换 `input.lastPointerPos` 的 client 坐标。
140
- * @param sourceEvent 触发本次重算的原始 DOM 鼠标事件。
141
- */
142
- checkHit(point?: PointView, sourceEvent?: MouseEvent): void;
143
- /** @internal 节点停用后,如果它仍在 hover 路径中则重新命中。 */
144
- clearHoverFor(node: Node): void;
145
- /** @internal 安排在下一帧几何和绘制提交后刷新 hover。 */
146
- scheduleHoverRefresh(): void;
147
- /** 当前 Element 是否符合 Root 的 pointer target 语义。 @internal */
148
- isPointerTarget(element: Element): boolean;
140
+ /** 判断 pointer target 资格;提供 world 点时同时检查祖先裁剪。 @internal */
141
+ isPointerTarget(element: Element, point?: PointView): boolean;
149
142
  /**
150
143
  * Lazily yield the topmost precise point candidates in committed paint order.
151
144
  * Scope and exclusions are applied before each candidate's precise hit query.
@@ -163,13 +156,10 @@ export declare class Root extends Node<NodeProperties, Layer> {
163
156
  */
164
157
  queryArea(area: RectWithCenter, options?: QueryAreaOptions): readonly Element[];
165
158
  /**
166
- * @internal 创建并派发一个带 world 坐标的 Fulate 输入事件。
167
- * @param eventName Core 输入事件名。
168
- * @param originalEvent 触发它的原始 DOM 事件;手动派发时可省略。
169
- * @param point 已转换为 Root world 坐标的点。
170
- * @param element 命中的活动元素;省略时事件目标为 Root。
159
+ * 每个指定元素导出一张完整子树 PNG,按输入顺序返回有绘制区域的结果。
160
+ * 空列表返回 [];目标属于当前 Root。共享 Element.exportPNG 的几何等待、绘制与编码路径。
171
161
  */
172
- dispatchInputEvent(eventName: EventName, originalEvent: Event | undefined, point: PointView, element?: Element): CustomEvent<FulateEventDetail<Element<import("..").ElementProperties, import("..").BaseElementOption<any>, Partial<Omit<import("..").BaseElementOption<any>, "key" | "children">>> | Root>>;
162
+ exportPNG(elements: readonly Element[], options?: PNGExportOptions): Promise<PNGExportResult[]>;
173
163
  /** 导出 Root 尺寸、Skin 和 Viewport 状态。 */
174
164
  toJSON(): {
175
165
  /** Viewport 的可序列化状态。 */
@@ -1,10 +1,11 @@
1
- import { Element } from "../node/element";
1
+ import { Element, type AnyElement } from "../node/element";
2
2
  import type { Node as SceneNode } from "../node/node";
3
+ import { CustomEvent, type EventName, type FulateEventDetail } from "../event";
3
4
  import type { Root } from "./index";
4
5
  import type { PointView } from "@fulate/share";
5
6
  /** 判断键盘事件目标是否应保留浏览器原生空格输入。 */
6
7
  export declare function isFormControlTarget(target: EventTarget | null): boolean;
7
- /** Root 拥有的 DOM 输入监听、指针会话和交互范围控制器。 */
8
+ /** Root 拥有的 DOM 输入监听、指针会话、hover 和交互范围控制器。 */
8
9
  export declare class RootInputController {
9
10
  private readonly root;
10
11
  /** @internal 当前 Root 是否处于空格平移模式。 */
@@ -15,6 +16,8 @@ export declare class RootInputController {
15
16
  hasLockPoint: boolean;
16
17
  /** Input 原地更新的唯一 client 坐标。 */
17
18
  private readonly pointerPosition;
19
+ /** 当前命中元素从祖先到叶子的唯一 hover 路径。 */
20
+ private hoverPathValue;
18
21
  /** 最近一次记录的指针是否位于 Root 容器内。 */
19
22
  private pointerInside;
20
23
  /** 当前允许接收元素级指针输入的子树根节点。 */
@@ -29,6 +32,10 @@ export declare class RootInputController {
29
32
  private lastClick;
30
33
  /** @internal 由 Root 构造;单独实例化不会接入 Root 生命周期。 */
31
34
  constructor(root: Root);
35
+ /** 当前 hover 路径中最深的元素;交互范围不改变实际命中结果。 */
36
+ get currentElement(): Element | undefined;
37
+ /** 当前 hover 路径的只读借用;每次更新替换数组,不复制或冻结。 */
38
+ get hoverPath(): readonly Element[];
32
39
  /** 最近一次 DOM 指针的 clientX/clientY 只读借用;后续输入原地更新同一对象。 */
33
40
  get lastPointerPos(): PointView;
34
41
  /** Root 当前是否认为指针位于容器内。 */
@@ -50,6 +57,7 @@ export declare class RootInputController {
50
57
  *
51
58
  * 场景操作按当前交互范围派发一次 pointercancel,不产生 pointerup 或 click;
52
59
  * 平移操作只释放输入状态,保留已经发生的 Viewport 平移。
60
+ * 取消完成后,容器内的 hover 由下一帧刷新;容器外已解除锁定时立即清空 hover。
53
61
  */
54
62
  cancelSession(node?: SceneNode): void;
55
63
  /** @internal 更新容器内外状态。 */
@@ -65,9 +73,21 @@ export declare class RootInputController {
65
73
  * 再次进入时重新注册。注册和注销通过现有帧队列刷新 hover 与 cursor,
66
74
  * 不自动取消进行中的指针操作;需要取消时调用 cancelSession(scope)。
67
75
  */
68
- registerInteractionScope(scope: Element): () => void;
76
+ registerInteractionScope(scope: AnyElement): () => void;
69
77
  /** 判断元素是否属于当前允许交互的子树;无范围限制时为 true,不执行命中或焦点查询。 */
70
- isInteractionTarget(element: Element): boolean;
78
+ isInteractionTarget(element: AnyElement): boolean;
79
+ /**
80
+ * @internal 立即按给定 world 点或最近指针位置刷新 hover。
81
+ * @param point world 坐标;省略时转换 `lastPointerPos` 的 client 坐标。
82
+ * @param sourceEvent 触发本次重算的原始 DOM 鼠标事件。
83
+ */
84
+ checkHit(point?: PointView, sourceEvent?: MouseEvent): void;
85
+ /** @internal 清空 hover,并向仍活动的节点派发 leave。 */
86
+ clearHit(point?: PointView, sourceEvent?: MouseEvent): void;
87
+ /** @internal 移除停用节点;画布外已解锁时立即清空其余 hover。 */
88
+ clearHoverFor(node: SceneNode): void;
89
+ /** @internal 安排在下一帧几何和绘制提交后刷新 hover。 */
90
+ scheduleHoverRefresh(): void;
71
91
  /** Root 容器所属的 Document。 */
72
92
  private get ownerDocument();
73
93
  /** Root 容器所属的 Window;缺失时回退当前全局 window。 */
@@ -76,6 +96,14 @@ export declare class RootInputController {
76
96
  private releaseActiveRoot;
77
97
  /** 保存 DOM client 坐标,供无显式事件的 hover 重算使用。 */
78
98
  private updatePointer;
99
+ /**
100
+ * @internal 创建并派发一个带 world 坐标的 Fulate 输入事件。
101
+ * @param eventName Core 输入事件名。
102
+ * @param originalEvent 触发它的原始 DOM 事件;手动派发时可省略。
103
+ * @param point 已转换为 Root world 坐标的点。
104
+ * @param element 命中的活动元素;省略时事件目标为 Root。
105
+ */
106
+ dispatchEvent(eventName: EventName, originalEvent: Event | undefined, point: PointView, element?: Element): CustomEvent<FulateEventDetail<Element<import("..").ElementProperties, import("..").BaseElementOption<any>, Partial<Omit<import("..").BaseElementOption<any>, "key" | "children">>, Partial<Omit<import("..").BaseElementOption<any>, "key" | "children">>> | Root>>;
79
107
  /** 将一个 DOM 输入转换为 Fulate world 事件并派给当前场景目标。 */
80
108
  private dispatchDomEvent;
81
109
  /** 清除活动 pointer id,并释放容器上的 pointer capture。 */
@@ -84,8 +112,8 @@ export declare class RootInputController {
84
112
  private releasePointerSessionResources;
85
113
  /** 把 pointerup/pointercancel 发给 pointerdown 时捕获的场景目标。 */
86
114
  private notifySceneSession;
87
- /** 取消当前会话、释放捕获,并清除 hover 锁和双击候选。 */
88
- private cancelPointerSession;
115
+ /** @internal 取消匹配会话;Node 停用后再清理 hover,保持取消事件先于停用。 */
116
+ cancelPointerSession(node?: SceneNode, originalEvent?: Event): boolean;
89
117
  /** 回调可能同步停用 Root;发生时立即取消剩余输入流程。 */
90
118
  private stopIfRootInactive;
91
119
  /** 进入空格平移模式,并清除普通 hover。 */
@@ -1,9 +1,12 @@
1
1
  import type { Node } from "../node/node";
2
- /** 监听一个 key 对应节点的注册和注销。 */
2
+ /** 消费指定 key 的注册事实,维护所属依赖/订阅;不在通知中改变节点 placement 或生命周期。 */
3
3
  export type NodeKeyObserver = (node: Node, registered: boolean) => void;
4
- /** 监听当前 Root 中节点进入或离开 active 生命周期。 */
4
+ /** 消费节点进入/离开 active 的事实,维护所属派生登记;不在通知中重新挂载或卸载节点。 */
5
5
  export type NodeRegistrationObserver = (node: Node, registered: boolean) => void;
6
- /** 监听会影响场景查询或工具缓存的变化;省略 node 表示批量结构变化。 */
6
+ /**
7
+ * 消费场景变化以失效查询/投影或清理失效交互;省略 node 表示批量结构变化。
8
+ * 继承 producer 的 R0/R1 阶段,不作为 authored/结构 writer。
9
+ */
7
10
  export type SceneChangeObserver = (node?: Node, affected?: readonly Node[]) => void;
8
11
  /** 管理活动场景的节点 key 索引和轻量变化观察器。 */
9
12
  export declare class SceneRegistry {
@@ -24,28 +27,35 @@ export declare class SceneRegistry {
24
27
  /**
25
28
  * 订阅后续场景查询/结构变化,返回退订函数;不补发当前状态。
26
29
  * 此通知不代表完整属性变化或帧已稳定;Root 销毁时清除订阅。
30
+ * consumer 只维护所属派生工作与交互清理;实际应用事件仍遵循其入口与阶段权限。
27
31
  */
28
32
  observeSceneChanges(observer: SceneChangeObserver): () => boolean;
29
33
  /** @internal 当前是否存在真实 scene change consumer。 */
30
34
  get hasSceneChangeObservers(): boolean;
31
35
  /**
32
36
  * 订阅后续节点进入/离开 active 生命周期,返回退订函数;不补发已有节点。
33
- * 回调时索引与 active 状态已安装;detach/reinsert 分别通知 false/true。
37
+ * 回调时索引、active 状态与本节点活动资源已完成切换。detach/reinsert 分别通知 false/true。
38
+ * 回调可管理自身订阅;本轮新增的同类 observer 从下一次通知接收,已退订者不再调用。
34
39
  * Root 销毁时清除订阅。
35
40
  */
36
41
  observeNodeRegistrations(observer: NodeRegistrationObserver): () => boolean;
37
42
  /** @internal 通知场景观察器;node 省略时表示整批变化。 */
38
43
  notifySceneChange(node?: Node, affected?: readonly Node[]): void;
39
- /** 订阅指定 key 的注册状态变化并返回注销函数。 */
44
+ /**
45
+ * 订阅指定 key 的后续注册变化并返回注销函数;不补发已有节点。
46
+ * 回调只维护所属依赖和订阅,本轮新增的同 key observer 从下一次通知接收。
47
+ */
40
48
  observeNodeKey(key: string, observer: NodeKeyObserver): () => void;
41
- /** 按当前索引状态通知指定 key 的观察者。 */
49
+ /** 交付 Node 生命周期已安装的注册事实。 */
42
50
  private notifyNodeKeyObservers;
43
51
  /** @internal 节点进入 active 状态后发送 key 注册通知。 */
44
52
  notifyNodeRegistered(node: Node): void;
45
53
  /** @internal 写入活动身份;producer 违约时只做 O(1) 诊断。 */
46
54
  registerNodeKey(node: Node): void;
47
- /** @internal 从索引移除停用节点并通知 key 观察器。 */
55
+ /** @internal 从索引移除停用节点。 */
48
56
  unregisterNodeKey(node: Node): void;
57
+ /** @internal 本节点活动资源释放后发送注销通知。 */
58
+ notifyNodeUnregistered(node: Node): void;
49
59
  private notifyNodeRegistrationObservers;
50
60
  /** 返回活动场景中指定 key 对应的节点。 */
51
61
  getByKey(key: string): Node<import("..").NodeProperties, Node<any, any>>;
@@ -11,6 +11,19 @@ export interface ViewportSnapshot {
11
11
  /** world 到容器 CSS 像素的缩放倍率。 */
12
12
  readonly scale: number;
13
13
  }
14
+ /** 一次 viewportchange 中实际变化的维度;缩放和平移可同时变化。 */
15
+ export interface ViewportChange {
16
+ /** scale 是否发生变化。 */
17
+ readonly zoom: boolean;
18
+ /** x 或 y 是否发生变化。 */
19
+ readonly translation: boolean;
20
+ }
21
+ declare module "../event" {
22
+ interface FulateEventMap {
23
+ /** Viewport 完整状态安装后同步发布的变化。 */
24
+ viewportchange: CustomEvent<ViewportChange>;
25
+ }
26
+ }
14
27
  /** `focus()` 在四边预留的 client 像素。 */
15
28
  export interface ViewportInsets {
16
29
  /** 顶部预留的 client 像素。 */
@@ -22,7 +35,11 @@ export interface ViewportInsets {
22
35
  /** 左侧预留的 client 像素。 */
23
36
  left?: number;
24
37
  }
25
- /** 管理 Root 的平移、缩放、DPR、坐标换算和 CSS 快速预览。 */
38
+ /**
39
+ * Root 唯一的 world 到容器坐标变换与绘制 Viewport owner。
40
+ * 平移/缩放通常在 R0 提交;首次布局定位可在 R2 前完成。R2 起本轮绘制输入固定。
41
+ * 同步 viewportchange 事件继承实际 writer 的阶段。
42
+ */
26
43
  export declare class Viewport {
27
44
  /** 当前 Viewport 所属的 Root。 */
28
45
  private readonly activeRoot;
@@ -84,17 +101,13 @@ export declare class Viewport {
84
101
  */
85
102
  getLogicalPosition(clientX: number, clientY: number): PointView;
86
103
  /**
87
- * 将 DPR、Viewport 和可选 own world matrix 写入 Canvas Context。
88
- * @param ctx 要更新 transform 的 Layer 2D Context。
89
- * @param ownMatrix 元素已提交的 own world matrix;绘制 Layer 本身时省略。
104
+ * 向提供的 Canvas Context 写入本轮稳定的 DPR、Viewport 与 own matrix;不提交场景。
90
105
  */
91
106
  applyTransform(ctx: CanvasRenderingContext2D, ownMatrix?: ReadonlyMatrix2D): void;
92
107
  /** 将倍率限制在 Root 创建时的 min/max 范围内。 */
93
108
  private clampScale;
94
109
  /** 提交 Viewport 状态,并决定走 CSS 预览还是完整 Canvas 重绘。 */
95
110
  private commit;
96
- /** 根据实际变化派发 zoom、translation 和 viewportchange。 */
97
- private emitChange;
98
111
  /** @internal 更新 DPR、重设 Layer surface 并完整重绘,不派发 Viewport 事件。 */
99
112
  setDevicePixelRatio(dpr: number): boolean;
100
113
  /**
@@ -124,7 +137,7 @@ export declare class Viewport {
124
137
  focus(rect: RectWithCenter, options?: {
125
138
  /** 矩形四周的容器 CSS 像素留白,默认 `10`。 */
126
139
  padding?: number;
127
- /** 启用 Tween;duration 单位为毫秒。 */
140
+ /** 启用 Tween;duration 单位为毫秒,easing 只计算进度、不提交场景。 */
128
141
  animate?: {
129
142
  duration?: number;
130
143
  easing?: (amount: number) => number;