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

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

@@ -1,20 +1,18 @@
 /**
- * Unified IR → GE scene generation pipeline. All IR sources (lottie, dsl2ge,
- * future) are processed here. Source-specific features are gated by data
- * existence (e.g. mask, precomp, shape layers are absent in dsl IR and
- * naturally skipped); `ir.source` branches are used only for B-class real
- * semantic differences that cannot be expressed via data existence.
+ * Unified IR → GE scene generation pipeline. All IR sources (lottie, dsl,
+ * future) are processed here. Normalized animation semantics select the GE
+ * lowering plan; source-specific payloads are consulted only for fidelity
+ * restoration such as GE hierarchy, mask and precomp graphs.
  */
-import type { IRComposition } from '@vvfx/animation-ir';
+import { type IRComposition } from '@vvfx/animation-ir';
 import type { JSONScene } from '@galacean/effects-specification';
 /**
  * Convert an IR composition to a GE JSONScene.
  *
- * All IR sources (lottie, dsl2ge, future) go through this single unified
- * pipeline. Source-specific features are gated by data existence (e.g. mask,
- * precomp, shape layers are absent in dsl IR and naturally skipped);
- * `ir.source` branches are used only for B-class real semantic differences
- * that cannot be expressed via data existence.
+ * All IR sources (lottie, dsl, future) go through this single unified
+ * pipeline. Normalized animation semantics select the GE lowering plan;
+ * source-specific payloads may preserve authored GE hierarchy or restore
+ * mask and precomp graphs.
  *
  * The optional `duration` arg is a caller override; lottie2ge currently passes
  * the duration computed from the raw json upstream. When omitted, the

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

@@ -2,12 +2,12 @@ import type { IRComposition, IRLayerNode, IRShapeData } from '@vvfx/animation-ir
 import type { LayerProcessingContext } from '../types';
 export declare function buildComponent(layer: IRLayerNode, itemId: string, anchorScaleX: number, anchorScaleY: number, ctx: LayerProcessingContext): string | undefined;
 /**
- * Copy the raw GE mask object (from ge2ir passthrough metadata) onto a freshly
+ * Copy the raw GE mask object (from specific.effects passthrough) onto a freshly
  * built component, as a top-level `mask` field matching GE's structure. For a
  * mask SOURCE this carries `{isMask:true, alphaMaskEnabled}`; for a TARGET it
  * carries `{isMask:false, reference, inverted}` where `reference.id` is still
- * the stale GE1 component id — `applyGeMaskRemap` rewrites it in post-process.
- * No-op for non-ge sources (Lottie masks go through the IRLayerNode.mask path).
+ * the stale GE1 component id — `applyGEMaskRemap` rewrites it in post-process.
+ * No-op for non-GE sources (Lottie masks go through the IRLayerNode.mask path).
  */
-export declare function applyGeMask(ir: IRComposition, layer: IRLayerNode, component: Record<string, unknown>): void;
+export declare function applyGEMask(ir: IRComposition, layer: IRLayerNode, component: Record<string, unknown>): void;
 export declare function buildShapeOptions(shapeData: IRShapeData, ratio: number, ctx?: LayerProcessingContext): Record<string, unknown>;

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

@@ -4,14 +4,14 @@ import type { IRLayerNode } from '@vvfx/animation-ir';
  * the time-stretch and offset semantics from `IRTimeContext`.
  *
  * dsl-source IRs leave `stretch` and `offsetFrame` undefined, in which case
- * this collapses to `delay = startFrame / fr` and
+ * this collapses to `delay = (startFrame - compositionInPoint) / fr` and
  * `duration = (endFrame - startFrame) / fr` — exactly what dsl2ge used to
  * compute inline.
  *
  * Zero/negative durations are clamped to a 0.0001 epsilon so GE keeps the
  * activation track alive for the (degenerate) layer.
  */
-export declare function computeLayerTiming(layer: IRLayerNode, frameRate: number): {
+export declare function computeLayerTiming(layer: IRLayerNode, frameRate: number, compositionInPoint?: number): {
     delay: number;
     layerDuration: number;
 };

package/dist/ir2ge/index.d.ts

@@ -2,7 +2,7 @@ export { convertIRToGE } from './assembly/generator';
 export type { DataPath, JSONScene } from '@galacean/effects-specification';
 export { readLottieSpecific } from './ir/specific';
 export type { LottieLayerSpecific } from './ir/specific';
-export { isTransformOnlyParentLink } from './ir/parent-link';
+export { hasIndependentParentLifetime } from './ir/parent-link';
 export type { ECSCollector, GEDataPath, GEItem, GEPoolIndex, GERecord, GETransform } from '../shared/types';
 export type { ProcessedItem, TransformAnimation } from './types';
 export { assembleScene } from './assembly/scene-assembly';

package/dist/ir2ge/ir/anchor-strategy.d.ts

@@ -10,15 +10,15 @@ import type { IRComposition, IRLayerNode } from '@vvfx/animation-ir';
  *   sits at the anchor; the sprite carries the visual content and is parented
  *   to the null with an anchor-relative position.
  *
- * The split decision is read from `IRLayerNode.transformSplit` when set by the
- * producer; for lottie IR without that flag the accessor falls back to
- * runtime geometry checks (rotation/scale animation + off-center anchor).
+ * The decision is a GE lowering detail derived from source-neutral IR geometry
+ * and animation semantics. GE-originated IR may additionally preserve its
+ * original hierarchy through `specific.effects.sourceHierarchy`.
  */
-export type AnchorStrategy = {
+export type GELayerLoweringPlan = {
     kind: 'inline-anchor';
     anchorScale: [number, number];
     anchorOffset: [number, number];
 } | {
     kind: 'split-null-sprite';
 };
-export declare function getStaticAnchorBehavior(ir: IRComposition, layer: IRLayerNode): AnchorStrategy;
+export declare function planGELayerLowering(ir: IRComposition, layer: IRLayerNode): GELayerLoweringPlan;

package/dist/ir2ge/ir/layer-dimensions.d.ts

@@ -1,13 +1,7 @@
-import type { IRLayerNode } from '@vvfx/animation-ir';
+import type { IRLayerNode, IRLocalBounds } from '@vvfx/animation-ir';
 /**
- * Read the producer-baked display size from an IR layer. When the producer
- * did not resolve one, returns `fallback` (defaults to `{ 1, 1 }` — the
- * value every existing call site was using inline).
+ * Read source-neutral local bounds from an IR layer. When the producer
+ * did not resolve one, returns `fallback` (defaults to bounds at the origin
+ * with a one-pixel width and height).
  */
-export declare function getLayerDisplaySize(layer: IRLayerNode, fallback?: {
-    width: number;
-    height: number;
-}): {
-    width: number;
-    height: number;
-};
+export declare function getLayerLocalBounds(layer: IRLayerNode, fallback?: IRLocalBounds): IRLocalBounds;

package/dist/ir2ge/ir/layer-utils.d.ts

@@ -1,11 +1,11 @@
-import type { IRLayerNode } from '@vvfx/animation-ir';
+import type { IRLayerNode, IRLocalBounds } from '@vvfx/animation-ir';
 import type { IRToGETimeContext } from '../builders/bezier';
 import type { LayerProcessingContext } from '../types';
 export { computeLayerTiming } from '../builders/timing';
 export declare function computeStaticPosition(layer: IRLayerNode, ctx: LayerProcessingContext, anchorOffsetX?: number, anchorOffsetY?: number): [number, number, number];
 export declare function getStaticAnchor(layer: IRLayerNode): [number, number];
-export declare function applyScalePositionAdjust(position: [number, number, number], layer: IRLayerNode, layerWidth: number, layerHeight: number, ratio: number): [number, number, number];
-export declare function computeAnchorInfo(layer: IRLayerNode, layerWidth: number, layerHeight: number): {
+export declare function applyScalePositionAdjust(position: [number, number, number], layer: IRLayerNode, bounds: IRLocalBounds, ratio: number): [number, number, number];
+export declare function computeAnchorInfo(layer: IRLayerNode, bounds: IRLocalBounds): {
     anchorScaleX: number;
     anchorScaleY: number;
     anchorOffsetX: number;

package/dist/ir2ge/ir/parent-link.d.ts

@@ -1,15 +1,6 @@
 import type { IRLayerNode } from '@vvfx/animation-ir';
 /**
- * True when the layer's parent only inherits transform — visibility and
- * lifetime are independent of the parent's window.
- *
- * Reads `IRLayerReference.linkKind` directly. Producers that don't set the
- * field (e.g. dsl2ge) effectively get `false` here, which is the correct
- * default for "full" parent containment.
- *
- * Lottie's parser sets `linkKind: 'transform-only'` when a child's parent
- * relationship comes from `layer.parent` rather than precomp expansion;
- * `applyPostProcess` consumes this to decide whether to advance the parent's
- * activation track when the child starts earlier.
+ * True when the child lifetime is independent of its transform parent's
+ * clipping window. An omitted lifetimeMode keeps the legacy clipped default.
  */
-export declare function isTransformOnlyParentLink(layer: IRLayerNode): boolean;
+export declare function hasIndependentParentLifetime(layer: IRLayerNode): boolean;

package/dist/ir2ge/ir/specific.d.ts

@@ -2,12 +2,10 @@
  * Read-side accessors for the `IRLayerNode.specific.lottie` slot.
  *
  * The shared generator must not branch on lottie semantics directly — every
- * lottie-specific read goes through these helpers so the rest of `ir2ge` stays
+ * Lottie-specific reads go through these helpers so the rest of ir2ge stays
  * agnostic to the producing tool.
  *
- * `isTransformOnlyParentLink` used to live here, reading
- * `specific.lottie.explicitParent`. It was promoted to a generic IR field
- * (`IRLayerReference.linkKind`); the accessor now lives at `./parent-link.ts`.
+ * Parent lifetime semantics are represented directly by the generic IR relation.
  */
 import type { IRLayerNode, LottieLayerSpecific } from '@vvfx/animation-ir';
 export type { LottieLayerSpecific };

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

@@ -3,10 +3,10 @@ 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
+ * `IRLayerNode.specific.effects.mask`), 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
+ * 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
@@ -15,4 +15,4 @@ import type { ECSCollector } from '../types';
  * 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.
  */
-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/index.d.ts

@@ -21,7 +21,7 @@ export interface PostProcessState {
     height?: number;
     frameRate?: number;
     /** GE1→GE2 component-id map for remapping ge2ir mask passthrough references. */
-    geComponentIdToNewId?: Record<string, string>;
+    GEComponentIdToNewId?: Record<string, string>;
 }
 /**
  * Run post-emit mutations on the collector before `assembleScene`.

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

@@ -6,21 +6,21 @@ 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>;
+    /** Child item IDs whose lifetime is independent of the transform parent's window. */
+    independentLifetimeChildItemIds?: 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
+ * its parent's delay/duration are already finalized. For children with an
+ * independent lifetime, 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.
  */
-export declare function normalizeChildVisibilityByParentDelays({ items, miscs, processedItems, transformOnlyParentLinkItemIds, roundNumber, }: NormalizeVisibilityParams): void;
+export declare function normalizeChildVisibilityByParentDelays({ items, miscs, processedItems, independentLifetimeChildItemIds, roundNumber, }: NormalizeVisibilityParams): void;
 export {};

package/dist/ir2ge/types.d.ts

@@ -22,7 +22,7 @@ export interface TransformAnimation {
 }
 /** Per-layer context threaded through the unified layer processors. */
 export interface LayerProcessingContext {
-    /** Full IR composition; needed by shared accessors that dispatch on `ir.source`. */
+    /** Full IR composition; needed for normalized semantics and guarded fidelity payloads. */
     ir: IRComposition;
     collector: ECSCollector;
     processedItems: ProcessedItem[];

package/dist/passthrough.d.ts

@@ -0,0 +1,15 @@
+import type { EffectsCompositionSpecific, EffectsLayerSpecific, IRComposition, IRLayerNode } from '@vvfx/animation-ir';
+export type EffectsLayerSpecificInvalidationTarget = 'position' | 'rotation' | 'scale' | 'color' | 'opacity' | 'anchor' | 'mask' | 'precomp';
+/** Read GE layer passthrough data. */
+export declare function getEffectsLayerSpecific(ir: IRComposition, layer: IRLayerNode): EffectsLayerSpecific | undefined;
+/** Read GE composition passthrough data. */
+export declare function getEffectsCompositionSpecific(ir: IRComposition): EffectsCompositionSpecific | undefined;
+/**
+ * Remove raw GE values that would otherwise shadow an edited normalized field.
+ * Empty `effects` and `specific` containers are pruned so serialization stays clean.
+ */
+export declare function invalidateEffectsLayerSpecific(layer: IRLayerNode, target: EffectsLayerSpecificInvalidationTarget): (keyof EffectsLayerSpecific)[];
+/** Whether invalidating opacity would also discard a GE color animation. */
+export declare function hasEffectsColorAnimationPassthrough(layer: IRLayerNode): boolean;
+/** Whether the layer retains any raw GE animation payload. */
+export declare function hasEffectsAnimationPassthrough(layer: IRLayerNode): boolean;

package/dist/shared/json-value.d.ts

@@ -0,0 +1,2 @@
+/** Return a detached value whose runtime shape is stable across JSON persistence. */
+export declare function normalizeJsonValue<T>(value: T): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvfx/ge-ir",
-  "version": "0.0.1-beta.4",
+  "version": "0.0.1-beta.6",
   "description": "Galacean Effects and animation IR bidirectional conversion package",
   "module": "./dist/index.mjs",
   "main": "./dist/index.js",
@@ -18,7 +18,7 @@
   "dependencies": {
     "@galacean/effects-specification": "^2.8.0",
     "uuid": "^13.0.0",
-    "@vvfx/animation-ir": "0.0.1-beta.4"
+    "@vvfx/animation-ir": "0.0.1-beta.6"
   },
   "contributors": [
     {
@@ -37,6 +37,7 @@
     "build:module": "rollup -c --bundleConfigAsCjs",
     "build:declaration": "tsc -b ../animation-ir tsconfig.json --emitDeclarationOnly",
     "clean": "rimraf dist *.tsbuildinfo",
-    "test": "vitest run"
+    "test": "vitest run",
+    "verify:dist": "node scripts/verify-dist.mjs"
   }
 }

package/dist/shared/ge2ir-metadata.d.ts

@@ -1,30 +0,0 @@
-import type { IRComposition, IRLayerNode } from '@vvfx/animation-ir';
-/**
- * Round-trip passthrough contract written by ge2ir and consumed by ir2ge.
- *
- * Supported keys:
- * positionOverLifetime, rotationOverLifetime, sizeOverLifetime,
- * colorOverLifetime, geComponentId, geMask, precompRefId,
- * precompContent.
- */
-export interface GE2IRPassthroughMetadata {
-    positionOverLifetime?: Record<string, unknown>;
-    rotationOverLifetime?: Record<string, unknown>;
-    sizeOverLifetime?: Record<string, unknown>;
-    colorOverLifetime?: Record<string, unknown>;
-    geComponentId?: string;
-    geMask?: Record<string, unknown>;
-    precompRefId?: string;
-    precompContent?: Record<string, unknown>;
-}
-/**
- * Composition-level GE metadata. `sourceScene` is intentionally opaque: it is
- * used only by ir2ge to restore untouched precomp resource pools that are
- * outside the single-composition editable IR.
- */
-export interface GE2IRCompositionMetadata {
-    sourceCompositionId?: string;
-    sourceScene?: Record<string, unknown>;
-}
-export declare function readGE2IRMetadata(ir: IRComposition, layer: IRLayerNode): GE2IRPassthroughMetadata | undefined;
-export declare function readGE2IRCompositionMetadata(ir: IRComposition): GE2IRCompositionMetadata | undefined;