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

package/README.md

@@ -1,7 +1,7 @@
 # @vvfx/ge-ir
 
 > 内部转换包。统一承载 Galacean Effects JSONScene 与 `@vvfx/animation-ir`
-> 之间的双向转换能力，供 monorepo 内的 `lottie2ge`、`dsl2ge`、调试页面等链路复用。
+> 之间的双向转换能力，供 monorepo 内的 lottie2ge、dsl2ge、调试页面等链路复用。
 
 ## 能力范围
 
@@ -36,17 +36,44 @@ const roundTrippedScene = convertIRToGE(ir);
 - `get2dTo3dRatio`
 - `convert2dTo3dPoint`
 
-`src/shared/ge2ir-metadata.ts` 是 round-trip passthrough metadata 的共同真源。`ge2ir`
-写入 `layer.metadata.ge2ir`，`ir2ge` 在生成 GE 时读取并复用原始 GE 动画和 mask 信息。
+`IRLayerNode.specific.effects` 是 round-trip passthrough 数据的共同入口。ge2ir 写入暂时无法通过
+规范化 IR 无损表示的 GE 动画、mask、precomp 和原始层级信息，ir2ge 在生成 GE 时读取并复用。
 
-当前支持的 metadata keys：
+当前支持的主要 passthrough keys：
 
 - `positionOverLifetime`
 - `rotationOverLifetime`
 - `sizeOverLifetime`
 - `colorOverLifetime`
-- `geComponentId`
-- `geMask`
+- `sourceComponentId`
+- `mask`
+- `precompRefId`
+- `precompContent`
+- `sourceHierarchy`
+
+`sourceHierarchy` 保留 GE 原始的 `single-item` / `null-sprite-pair` 结构。编辑 anchor、
+rotation 或 scale 后会使该提示失效，后续由 GE lowering 重新按动画语义决策。
+
+### Passthrough 辅助函数
+
+```ts
+import { getEffectsLayerSpecific, invalidateEffectsLayerSpecific } from '@vvfx/ge-ir';
+
+const effectsData = getEffectsLayerSpecific(composition, layer);
+
+layer.transform = {
+  ...layer.transform,
+  opacity: { keyframed: false, value: 0.5 },
+};
+
+invalidateEffectsLayerSpecific(layer, 'opacity');
+```
+
+修改已经存在等价保真数据的规范化字段后，应调用 `invalidateEffectsLayerSpecific`，避免旧的 GE
+payload 在 lowering 时覆盖编辑结果。函数会返回被删除的字段，并自动清理已经为空的容器。
+
+公共辅助 API 还包括 `getEffectsCompositionSpecific`、`hasEffectsAnimationPassthrough` 和
+`hasEffectsColorAnimationPassthrough`。
 
 `src/shared/types.ts` 放置不属于单一方向的 GE wire/pool 基础结构：
 
@@ -62,5 +89,5 @@ const roundTrippedScene = convertIRToGE(ir);
 `src/index.ts` 按三层导出：
 
 - 公开/主链路：`convertIRToGE`、`convertGEToIR`、基础类型。
-- sibling 包 API：`readLottieSpecific`、`isTransformOnlyParentLink`、部分 GE 处理中间类型。
-- debug internals：bezier/timeline/post-process/utils 等调试链路会用到的内部符号。
+- sibling 包 API：`readLottieSpecific`、`hasIndependentParentLifetime`、部分 GE 处理中间类型。
+- debug internals：bezier/timeline/post-process/utils 等调试链路会用到的内部符号。

package/dist/ge2ir/converter.d.ts

@@ -1,3 +1,3 @@
-import type { IRComposition } from '@vvfx/animation-ir';
+import { type IRComposition } from '@vvfx/animation-ir';
 import type { GE2IROptions } from './types';
 export declare function convertGEToIR(scene: Record<string, unknown>, options: GE2IROptions): IRComposition;

package/dist/ge2ir/parsers/component-parser.d.ts

@@ -9,7 +9,7 @@ export interface ComponentData {
     blendMode?: IRBlendMode;
     anchorScale?: [number, number];
     /** Original GE component id — rendezvous key for cross-component references (masks). */
-    geComponentId?: string;
+    GEComponentId?: string;
     /** Raw GE component-level `mask` object (source: {isMask:true,...}, target: {isMask:false,reference,inverted}). */
     rawMask?: Record<string, unknown>;
 }

package/dist/ge2ir/parsers/keyframe-parser.d.ts

@@ -1,7 +1,7 @@
 import type { IRBezierHandle, IRKeyframe } from '@vvfx/animation-ir';
 export declare function parseBezierKeyframes(curves: unknown[], startFrame: number, endFrame: number): IRKeyframe<number>[];
 export declare function parsePositionTimingKeyframes(curves: unknown[], startFrame: number, endFrame: number): Array<{
-    t: number;
+    frame: number;
     outTangent?: IRBezierHandle;
     inTangent?: IRBezierHandle;
 }>;

package/dist/ge2ir/reverse/blend-mode.d.ts

@@ -1,2 +1,2 @@
 import type { IRBlendMode as IRBlendModeType } from '@vvfx/animation-ir';
-export declare function reverseBlendMode(geCode: number | undefined): IRBlendModeType | undefined;
+export declare function reverseBlendMode(GECode: number | undefined): IRBlendModeType | undefined;

package/dist/ge2ir/reverse/end-behavior.d.ts

@@ -1,3 +1,3 @@
 import type { IREndBehavior as IREndBehaviorType } from '@vvfx/animation-ir';
-export declare function reverseEndBehavior(geBehavior: number | undefined): IREndBehaviorType | undefined;
-export declare function reverseCompositionEndBehavior(geBehavior: number | undefined): IREndBehaviorType | undefined;
+export declare function reverseEndBehavior(GEBehavior: number | undefined): IREndBehaviorType | undefined;
+export declare function reverseCompositionEndBehavior(GEBehavior: number | undefined): IREndBehaviorType | undefined;

package/dist/ge2ir/types.d.ts

@@ -3,7 +3,6 @@ import type { GEPoolIndex } from '../shared/types';
 export interface GE2IROptions {
     frameRate: number;
 }
-export type { GE2IRPassthroughMetadata } from '../shared/ge2ir-metadata';
 export interface GESceneContext {
     compositionId: string;
     width: number;

package/dist/index.d.ts

@@ -2,13 +2,14 @@ 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 { isTransformOnlyParentLink } from './ir2ge/ir/parent-link';
+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 type { GE2IRPassthroughMetadata } from './shared/ge2ir-metadata';
 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';