@vvfx/artis 0.0.1-alpha.0

package/dist/core/item/types.d.ts

@@ -0,0 +1,158 @@
+import type { SpriteItemProperty, TextItemProperty, VideoItemProperty, GeneratorItemProperty, GroupItemProperty, EffectsItemProperty, FrameItemProperty, CardItemProperty } from '../types';
+import { spec } from '../../shared';
+/**
+ * ArtisItem 基础选项接口
+ * 支持扩展属性，允许添加任意额外属性
+ */
+export type ArtisItemOptions = {
+    /**
+     * 元素ID
+     */
+    id: string;
+    /**
+     * Player 维度 VFXItem ID（运行时 GUID，不落盘——决策 D2）。
+     * 未传时构造兜底回退到 id（assembler 导入路径依赖）；createXxx / loadEffectsAsset
+     * 创建 VFXItem 后取 getInstanceId() 回填到 ArtisItem.vfxItemId。
+     */
+    vfxItemId?: string;
+    /**
+     * 元素名称
+     */
+    name: string;
+    /**
+     * 父节点ID
+     */
+    parentId?: string;
+    /**
+     * 子元素ID列表
+     */
+    children?: string[];
+    /**
+     * 元素生命周期
+     */
+    duration?: number;
+    /**
+     * 元素生命周期延时
+     */
+    delay?: number;
+    /**
+     * 可视状态
+     */
+    visible?: boolean;
+    /**
+     * 元素结束行为
+     */
+    endBehavior?: spec.EndBehavior;
+    /**
+     * 是否处于锁定状态
+     */
+    isLocked?: boolean;
+    /**
+     * 关键属性是否可编辑
+     */
+    isCoreEditable?: boolean;
+    /**
+     * 扩展属性存储（属性名 -> 属性值）
+     */
+    extension?: Record<string, any>;
+    /**
+     * 允许任意额外属性（用于兼容旧代码）
+     */
+    [extraProp: string]: any;
+};
+/**
+ * Sprite ArtisItem 选项
+ */
+export type SpriteItemOptions = ArtisItemOptions & {
+    /**
+     * 元素属性
+     */
+    property?: Partial<SpriteItemProperty>;
+};
+/**
+ * Text ArtisItem 选项
+ */
+export type TextItemOptions = ArtisItemOptions & {
+    /**
+     * 元素属性
+     */
+    property?: Partial<TextItemProperty>;
+};
+/**
+ * Video ArtisItem 选项
+ */
+export type VideoItemOptions = ArtisItemOptions & {
+    /**
+     * 元素属性
+     */
+    property?: Partial<VideoItemProperty>;
+};
+/**
+ * Group ArtisItem 选项（空节点/组）
+ */
+export type GroupItemOptions = ArtisItemOptions & {
+    /**
+     * 元素属性
+     */
+    property?: Partial<GroupItemProperty>;
+};
+/**
+ * Generator ArtisItem 选项（资源生成器）
+ * 支持 image 和 video 两种生成器类型
+ * 使用 GeneratorItemProperty 包含 generatorType
+ */
+export type GeneratorItemOptions = ArtisItemOptions & {
+    /**
+     * 元素属性（包含 generatorType）
+     */
+    property?: Partial<GeneratorItemProperty>;
+};
+/**
+ * Effects 特效产物 ArtisItem 选项
+ */
+export type EffectsItemOptions = ArtisItemOptions & {
+    property?: Partial<EffectsItemProperty>;
+};
+/**
+ * Frame 画板元素 ArtisItem 选项
+ */
+export type FrameItemOptions = ArtisItemOptions & {
+    /**
+     * 元素属性
+     */
+    property?: Partial<FrameItemProperty>;
+};
+/**
+ * ArtisItem 类型（独立于 spec.ItemType）
+ * 包含所有 SDK 层级的元素类型，包括虚拟类型如 generator
+ */
+export declare enum ArtisItemType {
+    SPRITE = "sprite",
+    TEXT = "text",
+    VIDEO = "video",
+    GROUP = "group",
+    GENERATOR = "generator",
+    EFFECTS = "effects",
+    FRAME = "frame",
+    CARD = "card"
+}
+/**
+ * ArtisItemType 与 spec.ItemType 的映射关系
+ */
+export declare const ArtisItemTypeToSpecItemType: Record<ArtisItemType, spec.ItemType>;
+/**
+ * Card 卡片元素 ArtisItem 选项
+ * 在 Player 中以 SpriteItem 形式渲染
+ */
+export type CardItemOptions = ArtisItemOptions & {
+    /**
+     * 元素属性（包含 cardType）
+     */
+    property?: Partial<CardItemProperty>;
+};
+/**
+ * 根据 ArtisItemType 获取对应的 spec.ItemType
+ * @param sdkItemType ArtisItem 类型
+ * @returns 对应的 spec.ItemType
+ */
+export declare function getSpecItemType(sdkItemType: ArtisItemType): spec.ItemType;

package/dist/core/item/video-item.d.ts

@@ -0,0 +1,120 @@
+import { type VideoItemProperty, type VideoItemSchema } from '../types';
+import { ArtisItemType, type VideoItemOptions } from './types';
+import { BaseItem } from './base-item';
+/**
+ * 视频元素 ArtisItem 类
+ * 支持属性扩展
+ */
+export declare class VideoItem extends BaseItem {
+    /**
+     * 元素类型
+     */
+    readonly type = ArtisItemType.VIDEO;
+    /**
+     * 元素属性
+     */
+    property: VideoItemProperty;
+    constructor(options: VideoItemOptions);
+    /**
+     * 尺寸模式：'auto'=随资源自适应，'fixed'=尺寸定死。auto→fixed 由 ItemService 在显式设尺寸时翻转。
+     */
+    get sizeMode(): 'auto' | 'fixed';
+    /**
+     * 视频地址
+     */
+    get video(): string;
+    /**
+     * 设置视频地址
+     * @param value 视频地址
+     */
+    set video(value: string);
+    /**
+     * 位置
+     */
+    get position(): [number, number];
+    /**
+     * 设置位置
+     * @param value 位置坐标 [x, y]
+     */
+    set position(value: [number, number]);
+    /**
+     * 宽度
+     */
+    get width(): number;
+    /**
+     * 设置宽度
+     * @param value 宽度
+     */
+    set width(value: number);
+    /**
+     * 高度
+     */
+    get height(): number;
+    /**
+     * 设置高度
+     * @param value 高度
+     */
+    set height(value: number);
+    /**
+     * 旋转（二维旋转角度）
+     */
+    get rotation(): number;
+    /**
+     * 设置旋转角度（二维）
+     * @param value 旋转角度
+     */
+    set rotation(value: number);
+    /**
+     * 是否静音
+     */
+    get muted(): boolean;
+    /**
+     * 设置是否静音
+     * @param state 是否静音
+     */
+    set muted(state: boolean);
+    /**
+     * 是否为透明视频（默认 false：普通视频。true 时按左右分屏 alpha 合成渲染透明视频）
+     */
+    get transparent(): boolean;
+    /**
+     * 设置是否为透明视频
+     * @param state 是否透明
+     */
+    set transparent(state: boolean);
+    /**
+     * 播放音量
+     */
+    get volume(): number;
+    /**
+     * 设置播放音量
+     * @param value 音量
+     */
+    set volume(value: number);
+    /**
+     * 播放速率
+     */
+    get playbackRate(): number;
+    /**
+     * 设置播放速率
+     * @param value 播放速率
+     */
+    set playbackRate(value: number);
+    /**
+     * 转换为 VideoItemSchema
+     * @param withParent 是否包含父节点ID
+     * @returns VideoItemSchema 对象
+     */
+    toSchema(withParent?: boolean): VideoItemSchema;
+    /**
+     * 克隆 ArtisItem
+     * @returns 新的 VideoItem 实例
+     */
+    clone(): VideoItem;
+}
+/**
+ * 类型守卫：检查是否是 VideoItem
+ * @param obj 待检查对象
+ * @returns 是否是 VideoItem 实例
+ */
+export declare function isVideoItem(obj: any): obj is VideoItem;

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

@@ -0,0 +1,11 @@
+/**
+ * core/keybinding - 快捷键系统
+ *
+ * 快捷键 = 按键 → 指令 映射层，复用 CommandService。与 command/gizmo/preferences 同级 core 子模块。
+ * 跨模块只 import 被引用子模块 barrel，避开顶层 core/index 循环依赖。
+ */
+export type { PlatformKey, KeyBindingScope, KeyCombo, KeyBindingSpec, StoredBindingEntry, ProfileEntries, StoredProfileMap, KeyBindingChange, KeyBindingEvents, KeyBindingStore, } from './types';
+export { KeyBindingController } from './key-binding-controller';
+export { DuplicateComboError, MissingKeyBindingError } from './key-binding-registry';
+export { createKeyComboFromEvent, matchCombo, comboToString, parseCombo, } from './key-matcher';
+export { LocalStorageKeyBindingStore } from './key-binding-store';

package/dist/core/keybinding/key-binding-controller.d.ts

@@ -0,0 +1,44 @@
+import type { CommandService } from '../command';
+import type { KeyBindingStore, KeyBindingSpec, KeyCombo, PlatformKey } from './types';
+import { KeyBindingRegistry } from './key-binding-registry';
+import type { GestureHandler } from '@vvfx/gizmo';
+/** 探测平台主修饰符：mac 系用 meta，其余用 ctrl。 */
+export declare function detectPlatformKey(): PlatformKey;
+/**
+ * KeyBindingController - 对外门面 + 装配点
+ *
+ * 持有 KeyBindingRegistry，探测平台修饰符，构造期即订阅 GestureHandler 转发的 runtime keyDown：命中注册组合即执行对应
+ * command/handler。
+ * 对外暴露 artis.keybinding.* 命名空间方法，委托 registry。
+ */
+export type KeyBindingControllerOptions = {
+    commandService: CommandService;
+    store: KeyBindingStore;
+    /** 订阅 runtime Control 经 GestureHandler 转发的 keyDown。 */
+    gestureHandler: GestureHandler;
+    platformKey?: PlatformKey;
+};
+export declare class KeyBindingController {
+    private readonly _registry;
+    private readonly _off;
+    constructor(options: KeyBindingControllerOptions);
+    /** 解订 keyDown 监听，供 dispose/切场景清理。 */
+    dispose(): void;
+    get registry(): KeyBindingRegistry;
+    register(spec: KeyBindingSpec): void;
+    unregister(id: string): void;
+    setKey(id: string, combo: KeyCombo): void;
+    resetKey(id: string): void;
+    enable(id: string): void;
+    disable(id: string): void;
+    pauseAll(): void;
+    resumeAll(): void;
+    getAll(): KeyBindingSpec[];
+    getActiveProfile(): string;
+    getProfiles(): string[];
+    switchProfile(profileId: string): void;
+    saveProfile(profileId: string): void;
+    deleteProfile(profileId: string): void;
+    /** 订阅注册表变更（UI 监听刷新）。返回解订函数。 */
+    on(cb: (change: import('./types').KeyBindingChange) => void): () => void;
+}

package/dist/core/keybinding/key-binding-registry.d.ts

@@ -0,0 +1,92 @@
+/**
+ * KeyBindingRegistry - 运行时注册表 + 控制面 + profile
+ *
+ * 维护「id → 绑定」表，按 active profile 应用持久化 override，在按键时解析命中并执行。
+ *
+ * 关键语义：
+ * - 冲突检测精确化为「同 combo + 同 scope」报错（{@link DuplicateComboError}）。不同 scope 的同一 combo 可共存，
+ *   因为运行时互斥（global 仅非文本态触发、editing 仅文本态触发），用于 Esc 这类「一键两态」复用。
+ * - resolve 在文本编辑态（activeElement 为 textarea/input/contenteditable）跳过 global 绑定、仅放行 editing 绑定，
+ *   避免与 textarea 抢键。
+ * - 执行（commandId 或 handler）失败只 console.error，不上抛，避免污染键盘链路。
+ */
+import { EventEmitter } from '../../shared';
+import type { CommandService } from '../command';
+import type { KeyBindingEvents, KeyBindingSpec, KeyBindingStore, PlatformKey } from './types';
+import { type KeyInputEvent } from './key-matcher';
+/** 同 combo + 同 scope 被其它 id 占用时抛出。 */
+export declare class DuplicateComboError extends Error {
+    readonly combo: string;
+    readonly existingId: string;
+    constructor(combo: string, existingId: string);
+}
+/** 无此 id 时由操作抛出。 */
+export declare class MissingKeyBindingError extends Error {
+    constructor(id: string);
+}
+/** 构造参数。 */
+export type KeyBindingRegistryOptions = {
+    store: KeyBindingStore;
+    commandService: CommandService;
+    platformKey: PlatformKey;
+};
+export declare class KeyBindingRegistry extends EventEmitter<KeyBindingEvents> {
+    private readonly _store;
+    private readonly _commandService;
+    private readonly _platformKey;
+    /** 注册的全部 spec（含默认 combo），按 id 索引。 */
+    private readonly _specs;
+    /** active profile 的持久化 override，按 id 索引。 */
+    private _overrides;
+    private _activeProfile;
+    /** 全局暂停标记（运行态，不持久化，播放态禁交互用）。 */
+    private _paused;
+    constructor(options: KeyBindingRegistryOptions);
+    /**
+     * 注册绑定。同 id 覆盖允许；若该 combo 在同 scope 被其它 id 占用则抛 {@link DuplicateComboError}。
+     * builtin 标记由 spec.builtin 携带；外部注册不带 builtin。
+     */
+    register(spec: KeyBindingSpec): void;
+    /** 注销绑定。builtin 降级为 disable（标记persist），非 builtin 真删。 */
+    unregister(id: string): void;
+    /** 改某 id 的键位。让出旧 combo→校验新 combo（同 scope 被占则抛错）→持久化。 */
+    setKey(id: string, combo: KeyBindingSpec['combo']): void;
+    /** 还原默认键位并清该 id 的持久化 override（builtin 适用；非 builtin 抛错）。 */
+    resetKey(id: string): void;
+    enable(id: string): void;
+    disable(id: string): void;
+    pauseAll(): void;
+    resumeAll(): void;
+    /** 返回当前 profile 下所有绑定的有效形态（应用 override 后），供 UI 展示。 */
+    getAll(): KeyBindingSpec[];
+    getActiveProfile(): string;
+    /** 列出已存 profile，至少含 'default'。 */
+    getProfiles(): string[];
+    /** 切换 active profile：重建 override 表，刷新文档态。 */
+    switchProfile(profileId: string): void;
+    /** 把当前 profile 的 override 另存为新 profile。 */
+    saveProfile(profileId: string): void;
+    /** 删除 profile（'default' 拒绝；若删的是 active 则切回 default）。 */
+    deleteProfile(profileId: string): void;
+    /**
+     * 解析键盘事件：命中首个 enabled 且 scope 允许的绑定则执行，返回 true。
+     * 文本编辑态跳过 global、仅放行 editing。执行异常 console.error 不上抛。
+     */
+    resolve(event: KeyInputEvent): boolean;
+    private _execute;
+    /** 校验 combo 在同 scope 未被其它 id 占用。 */
+    private _assertComboFree;
+    private _effective;
+    private _effectiveSpec;
+    private _setDisabled;
+    private _setOverride;
+    private _reloadOverrides;
+    private _serializeOverrides;
+    private _persistProfile;
+    private _emit;
+}
+/**
+ * 判断当前是否处于文本编辑上下文（textarea/input/contenteditable）。
+ * 用于 resolve 在文本态跳过 global 绑定、放行 editing 绑定。
+ */
+export declare function isInTextEditingContext(): boolean;

package/dist/core/keybinding/key-binding-store.d.ts

@@ -0,0 +1,29 @@
+/**
+ * KeyBindingStore 默认实现 - 基于 localStorage 的多 profile 持久化。
+ *
+ * 持久化范围：profileId → { id → { combo, disabled? } }；activeProfile 单独存储。
+ * 隐私模式 / SSR 等无 localStorage 环境下退化为内存 Map，保证不崩、当 session 有效。
+ */
+import type { KeyBindingStore, ProfileEntries, StoredProfileMap } from './types';
+/**
+ * 基于 localStorage 的默认持久化实现。
+ * 若 localStorage 不可用（隐私模式 / SSR），自动委托内存后端。
+ */
+export declare class LocalStorageKeyBindingStore implements KeyBindingStore {
+    private _memory;
+    private readonly _profilesKey;
+    private readonly _activeProfileKey;
+    constructor(profilesKey?: string, activeProfileKey?: string);
+    /** localStorage 不可用时退化到内存后端。 */
+    private fallback;
+    loadAll(): StoredProfileMap;
+    saveProfile(profileId: string, entries: ProfileEntries): void;
+    deleteProfile(profileId: string): void;
+    /** 读取当前盘上 profile map，按本次写入项合并（空 entries 视为删除该项）后返回待落盘全量。 */
+    private _mergedProfiles;
+    /** 整块落盘 profiles map；localStorage 不可用或写失败时走 fallback。 */
+    private _writeProfiles;
+    listProfiles(): string[];
+    getActiveProfile(): string;
+    setActiveProfile(profileId: string): void;
+}

package/dist/core/keybinding/key-matcher.d.ts

@@ -0,0 +1,24 @@
+/**
+ * KeyMatcher - 键位归一与匹配
+ *
+ * 1. createKeyComboFromEvent：把原生 KeyboardEvent 归一为平台无关的 KeyCombo
+ *    （key 小写、ctrl 修饰符按 platformKey 映射）。
+ * 2. matchCombo：判断事件是否命中某组合。
+ * 3. comboToString / parseCombo：组合与字符串互逆，供注册表反查与内置表声明。
+ *
+ * 修饰符顺序约定为 ctrl, alt, shift，comboString 形如 'meta+z' / 'delete' / 'shift+/'。
+ */
+import type { KeyCombo, PlatformKey } from './types';
+import { InputEventKey } from '@galacean/effects';
+export type KeyInputEvent = KeyboardEvent | InputEventKey;
+/**
+ * 把原生键盘事件归一为 KeyCombo。
+ * key 经归一化，修饰符合并到平台无关的 `ctrl`（mac=metaKey / win=ctrlKey）。
+ */
+export declare function createKeyComboFromEvent(e: KeyInputEvent, platformKey: PlatformKey): KeyCombo;
+/** 判断原生事件是否命中某组合。 */
+export declare function matchCombo(e: KeyInputEvent, spec: KeyCombo, platformKey: PlatformKey): boolean;
+/** 把组合序列化为字符串，如 'ctrl+shift+z' / 'delete' / ' '。 */
+export declare function comboToString(combo: KeyCombo): string;
+/** 把字符串解析回组合。平台无关：修饰符一律用 'ctrl' 抽象位（platformKey 仅在匹配事件时使用）。 */
+export declare function parseCombo(str: string): KeyCombo;

package/dist/core/keybinding/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 快捷键系统 - 类型定义
+ *
+ * 快捷键本质是「按键 → 指令」的映射层，复用既有 CommandService：键位命中后走
+ * `commandService.execute(commandId, ...args)`，或经 handler 旁路（undo/redo 等非命令动作）。
+ *
+ * 设计要点：
+ * - `KeyCombo` 用平台无关的抽象修饰符 `ctrl`：mac 下匹配 `metaKey`、win 下匹配
+ *   `ctrlKey`，具体由 KeyMatcher 按 `platformKey` 解释，不进 spec，避免耦合平台。
+ * - 同一 combo 在同一 profile 内被其它 id 占用即报错（DuplicateComboError），不做抢占共存。
+ * - 键位配置按 profile 隔离，支持多套交互配置（见 KeyBindingStore）。
+ */
+/** 平台修饰符键：mac 用 'meta'，其余用 'ctrl'。决定 KeyCombo.ctrl 匹配哪个原生按键。 */
+export type PlatformKey = 'ctrl' | 'meta';
+/** 快捷键作用域。'editing' 仅在文本编辑态放行；'global' 在文本态自动跳过（不抢 textarea 按键）。 */
+export type KeyBindingScope = 'global' | 'editing';
+/** 归一化后的按键组合。ctrl 在 mac=metaKey、win=ctrlKey，由 matcher 按 platformKey 解释。 */
+export type KeyCombo = {
+    /** KeyboardEvent.key 小写归一，如 'delete' / 'z' / '=' / '/' / ' ' */
+    key: string;
+    /** 主修饰符（平台无关）：mac 下匹配 metaKey、win 下匹配 ctrlKey */
+    ctrl?: boolean;
+    alt?: boolean;
+    shift?: boolean;
+};
+/** 单个 profile 内某条 binding 的持久化项。只存改后的键位与禁用标记，不存 handler/command。 */
+export type StoredBindingEntry = {
+    /** 改后的键位；缺省表示沿用 spec 默认 combo（仅记录 disabled 时可为空）。 */
+    combo?: KeyCombo;
+    disabled?: boolean;
+};
+/** 单个 profile 的全部 overrides，按 id 索引。 */
+export type ProfileEntries = Record<string, StoredBindingEntry>;
+/** 全部 profile 的存储形态：profileId → { id → override }。 */
+export type StoredProfileMap = Record<string, ProfileEntries>;
+/** 快捷键绑定规格：注册时传入，描述「某 id 在某键位触发什么」。 */
+export type KeyBindingSpec = {
+    /** 逻辑指令标识，如 'item.delete' / 'edit.undo' / 'myapp.custom'，可被外部引用、改键、禁用 */
+    id: string;
+    /** 当前生效键位（可被 setKey 覆盖并持久化到 active profile） */
+    combo: KeyCombo;
+    /** 走 CommandService 的路径（与 handler 二选一；二者都有时 commandId 优先） */
+    commandId?: string;
+    /** execute 透传参数（单参对象；静态 args 场景；需运行时上下文的场景请用 handler） */
+    args?: Record<string, unknown>;
+    /** 非 command 旁路：undo/redo、退出文本编辑等，或需动态取选中元素的内置绑定 */
+    handler?: () => void;
+    /** 临时关闭开关（运行态，不进 profile 持久化，仅 disabled 标记持久化） */
+    enabled?: boolean;
+    /** 作用域：'global' 默认；'editing' 仅文本编辑态放行 */
+    scope?: KeyBindingScope;
+    /** 内置标记：unregister 降级为 disable，resetKey 还原默认 */
+    builtin?: boolean;
+    /** UI 展示用标签 */
+    label?: string;
+};
+/** 注册表 / profile 变更事件负载。 */
+export type KeyBindingChange = {
+    type: 'register' | 'unregister' | 'setKey' | 'resetKey' | 'enable' | 'disable' | 'pauseAll' | 'resumeAll' | 'switchProfile' | 'saveProfile' | 'deleteProfile';
+    id?: string;
+    profileId?: string;
+};
+/** 快捷键事件订阅表（@galacean EventEmitter 要求值为参数元组数组）。 */
+export type KeyBindingEvents = {
+    change: [KeyBindingChange];
+};
+/**
+ * 持久化层抽象（默认 localStorage 实现）。
+ * 宿主可注入自定义 Store（远程配置中心等），便于平台支持多套交互配置。
+ * 只持久化 profile→{id→combo/disabled}，不存 handler/commandId（注册期确定，存了有反序列化风险）。
+ */
+export interface KeyBindingStore {
+    /** 读取全部 profile 的 overrides。 */
+    loadAll(): StoredProfileMap;
+    /** 写入（或覆盖）单个 profile。 */
+    saveProfile(profileId: string, entries: ProfileEntries): void;
+    /** 删除某个 profile（'default' 由实现拒绝）。 */
+    deleteProfile(profileId: string): void;
+    /** 列出已存的 profileId。 */
+    listProfiles(): string[];
+    /** 当前激活 profile（单独持久化，刷新后回到上次）。 */
+    getActiveProfile(): string;
+    setActiveProfile(profileId: string): void;
+}

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

@@ -0,0 +1,3 @@
+export { PluginSystem } from './plugin-system';
+export type { ArtisPlugin } from './plugin-system';
+export { IOPlugin } from './io-plugin';