@fulate/tools 1.0.0

package/dist/editor/interaction-controller.d.ts

@@ -0,0 +1,339 @@
+import { Element, Node, type ConnectionPortRef, type OwnerPropertyChange, type Root, type StructureChange } from "@fulate/core";
+import { LineTree, type EndpointConnectionRole, type EndpointRef, type ContentEditingSession, type EditorAuthoredGesture, type PointEditTarget, type PointEditingScope, type LineTreeBranchTailSource, type LineDecoration, type SelectionBehavior, type TransformInteractionCapability } from "@fulate/ui";
+import { type PointView, type Rect } from "@fulate/share";
+import type { HistoryManager, HistoryScope } from "../history";
+import type { LineTool } from "../line";
+import type { Select, SelectedPropertyPatch } from "../select";
+import { type ProjectionOwner, type ResizeHandle, type SelectionOverlayProjection, type SelectionOverlayTarget, type SelectionRotationPivot } from "../select/projection";
+import { type FlipDirection, type ResizeOptions } from "../select/transform";
+import type { PortSnapResult, Snap } from "../select/snap";
+interface SelectedOwner extends ProjectionOwner {
+    readonly behavior: SelectionBehavior;
+}
+export interface SelectionIdentity {
+    readonly owners: readonly SelectedOwner[];
+    readonly interaction: EditorInteractionState;
+}
+interface TransformOwnerRecord {
+    readonly owner: Element;
+    readonly parent: Node | undefined;
+    readonly capability: TransformInteractionCapability;
+    readonly baseline: ReturnType<TransformInteractionCapability["captureTransformBaseline"]>;
+}
+interface PointerIntent {
+    readonly point: PointView;
+    readonly shiftKey: boolean;
+}
+interface PointerGesture {
+    update(intent: PointerIntent): void;
+    finish(intent?: PointerIntent, cancelled?: boolean): void;
+}
+interface ApplyCommandOptions {
+    readonly beforeDrain?: () => void;
+    readonly afterHistory?: () => void;
+    readonly installSelection?: () => boolean;
+}
+interface LineDrawingSession {
+    readonly tool: LineTool;
+    readonly resultType: "line" | "lineTree";
+    readonly tailDecoration: LineDecoration;
+    readonly history: HistoryScope | undefined;
+    readonly confirmed: PointView[];
+    headTarget: ConnectionPortRef | undefined;
+    tailTarget: ConnectionPortRef | undefined;
+    preview: PointView | null;
+    snap: PortSnapResult | null;
+}
+interface ActivePointTarget {
+    readonly ownerKey: string;
+    readonly target: PointEditTarget;
+}
+export type SelectControllerState = {
+    readonly kind: "idle";
+    readonly gesture: MarqueeGesture | null;
+} | {
+    readonly kind: "transform";
+    readonly gesture: TransformGesture | PivotGesture | SelectionPressGesture | null;
+} | {
+    readonly kind: "point";
+    readonly ownerKey: string;
+    readonly scope: PointEditingScope;
+    readonly gesture: PointGesture | SelectionPressGesture | TransformGesture | null;
+    readonly activeTarget: ActivePointTarget | null;
+} | {
+    readonly kind: "port";
+    readonly ownerKey: string;
+    readonly scope: PointEditingScope;
+    readonly gesture: PointGesture;
+    readonly source: EndpointRef;
+    readonly activeTarget: ActivePointTarget | null;
+} | {
+    readonly kind: "content";
+    readonly session: ContentEditingSession;
+    readonly history: HistoryScope | undefined;
+};
+type LineTreeDrawingSession = {
+    readonly kind: "source-pick";
+    readonly tool: LineTool;
+    readonly owner: LineTree;
+    readonly tailDecoration: LineDecoration;
+    hover: LineTreeBranchTailSource | null;
+} | {
+    readonly kind: "branch-draw";
+    readonly tool: LineTool;
+    readonly owner: LineTree;
+    readonly source: LineTreeBranchTailSource;
+    readonly tailDecoration: LineDecoration;
+    readonly confirmed: PointView[];
+    tailTarget: ConnectionPortRef | undefined;
+    preview: PointView | null;
+    snap: PortSnapResult | null;
+};
+export type EditorInteractionState = {
+    readonly kind: "select";
+    readonly interaction: SelectControllerState;
+    readonly selection: readonly Element[];
+    readonly pivot: SelectionRotationPivot;
+} | {
+    readonly kind: "line-draw";
+    readonly session: LineDrawingSession | LineTreeDrawingSession;
+};
+declare class TransformGesture implements PointerGesture {
+    readonly controller: EditorInteractionController;
+    readonly kind: "move" | "resize" | "rotate";
+    readonly start: PointView;
+    readonly frame: NonNullable<SelectionOverlayProjection["frame"]>;
+    readonly records: readonly TransformOwnerRecord[];
+    readonly snapPoints: readonly PointView[];
+    readonly movableLineEndpoints: readonly PointView[];
+    readonly snapExcludes: readonly Element[];
+    readonly rotationPivotWorld: PointView;
+    readonly history: HistoryScope | undefined;
+    readonly resizeHandle?: ResizeHandle;
+    private lastIntent;
+    private previousRotationAngle;
+    private unwrappedRotationDelta;
+    constructor(controller: EditorInteractionController, kind: "move" | "resize" | "rotate", start: PointView, initialIntent: PointerIntent, frame: NonNullable<SelectionOverlayProjection["frame"]>, records: readonly TransformOwnerRecord[], snapPoints: readonly PointView[], movableLineEndpoints: readonly PointView[], snapExcludes: readonly Element[], rotationPivotWorld: PointView, history: HistoryScope | undefined, resizeHandle?: ResizeHandle);
+    consumeRotationDelta(point: PointView): number;
+    probeForbiddenPort(point: PointView): boolean;
+    update(intent: PointerIntent): void;
+    ownsCurrentContext(): boolean;
+    finishInvalidated(): void;
+    finish(intent?: PointerIntent): void;
+}
+declare class PointGesture implements PointerGesture, EditorAuthoredGesture {
+    readonly controller: EditorInteractionController;
+    readonly ownerKey: string;
+    readonly startParent: Node | undefined;
+    readonly startTarget: PointEditTarget;
+    readonly insertT: number | undefined;
+    readonly role: "endpoint" | "vertex" | "segment" | "handle";
+    readonly connectionRole: EndpointConnectionRole | null;
+    readonly snapExcludes: readonly Element[];
+    readonly history: HistoryScope | undefined;
+    readonly startPointerWorld: PointView;
+    readonly startTargetWorld: PointView;
+    private latestIntent;
+    private consumedIntent;
+    connectionTarget: ConnectionPortRef | undefined;
+    connectionTargetOwner: Element | undefined;
+    connectionTargetParent: Node | undefined;
+    constructor(controller: EditorInteractionController, ownerKey: string, startParent: Node | undefined, startTarget: PointEditTarget, insertT: number | undefined, role: "endpoint" | "vertex" | "segment" | "handle", connectionRole: EndpointConnectionRole | null, snapExcludes: readonly Element[], history: HistoryScope | undefined, startPointerWorld: PointView, startTargetWorld: PointView);
+    currentTarget: PointEditTarget;
+    ownsCurrentContext(): boolean;
+    get connectionSource(): EndpointRef | undefined;
+    resolveWorldPoint(pointer: PointView): {
+        x: number;
+        y: number;
+    };
+    update(intent: PointerIntent): void;
+    consumeLatestIntent(): void;
+    finish(intent?: PointerIntent, cancelled?: boolean): void;
+    finishInvalidated(): void;
+}
+declare class PivotGesture implements PointerGesture {
+    readonly controller: EditorInteractionController;
+    readonly owner: Element;
+    readonly startPointer: PointView;
+    readonly startPivot: PointView;
+    private finalPoint;
+    constructor(controller: EditorInteractionController, owner: Element, startPointer: PointView, startPivot: PointView);
+    update(intent: PointerIntent): void;
+    finish(intent?: PointerIntent): void;
+}
+declare class SelectionPressGesture implements PointerGesture {
+    readonly controller: EditorInteractionController;
+    readonly start: PointerIntent;
+    readonly candidate: Element | undefined;
+    readonly contentTarget: Element | null;
+    readonly directDragOwner?: Element;
+    constructor(controller: EditorInteractionController, start: PointerIntent, candidate: Element | undefined, contentTarget: Element | null, directDragOwner?: Element);
+    update(intent: PointerIntent): void;
+    finish(intent?: PointerIntent, cancelled?: boolean): void;
+}
+declare class MarqueeGesture implements PointerGesture {
+    readonly controller: EditorInteractionController;
+    readonly start: PointView;
+    readonly candidate: Element | undefined;
+    readonly additive: boolean;
+    readonly initialSelection: readonly Element[];
+    private current;
+    private moved;
+    constructor(controller: EditorInteractionController, start: PointView, candidate: Element | undefined, additive: boolean, initialSelection: readonly Element[]);
+    update(intent: PointerIntent): void;
+    finish(intent?: PointerIntent, cancelled?: boolean): void;
+}
+export declare class EditorInteractionController {
+    readonly select: Select;
+    readonly root: Root;
+    readonly history: HistoryManager;
+    readonly frameFlush: any;
+    private readonly cleanups;
+    private selectionValue;
+    private owners;
+    private policy;
+    private rotationPivotPreview;
+    private selectionFrame;
+    private preserveSelectionFrame;
+    private projectionState;
+    private projectionOwners;
+    private projectionMembership;
+    private projectionTopology;
+    private overlayDirty;
+    private pendingSelectionUpdate;
+    private pendingSelectionRepair;
+    private rotationPivotDisplayOwner;
+    private hoveredTarget;
+    private hoveredContent;
+    private controllerState;
+    private pasteTask;
+    private pointerWorld;
+    marquee: Readonly<Rect> | null;
+    constructor(select: Select, root: Root, history: HistoryManager);
+    get selection(): readonly Element[];
+    get projection(): SelectionOverlayProjection;
+    publishConfiguredChange(changed: boolean | undefined): void;
+    /** 把纯外部通知排到当前同步命令、回放或 frame completion 返回之后。 */
+    private notifySelect;
+    get contentHover(): Element<import("@fulate/core").ElementProperties, import("@fulate/core").BaseElementOption<any>, Partial<Omit<import("@fulate/core").BaseElementOption<any>, "key" | "children">>>;
+    get overlayTarget(): SelectionOverlayTarget;
+    get editorElements(): readonly Element[];
+    get snapTool(): Snap | undefined;
+    get state(): EditorInteractionState;
+    /** @internal Captures the canonical selection and interaction identities. */
+    captureSelectionIdentity(): SelectionIdentity;
+    /** @internal Makes one concrete clipboard Promise the latest paste intent. */
+    beginPaste(task: Promise<void>): void;
+    /** @internal Tests whether one paste still owns the captured selection intent. */
+    ownsPasteSelection(identity: SelectionIdentity, task: Promise<void>): boolean;
+    /** @internal Releases the latest paste intent after its Promise settles. */
+    finishPaste(task: Promise<void>): void;
+    private get selectState();
+    private installSelectState;
+    private get activeGesture();
+    private set activeGesture(value);
+    private get activePointGesture();
+    private get pointState();
+    private set pointState(value);
+    private get activePointTarget();
+    private set activePointTarget(value);
+    private get contentSession();
+    private set contentSession(value);
+    private get contentHistory();
+    private set contentHistory(value);
+    private get lineSession();
+    private set lineSession(value);
+    private get lineTreeSession();
+    private set lineTreeSession(value);
+    private get rotationPivotState();
+    private installInput;
+    private readonly handleSceneChange;
+    private sceneChangeAffectsSelection;
+    private selectionGeometryIsDirty;
+    private invalidatePointTopology;
+    private resolvePolicy;
+    setSelection(elements: readonly Element[]): void;
+    private readonly pointProjectionOwnerIsCurrent;
+    private restoreSelectionForHistory;
+    private replaceSelection;
+    private requestSelectionEnd;
+    private pointContextIsCurrent;
+    private resolveCurrentPointContext;
+    private resolvePointGestureContext;
+    pointGestureOwnsCurrentContext(gesture: PointGesture): boolean;
+    private setPointState;
+    private exitPointState;
+    private setActivePointTarget;
+    private invalidateOverlay;
+    private shouldShowRotationPivot;
+    private showRotationPivotForCurrentOwner;
+    hasPendingOverlayWork(): boolean;
+    flushOverlayProjection(): void;
+    hasPendingCompletionWork(): boolean;
+    flushCompletionWork(): void;
+    resolveCursor(point: PointView | undefined, contentCursor: string): string;
+    private updateHover;
+    private applyAuthoredBatch;
+    private onPointerDown;
+    private onPointerMove;
+    private onPointerFinish;
+    private onDoubleClick;
+    private onKeyDown;
+    private captureTransformRecords;
+    private startTransform;
+    promoteSelectionPress(gesture: SelectionPressGesture): TransformGesture | null;
+    finishSelectionPress(gesture: SelectionPressGesture): void;
+    finishSelectionGesture(gesture: PointerGesture, selection?: readonly Element[]): void;
+    consumeTransform(gesture: TransformGesture, intent: PointerIntent): void;
+    private startPointGesture;
+    consumePoint(gesture: PointGesture, intent: PointerIntent, first: boolean): void;
+    deletePointTarget(): boolean;
+    nudge(dx: number, dy: number): void;
+    setProperties(patch: SelectedPropertyPatch): void;
+    private prepareTransformCommandFrame;
+    private applyTransformCommand;
+    resize(options?: Readonly<ResizeOptions>): void;
+    flip(direction: FlipDirection): void;
+    previewRotationPivot(owner: Element, point: PointView): void;
+    clearRotationPivotPreview(owner: Element): void;
+    commitRotationPivot(owner: Element, point: PointView): boolean;
+    private resolveRotationPivot;
+    setMarquee(rect: Readonly<Rect> | null): void;
+    finishPointerGesture(gesture: PointerGesture): void;
+    private pointConnectionCandidateIsCurrent;
+    finishPointConnectionGesture(gesture: PointGesture): void;
+    private beginContentEditing;
+    finishContentEditing(discard: boolean): void;
+    startLineDrawing(tool: LineTool): void;
+    private startLineTreeBranchDrawing;
+    private updateLineTreeSourceHover;
+    private confirmLineTreeSource;
+    private beginLineTreeBranchDraft;
+    private updateLineTreePreview;
+    private probeLineTreeTail;
+    private confirmLineTreePoint;
+    private confirmLineTreeBranchDrawing;
+    private updateLinePreview;
+    private probeLineAnchor;
+    private confirmLinePoint;
+    stopLineDrawing(): void;
+    cancelLineDrawing(): void;
+    private confirmLineDrawing;
+    getLineDrawingView(tool: LineTool): LineDrawingSession | {
+        readonly kind: "branch-draw";
+        readonly tool: LineTool;
+        readonly owner: LineTree;
+        readonly source: LineTreeBranchTailSource;
+        readonly tailDecoration: LineDecoration;
+        readonly confirmed: PointView[];
+        tailTarget: ConnectionPortRef | undefined;
+        preview: PointView | null;
+        snap: PortSnapResult | null;
+    };
+    hasLineToolSession(tool: LineTool): boolean;
+    applyCommand(ownerEffects: readonly OwnerPropertyChange[], structureEffects: readonly StructureChange[], scope: HistoryScope | undefined, selectionAfter: readonly Element[], options?: ApplyCommandOptions): void;
+    finishCurrentInteraction(): void;
+    destroy(): void;
+}
+export declare function getEditorInteractionController(root: Root): EditorInteractionController;
+export {};

package/dist/editor/overlay-transform.d.ts

@@ -0,0 +1,6 @@
+import { Element, ElementTransform } from "@fulate/core";
+/** Tools 画布 overlay surface 始终参与 Layer paint，但从不成为内容命中目标。 */
+export declare class ToolOverlayTransform<E extends Element = Element> extends ElementTransform<E> {
+    hasPointHint(): boolean;
+    hasInView(): boolean;
+}

package/dist/editor-layer.d.ts

@@ -0,0 +1,18 @@
+import { Layer, type LayerOption, type Root } from "@fulate/core";
+/**
+ * Rendering and input boundary for editor tools.
+ *
+ * Tool painters draw outside their node geometry (selection handles,
+ * guides, rulers and previews), so dirty-rectangle repainting cannot
+ * describe their damage. Keep this layer on the full-frame path and avoid
+ * CSS viewport previews that would scale screen-space affordances. While the
+ * layer is active, its subtree becomes an interaction scope: content hits
+ * remain visible to Root observers without reaching content handlers.
+ */
+export declare class EditorLayer extends Layer {
+    readonly type = "editor-layer";
+    private releaseInteractionScope?;
+    constructor(options?: LayerOption);
+    protected onActivate(root: Root | null): void;
+    protected onDeactivate(root: Root | null): void;
+}

package/dist/history/index.d.ts

@@ -0,0 +1,88 @@
+import { Element, Node, type ChangeHistorySink, type Root } from "@fulate/core";
+import { LineTree, type LineTreeTopologyDelta } from "@fulate/ui";
+export interface HistoryPropertyChange {
+    readonly owner: Element;
+    readonly key: string;
+    readonly before: unknown;
+    readonly after: unknown;
+}
+export interface HistoryPlacement {
+    readonly owner: Node | null;
+    readonly index: number;
+}
+export interface HistoryPlacementChange {
+    readonly node: Node;
+    readonly before: HistoryPlacement;
+    readonly after: HistoryPlacement;
+}
+/**
+ * 已由其 owner 正常提交的外部 authored change。
+ * History 只在线性、非重入的 undo/redo 回放中调用这些方法，不负责首次执行。
+ * 每个方法只恢复该 change 自己拥有的数据，不得操纵当前 HistoryManager 的栈。
+ */
+export interface HistoryChange {
+    undo(): void;
+    redo(): void;
+}
+export interface EditorHistoryEntry {
+    readonly properties: readonly HistoryPropertyChange[];
+    readonly lineTrees: readonly HistoryLineTreeChange[];
+    readonly placements: readonly HistoryPlacementChange[];
+    readonly changes: readonly HistoryChange[];
+    readonly selectionBefore: readonly string[];
+    readonly selectionAfter: readonly string[];
+}
+export interface HistoryScope extends ChangeHistorySink {
+    /** 把已完成的外部 change 加入本 scope；不会立即调用 undo/redo。 */
+    record(change: HistoryChange): void;
+    /**
+     * 完成 semantic scope；返回值只表示 Canvas configured 是否有净变化。
+     * 仅有 HistoryChange 时仍形成 entry，但返回 false。
+     */
+    finish(selectionAfter: readonly Element[]): boolean;
+    discard(): void;
+}
+export interface HistorySelectionAdapter {
+    finishInteraction(): void;
+    getSelection(): readonly Element[];
+    hasConfiguredChangeListener(): boolean;
+    publishConfiguredChange(): void;
+    restoreSelection(elements: readonly Element[]): void;
+    completeReplay(type: "select:undo" | "select:redo", elements: readonly Element[], configuredChanged: boolean): void;
+}
+export interface HistoryLineTreeChange {
+    readonly owner: LineTree;
+    readonly delta: LineTreeTopologyDelta;
+}
+export declare class HistoryManager {
+    private readonly root;
+    private readonly limit;
+    enabled: boolean;
+    private undoStack;
+    private redoStack;
+    private selectionAdapter;
+    constructor(root: Root, limit?: number);
+    get undoCount(): number;
+    get redoCount(): number;
+    bindSelection(adapter: HistorySelectionAdapter | null): void;
+    openScope(selectionBefore?: readonly Element<import("@fulate/core").ElementProperties, import("@fulate/core").BaseElementOption<any>, Partial<Omit<import("@fulate/core").BaseElementOption<any>, "key" | "children">>>[]): HistoryScope | undefined;
+    /** @internal Publishes one completed actual configured semantic change. */
+    publishConfiguredChange(changed: boolean | undefined): void;
+    /** @internal 只由存在Canvas净变化或外部change的scope完成时写入。 */
+    push(entry: EditorHistoryEntry): void;
+    clear(): void;
+    private buildPropertyChanges;
+    private buildStructureChanges;
+    private buildLineTreeChanges;
+    private replay;
+    /**
+     * 线性撤销栈顶 entry。当前调用返回前，不得同步重入本 manager 的
+     * undo、redo、clear 或 push；HistoryChange 只恢复自己拥有的数据。
+     */
+    undo(): void;
+    /**
+     * 线性重做栈顶 entry。当前调用返回前，不得同步重入本 manager 的
+     * undo、redo、clear 或 push；HistoryChange 只恢复自己拥有的数据。
+     */
+    redo(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { checkElement } from "./select/checkElement";
+export { Select } from "./select/index";
+export type { ConnectionGesture, CopyContext, ClipboardDataProducer, DeleteContext, FlipDirection, PasteContext, PasteOptions, PasteParentResolver, ResizeAnchor, ResizeOptions, SelectedPropertyPatch, SelectKeyboardCommands, SelectOption, ToolsConnectionIntent } from "./select/index";
+export { Snap } from "./select/snap";
+export { HistoryManager } from "./history/index";
+export type { EditorHistoryEntry, HistoryChange, HistoryPlacementChange, HistoryPropertyChange, HistoryScope } from "./history/index";
+export { LineTool } from "./line/index";
+export type { LineToolOption } from "./line/index";
+export { Rule } from "./rule/index";
+export type { RuleOption } from "./rule/index";
+export { EditorLayer } from "./editor-layer";
+export { alignElements } from "./select/align";
+export type { AlignType } from "./select/align";
+export { ArrangeType } from "./select/arrange";
+export type { ClipboardPlugin } from "./select/clipboard";
+export { serializeScene, serializeSceneToJSON, deserializeElement, restoreScene, parseFileData, exportToFile, importFromFile } from "@fulate/import";
+export type { ElementFilter, FileData, DeserializeFactories, DeserializeFactory } from "@fulate/import";