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

package/dist/ir2ge/assemble.d.ts

@@ -0,0 +1,9 @@
+import { type IRScene } from '@vvfx/animation-ir';
+import type { JSONScene } from '@galacean/effects-specification';
+import type { GEToIRPreservedData } from '../preserved-data';
+import type { ECSCollector, GeneratedCompositionData } from './types';
+/**
+ * Assemble a GE JSONScene from generated pools and preserved source resources.
+ * `duration` overrides the value derived from the IR frame bounds.
+ */
+export declare function assembleGEScene(irScene: IRScene, collector: ECSCollector, generatedCompositions: GeneratedCompositionData[], duration?: number, preservedData?: GEToIRPreservedData): JSONScene;

package/dist/ir2ge/convert.d.ts

@@ -0,0 +1,9 @@
+import { type IRScene } from '@vvfx/animation-ir';
+import type { IRToGEOptions, IRToGEResult } from '../conversion';
+/**
+ * Convert the entry Composition of an IR Scene to a GE JSONScene.
+ *
+ * `options.preservedData` restores compatible GE-owned data when supplied.
+ * `options.duration` overrides the range derived from the IR frame bounds.
+ */
+export declare function convertIRToGE(irScene: IRScene, options?: IRToGEOptions): IRToGEResult;

package/dist/ir2ge/converter/animation.d.ts

@@ -0,0 +1,5 @@
+import type { IRAnimatedProperty, IRLayer } from '@vvfx/animation-ir';
+import type { ColorOverLifetime } from '@galacean/effects-specification';
+import type { GEAnimationPayload, LayerGenerationContext, TransformAnimation } from '../types';
+export declare function buildTransformAnimation(layer: IRLayer, ctx: LayerGenerationContext): TransformAnimation;
+export declare function buildColorAnimation(layer: IRLayer, ctx: LayerGenerationContext, inheritedOpacity?: IRAnimatedProperty<number>): GEAnimationPayload<ColorOverLifetime> | undefined;

package/dist/ir2ge/converter/bezier.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Encode IR keyframes as GE BezierKeyframeValue payloads.
+ *
+ * Wire format:
+ * - First:  [EASE_OUT(3), [t, v, out_cp_x, out_cp_y]]
+ * - Middle: [EASE(1),     [in_cp_x, in_cp_y, t, v, out_cp_x, out_cp_y]]
+ * - Last:   [EASE_IN(2),  [in_cp_x, in_cp_y, t, v]]
+ *
+ * Time is normalized to the layer's visible frame range.
+ */
+import type { IRAnimatedProperty, IRVec3 } from '@vvfx/animation-ir';
+import { type BezierKeyframeValue } from '@galacean/effects-specification';
+export interface IRToGETimeContext {
+    /** Layer visible start frame. */
+    inFrame: number;
+    /** Layer visible end frame. */
+    outFrame: number;
+}
+interface GEPositionAnimationData {
+    /** One-dimensional timing curves in BezierKeyframeValue format. */
+    curves: BezierKeyframeValue[][];
+    /** Segment endpoints as `[[startX, startY], [endX, endY]]`. */
+    pathPoints: [[number, number], [number, number]][];
+    /** Segment control offsets as `[[outX, outY], [inX, inY]]`. */
+    controlPoints: [[number, number], [number, number]][];
+}
+/** Convert a scalar property to a single GE Bezier curve. */
+export declare function convertIRScalarKeyframesToGE(property: IRAnimatedProperty<number>, timeContext: IRToGETimeContext): BezierKeyframeValue[][] | undefined;
+/** Convert a vector property to one GE Bezier curve per dimension. */
+export declare function convertIRVectorKeyframesToGE(property: IRAnimatedProperty<IRVec3>, timeContext: IRToGETimeContext): BezierKeyframeValue[][] | undefined;
+/** Convert position keyframes to GE path, control-point, and timing payloads. */
+export declare function convertIRPositionKeyframesToGE(property: IRAnimatedProperty<IRVec3>, timeContext: IRToGETimeContext): GEPositionAnimationData | undefined;
+/** Return whether GE's compact keyframe fields are required for this property. */
+export declare function shouldUseKeyframeMode(property: IRAnimatedProperty): boolean;
+export {};

package/dist/ir2ge/converter/normalized-animation.d.ts

@@ -0,0 +1,15 @@
+import type { IRLayer } from '@vvfx/animation-ir';
+import type { ColorOverLifetime, TransformPlayableAssetData } from '@galacean/effects-specification';
+interface NormalizedAnimationContext {
+    width: number;
+    height: number;
+}
+type NormalizedTransformAnimation = Pick<TransformPlayableAssetData, 'positionOverLifetime' | 'rotationOverLifetime' | 'sizeOverLifetime'>;
+/**
+ * Encode normalized IR transform channels as GE timeline payloads without
+ * consulting composition-specific passthrough data.
+ */
+export declare function buildNormalizedTransformAnimation(layer: IRLayer, ctx: NormalizedAnimationContext): NormalizedTransformAnimation;
+/** Encode normalized IR opacity as a GE color-over-lifetime payload. */
+export declare function buildNormalizedColorAnimation(layer: IRLayer): ColorOverLifetime | undefined;
+export {};

package/dist/ir2ge/converter/opacity.d.ts

@@ -0,0 +1,8 @@
+import type { IRAnimatedProperty, IRPrecompLayer } from '@vvfx/animation-ir';
+import type { IRComposition } from '@vvfx/animation-ir';
+/** Multiply two opacity channels in one Composition time domain. */
+export declare function multiplyOpacityProperties(left: IRAnimatedProperty<number> | undefined, right: IRAnimatedProperty<number> | undefined, inFrame: number, outFrame: number): IRAnimatedProperty<number> | undefined;
+/** Map an instance opacity channel from its parent timeline into referenced Composition frames. */
+export declare function mapOpacityToReferencedComposition(opacity: IRAnimatedProperty<number> | undefined, layer: IRPrecompLayer, parent: IRComposition, referenced: IRComposition): IRAnimatedProperty<number> | undefined;
+export declare function isDefaultOpacity(opacity: IRAnimatedProperty<number> | undefined): boolean;
+export declare function hasAnimatedOpacity(opacity: IRAnimatedProperty<number> | undefined): boolean;

package/dist/ir2ge/converter/precomp.d.ts

@@ -0,0 +1,17 @@
+import { type IRAnimatedProperty, type IRComposition, type IRScene, type IRPrecompLayer } from '@vvfx/animation-ir';
+import type { ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
+interface CompositionGenerationRequest {
+    id: string;
+    ir: IRComposition;
+    inheritedOpacity?: IRAnimatedProperty<number>;
+    precompOutputIdByLayerId: Map<string, string>;
+}
+interface CompositionGenerationPlan {
+    compositionById: ReadonlyMap<string, IRComposition>;
+    requests: CompositionGenerationRequest[];
+}
+/** Plan source Compositions and the instance-specific variants required by GE. */
+export declare function buildCompositionGenerationPlan(irScene: IRScene, diagnostics: ConversionDiagnostic[]): CompositionGenerationPlan;
+/** Report GE runtime limitations that apply to a source Precomp instance. */
+export declare function collectPrecompExportDiagnostics(layer: IRPrecompLayer, compositionById: ReadonlyMap<string, IRComposition>, composition: IRComposition, diagnostics: ConversionDiagnostic[]): void;
+export {};

package/dist/ir2ge/converter/timing.d.ts

@@ -0,0 +1,9 @@
+import type { IRLayer } from '@vvfx/animation-ir';
+/**
+ * Convert a Layer activation range from parent-Composition frames to GE seconds.
+ * Precomp sourceStartFrame/stretch affect source sampling, not activation.
+ */
+export declare function computeLayerTiming(layer: IRLayer, frameRate: number, compositionInPoint?: number): {
+    delay: number;
+    layerDuration: number;
+};

package/dist/ir2ge/converter/transform.d.ts

@@ -0,0 +1,14 @@
+import type { IRLayer, IRLocalBounds } from '@vvfx/animation-ir';
+import type { IRToGETimeContext } from './bezier';
+import type { LayerGenerationContext } from '../types';
+export declare function getLayerLocalBounds(layer: IRLayer, fallback?: IRLocalBounds): IRLocalBounds;
+export declare function computeStaticPosition(layer: IRLayer, ctx: LayerGenerationContext, anchorOffsetX?: number, anchorOffsetY?: number): [number, number, number];
+export declare function getStaticAnchor(layer: IRLayer): [number, number];
+export declare function applyScalePositionAdjust(position: [number, number, number], layer: IRLayer, bounds: IRLocalBounds, ratio: number): [number, number, number];
+export declare function computeAnchorInfo(layer: IRLayer, bounds: IRLocalBounds): {
+    anchorScaleX: number;
+    anchorScaleY: number;
+    anchorOffsetX: number;
+    anchorOffsetY: number;
+};
+export declare function getTimeContext(layer: IRLayer): IRToGETimeContext;

package/dist/ir2ge/generator/build-particle-component.d.ts

@@ -0,0 +1,3 @@
+import type { IRParticleLayer } from '@vvfx/animation-ir';
+import type { LayerGenerationContext } from '../types';
+export declare function buildParticleComponent(layer: IRParticleLayer, itemId: string, anchorScaleX: number, anchorScaleY: number, ctx: LayerGenerationContext): string;

package/dist/ir2ge/generator/component-preservation.d.ts

@@ -0,0 +1,5 @@
+import type { IRLayer } from '@vvfx/animation-ir';
+import type { GeneratedComponentData, LayerGenerationContext } from '../types';
+export declare function resolveComponentId(layer: IRLayer, ctx: LayerGenerationContext): string;
+/** Copy a preserved GE mask whose target references are remapped after generation. */
+export declare function copyPreservedMaskToComponent(layer: IRLayer, component: GeneratedComponentData, ctx: LayerGenerationContext): void;

package/dist/ir2ge/generator/component.d.ts

@@ -0,0 +1,10 @@
+import type { IRLayer, IRShape, IRShapePaint, IRShapeStroke } from '@vvfx/animation-ir';
+import type { LayerGenerationContext } from '../types';
+export declare function buildComponent(layer: IRLayer, itemId: string, anchorScaleX: number, anchorScaleY: number, ctx: LayerGenerationContext): string | undefined;
+export declare function buildShapeOptions(shapeData: IRShape, ratio: number, ctx?: LayerGenerationContext, renderStyle?: ShapeRenderStyle): Record<string, unknown>;
+export interface ShapeRenderStyle {
+    fills: IRShapePaint[];
+    strokes: IRShapeStroke[];
+}
+/** Split only when GE's component-level stroke geometry would lose an authored style. */
+export declare function buildShapeRenderStyles(shape: IRShape): ShapeRenderStyle[];

package/dist/ir2ge/generator/layer-strategy.d.ts

@@ -0,0 +1,19 @@
+import type { IRLayer } from '@vvfx/animation-ir';
+import type { EffectsLayerPreservedData } from '../../preserved-data';
+/**
+ * Anchor encoding strategy.
+ *
+ * - `inline-anchor` encodes the renderer anchor and compensates item position.
+ * - `split-null-sprite` places transforms on a null parent and visual content
+ *   on an anchor-offset child.
+ * Effects passthrough data may request the source hierarchy.
+ */
+type LayerGenerationStrategy = {
+    kind: 'inline-anchor';
+    anchorScale: [number, number];
+    anchorOffset: [number, number];
+} | {
+    kind: 'split-null-sprite';
+};
+export declare function resolveLayerGenerationStrategy(layer: IRLayer, preservedData?: EffectsLayerPreservedData): LayerGenerationStrategy;
+export {};

package/dist/ir2ge/generator/layer.d.ts

@@ -0,0 +1,6 @@
+import type { IRLayer, IRPrecompLayer } from '@vvfx/animation-ir';
+import type { LayerGenerationContext } from '../types';
+export declare function appendNullLayer(layer: IRLayer, ctx: LayerGenerationContext): void;
+export declare function appendPrecompLayer(layer: IRPrecompLayer, ctx: LayerGenerationContext): void;
+export declare function appendParentLayer(layer: IRLayer, ctx: LayerGenerationContext): void;
+export declare function appendVisualLayer(layer: IRLayer, ctx: LayerGenerationContext): void;

package/dist/ir2ge/generator/timeline.d.ts

@@ -0,0 +1,8 @@
+import { type EndBehavior, ItemType } from '@galacean/effects-specification';
+import type { TransformAnimation } from '../types';
+interface TimelineTrackCollector {
+    miscs: Record<string, unknown>[];
+}
+/** Build binding, activation, transform, and supported renderer-color tracks for one Item. */
+export declare function buildTimelineTracks(collector: TimelineTrackCollector, delay: number, duration: number, endBehavior: EndBehavior, animation: TransformAnimation, itemType: ItemType, precompTimeOffset?: number): string;
+export {};

package/dist/ir2ge/map-particle-layout-to-ge-transform.d.ts

@@ -0,0 +1,30 @@
+export interface GEParticleTargetRegion {
+    width: number;
+    height: number;
+    center: readonly [x: number, y: number];
+}
+export interface ParticleLayoutMappingOptions {
+    targetRegion: GEParticleTargetRegion;
+    hostComposition: Record<string, unknown>;
+    sourceComposition: Record<string, unknown>;
+    authoringBounds: readonly [x: number, y: number, width: number, height: number];
+}
+export interface GEParticleLayoutTransform {
+    position: {
+        x: number;
+        y: number;
+        z: 0;
+    };
+    eulerHint: {
+        x: 0;
+        y: 0;
+        z: 0;
+    };
+    scale: {
+        x: number;
+        y: number;
+        z: 1;
+    };
+}
+/** Map one planned particle region from pixel layout into a GE transform. */
+export declare function mapParticleLayoutToGETransform(options: ParticleLayoutMappingOptions): GEParticleLayoutTransform;

package/dist/ir2ge/mapping.d.ts

@@ -0,0 +1,6 @@
+import { IRBlendMode, IREndBehavior, type IRLayerType } from '@vvfx/animation-ir';
+import { BlendingMode, EndBehavior, ItemType } from '@galacean/effects-specification';
+export declare function mapBlendModeToGE(blendMode: IRBlendMode | undefined): BlendingMode | undefined;
+export declare function mapEndBehaviorToGE(endBehavior: IREndBehavior): EndBehavior;
+export declare function mapLayerTypeToGETimelineItemType(type: IRLayerType): ItemType;
+export declare function mapLayerTypeToGEVFXItemType(type: IRLayerType): ItemType;

package/dist/ir2ge/post-process/cross-composition-mask.d.ts

@@ -0,0 +1,4 @@
+import type { ECSCollector, GeneratedCompositionData } from '../types';
+import { type RuntimeMaskState } from './mask';
+/** Propagate Precomp mask sources through generated Composition boundaries. */
+export declare function applyCrossCompositionMasks(generatedCompositions: GeneratedCompositionData[], collector: ECSCollector, runtimeMaskState: RuntimeMaskState): void;

package/dist/ir2ge/post-process/ge-mask-remap.d.ts

@@ -1,18 +1,6 @@
 import type { ECSCollector } from '../types';
 /**
- * Remap GE mask references after ge2ir round-trip.
- *
- * ge2ir carries each masked component's raw `mask` object verbatim (via
- * `IRLayerNode.metadata.ge2ir.geMask`), but `mask.reference.id` still points at the
- * ORIGINAL (GE1) mask-source component id, which ir2ge has regenerated. This
- * pass rewrites every target's `reference.id` from the stale GE1 id to the
- * freshly-minted GE2 component id, using the `geComponentId → newId` map built
- * during the layer walk.
- *
- * Mirrors `applyParenting`: an IR-side reference (here the stale id stored in
- * data) → map → regenerated id → written in place. Mask SOURCE components have
- * no `reference` and are skipped. Dangling references (source not regenerated —
- * e.g. dropped by the null+sprite merger) have their `mask` removed so the GE
- * runtime doesn't choke on an id that resolves to nothing.
+ * Remap preserved mask targets from source component IDs to regenerated IDs.
+ * Source masks have no reference; unresolved target masks are removed.
  */
-export declare function applyGeMaskRemap(collector: ECSCollector, geComponentIdToNewId: Record<string, string>): void;
+export declare function applyGEMaskRemap(collector: ECSCollector, GEComponentIdToNewId: Record<string, string>): void;

package/dist/ir2ge/post-process/mask-geometry.d.ts

@@ -0,0 +1,16 @@
+import { type IRMask } from '@vvfx/animation-ir';
+import type { GeneratedCompositionData, GeneratedMiscData, GeneratedVFXItemData } from '../types';
+interface Point2D {
+    x: number;
+    y: number;
+}
+/** A positive, closed mask boundary expressed in one Composition's local space. */
+export interface RuntimeMaskGeometry {
+    points: Point2D[];
+}
+export type MaskContainment = 'equal' | 'existing-contains-source' | 'source-contains-existing' | 'none';
+export declare function buildRuntimeMaskGeometry(mask: IRMask, ratio: number, coordinateOrigin: [number, number]): RuntimeMaskGeometry | undefined;
+export declare function mapMaskGeometryIntoPrecomp(geometry: RuntimeMaskGeometry | undefined, precompItem: GeneratedVFXItemData, items: GeneratedVFXItemData[], animatedItemIds: ReadonlySet<string>): RuntimeMaskGeometry | undefined;
+export declare function collectAnimatedTransformItemIds(generatedCompositions: GeneratedCompositionData[], miscs: GeneratedMiscData[]): Set<string>;
+export declare function compareMaskContainment(existing: RuntimeMaskGeometry | undefined, source: RuntimeMaskGeometry | undefined): MaskContainment;
+export {};

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

@@ -1,26 +1,33 @@
 /**
- * Mask post-process: emits a mask shape item + component for each layer that
- * carries `IRMaskData`, propagating the mask reference to the layer's renderer
- * component or — for parent layers — to descendant renderers.
- *
- * The decision to emit (per-layer) is gated solely on `layer.mask != null`,
- * so any IR producer can opt in by writing the field. Currently only lottie
- * IR has masks; dsl IR leaves `mask` undefined and this module no-ops for it.
- *
- * The lookup callbacks let each pipeline plug in its own layer-to-emitted-id
- * mapping — lottie keeps `layerToItemId`/`layerToComponentId`/`parentIndexSet`
- * during emission, dsl tracks differently. Mask handling stays generic.
- */
-import type { IRComposition } from '@vvfx/animation-ir';
-import type { ECSCollector, ProcessedItem } from '../types';
-/**
- * Pipeline-specific lookups consumed during mask emission. A pipeline that
- * never produces masks can pass stub callbacks (the iterator skips layers
- * without `mask`, so the callbacks are never invoked in that case).
+ * Generate GE mask items for masked IR layers and attach references to direct
+ * or descendant renderer components.
  */
+import { type IRComposition, type IRMask } from '@vvfx/animation-ir';
+import { type RuntimeMaskGeometry } from './mask-geometry';
+import type { ECSCollector, GeneratedItemBinding } from '../types';
+/** Resolve stable IR Layer IDs to generated items and components. */
 export interface MaskLayerLookup {
-    getItemId(layerIndex: number): string | undefined;
-    getComponentId(layerIndex: number): string | undefined;
-    isParentLayer(layerIndex: number): boolean;
+    getItemId(layerId: string): string | undefined;
+    getMaskParentItemId(layerId: string): string | undefined;
+    getMaskCoordinateOrigin(layerId: string): [number, number] | undefined;
+    getComponentId(layerId: string): string | undefined;
+    isParentLayer(layerId: string): boolean;
+}
+type MaskOrigin = 'authored' | 'clip';
+/** Internal ownership metadata for each renderer's single Runtime mask slot. */
+export interface RuntimeMaskSourceMeta {
+    origin: MaskOrigin;
+    area: number;
+    geometry?: RuntimeMaskGeometry;
+    specificity: number;
+}
+/** Shared single-mask arbitration state across every generated Composition. */
+export interface RuntimeMaskState {
+    slots: Map<string, RuntimeMaskSourceMeta>;
+    sources: Map<string, RuntimeMaskSourceMeta>;
 }
-export declare function applyMasks(ir: IRComposition, collector: ECSCollector, processedItems: ProcessedItem[], ratio: number, width: number, height: number, frameRate: number, lookup: MaskLayerLookup): void;
+export declare function createRuntimeMaskState(): RuntimeMaskState;
+export declare function applyMasks(ir: IRComposition, collector: ECSCollector, itemBindings: GeneratedItemBinding[], ratio: number, _width: number, _height: number, frameRate: number, lookup: MaskLayerLookup, compositionById?: ReadonlyMap<string, IRComposition>, runtimeMaskState?: RuntimeMaskState): void;
+/** Fold the source-neutral Mask operation and path polarity into GE's single inversion flag. */
+export declare function resolveGEMaskInverted(mask: Pick<IRMask, 'mode' | 'inverted'>): boolean;
+export {};

package/dist/ir2ge/post-process/matte.d.ts

@@ -0,0 +1,5 @@
+import { type IRComposition } from '@vvfx/animation-ir';
+import type { ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
+import type { ECSCollector } from '../types';
+/** Lower Layer-reference mattes to GE's component mask source/target relationship. */
+export declare function applyLayerMattes(ir: IRComposition, collector: ECSCollector, layerToComponentId: Readonly<Record<string, string>>, diagnostics: ConversionDiagnostic[]): void;

package/dist/ir2ge/post-process/merge-preserved-resources.d.ts

@@ -0,0 +1,3 @@
+import type { GEToIRPreservedData } from '../../preserved-data';
+/** Merge source GE objects that are outside Composition graphs regenerated from IR. */
+export declare function mergePreservedResources(generated: Record<string, unknown>, preservedData?: GEToIRPreservedData): Record<string, unknown>;

package/dist/ir2ge/post-process/parenting.d.ts

@@ -1,3 +1,3 @@
-import type { IRLayerNode } from '@vvfx/animation-ir';
-import type { GEItem } from '../types';
-export declare function applyParenting(layers: IRLayerNode[], items: GEItem[], layerToItemId: Record<number, string>, ratio: number, width: number, height: number): void;
+import type { IRLayer } from '@vvfx/animation-ir';
+import type { GeneratedVFXItemData } from '../types';
+export declare function applyParenting(layers: IRLayer[], items: GeneratedVFXItemData[], layerToItemId: Record<string, string>, ratio: number, width: number, height: number): void;

package/dist/ir2ge/post-process/pipeline.d.ts

@@ -0,0 +1,25 @@
+import type { IRComposition } from '@vvfx/animation-ir';
+import type { ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
+import type { ECSCollector, GeneratedItemBinding } from '../types';
+import type { EffectsLayerPreservedData } from '../../preserved-data';
+import { type MaskLayerLookup, type RuntimeMaskState } from './mask';
+/** Complete generation state consumed by the ordered post-processing pipeline. */
+interface PostProcessState {
+    collector: ECSCollector;
+    itemBindings: GeneratedItemBinding[];
+    compositionById: ReadonlyMap<string, IRComposition>;
+    maskLookup: MaskLayerLookup;
+    runtimeMaskState: RuntimeMaskState;
+    layerToItemId: Record<string, string>;
+    layerToComponentId: Record<string, string>;
+    ratio: number;
+    width: number;
+    height: number;
+    frameRate: number;
+    geComponentIdToNewId: Record<string, string>;
+    layerDataById: Readonly<Record<string, EffectsLayerPreservedData>>;
+    diagnostics: ConversionDiagnostic[];
+}
+/** Run ordered post-generation passes before scene assembly. */
+export declare function applyPostProcess(ir: IRComposition, state: PostProcessState): void;
+export {};

package/dist/ir2ge/post-process/visibility.d.ts

@@ -1,26 +1,22 @@
-interface ProcessedItemRef {
+import type { VFXItemData } from '@galacean/effects-specification';
+import type { GeneratedMiscData } from '../types';
+type VisibilityItem = Pick<VFXItemData, 'id' | 'delay' | 'duration' | 'parentId'>;
+interface GeneratedItemBindingRef {
     itemId: string;
-    objectBindingTrackId: string;
+    objectBindingTrackId?: string;
 }
 interface NormalizeVisibilityParams {
-    items: Record<string, unknown>[];
-    miscs: Record<string, unknown>[];
-    processedItems: ProcessedItemRef[];
-    /** Item IDs whose parent-child relationship only inherits transform, not visibility. */
-    transformOnlyParentLinkItemIds?: Set<string>;
+    items: VisibilityItem[];
+    miscs: GeneratedMiscData[];
+    itemBindings: GeneratedItemBindingRef[];
+    /** Generated item IDs corresponding to IR Layers with a Transform Parent. */
+    transformParentChildItemIds?: Set<string>;
     roundNumber: (value: number, precision: number) => number;
 }
 /**
- * Normalize child visibility delays so children never appear before their parent.
- *
- * Topologically sorts items (parent-first) so by the time we process any child
- * its parent's delay/duration are already finalized. For transform-only
- * parent-link children, we instead advance the parent's delay/duration so the
- * child can render from its own start time (GE requires the parent to be active
- * for transform inheritance, but the parent-link relationship does not propagate
- * visibility). Only the ActivationTrack clip is updated; TransformTrack
- * keyframes are normalized to the original time range and would hold their
- * first frame value if the track started earlier.
+ * Keep IR Transform Parents active across every descendant's interval, then
+ * normalize internal generated child items in parent-first order. Parent
+ * activation changes do not alter Transform keyframe time domains.
  */
-export declare function normalizeChildVisibilityByParentDelays({ items, miscs, processedItems, transformOnlyParentLinkItemIds, roundNumber, }: NormalizeVisibilityParams): void;
+export declare function normalizeChildVisibilityByParentDelays({ items, miscs, itemBindings, transformParentChildItemIds, roundNumber, }: NormalizeVisibilityParams): void;
 export {};

package/dist/ir2ge/types.d.ts

@@ -1,37 +1,68 @@
-import type { IRComposition } from '@vvfx/animation-ir';
-import type { DataPath } from '@galacean/effects-specification';
-import type { ECSCollector } from '../shared/types';
-export type { ECSCollector, GEDataPath, GEItem, GEPoolIndex, GERecord, GETransform } from '../shared/types';
-/**
- * Bookkeeping for a fully emitted item: its VFXItemData id and the
- * ObjectBindingTrack that owns its child Activation/Transform/SpriteColor
- * tracks. The optional `layerIndex` lets source-specific post-processing
- * (e.g. lottie visibility normalization) trace items back to the IR layer.
- */
-export interface ProcessedItem {
+import type { IRAnimatedProperty, IRComposition, IRFontAsset, IRImageAsset } from '@vvfx/animation-ir';
+import type { ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
+import type { ColorOverLifetime, ComponentData, DataPath, EffectsObjectData, JSONScene, PositionOverLifetime, RotationOverLifetime, SizeOverLifetime, VFXItemData } from '@galacean/effects-specification';
+import type { EffectsLayerPreservedData } from '../preserved-data';
+/** Generated item with a required transform and optional deprecated content. */
+export type GeneratedVFXItemData = Omit<VFXItemData, 'content' | 'transform'> & Partial<Pick<VFXItemData, 'content'>> & Required<Pick<VFXItemData, 'transform'>>;
+/** Generated component with specification fields and preserved extension data. */
+export type GeneratedComponentData = ComponentData & Record<string, unknown>;
+/** Generated misc object with specification fields and timeline payloads. */
+export type GeneratedMiscData = EffectsObjectData & Record<string, unknown>;
+/** Pools collected while building a GE JSONScene. */
+export interface ECSCollector {
+    images: JSONScene['images'];
+    fonts: NonNullable<JSONScene['fonts']>;
+    components: GeneratedComponentData[];
+    items: GeneratedVFXItemData[];
+    textures: NonNullable<JSONScene['textures']>;
+    miscs: GeneratedMiscData[];
+}
+/** Generated pools and bindings owned by one IR Composition. */
+export interface GeneratedCompositionData {
+    id: string;
+    ir: IRComposition;
+    itemBindings: GeneratedItemBinding[];
+    items: GeneratedVFXItemData[];
+    precompOutputIdByLayerId: ReadonlyMap<string, string>;
+}
+/** Links a generated item and its binding track to the originating IR layer. */
+export interface GeneratedItemBinding {
     itemId: string;
-    objectBindingTrackId: string;
-    layerIndex?: number;
+    objectBindingTrackId?: string;
+    layerId?: string;
 }
+/** Specification-defined GE animation data or an opaque preserved payload. */
+export type GEAnimationPayload<T> = T | Record<string, unknown>;
 /** Per-channel animation payload consumed by the timeline tracks. */
 export interface TransformAnimation {
-    positionOverLifetime?: Record<string, unknown> | null;
-    rotationOverLifetime?: Record<string, unknown> | null;
-    sizeOverLifetime?: Record<string, unknown> | null;
-    colorOverLifetime?: Record<string, unknown> | null;
+    positionOverLifetime?: GEAnimationPayload<PositionOverLifetime>;
+    rotationOverLifetime?: GEAnimationPayload<RotationOverLifetime>;
+    sizeOverLifetime?: GEAnimationPayload<SizeOverLifetime>;
+    colorOverLifetime?: GEAnimationPayload<ColorOverLifetime>;
 }
-/** Per-layer context threaded through the unified layer processors. */
-export interface LayerProcessingContext {
-    /** Full IR composition; needed by shared accessors that dispatch on `ir.source`. */
+/** Shared context for layer generation. */
+export interface LayerGenerationContext {
+    /** IR Composition used for normalized semantics. */
     ir: IRComposition;
+    layerDataById: Readonly<Record<string, EffectsLayerPreservedData>>;
+    compositionById: ReadonlyMap<string, IRComposition>;
+    inheritedOpacity?: IRAnimatedProperty<number>;
+    precompOutputIdByLayerId: ReadonlyMap<string, string>;
     collector: ECSCollector;
-    processedItems: ProcessedItem[];
-    layerToItemId: Record<number, string>;
-    layerToComponentId: Record<number, string>;
+    itemBindings: GeneratedItemBinding[];
+    layerToItemId: Record<string, string>;
+    layerToComponentId: Record<string, string>;
     textureCache: Map<string, DataPath>;
-    parentIndexSet: Set<number>;
+    imageAssetById: ReadonlyMap<string, IRImageAsset>;
+    fontAssetById: ReadonlyMap<string, IRFontAsset>;
+    parentLayerIdSet: Set<string>;
     ratio: number;
     width: number;
     height: number;
     frameRate: number;
+    diagnostics: ConversionDiagnostic[];
+    /** Visual item that owns a layer-local mask source. */
+    layerToMaskParentItemId: Record<string, string>;
+    /** Layer-local point represented by the generated mask parent's origin. */
+    layerToMaskCoordinateOrigin: Record<string, [number, number]>;
 }

package/dist/layer-preserved-data.d.ts

@@ -0,0 +1,11 @@
+import type { EffectsLayerPreservedData, GEToIRPreservedData } from './preserved-data';
+/** Normalized field whose conflicting GE-owned Layer data should be removed. */
+export type EffectsLayerPreservedDataInvalidationTarget = 'position' | 'rotation' | 'scale' | 'color' | 'opacity' | 'anchor' | 'asset' | 'mask' | 'precomp' | 'particle';
+/** Resolve GE-owned data by its scoped IR Composition and Layer identities. */
+export declare function getEffectsLayerPreservedData(preservedData: GEToIRPreservedData | undefined, compositionId: string, layerId: string): EffectsLayerPreservedData | undefined;
+/** Remove raw GE values that would otherwise shadow an edited normalized field. */
+export declare function invalidateEffectsLayerPreservedData(preservedData: GEToIRPreservedData | undefined, compositionId: string, layerId: string, target: EffectsLayerPreservedDataInvalidationTarget): (keyof EffectsLayerPreservedData)[];
+/** Whether invalidating opacity would also discard a preserved GE color animation. */
+export declare function hasEffectsColorAnimationPreservedData(layerData: EffectsLayerPreservedData | undefined): boolean;
+/** Whether the Layer retains any raw GE animation payload. */
+export declare function hasEffectsAnimationPreservedData(layerData: EffectsLayerPreservedData | undefined): boolean;

package/dist/particle/merge-particle-fragment.d.ts

@@ -0,0 +1,12 @@
+import type { ResolvedGEParticlePlacement } from './merge-particle-scenes';
+import { type ParticleFragment } from './particle-fragment';
+interface AppendParticleFragmentOptions {
+    usedIds: Set<string>;
+    itemZById: Map<string, number>;
+    wrapperItemIds: Set<string>;
+}
+/** Append one dependency-closed particle effect fragment to a GE host. */
+export declare function appendParticleFragmentToGE(hostScene: Record<string, unknown>, fragment: ParticleFragment, placement: ResolvedGEParticlePlacement, options: AppendParticleFragmentOptions): void;
+export declare function collectGEIds(value: unknown, ids?: Set<string>, visited?: WeakSet<object>): Set<string>;
+export declare function mergeGEPlayerVersion(hostScene: Record<string, unknown>, sourceScene: Record<string, unknown>): void;
+export {};

package/dist/particle/merge-particle-scenes.d.ts

@@ -0,0 +1,21 @@
+import type { JSONScene } from '@galacean/effects-specification';
+import type { GEParticleAuthoringBounds, GEToIRPreservedData } from '../preserved-data';
+/** Host-canvas placement for an effect group or one bound particle system. */
+export interface GEParticlePlacement {
+    effectGroupId: string;
+    irLayerId?: string;
+    width: number;
+    height: number;
+    position: readonly [x: number, y: number, z: number];
+}
+export interface ParticleSceneMergeInput {
+    scene: unknown;
+    preservedData: GEToIRPreservedData;
+    placements: readonly GEParticlePlacement[];
+}
+export interface ResolvedGEParticlePlacement extends GEParticlePlacement {
+    irCompositionId: string;
+    authoringBounds: Readonly<GEParticleAuthoringBounds>;
+}
+/** Merge multiple restored particle GE scenes while preserving one shared painter-order calculation. */
+export declare function mergeParticleScenes(hostScene: unknown, sources: readonly ParticleSceneMergeInput[], hostStackingOrder?: ReadonlyMap<string, number>): JSONScene;

package/dist/particle/particle-fragment.d.ts

@@ -0,0 +1,10 @@
+import type { GEToIRPreservedData } from '../preserved-data';
+import type { ResolvedGEParticlePlacement } from './merge-particle-scenes';
+export interface ParticleFragment {
+    scene: Record<string, unknown>;
+    sourceCompositionId: string;
+    rootItemIds: string[];
+}
+/** Extract one complete particle effect group from a restored GE scene. */
+export declare function buildParticleFragment(sourceScene: Record<string, unknown>, preservedData: GEToIRPreservedData, placement: ResolvedGEParticlePlacement): ParticleFragment;
+export declare function resolveCompositionRuntime(composition: Record<string, unknown>, componentById: ReadonlyMap<string, Record<string, unknown>>): Record<string, unknown>;