@fulate/tools 1.0.0

package/dist/line/index.d.ts

@@ -0,0 +1,29 @@
+import { Element, Layer, type BaseElementOption, type Root } from "@fulate/core";
+import type { LineDecoration } from "@fulate/ui";
+export interface LineToolOption extends BaseElementOption {
+    contentLayer?: string | Layer;
+    resultType?: "line" | "lineTree";
+    tailDecoration?: LineDecoration;
+}
+/**
+ * Line command/paint surface。Root listeners、mode、draft 与 History 全由唯一
+ * EditorInteractionController 拥有。
+ */
+export declare class LineTool extends Element {
+    readonly type = "lineTool";
+    private readonly contentLayer;
+    private readonly resultType;
+    private readonly tailDecoration;
+    constructor(options?: LineToolOption);
+    startDrawing(): void;
+    stopDrawing(): void;
+    cancelDrawing(): void;
+    protected onDeactivate(root: Root | null, layer: Layer | null): void;
+    /** @internal controller 在 final confirm 时解析唯一 structure destination。 */
+    getContentLayerForController(): Layer<import("@fulate/core").LayerProperties, import("@fulate/core").LayerOption>;
+    /** @internal drawing session开始时读取一次，之后不再跟随配置变化。 */
+    getResultTypeForController(): "lineTree" | "line";
+    /** @internal drawing session 开始时读取一次。 */
+    getTailDecorationForController(): LineDecoration;
+    paint(): void;
+}

package/dist/rule/index.d.ts

@@ -0,0 +1,35 @@
+import { Element, type BaseElementOption, type ElementOptionPatch, type Layer, type Root } from "@fulate/core";
+import type { Select } from "../select";
+export interface RuleOption extends BaseElementOption {
+    /** 同一编辑器组合中提供 live selection projection 的直接引用。 */
+    select?: Select;
+    rulerSize?: number;
+    backgroundColor?: string;
+    cornerBackgroundColor?: string;
+    majorTickColor?: string;
+    minorTickColor?: string;
+    borderColor?: string;
+    textColor?: string;
+    /** 标尺选区颜色；省略时每次绘制读取当前 root.skin.selection。 */
+    selectionColor?: string;
+}
+export declare class Rule extends Element {
+    readonly type = "rule";
+    private readonly appearance;
+    private readonly select;
+    private readonly workspaceFocusInsets;
+    constructor(options?: RuleOption);
+    get rulerSize(): number;
+    get backgroundColor(): string;
+    get cornerBackgroundColor(): string;
+    get majorTickColor(): string;
+    get minorTickColor(): string;
+    get borderColor(): string;
+    get textColor(): string;
+    get selectionColor(): string;
+    protected onActivate(root: Root | null, layer: Layer | null): void;
+    protected onDeactivate(root: Root | null, layer: Layer | null): void;
+    setOptions(options?: ElementOptionPatch<RuleOption>): this;
+    private setAppearance;
+    paint(): void;
+}

package/dist/select/align.d.ts

@@ -0,0 +1,3 @@
+import type { Select } from "./index";
+export type AlignType = "justify-start" | "justify-center" | "justify-end" | "justify-between" | "align-start" | "align-center" | "align-end" | "align-between";
+export declare function alignElements(select: Select, type: AlignType): void;

package/dist/select/arrange.d.ts

@@ -0,0 +1,11 @@
+import type { Select } from "./index";
+/** Select 支持的跨 Layer 与 sibling 排列方向。 */
+export declare enum ArrangeType {
+    LayerUp = "layer-up",
+    LayerDown = "layer-down",
+    Forward = "forward",
+    Backward = "backward",
+    Top = "top",
+    Bottom = "bottom"
+}
+export declare function arrangeElements(select: Select, type: ArrangeType): void;

package/dist/select/checkElement.d.ts

@@ -0,0 +1,2 @@
+import { Element } from "@fulate/core";
+export declare function checkElement(element: Element, excludes?: readonly Element[], scopeRootKey?: string): Element | undefined;

package/dist/select/clipboard.d.ts

@@ -0,0 +1,40 @@
+import { Element, Node } from "@fulate/core";
+import { type DeserializeFactory } from "@fulate/import";
+import type { HistoryScope } from "../history";
+import type { Select } from "./index";
+export interface ClipboardPlugin {
+    readonly type: string;
+    readonly deserialize: DeserializeFactory;
+}
+/** Copy producer 读取的 live selection 与一次收集的完整 subtree key 集合。 */
+export interface CopyContext {
+    readonly sources: readonly Element[];
+    /** Fulate 在 snapshot 过程中已经收集的完整 source subtree keys。 */
+    readonly sourceKeys: ReadonlySet<string>;
+}
+/** 生成透明 applicationData；Fulate 不解释或额外复制返回值。 */
+export type ClipboardDataProducer = (context: CopyContext) => unknown;
+/** Paste 安装接缝收到的同一 applicationData、clone keyMap 与当前 History scope。 */
+export interface PasteContext {
+    readonly applicationData: unknown;
+    /** Clipboard 中全部旧 key 到本次实际新 key 的同一份映射。 */
+    readonly keyMap: ReadonlyMap<string, string>;
+    /** History 关闭时为 undefined。 */
+    readonly history: HistoryScope | undefined;
+}
+/** 为一个非 Layer 顶层副本解析最终 live parent。 */
+export type PasteParentResolver = (sourceParent: Node | undefined) => Node;
+/** Paste 的 parent resolver 与 Canvas 安装后应用接缝。 */
+export interface PasteOptions {
+    readonly resolveParent?: PasteParentResolver;
+    readonly afterInstall?: (context: PasteContext) => void;
+}
+/** Canvas 删除闭包安装后的应用接缝上下文。 */
+export interface DeleteContext {
+    /** selected roots、descendants 与连带依赖节点组成的真实删除闭包。 */
+    readonly elements: readonly Element[];
+    /** History 关闭时为 undefined。 */
+    readonly history: HistoryScope | undefined;
+}
+export declare function copyElements(select: Select, producer?: ClipboardDataProducer): void;
+export declare function pasteElements(select: Select, deserializers: ReadonlyMap<string, DeserializeFactory>, options?: PasteOptions): Promise<void>;

package/dist/select/delete.d.ts

@@ -0,0 +1,3 @@
+import type { DeleteContext } from "./clipboard";
+import type { Select } from "./index";
+export declare function deleteElements(select: Select, afterInstall?: (context: DeleteContext) => void): void;

package/dist/select/grouping.d.ts

@@ -0,0 +1,5 @@
+import { Element } from "@fulate/core";
+import { Group } from "@fulate/ui";
+import type { Select } from "./index";
+export declare function doGroup(select: Select): Group;
+export declare function unGroup(select: Select): Element<import("@fulate/core").ElementProperties, import("@fulate/core").BaseElementOption<any>, Partial<Omit<import("@fulate/core").BaseElementOption<any>, "key" | "children">>>[];

package/dist/select/index.d.ts

@@ -0,0 +1,119 @@
+import { Element, ElementProperties, type BaseElementOption, type ConnectionPortRef, type Layer, type Root } from "@fulate/core";
+import { EditorInteractionController } from "../editor/interaction-controller";
+import { HistoryManager } from "../history";
+import { type AlignType } from "./align";
+import { type ArrangeType } from "./arrange";
+import { type ClipboardDataProducer, type ClipboardPlugin, type DeleteContext, type PasteOptions } from "./clipboard";
+import { Snap } from "./snap";
+import type { EndpointRef } from "@fulate/ui";
+import type { FlipDirection, ResizeOptions } from "./transform";
+import type { LineTool } from "../line";
+export type { FlipDirection, ResizeAnchor, ResizeOptions } from "./transform";
+export type { CopyContext, ClipboardDataProducer, DeleteContext, PasteContext, PasteOptions, PasteParentResolver } from "./clipboard";
+export interface SelectKeyboardCommands {
+    copy(): void;
+    cut(): void;
+    paste(): void | Promise<void>;
+    delete(): void;
+}
+export interface ToolsConnectionIntent {
+    readonly source: EndpointRef;
+    readonly target: ConnectionPortRef;
+    connect(): void;
+}
+export type ConnectionGesture = "auto" | false | ((intent: ToolsConnectionIntent) => void);
+export interface SelectOption extends BaseElementOption {
+    readonly connectionGesture?: ConnectionGesture;
+    /** 同一编辑器组合中用于吸附的直接工具引用。 */
+    readonly snap?: Snap;
+    /** 同一编辑器组合中由快捷键启动的直接画线工具引用。 */
+    readonly lineTool?: LineTool;
+}
+/** 一次 selection property intent；同一 canonical reference 直接交给各 owner。 */
+export type SelectedPropertyPatch = Readonly<Record<string, unknown>>;
+/**
+ * 轻量 Editor command/paint surface；交互状态由唯一 controller 拥有。
+ *
+ * `select:end` 在一次显式选择、交互选择、selection-producing command
+ * 或 History replay 的内部工作和 selection projection 完成后异步通知。
+ * `select:update` 仅在存在直接监听器时，于选中内容的几何、投影和绘制
+ * 在当前 Root frame 内稳定后同步派发；同一显示帧的连续变化合并为一次通知。
+ * `select:configured-change` 在一次 Select/History 语义操作产生最终 configured
+ * 属性或结构净变化时异步通知一次；适用的 History entry/stack 已先安装。事件不携带
+ * payload，普通 noop 与纯 runtime override 不派发；`select:end` 不承担持久化。
+ * 每次显式 `select()` 都是一次独立操作，包括重复传入同一 selection。全部 Select
+ * `end/configured-change/undo/redo` 通知只供外部读取派发时的 live state，不参与、阻止或使已完成的同步操作失败。
+ */
+export declare class Select extends Element {
+    controlSize: number;
+    hitPadding: number;
+    snapAngle: number;
+    snapThreshold: number;
+    history: HistoryManager;
+    readonly connectionGesture: ConnectionGesture;
+    readonly snapTool: Snap | undefined;
+    readonly lineTool: LineTool | undefined;
+    private controller?;
+    private keyboardCommands?;
+    private readonly clipboardDeserializers;
+    constructor(options?: SelectOption);
+    get selectedElements(): readonly Element[];
+    get editorState(): import("../editor/interaction-controller").EditorInteractionState;
+    /** @internal command modules使用同一 controller/batch/History owner。 */
+    get interactionController(): EditorInteractionController;
+    /** 以一次独立操作选择给定元素，并在完成后异步通知 `select:end`。 */
+    select(elements: readonly Element[]): void;
+    /**
+     * Groups the live multi-selection. Accepted active Transform work finishes
+     * before the independent Group command; stale pointer continuation is ignored.
+     * An obvious insufficient-selection noop does not drain the frame runtime.
+     */
+    doGroup(): import("@fulate/ui").Group;
+    /**
+     * Ungroups the live single Group selection. Accepted active Transform work
+     * finishes before the independent command; stale pointer continuation is ignored.
+     * An obvious non-Group noop does not drain the frame runtime.
+     */
+    unGroup(): Element<ElementProperties, BaseElementOption<any>, Partial<Omit<BaseElementOption<any>, "key" | "children">>>[];
+    align(type: AlignType): void;
+    /** 按当前 Layer 与 sibling 顺序排列 live selection。 */
+    arrange(type: ArrangeType): void;
+    /**
+     * 把一次 authored 顶层属性 intent 应用到全部 live selected elements。
+     * 省略字段保持不变，`undefined` 恢复默认值，`null` 是普通领域值；
+     * 对象和数组不 deep merge/patch；Tools 将同一份 patch 引用直接交给全部
+     * selected owners。调用者需要独立副本时应在交付前复制；标量相同值仍是 noop。
+     * Tools 不过滤元素是否支持字段。
+     * 空 selection 不结束其他交互；非空 selection 先完成已接受交互，再以
+     * 一个 batch 和最多一条 History 提交。本命令不改变 selection，也不派发
+     * `select:end`；最终 configured 净变化异步通知一次 `select:configured-change`。
+     * geometry impact 可触发 `select:update`，纯 paint 不触发该几何事件。
+     * 世界有效尺寸与位置仍使用 resize/Transform 命令。
+     */
+    setProperties(patch: SelectedPropertyPatch): void;
+    /**
+     * Resizes the live selection to world visual/frame dimensions in one
+     * semantic command. Omitted axes keep their current size; `top-left` is the
+     * default fixed anchor. Parent and nested Group transforms are resolved
+     * internally.
+     */
+    resize(options?: ResizeOptions): void;
+    /** 围绕当前 selection frame 中心沿 frame 自身轴镜像。 */
+    flip(direction: FlipDirection): void;
+    /** 删除当前 selection，并在 Canvas 删除安装后、drain/finish 前交付一次应用接缝。 */
+    delete(afterInstall?: (context: DeleteContext) => void): void;
+    /**
+     * 复制 live selection 到 Clipboard v2；producer 最多同步执行一次，不改 Canvas、selection 或 History。
+     */
+    copy(producer?: ClipboardDataProducer): void;
+    /** 从 system Clipboard 或同一 memory payload 粘贴，并在安装后交付可选应用接缝。 */
+    paste(options?: PasteOptions): Promise<void>;
+    /** 绑定当前唯一应用键盘命令 owner；cleanup 只清除仍属于本次绑定的引用。 */
+    bindKeyboardCommands(commands: SelectKeyboardCommands): () => void;
+    /** @internal Controller 读取当前唯一键盘 command owner。 */
+    get keyboardCommandOwner(): SelectKeyboardCommands;
+    useClipboard(...plugins: ClipboardPlugin[]): this;
+    protected onActivate(root: Root | null, layer: Layer | null): void;
+    protected onDeactivate(root: Root | null, layer: Layer | null): void;
+    paint(): void;
+}

package/dist/select/paint.d.ts

@@ -0,0 +1,4 @@
+import type { EditorInteractionController } from "../editor/interaction-controller";
+import type { Select } from "./index";
+/** paint 与 hit 直接读取 controller 当前同一 projection object。 */
+export declare function paintSelect(select: Select, controller: EditorInteractionController): void;

package/dist/select/port-index.d.ts

@@ -0,0 +1,42 @@
+import { Element, type ConnectionPortDefinition, type ConnectionPortRef, type Root } from "@fulate/core";
+import type { PointView } from "@fulate/share";
+import { type EditorSpatialClient } from "@fulate/ui";
+export interface IndexedConnectionPort {
+    readonly ref: ConnectionPortRef;
+    readonly kind: "endpoint-binding";
+    readonly worldPosition: PointView;
+    readonly definition?: ConnectionPortDefinition;
+    readonly owner: Element;
+}
+/** Tools 唯一按 Root spatial phase 增量更新的 committed Port projection。 */
+export declare class PortIndex implements EditorSpatialClient {
+    private readonly root;
+    private readonly tree;
+    private readonly itemsByOwner;
+    private readonly dirtyOwners;
+    private readonly ownerObservationCleanups;
+    private readonly cleanups;
+    private readonly frameFlush;
+    private lastCandidateCount;
+    private projectionFlushCount;
+    constructor(root: Root);
+    private hasDeclaredPorts;
+    private refreshOwner;
+    private registerOwner;
+    private unregisterOwner;
+    private markOwnerDirty;
+    hasPendingSpatialWork(): boolean;
+    flushSpatialProjection(): void;
+    private replaceOwnerProjection;
+    query(point: PointView, radius: number): readonly IndexedConnectionPort[];
+    portsForOwners(owners: ReadonlySet<Element>): readonly IndexedConnectionPort[];
+    /** @internal 性能结构门禁。 */
+    get debugStats(): {
+        indexedPorts: number;
+        observedOwners: number;
+        pendingOwners: number;
+        lastQueryCandidates: number;
+        projectionFlushes: number;
+    };
+    dispose(): void;
+}

package/dist/select/projection.d.ts

@@ -0,0 +1,139 @@
+import { Element } from "@fulate/core";
+import { type PointEditTarget, type PointEditingScope, type SnapSourceCapability, type TransformInteractionCapability, type TransformInteractionPolicy } from "@fulate/ui";
+import { type PointView, type Rect } from "@fulate/share";
+export type ResizeHandle = "tl" | "tr" | "br" | "bl" | "mt" | "mr" | "mb" | "ml";
+export type SelectionRotationPivot = {
+    readonly kind: "selection-center";
+} | {
+    readonly kind: "custom-owner-local";
+    readonly ownerKey: string;
+    readonly local: PointView;
+};
+export type SelectionOverlayTarget = {
+    readonly kind: "resize";
+    readonly handle: ResizeHandle;
+} | {
+    readonly kind: "rotate";
+} | {
+    readonly kind: "pivot";
+} | {
+    readonly kind: "body";
+} | {
+    readonly kind: "point";
+    readonly ownerKey: string;
+    readonly target: PointEditTarget;
+    readonly move: "free" | "locked";
+    readonly deletable: boolean;
+    readonly role: "endpoint" | "vertex" | "segment" | "handle";
+    readonly insertT: number | undefined;
+};
+export interface SelectionOverlayControl {
+    readonly world: PointView;
+    readonly cursor: string;
+    readonly shape: "rect" | "circle" | "diamond" | "handle" | null;
+    readonly guideFrom?: PointView;
+    readonly active?: boolean;
+    readonly hit: {
+        readonly kind: "point";
+    } | {
+        readonly kind: "segment";
+        readonly from: PointView;
+        readonly to: PointView;
+    } | {
+        readonly kind: "rotation-ring";
+    };
+    readonly target: Exclude<SelectionOverlayTarget, {
+        readonly kind: "body";
+    }>;
+}
+export interface SelectionFrameProjection {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+    readonly angle: number;
+    readonly matrix: DOMMatrixReadOnly;
+    readonly inverseMatrix: DOMMatrixReadOnly;
+    readonly outline: readonly PointView[];
+    readonly worldCenter: PointView;
+}
+export type SelectionRotationPivotHorizontal = "left" | "center" | "right";
+export type SelectionRotationPivotVertical = "top" | "center" | "bottom";
+export interface SelectionRotationPivotSnapMarker extends PointView {
+    readonly horizontal: SelectionRotationPivotHorizontal;
+    readonly vertical: SelectionRotationPivotVertical;
+}
+export interface SelectionOverlayProjection {
+    readonly selectionKeys: readonly string[];
+    readonly frame: SelectionFrameProjection | null;
+    readonly controls: readonly SelectionOverlayControl[];
+    readonly selectedOutlineOwners: readonly ProjectionOwner[];
+    readonly pointScopeOutline: readonly PointView[] | null;
+    readonly bodyEnabled: boolean;
+    readonly frameVisible: boolean;
+    readonly rotationPivotWorld: PointView;
+    readonly rotationPivotSnapMarkers: readonly SelectionRotationPivotSnapMarker[];
+    readonly marquee: Readonly<Rect> | null;
+}
+export interface ProjectionOwner {
+    readonly element: Element;
+    readonly transform: TransformInteractionCapability | undefined;
+    readonly pointEnabled: boolean;
+    readonly pointScope: PointEditingScope | null;
+    readonly snap: SnapSourceCapability | undefined;
+    readonly frameVisible: boolean;
+}
+export interface ProjectionPolicy {
+    readonly move: boolean;
+    readonly resize: TransformInteractionPolicy["resize"];
+    readonly rotate: boolean;
+    readonly rotationPivot: TransformInteractionPolicy["rotationPivot"];
+}
+export interface SelectionProjectionMembership {
+    readonly selectionKeys: readonly string[];
+    readonly selectedOutlineOwners: readonly ProjectionOwner[];
+    readonly bodyEnabled: boolean;
+    readonly frameVisible: boolean;
+}
+interface PointControlTopology {
+    readonly local: PointView;
+    readonly guideLocal?: PointView;
+    readonly cursor: string;
+    readonly shape: "circle" | "diamond" | "handle";
+    readonly target: Extract<SelectionOverlayTarget, {
+        readonly kind: "point";
+    }>;
+}
+export interface SelectionProjectionTopology {
+    readonly pointControls: readonly PointControlTopology[];
+    readonly pointScopeOutline: readonly PointView[] | null;
+    readonly pointScopeValid: boolean;
+}
+export declare function samePointEditTarget(left: PointEditTarget, right: PointEditTarget): boolean;
+export declare function createSelectionFrameProjection({ left, top, width, height, angle }: Pick<SelectionFrameProjection, "left" | "top" | "width" | "height" | "angle">): SelectionFrameProjection;
+/** @internal Build a command frame from the current owner bounds. */
+export declare function createWorldVisualBoundsSelectionFrame(owners: readonly ProjectionOwner[], fallback?: SelectionFrameProjection | null): SelectionFrameProjection;
+export declare function createSelectionRotationPivotSnapMarkers(frame: SelectionFrameProjection): readonly SelectionRotationPivotSnapMarker[];
+export declare function createSelectionProjectionMembership(owners: readonly ProjectionOwner[], policy: ProjectionPolicy): SelectionProjectionMembership;
+export declare function createSelectionProjectionTopology(owners: readonly ProjectionOwner[], isCurrent?: (owner: ProjectionOwner) => boolean): SelectionProjectionTopology;
+export declare function createProjectionOwner(element: Element, frameVisible?: boolean, pointScope?: PointEditingScope | null, pointEnabled?: boolean): ProjectionOwner;
+export declare function buildSelectionOverlayProjection({ owners, membership, topology, frame: frameOverride, policy, pivot, showPivot, pivotSnapMarkers, activePointTarget, marquee }: {
+    readonly owners: readonly ProjectionOwner[];
+    readonly membership: SelectionProjectionMembership;
+    readonly topology: SelectionProjectionTopology;
+    readonly frame?: SelectionFrameProjection | null;
+    readonly policy: ProjectionPolicy;
+    readonly pivot: SelectionRotationPivot;
+    readonly showPivot: boolean;
+    readonly pivotSnapMarkers?: readonly SelectionRotationPivotSnapMarker[];
+    readonly activePointTarget?: Readonly<{
+        ownerKey: string;
+        target: PointEditTarget;
+    }> | null;
+    readonly marquee: Readonly<Rect> | null;
+}): SelectionOverlayProjection;
+export declare function hitSelectionOverlay(projection: SelectionOverlayProjection, point: PointView, controlRadius: number, edgePadding: number, rotatePadding: number): {
+    readonly target: SelectionOverlayTarget;
+    readonly cursor: string;
+} | null;
+export {};

package/dist/select/snap.d.ts

@@ -0,0 +1,97 @@
+import { type PointView } from "@fulate/share";
+import { Element, type BaseElementOption, type Layer, type Root } from "@fulate/core";
+import { type EndpointConnectionRole, type EndpointRef } from "@fulate/ui";
+interface SnapLine {
+    type: "vertical" | "horizontal";
+    value: number;
+    start: number;
+    end: number;
+    distanceText?: string;
+    points: PointView[];
+    textPos?: PointView;
+}
+interface SnapResult {
+    dx: number;
+    dy: number;
+}
+export interface PortSnapResult extends PointView {
+    elementKey: string;
+    /** target owner-local Port ID。 */
+    portId: string;
+}
+export interface PortSnapProbeResult {
+    readonly snap: PortSnapResult | null;
+    readonly state: PortInteractionState | null;
+}
+type PortInteractionState = "available" | "incompatible" | "forbidden";
+interface PortHighlight extends PointView {
+    readonly element: Element;
+    readonly portId: string;
+    state: PortInteractionState | null;
+}
+interface AxisRange {
+    min: number;
+    max: number;
+}
+interface AxisSegment extends AxisRange {
+    value: number;
+}
+interface SnapAxes {
+    vertical: AxisSegment[];
+    horizontal: AxisSegment[];
+}
+interface AxisLineMatch {
+    targetVal: number;
+    segments: AxisRange[];
+}
+export declare function isAxisAlignedRect(pts: readonly PointView[]): boolean;
+export declare function addEdgeMidpoints(pts: readonly PointView[]): PointView[];
+export declare function createSnapAxes(snapPoints: readonly PointView[]): SnapAxes;
+export declare function buildAxisSnapLines(best: AxisLineMatch, movingRange: {
+    min: number;
+    max: number;
+}, type: "vertical" | "horizontal", scale: number): SnapLine[];
+export declare class Snap extends Element {
+    readonly type = "snap";
+    threshold: number;
+    lineColor: string;
+    lineWidth: number;
+    dashPattern: number[];
+    isSnapping: boolean;
+    private snapLines;
+    private snapCandidates;
+    private axisElementExcludes;
+    private axisPointExcludes;
+    private axisTargets;
+    private portIndex;
+    private showViewportPorts;
+    private viewportPortTargets;
+    private activePortHighlight;
+    private portProbe;
+    private snapViewportState;
+    private sceneChangeCleanup?;
+    portHighlights: PortHighlight[];
+    constructor(options?: BaseElementOption);
+    protected onActivate(root: Root | null, layer: Layer | null): void;
+    protected onDeactivate(root: Root | null, layer: Layer | null): void;
+    private collectSnapCandidates;
+    private rebuildPortHighlights;
+    private refreshSnapCandidates;
+    private invalidateSnapshot;
+    private sceneChangeIsExcluded;
+    private handleSceneChange;
+    start(excludeEls: readonly Element[], excludePoints?: readonly {
+        element: Element;
+        indices: readonly number[];
+    }[], showViewportPorts?: boolean): void;
+    private getAxisTargets;
+    detect(originalPoints: readonly PointView[], rawDx: number, rawDy: number): SnapResult;
+    stop(): void;
+    private findClosestPortTarget;
+    private clearActivePortHighlight;
+    probeForbiddenPortMove(points: readonly PointView[], dx: number, dy: number, excludeEls?: readonly Element[]): boolean;
+    probePortSnap(worldX: number, worldY: number, role: EndpointConnectionRole, excludeEls?: readonly Element[], excludeSource?: EndpointRef): PortSnapProbeResult;
+    detectPortSnap(worldX: number, worldY: number, role: EndpointConnectionRole, excludeEls?: readonly Element[], excludeSource?: EndpointRef): PortSnapResult | null;
+    paint(): void;
+}
+export {};

package/dist/select/transform.d.ts

@@ -0,0 +1,40 @@
+import { type PointView } from "@fulate/share";
+import { type ResizeHandle, type SelectionFrameProjection } from "./projection";
+/** Selection frame 中保持不动的固定点。 */
+export type ResizeAnchor = "top-left" | "top" | "top-right" | "left" | "center" | "right" | "bottom-left" | "bottom" | "bottom-right";
+/** 按当前选择的 world visual/frame 尺寸调整选中元素。 */
+export interface ResizeOptions {
+    /** 目标 world visual frame 宽度；省略时保持当前宽度。 */
+    readonly width?: number;
+    /** 目标 world visual frame 高度；省略时保持当前高度。 */
+    readonly height?: number;
+    /** 保持不动的 frame 固定点，默认 `top-left`。 */
+    readonly anchor?: ResizeAnchor;
+}
+/** Selection frame 内执行镜像的方向。 */
+export type FlipDirection = "horizontal" | "vertical";
+export declare function resolveSelectionFrameTransform(frame: SelectionFrameProjection, worldDelta: DOMMatrixReadOnly, kind: "move" | "resize" | "rotate"): SelectionFrameProjection;
+export declare function resolveResizeWorldDelta(frame: SelectionFrameProjection, handle: ResizeHandle, worldPoint: PointView, proportional: boolean): DOMMatrix;
+/** @internal 把 target frame 尺寸转为一个固定锚点的 world 线性变换。 */
+export declare function resolveResizeWorldDeltaForSize(frame: SelectionFrameProjection, width: number, height: number, anchor?: ResizeAnchor): DOMMatrix;
+/** @internal 围绕 selection frame 中心沿 frame 自身坐标轴镜像。 */
+export declare function resolveFlipWorldDelta(frame: SelectionFrameProjection, direction: FlipDirection): DOMMatrix;
+export declare function resolveRotationTransform({ frameAngle, pivot, unwrappedDelta, snapAngle, snapThreshold }: {
+    readonly frameAngle: number;
+    readonly pivot: PointView;
+    readonly unwrappedDelta: number;
+    readonly snapAngle: number;
+    readonly snapThreshold: number;
+}): {
+    worldDelta: DOMMatrix;
+    unwrappedDelta: number;
+};
+/** 根据两个 pointer 位置解析单步旋转；连续手势由 controller 累积 unwrappedDelta。 */
+export declare function resolveRotationWorldDelta({ frameAngle, pivot, start, current, snapAngle, snapThreshold }: {
+    readonly frameAngle: number;
+    readonly pivot: PointView;
+    readonly start: PointView;
+    readonly current: PointView;
+    readonly snapAngle: number;
+    readonly snapThreshold: number;
+}): DOMMatrix;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@fulate/tools",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --config vitest.config.ts"
+  },
+  "dependencies": {
+    "@fulate/share": "*",
+    "@fulate/core": "*",
+    "@fulate/ui": "*",
+    "@fulate/import": "*",
+    "lodash-es": "^4.17.22",
+    "rbush": "^4.0.1"
+  },
+  "devDependencies": {
+    "@types/rbush": "^4.0.0"
+  }
+}