@vvfx/artis 0.0.1-alpha.0

package/dist/helper/exporter/utils.d.ts

@@ -0,0 +1,71 @@
+import type { Img2WebPCore } from './types';
+import { Player } from '@galacean/effects';
+/**
+ * 将数字保留两位小数
+ * @param num 输入数字
+ * @returns 保留两位小数后的数字
+ */
+export declare function getTwoDecimal(num: number): number;
+/**
+ * 将播放器画布按背景色/背景画布合成绘制到输出画布
+ * @param playerCanvas 播放器画布
+ * @param canvas 输出画布
+ * @param backgroundColor 背景色
+ * @param backgroundCanvas 可选背景画布
+ */
+export declare function drawToOutputCanvas(playerCanvas: HTMLCanvasElement, canvas: HTMLCanvasElement, backgroundColor: string, backgroundCanvas?: HTMLCanvasElement): void;
+/**
+ * 按AlphaMask视频格式将输入画布拆分rgb与alpha通道拼接到输出画布
+ * @param inputCanvas 输入画布
+ * @param outputCanvas 输出画布（宽度为输入的两倍）
+ */
+export declare function getAlphaMaskImage(inputCanvas: HTMLCanvasElement, outputCanvas: HTMLCanvasElement): void;
+/**
+ * 将字符串参数数组写入 img2webp 内核内存，返回 argc/argv 指针
+ * @param Core img2webp 内核实例
+ * @param args 命令行参数数组
+ * @returns [参数个数, 参数指针数组地址]
+ */
+export declare function parseArgs(Core: Img2WebPCore, args: string[]): number[];
+/**
+ * 将 canvas 转为 ArrayBuffer，底层走 toBlob
+ * @param canvas 目标画布
+ * @param mime 输出 MIME 类型
+ * @param quality 输出质量（0-1）
+ * @returns 图片对应的 ArrayBuffer
+ */
+export declare function canvasToArrayBuffer(canvas: HTMLCanvasElement, mime?: string, quality?: number): Promise<ArrayBuffer>;
+/** 等待一帧（requestAnimationFrame）后 resolve */
+export declare function sleepForOneFrame(): Promise<unknown>;
+/**
+ * 数字前补零到指定长度
+ * @param num 原数字
+ * @param length 目标字符串长度
+ * @returns 补零后的字符串
+ */
+export declare function padZero(num: number, length: number): string;
+/**
+ * 异步加载 img2webp 脚本并初始化内核实例
+ * @returns 初始化完成的 Img2WebPCore 实例
+ */
+export declare function loadWebpHelper(): Promise<Img2WebPCore>;
+export type LoadFFmpegHelperOptions = {
+    multiThreading?: boolean;
+};
+export type LoadConfig = {
+    coreURL: string;
+    wasmURL: string;
+    workerURL?: string;
+    classWorkerURL?: string;
+};
+/**
+ * 动态加载并初始化 FFmpeg 实例，按需选择多线程/单线程内核
+ * @param options 加载选项，可指定多线程
+ * @returns 加载完成的 FFmpeg 实例
+ */
+export declare function loadFFmpegHelper(options?: LoadFFmpegHelperOptions): Promise<import("@ffmpeg/ffmpeg").FFmpeg>;
+/**
+ * 清理播放器当前合成相关的纹理与合成资源
+ * @param player 目标播放器
+ */
+export declare function clearPlayerAssets(player: Player): void;

package/dist/helper/exporter/wav-audio.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 生成 wav 音轨文件
+ * NOTE: 为什么不直接使用 ffmpeg 命令生成音轨？
+ * 因为直接使用 ffmpeg 命令生成音轨，会造成视频转码过程中存在 blocking 问题，
+ * 这里对于音轨要求不高，只是生成一个静音音轨，所以手动生成 wav 文件
+ */
+export type WavAudioOptions = {
+    /**
+     * 采样率，默认 44100（标准采用率）
+     */
+    sampleRate?: number;
+    /**
+     * 时长，单位秒，默认 1
+     */
+    duration?: number;
+    /**
+     * 通道数，默认 2
+     */
+    channels?: number;
+};
+export declare class WavAudio {
+    sampleRate: number;
+    duration: number;
+    channels: number;
+    /**
+     * 构造 WavAudio，按参数生成静音 wav 配置
+     * @param options 采样率/时长/通道数选项
+     */
+    constructor(options?: WavAudioOptions);
+    /**
+     * 按RIFF/WAVE规范生成静音 wav 文件字节
+     * @returns wav 文件对应的 Uint8Array
+     */
+    getBuffer(): Uint8Array;
+}

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

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

package/dist/helper/html-overlay/auto-height-layout.d.ts

@@ -0,0 +1,16 @@
+export type AutoHeightFeedback = {
+    nextHeight: number;
+    offset: number;
+    steps: number;
+};
+export declare function resolveTopAnchoredCardPosition({ nextHeight, position, previousHeight, scaleY, }: {
+    nextHeight: number;
+    position: [number, number];
+    previousHeight: number;
+    scaleY: number;
+}): [number, number];
+export declare function clampCardAutoHeight(height: number, initialHeight: number): number;
+export declare function trackAutoHeightFeedback(previous: AutoHeightFeedback | undefined, currentHeight: number, nextHeight: number): {
+    feedback?: AutoHeightFeedback;
+    loopDetected: boolean;
+};

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

@@ -0,0 +1,40 @@
+import type { CardHTMLRenderCleanup } from '../../core';
+export type CardHTMLAutoHeightMessage = {
+    source: 'vvfx-card-html-auto-height';
+    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;
+    onStreamRuntimePhase?: (phase: CardHTMLStreamRuntimePhase) => void;
+    streamRuntimeId?: string;
+};
+export type CardHTMLStreamRuntimePhase = 'parsing' | 'draining' | 'complete' | 'finalizing' | 'disposed' | 'error';
+/**
+ * 为 iframe 创建自动高度消息监听，未配置自动高度时返回空清理函数
+ * @param iframe 监听目标的 iframe
+ * @param options 自动高度 ID 与回调
+ * @returns 注销监听的清理函数
+ */
+export declare function createAutoHeightMessageListener(iframe: HTMLIFrameElement, options?: CardHTMLAutoHeightOptions): CardHTMLRenderCleanup;
+export declare function getCardHTMLStreamRuntimePhase(data: unknown, expectedRuntimeId: string): CardHTMLStreamRuntimePhase | undefined;
+/**
+ * 类型守卫：判断消息是否为指定卡片的自动高度消息
+ * @param data 待判断的消息
+ * @param id 卡片 ID
+ * @returns 是否匹配
+ */
+export declare function isCardHTMLAutoHeightMessage(data: unknown, id: string): data is CardHTMLAutoHeightMessage;
+export declare function requestCardHTMLAutoHeight(iframe: HTMLIFrameElement, id: string): void;
+/**
+ * 在 HTML 中注入自动高度桥接脚本，无 id 时原样返回
+ * @param html 原始 HTML
+ * @param id 自动高度卡片 ID
+ * @returns 注入脚本后的 HTML
+ */
+export declare function withCardHTMLAutoHeightBridge(html: string, id?: string): string;

package/dist/helper/html-overlay/document-runtime.d.ts

@@ -0,0 +1,18 @@
+import { type CardHTMLAutoHeightOptions } from './auto-height-runtime';
+import { CardHTMLContentCleanup, CardHTMLDocumentContent, CardHTMLDOMRenderer, CardHTMLRenderCleanup } from '../../core/types';
+/**
+ * 将文档型卡片内容渲染到 iframe 中，挂载消息与自动高度桥接
+ * @param overlay 内容容器
+ * @param content 文档型卡片内容
+ * @param options 自动高度相关参数
+ * @returns 清空 iframe 与监听的清理函数
+ */
+export declare function renderDocumentContent(overlay: HTMLElement, content: CardHTMLDocumentContent, options?: CardHTMLAutoHeightOptions): CardHTMLRenderCleanup;
+/**
+ * 在 iframe 中渲染 DOM 型卡片内容，每次 load 重新挂载并清理上一轮
+ * @param overlay 内容容器
+ * @param render DOM 渲染函数
+ * @param cleanup 可选的 DOM 清理函数
+ * @returns 移除 iframe 与相关监听的清理函数
+ */
+export declare function renderDOMContentInIframe(overlay: HTMLElement, render: CardHTMLDOMRenderer, cleanup?: CardHTMLContentCleanup): CardHTMLRenderCleanup;

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

@@ -0,0 +1,46 @@
+export type DocumentFileUrlFactory = (rawPath: string, fromPath: string) => string;
+/**
+ * 将文件记录归一化为路径到源的 Map
+ * @param files 原始文件记录
+ * @returns 归一化后的 Map
+ */
+export declare function normalizeDocumentFiles(files: Record<string, string>): Map<string, string>;
+/**
+ * 创建文件路径到 data URL 的工厂函数，带缓存与循环引用保护
+ * @param files 归一化后的文件表
+ * @returns URL 工厂函数
+ */
+export declare function createDocumentFileUrlFactory(files: Map<string, string>): DocumentFileUrlFactory;
+/**
+ * 按文件扩展名分发返回变换后的源码，未匹配类型原样返回
+ * @param path 文件路径
+ * @param source 原始源码
+ * @param createFileUrl URL 工厂
+ * @param resolving 正在解析的路径集合，防止循环
+ * @returns 变换后的源码
+ */
+export declare function transformDocumentFile(path: string, source: string, createFileUrl: DocumentFileUrlFactory, resolving?: Set<string>): string;
+/**
+ * 重写 HTML 中的资源引用并把内联 style/script 交由对应变换器处理
+ * @param path 当前文件路径
+ * @param source 原始 HTML
+ * @param createFileUrl URL 工厂
+ * @returns 变换后的 HTML
+ */
+export declare function transformHTMLDocument(path: string, source: string, createFileUrl: DocumentFileUrlFactory): string;
+/**
+ * 重写 CSS 中 url() 与 @import 的资源引用为 data URL
+ * @param path 当前文件路径
+ * @param source 原始 CSS
+ * @param createFileUrl URL 工厂
+ * @returns 变换后的 CSS
+ */
+export declare function transformCSSDocument(path: string, source: string, createFileUrl: DocumentFileUrlFactory): string;
+/**
+ * 重写 JS 中静态 import、动态 import 与 from 的模块引用为 data URL
+ * @param path 当前文件路径
+ * @param source 原始 JS
+ * @param createFileUrl URL 工厂
+ * @returns 变换后的 JS
+ */
+export declare function transformJSDocument(path: string, source: string, createFileUrl: DocumentFileUrlFactory): string;

package/dist/helper/html-overlay/dom-order.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 按数组顺序给元素赋递增 z-index 同步堆叠层级
+ * @param elements 需同步顺序的元素列表
+ */
+export declare function syncElementStackOrder(elements: HTMLElement[]): void;

package/dist/helper/html-overlay/host-message-runtime.d.ts

@@ -0,0 +1,15 @@
+import type { CardHTMLDocumentContent, CardHTMLDocumentMessage, CardHTMLRenderCleanup } from '../../core';
+/**
+ * 创建监听 iframe 内卡片 HTML 文档消息的宿主监听器，返回用于卸载监听的清理函数。
+ * 仅当内容声明启用 host messaging 且提供 onMessage 回调时才绑定，否则返回空函数。
+ * @param iframe 承载卡片 HTML 文档的 iframe 元素，用于校验消息来源。
+ * @param content 卡片 HTML 文档内容，提供是否启用宿主消息及消息回调。
+ * @returns 卸载监听的清理函数。
+ */
+export declare function createHostMessageListener(iframe: HTMLIFrameElement, content: CardHTMLDocumentContent): CardHTMLRenderCleanup;
+/**
+ * 判断未知数据是否符合卡片 HTML 文档消息结构，来源需为 'vvfx-card-html' 且 type 为字符串。
+ * @param data 待校验的消息数据。
+ * @returns 命中消息结构则返回 true，作为类型守卫收窄类型。
+ */
+export declare function isCardHTMLDocumentMessage(data: unknown): data is CardHTMLDocumentMessage;

package/dist/helper/html-overlay/html-capture-runtime.d.ts

@@ -0,0 +1,12 @@
+export type HTMLCaptureViewportSize = {
+    width: number;
+    height: number;
+};
+export type HTMLCaptureTarget = {
+    cleanup: () => void;
+    target: HTMLElement;
+};
+export declare function captureViewportSize(logicalSize: HTMLCaptureViewportSize, _displayedBounds?: Pick<DOMRectReadOnly, 'width' | 'height'>): HTMLCaptureViewportSize;
+export declare function serializeComputedCaptureStyle(style: CSSStyleDeclaration): string;
+export declare function createHTMLCaptureReplica(ownerDocument: Document, html: string, logicalSize: HTMLCaptureViewportSize): Promise<HTMLCaptureTarget | undefined>;
+export declare function createHTMLCaptureReplicaFromDocument(ownerDocument: Document, sourceDocument: Document, logicalSize: HTMLCaptureViewportSize): Promise<HTMLCaptureTarget | undefined>;

package/dist/helper/html-overlay/html-card-service.d.ts

@@ -0,0 +1,287 @@
+import { CardHTML, CardTypeConfig, type CardItem } from '../../core';
+/**
+ * HTML 卡片服务。
+ *
+ * 对外提供内容解析、刷新、增量更新与跨文档通信；同一实例在内部负责
+ * HTML 覆盖层的挂载、布局、交互和栅格化，不再维护独立的 manager。
+ */
+export declare class HTMLCardService {
+    private options;
+    private isAutoHeightMessage;
+    private eventCleanups;
+    private htmlRootConfigCleanups;
+    private pendingContentInteractionEvent?;
+    private contentInteractionFrame?;
+    private state;
+    /** HTML 卡片根层，由 Artis 装配层统一管理画布层级。 */
+    get layerElement(): HTMLElement;
+    /** 按注册的 cardType 动态解析卡片 HTML。 */
+    resolveHTML(item: CardItem): CardHTML | undefined;
+    /** 从实例级卡片注册表解析类型配置。 */
+    resolveTypeConfig(item: CardItem): CardTypeConfig | undefined;
+    /** 重新解析并挂载指定卡片的 HTML。 */
+    refresh(id: string): boolean;
+    /** 向卡片内容注册的 patch handler 派发增量更新。 */
+    patch(id: string, patch: unknown): boolean;
+    /** 获取 HTML 卡片 iframe window。 */
+    getWindow(id: string): Window | null | undefined;
+    /** 向 HTML 卡片 iframe 派发跨文档事件。 */
+    dispatchEvent(id: string, type: string, detail?: unknown): boolean;
+    private invalidateCardHTML;
+    /**
+     * 订阅宿主事件并返回清理函数列表
+     */
+    private initEvents;
+    /**
+     * 在容器上绑定鼠标事件，使用捕获阶段
+     */
+    private initDOMEvents;
+    /**
+     * 双击进入卡片编辑，已处于编辑目标内部时忽略
+     * @param event 鼠标事件
+     */
+    private handleContainerDoubleClick;
+    /**
+     * 在编辑态外按下鼠标时退出编辑
+     * @param event 鼠标事件
+     */
+    private handleContainerMouseDown;
+    private selectHTMLInteractionCard;
+    /**
+     * 悬停态切换时同步可交互元素的指针事件
+     * @param event 鼠标事件
+     */
+    private handleContainerMouseMove;
+    /**
+     * 鼠标离开容器时清除悬停态
+     */
+    private handleContainerMouseLeave;
+    private isMouseLeaveWithinContainer;
+    private handleContainerContextMenu;
+    private isHTMLContextMenuEvent;
+    /**
+     * 视口被外部改变时使保存的恢复视口失效
+     */
+    private handleViewportTransform;
+    /**
+     * 主渲染流程：刷新帧与卡片覆盖层，清理不可见项并同步堆叠顺序
+     */
+    private render;
+    /**
+     * 按顺序同步根级元素与各帧内子元素的堆叠层级
+     * @param items 全部画布项
+     * @param frameByChildId 卡片所属帧映射
+     * @param visibleCardIds 当前可见卡片集合
+     */
+    private syncOverlayOrder;
+    private getOrCreateSelectionLayer;
+    /**
+     * 渲染可见帧覆盖层并清理消失的帧，返回子卡片到所属帧的映射
+     * @param items 全部画布项
+     * @param layer 覆盖层根节点
+     * @returns 子卡片 ID 到帧 ID 的映射
+     */
+    private renderFrameOverlays;
+    /**
+     * 获取或创建帧覆盖层元素
+     * @param id 帧 ID
+     * @param layer 覆盖层根节点
+     * @returns 帧覆盖层 DOM
+     */
+    private getOrCreateFrameOverlay;
+    /**
+     * 获取或创建卡片覆盖层元素，必要时迁移父节点
+     * @param id 卡片 ID
+     * @param parent 父节点
+     * @param elements 元素缓存表
+     * @returns 卡片覆盖层 DOM
+     */
+    private getOrCreateOverlay;
+    private getOrCreateSelectionOverlay;
+    private syncOverlaySelection;
+    private getSelectionBoxShadow;
+    private getPreSelectionBoxShadow;
+    /**
+     * 通过事件命中点反查最上层的可双击卡片
+     * @param event 鼠标事件
+     * @returns 命中的卡片 ID 或 undefined
+     */
+    private getHTMLCardIdByEvent;
+    /**
+     * 判断事件是否落在壳层可交互元素上，返回对应卡片 ID
+     * @param event 鼠标事件
+     * @returns 命中的卡片 ID 或 undefined
+     */
+    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;
+    /**
+     * 将事件客户端坐标转换为覆盖层相对坐标
+     * @param event 鼠标事件
+     * @returns 覆盖层局部坐标
+     */
+    private getLayerPoint;
+    /**
+     * 获取或创建内容容器与缩放容器并维持父子关系
+     * @param id 卡片 ID
+     * @param overlay 卡片覆盖层
+     * @returns 内容容器 DOM
+     */
+    private getOrCreateContentOverlay;
+    /**
+     * 创建内容缩放容器 DOM
+     * @param id 卡片 ID
+     * @returns 缩放容器 DOM
+     */
+    private createContentScaleOverlay;
+    /**
+     * 按卡片尺寸同步缩放与内容容器尺寸，无效尺寸跳过
+     * @param id 卡片 ID
+     * @param width 卡片宽度
+     * @param height 卡片高度
+     */
+    private syncContentScale;
+    private requestAutoHeightFromIframes;
+    /**
+     * 根据编辑态与悬停态切换各层与可交互元素指针事件
+     * @param id 卡片 ID
+     */
+    private syncContentInteraction;
+    private syncContentInteractionZones;
+    private clearContentInteractionState;
+    /**
+     * 同步壳层与编辑态可交互元素的指针事件和数据属性
+     * @param id 卡片 ID
+     * @param contentOverlay 内容容器
+     * @param isEditing 是否处于编辑态
+     */
+    private syncShellInteraction;
+    /**
+     * 进入指定卡片编辑态，必要时调整视口并记录恢复信息
+     * @param id 卡片 ID
+     */
+    private enterEditing;
+    private isEditableCard;
+    /**
+     * 退出当前编辑态，可控制是否恢复视口
+     * @param options restoreZoom 设为 false 时不恢复视口
+     */
+    private exitEditing;
+    /**
+     * 计算使卡片居中放大的目标缩放，视口不可用时返回 undefined
+     * @param box 卡片包围盒
+     * @param currentZoom 当前视口缩放
+     * @returns 目标缩放值或 undefined
+     */
+    private getEditingFitZoom;
+    /**
+     * 判断事件目标是否落在指定卡片覆盖层内部
+     * @param id 卡片 ID
+     * @param event 鼠标事件
+     * @returns 是否在覆盖层内
+     */
+    private isEventInsideOverlay;
+    /**
+     * 重置覆盖层内容并挂载壳层与内容，注册清理函数
+     * @param id 卡片 ID
+     * @param overlay 卡片覆盖层
+     * @param html 卡片 HTML 描述
+     */
+    private renderOverlayHTML;
+    private observeContentInteractionZones;
+    private createPatchContext;
+    private applyHTMLRootConfig;
+    private makeSelectionOverlayTransparent;
+    /**
+     * 按内容类型分发渲染到内联、DOM 或文档模式
+     * @param overlay 内容容器
+     * @param content 卡片 HTML 内容
+     * @param options 自动高度相关参数
+     * @returns 渲染清理函数或 undefined
+     */
+    private renderOverlayContent;
+    /**
+     * 将多个清理函数组合为单个清理函数，全为空时返回 undefined
+     * @param cleanups 待组合的清理函数
+     * @returns 组合后的清理函数或 undefined
+     */
+    private chainCleanups;
+    /**
+     * 清理指定卡片的内容、自动高度监听及相关状态
+     * @param id 卡片 ID
+     */
+    private cleanupOverlayContent;
+    /**
+     * 移除卡片覆盖层及其内容并清理缓存
+     * @param id 卡片 ID
+     */
+    private removeOverlay;
+    /**
+     * 同步自动高度监听状态，禁用时清理
+     * @param id 卡片 ID
+     * @param enabled 是否启用自动高度
+     */
+    private syncAutoHeight;
+    private ensureAutoHeightMode;
+    /**
+     * 为卡片挂载 Resize/Mutation 观察与 iframe 消息监听，返回清理函数
+     * @param id 卡片 ID
+     * @returns 注销观察与监听的清理函数
+     */
+    private createAutoHeightObserver;
+    /**
+     * 调度一帧后的高度测量，已在队列中则跳过
+     * @param id 卡片 ID
+     */
+    private scheduleAutoHeightMeasure;
+    /**
+     * 测量卡片自然高度并应用，未启用或无挂载时清理
+     * @param id 卡片 ID
+     */
+    private measureAutoHeight;
+    /**
+     * 计算内容容器的自然高度，优先取 iframe 与子元素高度
+     * @param element 内容挂载元素
+     * @returns 自然内容高度
+     */
+    private getNaturalContentHeight;
+    /**
+     * 计算 iframe 内文档的自然高度
+     * @param iframe iframe 元素
+     * @returns 高度或 undefined
+     */
+    private getIframeNaturalContentHeight;
+    /**
+     * 取直接子元素底部最大偏移作为高度
+     * @param element 容器元素
+     * @returns 子元素最大底部偏移
+     */
+    private getChildrenNaturalHeight;
+    /**
+     * 清理自动高度观察与待执行测量帧
+     * @param id 卡片 ID
+     */
+    private cleanupAutoHeight;
+    /**
+     * 应用自然高度到卡片项，忽略非启用项与无效或微小变化
+     * @param id 卡片 ID
+     * @param height 测得的高度
+     */
+    private applyAutoHeight;
+    private setAutoHeightStreamPhase;
+    private isAutoHeightStreamActive;
+    private getAutoHeightItemHeight;
+    private isAutoHeightEnabled;
+    private isAutoScaleEnabled;
+}

package/dist/helper/html-overlay/html-viewport-style.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 为卡片 HTML 文档注入视口样式，已有 head 则插入其内，无 head 但有 html 则补建 head，否则包装为完整文档结构。
+ * @param html 原始 HTML 文档片段或完整文档字符串。
+ * @returns 注入视口样式后的 HTML 字符串。
+ */
+export declare function withCardHTMLViewportStyle(html: string): string;

package/dist/helper/html-overlay/index.d.ts

@@ -0,0 +1 @@
+export { HTMLCardService } from './html-card-service';

package/dist/helper/html-overlay/inline-script-json.d.ts

@@ -0,0 +1 @@
+export declare function serializeInlineScriptJson(value: unknown): string;

package/dist/helper/html-overlay/mime-utils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 根据路径扩展名推断 MIME 类型，未匹配时回退为 text/plain。
+ * @param path 资源路径，按扩展名映射 MIME 类型。
+ * @returns 对应的 MIME 类型字符串。
+ */
+export declare function getMimeType(path: string): string;
+/**
+ * 将源文本内容编码为指定 MIME 类型的 data URL。
+ * @param source 待编码的源文本内容。
+ * @param mimeType 内容的 MIME 类型。
+ * @returns 形如 data:{mimeType};charset=utf-8,{encoded} 的 data URL。
+ */
+export declare function createDataUrl(source: string, mimeType: string): string;

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

@@ -0,0 +1,30 @@
+import { Box2 } from '@vvfx/gizmo';
+export type CardOverlayBoxStyle = {
+    left: string;
+    top: string;
+    width: string;
+    height: string;
+    contentWidth: number;
+    contentHeight: number;
+    transform: string;
+};
+/**
+ * 根据卡片叠加盒子的四角与目标宽高计算 CSS 定位样式，四角齐全且尺寸有效时用矩阵变换，否则退化为边界框定位。
+ * @param box 卡片叠加盒子，提供四角与最小/最大边界。
+ * @param width 目标渲染宽度，需大于 0 才走矩阵路径。
+ * @param height 目标渲染高度，需大于 0 才走矩阵路径。
+ * @param offsetX 横向偏移量，用于平移坐标原点，默认 0。
+ * @param offsetY 纵向偏移量，用于平移坐标原点，默认 0。
+ * @returns 包含 left/top/width/height/transform 的样式对象。
+ */
+export declare function getCardOverlayBoxStyle(box: Box2, width: number, height: number, offsetX?: number, offsetY?: number): CardOverlayBoxStyle;
+/**
+ * 判断点是否落在卡片叠加盒子内，四角齐全时用射线法判定多边形包含，否则用轴对齐边界框判定。
+ * @param box 卡片叠加盒子。
+ * @param point 待判定的二维点。
+ * @returns 点在盒子内返回 true。
+ */
+export declare function isPointInCardOverlayBox(box: Box2, point: {
+    x: number;
+    y: number;
+}): boolean;

package/dist/helper/html-overlay/path-utils.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 规范化路径，处理 . 与 .. 段并折叠冗余分隔，返回无头尾斜杠的相对路径形式。
+ * @param path 待规范化的路径字符串。
+ * @returns 规范化后的路径。
+ */
+export declare function normalizePath(path: string): string;
+/**
+ * 取路径的目录部分，先规范化再截取最后一个分隔符之前的内容，无分隔符返回空串。
+ * @param path 待提取目录的路径字符串。
+ * @returns 目录路径，根或仅文件名时返回空串。
+ */
+export declare function dirname(path: string): string;
+/**
+ * 相对基准路径解析目标路径，绝对路径直接规范化，否则相对基准路径的目录拼接后规范化。
+ * @param path 待解析的目标路径。
+ * @param fromPath 解析基准路径，提供相对解析的参照目录。
+ * @returns 解析后的绝对形式路径字符串。
+ */
+export declare function resolvePath(path: string, fromPath: string): string;
+/**
+ * 将资源路径拆分为纯路径与查询/锚点后缀两部分。
+ * @param path 含可能的 query 或 hash 后缀的资源路径。
+ * @returns 包含纯路径 path 与后缀 suffix 的对象，无后缀时 suffix 为空串。
+ */
+export declare function splitResourcePath(path: string): {
+    path: string;
+    suffix: string;
+};
+/**
+ * 判断资源 URL 是否需要改写，命中协议头、//、# 开头等绝对或锚点形式时跳过改写。
+ * @param url 待判定的资源 URL。
+ * @returns 需要改写返回 true。
+ */
+export declare function shouldRewriteResource(url: string): boolean;

package/dist/helper/html-overlay/runtime-context.d.ts

@@ -0,0 +1,2 @@
+export declare function createCardHTMLRuntimeId(cardId?: string): string;
+export declare function withCardHTMLRuntimeContext(html: string, runtimeId: string): string;

package/dist/helper/html-overlay/shell-runtime.d.ts

@@ -0,0 +1,13 @@
+import type { CardHTMLContent, CardHTMLRenderCleanup, CardHTMLShellContent } from '../../core';
+export type MountedHTMLShell = {
+    contentContainer: HTMLElement;
+    cleanup?: CardHTMLRenderCleanup;
+};
+/**
+ * 挂载卡片 HTML 壳层；未提供 shell 时直接使用容器作为内容容器
+ * @param container 宿主容器
+ * @param content 卡片 HTML 内容
+ * @param shell 可选的壳层描述
+ * @returns 挂载结果，含内容容器与清理函数
+ */
+export declare function mountHTMLShell(container: HTMLElement, content: CardHTMLContent, shell?: CardHTMLShellContent): MountedHTMLShell;