@vvfx/ge-ir 0.0.1-beat.2 → 0.0.1-beta.11

package/README.md

@@ -1,66 +1,314 @@
 # @vvfx/ge-ir
 
-> 内部转换包。统一承载 Galacean Effects JSONScene 与 `@vvfx/animation-ir`
-> 之间的双向转换能力，供 monorepo 内的 `lottie2ge`、`dsl2ge`、调试页面等链路复用。
+English | [简体中文](./README-zh_CN.md)
 
-## 能力范围
+Bidirectional conversion between Galacean Effects and source-neutral Animation IR.
 
+The package converts supported GE content into normalized IR and retains GE-only data in an adapter-owned sidecar
+for fidelity-preserving export. Applications compose this adapter with `@vvfx/dsl-ir` when editing DSL.
+
+## Contents
+
+- [Install](#install)
+- [Usage](#usage)
+- [Preserved data](#preserved-data)
+- [Data boundaries](#data-boundaries)
+- [API](#api)
+- [Project structure](#project-structure)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Install
+
+Node.js 22 or later is required.
+
+```bash
+pnpm add @vvfx/ge-ir
+```
+
+## Usage
+
+### Convert GE to Animation IR
+
+```ts
+import { convertGEToIR } from '@vvfx/ge-ir';
+
+const imported = convertGEToIR(geScene, {
+  frameRate: 30,
+  resourceBaseUrl: 'https://cdn.example.com/scenes/demo.json',
+});
+
+console.info(imported.scene);
+console.info(imported.diagnostics);
+```
+
+`frameRate` converts GE timing in seconds to IR frames. `resourceBaseUrl` is optional and must be absolute when
+supplied; it resolves relative image and font URLs at the GE import boundary.
+
+### Particle source data
+
+`convertGEToIR` extracts the ParticleSystem bindings and source layout needed for final host placement:
+
+```ts
+import { convertGEToIR } from '@vvfx/ge-ir';
+
+const imported = convertGEToIR(geScene, { frameRate: 30 });
+
+console.info(imported.preservedData.particleSourceData);
+```
+
+Each source Composition containing ParticleSystems becomes one `particleEffectGroup`; every ParticleSystem retains an
+independent binding and its original Item order. Because GE does not provide principal visual bounds, the adapter
+stores `[0, 0, previewWidth, previewHeight]` as the fallback `authoringBounds` without a separate provenance marker.
+Scenes without ParticleSystem components store empty group and Layer arrays. Complete renderer, shape, and resource
+data remains in the GE-owned layer payload rather than this layout index.
+
+### Map particle layout to a GE transform
+
+Layout mapping is handled internally when converting DSL with particles.
+
+The internal mapping scales the source `authoringBounds` proportionally and aligns its center with `targetRegion.center`.
+It follows the Python layout contract: FOV is vertical, world height is `2 * abs(camera.position.z) * tan(fov / 2)`,
+and world width is world height times the preview aspect ratio. Camera `clipMode`, XY position, and rotation are
+ignored. Returned world Z is zero; placement Z controls painter order.
+When merging GE scenes, portrait-camera horizontal FOV is converted to equivalent vertical FOV for both
+source and host before this mapping. The stored cameras remain unchanged.
+
+### Merge restored particle GE scenes
+
+The caller restores particle scenes through `convertIRToGE`, then merges them into a host GE scene:
+
+```ts
+import { mergeParticleScenes } from '@vvfx/ge-ir';
+
+const scene = mergeParticleScenes(hostScene, [{
+  scene: restoredParticleScene,
+  preservedData: particleGEPreservedData,
+  placements,
+}], hostStackingOrder);
+```
+
+Each placement identifies a preserved effect group, its target width and height, and center position.
+`irLayerId` selects one particle system; omit it to place the entire group. A group must have either one group placement
+or one placement per system. The merger validates and resolves these bindings internally.
+The merger preserves required ancestors and timelines, namespaces IDs, rebases binary pointers, and orders Items,
+scene bindings, and timeline tracks together. Sources must share the host GE version and be self-contained.
+
+`hostStackingOrder` optionally maps GE Item IDs to painter ranks independently of spatial Z. To carry source IR ranks
+through conversion, read `itemLayerIds` from the `convertIRToGE` result. This JSON-serializable record maps generated
+Item IDs to IR Layer IDs. The caller joins these bindings to its layer ranks. Without explicit ranks, the merger uses cumulative
+host spatial Z.
+
+DSL conversion, paired sidecars, model requests, and initial placement policies belong to the application.
+See [the web workflows](../../web-packages/README.md#ge--dsl-集成边界) for a complete example.
+
+### Convert Animation IR to GE
+
+```ts
+import { convertIRToGE } from '@vvfx/ge-ir';
+
+const exported = convertIRToGE(irScene);
+
+console.info(exported.scene);
+console.info(exported.diagnostics);
+```
+
+`convertIRToGE` validates the IR scene before conversion. `options.duration` can override the exported duration.
+
+### Preserve GE-only data across a round trip
+
+Pass the sidecar returned by `convertGEToIR` back to `convertIRToGE` when the IR has not been edited:
+
+```ts
+const imported = convertGEToIR(geScene, { frameRate: 30 });
+const roundTripped = convertIRToGE(imported.scene, {
+  preservedData: imported.preservedData,
+});
 ```
-JSONScene ── convertGEToIR ──> IRComposition ── convertIRToGE ──> JSONScene
-                         @vvfx/animation-ir
+
+The IR scene remains valid without the sidecar. Most supported layer types are also exportable without it. Particle
+layers require their trusted GE sidecar for export because renderer, shape, and resource bindings are outside the
+source-neutral particle contract. Supplying the sidecar restores compatible GE object-pool data, raw
+animation payloads, masks, precomposition payloads, sprite metadata, particle payloads, and source hierarchy data.
+
+### Export edited IR with retained GE data
+
+After editing IR, reconcile the original sidecar before exporting:
+
+```ts
+import { convertGEToIR, convertIRToGE, updateGEToIRPreservedData } from '@vvfx/ge-ir';
+
+const imported = convertGEToIR(geScene, { frameRate: 30 });
+const updatedScene = structuredClone(imported.scene);
+
+updatedScene.compositions[0].layers[0].transform = {
+  ...updatedScene.compositions[0].layers[0].transform,
+  opacity: { type: 'static', value: 0.5 },
+};
+
+const updatedPreservedData = updateGEToIRPreservedData(
+  imported.scene,
+  updatedScene,
+  imported.preservedData,
+);
+
+const exported = convertIRToGE(updatedScene, {
+  preservedData: updatedPreservedData,
+});
 ```
 
-本包不定义 IR 数据模型；`@vvfx/animation-ir` 仍是 IR 类型和校验逻辑的唯一真源。
+`updateGEToIRPreservedData` compares the baseline IR with the updated IR. It clones the supplied sidecar, removes only
+GE values that conflict with changed IR fields, removes bindings for deleted compositions and layers, and returns the
+reconciled sidecar. It does not modify either IR scene or generate GE output.
+
+## Preserved data
+
+`GEToIRPreservedData` is owned by this adapter and stored outside the Animation IR contract. Persist it together with
+the IR scene when GE round-trip fidelity is required. Applications should not edit its internal fields directly.
+
+Layer-level preserved data can include:
+
+- raw position, rotation, scale, and color animation payloads;
+- sprite start color, texture splits, and texture-sheet animation settings;
+- GE item and component identities plus Activation clip end behavior;
+- masks and precomposition payloads that cannot be normalized losslessly;
+- complete ParticleSystem payloads whose normalized IR fields override the corresponding values on export;
+- the original single-item or null/sprite hierarchy.
+
+Top-level `particleSourceData` indexes ParticleSystem source bounds, source order, and IR bindings used by final host
+placement. A source Composition without a valid `previewSize` still imports into IR, but its host-placement bindings
+are omitted and reported as
+`GE_PARTICLE_SOURCE_LAYOUT_UNAVAILABLE`.
+
+Use `updateGEToIRPreservedData` for an edited scene. It derives all supported invalidations from the difference
+between the baseline and updated IR scenes; layer-level lookup and invalidation remain internal implementation details.
 
-## 主要 API
+## Data boundaries
+
+- `@vvfx/animation-ir` is the single source of truth for Animation IR types and validation.
+- `GEToIRPreservedData` belongs to `@vvfx/ge-ir`; it is never embedded in the source-neutral IR schema.
+- Preserved data is bound to specific IR composition and layer identities. Version and scene bindings are
+  validated before reuse.
+- All source compositions are imported. The source entry composition becomes `IRScene.entryCompositionId`.
+- External image and font resources entering IR must resolve to absolute URLs or Data URLs.
+- Conversion diagnostics report normalization, approximation, dropped data, and unsupported features.
+- Applications compose GE and DSL adapters through Animation IR. Their production code must not depend on each other.
+- Particle import maps editable GE `options` fields to flat IR particle content, normalizes supported GE scalar forms
+  to the IR curve model, and
+  keeps engine-only particle data in the trusted sidecar. Export applies `maxParticles`, `startLifetime`,
+  `rateOverTime`, `bursts`, Layer blend mode, anchor, and static opacity to that baseline instead of fabricating
+  renderer, shape, or resource defaults. Animated Particle Layer opacity is reported as unsupported because GE has
+  no timeline-compatible Particle renderer opacity target.
+- GE burst defaults are normalized to explicit IR `cycleCount` and `repeatIntervalFrames` values, including
+  unbounded cycles, with an informational normalization diagnostic. GE Item end behavior enters the normalized Layer;
+  Activation clip end behavior is retained independently in preserved data and restored during export.
+
+Further documentation:
+
+- [GE and Animation IR reference](../../docs/ge-ir-reference.md)
+- [DSL, IR, and GE package boundaries](../../docs/dsl-ir-ge-ir-boundary.md)
+- [DSL and IR editing capabilities](../../docs/dsl-ir-editing-capabilities.md)
+- [Animation IR particle contract](../../docs/particle-ir-contract.md)
+
+Ordinary and particle layers share the initial DSL `position.z` stacking order; higher values render above lower
+values. Reordering input arrays does not change stacking. Ordinary child subtrees stay together at their root rank.
+The rank-to-item mapping is internal and is not serialized into GE transforms.
+
+## API
+
+### Conversion and preservation
+
+```ts
+function convertGEToIR(scene: Record<string, unknown>, options: GEToIROptions): GEToIRResult;
+
+function convertIRToGE(scene: IRScene, options?: IRToGEOptions): IRToGEResult;
+
+function updateGEToIRPreservedData(
+  baselineScene: IRScene,
+  updatedScene: IRScene,
+  preservedData: GEToIRPreservedData,
+  options?: UpdateGEToIRPreservedDataOptions,
+): GEToIRPreservedData;
+
+```
+
+Results and options:
 
 ```ts
-import { convertGEToIR, convertIRToGE } from '@vvfx/ge-ir';
+interface GEToIRResult {
+  scene: IRScene;
+  preservedData: GEToIRPreservedData;
+  diagnostics: ConversionDiagnostic[];
+}
+
+interface IRToGEResult {
+  itemLayerIds: Readonly<Record<string, string>>;
+  scene: JSONScene;
+  diagnostics: ConversionDiagnostic[];
+}
+
+interface GEToIROptions {
+  frameRate: number;
+  resourceBaseUrl?: string;
+}
 
-const ir = convertGEToIR(scene, { frameRate: 30 });
-const roundTrippedScene = convertIRToGE(ir);
+interface IRToGEOptions {
+  duration?: number;
+  preservedData?: GEToIRPreservedData;
+}
 ```
 
-- `convertIRToGE(ir, duration?)`：IR -> GE JSONScene。
-- `convertGEToIR(scene, options)`：GE JSONScene -> IRComposition。
-- `GE2IROptions`：当前包含 `frameRate`。
-- `JSONScene` / `DataPath`：从 `@galacean/effects-specification` 透出，方便 sibling 包消费。
+`UpdateGEToIRPreservedDataOptions.onChange` receives the composition, layer, and preserved field removed during
+reconciliation.
 
-## 共享契约
+### Runtime exports
 
-`src/shared/coordinate.ts` 是正反向坐标换算的共同真源：
+| Export | Purpose |
+| --- | --- |
+| `convertGEToIR` | Import GE JSONScene as Animation IR and GE-owned preserved data |
+| `convertIRToGE` | Export Animation IR as GE JSONScene |
+| `mergeParticleScenes` | Merge restored particle GE scenes with explicit layout and painter order |
+| `updateGEToIRPreservedData` | Reconcile GE preserved data after IR edits |
+| `get2dTo3dRatio` | Calculate the coordinate conversion ratio |
 
-- `DEFAULT_CAMERA_Z`
-- `DEFAULT_CAMERA_FOV`
-- `DEFAULT_CLIP_MODE`
-- `get2dTo3dRatio`
-- `convert2dTo3dPoint`
+### Type exports
 
-`src/shared/ge2ir-metadata.ts` 是 round-trip passthrough metadata 的共同真源。`ge2ir`
-写入 `layer.metadata.ge2ir`，`ir2ge` 在生成 GE 时读取并复用原始 GE 动画和 mask 信息。
+All public types are imported from the package root:
 
-当前支持的 metadata keys：
+- Conversion: `GEToIROptions`, `GEToIRResult`, `IRToGEOptions`, and `IRToGEResult`.
+- Particle merge: `GEParticlePlacement` and `ParticleSceneMergeInput`.
+- GE preserved data: `GEToIRPreservedData`.
+- Reconciliation: `GEToIRPreservedDataChange` and `UpdateGEToIRPreservedDataOptions`.
 
-- `positionOverLifetime`
-- `rotationOverLifetime`
-- `sizeOverLifetime`
-- `colorOverLifetime`
-- `geComponentId`
-- `geMask`
+`JSONScene` is defined by `@galacean/effects-specification` and should be imported from that package.
 
-`src/shared/types.ts` 放置不属于单一方向的 GE wire/pool 基础结构：
+## Project structure
 
-- `GERecord`
-- `GEDataPath`
-- `GEPoolIndex`
-- `GETransform`
-- `GEItem`
-- `ECSCollector`
+```text
+src/
+  ge2ir/                   GE parsing, mapping, assembly, and post-processing
+  ir2ge/                   IR conversion, GE generation, assembly, and post-processing
+  particle/                Particle fragment extraction, layout, and host-scene merge
+  common/                  Coordinate, DataPath, JSON, ID, and math utilities
+  conversion.ts            Public conversion result and option types
+  preserved-data.ts        GE-owned composition and layer data contract
+  layer-preserved-data.ts  Layer data lookup and field invalidation
+  update-preserved-data.ts Scene-level preserved-data reconciliation
+  index.ts                 Stable public entry
+```
+
+## Contributing
+
+Use repository issues for questions and bug reports. Pull requests are welcome. Run the package checks after changing
+public behavior:
+
+```bash
+pnpm --filter @vvfx/ge-ir test
+pnpm --filter @vvfx/ge-ir build
+```
 
-## 稳定性分层
+Rendering changes require representative visual comparison in addition to automated checks.
 
-`src/index.ts` 按三层导出：
+## License
 
-- 公开/主链路：`convertIRToGE`、`convertGEToIR`、基础类型。
-- sibling 包 API：`readLottieSpecific`、`isTransformOnlyParentLink`、部分 GE 处理中间类型。
-- debug internals：bezier/timeline/post-process/utils 等调试链路会用到的内部符号。
+[MIT](./LICENSE) © 2019-present Ant Group Co., Ltd.

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

@@ -0,0 +1,3 @@
+import type { IRLayerType, IRTransform } from '@vvfx/animation-ir';
+/** Apply GE's parented visual rotation convention to an anchor position offset. */
+export declare function rotateAnchorOffsetForParentedVisual(layerType: IRLayerType, hasParent: boolean, transform: IRTransform | undefined, offsetX: number, offsetY: number): [number, number];

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

@@ -0,0 +1,19 @@
+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];
+/**
+ * Convert a GE world-space point to a top-left canvas coordinate while
+ * preserving its perspective-adjusted Z value.
+ */
+export declare function convert3dTo2dPoint(x: number, y: number, z: number, width: number, height: number): [number, number, number];

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

@@ -0,0 +1,14 @@
+import type { DataPath } from '@galacean/effects-specification';
+type GERecord = Record<string, unknown>;
+/** GE scene collection indexed by entity ID. */
+export type GESceneCollectionIndex = Map<string, GERecord>;
+/** Wrap an ID in a GE DataPath reference. */
+export declare function toDataPath(id: string): DataPath;
+/** Index GE scene collection entries by string ID. */
+export declare function buildSceneCollectionIndex(collection: GERecord[] | undefined): GESceneCollectionIndex;
+/** Resolve a GE DataPath against an indexed scene collection. */
+export declare function resolveDataPath(collectionIndex: GESceneCollectionIndex, reference: unknown): GERecord | undefined;
+/** Return the string ID stored in a GE DataPath-like value. */
+export declare function resolveDataPathId(reference: unknown): string | undefined;
+export declare function visitDataPathReferences(value: unknown, visit: (id: string) => void, visited?: WeakSet<object>): void;
+export {};

package/dist/common/id.d.ts

@@ -0,0 +1,2 @@
+/** Generate a 32-character hexadecimal UUID v4. */
+export declare function createId(): string;

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/common/particle-expression.d.ts

@@ -0,0 +1,4 @@
+import type { IRParticleScalarExpression } from '@vvfx/animation-ir';
+import { type NumberExpression } from '@galacean/effects-specification';
+export declare function parseGEParticleScalarExpression(value: unknown): IRParticleScalarExpression | undefined;
+export declare function convertIRParticleScalarExpressionToGE(expression: IRParticleScalarExpression): NumberExpression;

package/dist/conversion.d.ts

@@ -0,0 +1,21 @@
+import type { JSONScene } from '@galacean/effects-specification';
+import type { IRScene } from '@vvfx/animation-ir';
+import type { ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
+import type { GEToIRPreservedData } from './preserved-data';
+/** Result of importing a GE JSONScene into normalized Animation IR. */
+export interface GEToIRResult {
+    scene: IRScene;
+    preservedData: GEToIRPreservedData;
+    diagnostics: ConversionDiagnostic[];
+}
+/** Result of lowering a normalized Animation IR scene to a GE JSONScene. */
+export interface IRToGEResult {
+    /** Generated GE Item IDs mapped to their source IR Layer IDs. */
+    itemLayerIds: Readonly<Record<string, string>>;
+    scene: JSONScene;
+    diagnostics: ConversionDiagnostic[];
+}
+export interface IRToGEOptions {
+    duration?: number;
+    preservedData?: GEToIRPreservedData;
+}

package/dist/ge2ir/assemble.d.ts

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

package/dist/ge2ir/convert.d.ts

@@ -0,0 +1,4 @@
+import type { GEToIROptions } from './types';
+import type { GEToIRResult } from '../conversion';
+/** Convert a GE scene to normalized IR plus adapter-owned preserved data. */
+export declare function convertGEToIR(scene: Record<string, unknown>, options: GEToIROptions): GEToIRResult;

package/dist/ge2ir/extract-particle-source-data.d.ts

@@ -0,0 +1,5 @@
+import type { IRScene } from '@vvfx/animation-ir';
+import type { ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
+import type { GEParticleSourceData, GEToIRPreservedData } from '../preserved-data';
+/** Extract source bindings and layout metadata needed to place restored ParticleSystems in a host scene. */
+export declare function extractGEParticleSourceData(scene: IRScene, preservedData: GEToIRPreservedData, diagnostics: ConversionDiagnostic[]): GEParticleSourceData;

package/dist/ge2ir/mapping.d.ts

@@ -0,0 +1,5 @@
+import { IRBlendMode, IREndBehavior, type IRLayerTime } 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, compositionInPoint?: number): IRLayerTime;

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

@@ -1,4 +1,4 @@
-import type { IRAnimatedProperty, IRTransformChannels } from '@vvfx/animation-ir';
+import type { IRAnimatedProperty, IRTransform } from '@vvfx/animation-ir';
 import type { GESceneContext } from '../types';
-export declare function parseTransformAnimation(asset: Record<string, unknown>, startFrame: number, endFrame: number, ctx: GESceneContext): Partial<IRTransformChannels>;
+export declare function parseTransformAnimation(asset: Record<string, unknown>, startFrame: number, endFrame: number, ctx: GESceneContext): Partial<IRTransform>;
 export declare function parseOpacityAnimation(asset: Record<string, unknown>, startFrame: number, endFrame: number): IRAnimatedProperty<number> | undefined;

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

@@ -0,0 +1,22 @@
+import type { IRBlendMode, IRColor, IRLocalBounds, IRParticleContent, IRShape, IRTextContent } from '@vvfx/animation-ir';
+import type { GESceneContext } from '../types';
+import type { EffectsSpriteSplit, EffectsTextSizeMode, EffectsTextureSheetAnimation } from '../../preserved-data';
+interface ParsedComponentData {
+    type: 'image' | 'solid' | 'text' | 'shape' | 'particle';
+    imageAssetId?: string;
+    spriteStartColor?: IRColor;
+    text?: IRTextContent;
+    textBounds?: IRLocalBounds;
+    shapes?: IRShape[];
+    blendMode?: IRBlendMode;
+    anchorScale?: [number, number];
+    spriteSplits?: EffectsSpriteSplit[];
+    textureSheetAnimation?: EffectsTextureSheetAnimation;
+    textSizeMode?: EffectsTextSizeMode;
+    GEComponentId?: string;
+    rawMask?: Record<string, unknown>;
+    particle?: IRParticleContent;
+    rawParticleContent?: Record<string, unknown>;
+}
+export declare function parseComponent(item: Record<string, unknown>, ctx: GESceneContext): ParsedComponentData | undefined;
+export {};

package/dist/ge2ir/{parsers/keyframe-parser.d.ts → parser/keyframe.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/parser/layer.d.ts

@@ -0,0 +1,13 @@
+import { type IRLayer } from '@vvfx/animation-ir';
+import type { GESceneContext } from '../types';
+import type { EffectsLayerPreservedData } from '../../preserved-data';
+export interface ParsedItemLayer {
+    layer: IRLayer;
+    preservedData: EffectsLayerPreservedData;
+}
+/** Parse one GE item and its referenced component data into an IR layer. */
+export declare function parseItemToLayer(item: Record<string, unknown>, itemId: string, ctx: GESceneContext): ParsedItemLayer | undefined;
+export declare function readItemSize(itemTransform: Record<string, unknown> | undefined): {
+    x: number;
+    y: number;
+} | undefined;

package/dist/ge2ir/parser/parse-particle-component.d.ts

@@ -0,0 +1,7 @@
+import type { IRParticleContent } from '@vvfx/animation-ir';
+export interface ParsedGEParticleComponent {
+    particle: IRParticleContent;
+    rawParticleContent: Record<string, unknown>;
+    normalizedBurstRuntimeDefaults: boolean;
+}
+export declare function parseParticleComponent(component: Record<string, unknown>, frameRate: number): ParsedGEParticleComponent | undefined;

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

@@ -0,0 +1,4 @@
+import { type ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
+import type { GEAssetRegistry, GEToIROptions, GESceneContext } from '../types';
+export declare function buildSceneContext(scene: Record<string, unknown>, options: GEToIROptions, compositionId?: string, compositionIdBySourceId?: ReadonlyMap<string, string>, compositionStartFrameBySourceId?: ReadonlyMap<string, number>, assetRegistry?: GEAssetRegistry, diagnostics?: ConversionDiagnostic[]): GESceneContext;
+export declare function getCompositionItemIds(scene: Record<string, unknown>, compositionId?: string): 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;
+    activationEndBehavior?: 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/parser/transform.d.ts

@@ -0,0 +1,3 @@
+import type { IRTransform } from '@vvfx/animation-ir';
+import type { GESceneContext } from '../types';
+export declare function parseStaticTransform(itemTransform: Record<string, unknown>, ctx: GESceneContext): Partial<IRTransform>;

package/dist/ge2ir/post-process/mask.d.ts

@@ -0,0 +1,10 @@
+import type { ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
+import type { RawLayerDescriptor } from '../post-process';
+import type { GESceneContext } from '../types';
+export interface GEMaskNormalizationComposition {
+    sourceCompositionId: string;
+    ctx: GESceneContext;
+    descriptors: RawLayerDescriptor[];
+}
+/** Normalize GE component mask references into Layer mattes or a strict cross-Composition path fallback. */
+export declare function normalizeSingleGEMasks(compositions: GEMaskNormalizationComposition[], diagnostics: ConversionDiagnostic[]): void;

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

@@ -1,9 +1,11 @@
-import type { IRLayerNode } from '@vvfx/animation-ir';
-import type { GESceneContext } from '../types';
+import type { IRLayer } from '@vvfx/animation-ir';
+import type { GESceneContext } from './types';
+import type { EffectsLayerPreservedData } from '../preserved-data';
 export interface RawLayerDescriptor {
     itemId: string;
     item: Record<string, unknown>;
-    layer: IRLayerNode;
+    layer: IRLayer;
+    preservedData: EffectsLayerPreservedData;
 }
 export declare function mergeNullSpritePairs(descriptors: RawLayerDescriptor[], ctx: GESceneContext): RawLayerDescriptor[];
 export declare function resolveHierarchy(descriptors: RawLayerDescriptor[], ctx: GESceneContext): void;

package/dist/ge2ir/types.d.ts

@@ -1,10 +1,25 @@
-import type { IRColor, IREndBehavior } from '@vvfx/animation-ir';
-import type { GEPoolIndex } from '../shared/types';
-export interface GE2IROptions {
+import type { IRColor, IREndBehavior, IRFontAsset, IRImageAsset } from '@vvfx/animation-ir';
+import type { ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
+import type { GESceneCollectionIndex } from '../common/data-path';
+/** Options for converting a GE scene to IR. */
+export interface GEToIROptions {
     frameRate: number;
+    resourceBaseUrl?: string;
+}
+export interface GEAssetRegistry {
+    imageAssetById: Map<string, IRImageAsset>;
+    imageAssetIdBySourceId: Map<string, string>;
+    fontAssetById: Map<string, IRFontAsset>;
+    fontAssetIdByIdentity: Map<string, string>;
 }
-export type { GE2IRPassthroughMetadata } from '../shared/ge2ir-metadata';
 export interface GESceneContext {
+    diagnostics: ConversionDiagnostic[];
+    compositionId: string;
+    irCompositionId: string;
+    compositionIdBySourceId: ReadonlyMap<string, string>;
+    compositionStartFrameBySourceId: ReadonlyMap<string, number>;
+    compositionStartTime: number;
+    resourceBaseUrl?: string;
     width: number;
     height: number;
     frameRate: number;
@@ -12,13 +27,18 @@ export interface GESceneContext {
     duration: number;
     inPoint: number;
     outPoint: number;
-    compositionName: string;
-    endBehavior?: IREndBehavior;
+    compositionName?: string;
+    endBehavior: IREndBehavior;
     backgroundColor?: IRColor;
-    itemById: GEPoolIndex;
-    componentById: GEPoolIndex;
-    miscById: GEPoolIndex;
-    imageById: GEPoolIndex;
-    textureById: GEPoolIndex;
+    itemById: GESceneCollectionIndex;
+    componentById: GESceneCollectionIndex;
+    miscById: GESceneCollectionIndex;
+    imageById: GESceneCollectionIndex;
+    textureById: GESceneCollectionIndex;
+    imageAssetById: Map<string, IRImageAsset>;
+    imageAssetIdBySourceId: Map<string, string>;
+    fontDefinitionByFamily: Map<string, Record<string, unknown>>;
+    fontAssetById: Map<string, IRFontAsset>;
+    fontAssetIdByIdentity: Map<string, string>;
     itemIdToTrackId: Map<string, string>;
 }