@vvfx/ge-ir 0.0.1-beta.10 → 0.0.1-beta.12

package/README.md

@@ -1,5 +1,7 @@
 # @vvfx/ge-ir
 
+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
@@ -9,16 +11,16 @@ for fidelity-preserving export. Applications compose this adapter with `@vvfx/ds
 
 - [Install](#install)
 - [Usage](#usage)
+- [Input capabilities](#input-capabilities)
 - [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.
+Node.js 24 or later is required.
 
 ```bash
 pnpm add @vvfx/ge-ir
@@ -58,47 +60,51 @@ 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.
+Source GE may omit an unused `animations` collection; when present, it must be an array.
 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.
+### Convert a complete DSL with particle sources
 
-### Merge restored particle GE scenes
-
-The caller restores particle scenes through `convertIRToGE`, then merges them into a host GE scene:
+Pass the complete DSL to `convertDSLToIR`. Bind its particle placeholders to the paired source DSL sidecar;
+ordinary layers are authored in the same conversion. This example uses a source with one root particle layer and
+a `fullDSL` containing the target layer ID `target-particle`:
 
 ```ts
-import { mergeParticleScenes } from '@vvfx/ge-ir';
-
-const scene = mergeParticleScenes(hostScene, [{
-  scene: restoredParticleScene,
-  preservedData: particleGEPreservedData,
-  placements,
-}], hostStackingOrder);
+import { convertDSLToIR, convertIRToDSL } from '@vvfx/dsl-ir';
+import { convertGEToIR, convertIRToGE } from '@vvfx/ge-ir';
+
+const particle = convertGEToIR(particleGE, { frameRate: 30 });
+const source = convertIRToDSL(particle.scene);
+const converted = convertDSLToIR(fullDSL, {
+  particleSources: [{
+    preservedData: source.preservedData,
+    layers: { 'target-particle': source.dsl.layers[0].id },
+  }],
+});
+const exported = convertIRToGE(converted.scene, {
+  sources: converted.sourceInstances?.map(({ idMap }) => ({ ...particle, idMap })),
+});
 ```
 
-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.
+Each `particleSources` entry creates one independent IR Precomp instance. Its `layers` record maps target DSL IDs to
+source DSL IDs. Bind one system or every system in the source composition. Shared systems must have identical target
+width, height, and static position. Targets must be root particle leaves. Use separate entries for independent
+placements or repeated instances. Auxiliary layers accompany the first source system when systems are split.
 
-`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.
+Target width, height, and position place the source region; Z controls painter order with ordinary DSL layers.
+Optional `authoringBounds` defaults to the source canvas and fits proportionally without clipping. Source-local
+position and depth remain intact. Particle values, name, and supplied rotation, scale, anchor, opacity, and timing
+edit the retained source IR. Unedited curves survive. Omitted timing extends the particle and its ancestors to the
+host duration; explicit timing remains unchanged. Source frame rates are retained and the host covers source duration.
 
-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.
+`sourceInstances` returns each input `sourceIndex` and its `idMap`. For multiple sources, pair each mapping with the
+original GE import at that index. `convertIRToGE` restores and namespaces GE payloads through `options.sources`,
+reconciles edited fields, and exports once. The assembled preserved data is used internally during export.
+Inputs are not mutated.
+
+Sources require trusted GE 3.6 data and self-contained compositions. Coupled systems must stay in one instance.
+DSL and GE adapters remain independent; source selection and paired sidecars belong to the application.
 
 ### Convert Animation IR to GE
 
@@ -113,6 +119,12 @@ console.info(exported.diagnostics);
 
 `convertIRToGE` validates the IR scene before conversion. `options.duration` can override the exported duration.
 
+Exports use GE JSONScene **3.7**, with `children` on compositions and items instead of
+`CompositionComponent.items`. Timeline assets and scene bindings retain playback and painter order.
+Text uses `autoResize` and separates glyph size from item scale. Output is verified with GE Player `2.11.0-alpha.1`.
+Consumers that read the former flat item list must traverse `children`; timeline-bound items use Timeline track
+order for rendering. GE import continues to accept 3.6 input and also reads the exported 3.7 hierarchy and text units.
+
 ### Preserve GE-only data across a round trip
 
 Pass the sidecar returned by `convertGEToIR` back to `convertIRToGE` when the IR has not been edited:
@@ -127,7 +139,8 @@ const roundTripped = convertIRToGE(imported.scene, {
 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.
+animation payloads, component property tracks, camera configuration, renderer and geometry settings, masks,
+precomposition payloads, sprite metadata, particle payloads, and source hierarchy data.
 
 ### Export edited IR with retained GE data
 
@@ -159,16 +172,86 @@ const exported = convertIRToGE(updatedScene, {
 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.
 
+Changing a layer's activation interval keeps existing animation times: retained Bezier, linear, and color-gradient
+curves are rebased to the new interval. Normalized IR keyframes use the edited composition's frame rate; animations
+represented only in the GE sidecar retain their source times in seconds. Newly inserted layers follow IR painter order
+among retained layers, while GE-only items keep their source slots.
+
+## Input capabilities
+
+This matrix describes GE JSONScene import and round trips. Supported applies to the listed IR subset; partial
+requires approximation or GE-owned preserved data. Keeping a raw payload does not make it editable in IR.
+
+| Capability | Status | Behavior |
+| --- | --- | --- |
+| Scene and compositions | Supported | Imports all source compositions and resolves the entry composition. |
+| Common layers | Supported | Image, solid, text, shape, null, precomp, and valid ParticleSystem layers. |
+| Hierarchy and timing | Supported | Parent references, painter order, seconds-to-frames, and activation timing. |
+| Transform animation | Partial | Maps supported channels, including base-scale multipliers; raw encodings stay in the sidecar. |
+| GE runtime graphs | Preserved | Effect, post-processing, model/lighting, FFD, video, camera controllers, and Animator objects remain GE-owned. |
+| Component property tracks | Partial | Reconnects source component tracks and playable assets through preserved data. |
+| Camera and renderer settings | Partial | Retains source cameras, depth/render settings, and referenced geometry in preserved data. |
+| Sprite metadata | Partial | Tint, atlas splits, sampling settings, alternate image URLs, and texture sheets use preserved data. |
+| Text and shape paints | Partial | Normalizes text metrics; gradients missing endpoints are dropped with a warning. |
+| Mask references | Partial | Single resolvable masks; multiple or unresolved references remain source-specific. |
+| Precomp export | Partial | Opacity, nonzero source start, and stretch can cause diagnostics; clipping composes with masks. |
+| Particle editing | Partial | Maps supported parameters; export needs trusted source renderer, shape, and resources. |
+| Particle opacity animation | Unsupported | Static opacity is applied; animated opacity produces an export warning. |
+| Luminance matte export | Unsupported | Not generated; reports `GE_MATTE_MODE_UNSUPPORTED`. |
+| Other item / plugin types | Preserved | Items outside the mapped subset remain in the sidecar with `GE_RUNTIME_ITEM_PRESERVED`. |
+| External resources | Partial | Resolves image/font/media/binary URLs with `resourceBaseUrl`; no downloading. |
+
+Inspect `diagnostics` for `normalized`, `approximated`, `dropped`, and `unsupported` actions. Particle source layout
+without valid `previewSize` reports `GE_PARTICLE_SOURCE_LAYOUT_UNAVAILABLE`; particle import can still succeed.
+Malformed required data, a missing entry composition, invalid IR, or mismatched preserved data can throw errors.
+The converter does not guarantee arbitrary plugin payloads or every GE runtime version will round-trip unchanged.
+
+### Composition export
+
+`convertIRToGE` generates the selected `entryCompositionId` and its reachable Precomp graph. Unreferenced IR
+compositions and their items, components, and timelines are not generated. Shared references reuse a composition
+unless clipping, masks, or inherited opacity require an instance-specific variant; unused originals are not emitted
+alongside those variants. To export another root, set `entryCompositionId` to that composition before conversion.
+GE-owned resources retained through `preservedData` continue to follow the preservation rules below.
+
+### Mask export
+
+Authored `layer.masks[]`, Precomp clipping, and Layer mattes compose into GE `mask.references[]` entries shaped as
+`{ mask: { id: componentId }, inverted: boolean }`. Mask sources retain their hierarchy across compositions.
+Redundant positive masks are removed only when their geometry shares the same coordinate space.
+
+This is a breaking contract change: replace IR `mask: value` with `masks: [value]` and GE
+`mask: { reference, inverted }` with `mask: { references: [{ mask: reference, inverted }] }`.
+Import accepts legacy singular references and converts them to `references[]`; existing array references take precedence.
+Export emits only array references, without modifying caller-owned input JSON. Playback requires a Runtime that reads
+`mask.references[]`; the workbench uses GE `2.11.0-alpha.1` with matching plugins.
+
+Positive references intersect and inverted references subtract. Multiple positive Add masks require a union, which
+this Runtime model cannot express: additional positive Add entries are omitted with `GE_MASK_ADD_UNION_UNSUPPORTED`.
+GE import still keeps multiple references in the paired preserved data instead of reconstructing an authored stack.
+
 ## 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.
 
+GE-only items remain in their owning composition's preservation binding. They do not become placeholder IR Null
+layers. Additional components on editable layers and composition-level components retain their object references,
+timeline bindings, materials, shaders, geometry, binary resources, and media. Export rebuilds their hierarchy and
+painter order around regenerated IR items; it also retains scene render settings. Media and binary URLs use
+`resourceBaseUrl` when supplied, just like normalized image assets.
+
+`GE_RUNTIME_ITEM_PRESERVED` reports items whose content is retained but cannot be edited through IR. These capabilities
+require the paired `preservedData` and compatible GE Runtime/plugins; they are not portable IR feature definitions.
+Deleting or changing the type of an editable layer removes its attached runtime components. GE-only sibling items
+remain owned by the composition. Their internal parameters and animation are preserved rather than normalized.
+
 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;
+- raw position, rotation, scale, and color animation payloads, including static scale bases;
+- component property tracks and their playable assets, renderer settings, and geometry references;
+- sprite start color, texture splits, sampling settings, alternate image URLs, and texture-sheet animation settings;
+- GE item and component identities, item timing, and independent 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.
@@ -180,6 +263,11 @@ are omitted and reported as
 
 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.
+Composition bindings also retain camera configuration. Property tracks are discarded when layer type or timing changes;
+content or bounds edits invalidate property tracks, and opacity edits invalidate color tracks. Asset replacement
+invalidates texture metadata; scale edits invalidate both the raw scale curve and its base.
+Composition bindings cover imported content. Newly authored compositions do not need a source binding, while particle
+layers still require their trusted GE payload. Export retains the source minimum web player version and binary slots.
 
 ## Data boundaries
 
@@ -197,16 +285,18 @@ between the baseline and updated IR scenes; layer-level lookup and invalidation
   `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.
+- Particle random endpoints are ordered for IR validation, and curves are cropped to emitter progress `[0, 1]`.
+  Unedited parameters retain their original GE expressions to preserve evaluation and seeded random order. Negative
+  item dimensions become positive local bounds with reflection in the scale channel.
 - 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)
+- [Animation IR contract](../animation-ir/README.md)
+- [DSL adapter and editing contract](../dsl-ir/README.md)
+- [Conversion manual](../../site/public/data/manual/en/conversion.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.
@@ -253,6 +343,11 @@ interface GEToIROptions {
 interface IRToGEOptions {
   duration?: number;
   preservedData?: GEToIRPreservedData;
+  sources?: readonly {
+    scene: IRScene;
+    preservedData: GEToIRPreservedData;
+    idMap: Readonly<Record<string, string>>;
+  }[];
 }
 ```
 
@@ -265,7 +360,6 @@ reconciliation.
 | --- | --- |
 | `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 |
 
@@ -274,7 +368,6 @@ reconciliation.
 All public types are imported from the package root:
 
 - Conversion: `GEToIROptions`, `GEToIRResult`, `IRToGEOptions`, and `IRToGEResult`.
-- Particle merge: `GEParticlePlacement` and `ParticleSceneMergeInput`.
 - GE preserved data: `GEToIRPreservedData`.
 - Reconciliation: `GEToIRPreservedDataChange` and `UpdateGEToIRPreservedDataOptions`.
 
@@ -295,18 +388,6 @@ src/
   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.
-
 ## License
 
 [MIT](./LICENSE) © 2019-present Ant Group Co., Ltd.

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

@@ -5,6 +5,8 @@ export declare const DEFAULT_CAMERA_Z = 8;
 export declare const DEFAULT_CAMERA_FOV = 60;
 /** Default camera clipping mode for 2D GE scenes. */
 export declare const DEFAULT_CLIP_MODE = CameraClipMode.portrait;
+/** GE 3.7 text layout converts glyph pixels to world units before applying item scale. */
+export declare const TEXT_WORLD_UNITS_PER_PIXEL = 0.0123;
 /** Return the pixel-to-world scale for the given canvas. */
 export declare function get2dTo3dRatio(width: number, height: number): number;
 /**

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

@@ -1,3 +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;
+export declare function normalizeJSONValue<T>(value: T): T;

package/dist/common/particle-expression.d.ts

@@ -2,3 +2,5 @@ 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;
+/** Preserve GE evaluation and seeded random ordering until the normalized parameter changes. */
+export declare function restoreGEParticleScalarExpression(expression: IRParticleScalarExpression, source: unknown): unknown;

package/dist/conversion.d.ts

@@ -18,4 +18,10 @@ export interface IRToGEResult {
 export interface IRToGEOptions {
     duration?: number;
     preservedData?: GEToIRPreservedData;
+    /** Source instances and their identities in the supplied IR scene. */
+    sources?: readonly {
+        scene: IRScene;
+        preservedData: GEToIRPreservedData;
+        idMap: Readonly<Record<string, string>>;
+    }[];
 }

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

@@ -1,6 +1,6 @@
 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';
+import type { EffectsLayerPreservedData, EffectsSpriteSplit, EffectsTextSizeMode, EffectsTextureSheetAnimation } from '../../preserved-data';
 interface ParsedComponentData {
     type: 'image' | 'solid' | 'text' | 'shape' | 'particle';
     imageAssetId?: string;
@@ -11,6 +11,7 @@ interface ParsedComponentData {
     blendMode?: IRBlendMode;
     anchorScale?: [number, number];
     spriteSplits?: EffectsSpriteSplit[];
+    spriteTexture?: EffectsLayerPreservedData['spriteTexture'];
     textureSheetAnimation?: EffectsTextureSheetAnimation;
     textSizeMode?: EffectsTextSizeMode;
     GEComponentId?: string;

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

@@ -1,11 +1,13 @@
 import { EndBehavior } from '@galacean/effects-specification';
 import type { GESceneContext } from '../types';
+import type { EffectsLayerPreservedData } from '../../preserved-data';
 interface ParsedTimelineData {
-    delay: number;
-    duration: number;
+    delay?: number;
+    duration?: number;
     activationEndBehavior?: EndBehavior;
     transformAsset?: Record<string, unknown>;
     spriteColorAsset?: Record<string, unknown>;
 }
 export declare function parseTimeline(itemId: string, ctx: GESceneContext): ParsedTimelineData | undefined;
+export declare function parseComponentTimeline(componentId: string, ctx: GESceneContext): EffectsLayerPreservedData['componentTimeline'];
 export {};

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

@@ -7,4 +7,4 @@ export interface GEMaskNormalizationComposition {
     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;
+export declare function normalizeGEMasks(compositions: GEMaskNormalizationComposition[], diagnostics: ConversionDiagnostic[]): void;

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

@@ -7,5 +7,5 @@ export interface RawLayerDescriptor {
     layer: IRLayer;
     preservedData: EffectsLayerPreservedData;
 }
-export declare function mergeNullSpritePairs(descriptors: RawLayerDescriptor[], ctx: GESceneContext): RawLayerDescriptor[];
+export declare function mergeNullVisualPairs(descriptors: RawLayerDescriptor[], ctx: GESceneContext): RawLayerDescriptor[];
 export declare function resolveHierarchy(descriptors: RawLayerDescriptor[], ctx: GESceneContext): void;

package/dist/ge2ir/preserve-scene.d.ts

@@ -0,0 +1,2 @@
+/** Resolve adapter-owned resources against the same base as normalized IR assets. */
+export declare function preserveSourceScene(scene: Record<string, unknown>, resourceBaseUrl?: string): Record<string, unknown>;

package/dist/ge2ir/types.d.ts

@@ -24,10 +24,12 @@ export interface GESceneContext {
     height: number;
     frameRate: number;
     ratio: number;
+    textScaleIncludesSize?: boolean;
     duration: number;
     inPoint: number;
     outPoint: number;
     compositionName?: string;
+    camera?: Record<string, unknown>;
     endBehavior: IREndBehavior;
     backgroundColor?: IRColor;
     itemById: GESceneCollectionIndex;

package/dist/index.d.ts

@@ -2,10 +2,7 @@ export { convertIRToGE } from './ir2ge/convert';
 export { convertGEToIR } from './ge2ir/convert';
 export type { GEToIRResult, IRToGEOptions, IRToGEResult } from './conversion';
 export type { GEToIRPreservedData } from './preserved-data';
-export type { GEParticlePlacement } from './particle/merge-particle-scenes';
 export { get2dTo3dRatio } from './common/coordinate-mapping';
 export { updateGEToIRPreservedData } from './update-preserved-data';
 export type { GEToIROptions } from './ge2ir/types';
 export type { GEToIRPreservedDataChange, UpdateGEToIRPreservedDataOptions } from './update-preserved-data';
-export { mergeParticleScenes } from './particle/merge-particle-scenes';
-export type { ParticleSceneMergeInput } from './particle/merge-particle-scenes';