@vvfx/artis 0.0.1-alpha.0

package/dist/core/quality/stability-monitor/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 稳定性信号
+ *
+ * - CONTEXT_LOST   WebGL 上下文丢失（P0 瞬态）：engine opt-in 自恢复，降权后随 reportContextRestored 恢复
+ * - ERROR_RATE     出错率超阈值（错误/分钟）
+ * - ERROR_CLUSTER  同因反复（同 errorKey 1 分钟窗口内 ≥N 次）
+ * - MEMORY_GROWTH  可选：内存增长（Chrome performance.memory 受限，尽力而为，初版不实现）
+ * - FPS_DROP       可选：持续掉帧（rAF 采样，初版不实现）
+ */
+export declare enum StabilitySignal {
+    CONTEXT_LOST = "context-lost",
+    ERROR_RATE = "error-rate",
+    ERROR_CLUSTER = "error-cluster",
+    MEMORY_GROWTH = "memory-growth",
+    FPS_DROP = "fps-drop"
+}
+/**
+ * 稳定性信号标识：枚举常量 + 容纳外部自定义信号
+ *
+ * 用 `Enum | (string & {})` 形式：保留 IDE 补全 + 允许业务方扩展自有信号。
+ */
+export type StabilitySignalToken = StabilitySignal | (string & {});
+/** 健康度：0 完全崩坏 ~ 1 健康 */
+export type HealthState = {
+    /** 0~1，1 为完全健康 */
+    score: number;
+    /** 当前触发的信号列表 */
+    signals: StabilitySignal[];
+    /** 触发原因摘要，供宿主展示 */
+    reasons: string[];
+    /** 墙钟时间戳（Date.now） */
+    timestamp: number;
+    /**
+     * 建议动作：context-lost→'recreate'；其余缺省 'none'。
+     * 宿主据此无歧义决策恢复（取代靠 signals 字符串硬判）。
+     */
+    recommendedAction?: RecommendedActionToken;
+};
+/**
+ * 稳定性建议动作：随健康度外达，告诉宿主建议如何恢复。
+ *
+ * - recreate  context-lost 标记的建议动作。当前 effects Player 已 opt-in 自恢复（doNotHandleContextLost:false），
+ *             engine 在 webglcontextrestored 上就地重建 GPU 资源——context-lost 为瞬态抖动、随 reportContextRestored 恢复，
+ *             上层 enableAutoRecreate 自动走轻同步而非重建。'recreate' 仅供宿主在自恢复失败时手动调 artis.recreate() 兜底。
+ * - reload    资源/页面级刷新（SDK 不内建，提示宿主）
+ * - none      无需动作（restore 后 reportContextRestored 重算得出）
+ */
+export type RecommendedAction = 'recreate' | 'reload' | 'none';
+/** 建议动作标识：枚举值 + 容纳外部自定义（开放扩展点） */
+export type RecommendedActionToken = RecommendedAction | (string & {});
+/** 稳定性上报信息（即一次健康度变化快照） */
+export type StabilityReport = HealthState;
+/** 健康度变化回调 */
+export type StabilityMonitorCallback = (state: HealthState) => void;
+/**
+ * StabilityMonitor 依赖注入接口
+ *
+ * - now：时间源，生产用 () => Date.now()
+ * - onError：可选，订阅 error-monitor 节流前原始错误流；缺省时 error 类信号不工作
+ *           返回取消订阅函数
+ */
+export type StabilityMonitorDeps = {
+    now: () => number;
+    onError?: (cb: (info: {
+        errorKey: string;
+        timestamp: number;
+        phase: string;
+    }) => void) => () => void;
+};

package/dist/core/renderer/background-controller.d.ts

@@ -0,0 +1,56 @@
+import type { ArtisBackgroundConfig, Disposable } from '../types';
+import type { ViewportState } from '../service';
+/**
+ * BackgroundController - 背景控制器
+ *
+ * 职责：
+ * 1. 封装 BackgroundManager
+ * 2. 接收 ArtisBackgroundConfig（联合类型），自动映射为对应操作
+ * 3. 跟随 ViewportManager 的 transform 更新背景位置
+ */
+export declare class BackgroundController implements Disposable {
+    private _manager;
+    private _currentConfig;
+    /**
+     * 创建 BackgroundController 实例，内部初始化 BackgroundManager
+     */
+    constructor();
+    /**
+     * 绑定容器
+     *
+     * @param container 背景挂载的 DOM 容器
+     */
+    attach(container: HTMLElement): void;
+    /**
+     * 解绑容器
+     */
+    detach(): void;
+    /**
+     * 获取当前背景配置
+     */
+    get currentConfig(): ArtisBackgroundConfig | undefined;
+    /**
+     * 应用背景配置（根据联合类型自动分发）
+     *
+     * @param config 背景配置（颜色/图片/棋盘/点阵）
+     */
+    applyConfig(config: ArtisBackgroundConfig): void;
+    /**
+     * 跟随视口变换更新背景位置
+     *
+     * @param state 视口状态（缩放、平移、内容缩放）
+     * @param shift 背景位移量
+     */
+    updateTransform(state: ViewportState, shift: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * 重置背景位置
+     */
+    reset(): void;
+    /**
+     * 销毁
+     */
+    dispose(): void;
+}

package/dist/core/renderer/index.d.ts

@@ -0,0 +1,5 @@
+export { Renderer } from './renderer';
+export type { RendererOptions } from './renderer';
+export { PlayerAdapter } from './player-adapter';
+export type { PlayerAdapterEventMap, PlayerAdapterOptions } from './player-adapter';
+export { BackgroundController } from './background-controller';

package/dist/core/renderer/player-adapter.d.ts

@@ -0,0 +1,129 @@
+import { Composition, EventEmitter, Player, spec } from '../../shared';
+import type { Disposable } from '../types';
+/**
+ * PlayerAdapter 事件类型
+ */
+export type PlayerAdapterEventMap = {
+    'sceneLoaded': [composition: Composition];
+    'progress': [info: {
+        duration: number;
+        time: number;
+        end: boolean;
+        paused: boolean;
+    }];
+    'contextLost': [];
+    'contextRestored': [];
+};
+/**
+ * PlayerAdapter 初始化选项
+ */
+export type PlayerAdapterOptions = {
+    width: number;
+    height: number;
+    pixelRatio?: number;
+};
+/**
+ * PlayerAdapter - Player 封装层
+ *
+ * 职责：
+ * 1. 创建 playerContainer DOM 子元素
+ * 2. 初始化 GE Player 实例
+ * 3. 管理 Player 生命周期（resize / dispose）
+ * 4. 提供 loadScene / switchScene 方法
+ * 5. 监听 Player update 事件，向外分发 progress
+ *
+ * context-lost：构造传 `doNotHandleContextLost:false`，GE engine 在 webglcontextrestored 上
+ * 就地重建全部 GPU 资源（含 artis 自建 Texture.fromImage 纹理），Player/composition 存活，
+ * 本层只向外 emit contextLost/contextRestored，由上层做轻同步（见 BaseArtis._onContextRestored）。
+ */
+export declare class PlayerAdapter extends EventEmitter<PlayerAdapterEventMap> implements Disposable {
+    player: Player;
+    playerContainer: HTMLElement;
+    /** 容器尺寸缓存（_buildPlayerContainer 复用） */
+    private _containerWidth;
+    private _containerHeight;
+    /** 像素比缓存（Player 构造复用） */
+    private readonly _pixelRatio;
+    private _currentScene;
+    /** 当前业务场景合成；Player 中还可能存在 Gizmo 等宿主自建 overlay 合成。 */
+    private _sceneComposition;
+    private _playing;
+    private _disposed;
+    private _time;
+    /** Player 构造参数（构造期缓存，仅 new Player 用；context-lost 不再重建故无复用场景） */
+    private _playerOptions;
+    /**
+     * 创建 PlayerAdapter，构建 playerContainer 并初始化 GE Player 实例
+     *
+     * @param parentContainer 外层父容器，playerContainer 将挂载其下
+     * @param options 初始化选项（宽高、像素比）
+     */
+    constructor(parentContainer: HTMLElement, options: PlayerAdapterOptions);
+    /**
+     * 构造 playerContainer DOM 节点（样式固定）。
+     */
+    private _buildPlayerContainer;
+    /**
+     * 仅销毁底层 Player 实例（不动 playerContainer DOM）。供 dispose 复用。
+     */
+    private _disposePlayerOnly;
+    /** 当前场景 */
+    get currentScene(): spec.JSONScene | undefined;
+    /** 是否正在播放 */
+    get playing(): boolean;
+    /**
+     * 设置播放状态标记
+     *
+     * @param value 是否播放
+     */
+    set playing(value: boolean);
+    /** 当前播放时间 */
+    get time(): number;
+    /**
+     * 设置当前播放时间
+     *
+     * @param value 时间值
+     */
+    set time(value: number);
+    /**
+     * 加载场景并播放
+     *
+     * 加载前仅释放旧业务 composition runtime（VFXItem/component/object 树），避免切场景累积；
+     * Player 中由宿主创建的 Gizmo 等 overlay composition 保持存活。
+     * @param scene 待加载的场景 JSON
+     */
+    loadScene(scene: spec.JSONScene): Promise<void>;
+    /**
+     * 切换场景（暂停旧场景 → 卸载 → 加载新场景）
+     * @param scene 待切换的目标场景 JSON
+     */
+    switchScene(scene: spec.JSONScene): Promise<void>;
+    /**
+     * 暂停播放
+     */
+    pause(): void;
+    /**
+     * 恢复播放
+     */
+    resume(): void;
+    /**
+     * 设置播放进度
+     * @param time 目标时间
+     */
+    seek(time: number): void;
+    /**
+     * 适配容器尺寸变化
+     * @param width 目标宽度
+     * @param height 目标高度
+     */
+    resize(width: number, height: number): void;
+    /**
+     * 销毁
+     */
+    dispose(): void;
+    /**
+     * 绑定 Player 的 update / webglcontextlost / webglcontextrestored 事件
+     * 向外分发进度与上下文丢失/恢复（doNotHandleContextLost:false 下 engine 自重建 GPU 资源）。
+     */
+    private setupPlayerEvents;
+}

package/dist/core/renderer/renderer.d.ts

@@ -0,0 +1,134 @@
+import { Player, spec } from '../../shared';
+import { Vector2 } from '@vvfx/gizmo';
+import { PlayerAdapter } from './player-adapter';
+import { BackgroundController } from './background-controller';
+import { type ArtisBackgroundConfig, type Disposable, type PagePreferences } from '../types';
+import { type ViewportState } from '../service';
+/**
+ * Renderer 初始化选项
+ */
+export type RendererOptions = {
+    /** 背景配置 */
+    background?: ArtisBackgroundConfig;
+    /** Player 像素比 */
+    pixelRatio?: number;
+    /** 页面配置 */
+    pagePreferences?: PagePreferences;
+    /**
+     * 编辑后 goto 的 playing 策略：true=gotoAndPlay（Artis 默认，编辑后继续播放），
+     * false=gotoAndStop（SceneArtis 默认，保 stop 态可编辑）。作为「编辑后刷新渲染」的
+     * 统一播放策略真源；服务层经 {@link Renderer#gotoEdit} 调用，不再各自持有副本。
+     */
+    editGotoPlaying?: boolean;
+};
+/**
+ * Renderer - 渲染管线编排
+ *
+ * 职责：
+ * 1. 协调 PlayerAdapter + BackgroundController 的调用顺序
+ * 2. 提供 run() 方法作为入口（加载场景 + 初始渲染）
+ * 3. 暴露 applyViewportToPlayer 供 ViewService 驱动视口变换
+ */
+export declare class Renderer implements Disposable {
+    readonly playerAdapter: PlayerAdapter;
+    readonly background: BackgroundController;
+    private _container;
+    private _disposed;
+    /** 编辑后 goto 的 playing 策略（gotoEdit 用）。Artis 默认 true，SceneArtis 默认 false。 */
+    private readonly _editGotoPlaying;
+    /**
+     * 创建 Renderer 实例，初始化 Player 适配器与背景控制器并应用初始背景
+     *
+     * @param container 渲染挂载的 DOM 容器
+     * @param options 渲染初始化选项（背景、像素比、页面配置）
+     */
+    constructor(container: HTMLElement, options?: RendererOptions);
+    /**
+     * 加载场景数据并启动渲染
+     *
+     * @param input 场景数据或场景 JSON 的 URL，缺省时使用内置基础场景
+     * @param containerSize 容器尺寸，缺省时取当前容器实际尺寸
+     */
+    run(input?: spec.JSONScene | string, containerSize?: spec.vec2): Promise<void>;
+    /** 底层 Player 实例 */
+    get player(): Player;
+    /** 当前是否处于播放状态 */
+    get playing(): boolean;
+    /**
+     * 设置播放状态并跳转到当前时间
+     *
+     * @param value 是否播放
+     */
+    set playing(value: boolean);
+    /** 当前播放时间 */
+    get time(): number;
+    /**
+     * 设置当前播放时间
+     *
+     * @param value 时间值
+     */
+    set time(value: number);
+    /**
+     * 销毁
+     */
+    dispose(): void;
+    /**
+     * 将视口状态应用到 Player 相机（由 ViewService 的 change 事件驱动）
+     *
+     * @param state 视口状态（缩放、平移、内容缩放）
+     * @param containerSize 容器像素尺寸，用于 NDC 换算
+     */
+    applyViewportToPlayer(state: ViewportState, containerSize: Vector2): void;
+    /**
+     * 解析场景输入，字符串按 URL 拉取 JSON，对象直接返回
+     *
+     * @param sceneInput 场景数据或场景 JSON 的 URL
+     * @returns 解析后的场景数据
+     */
+    private resolveScene;
+    /**
+     * 跳转到指定时间
+     *
+     * @param time 目标时间
+     * @param playing 是否继续播放（true=gotoAndPlay, false=gotoAndStop）
+     * @param ignoreMediaPlayState 是否忽略视频/特效元素的播放状态，默认 false。
+     *   当为 true 时，goto 后保持视频和特效元素原有的播放/暂停状态不变。
+     */
+    goto(time: number, playing?: boolean, ignoreMediaPlayState?: boolean): void;
+    /**
+     * 编辑后刷新渲染：按 {@link RendererOptions.editGotoPlaying} 策略 goto 当前/指定时间。
+     *
+     * 作为「编辑后渲染刷新」的统一入口，取代此前 ItemService/Frame/Asset/Sync 各自持有
+     * `_editGotoPlaying` 副本再 `goto(time, _editGotoPlaying)` 的分散写法（播放策略单一真源）。
+     *
+     * @param time 目标时间，缺省取当前 `renderer.time`
+     */
+    gotoEdit(time?: number): void;
+    /**
+     * 捕获所有视频和特效元素的播放状态
+     *
+     * @param player Effects Player 实例
+     * @returns 元素实例 ID → 是否正在播放 的映射
+     */
+    private captureMediaPlayStates;
+    /**
+     * 恢复视频和特效元素的播放状态
+     *
+     * @param player Effects Player 实例
+     * @param states 元素实例 ID → 是否正在播放 的映射
+     */
+    private restoreMediaPlayStates;
+    /**
+     * 递归遍历所有 VFXItem
+     *
+     * @param items 待遍历的元素列表
+     * @param callback 每个元素的回调
+     */
+    private traverseItems;
+    /**
+     * 适配容器尺寸变化并通知 Player 重排
+     *
+     * @param size 新的容器尺寸，缺省时取当前容器实际尺寸
+     */
+    resize(size?: Vector2): void;
+}

package/dist/core/service/frame-service.d.ts

@@ -0,0 +1,116 @@
+import { FrameManager } from '@vvfx/gizmo';
+import { type LayoutInfo } from '../types';
+import { type Store } from '../store';
+import { type Renderer } from '../renderer';
+import { type ItemService } from './item-service';
+import { type ViewService } from './view-service';
+/**
+ * FrameService - 画板（Frame）关系与布局服务
+ *
+ * 职责：管理画板子元素的移入/移出、自动布局（Shelf 算法）、布局模式切换、尺寸刷新等。
+ * 采用组合模式：持有 ItemService 引用，复用其 getArtisItem / findPlayerItemById /
+ * collectItemsWithChildren 等公共方法与基础设施（Store / Renderer 由构造注入）。
+ *
+ * 画板「创建」相关逻辑（createFrameItemInternal / loadFrameAsset）仍留在 ItemService，
+ * 因其与 createItem 异步资源加载链路强耦合。
+ */
+export declare class FrameService {
+    private _itemService;
+    private _store;
+    private _renderer;
+    private _viewService;
+    private _frameManager;
+    /**
+     * 注入 ItemService 与基础设施依赖
+     * @param itemService 元素门面服务
+     * @param store 数据存储
+     * @param renderer 渲染管线
+     * @param viewService 视口服务
+     * @param frameManager Frame 运行时模块
+     */
+    constructor(itemService: ItemService, store: Store, renderer: Renderer, viewService: ViewService, frameManager: FrameManager);
+    /**
+     * 修改画板布局模式，刷新背景色；切到 auto 时立即执行一次自动布局
+     * @param id 画板 ID
+     * @param layoutMode 布局模式 'auto' | 'free'
+     */
+    updateFrameLayoutMode(id: string, layoutMode: 'auto' | 'free'): void;
+    /**
+     * 计算「单元素行列变更」后的完整 layoutInfos（纯计算，不修改任何数据）
+     *
+     * 拖拽单个元素改变行列时，会联动调整同行/同列其它元素的列号。
+     * 此方法基于当前 Frame.layoutInfos 克隆出一份新的完整 layoutInfos 并返回，
+     * 供 FrameLayoutCommand 作为整份快照入参使用。
+     *
+     * @param frameId 画板 ID
+     * @param draggedItemId 被拖拽元素 ID
+     * @param fromRow 起始行
+     * @param fromColumn 起始列
+     * @param toRow 目标行
+     * @param toColumn 目标列
+     * @returns 完整的新 layoutInfos；Frame 或被拖拽元素不存在时返回 undefined
+     */
+    computeLayoutInfosAfterReorder(frameId: string, draggedItemId: string, fromRow: number, fromColumn: number, toRow: number, toColumn: number): Record<string, LayoutInfo> | undefined;
+    /**
+     * 调整 Frame 内元素行列顺序：写回新 layoutInfos 并基于其重新自动排布
+     * @param frameId 画板 ID
+     * @param draggedItemId 被拖拽元素 ID
+     * @param fromRow 起始行
+     * @param fromColumn 起始列
+     * @param toRow 目标行
+     * @param toColumn 目标列
+     */
+    adjustFrameLayoutOrder(frameId: string, draggedItemId: string, fromRow: number, fromColumn: number, toRow: number, toColumn: number): void;
+    /**
+     * 修改画板子元素
+     * @param id 画板 ID
+     * @param children 子元素 ID 列表
+     */
+    updateFrameChildren(id: string, children: string[]): void;
+    /**
+     * 将元素移动到 Frame 中（数据层 + Player 层 + transform 补偿一体化）。
+     *
+     * 统一处理批量移入语义（需求 3.a）：
+     * - 仅记**顶层**成员到 `Frame.children`；组整体移入时其内部子元素**不**被改（修问题 1）。
+     * - 「父在批次内」的元素跳过（3.a.ⅱ：由其父组携带移动，当前元素不变）。
+     * - 「父是不在批次内的 Group」的元素：先从该 Group.children 移除（取消认父），再认父为画板（3.a.ⅰ）。
+     * - 所有 Player 层 reparent 均用 `getItemTransformUnderParent` 做世界 transform 烘焙，保持画布位置不变。
+     *
+     * @param itemIds 要移动的元素ID列表（elementId）
+     * @param frameId 目标 Frame ID（elementId）
+     */
+    moveItemsToFrame(itemIds: string[], frameId: string): void;
+    /**
+     * 将元素从 Frame 移出到主场景根节点
+     *
+     * 父子关系保留规则：
+     * - Group 整组移出：只改 Group.parentId = undefined，内部子元素 parentId 保持不变
+     * - 单个元素脱离 Group 后移出：先从 Group.children 中移除，再移到根节点
+     * - Player 层只对顶层元素 setParent（子元素在场景图中自动跟随）
+     *
+     * @param itemIds 要移出的元素 ID 列表
+     */
+    moveItemsOutOfFrame(itemIds: string[]): void;
+    /**
+     * 对 Frame 内子元素应用 FrameManager 计算出的自动布局结果。
+     * @param frameId 画板 ID
+     */
+    applyFrameAutoLayout(frameId: string): void;
+    /**
+     * 修改画板元素大小（仅 Player + ArtisItem，不涉及 JSON 层）
+     *
+     * 同步更新：
+     * 1. ArtisItem.property.width/height
+     * 2. Player 层 Frame 控制器（空节点）的 transform.size
+     * 3. 底层预合成（subCompositionItem）的 scale —— 按新世界尺寸重新计算 cameraScale
+     *
+     * @param id Frame 元素 ID
+     * @param size 目标大小 [width, height]（像素）
+     */
+    updateFrameItemSize(id: string, size: [number, number]): void;
+    /**
+     * 刷新 Frame 子元素列表：从 Player 层父子关系反向同步到 Frame.property.children
+     * @param frameId 画板 ID
+     */
+    refreshFrameChildren(frameId: string): void;
+}

package/dist/core/service/index.d.ts

@@ -0,0 +1,9 @@
+export { ItemService } from './item-service';
+export { InteractionService } from './interaction-service';
+export { createViewportProvider, createCameraProvider, createItemTransformProvider, } from './interaction-providers';
+export type { ViewportProvider, CameraProvider, ItemTransformProvider, InteractionConfig, } from './interaction-service';
+export { ViewService } from './view-service';
+export type { ViewportState, ViewServiceEventMap, ViewServiceOptions } from './view-service';
+export { SceneDataAssembler } from './scene-data-assembler';
+export type { SceneDataAssemblerDeps, ArtisItemTypeTable } from './scene-data-assembler';
+export { JsonSceneSyncService, serializeArtisItemToJSON } from './json-scene-sync-service';

package/dist/core/service/interaction-providers.d.ts

@@ -0,0 +1,20 @@
+import type { ViewportProvider, CameraProvider, ItemTransformProvider } from './interaction-service';
+import type { ViewService } from './view-service';
+import type { Renderer } from '../renderer';
+/**
+ * 视口数据提供者：返回容器尺寸 + 当前 zoom / translation。
+ *
+ * @param container 画布 DOM 容器（offsetWidth/Height 取真实布局尺寸）
+ * @param viewService 视口服务（提供 effectiveZoom 与 translation）
+ */
+export declare function createViewportProvider(container: HTMLElement, viewService: ViewService): ViewportProvider;
+/**
+ * 相机数据提供者：从激活组合的 camera 取 VP / 逆 VP / View 矩阵。
+ * 无激活组合或相机时返回 undefined。
+ */
+export declare function createCameraProvider(renderer: Renderer): CameraProvider;
+/**
+ * 元素变换提供者：按 instanceId 在组合树中查找节点，返回其世界矩阵。
+ * 节点缺失或无 transform 时返回 undefined。
+ */
+export declare function createItemTransformProvider(renderer: Renderer): ItemTransformProvider;