@vvfx/sdk 0.2.2 → 0.2.4

package/dist/config.d.ts

@@ -1,6 +1,10 @@
 import { ExportMediaInitOptions } from './exporter';
 import { GlobalLayoutMode } from './utils';
+import type { CardHTML } from './types';
+import type { CardItem } from './sdk-item/card-item';
 export type SDKMode = 'editor' | 'template';
+export type CardTypeHTMLResolver = (item: CardItem) => CardHTML | undefined;
+export type CardAutoHeightAnchor = 'top' | 'center';
 /**
  * @description SDK功能配置
  */
@@ -136,6 +140,30 @@ export type CardTypeConfig = {
      * @description TransformGizmo 左上角展示的 icon URL
      */
     iconUrl: string;
+    /**
+     * @description 卡片类型对应的运行时 HTML 渲染配置；函数不会进入序列化数据，恢复时由 cardType 动态解析。
+     */
+    html?: CardTypeHTMLResolver;
+    /**
+     * @description 是否根据 HTML 挂载内容的自然高度自动更新卡片高度
+     */
+    autoHeight?: boolean;
+    /**
+     * @description autoHeight 更新卡片高度时的锚点。top 保持上边缘不动，center 保持中心点不动。未配置时默认 top。
+     */
+    autoHeightAnchor?: CardAutoHeightAnchor;
+    /**
+     * @description HTML 内容是否跟随卡片 scale 缩放，关闭后 HTML 按最终显示尺寸重新布局
+     */
+    autoScale?: boolean;
+    /**
+     * @description 是否启用编辑态交互。未配置时默认 true；只有显式 false 时，卡片默认直接交互且不进入编辑态。
+     */
+    editable?: boolean;
+    /**
+     * @description HTML 内容中可在非编辑态直接响应事件的额外 CSS 选择器；会与 SDK 默认交互选择器合并。
+     */
+    htmlInteractionSelectors?: string[];
 };
 /**
  * @description 卡片元素参数配置
@@ -146,7 +174,7 @@ export type CardConfig = {
      */
     backgroundColor: [number, number, number, number];
     /**
-     * @description 注册的卡片类型列表，支持动态配置
+     * @description 注册的卡片类型列表，支持通过 registerCardType/registerCardTypes 动态配置
      * 每个条目包含 type 标识、显示名称和图标 URL
      */
     cardTypes: CardTypeConfig[];

package/dist/gesture-handler/gizmo/mask-gizmo.d.ts

@@ -28,7 +28,7 @@ export declare class MaskGizmo extends Gizmo {
     private _config;
     private boxGraphics;
     type: GizmoType;
-    mode: 'paint' | 'erase';
+    mode: 'paint' | 'erase' | 'box-erase' | 'box-paint';
     /**
      * 蒙版工具独立的撤销重做实例
      */
@@ -37,6 +37,10 @@ export declare class MaskGizmo extends Gizmo {
      * 存储绘画开始前的数据，用于 undoRedo
      */
     private _oldLines;
+    /**
+     * 框选擦除进行中标记（按下到松开之间），用于实时选框描边的显示控制
+     */
+    private _isBoxErasing;
     /**
      * 鼠标状态绘制结果
      */
@@ -52,9 +56,17 @@ export declare class MaskGizmo extends Gizmo {
     set config(config: Partial<MaskGizmoConfig>);
     /**
      * 设置模式
-     * @param mode 模式类型：'paint' 表示涂抹，'erase' 表示擦除
+     * @param mode 模式类型：'paint' 笔刷涂抹、'erase' 笔刷逐笔擦除、'box-erase' 框选擦除、'box-paint' 框选涂抹
+     */
+    setMode(mode: 'paint' | 'erase' | 'box-erase' | 'box-paint'): void;
+    /**
+     * @description 判断点是否在包围盒内
+     */
+    private _isPointInBox;
+    /**
+     * @description 将屏幕坐标转换为包围盒内的归一化坐标 [0,1]（钳制在范围内）
      */
-    setMode(mode: 'paint' | 'erase'): void;
+    private _toNormalized;
     initialize(): void;
     preparationAction(event: MouseEvent): GizmoType | undefined;
     preAction(event: MouseEvent): GizmoType | undefined;

package/dist/gesture-handler/gizmo/type.d.ts

@@ -85,6 +85,10 @@ export type MaskResult = {
         brushSize: number;
         points: Vector2[];
         type?: 'paint' | 'erase';
+        /**
+         * @description 形状类型：'stroke' 折线（默认），'rect' 矩形框选（points=[起点, 终点]）
+         */
+        shape?: 'stroke' | 'rect';
     }[];
 };
 /**
@@ -396,7 +400,7 @@ export type InsertPosition = {
     siblingId?: string;
 };
 export type GizmoType = 'null' | 'selector' | 'transform' | 'control' | 'adsorption' | 'preference' | 'picture-cut' | 'text' | 'mask' | 'loading' | 'picture-expand' | 'sprite-text-edit' | 'icon' | 'item-create';
-export type GestureCursorType = 'normal' | 'rotation' | 'scale' | 'text-rotation' | 'circle' | 'hand' | 'active-hand' | 'pointer' | 'text-create' | 'frame-create';
+export type GestureCursorType = 'normal' | 'rotation' | 'scale' | 'text-rotation' | 'circle' | 'hand' | 'active-hand' | 'pointer' | 'text-create' | 'frame-create' | 'box-select';
 export type TransformType = 'null' | 'translation' | 'rotation' | 'scale';
 export type GestureHandlerInteractType = 'select' | 'hand';
 export type ControlGizmoInteractionType = 'mouse' | 'wheel';

package/dist/gesture-handler/src/gesture-handler.d.ts

@@ -107,7 +107,7 @@ export declare class GestureHandler {
     closeMaskGizmo(): void;
     setMaskGizmoConfig(config: Partial<MaskGizmoConfig>): void;
     getMask(): string | null | undefined;
-    setMaskGizmoMode(mode: 'paint' | 'erase'): void;
+    setMaskGizmoMode(mode: 'paint' | 'erase' | 'box-erase' | 'box-paint'): void;
     openLoadingGizmo(id: string, options?: {
         loadingBox?: Box2;
         clearSelected?: boolean;

package/dist/html-overlay/anchor-navigation-runtime.d.ts

@@ -0,0 +1 @@
+export declare function withCardHTMLAnchorNavigationGuard(html: string, allowAnchorNavigation?: boolean): string;

package/dist/html-overlay/auto-height-runtime.d.ts

@@ -4,10 +4,15 @@ export type CardHTMLAutoHeightMessage = {
     id: string;
     height: number;
 };
+export type CardHTMLAutoHeightRequest = {
+    source: 'vvfx-card-html-auto-height-request';
+    id: string;
+};
 export type CardHTMLAutoHeightOptions = {
     autoHeightId?: string;
     onAutoHeight?: (height: number) => void;
 };
 export declare function createAutoHeightMessageListener(iframe: HTMLIFrameElement, options?: CardHTMLAutoHeightOptions): CardHTMLRenderCleanup;
 export declare function isCardHTMLAutoHeightMessage(data: unknown, id: string): data is CardHTMLAutoHeightMessage;
+export declare function requestCardHTMLAutoHeight(iframe: HTMLIFrameElement, id: string): void;
 export declare function withCardHTMLAutoHeightBridge(html: string, id?: string): string;

package/dist/html-overlay/manager.d.ts

@@ -1,14 +1,20 @@
 import type { Box2 } from '../math';
 import { type SnapdomOptions } from '@zumer/snapdom';
+import type { CardAutoHeightAnchor, CardTypeConfig } from '../config';
 import type { EventEmitter } from '../shared';
 import type { SDKEvents } from '../sdk';
 import { type SDKItem } from '../sdk-item';
+import type { CardHTML } from '../types';
 type CardRasterizeOptions = {
     width: number;
     height: number;
     pixelRatio?: number;
     snapdomOptions?: SnapdomOptions;
 };
+type SetCardItemHeightOptions = {
+    anchor: CardAutoHeightAnchor;
+    previousHeight: number;
+};
 type HTMLOverlayManagerOptions = {
     container: HTMLElement;
     emitter: EventEmitter<SDKEvents>;
@@ -23,47 +29,102 @@ type HTMLOverlayManagerOptions = {
         translation: [number, number];
     }) => void;
     viewportFit: (box: Box2) => void;
-    setCardItemHeight: (id: string, height: number) => void;
+    setCardItemHeight: (id: string, height: number, options: SetCardItemHeightOptions) => void;
+    getSelectedItemIds: () => string[];
+    setSelectedItemIds: (ids: string[]) => void;
+    getPreSelectedItemId: () => string | undefined;
+    getSelectionEdgeStyle: () => {
+        color: number;
+        alpha: number;
+        width: number;
+    };
+    getPreSelectionEdgeStyle: () => {
+        color: number;
+        alpha: number;
+        width: number;
+    };
+    getCanvasEventTarget?: () => HTMLElement | undefined;
+    resolveCardHTML: (item: SDKItem) => CardHTML | undefined;
+    resolveCardTypeConfig: (item: SDKItem) => CardTypeConfig | undefined;
 };
 export declare class HTMLOverlayManager {
     private options;
     private eventCleanups;
+    private htmlRootConfigCleanups;
+    private pendingContentInteractionEvent?;
+    private contentInteractionFrame?;
     private state;
     constructor(options: HTMLOverlayManagerOptions);
     attach(): void;
+    get layerElement(): HTMLElement | undefined;
     dispose(): void;
     scheduleRender(): void;
+    invalidateCardHTML(id: string): void;
+    getHtmlCardWindow(id: string): Window | null | undefined;
+    patchCardHTML(id: string, patch: unknown): boolean;
+    dispatchHtmlCardEvent(id: string, type: string, detail?: unknown): boolean;
     rasterizeCard(id: string, options: CardRasterizeOptions): Promise<string | undefined>;
     private initEvents;
     private initDOMEvents;
     private handleContainerDoubleClick;
     private handleContainerMouseDown;
+    private selectHTMLInteractionCard;
     private handleContainerMouseMove;
     private handleContainerMouseLeave;
+    private isMouseLeaveWithinContainer;
+    private handleContainerContextMenu;
+    private isHTMLContextMenuEvent;
     private handleViewportTransform;
     private render;
     private syncOverlayOrder;
+    private getOrCreateSelectionLayer;
     private renderFrameOverlays;
     private getOrCreateFrameOverlay;
     private getOrCreateOverlay;
+    private getOrCreateSelectionOverlay;
+    private syncOverlaySelection;
+    private getSelectionBoxShadow;
+    private getPreSelectionBoxShadow;
     private getHTMLCardIdByEvent;
     private getHoverShellInteractiveIdByEvent;
+    private syncActiveContentInteraction;
+    private scheduleActiveContentInteractionSync;
+    private setActiveContentInteraction;
+    private shouldKeepActiveContentInteractionForFocusedElement;
+    private resolveHTMLInteractionTarget;
+    private getActiveSubtreeInteractionAtEvent;
+    private resolveContentInteractionZone;
+    private getContentInteractionZones;
+    private getContentInteractiveSelector;
+    private isContentInteractionDisabled;
+    private getContentInteractionZoneMode;
+    private invalidateContentInteractionZones;
+    private observeContentInteractionZoneResizes;
     private getLayerPoint;
     private getOrCreateContentOverlay;
     private createContentScaleOverlay;
     private syncContentScale;
+    private requestAutoHeightFromIframes;
     private syncContentInteraction;
+    private syncContentInteractionZones;
+    private clearContentInteractionState;
     private syncShellInteraction;
     private enterEditing;
     private exitEditing;
+    private isEditableCard;
     private getEditingFitZoom;
     private isEventInsideOverlay;
     private renderOverlayHTML;
+    private createPatchContext;
+    private observeContentInteractionZones;
+    private applyHTMLRootConfig;
+    private makeSelectionOverlayTransparent;
     private renderOverlayContent;
     private chainCleanups;
     private cleanupOverlayContent;
     private removeOverlay;
     private syncAutoHeight;
+    private ensureAutoHeightMode;
     private createAutoHeightObserver;
     private scheduleAutoHeightMeasure;
     private measureAutoHeight;
@@ -72,6 +133,10 @@ export declare class HTMLOverlayManager {
     private getChildrenNaturalHeight;
     private cleanupAutoHeight;
     private applyAutoHeight;
+    private getAutoHeightAnchor;
+    private getAutoHeightItemHeight;
     private isAutoHeightMessage;
+    private isAutoHeightEnabled;
+    private isAutoScaleEnabled;
 }
 export {};

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

@@ -4,9 +4,11 @@ export type CardOverlayBoxStyle = {
     top: string;
     width: string;
     height: string;
+    contentWidth: number;
+    contentHeight: number;
     transform: string;
 };
-export declare function getCardOverlayBoxStyle(box: Box2, width: number, height: number, offsetX?: number, offsetY?: number): CardOverlayBoxStyle;
+export declare function getCardOverlayBoxStyle(box: Box2, width: number, height: number, offsetX?: number, offsetY?: number, _autoScale?: boolean): CardOverlayBoxStyle;
 export declare function isPointInCardOverlayBox(box: Box2, point: {
     x: number;
     y: number;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export type { SDKOptions, SDKInputParam, PageData, PageProperty, ViewProperty, ActiveData, ViewParam, BaseItemProperty, SpriteItemProperty, TextItemProperty, VideoItemProperty, GeneratorItemProperty, FrameItemProperty, FrameLayoutMode, SpriteCreateInfo, TextCreateInfo, GroupCreateInfo, VideoCreateInfo, GeneratorCreateInfo, EffectsCreateInfo, FrameCreateInfo, CardCreateInfo, CardItemProperty, CardItemTransformInfo, ItemCreateInfo, } from './types';
-export type { CardTypeConfig, CardConfig } from './config';
+export type { SDKOptions, SDKInputParam, PageData, PageProperty, ViewProperty, ActiveData, ViewParam, BaseItemProperty, SpriteItemProperty, TextItemProperty, VideoItemProperty, GeneratorItemProperty, FrameItemProperty, FrameLayoutMode, SpriteCreateInfo, TextCreateInfo, GroupCreateInfo, VideoCreateInfo, GeneratorCreateInfo, EffectsCreateInfo, FrameCreateInfo, CardCreateInfo, CardItemProperty, CardItemTransformInfo, CardHTML, CardHTMLContent, CardHTMLInlineContent, CardHTMLDOMRendererContent, CardHTMLDocumentContent, CardHTMLDocumentMessage, CardHTMLShellContent, CardHTMLShellRenderer, CardHTMLShellRendererContext, CardHTMLShellRendererResult, CardHTMLDOMRenderer, CardHTMLContentCleanup, CardHTMLRenderCleanup, CardHTMLPatchContext, CardHTMLPatchHandler, CardHTMLWindowEventMessage, CardHTMLRootConfig, CardHTMLRootStyle, ItemCreateInfo, } from './types';
+export type { SDKConfig, SDKMode, CardTypeConfig, CardConfig, CardAutoHeightAnchor, CardTypeHTMLResolver, } from './config';
 export type { SDKItem } from './sdk-item';
 export { BaseItem, SpriteItem, TextItem, VideoItem, GroupItem, GeneratorItem, EffectsItem, FrameItem, CardItem, isBaseItem, isSpriteItem, isTextItem, isVideoItem, isGroupItem, isGeneratorItem, isEffectsItem, isFrameItem, isCardItem, SDKItemType, } from './sdk-item';
 export type { SDKItemOptions, SpriteItemOptions, TextItemOptions, VideoItemOptions, GroupItemOptions, GeneratorItemOptions, EffectsItemOptions, FrameItemOptions, CardItemOptions, } from './sdk-item';