@vvfx/lottie2ir 0.0.1-beta.10 → 0.0.1-beta.12

package/README.md

@@ -1,19 +1,21 @@
 # @vvfx/lottie2ir
 
+English | [简体中文](./README-zh_CN.md)
+
 Lottie to Animation IR converter.
 
 ## Contents
 
 - [Install](#install)
 - [Usage](#usage)
+- [Input capabilities](#input-capabilities)
 - [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/lottie2ir
@@ -45,6 +47,43 @@ const extracted = await extractLottieFromZip(zipArrayBuffer);
 const result = convertLottieToIR(extracted.json, { zipResources: extracted });
 ```
 
+## Input capabilities
+
+This matrix describes Lottie import into Animation IR. Supported means the listed subset is converted; partial means
+some values are approximated or omitted. GE export through `@vvfx/ge-ir` has additional limits.
+
+| Capability | Status | Behavior |
+| --- | --- | --- |
+| JSON object / string | Supported | Requires valid frame rate, canvas size, and in/out points. |
+| ZIP input | Supported | Extracts JSON and supported image/font files; ZIP entries become Data URLs. |
+| Layers and hierarchy | Supported | Precomp, solid, image, null, shape, and text layers; parent references. |
+| Precomp timing | Partial | Start and stretch are mapped; invalid stretch uses `1` with a warning. |
+| Transform keyframes | Partial | Position, rotation, scale, and opacity; animated anchors use the first value. |
+| Separated position | Partial | Incompatible axis timelines are sampled at combined keyframe times, with a warning. |
+| Shape geometry and paint | Partial | Paths, rectangles, ellipses, stars, polygons, fills, and strokes. |
+| Animated gradients | Partial | Only the first keyframe is retained; a warning is returned. |
+| Shape modifiers | Unsupported | Trim, repeater, merge, and other unsupported operators are omitted with warnings. |
+| Authored masks | Partial | Ordered closed static paths, full opacity, add/subtract/intersect, and inversion. |
+| Track mattes | Partial | Alpha/luminance and inversion enter IR; GE export cannot lower luminance mattes. |
+| Text | Partial | First Text Document only. Static filled point-text glyphs become vector shapes; font-based text may use estimated bounds and fallback fonts. |
+| Resource loading | Partial | Resolves URLs or ZIP data; conversion does not fetch external images or fonts. |
+| Expressions, effects, 3D | Unsupported | No expression evaluator, general effect pipeline, or 3D scene conversion. |
+
+Inspect `result.diagnostics`: examples include `LOTTIE_UNSUPPORTED_LAYER_TYPE`, `LOTTIE_UNSUPPORTED_SHAPE_FEATURE`,
+`LOTTIE_UNSUPPORTED_MASK`, `LOTTIE_ANIMATED_ANCHOR_FALLBACK`, and `LOTTIE_ANIMATED_GRADIENT_FALLBACK`.
+Masks retain source order in `layer.masks[]`. A stack containing animated, open, non-opaque, or unsupported entries
+is dropped as a whole with `LOTTIE_UNSUPPORTED_MASK`. GE export has separate limits on Add unions.
+Embedded `chars` preserve glyph contours, advance widths, tracking, alignment, and line spacing as IR Shape layers.
+These layers retain their transforms and parenting but are no longer editable text. Missing glyphs, paragraph boxes,
+strokes, animated glyphs, and unsupported outline operators fall back to font-based text with
+`LOTTIE_UNSUPPORTED_TEXT_GLYPHS`.
+Duplicate layer indices produce `LOTTIE_DUPLICATE_LAYER_INDEX`; parent references retain lottie-web's source-order
+transform multiplication through private null layers, without changing the visible parents.
+Children active outside an ancestor's visibility interval also use independent transform nodes, so the ancestor's
+animation continues to affect them while its own content keeps its authored display interval.
+Text animation and unrecognized fields do not all have dedicated diagnostics; an empty array does not prove fidelity.
+Invalid JSON, ZIP parsing, conversion, or IR validation failures throw `LottieConverterError`.
+
 ## API
 
 ### `convertLottieToIR(input, options?)`
@@ -76,16 +115,6 @@ src/
 └── index.ts                            # Stable public entry
 ```
 
-## Contributing
-
-Use repository issues for questions and bug reports. Pull requests are welcome. Run the following checks after changing
-conversion behavior:
-
-```bash
-pnpm --filter @vvfx/lottie2ir test
-pnpm --filter @vvfx/lottie2ir build
-```
-
 ## License
 
 [MIT](./LICENSE) © 2019-present Ant Group Co., Ltd.

package/dist/common/conversion-diagnostic.d.ts

@@ -1,5 +1,5 @@
 import type { ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
-type LottieDiagnosticCode = 'unsupported-layer-type' | 'unsupported-shape-type' | 'unsupported-shape-feature' | 'unsupported-mask' | 'unsupported-track-matte' | 'missing-font' | 'missing-image-asset' | 'missing-text-data' | 'invalid-stretch-ratio' | 'separated-position-fallback' | 'animated-anchor-fallback' | 'animated-gradient-fallback';
+type LottieDiagnosticCode = 'unsupported-layer-type' | 'unsupported-shape-type' | 'unsupported-shape-feature' | 'unsupported-mask' | 'unsupported-track-matte' | 'missing-font' | 'missing-image-asset' | 'missing-text-data' | 'invalid-stretch-ratio' | 'separated-position-fallback' | 'animated-anchor-fallback' | 'animated-gradient-fallback' | 'duplicate-layer-index' | 'unsupported-text-glyphs';
 interface CreateLottieDiagnosticOptions {
     code: LottieDiagnosticCode;
     message: string;

package/dist/converter/convert-lottie-layer.d.ts

@@ -1,6 +1,7 @@
 import { type IRLayer, type IRLayerMatte } from '@vvfx/animation-ir';
+import type { Text } from '@lottie-animation-community/lottie-types';
 import type { ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
-import type { LottieImageAsset, LottiePrecompAsset, LottieVisualLayer } from '../common/conversion-types';
+import type { LottieFont, LottieImageAsset, LottiePrecompAsset, LottieVisualLayer } from '../common/conversion-types';
 interface CompositionFrameRange {
     inPoint: number;
     outPoint: number;
@@ -14,6 +15,8 @@ interface ConvertLottieLayerOptions {
     compositionRange: CompositionFrameRange;
     precompCompositionId?: string;
     fontAssetIdByName: ReadonlyMap<string, string>;
+    fonts: LottieFont[];
+    chars?: Text.CharacterData[];
 }
 interface ConvertLottieLayerResult {
     layer: IRLayer;

package/dist/converter/convert-lottie-mask.d.ts

@@ -1,8 +1,8 @@
 import { type IRMask } from '@vvfx/animation-ir';
 interface LottieMaskConversion {
-    mask?: IRMask;
+    masks: IRMask[];
     unsupportedFeatures: string[];
 }
-/** Converts one supported authored Mask and reports features that prevent conversion. */
-export declare function convertLottieMask(maskInfo: unknown): LottieMaskConversion;
+/** Converts the ordered authored Mask stack and reports features that prevent conversion. */
+export declare function convertLottieMasks(maskInfo: unknown): LottieMaskConversion;
 export {};

package/dist/converter/convert-lottie-text-glyphs.d.ts

@@ -0,0 +1,5 @@
+import type { IRShape } from '@vvfx/animation-ir';
+import type { Text } from '@lottie-animation-community/lottie-types';
+import type { LottieFont, LottieVisualLayer } from '../common/conversion-types';
+/** Embedded glyph paths use 100-unit font coordinates, independent of the exported font size. */
+export declare function convertLottieTextGlyphs(layer: LottieVisualLayer, fonts: LottieFont[], chars: Text.CharacterData[]): IRShape[] | undefined;