@fulate/core 1.0.0

package/dist/layer/dirty-grid.d.ts

@@ -0,0 +1,17 @@
+import { type Rect } from "@fulate/share";
+export interface DirtyGridResult {
+    /** 合并后的脏矩形；`null` 表示应完整重绘 Layer。 */
+    rects: Rect[] | null;
+}
+/** 使用固定 3×3 网格合并零散 damage，并决定是否完整重绘。 */
+export declare class DirtyGrid {
+    /** 每个网格单元当前合并得到的矩形。 */
+    private buckets;
+    /**
+     * 合并可见 damage；返回 `null` 表示合并面积已不值得局部重绘。
+     * @param dirtyRects 已裁剪到可见 world 区域的矩形。
+     * @param visibleArea 当前可见 world 区域面积。
+     * @param fullRepaintRatio 触发完整重绘的面积比例。
+     */
+    merge(dirtyRects: Rect[], visibleArea: number, fullRepaintRatio: number): DirtyGridResult;
+}

package/dist/layer/index.d.ts

@@ -0,0 +1,224 @@
+import { Element, ElementProperties, type AnyElement } from "../node/element";
+import { ElementTransform } from "../node/element-transform";
+import { type PropertyChanges } from "../node/properties";
+import type { BaseElementOption, ElementOptionPatch } from "../node/element";
+import { Bound, type Rect, type RectWithCenter } from "@fulate/share";
+import type { Root } from "../root";
+/** 一轮 Layer 几何和绘制提交所消费的工作快照。
+ *
+ * @internal
+ */
+export interface LayerFrameWork {
+    /** 需要提交布局、矩阵和几何的元素。 */
+    dirtyNodes: Set<Element>;
+    /** 仅需要重新绘制的元素。 */
+    paintDirtyNodes: Set<Element>;
+    /** 元素移除或移动前留下的 world damage 区域。 */
+    damageRects: Rect[];
+    /** 是否跳过脏矩形并完整重绘整层。 */
+    forceFullRepaint: boolean;
+}
+/** Layer 的构造选项。 */
+export interface LayerOption extends Omit<BaseElementOption, "layer"> {
+    /** Root 中的图层顺序，默认 `1`，可通过 `setOptions()` 更新。 */
+    zIndex?: number;
+    /** 当前 Layer 中的元素是否可以参与层级排列，默认 `false`。 */
+    elementArrangementEnabled?: boolean;
+    /** 是否启用脏矩形绘制，默认 `true`，仅构造时设置。 */
+    enableDirtyRect?: boolean;
+    /** 是否允许 Viewport 使用 CSS 快速预览，默认 `true`，仅构造时设置。 */
+    cssTransformable?: boolean;
+    /** 是否显示脏矩形调试层，默认 `false`，仅构造时设置。 */
+    debugDirtyRect?: boolean;
+}
+/** `Layer.setOptions()` 接受的运行时补丁，不包含三个构造期绘制标志。 */
+export type LayerOptionPatch<O extends LayerOption = LayerOption> = Omit<ElementOptionPatch<O>, "enableDirtyRect" | "cssTransformable" | "debugDirtyRect">;
+/** Layer 选项规范化后的属性快照。 */
+export declare class LayerProperties extends ElementProperties {
+    /** 当前图层顺序，默认 `1`。 */
+    zIndex: number;
+    /** 当前 Layer 中的元素是否可以参与层级排列，默认 `false`。 */
+    elementArrangementEnabled: boolean;
+    /** 是否启用脏矩形绘制，默认 `true`。 */
+    enableDirtyRect: boolean;
+    /** 是否允许 CSS 快速预览，默认 `true`。 */
+    cssTransformable: boolean;
+    /** 是否显示脏矩形调试层，默认 `false`。 */
+    debugDirtyRect: boolean;
+    /** 创建并规范化 Layer 属性。 */
+    constructor(options?: LayerOption);
+    /** 将 `zIndex` 变化映射为 Layer 排序和 hover 更新。 */
+    getImpact(changes: PropertyChanges): number;
+}
+/** Layer 以 Root 逻辑尺寸解析 fit，并作为 transform ancestry 终点。 */
+export declare class LayerTransform<E extends Layer = Layer> extends ElementTransform<E> {
+    protected resolveFitSize(): void;
+}
+/** Root 直接拥有的 Canvas 图层及其帧提交状态。 */
+export declare class Layer<P extends LayerProperties = LayerProperties, O extends LayerOption = LayerOption> extends Element<P, O, LayerOptionPatch<O>> {
+    /** 序列化使用的节点类型。 */
+    readonly type: string;
+    /** 由当前 Layer 拥有并挂载到 Root 容器的 Canvas。 */
+    canvasEl: HTMLCanvasElement;
+    /** `canvasEl` 的 2D 绘制上下文。 */
+    ctx: CanvasRenderingContext2D;
+    /** 当前 Root 图层顺序。 */
+    get zIndex(): number;
+    /** 当前 Layer 中的元素是否可以参与层级排列。 */
+    get elementArrangementEnabled(): boolean;
+    /** 是否使用脏矩形绘制。 */
+    get enableDirtyRect(): boolean;
+    /** 是否允许 Viewport 使用 CSS 快速预览。 */
+    get cssTransformable(): boolean;
+    /** 已提交 world visual AABB 的空间索引。 */
+    private spatialIndex;
+    /** Element 到可复用 RBush item 的映射。 */
+    private spatialItems;
+    /** 下一轮 frame runtime 要取走的 Layer 工作。 */
+    private pendingWork;
+    /** 已保存提交前 visual bounds、等待绘制后清理的节点。 */
+    private previousVisualBoundsNodes;
+    /** 当前局部绘制按 parent 选中的直接 children；只在一次 `paint()` 内有效。
+     *
+     * @internal
+     */
+    dirtyPaintChildren: ReadonlyMap<AnyElement, readonly AnyElement[]> | null;
+    /** 当前绘制所属的 Root；只在一次帧提交内有效。
+     *
+     * @internal
+     */
+    paintOwner: Root | null;
+    /** 声明当前节点具有 Layer 结构语义。 */
+    isLayerNode(): this is Layer;
+    /** 是否显示脏矩形调试层。 */
+    get debugDirtyRect(): boolean;
+    /** 脏矩形调试用的独立 Canvas。 */
+    private debugSurface;
+    /** 调试矩形自动清除定时器。 */
+    private debugTimer;
+    /** 本帧需要写入或移出 RBush 的元素。 */
+    private pendingSpatialNodes;
+    /** 合并 damage 超过可见面积此比例时完整重绘。 */
+    private static FULL_REPAINT_RATIO;
+    /** 候选命中达到空间项此比例时直接完整重绘。 */
+    private static CANDIDATE_FULL_REPAINT_RATIO;
+    /** 空间项变更超过现有项此比例时重建整个 RBush。 */
+    private static RBUSH_REBUILD_RATIO;
+    /** 将零散 damage 合并为有限数量矩形的网格。 */
+    private dirtyGrid;
+    /** 创建拥有独立 Canvas surface 的 Layer。 */
+    constructor(options?: NoInfer<O>, properties?: P);
+    /** 首次挂载时建立 Layer 上下文并初始化 Canvas 样式。 */
+    protected onMount(): void;
+    /** 激活时挂载 Canvas、注册 Layer 并安排首次完整提交。 */
+    protected onActivate(root: Root | null): void;
+    /** 停用时注销 Layer、移除 Canvas 并清理 Viewport 绘制记录。 */
+    protected onDeactivate(root: Root | null): void;
+    /** 卸载时释放 Canvas、空间索引、调试层和全部待提交状态。 */
+    protected onUnmount(): void;
+    /** 从 DOM 移除主 Canvas 和可选调试 Canvas。 */
+    private removeCanvases;
+    /** 属性提交后同步 Layer 自有的 Canvas 显示状态。 */
+    protected onPropertiesChanged(current: P, changes: PropertyChanges): void;
+    /**
+     * 按逻辑像素尺寸和 DPR 更新 Canvas backing store，并返回像素尺寸是否变化。
+     * @param width Canvas CSS/逻辑宽度。
+     * @param height Canvas CSS/逻辑高度。
+     * @param dpr 设备像素比，用于计算 backing store 尺寸。
+     */
+    resizeSurface(width: number, height: number, dpr: number): boolean;
+    /** 将需要写入空间索引的元素加入本帧队列。
+     *
+     * @internal
+     */
+    queueSpatialUpdate(node: Element): void;
+    /** 记录已捕获旧 visual bounds 的元素，以便绘制后清理缓存。
+     *
+     * @internal
+     */
+    registerPreviousVisualBounds(node: Element): void;
+    /** 绘制覆盖旧区域后清除节点的提交前 visual bounds。 */
+    private clearPreviousVisualBounds;
+    /** 从 pending 集合、item map 和 RBush 移除节点。 */
+    private removeSpatialItem;
+    /** 元素停用时移除其空间项和待处理状态，并保留需要重绘的旧区域。 */
+    detachNode(node: Element): void;
+    /**
+     * 查询 world visual AABB 相交的已提交元素，可按 Layer 内绘制顺序返回。
+     * @param area world 坐标查询矩形。
+     * @param order `paint` 按前到后排序，`none` 保留空间索引返回顺序。
+     */
+    queryCommittedElements(area: RectWithCenter, order?: "paint" | "none"): Element[];
+    /** @internal Copy the last visual bounds committed to this Layer index. */
+    getCommittedVisualBounds(node: Element): Bound | null;
+    /**
+     * Lazily yields visual-index candidates from the top of this Layer's paint
+     * order. The RBush broad-phase result is sorted in place; precise hit work
+     * stays with the consumer and stops when the iterator is closed.
+     *
+     * @internal
+     */
+    iterateCommittedElements(area: RectWithCenter): IterableIterator<Element>;
+    /** 直接查询 RBush 中与 world AABB 相交的已提交元素。 */
+    private searchCommittedElements;
+    /** 直接查询 RBush 中与 world AABB 相交的已提交空间项。 */
+    private searchCommittedItems;
+    /** 将本帧积累的 visual bounds 更新批量提交到 RBush。 */
+    flushRbush(): void;
+    /** 以节点当前 world visual bounds 创建或更新空间项。 */
+    private updateSpatialItem;
+    /** 标记元素需要重新提交布局、几何、空间索引和绘制。 */
+    invalidateLayout(node: Element): void;
+    /** 标记元素只需重绘而不重新提交几何。 */
+    invalidatePaint(node: Element): void;
+    /** 把当前 Layer 登记到所属 Root 的下一帧。 */
+    private scheduleCommit;
+    /** 请求整层完整重绘而不单独标脏全部元素几何。 */
+    invalidateAll(): void;
+    /** 判断 pendingWork 是否包含 geometry、paint、damage 或完整重绘。 */
+    private hasWork;
+    /** 取走下一轮几何提交要消费的工作快照；没有工作时返回 `null`。
+     *
+     * @internal
+     */
+    takeFrameWork(): LayerFrameWork | null;
+    /** @internal stabilization failure 诊断当前仍 pending 的 dirty owner keys。 */
+    pendingDirtyOwnerKeys(): readonly string[];
+    /** 提交工作快照中的布局和 world 几何，过程中可以产生下一轮工作。
+     *
+     * @internal
+     */
+    flushGeometry(work: LayerFrameWork): void;
+    /** 判断节点或其 ancestor 是否仍有下一帧 damage。 */
+    private hasPendingDamage;
+    /** 清理本次已覆盖且没有再次失效的提交前 visual bounds。 */
+    private clearPaintedDamage;
+    /** 清空并重新绘制整个 Layer Canvas。 */
+    private fullRepaint;
+    /** 树结构变化后提交 Layer 内用于命中排序的 preorder。
+     *
+     * @internal
+     */
+    commitStructureOrder(): void;
+    /** 从最终 damage 的 RBush hits 构建一次绘制期有序邻接表。 */
+    private buildDirtyPaintChildren;
+    /** 裁剪到 damage 矩形，并消费已经完成组织的候选绘制树。 */
+    private paintDirtyRects;
+    /** 按需创建并挂载脏矩形调试 Canvas。 */
+    private ensureDebugSurface;
+    /** 在调试 Canvas 上短暂显示脏矩形和命中轮廓。 */
+    private flashRects;
+    /** 绘制几何稳定后积累的工作，并返回是否产生了真实 Canvas 绘制。
+     *
+     * @internal
+     */
+    flushPaint(work: LayerFrameWork): boolean;
+    /** 将 world damage 转为覆盖完整像素的 backing-store 矩形。 */
+    private worldToScreenRects;
+    /** 在调试层标记本次完整重绘。 */
+    private flashFullRepaint;
+    /** 使用已提交顺序绘制 children。 */
+    paint(ctx?: CanvasRenderingContext2D): void;
+    /** 清空整个 Canvas backing store，不改变场景树或待提交状态。 */
+    clear(): void;
+}

package/dist/mutation/change-batch.d.ts

@@ -0,0 +1,29 @@
+import type { Element } from "../node/element";
+import type { Node } from "../node/node";
+import type { Root } from "../root";
+import { type StructureChange } from "./structure-change";
+/** 领域 owner writer 产生的 typed configured patch effect。 */
+export interface OwnerPropertyChange {
+    readonly owner: Element;
+    readonly patch: Readonly<Record<string, unknown>>;
+}
+/**
+ * 可选 semantic History owner 消费的 actual changed fields/placements。
+ * before 是 finalize 已有的 raw configured source；sink 在语义操作结束时读取 live final，
+ * 并决定是否持久化复制。
+ */
+export interface ChangeHistorySink {
+    /** 记录一个 owner/key 首次触及批次提供的 raw configured before。 */
+    recordPropertyChange(owner: Element, key: string, before: unknown): void;
+    /** 记录一个节点首次触及批次提供的 before placement。 */
+    recordPlacementChange(node: Node, beforeOwner: Node | null, beforeIndex: number): void;
+}
+/**
+ * 同步应用一份 trusted change batch。
+ *
+ * owner effects 先按对象身份合并最终 patch；所有 fields/raw links 安装完成后才运行
+ * History、lifecycle、hooks、dirty 和一次 scene delivery。本函数不提供 rollback、
+ * retry、receipt 或 rejected 结果。
+ */
+export declare function applyChangeBatch(root: Root, ownerEffects: readonly OwnerPropertyChange[], structureEffects?: readonly StructureChange[], history?: ChangeHistorySink): void;
+export type { StructureChange } from "./structure-change";

package/dist/mutation/structure-change.d.ts

@@ -0,0 +1,30 @@
+import type { Node } from "../node/node";
+/** 一个 trusted batch 中某个 affected parent 的最终 children。 */
+export interface StructureChange {
+    readonly owner: Node;
+    readonly children: readonly Node[];
+}
+/** @internal affected-parent install 与 publication 共用的最终 delta。 */
+export interface PreparedStructureChange extends StructureChange {
+    readonly before: readonly Node[];
+    readonly changed: readonly Node[];
+}
+/** @internal structure finalize 交给 install/publication 的局部记录。 */
+export interface PreparedStructureBatch {
+    readonly changes: readonly PreparedStructureChange[];
+    readonly placementNodes: ReadonlySet<Node>;
+}
+/** @internal History-on 时才创建的一项实际 placement 变化。 */
+export interface PreparedPlacementChange {
+    readonly node: Node;
+    readonly beforeOwner: Node | null;
+    readonly beforeIndex: number;
+}
+/** @internal 按 parent 对象身份合并，并只保留最终非空变化。 */
+export declare function prepareStructureBatch(effects: readonly StructureChange[]): PreparedStructureBatch;
+/** @internal History-on 才把 affected-parent delta 收敛为实际 node placements。 */
+export declare function preparePlacementChanges(changes: readonly PreparedStructureChange[]): readonly PreparedPlacementChange[];
+/** @internal 直接安装 affected raw links，并返回需要同步 lifecycle 的局部 roots。 */
+export declare function installStructureLinks(batch: PreparedStructureBatch): readonly Node<import("..").NodeProperties, Node<any, any>>[];
+/** @internal 所有 fields/raw links 安装及 History 记录后同步局部 lifecycle。 */
+export declare function syncStructureLifecycles(nodes: readonly Node[]): void;

package/dist/node/element-transform.d.ts

@@ -0,0 +1,252 @@
+import { Bound, type BoundingBox, type PointView, type Rect } from "@fulate/share";
+import { type GeometryPathPoint, type GeometryPathPosition, type GeometryQuery, type GeometrySnapshot } from "../geometry";
+import type { Root } from "../root";
+import type { Element } from "./element";
+import { ChangeImpact } from "./properties";
+/** 几何缓存内部借出的只读世界边界。 @internal */
+export type GeometryBoundsView = Readonly<Rect & BoundingBox>;
+/** 一次 Layer damage 收集共享的子树 visual bounds memo。 @internal */
+export type DirtyBoundsMemo = Map<ElementTransform, Bound | null>;
+/** Element 构造链传递的 companion Transform constructor。 */
+export type ElementTransformConstructor<E extends Element = Element> = new (element: E) => ElementTransform<E>;
+/** Element 继承构造链内部使用的 existential companion constructor。 */
+export type ElementTransformClass = new (element: never) => ElementTransform;
+/**
+ * 一个 Element 唯一的变换、几何、damage 与子树派生状态 owner。
+ *
+ * 具体 Element 类型通过 companion subclass 覆写 protected 几何、尺寸或矩阵方法。
+ */
+export declare class ElementTransform<E extends Element = Element> {
+    protected readonly element: E;
+    /** 布局解析得到的 x 位移；只供采用 resolved frame 的元素读取。 @internal */
+    resolvedLeft: number | undefined;
+    /** 布局解析得到的 y 位移；只供采用 resolved frame 的元素读取。 @internal */
+    resolvedTop: number | undefined;
+    /** 布局解析得到的宽度；作者宽度优先。 @internal */
+    resolvedWidth: number | undefined;
+    /** 布局解析得到的高度；作者高度优先。 @internal */
+    resolvedHeight: number | undefined;
+    /** 当前 owner 是否需要提交尺寸、matrix 和空间索引。 @internal */
+    needsCommit: boolean;
+    /** descendant 是否仍有待提交变换。 @internal */
+    hasDirtyDescendant: boolean;
+    /** 当前 transform 提交是否正在解析 fitWidth/fitHeight。 */
+    private resolvingFitSize;
+    /** 本轮是否只失效 hit bounds、仍保留旧 visual 几何。 */
+    private hitOnlyInvalidation;
+    /** 自身 reference 或 child world space 是否要求 descendants 重算布局。 */
+    private childLayoutDirty;
+    /** 当前最后一次提交的 own world matrix。 */
+    private worldMatrix;
+    /** worldMatrix 的惰性逆矩阵。 */
+    private inverseWorldMatrix;
+    /** 提供给 children 的 world 坐标空间逆矩阵。 */
+    private inverseChildWorldMatrix;
+    /** local 命中 AABB；`undefined` 表示尚未计算。 */
+    private localHitBounds;
+    /** local 绘制 AABB；`undefined` 表示尚未计算。 */
+    private localVisualBounds;
+    /** 当前 canonical local geometry 快照。 */
+    private geometrySnapshot;
+    /** 下一份 snapshot 使用的 element-local revision。 */
+    private geometryRevision;
+    /** 复用 geometrySnapshot 的定位和包含查询。 */
+    private geometryQuery;
+    /** local 绘制轮廓点缓存。 */
+    private visualOutline;
+    /** visualOutline 变换后的 world 点缓存。 */
+    private worldVisualPoints;
+    /** localHitBounds 变换后的 world AABB。 */
+    private worldHitBounds;
+    /** localVisualBounds 变换后的 world AABB。 */
+    private worldVisualBounds;
+    /** 属性失效前最后一次提交的 world visual bounds。 */
+    private previousVisualBounds;
+    /** 稳定状态下缓存的当前子树 world render coverage。 */
+    private currentRenderCoverageBounds;
+    /** 当前 content subtree 在直接 parent child reference 中的只读 AABB。 */
+    private contentBoundsInParent;
+    /** 只在真实 dependent 存在时创建的内部 transform commit observers。 */
+    private transformCommitObservers?;
+    /**
+     * 创建指定 Element 的唯一 companion runtime。
+     * @param element 拥有此 transform 的 Element。
+     */
+    constructor(element: E);
+    /** Element 进入 active 上下文时要求重新提交自身和空间项。 @internal */
+    activate(): void;
+    /** raw parent link 改变后只标记本地 world commit；publication 在结构阶段统一执行。 @internal */
+    markParentChanged(): void;
+    /** children hook 的 companion Transform 扩展入口。 @internal */
+    runChildrenChanged(): void;
+    /** children raw links 已完整安装后的 dirty publication。 @internal */
+    publishChildrenDirty(): void;
+    /** 失效 visibility 影响的 content/render views 与 ancestor dirty path。 @internal */
+    markVisibilityDirty(): void;
+    /** children 变化时的 Transform 扩展点。 */
+    protected onChildrenChanged(): void;
+    /** descendant 变脏时的 Transform 扩展点。 */
+    protected onDescendantDirty(_child: ElementTransform, _affectsContentBounds: boolean): void;
+    /** 当前 branch 是否贡献到 parent/ancestor content bounds。 */
+    protected contributesToAncestorContentBounds(): boolean;
+    /** @internal dirty propagation 与 content query 共用的 branch role。 */
+    affectsAncestorContentBounds(): boolean;
+    /** 首次进入 dirty-descendant 状态并登记到唯一 RootFrameRuntime。 */
+    private enterDirtyDescendantState;
+    /** 清除当前 transform 的 dirty-descendant 标记。 @internal */
+    clearDirtyDescendantState(root: Root, includeDetached?: boolean): void;
+    /** 失效当前 owner 和 Layer 以内 ancestors 的 render coverage/dirty path。 */
+    private markDirtyAncestors;
+    /** @internal 失效当前 transform 及 Layer 以内 ancestors 的 render coverage。 */
+    invalidateRenderCoverageBounds(): void;
+    /** 构建 transform reference bounds；子类可覆盖。 */
+    protected buildLayoutReferenceBounds(): Readonly<Rect> | null;
+    /** 使用本次提交的 reference bounds 构建 canonical rectangle snapshot。 */
+    protected buildGeometrySnapshot(revision: number, layoutReferenceBounds?: Readonly<Rect>): GeometrySnapshot;
+    /** 构建命中候选使用的 local AABB；默认复用 reference bounds。 */
+    protected buildLocalHitBounds(snapshot: GeometrySnapshot): Readonly<Rect> | null;
+    /** 在 AABB 粗筛后执行精确 local 命中判断。 */
+    protected containsLocalHitPoint(point: PointView, query: GeometryQuery): boolean;
+    /** 构建用于精确世界投影的 local 绘制轮廓。 */
+    protected buildVisualOutline(snapshot: GeometrySnapshot): readonly PointView[];
+    /** 构建权威 local 绘制边界。 */
+    protected buildVisualBounds(snapshot: GeometrySnapshot): Readonly<Rect> | null;
+    /** 覆盖后可直接提供完整 world 矩阵；返回 `null` 使用标量变换。 */
+    protected buildWorldMatrix(): DOMMatrix | null;
+    /** 返回标量 world matrix 计算使用的 transform reference bounds。 */
+    protected getWorldMatrixReferenceBounds(): Readonly<Rect> | null;
+    /** world matrix 是否参与当前元素 local geometry 的解析。 */
+    protected worldMatrixAffectsLocalGeometry(): boolean;
+    /** 返回当前节点提供给 children 的 world 坐标空间。 */
+    protected getChildWorldMatrixView(): DOMMatrixReadOnly;
+    /** 按属性影响范围失效对应的几何缓存。 */
+    private invalidateCache;
+    /** 借用 canonical snapshot 的 transform reference bounds。 @internal */
+    getLayoutReferenceBoundsView(): Readonly<Rect>;
+    /** 当前 canonical snapshot 是否包含 resolved vertex。 @internal */
+    hasGeometry(): boolean;
+    /** 惰性构建 local 命中 AABB；没有专用 hook 时复用逻辑边界。 */
+    private getLocalHitBounds;
+    /** 返回当前 local 几何快照。 */
+    getGeometrySnapshot(): GeometrySnapshot;
+    /** @internal Current local-geometry identity for owner-local derived views. */
+    getLocalGeometryRevision(): number;
+    /** 返回复用当前快照的几何查询对象。 */
+    getGeometryQuery(): GeometryQuery;
+    /** 立即提交自身 world 矩阵并返回副本。 */
+    updateWorldMatrix(): DOMMatrix;
+    /** 清除 world 投影；world-dependent local geometry 只在矩阵实际变化时失效。 */
+    private finishWorldMatrixCommit;
+    /** 以给定 parent reference 组合当前 authored scalar matrix。 */
+    protected writeScalarMatrix(matrix: DOMMatrix, parentMatrix?: DOMMatrixReadOnly): DOMMatrix;
+    /** 提交作者 world matrix 并清除依赖它的投影。 */
+    private commitWorldMatrix;
+    /** 返回已提交的 world 矩阵副本，不包含 Viewport 和 DPR。 */
+    getWorldMatrix(): DOMMatrix;
+    /** 借用已提交矩阵；调用方不得修改或保留。 @internal */
+    getWorldMatrixView(): DOMMatrixReadOnly;
+    /** 借用已提交 child 坐标空间的逆矩阵。 @internal */
+    getChildWorldInverseMatrixView(): DOMMatrixReadOnly;
+    /** 返回已解析尺寸中心对应的 world 坐标。 */
+    getWorldCenter(): PointView;
+    /** 将 local 点转换为 world 点。 */
+    toWorld(point: PointView): PointView;
+    /** 将 world 点转换为 local 点；矩阵不可逆时返回 `undefined`。 */
+    toLocal(point: PointView): PointView | undefined;
+    /** 求值 snapshot-local path position，并转换 point/tangent/normal 到 world。 */
+    getWorldPathPoint(position: GeometryPathPosition): GeometryPathPoint | undefined;
+    /** 判断 world 点是否位于当前闭合几何内或边界上。 */
+    containsWorldPoint(point: PointView): boolean;
+    /** 借用已提交的 world 命中 AABB。 @internal */
+    getWorldHitBoundsView(): GeometryBoundsView;
+    /** 返回 world 绘制轮廓的独立点数组。 */
+    getWorldVisualPoints(): PointView[];
+    /** 返回 world 绘制 AABB 的独立副本。 */
+    getWorldVisualBounds(): Bound;
+    /** 借用当前 snapshot 的 local 绘制 AABB。 @internal */
+    getLocalVisualBoundsView(): Readonly<Rect> | null;
+    /** 返回自身贡献给 ancestor content query 的 local bounds。 */
+    protected getOwnContentBoundsView(): Readonly<Rect> | null;
+    /** 借用已提交的 world 绘制 AABB。 @internal */
+    getWorldVisualBoundsView(): GeometryBoundsView;
+    /** 构建当前 owner 的完整 world 绘制 AABB。 */
+    protected buildWorldVisualBounds(): Bound;
+    /** 将 local AABB 四角投影为当前 own world matrix 下的 world AABB。 */
+    private toWorldBounds;
+    /** 将 local AABB 四角投影到指定 reference matrix。 */
+    protected toBounds(matrix: DOMMatrixReadOnly, bounds: Readonly<Rect> | null): Bound;
+    /** 惰性构建当前快照对应的 local 绘制轮廓。 */
+    private getVisualOutline;
+    /** 借用已提交的 world 绘制轮廓。 @internal */
+    getWorldVisualPointsView(): readonly PointView[];
+    /** 在清理 visual 缓存前保存最后一次提交的 world 绘制范围。 */
+    private captureCurrentVisualBounds;
+    /** 将旧 visual bounds交给当前 transform 和所属 Layer 的 damage 跟踪。 */
+    private captureVisualBounds;
+    /** 返回累积旧 visual bounds 的独立副本。 @internal */
+    getPreviousVisualBounds(): Bound | null;
+    /** 是否保存了失效前的 visual bounds。 @internal */
+    hasPreviousVisualBounds(): boolean;
+    /** 清除失效前的 visual bounds。 @internal */
+    clearPreviousVisualBounds(): void;
+    /** @internal 按影响范围失效几何并安排 Layer 提交。 */
+    invalidate(impact: ChangeImpact, previousBounds?: Readonly<BoundingBox> | null): void;
+    /** 标记 local 几何需要重新构建。 */
+    markGeometryNeedsLayout(notifyScene?: boolean): void;
+    /** 安排当前元素所属 Layer 重绘。 @internal */
+    markPaintDirty(): void;
+    /** 标记 world 变换失效并安排 Layer 提交。 */
+    markNeedsLayout(notifyScene?: boolean): void;
+    /** @internal 订阅实际 world transform commit；返回同一 observer 的注销函数。 */
+    observeTransformCommit(observer: (transform: ElementTransform) => void): () => void;
+    /** 安装一次最终 resolved frame delta，并只发布一次合并后的几何影响。 */
+    private installResolvedFrame;
+    /** @internal 提交由布局解析得到的尺寸。 */
+    commitResolvedSize(width: number | undefined, height: number | undefined): boolean;
+    /** @internal 提交一个布局 owner 最终解析出的完整 frame。 */
+    commitResolvedFrame(frame: Readonly<Rect> | null): boolean;
+    /** 根据 parent 尺寸解析 fitWidth 和 fitHeight。 */
+    protected resolveFitSize(): void;
+    /** 立即提交当前节点所在的最高脏变换链。 */
+    bubbleUpdateTransform(): void;
+    /** @internal 仅在祖先变换脏时同步提交当前 world 变换链。 */
+    updateWorldTransformChain(): void;
+    /** 找到当前节点上方、Layer 以内最高的脏 Transform。 */
+    private findHighestDirtyAncestor;
+    /** 提交自身尺寸、world matrix 和空间索引更新，不递归 children。 */
+    private commitOwnTransform;
+    /** @internal 立即提交当前脏子树的变换和几何。 */
+    updateTransform(parentLayoutDirty?: boolean): void;
+    /** 返回本次失效前后覆盖到的 world 脏区域。 */
+    getDirtyRect(): Bound;
+    /** @internal 复用当前 Layer damage 收集已经解析的子树范围。 */
+    getDirtyRect(memo: DirtyBoundsMemo): Bound | null;
+    /** 返回自身与可见 descendants 的已提交 world render coverage。 */
+    getRenderCoverageBounds(): Bound;
+    /** 返回排除 decoration boundary 后的 world content subtree bounds。 */
+    getContentBounds(): Bound;
+    /** 在指定 reference 中沿 canonical local matrices 解析 content subtree。 */
+    protected collectContentBoundsInReference(parentMatrix: DOMMatrixReadOnly, referenceWorldInverse: DOMMatrixReadOnly): Bound | null;
+    /** 返回当前 content subtree 在直接 parent child reference 中的 AABB。 */
+    getContentBoundsInParentView(): GeometryBoundsView | null;
+    /** 借用排除 decoration boundary 后的已提交 world content bounds。 */
+    getWorldContentBoundsView(): GeometryBoundsView | null;
+    /** 借用自身与可见 descendants 的已提交 world render coverage。 @internal */
+    getRenderCoverageBoundsView(): Readonly<BoundingBox & Rect> | null;
+    /** 合并子树每个节点提交前后的 visual bounds，形成 damage 区域。 */
+    private collectDirtySubtreeBounds;
+    /** 将当前 owner local child clip 转换成保守的 world AABB。 */
+    private getWorldChildClipBounds;
+    /** 借用精确命中前使用的 world AABB。 @internal */
+    getHitTestBounds(): Readonly<BoundingBox>;
+    /** 返回命中边界变换到浏览器 client 坐标后的旋转 AABB。 */
+    getBoundingClientRect(): Bound;
+    /** 判断 world 点是否精确命中当前元素。 */
+    hasPointHint(point: PointView): boolean;
+    /** 判断自身或可见 descendants 是否与当前 Viewport 相交。 */
+    hasInView(): boolean;
+    /** 清除依赖 world matrix 的逆矩阵和 world 投影缓存。 */
+    private clearWorldProjection;
+    /** Element 卸载时释放全部 transform-owned 派生状态。 */
+    dispose(): void;
+}