@fulate/core 1.0.0

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

@@ -0,0 +1,64 @@
+import { type PointView, type Rect } from "@fulate/share";
+import type { ElementOptionPatch } from "./element";
+import { type OriginX, type OriginY } from "./properties";
+/** 交互开始时直接借用的作者 frame 标量。 */
+export interface ReferenceTransformFrame {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+    readonly angle: number;
+    readonly scaleX: number;
+    readonly scaleY: number;
+    readonly skewX: number;
+    readonly skewY: number;
+    readonly originX: OriginX;
+    readonly originY: OriginY;
+}
+/** 一次连续 Transform 唯一的 frozen reference。 */
+export interface ReferenceTransformBaseline {
+    readonly writeMode: "frame-authored" | "authored-geometry" | "pose-authored";
+    readonly startWorldMatrix: DOMMatrixReadOnly;
+    readonly startParentWorldMatrix: DOMMatrixReadOnly;
+    readonly startParentWorldInverseMatrix: DOMMatrixReadOnly;
+    readonly referenceBounds: Readonly<Rect>;
+    readonly frame: Readonly<ReferenceTransformFrame>;
+}
+/** owner 自有 immutable branch 与通用 reference baseline。 */
+export interface ElementTransformBaseline<OwnedState = unknown> {
+    readonly ownedState: OwnedState;
+    readonly reference: ReferenceTransformBaseline;
+}
+/** 当前显示帧从 frozen baseline 直接求值的世界 intent。 */
+export interface TransformIntent {
+    readonly worldDelta: DOMMatrixReadOnly;
+    /** 连续旋转手势从 frozen baseline 累积的未折叠 world 角度。 */
+    readonly unwrappedRotationDelta?: number;
+}
+/** 只有显式 reparent 才携带的新 parent world reference。 */
+export interface ReparentTransformIntent extends TransformIntent {
+    readonly targetParentWorldMatrix: DOMMatrixReadOnly;
+}
+/** 已由调用方持有的最终 world pose 与目标 parent inverse。 */
+export interface ReferenceTransformTarget {
+    readonly worldMatrix: DOMMatrixReadOnly;
+    readonly worldCenter: PointView;
+    readonly parentInverseMatrix: DOMMatrixReadOnly;
+}
+/** 通用 frame patch 与 authored local 坐标 delta。 */
+export interface ReferenceTransformResolution {
+    readonly framePatch: Readonly<ElementOptionPatch>;
+    readonly authoredLocalDelta: DOMMatrixReadOnly;
+}
+/** 判断变换意图是否包含跨父级重挂载所需的目标父级矩阵。 */
+export declare function isReparentTransformIntent(intent: Readonly<TransformIntent | ReparentTransformIntent>): intent is Readonly<ReparentTransformIntent>;
+/**
+ * 从调用方已经持有的最终 world pose 解析 frame/authored geometry。
+ * target 与 reference 都是当前操作的权威输入；函数只计算，不提交或调度。
+ */
+export declare function resolveReferenceTransformTarget(baseline: Readonly<ReferenceTransformBaseline>, target: Readonly<ReferenceTransformTarget>): ReferenceTransformResolution;
+/**
+ * 从 frozen reference 与当前 intent 纯计算最终 frame/authored delta。
+ * 不读取 owner/live state，不提交、不校验、不 clone structured authored state。
+ */
+export declare function resolveReferenceTransform(baseline: Readonly<ReferenceTransformBaseline>, intent: Readonly<TransformIntent | ReparentTransformIntent>): ReferenceTransformResolution;

package/dist/node/shape.d.ts

@@ -0,0 +1,146 @@
+import { Element, BaseElementOption, ElementProperties, type ElementOptionPatch } from "./element";
+import { ElementTransform, type ElementTransformClass } from "./element-transform";
+import { ChangeImpact, type PropertyChanges } from "./properties";
+import { type BackgroundColor, type Edge, type PointView } from "@fulate/share";
+import { type GeometryQuery, type GeometrySnapshot } from "../geometry";
+/** border 相对内容轮廓的绘制位置。 */
+export type BorderPosition = "inside" | "outside";
+/** Shape 阴影样式。 */
+export interface ShadowOption {
+    /** 阴影颜色；默认半透明黑色。 */
+    color?: string;
+    /** 模糊半径，单位为 local 坐标。 */
+    blur?: number;
+    /** x 方向偏移，单位为 local 坐标。 */
+    offsetX?: number;
+    /** y 方向偏移，单位为 local 坐标。 */
+    offsetY?: number;
+}
+/** local 边界四个方向的视觉外扩量。 */
+export interface Outset {
+    /** 顶部外扩量。 */
+    top: number;
+    /** 右侧外扩量。 */
+    right: number;
+    /** 底部外扩量。 */
+    bottom: number;
+    /** 左侧外扩量。 */
+    left: number;
+}
+/** Shape 的填充、border、透明度和阴影选项。 */
+export interface ShapeOption<T = Shape> extends BaseElementOption<T> {
+    /** Canvas 填充和裁剪规则；默认 `"nonzero"`。 */
+    fillRule?: CanvasFillRule;
+    /** 显式填充颜色或渐变；省略时使用 Skin，`null` 表示不填充。 */
+    backgroundColor?: BackgroundColor | null;
+    /** 显式 border 颜色或渐变；省略时使用 Skin，`null` 表示不描边。 */
+    borderColor?: BackgroundColor | null;
+    /** border 宽度，单位为 local 坐标，默认 `0`。 */
+    borderWidth?: number;
+    /** border 绘制位置，默认 `"inside"`。 */
+    borderPosition?: BorderPosition;
+    /** 绘制透明度，默认 `1`。 */
+    opacity?: number;
+    /** 阴影样式；默认 `null`。 */
+    shadow?: ShadowOption | null;
+}
+/** Shape 的增量选项。 */
+export type ShapeOptionPatch<O extends ShapeOption<any> = ShapeOption> = ElementOptionPatch<O>;
+/** Shape 规范化后的样式属性。 */
+export declare class ShapeProperties extends ElementProperties {
+    /** 当前 Canvas 填充和裁剪规则。 */
+    fillRule: CanvasFillRule;
+    /** 当前显式填充颜色或渐变；`undefined` 表示继承 Skin。 */
+    backgroundColor?: BackgroundColor | null;
+    /** 当前显式 border 颜色或渐变；`undefined` 表示继承 Skin。 */
+    borderColor?: BackgroundColor | null;
+    /** 当前 border 宽度。 */
+    borderWidth: number;
+    /** 当前 border 绘制位置。 */
+    borderPosition: BorderPosition;
+    /** 当前绘制透明度。 */
+    opacity: number;
+    /** 当前阴影样式。 */
+    shadow: Readonly<ShadowOption> | null;
+    /** 创建 Shape 样式属性；gradient、shadow 等结构值直接采用输入引用。 */
+    constructor(options?: ShapeOption);
+    getImpact(changes: PropertyChanges): ChangeImpact;
+}
+/** Shape 的 border/shadow hit 与 visual geometry companion runtime。 */
+export declare class ShapeTransform<E extends Shape = Shape> extends ElementTransform<E> {
+    /** 构建包含 outside border、但不含 shadow 的 local 命中边界。 */
+    protected buildLocalHitBounds(snapshot: GeometrySnapshot): Readonly<import("@fulate/share").Rect>;
+    /** 使用 canonical query 命中填充和 outside border。 */
+    protected containsLocalHitPoint(point: PointView, query: GeometryQuery): boolean;
+    /** 构建包含绘制外扩的保守 local 轮廓。 */
+    protected buildVisualOutline(snapshot: GeometrySnapshot): PointView[];
+    /** 构建空间索引使用的 local 绘制 AABB。 */
+    protected buildVisualBounds(snapshot: GeometrySnapshot): Readonly<import("@fulate/share").Rect>;
+}
+/** 提供填充、border、阴影及对应命中几何的可绘制元素。 */
+export declare class Shape<P extends ShapeProperties = ShapeProperties, O extends ShapeOption<any> = ShapeOption<any>> extends Element<P, O> {
+    readonly type: string;
+    /** 当前 Canvas 填充和裁剪规则。 */
+    get fillRule(): CanvasFillRule;
+    /** 当前显式填充颜色或渐变；`undefined` 表示继承 Skin。 */
+    get backgroundColor(): BackgroundColor;
+    /** 当前显式 border 颜色或渐变；`undefined` 表示继承 Skin。 */
+    get borderColor(): BackgroundColor;
+    /** 当前 border 宽度，单位为 local 坐标。 */
+    get borderWidth(): number;
+    /** 当前 border 相对内容轮廓的位置。 */
+    get borderPosition(): BorderPosition;
+    /** 当前绘制透明度。 */
+    get opacity(): number;
+    /** 当前阴影样式；`null` 表示无阴影。 */
+    get shadow(): Readonly<ShadowOption>;
+    /** 创建带填充、border、透明度和阴影样式的 Shape。 */
+    constructor(options?: NoInfer<O>, properties?: P, Transform?: ElementTransformClass);
+    /** 返回 outside border 对 local hit/visual 边界的单侧外扩量。 */
+    getBorderOutset(): number;
+    /** 返回包含 outside border 和 shadow 的四向视觉外扩量。 */
+    getVisualOutset(): Outset;
+    /**
+     * 返回逻辑边对应的局部坐标线段（不含 visual outset）。
+     * 多边形 / 三角形等子类覆写此方法即可让锚点贴着实际轮廓。
+     */
+    getEdgeSegment(edge: Edge): {
+        /** 线段起点。 */
+        start: PointView;
+        /** 线段终点。 */
+        end: PointView;
+    };
+    /**
+     * 返回某条逻辑边上 ratio 处的局部坐标和朝外法线。
+     * 默认实现基于 getEdgeSegment 做线性插值；圆形等曲线形状可直接覆写。
+     */
+    getEdgePosition(edge: Edge, ratio: number): {
+        /** ratio 对应的边上位置。 */
+        pos: PointView;
+        /** 朝外法线的 x 分量。 */
+        nx: number;
+        /** 朝外法线的 y 分量。 */
+        ny: number;
+    };
+    getConnectionPortPosition(edge: Edge, ratio: number): PointView;
+    /** Replay the committed line/cubic snapshot into the current Canvas path. */
+    protected buildResolvedPath(ctx: CanvasRenderingContext2D): void;
+    paint(ctx?: CanvasRenderingContext2D): void;
+    /** 定义形状路径（width × height），hover 复用此路径 */
+    protected buildPath(ctx: CanvasRenderingContext2D): void;
+    /** 构建 border 描边路径 */
+    protected buildBorderPath(ctx: CanvasRenderingContext2D): void;
+    /** 使用 Shape 的实际路径裁剪 children。 */
+    protected applyChildClip(ctx: CanvasRenderingContext2D): void;
+    /** Shape 的 child clip 与其实际填充 path 使用同一 canonical query。 */
+    containsChildClipPoint(point: PointView): boolean;
+    /** 绘制元素自身内容（文字、图片等），默认为空 */
+    protected paintContent(_ctx: CanvasRenderingContext2D): void;
+    /** 绘制 Shape 的填充背景。 */
+    protected paintBackground(ctx: CanvasRenderingContext2D): void;
+    /** 按当前 border 样式绘制内容轮廓。 */
+    protected paintBorder(ctx: CanvasRenderingContext2D): void;
+    /** 在隔离的 Context 状态中绘制 shadow，不影响后续 fill 和 border。 */
+    private paintShadow;
+    paintHover(ctx: CanvasRenderingContext2D, scale: number): void;
+}

package/dist/root/frame-runtime.d.ts

@@ -0,0 +1,122 @@
+import { Group } from "@tweenjs/tween.js";
+import type { Layer } from "../layer";
+import type { ElementTransform } from "../node/element-transform";
+import type { Root } from "./index";
+import type { PointView } from "@fulate/share";
+import { Element } from "../node/element";
+/** Root 唯一 frame runtime 可安装的单 participant 基础协议。 */
+export interface RootFrameParticipant {
+    /** authored mutation work 是否仍需进入 stabilization round。 */
+    hasPendingWork(): boolean;
+    /** 消费本轮唯一 queued authored intent。 */
+    flushMutationPhase(): void;
+    /** stabilization 后是否有待更新的 Editor spatial projection。 */
+    hasPendingSpatialWork?(): boolean;
+    /** stabilization 后、overlay/RBush/paint 前更新 Editor spatial projection。 */
+    flushSpatialProjection?(): void;
+    /** stabilization 后是否需要重建唯一 Editor overlay projection。 */
+    hasPendingOverlayWork?(): boolean;
+    /** stabilization 后、RBush/paint 前重建唯一 Editor overlay projection。 */
+    flushOverlayProjection?(): void;
+    /** frame 派生工作和 transform completion 后是否还有完成通知。 */
+    hasPendingCompletionWork?(): boolean;
+    /** 在 geometry/spatial/overlay/RBush/paint/hover 后发布完成通知。 */
+    flushCompletionWork?(): void;
+    /** 使用当前 overlay projection 仲裁 content cursor。 */
+    resolveCursor?(point: PointView | undefined, contentCursor: string): string;
+    /** stabilization failure 时报告仍 dirty 的 owner keys。 */
+    getDirtyOwnerKeys?(): readonly string[];
+}
+/** 在唯一 Root frame 中提交派生布局的稳定 owner。 */
+export interface RootFrameLayoutOwner {
+    readonly key: string;
+    /** 在当前 stabilization round 安装该 owner 的最终派生布局。 */
+    flushLayout(): void | readonly Element[];
+}
+/** Root frame-final 内部 work；相同函数引用在同一轮只执行一次。 */
+export type RootFrameCompletionWork = () => void;
+/** stabilization 超过统一轮次上限时暴露仍 dirty 的 owner keys。 */
+export declare class FrameStabilizationError extends Error {
+    readonly dirtyOwnerKeys: readonly string[];
+    /** 创建包含稳定化结束时仍 dirty owner keys 的错误。 */
+    constructor(dirtyOwnerKeys: readonly string[]);
+}
+/** 管理 Root 唯一 RAF、稳定化循环、Tween、paint、hover 与 nextTick。 */
+export declare class RootFrameRuntime {
+    private readonly root;
+    readonly animationGroup: Group;
+    private pendingLayers;
+    private pendingLayouts;
+    private pendingDirtyTransforms;
+    private pendingTransformCompletions;
+    private transformCompletionScratch;
+    private hoverRefreshPending;
+    private geometryStabilizing;
+    private publishingTransformCompletions;
+    private completionFollowUpFrameRequested;
+    private animationFrameScheduled;
+    private animationFrameId;
+    private participant;
+    private completionWork;
+    private nextTickPromise;
+    private nextTickResolve;
+    private nextTickReject;
+    /** 创建绑定指定 Root 生命周期的唯一 frame runtime。 */
+    constructor(root: Root);
+    /** 当前是否正在同步运行 geometry stabilization rounds。 */
+    get isStabilizingGeometry(): boolean;
+    /** 安装或移除 Root 生命周期内唯一的无调度 participant。 */
+    setParticipant(participant: RootFrameParticipant | null): void;
+    /** 判断 Layer 是否仍由当前活动 Root 拥有。 */
+    ownsLayer(layer: Layer): boolean;
+    /** 激活后为已存在的 animation、Layer 或 participant 工作请求帧。 */
+    activate(): void;
+    /** Layer 离开 Root 时丢弃其尚未消费的帧登记。 */
+    forgetLayer(layer: Layer): void;
+    /** 合并一个活动 Layer 的 geometry/paint 提交请求。 */
+    scheduleLayerCommit(layer: Layer): void;
+    /** 登记 stabilization round 结束时需要重置的 dirty transform。 */
+    registerDirtyTransform(transform: ElementTransform): void;
+    /** 合并一个派生布局 owner；同一稳定对象在一轮只提交一次。 */
+    scheduleLayout(owner: RootFrameLayoutOwner): void;
+    /** owner 离开当前 Root 时丢弃其尚未消费的布局工作。 */
+    forgetLayout(owner: RootFrameLayoutOwner): void;
+    /** @internal 合并实际完成 world transform commit 的 element identity。 */
+    recordTransformCommit(element: Element): void;
+    /** 把内部 work 合并到当前 Root 唯一 frame 的 completion phase。 */
+    requestCompletion(work: RootFrameCompletionWork): void;
+    /** 请求推进当前 animation group。 */
+    scheduleAnimation(): void;
+    /** 请求在 geometry、spatial index 和 paint 提交后刷新 hover。 */
+    scheduleHoverRefresh(): void;
+    /**
+     * 合并到当前 Root 唯一待执行 RAF。重复调用幂等，且不直接执行任何 phase。
+     */
+    requestFrame(): void;
+    /**
+     * 唯一同步稳定入口。取消尚未执行的 RAF，并使用与 RAF 相同的 phase 实现清空工作。
+     */
+    drain(): void;
+    private hasPendingSynchronousWork;
+    private needsAnotherFrame;
+    private runFrame;
+    /** 在 geometry/spatial/overlay/RBush/paint/hover 后派发实际 transform completion。 */
+    private publishTransformCompletions;
+    /** callback 边界后只发布当前 Root 和当前 transform 关系仍证明有效的完成事实。 */
+    private isCurrentTransformCompletion;
+    /** Core hit path 使用当前唯一 participant 仲裁 overlay/content cursor。 */
+    get hasCursorResolver(): boolean;
+    /** Core hit path 使用当前唯一 participant 仲裁 overlay/content cursor。 */
+    resolveCursor(point: PointView | undefined, contentCursor: string): string;
+    private consumeDirtyTransforms;
+    private flushLayouts;
+    private takePendingLayers;
+    private dirtyOwnerKeys;
+    private stabilize;
+    /** 停止 RAF、Tween 和待处理工作，并结清当前 `nextTick()`。 */
+    stop(): void;
+    private resolveNextTick;
+    private rejectNextTick;
+    /** 返回在当前已安排帧完成后结算的共享 Promise。 */
+    nextTick(): Promise<void>;
+}

package/dist/root/hit-test.d.ts

@@ -0,0 +1,34 @@
+import { type PointView, type RectWithCenter } from "@fulate/share";
+import type { Root } from "./index";
+import { Element } from "../node/element";
+/** `queryArea()` 使用的 world AABB 类型。 */
+export type QueryAreaBounds = "visual" | "hit";
+/** `queryArea()` 的返回顺序。 */
+export type QueryAreaOrder = "paint" | "none";
+/** `queryArea()` 的边界类型和排序选项。 */
+export interface QueryAreaOptions {
+    /** 默认 `"visual"`；使用包含 shadow 的视觉边界或不含 shadow 的命中边界。 */
+    bounds?: QueryAreaBounds;
+    /** 默认 `"paint"`；`"none"` 不保证返回顺序。 */
+    order?: QueryAreaOrder;
+}
+/** Root ordered point-query filters applied before precise geometry. */
+export interface IteratePointOptions {
+    /** Candidate element keys to omit. */
+    readonly exclude?: ReadonlySet<string>;
+    /** Only strict descendants of this active container key are considered. */
+    readonly scopeRootKey?: string;
+}
+/** 判断元素是否符合当前 Root 的 pointer target 语义。@internal */
+export declare function isPointerTarget(root: Root, element: Element): boolean;
+/**
+ * Yield the single canonical ordered point candidate stream. Broad-phase
+ * Layer/RBush work happens per yielded Layer; filters and precise geometry
+ * are evaluated only as the consumer advances the iterator.
+ */
+export declare function iteratePointElements(root: Root, point: PointView, options?: IteratePointOptions): IterableIterator<Element>;
+/** Consume and close exactly the first item from Root's canonical stream. */
+export declare function firstPointElement(root: Root, point: PointView, options?: IteratePointOptions): any;
+export declare function checkHit(root: Root, point?: PointView, sourceEvent?: MouseEvent): void;
+export declare function clearHit(root: Root, point?: PointView, sourceEvent?: MouseEvent): void;
+export declare function queryAreaElements(root: Root, area: RectWithCenter, options?: QueryAreaOptions): Element[];

package/dist/root/index.d.ts

@@ -0,0 +1,196 @@
+import { Node } from "../node/node";
+import type { NodeProperties } from "../node/properties";
+import type { Layer } from "../layer";
+import { Element } from "../node/element";
+import { CustomEvent, type EventName, type FulateEventDetail } from "../event";
+import type { PointView } from "@fulate/share";
+import { RectWithCenter } from "@fulate/share";
+import { RootInputController } from "./input-controller";
+import { Viewport } from "./viewport";
+import { type QueryAreaOptions, type IteratePointOptions } from "./hit-test";
+import { Skin, type SkinChange } from "../skin";
+import { RootFrameRuntime } from "./frame-runtime";
+import { SceneRegistry } from "./scene-registry";
+import { type ChangeHistorySink, type OwnerPropertyChange, type StructureChange } from "../mutation/change-batch";
+export type { QueryAreaBounds, QueryAreaOptions, QueryAreaOrder, IteratePointOptions } from "./hit-test";
+/** Root 当前 committed Canvas/element 绘制顺序。 */
+export interface PaintOrderKey {
+    readonly layer: number;
+    readonly element: number;
+}
+/** 场景树根节点，统一管理 Layer、Viewport、输入、查询和帧提交。 */
+export declare class Root extends Node<NodeProperties, Layer> {
+    /** Root 的序列化类型。 */
+    readonly type: string;
+    /** 承载 Layer Canvas 和 DOM 输入监听的容器。 */
+    readonly container: HTMLElement;
+    /** Root 使用的唯一 Skin；调用者直接修改其属性。 */
+    readonly skin: Skin;
+    /** 只在真实 Text dependent 存在时创建的 Skin text commit observers。 */
+    private skinTextCommitObservers?;
+    /** Root 的平移、缩放、DPR 和坐标换算对象。 */
+    readonly viewport: Viewport;
+    /** @internal Root 拥有的 DOM 输入和指针会话控制器。 */
+    readonly input: RootInputController;
+    /** @internal 活动节点 key 索引和场景变化观察器。 */
+    readonly sceneRegistry: SceneRegistry;
+    /** @internal 跨 Layer 帧队列、动画时钟和 nextTick 状态。 */
+    readonly frameRuntime: RootFrameRuntime;
+    /** Port 绘制、发现、Snap 和新建连接的全局开关；不影响已有 relation。 */
+    enablePorts: boolean;
+    /** 当前 hover 路径中最深的元素。 */
+    get currentElement(): Element<import("..").ElementProperties, import("..").BaseElementOption<any>, Partial<Omit<import("..").BaseElementOption<any>, "key" | "children">>>;
+    /** @internal 当前命中元素从祖先到叶子的 hover 路径。 */
+    hoverPath: Element[];
+    /** 当前 Root 逻辑宽度。 */
+    private widthValue;
+    /** 当前 Root 逻辑高度。 */
+    private heightValue;
+    /** Root 当前的逻辑宽度。 */
+    get width(): number;
+    /** Root 当前的逻辑高度。 */
+    get height(): number;
+    /** 已激活并按最终 Canvas 顺序排列的 Layer。 */
+    private registeredLayers;
+    /** 按 zIndex 和 Root 树顺序排列的活动 Layer 快照。 */
+    get layers(): readonly Layer[];
+    /** Root 每帧推进的 Tween group；自定义 Tween 还需请求动画帧。 */
+    get animationGroup(): import("@tweenjs/tween.js").Group;
+    /**
+     * 创建场景 Root；未传尺寸时读取容器 clientWidth/clientHeight。
+     * children 只能包含 Layer。
+     */
+    constructor(el: HTMLElement, options?: {
+        /** Root 构造期只读 key；省略时由 Core 自动生成。 */
+        readonly key?: string;
+        /** Root 逻辑宽度；默认读取容器 `clientWidth`。 */
+        width?: number;
+        /** Root 逻辑高度；默认读取容器 `clientHeight`。 */
+        height?: number;
+        /** Viewport 允许的最小和最大缩放倍率。 */
+        scale?: {
+            min?: number;
+            max?: number;
+        };
+        /** 是否初始启用 Port 绘制、发现、Snap 和新建连接；默认 `false`。 */
+        readonly enablePorts?: boolean;
+        /** 直接采用的 Skin 实例；省略时为当前内置默认皮肤。 */
+        readonly skin?: Skin;
+        /** 首次挂载的 Layer。 */
+        children?: readonly Layer[];
+    });
+    /** 运行时切换 Port 交互，并失效绘制和场景查询缓存。 */
+    setEnablePorts(enabled: boolean): void;
+    /** @internal Skin setter 安装新值后直接提交到当前 Root。 */
+    commitSkinChange(change: SkinChange): void;
+    /** @internal 订阅 Skin text commit；返回同一 observer 的注销函数。 */
+    observeSkinTextCommit(observer: () => void): () => void;
+    /** @internal 激活 Root 的输入、Viewport 和帧运行时。 */
+    protected onActivate(root: Root | null, layer: Layer | null): void;
+    /** @internal 停用 Root 拥有的输入、Viewport 和帧运行时。 */
+    protected onDeactivate(root: Root | null, layer: Layer | null): void;
+    /**
+     * 更新逻辑尺寸和所有 Layer surface，并在需要时重新布局和绘制；
+     * 实际尺寸变化安装完成后派发一次 `resize`。
+     * @param width Root 的逻辑宽度，通常来自容器 `clientWidth`。
+     * @param height Root 的逻辑高度，通常来自容器 `clientHeight`。
+     */
+    resize(width: number, height: number): void;
+    /** @internal 注册已激活的 Layer，并同步 Canvas 顺序。 */
+    registerLayer(layer: Layer): void;
+    /** 按 zIndex 和 Root children 顺序重排 Layer 及其 Canvas DOM。 */
+    private sortLayers;
+    /** @internal 在 children 事务提交后刷新 Layer 顺序、布局、绘制和 hover。 */
+    commitStructureChange(owner: Node, changed: readonly Node[]): void;
+    /** @internal trusted batch 只消费受影响 owners/subgraph，并合并 Layer 工作。 */
+    commitBatchStructureChanges(changes: readonly {
+        readonly owner: Node;
+        readonly changed: readonly Node[];
+    }[], layerOrderImpact?: boolean): void;
+    private commitStructureChanges;
+    /** @internal 返回结构提交后记录的 Layer 内 paint preorder。 */
+    getPaintOrder(element: Element): number | undefined;
+    /** @internal 返回跨 Layer 可直接比较的 committed paint key。 */
+    getPaintOrderKey(element: Element): PaintOrderKey | undefined;
+    /** @internal Layer zIndex 变化后重排 Canvas 并刷新 hover。 */
+    commitLayerOrderChange(): void;
+    /** @internal 注销停用的 Layer，并清除其待提交帧工作。 */
+    unregisterLayer(layer: Layer): void;
+    /** 请求所有活动 Layer 完整重绘。 */
+    invalidateAll(): void;
+    /** 判断 Layer 是否仍由当前活动 Root 拥有。 */
+    private ownsLayer;
+    /** @internal 将一个 Layer 的待处理工作加入 Root 帧队列。 */
+    scheduleLayerCommit(layer: Layer): void;
+    /** 请求动画帧以推进 animationGroup；本方法不会注册 Tween。 */
+    scheduleAnimation(): void;
+    /**
+     * 等待当前 frame-final completion 及其监听器同步新增的帧工作。
+     * 监听器抛错时以同一个 error reject；没有待处理帧时立即完成。
+     */
+    nextTick(): Promise<void>;
+    /**
+     * 同步应用领域已经决定的 owner/structure effects。
+     * 同 owner 只 finalize/install 一次，全部 fields/raw links 安装后统一发布。
+     */
+    applyChangeBatch(owners: readonly OwnerPropertyChange[], structure?: readonly StructureChange[], history?: ChangeHistorySink): void;
+    /** 按活动场景中的唯一 key 查询节点；key 来自 `node.key`。 */
+    getByKey(key: string): Node | undefined;
+    /**
+     * @internal 立即按给定 world 点或最近指针位置刷新 hover。
+     * @param point world 坐标；省略时转换 `input.lastPointerPos` 的 client 坐标。
+     * @param sourceEvent 触发本次重算的原始 DOM 鼠标事件。
+     */
+    checkHit(point?: PointView, sourceEvent?: MouseEvent): void;
+    /** @internal 节点停用后，如果它仍在 hover 路径中则重新命中。 */
+    clearHoverFor(node: Node): void;
+    /** @internal 安排在下一帧几何和绘制提交后刷新 hover。 */
+    scheduleHoverRefresh(): void;
+    /** 当前 Element 是否符合 Root 的 pointer target 语义。 @internal */
+    isPointerTarget(element: Element): boolean;
+    /**
+     * Lazily yield the topmost precise point candidates in committed paint order.
+     * Scope and exclusions are applied before each candidate's precise hit query.
+     */
+    iteratePoint(point: PointView, options?: IteratePointOptions): IterableIterator<Element>;
+    /**
+     * 返回 world 坐标下最上层的精确命中元素。
+     * @param point 可直接使用 Fulate 指针事件的 `detail.x/y`；DOM client 坐标先用 `viewport.getLogicalPosition()` 转换。
+     */
+    hitTest(point: PointView): Element | undefined;
+    /**
+     * 按 visual/hit world AABB 查询已提交的可选元素。
+     * @param area world 坐标查询矩形。
+     * @param options 选择 visual/hit 边界和返回顺序；省略时使用 visual + paint。
+     */
+    queryArea(area: RectWithCenter, options?: QueryAreaOptions): readonly Element[];
+    /**
+     * @internal 创建并派发一个带 world 坐标的 Fulate 输入事件。
+     * @param eventName Core 输入事件名。
+     * @param originalEvent 触发它的原始 DOM 事件；手动派发时可省略。
+     * @param point 已转换为 Root world 坐标的点。
+     * @param element 命中的活动元素；省略时事件目标为 Root。
+     */
+    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>>;
+    /** 导出 Root 尺寸、Skin 和 Viewport 状态。 */
+    toJSON(): {
+        /** Viewport 的可序列化状态。 */
+        viewport: {
+            x: number;
+            y: number;
+            scale: number;
+            minScale: number;
+            maxScale: number;
+        };
+        /** 当前 Skin 的独立可序列化值。 */
+        skin: Required<import("..").SkinOptions>;
+        /** Root 逻辑宽度。 */
+        width: number;
+        /** Root 逻辑高度。 */
+        height: number;
+    };
+    /** @internal 递归卸载前停止并释放 Root 运行时。 */
+    protected onBeforeUnmount(): void;
+    /** @internal children 清理后释放 Root 持有的索引和输入状态。 */
+    protected onUnmount(): void;
+}

package/dist/root/input-controller.d.ts

@@ -0,0 +1,103 @@
+import { Element } from "../node/element";
+import type { Node as SceneNode } from "../node/node";
+import type { Root } from "./index";
+import type { MutablePointView } from "@fulate/share";
+/** 判断键盘事件目标是否应保留浏览器原生空格输入。 */
+export declare function isFormControlTarget(target: EventTarget | null): boolean;
+/** Root 拥有的 DOM 输入监听、指针会话和交互范围控制器。 */
+export declare class RootInputController {
+    private readonly root;
+    /** @internal 当前 Root 是否处于空格平移模式。 */
+    isSpacePressed: boolean;
+    /** @internal 是否正在用指针平移 Viewport。 */
+    isPanning: boolean;
+    /** @internal 是否应在连续指针操作期间暂停 hover 重算。 */
+    hasLockPoint: boolean;
+    /** @internal 最近一次 DOM 指针的 clientX/clientY，不是 world 坐标。 */
+    lastPointerPos: MutablePointView;
+    /** 最近一次记录的指针是否位于 Root 容器内。 */
+    private pointerInside;
+    /** 当前允许接收元素级输入的工具子树根节点。 */
+    private readonly interactionScopes;
+    /** 一次 Root 激活周期内全部 DOM listener 的统一清理器。 */
+    private abortController;
+    /** 当前捕获的 primary pointer id；`null` 表示没有会话。 */
+    private activePointerId;
+    /** 当前场景点击或空格平移会话。 */
+    private pointerSession;
+    /** 上一次有效 click，用于 500ms/4px 的双击判断。 */
+    private lastClick;
+    /** @internal 由 Root 构造；单独实例化不会接入 Root 生命周期。 */
+    constructor(root: Root);
+    /** @internal Root 当前是否认为指针位于容器内。 */
+    get isPointerInside(): boolean;
+    /** @internal 安装当前 Root 的键盘、指针、滚轮和焦点监听。 */
+    activate(): void;
+    /** @internal 移除监听并清理当前输入和 hover 会话。 */
+    deactivate(): void;
+    /** @internal 停用控制器并释放全部 interaction scope。 */
+    dispose(): void;
+    /** @internal 取消全部指针会话，或仅取消目标位于指定节点子树的场景会话。 */
+    cancelSession(node?: SceneNode): void;
+    /** @internal 更新容器内外状态。 */
+    setPointerInside(inside: boolean): void;
+    /** @internal 注册工具交互范围，只让其子树接收元素级输入，并返回注销函数。 */
+    registerInteractionScope(scope: Element): () => void;
+    /** @internal 判断命中元素是否属于当前任一 interaction scope。 */
+    isInteractionTarget(element: Element): boolean;
+    /** Root 容器所属的 Document。 */
+    private get ownerDocument();
+    /** Root 容器所属的 Window；缺失时回退当前全局 window。 */
+    private get ownerWindow();
+    /** 在指针、焦点和捕获均不属于本 Root 时释放键盘输入归属。 */
+    private releaseActiveRoot;
+    /** 保存 DOM client 坐标，供无显式事件的 hover 重算使用。 */
+    private updatePointer;
+    /** 将一个 DOM 输入转换为 Fulate world 事件并派给当前场景目标。 */
+    private dispatchDomEvent;
+    /** 清除活动 pointer id，并释放容器上的 pointer capture。 */
+    private releasePointer;
+    /** 释放 InputController 自己创建的 pointer capture 和 ephemeral session 状态。 */
+    private releasePointerSessionResources;
+    /** 把 pointerup/pointercancel 发给 pointerdown 时捕获的场景目标。 */
+    private notifySceneSession;
+    /** 取消当前会话、释放捕获，并清除 hover 锁和双击候选。 */
+    private cancelPointerSession;
+    /** 回调可能同步停用 Root；发生时立即取消剩余输入流程。 */
+    private stopIfRootInactive;
+    /** 进入空格平移模式，并清除普通 hover。 */
+    private readonly onKeyDown;
+    /** 退出空格平移模式，并在没有平移会话时恢复 hover。 */
+    private readonly onKeyUp;
+    /** 记录指针进入，并把同 Document 的键盘归属切到当前 Root。 */
+    private readonly onPointerEnter;
+    /** Root 内获得焦点时取得同 Document 的键盘归属。 */
+    private readonly onFocusIn;
+    /** 焦点离开后按当前指针和捕获状态决定是否释放键盘归属。 */
+    private readonly onFocusOut;
+    /** 更新拖动阈值、Viewport 平移或普通场景 pointermove。 */
+    private readonly onPointerMove;
+    /** 无 pointer capture 时清空 hover，并尝试释放键盘归属。 */
+    private readonly onPointerLeave;
+    /** 捕获 primary pointer，并创建场景或平移会话。 */
+    private readonly onPointerDown;
+    /**
+     * 结束捕获会话，派发 up/cancel，并在满足阈值时生成 click/dblclick。
+     *
+     * @privateRemarks
+     * click 必须使用会话结束后重新命中的目标，并与 pointerdown 目标相同。
+     */
+    private finishPointer;
+    /** 正常结束当前 pointer 会话。 */
+    private readonly onPointerUp;
+    /** 以取消状态结束当前 pointer 会话。 */
+    private readonly onPointerCancel;
+    /** 先派发 scene wheel；未取消时再按 DOM delta 缩放 Viewport。 */
+    private readonly onWheel;
+    /** 派发场景 contextmenu，并按 defaultPrevented 决定是否阻止浏览器菜单。 */
+    private readonly onContextMenu;
+    /** pointer capture 意外丢失时取消匹配的活动会话。 */
+    private readonly onLostPointerCapture;
+    /** 宿主窗口失焦时取消会话、空格模式和 hover。 */
+    private readonly onWindowBlur;
+}