@galacean/effects-plugin-editor-gizmo 2.10.3 → 2.11.0-alpha.0

package/README.md

@@ -1,13 +1,45 @@
 # Galacean Effects Editor Gizmo Plugin
 
-## Development
+Editor interaction and scene gizmos for Galacean Effects.
+
+- **2D**: selection, translation, resizing, rotation, text editing, image cropping,
+  viewport navigation and frame layout.
+- **3D**: transform handles, camera and light gizmos, geometry and wireframes.
+
+## Usage
+
+```ts
+import { GestureHandler, GizmoComponent } from '@galacean/effects-plugin-editor-gizmo';
+```
+
+Use `GestureHandler` for 2D editor interaction and `GizmoComponent` for 3D scene
+gizmos. Importing the package registers the `editor-gizmo` plugin. Keep its version
+aligned with `@galacean/effects`.
 
-### Getting Started
+## Source layout
 
-``` bash
-# demo
+- `src/2d/`: 2D interaction, selection, viewport and layout helpers.
+- `src/3d/`: 3D gizmos, geometry, wireframes and plugin loader.
+- `../../web-packages/test/unit/src/plugin-editor-gizmo/`: unit tests.
+
+## Development
+
+```bash
 pnpm --filter @galacean/effects-plugin-editor-gizmo dev
 ```
 
-> Open in browser: http://localhost:8081/demo/index.html
+Open [the demo](http://localhost:8081/demo/index.html).
+
+Build the plugin:
+
+```bash
+pnpm --filter @galacean/effects-plugin-editor-gizmo build
+```
+
+Run the shared unit tests:
+
+```bash
+pnpm test
+```
 
+Open [the unit tests](http://localhost:9090/unit/index.html).

package/dist/2d/configs/builtin-configs.d.ts

@@ -0,0 +1,14 @@
+import type { EffectsEditModeConfig, IconConfig, ItemCreateConfig, MaskConfig, ImageCutConfig, ImageExpandConfig, SelectionPreviewConfig, SnapConfig, SpriteTextEditConfig, ResizeSelectionConfig, ViewportNavigationConfig, ViewportOverlayConfig } from './types';
+export { DEFAULT_LOADING_FRAGMENT, loadingConfig } from './loading-config';
+export declare const effectsEditModeConfig: import("./config-definition").ConfigDefinition<"mode.effects-edit", EffectsEditModeConfig>;
+export declare const viewportNavigationConfig: import("./config-definition").ConfigDefinition<"viewport.navigation", ViewportNavigationConfig>;
+export declare const viewportOverlayConfig: import("./config-definition").ConfigDefinition<"viewport.overlay", ViewportOverlayConfig>;
+export declare const selectionPreviewConfig: import("./config-definition").ConfigDefinition<"selection.preview", SelectionPreviewConfig>;
+export declare const selectionSnapConfig: import("./config-definition").ConfigDefinition<"selection.snap", SnapConfig>;
+export declare const resizeSelectionConfig: import("./config-definition").ConfigDefinition<"resize-selection", ResizeSelectionConfig>;
+export declare const imageCutConfig: import("./config-definition").ConfigDefinition<"tool.image-cut", ImageCutConfig>;
+export declare const imageExpandConfig: import("./config-definition").ConfigDefinition<"tool.image-expand", ImageExpandConfig>;
+export declare const maskConfig: import("./config-definition").ConfigDefinition<"tool.mask", MaskConfig>;
+export declare const spriteTextEditConfig: import("./config-definition").ConfigDefinition<"tool.sprite-text-edit", SpriteTextEditConfig>;
+export declare const iconConfig: import("./config-definition").ConfigDefinition<"feedback.icon", IconConfig>;
+export declare const itemCreateConfig: import("./config-definition").ConfigDefinition<"tool.item-create", ItemCreateConfig>;

package/dist/2d/configs/config-definition.d.ts

@@ -0,0 +1,40 @@
+/** 带稳定标识、默认值和校验器的配置定义。 */
+export type ConfigDefinition<Id extends string, T extends object> = {
+    /** 配置唯一标识。 */
+    readonly id: Id;
+    /** 配置默认值。 */
+    readonly defaults: Readonly<T>;
+    /** 校验并归一化外部配置。 */
+    readonly validate?: (input: unknown) => Partial<T> | undefined;
+};
+/** 任意配置定义的通用类型。 */
+export type AnyConfigDefinition = ConfigDefinition<string, Record<string, unknown>>;
+/** 提取配置定义对应的值类型。 */
+export type ConfigValue<D> = D extends ConfigDefinition<string, infer T> ? T : never;
+/** 一次配置变更的前后值。 */
+export type ConfigChange<T extends object> = {
+    /** 本次接受的增量配置。 */
+    partial: Readonly<Partial<T>>;
+    /** 变更前的完整配置。 */
+    previous: Readonly<T>;
+    /** 变更后的完整配置。 */
+    current: Readonly<T>;
+};
+/**
+ * 深拷贝由数组和普通对象组成的配置值。
+ * @param value 待拷贝的配置值
+ * @returns 配置值副本
+ */
+export declare function cloneConfigValue<T>(value: T): T;
+/**
+ * 递归冻结配置值。
+ * @param value 待冻结的配置值
+ * @returns 已冻结的原值
+ */
+export declare function freezeConfigValue<T>(value: T): T;
+/**
+ * 创建不可变的配置定义。
+ * @param definition 配置标识、默认值和可选校验器
+ * @returns 默认值已复制并冻结的配置定义
+ */
+export declare function defineConfig<const Id extends string, T extends object>(definition: ConfigDefinition<Id, T>): ConfigDefinition<Id, T>;

package/dist/2d/configs/config-manager.d.ts

@@ -0,0 +1,52 @@
+import { EventEmitter } from '@galacean/effects';
+import { type AnyConfigDefinition, type ConfigChange, type ConfigValue } from './config-definition';
+/** 任意配置项的一次变更。 */
+export type AnyConfigChange = {
+    /** 配置唯一标识。 */
+    id: string;
+    /** 本次接受的增量配置。 */
+    partial: Readonly<Record<string, unknown>>;
+    /** 变更前的完整配置。 */
+    previous: Readonly<Record<string, unknown>>;
+    /** 变更后的完整配置。 */
+    current: Readonly<Record<string, unknown>>;
+};
+/** 配置管理器事件参数。 */
+export type ConfigManagerEvents = {
+    /** 任意配置变更事件。 */
+    configChange: [AnyConfigChange];
+};
+/** 管理配置定义、当前值和变更订阅。 */
+export declare class ConfigManager extends EventEmitter<ConfigManagerEvents> {
+    private readonly values;
+    private readonly definitions;
+    /**
+     * 获取配置当前值，首次读取时使用默认值初始化。
+     * @param definition 配置定义
+     * @returns 当前不可变配置
+     */
+    get<D extends AnyConfigDefinition>(definition: D): Readonly<ConfigValue<D>>;
+    /**
+     * 合并并保存增量配置。
+     * @param definition 配置定义
+     * @param partial 待合并的增量配置
+     */
+    set<D extends AnyConfigDefinition>(definition: D, partial: Partial<ConfigValue<D>>): void;
+    /**
+     * 将配置恢复为默认值。
+     * @param definition 配置定义
+     */
+    reset(definition: AnyConfigDefinition): void;
+    /**
+     * 订阅指定配置的变更。
+     * @param definition 配置定义
+     * @param listener 配置变更回调
+     * @returns 取消订阅函数
+     */
+    onChange<D extends AnyConfigDefinition>(definition: D, listener: (change: ConfigChange<ConfigValue<D>>) => void): () => void;
+    /**
+     * 注册配置定义并校验标识冲突。
+     * @param definition 配置定义
+     */
+    private assertDefinition;
+}

package/dist/2d/configs/index.d.ts

@@ -0,0 +1,6 @@
+export { cloneConfigValue, defineConfig, freezeConfigValue, } from './config-definition';
+export type { AnyConfigDefinition, ConfigChange, ConfigDefinition, ConfigValue, } from './config-definition';
+export { ConfigManager } from './config-manager';
+export type { AnyConfigChange, ConfigManagerEvents, } from './config-manager';
+export { effectsEditModeConfig, iconConfig, itemCreateConfig, DEFAULT_LOADING_FRAGMENT, loadingConfig, maskConfig, imageCutConfig, imageExpandConfig, resizeSelectionConfig, selectionPreviewConfig, selectionSnapConfig, spriteTextEditConfig, viewportNavigationConfig, viewportOverlayConfig, } from './builtin-configs';
+export type { EffectsEditModeConfig, IconConfig, ItemCreateConfig, LoadingConfig, MaskConfig, ImageCutConfig, ImageExpandConfig, ResizeSelectionBehavior, ResizeSelectionConfig, SelectionPreviewConfig, SnapConfig, SpriteTextEditConfig, ViewportNavigationConfig, ViewportOverlayConfig, } from './types';

package/dist/2d/configs/loading-config.d.ts

@@ -0,0 +1,3 @@
+import type { LoadingConfig } from './types';
+export declare const DEFAULT_LOADING_FRAGMENT = "\n// Shadertoy Fragment Shader\n// Diagonal background gradient + wider colorful transparent shimmer\n\nprecision highp float;\n\nvarying vec2 vUV;\n\nuniform vec4 _Time;\n\n// ------------------------------------------------------------\n// Background\n// ------------------------------------------------------------\nvec3 background(vec2 uv) {\n    vec3 topLeft     = vec3(0.88, 0.85, 1.00);\n    vec3 bottomRight = vec3(0.98, 0.98, 0.98);\n\n    float d = (uv.x + (1.0 - uv.y)) * 0.5;\n    d = smoothstep(0.0, 1.0, d);\n\n    vec3 col = mix(topLeft, bottomRight, d);\n\n    vec2 p1 = uv - vec2(1.13, 1.40);\n    float r1 = length(p1 / vec2(0.85, 0.85));\n    float g1 = 1.0 - smoothstep(0.0, 0.96, r1);\n    col += vec3(172.0/255.0, 183.0/255.0, 1.0) * g1 * 0.28;\n\n    vec2 p2 = uv - vec2(0.25, 0.23);\n    float r2 = length(p2 / vec2(0.74, 0.64));\n    float g2 = 1.0 - smoothstep(0.0, 1.0, r2);\n    col += vec3(147.0/255.0, 108.0/255.0, 1.0) * g2 * 0.10;\n\n    return col;\n}\n\n// ------------------------------------------------------------\n// Easing: slow at start, fast at end\n// ------------------------------------------------------------\nfloat easeInQuad(float x) {\n    return x * x;\n}\n\n// ------------------------------------------------------------\n// Color palette helper\n// ------------------------------------------------------------\nvec3 palette(float t) {\n    // \u67D4\u548C\u7684\u5F69\u8272\u6761\uFF1A\u84DD -> \u9752 -> \u7D2B -> \u7C89 -> \u84DD\n    vec3 a = vec3(0.62, 0.82, 1.00);\n    vec3 b = vec3(0.72, 0.95, 1.00);\n    vec3 c = vec3(0.83, 0.76, 1.00);\n    vec3 d = vec3(1.00, 0.82, 0.95);\n\n    t = fract(t);\n\n    if (t < 0.33) {\n        float k = smoothstep(0.0, 0.33, t);\n        return mix(a, b, k);\n    } else if (t < 0.66) {\n        float k = smoothstep(0.33, 0.66, t);\n        return mix(b, c, k);\n    } else {\n        float k = smoothstep(0.66, 1.0, t);\n        return mix(c, d, k);\n    }\n}\n\n// ------------------------------------------------------------\n// Wider colorful transparent left-to-right shimmer\n// ------------------------------------------------------------\nvec4 shimmerBand(vec2 uv, float t) {\n    float cycle = fract(t * 0.70);\n    cycle = easeInQuad(cycle);\n\n    float x = cycle * 1.55 - 0.25;   // sweep from left to right\n\n    float d = abs(uv.x - x);\n    float band = 1.0 - smoothstep(0.0, 0.30, d);\n    float core = 1.0 - smoothstep(0.0, 0.10, d);\n\n    float x2 = x + (uv.y - 0.5) * 0.18;\n    float d2 = abs(uv.x - x2);\n    float band2 = 1.0 - smoothstep(0.0, 0.20, d2);\n\n    float s = max(band * 0.85, band2 * 0.60);\n    s = max(s, core * 0.95);\n    s = clamp(s, 0.0, 1.0);\n\n    // \u989C\u8272\u6CBF\u6761\u5E26\u53D8\u5316\uFF0C\u6A21\u62DF\u5F69\u8272\u6E10\u53D8\n    float hueT = uv.y * 0.25 + uv.x * 0.60 + t * 0.10;\n    vec3 color1 = palette(hueT);\n\n    // \u4E2D\u95F4\u66F4\u4EAE\u4E00\u70B9\uFF0C\u8FB9\u7F18\u66F4\u6DE1\n    vec3 color2 = mix(color1, vec3(1.0), core * 0.35);\n\n    return vec4(color2, s);\n}\n\n// ------------------------------------------------------------\n// Main\n// ------------------------------------------------------------\nvoid main() {\n    vec2 uv = vUV;\n\n    vec3 col = background(uv);\n\n    vec4 sh = shimmerBand(uv, _Time.y);\n\n    // \u53EF\u9009\uFF1A\u589E\u52A0\u4E00\u70B9\u67D4\u5149\u611F\n    col += sh.rgb * sh.a * 0.06;\n\n    gl_FragColor = vec4(col, 1.0);\n}";
+export declare const loadingConfig: import("./config-definition").ConfigDefinition<"feedback.loading", LoadingConfig>;

package/dist/2d/configs/types.d.ts

@@ -0,0 +1,321 @@
+/** 选区移动与缩放的吸附配置。 */
+export type SnapConfig = {
+    /** 是否启用选区吸附。 */
+    enabled: boolean;
+    /** 吸附线宽度 */
+    lineWidth: number;
+    /** 吸附线颜色 */
+    lineColor: number;
+    /** 吸附判断距离 */
+    distance: number;
+};
+/** 动效内部编辑模式配置。 */
+export type EffectsEditModeConfig = {
+    /** 是否允许子元素移动、缩放和旋转。 */
+    allowTransform: boolean;
+};
+/** 滚轮驱动的视口导航配置。 */
+export type ViewportNavigationConfig = {
+    /** 是否将无修饰键的滚轮事件解释为缩放而非平移。 */
+    scrollWheelZoom: boolean;
+    /** 是否反转滚轮缩放方向。 */
+    invertZoom: boolean;
+    /** 单次滚轮事件允许的最大相对缩放比例。 */
+    zoomStep: number;
+};
+/**
+ * 视口展示 Gizmo 配置
+ */
+export type ViewportOverlayConfig = {
+    /** 视口包围盒颜色 */
+    boxColor: number;
+    /** 视口包围盒线宽 */
+    boxWidth: number;
+    /** 是否绘制画框外遮罩。 */
+    outerMaskEnabled: boolean;
+    /** 蒙版颜色 */
+    markColor: number;
+    /** 蒙版透明度 */
+    markAlpha: number;
+    /** 出血安全区开关 */
+    safeAreaEnabled: boolean;
+    /** 出血安全区包围盒颜色 */
+    safeAreaBoxColor: number;
+    /** 出血安全区包围盒透明度 */
+    safeAreaBoxAlpha: number;
+};
+/** 选区悬停与框选预览配置。 */
+export type SelectionPreviewConfig = {
+    /** 视频元素预选中是否自动播放 */
+    videoPreSelectedPlay: boolean;
+    /** 预选中线宽 */
+    preSelectedWidth: number;
+    /** 预选中颜色 */
+    preSelectedColor: number;
+    /** 框选区域填充色 */
+    regionBoxColor: number;
+    /** 框选区域填充透明度 */
+    regionBoxAlpha: number;
+    /** 框选区域线框颜色 */
+    regionWireframeColor: number;
+    /** 框选区域线框透明度 */
+    regionWireframeAlpha: number;
+    /** 框选区域线框宽度 */
+    regionWireframeWidth: number;
+};
+/** 元素缩放行为：整体缩放，或把缩放吸收到排版尺寸的双轴/单轴调整。 */
+export type ResizeSelectionBehavior = 'scale' | 'resize' | 'resize-x' | 'resize-y';
+/** 选区变换线框、手柄与信息标签配置。 */
+export type ResizeSelectionConfig = {
+    /** 预览基准像素到当前显示尺寸的比例。 */
+    pixelRatio: number;
+    /** 已包含在 viewScale 中的内容适配比例。 */
+    contentRatio: number;
+    /** 按运行时元素 ID 解析整体缩放或排版尺寸调整行为；默认整体缩放。 */
+    resolveResizeBehavior?: (itemId: string) => ResizeSelectionBehavior;
+    /** 线框颜色 */
+    wireframeColor: number;
+    /** 线框透明度 */
+    wireframeAlpha: number;
+    /** 线框线宽 */
+    wireframeWidth: number;
+    /** 角点填充色 */
+    cornerFillColor: number;
+    /** 角点描边色 */
+    cornerLineColor: number;
+    /** 角点描边宽度 */
+    cornerLineWidth: number;
+    /** 角点描边透明度 */
+    cornerLineAlpha: number;
+    /** 缩放交互点半径 */
+    scaleCircleSize: number;
+    /** 旋转交互方形的半边长 */
+    rotationCircleSize: number;
+    /** 画板移动元素位置线颜色 */
+    frameMoveLineColor: number;
+    /** 画板移动元素位置线宽 */
+    frameMoveLineWidth: number;
+    /** 信息展示开关 */
+    infoShowEnabled: boolean;
+    /** 尺寸文案颜色 */
+    sizeTextColor: number;
+    /** 名称文案颜色 */
+    nameTextColor: number;
+    /** 图片元素 logo 地址 */
+    imageLogoUrl: string;
+    /** 成组元素 logo 地址 */
+    groupLogoUrl: string;
+    /** 文本元素 logo 地址 */
+    textLogoUrl: string;
+    /** 视频元素 logo 地址 */
+    videoLogoUrl: string;
+    /** 画板元素 logo 地址 */
+    frameLogoUrl: string;
+    /** 动效元素 logo 地址 */
+    effectsLogoUrl: string;
+};
+/**
+ * 图片裁切 Gizmo 配置
+ */
+export type ImageCutConfig = {
+    /** 蒙版颜色 */
+    maskColor: number;
+    /** 蒙版透明度 */
+    maskAlpha: number;
+    /** 裁切包围盒线宽 */
+    cutBoxLineWidth: number;
+    /** 裁切包围盒线色 */
+    cutBoxLineColor: number;
+    /** 裁切包围盒线透明度 */
+    cutBoxLineAlpha: number;
+    /** 元素包围盒线宽 */
+    itemBoxLineWidth: number;
+    /** 元素包围盒线色 */
+    itemBoxLineColor: number;
+    /** 元素包围盒线透明度 */
+    itemBoxLineAlpha: number;
+    /** 角点半径 */
+    cutBoxCornerRadius: number;
+    /** 角点填充色 */
+    cutBoxCornerFillColor: number;
+    /** 角点线宽 */
+    cutBoxCornerLineWidth: number;
+    /** 角点线色 */
+    cutBoxCornerLineColor: number;
+    /** 角点线透明度 */
+    cutBoxCornerLineAlpha: number;
+    /** 缩放交互判断距离 */
+    scaleInteractionDistance: number;
+    /** 单向缩放交互判断距离 */
+    directionScaleInteractionDistance: number;
+    /** 网格线宽度 */
+    gridLineWidth: number;
+    /** 网格线颜色 */
+    gridLineColor: number;
+    /** 网格线透明度 */
+    gridLineAlpha: number;
+    /** 网格线数量 */
+    gridCount: number;
+};
+/**
+ * 图片扩边 Gizmo 配置
+ */
+export type ImageExpandConfig = {
+    /** 蒙版颜色 */
+    maskColor: number;
+    /** 蒙版透明度 */
+    maskAlpha: number;
+    /** 扩边包围盒线宽 */
+    expandBoxLineWidth: number;
+    /** 扩边包围盒线色 */
+    expandBoxLineColor: number;
+    /** 扩边包围盒线透明度 */
+    expandBoxLineAlpha: number;
+    /** 角点半径 */
+    expandBoxCornerRadius: number;
+    /** 角点线宽 */
+    expandBoxCornerLineWidth: number;
+    /** 角点线色 */
+    expandBoxCornerLineColor: number;
+    /** 角点线透明度 */
+    expandBoxCornerLineAlpha: number;
+    /** 角点填充色 */
+    expandBoxCornerFillColor: number;
+    /** 缩放交互判断距离 */
+    scaleInteractionDistance: number;
+    /** 单向缩放交互判断距离 */
+    directionScaleInteractionDistance: number;
+    /** 网格线宽度 */
+    gridLineWidth: number;
+    /** 网格线颜色 */
+    gridLineColor: number;
+    /** 网格线透明度 */
+    gridLineAlpha: number;
+    /** 网格线数量 */
+    gridCount: number;
+};
+/**
+ * 蒙版 Gizmo 配置
+ */
+export type MaskConfig = {
+    /** 黑白蒙版图片 URL；空字符串表示不使用基础蒙版图 */
+    maskImage: string;
+    /** 画笔大小 */
+    brushSize: number;
+    /** 笔刷颜色 */
+    brushColor: number;
+    /** 笔刷透明度 */
+    brushAlpha: number;
+    /** 蒙版颜色 */
+    maskColor: number;
+    /** 蒙版背景色 */
+    maskBackgroundColor: number;
+    /** 蒙版透明度 */
+    maskAlpha: number;
+    /** 元素包围盒线框宽度 */
+    boxLineWidth: number;
+    /** 元素包围盒线框颜色 */
+    boxLineColor: number;
+    /** 元素包围盒线框透明度 */
+    boxLineAlpha: number;
+};
+/**
+ * 精准改字 Gizmo 配置
+ */
+export type SpriteTextEditConfig = {
+    /** 文案颜色 */
+    textColor: number;
+    /** 预选中文案颜色 */
+    preSelectedTextColor: number;
+    /** 包围盒线框宽度 */
+    boxLineWidth: number;
+    /** 包围盒间隔线长度 */
+    dashLineDash: number;
+    /** 包围盒间隔线间隔 */
+    dashLineGap: number;
+    /** 编辑包围盒颜色 */
+    editBoxColor: number;
+    /** 编辑包围盒透明度 */
+    editBoxAlpha: number;
+    /** 编辑包围盒线框颜色 */
+    editBoxLineColor: number;
+    /** 编辑包围盒线框透明度 */
+    editBoxLineAlpha: number;
+    /** 编辑包围盒预选颜色 */
+    editBoxPreSelectedColor: number;
+    /** 编辑包围盒预选透明度 */
+    editBoxPreSelectedAlpha: number;
+    /** 编辑包围盒预选线框颜色 */
+    editBoxLinePreSelectedColor: number;
+    /** 编辑包围盒预选线框透明度 */
+    editBoxLinePreSelectedAlpha: number;
+    /** 已更改编辑包围盒颜色 */
+    hasChangedEditBoxColor: number;
+    /** 已更改编辑包围盒透明度 */
+    hasChangedEditBoxAlpha: number;
+    /** 已更改编辑包围盒线框颜色 */
+    hasChangedEditBoxLineColor: number;
+    /** 已更改编辑包围盒线框透明度 */
+    hasChangedEditBoxLineAlpha: number;
+    /** 已更改编辑包围盒预选颜色 */
+    hasChangedEditBoxPreSelectedColor: number;
+    /** 已更改编辑包围盒预选透明度 */
+    hasChangedEditBoxPreSelectedAlpha: number;
+    /** 已更改编辑包围盒预选线框颜色 */
+    hasChangedEditBoxLinePreSelectedColor: number;
+    /** 已更改编辑包围盒预选线框透明度 */
+    hasChangedEditBoxLinePreSelectedAlpha: number;
+    /** 选中状态标记包围盒颜色 */
+    editBoxSelectedColor: number;
+    /** 选中状态标记包围盒透明度 */
+    editBoxSelectedAlpha: number;
+};
+/**
+ * 图标 Gizmo 配置
+ */
+export type IconConfig = {
+    /** 自动展示 */
+    autoShow: boolean;
+    /** 视频播放图标地址 */
+    videoPlayUrl: string;
+    /** 视频播放图标距右下角偏移值 */
+    videoPlayShift: [number, number];
+    /** 视频播放图标宽 */
+    videoPlayWidth: number;
+    /** 视频播放图标高 */
+    videoPlayHeight: number;
+    /** 图片生成器图标地址 */
+    imageGeneratorUrl: string;
+    /** 视频生成器图标地址 */
+    videoGeneratorUrl: string;
+    /** 生成器图标宽 */
+    generatorWidth: number;
+    /** 生成器图标高 */
+    generatorHeight: number;
+};
+/**
+ * 元素创建 Gizmo 配置
+ */
+export type ItemCreateConfig = {
+    /** 边框颜色 */
+    frameBorderColor: number;
+    /** 边框宽度 */
+    frameBorderWidth: number;
+    /** 边框透明度 */
+    frameBorderAlpha: number;
+    /** 填充颜色 */
+    frameFillColor: number;
+    /** 填充透明度 */
+    frameFillAlpha: number;
+    /** 选中子元素包围盒透明度 */
+    frameChildBoxAlpha: number;
+    /** 选中子元素包围盒颜色 */
+    frameChildBoxColor: number;
+};
+/**
+ * Loading Gizmo 配置
+ */
+export type LoadingConfig = {
+    /** Loading 态 fragment 标识 */
+    loadingFragment: string;
+};

package/dist/2d/cursor-icons.d.ts

@@ -0,0 +1,8 @@
+import type { GestureCursorType } from './cursor';
+export declare const cursorMap: Record<GestureCursorType, {
+    type: 'svg' | 'preset';
+    content: string;
+    url?: string;
+}>;
+/** 加载并缓存所有 SVG 光标资源。 */
+export declare function loadCursorIcons(): Promise<void>;

package/dist/2d/cursor.d.ts

@@ -0,0 +1,36 @@
+/** Gizmo 提交给宿主的光标样式。 */
+export type GestureCursorResult = {
+    /** 光标类型。 */
+    type: GestureCursorType;
+    /** 光标旋转角度。 */
+    angle: number;
+    /** 圆形光标半径。 */
+    radius?: number;
+};
+/** 内置光标类型。 */
+export declare enum GestureCursorType {
+    /** 默认光标。 */
+    NORMAL = "normal",
+    /** 旋转光标。 */
+    ROTATION = "rotation",
+    /** 缩放光标。 */
+    SCALE = "scale",
+    /** 文本旋转光标。 */
+    TEXT_ROTATION = "text-rotation",
+    /** 圆形画笔光标。 */
+    CIRCLE = "circle",
+    /** 可抓取手形光标。 */
+    HAND = "hand",
+    /** 抓取中的手形光标。 */
+    ACTIVE_HAND = "active-hand",
+    /** 指针光标。 */
+    POINTER = "pointer",
+    /** 文本编辑光标。 */
+    TEXT = "text",
+    /** 文本创建光标。 */
+    TEXT_CREATE = "text-create",
+    /** 画板创建光标。 */
+    FRAME_CREATE = "frame-create",
+    /** 框选十字光标。 */
+    BOX_SELECT = "box-select"
+}

package/dist/2d/drag-threshold.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 鼠标拖拽轮次的起始距离（CSS px）。
+ */
+export declare const DRAG_THRESHOLD_PX = 5;
+/**
+ * 判断指针相对按下点的累计位移是否达到拖拽阈值。
+ * @param startClientX 按下点 X 坐标
+ * @param startClientY 按下点 Y 坐标
+ * @param currentClientX 当前 X 坐标
+ * @param currentClientY 当前 Y 坐标
+ * @returns 是否达到拖拽阈值
+ */
+export declare function isDragThresholdReached(startClientX: number, startClientY: number, currentClientX: number, currentClientY: number): boolean;