@vvfx/ge-ir 0.0.1-beta.6 → 0.0.1-beta.8

package/README.md

@@ -1,38 +1,74 @@
 # @vvfx/ge-ir
 
 > 内部转换包。统一承载 Galacean Effects JSONScene 与 `@vvfx/animation-ir`
-> 之间的双向转换能力，供 monorepo 内的 lottie2ge、dsl2ge、调试页面等链路复用。
+> 之间的双向转换能力，供 monorepo 内的 lottie2ge、ge-dsl、调试页面等链路复用。
 
 ## 能力范围
 
 ```
-JSONScene ── convertGEToIR ──> IRComposition ── convertIRToGE ──> JSONScene
-                         @vvfx/animation-ir
+GE JSONScene ── convertGEToIR ──> IRComposition ── convertIRToGE ──> GE JSONScene
 ```
 
 本包不定义 IR 数据模型；`@vvfx/animation-ir` 仍是 IR 类型和校验逻辑的唯一真源。
 
+## 源码结构
+
+```text
+src/
+├── common/
+│   ├── coordinate-mapping.ts  # GE 2D/3D 坐标换算
+│   ├── data-path.ts           # 实体 ID、DataPath 与实体池索引
+│   ├── json-normalization.ts  # JSON 边界校验与规范化
+│   └── math.ts                # 数值计算
+├── ge2ir/
+│   ├── index.ts               # GE → IR 流程编排
+│   ├── assemble.ts            # 组装最终 IRComposition
+│   ├── parser/                # 解析 scene、layer、component、animation
+│   ├── mapping.ts             # GE 值到 IR 值的纯映射
+│   └── post-process.ts        # 合并图层并恢复层级
+├── ir2ge/
+│   ├── index.ts               # IR → GE 流程编排
+│   ├── assemble.ts            # 组装最终 GE JSONScene
+│   ├── converter/             # IR 语义到 GE payload 的转换
+│   ├── generator/             # 生成 item、component 和 timeline
+│   ├── post-process/          # 处理层级、mask、可见性与保留资源
+│   ├── mapping.ts             # IR 值到 GE 值的纯映射
+│   └── types.ts               # 内部类型与生成阶段实体池
+├── effects-passthrough.ts     # Effects 保真数据的读取与失效处理
+└── index.ts                   # 稳定公开入口
+```
+
 ## 主要 API
 
 ```ts
+import type { JSONScene } from '@galacean/effects-specification';
 import { convertGEToIR, convertIRToGE } from '@vvfx/ge-ir';
+import type { GEToIROptions } from '@vvfx/ge-ir';
 
-const ir = convertGEToIR(scene, { frameRate: 30 });
+const options: GEToIROptions = { frameRate: 30 };
+const ir = convertGEToIR(scene, options);
 const roundTrippedScene = convertIRToGE(ir);
 ```
 
 - `convertIRToGE(ir, duration?)`：IR -> GE JSONScene。
 - `convertGEToIR(scene, options)`：GE JSONScene -> IRComposition。
-- `GE2IROptions`：当前包含 `frameRate`。
-- `JSONScene` / `DataPath`：从 `@galacean/effects-specification` 透出，方便 sibling 包消费。
+- `GEToIROptions`：当前包含 `frameRate`。
+
+`JSONScene` 由 `@galacean/effects-specification` 定义，应从其真实定义包直接导入。
 
 ## 共享契约
 
-`src/shared/coordinate.ts` 是正反向坐标换算的共同真源：
+共享实现仍按职责归属在各自源码模块，对外统一从包根入口导入：
+
+```ts
+import {
+  convert2dTo3dPoint, get2dTo3dRatio, invalidateEffectsLayerSpecific,
+} from '@vvfx/ge-ir';
+```
+
+公开的坐标换算能力包括：
 
 - `DEFAULT_CAMERA_Z`
-- `DEFAULT_CAMERA_FOV`
-- `DEFAULT_CLIP_MODE`
 - `get2dTo3dRatio`
 - `convert2dTo3dPoint`
 
@@ -52,14 +88,12 @@ const roundTrippedScene = convertIRToGE(ir);
 - `sourceHierarchy`
 
 `sourceHierarchy` 保留 GE 原始的 `single-item` / `null-sprite-pair` 结构。编辑 anchor、
-rotation 或 scale 后会使该提示失效，后续由 GE lowering 重新按动画语义决策。
+rotation 或 scale 后会使该提示失效，后续由 GE 生成策略重新按动画语义决策。
 
 ### Passthrough 辅助函数
 
 ```ts
-import { getEffectsLayerSpecific, invalidateEffectsLayerSpecific } from '@vvfx/ge-ir';
-
-const effectsData = getEffectsLayerSpecific(composition, layer);
+import { invalidateEffectsLayerSpecific } from '@vvfx/ge-ir';
 
 layer.transform = {
   ...layer.transform,
@@ -70,24 +104,28 @@ invalidateEffectsLayerSpecific(layer, 'opacity');
 ```
 
 修改已经存在等价保真数据的规范化字段后，应调用 `invalidateEffectsLayerSpecific`，避免旧的 GE
-payload 在 lowering 时覆盖编辑结果。函数会返回被删除的字段，并自动清理已经为空的容器。
+payload 在生成 GE 时覆盖编辑结果。函数会返回被删除的字段，并自动清理已经为空的容器。
 
-公共辅助 API 还包括 `getEffectsCompositionSpecific`、`hasEffectsAnimationPassthrough` 和
-`hasEffectsColorAnimationPassthrough`。
+根入口还提供 `hasEffectsAnimationPassthrough` 和 `hasEffectsColorAnimationPassthrough`。
 
-`src/shared/types.ts` 放置不属于单一方向的 GE wire/pool 基础结构：
+生成阶段的内部类型定义在 `src/ir2ge/types.ts`：
 
-- `GERecord`
-- `GEDataPath`
-- `GEPoolIndex`
-- `GETransform`
-- `GEItem`
+- `GeneratedVFXItemData`
+- `GeneratedComponentData`
+- `GeneratedMiscData`
 - `ECSCollector`
 
-## 稳定性分层
+标准 GE 数据直接复用 `@galacean/effects-specification` 的 `TransformData`、`VFXItemData`、
+`ComponentData`、`EffectsObjectData` 和 `JSONScene`。这里只保留生成阶段确实需要的兼容桥接：组件和 misc
+允许携带转换器透传字段；`GeneratedVFXItemData` 允许省略规范包仍标记为必填、但已废弃的 `content`。
+
+## 导出边界
 
-`src/index.ts` 按三层导出：
+根入口统一提供稳定的跨包能力：
 
-- 公开/主链路：`convertIRToGE`、`convertGEToIR`、基础类型。
-- sibling 包 API：`readLottieSpecific`、`hasIndependentParentLifetime`、部分 GE 处理中间类型。
-- debug internals：bezier/timeline/post-process/utils 等调试链路会用到的内部符号。
+- 转换：`convertIRToGE`、`convertGEToIR`。
+- 坐标换算：`convert2dTo3dPoint`、`get2dTo3dRatio`、`DEFAULT_CAMERA_Z`。
+- 动画生成：`buildNormalizedColorAnimation`、`buildNormalizedTransformAnimation`。
+- Passthrough：`hasEffectsAnimationPassthrough`、`hasEffectsColorAnimationPassthrough`、
+  `invalidateEffectsLayerSpecific`。
+- 类型：`GEToIROptions`。

package/dist/common/coordinate-mapping.d.ts

@@ -0,0 +1,14 @@
+import { CameraClipMode } from '@galacean/effects-specification';
+/** Default camera Z position for 2D GE scenes. */
+export declare const DEFAULT_CAMERA_Z = 8;
+/** Default camera field of view for 2D GE scenes. */
+export declare const DEFAULT_CAMERA_FOV = 60;
+/** Default camera clipping mode for 2D GE scenes. */
+export declare const DEFAULT_CLIP_MODE = CameraClipMode.portrait;
+/** Return the pixel-to-world scale for the given canvas. */
+export declare function get2dTo3dRatio(width: number, height: number): number;
+/**
+ * Convert a canvas point from a top-left origin to GE world space with a centered
+ * origin and inverted Y axis. The Z value is included in the perspective adjustment.
+ */
+export declare function convert2dTo3dPoint(x: number, y: number, z: number, width: number, height: number): [number, number, number];

package/dist/common/data-path.d.ts

@@ -0,0 +1,15 @@
+import type { DataPath } from '@galacean/effects-specification';
+type GERecord = Record<string, unknown>;
+/** GE entity pool indexed by ID. */
+export type GEPoolIndex = Map<string, GERecord>;
+/** Create a 32-character hexadecimal GE entity ID. */
+export declare function createId(): string;
+/** Wrap an ID in a GE DataPath reference. */
+export declare function toDataPath(id: string): DataPath;
+/** Index GE pool entries by string ID. */
+export declare function buildPoolIndex(pool: GERecord[] | undefined): GEPoolIndex;
+/** Resolve a GE DataPath against an indexed pool. */
+export declare function resolveDataPath(pool: GEPoolIndex, ref: unknown): GERecord | undefined;
+/** Return the string ID stored in a GE DataPath-like value. */
+export declare function resolveDataPathId(ref: unknown): string | undefined;
+export {};

package/dist/common/json-normalization.d.ts

@@ -0,0 +1,3 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Clone and normalize a value to its JSON-persisted runtime shape. */
+export declare function normalizeJsonValue<T>(value: T): T;

package/dist/common/math.d.ts

@@ -0,0 +1,4 @@
+/** Round a number to the given decimal precision. */
+export declare function roundNumber(value: number, precision?: number): number;
+/** Interpolate linearly between `a` and `b`. */
+export declare function lerp(a: number, b: number, factor: number): number;

package/dist/{passthrough.d.ts → effects-passthrough.d.ts}

@@ -1,8 +1,9 @@
 import type { EffectsCompositionSpecific, EffectsLayerSpecific, IRComposition, IRLayerNode } from '@vvfx/animation-ir';
+/** Normalized field whose conflicting Effects passthrough data should be removed. */
 export type EffectsLayerSpecificInvalidationTarget = 'position' | 'rotation' | 'scale' | 'color' | 'opacity' | 'anchor' | 'mask' | 'precomp';
-/** Read GE layer passthrough data. */
+/** Return Effects passthrough data for a layer from a GE composition. */
 export declare function getEffectsLayerSpecific(ir: IRComposition, layer: IRLayerNode): EffectsLayerSpecific | undefined;
-/** Read GE composition passthrough data. */
+/** Return Effects passthrough data for a GE composition. */
 export declare function getEffectsCompositionSpecific(ir: IRComposition): EffectsCompositionSpecific | undefined;
 /**
  * Remove raw GE values that would otherwise shadow an edited normalized field.

package/dist/ge2ir/assemble.d.ts

@@ -0,0 +1,4 @@
+import type { IRComposition, IRLayerNode } from '@vvfx/animation-ir';
+import type { GESceneContext } from './types';
+/** Assemble parsed GE data into the final normalized IR composition. */
+export declare function assembleIRComposition(scene: Record<string, unknown>, itemIds: string[], layers: IRLayerNode[], ctx: GESceneContext): IRComposition;

package/dist/ge2ir/index.d.ts

@@ -1,2 +1,4 @@
-export { convertGEToIR } from './converter';
-export type { GE2IROptions } from './types';
+import type { IRComposition } from '@vvfx/animation-ir';
+import type { GEToIROptions } from './types';
+/** Convert a GE scene to normalized IR while retaining fidelity passthrough data. */
+export declare function convertGEToIR(scene: Record<string, unknown>, options: GEToIROptions): IRComposition;

package/dist/ge2ir/mapping.d.ts

@@ -0,0 +1,6 @@
+import { IRBlendMode, IREndBehavior, type IRTimeContext } from '@vvfx/animation-ir';
+import { EndBehavior } from '@galacean/effects-specification';
+export declare function mapBlendModeToIR(GECode: number | undefined): IRBlendMode | undefined;
+export declare function mapEndBehaviorToIR(GEBehavior: EndBehavior | undefined): IREndBehavior | undefined;
+export declare function mapLayerTimingToIR(delay: number, duration: number, frameRate: number): IRTimeContext;
+export declare function convert3dTo2dPoint(x: number, y: number, z: number, width: number, height: number): [number, number, number];

package/dist/ge2ir/{parsers/component-parser.d.ts → parser/component.d.ts}

@@ -1,6 +1,6 @@
 import type { IRAssetReference, IRBlendMode, IRColor, IRShapeData, IRTextData } from '@vvfx/animation-ir';
 import type { GESceneContext } from '../types';
-export interface ComponentData {
+interface ParsedComponentData {
     type: 'image' | 'solid' | 'text' | 'shape';
     asset?: IRAssetReference;
     solidColor?: IRColor;
@@ -8,9 +8,10 @@ export interface ComponentData {
     shapes?: IRShapeData[];
     blendMode?: IRBlendMode;
     anchorScale?: [number, number];
-    /** Original GE component id — rendezvous key for cross-component references (masks). */
+    /** Source GE component ID used to remap cross-component references. */
     GEComponentId?: string;
-    /** Raw GE component-level `mask` object (source: {isMask:true,...}, target: {isMask:false,reference,inverted}). */
+    /** Raw component mask preserved for source and target reconstruction. */
     rawMask?: Record<string, unknown>;
 }
-export declare function parseComponent(item: Record<string, unknown>, ctx: GESceneContext): ComponentData | undefined;
+export declare function parseComponent(item: Record<string, unknown>, ctx: GESceneContext): ParsedComponentData | undefined;
+export {};

package/dist/ge2ir/parser/layer.d.ts

@@ -0,0 +1,4 @@
+import type { IRLayerNode } from '@vvfx/animation-ir';
+import type { GESceneContext } from '../types';
+/** Parse one GE item and its referenced component data into an IR layer. */
+export declare function parseItemToLayer(item: Record<string, unknown>, itemId: string, index: number, ctx: GESceneContext): IRLayerNode;

package/dist/ge2ir/{scene-reader.d.ts → parser/scene.d.ts}

@@ -1,3 +1,3 @@
-import type { GE2IROptions, GESceneContext } from './types';
-export declare function buildSceneContext(scene: Record<string, unknown>, options: GE2IROptions): GESceneContext;
+import type { GEToIROptions, GESceneContext } from '../types';
+export declare function buildSceneContext(scene: Record<string, unknown>, options: GEToIROptions): GESceneContext;
 export declare function getCompositionItemIds(scene: Record<string, unknown>): string[];

package/dist/ge2ir/{parsers/timeline-parser.d.ts → parser/timeline.d.ts}

@@ -1,9 +1,11 @@
+import { EndBehavior } from '@galacean/effects-specification';
 import type { GESceneContext } from '../types';
-export interface TimelineData {
+interface ParsedTimelineData {
     delay: number;
     duration: number;
-    endBehavior: number;
+    endBehavior: EndBehavior;
     transformAsset?: Record<string, unknown>;
     spriteColorAsset?: Record<string, unknown>;
 }
-export declare function parseTimeline(itemId: string, ctx: GESceneContext): TimelineData | undefined;
+export declare function parseTimeline(itemId: string, ctx: GESceneContext): ParsedTimelineData | undefined;
+export {};

package/dist/ge2ir/{merge/merge.d.ts → post-process.d.ts}

@@ -1,5 +1,5 @@
 import type { IRLayerNode } from '@vvfx/animation-ir';
-import type { GESceneContext } from '../types';
+import type { GESceneContext } from './types';
 export interface RawLayerDescriptor {
     itemId: string;
     item: Record<string, unknown>;

package/dist/ge2ir/types.d.ts

@@ -1,6 +1,8 @@
 import type { IRColor, IREndBehavior } from '@vvfx/animation-ir';
-import type { GEPoolIndex } from '../shared/types';
-export interface GE2IROptions {
+import type { GEPoolIndex } from '../common/data-path';
+/** Options for converting a GE scene to IR. */
+export interface GEToIROptions {
+    /** Frame rate used to express GE second-based timing in IR frames. */
     frameRate: number;
 }
 export interface GESceneContext {
@@ -22,4 +24,3 @@ export interface GESceneContext {
     textureById: GEPoolIndex;
     itemIdToTrackId: Map<string, string>;
 }
-export type GEJsonContext = GESceneContext;

package/dist/index.d.ts

@@ -1,18 +1,7 @@
-export { convertIRToGE } from './ir2ge/assembly/generator';
-export { convertGEToIR } from './ge2ir/converter';
-export type { GE2IROptions } from './ge2ir/types';
-export type { DataPath, JSONScene } from '@galacean/effects-specification';
-export { getEffectsCompositionSpecific, getEffectsLayerSpecific, hasEffectsAnimationPassthrough, hasEffectsColorAnimationPassthrough, invalidateEffectsLayerSpecific, } from './passthrough';
-export type { EffectsLayerSpecificInvalidationTarget } from './passthrough';
-export { readLottieSpecific } from './ir2ge/ir/specific';
-export type { LottieLayerSpecific } from './ir2ge/ir/specific';
-export { hasIndependentParentLifetime } from './ir2ge/ir/parent-link';
-export type { ECSCollector, GEDataPath, GEItem, GEPoolIndex, GERecord, GETransform } from './shared/types';
-export type { ProcessedItem, TransformAnimation } from './ir2ge/types';
-export { DEFAULT_CAMERA_Z, DEFAULT_CAMERA_FOV, DEFAULT_CLIP_MODE, get2dTo3dRatio, convert2dTo3dPoint, } from './shared/coordinate';
-export { assembleScene } from './ir2ge/assembly/scene-assembly';
-export { estimateTextWidth, roundNumber, lerp, createId, toDataPath } from './ir2ge/utils';
-export { irScalarKeyframesToGE, irVectorKeyframesToGE, irPositionKeyframesToGE, shouldUseKeyframeMode, } from './ir2ge/builders/bezier';
-export type { IRToGETimeContext, IRPositionGEResult } from './ir2ge/builders/bezier';
-export { buildTimelineTracks } from './ir2ge/builders/timeline';
-export { normalizeChildVisibilityByParentDelays } from './ir2ge/post-process/visibility';
+export { convertIRToGE } from './ir2ge';
+export { convertGEToIR } from './ge2ir';
+export { buildNormalizedColorAnimation, buildNormalizedTransformAnimation, } from './ir2ge/converter/normalized-animation';
+export { convert2dTo3dPoint, DEFAULT_CAMERA_Z, get2dTo3dRatio, } from './common/coordinate-mapping';
+export { hasEffectsAnimationPassthrough, hasEffectsColorAnimationPassthrough, invalidateEffectsLayerSpecific, } from './effects-passthrough';
+export type { GEToIROptions } from './ge2ir/types';
+export type { EffectsLayerSpecificInvalidationTarget } from './effects-passthrough';