@vvfx/lottie2ir 0.0.1-beta.10

package/LICENSE

@@ -0,0 +1,22 @@
+MIT LICENSE
+
+Copyright (c) 2019-present Ant Group Co., Ltd. https://www.antgroup.com/
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @vvfx/lottie2ir
+
+Lottie to Animation IR converter.
+
+## Contents
+
+- [Install](#install)
+- [Usage](#usage)
+- [API](#api)
+- [Project structure](#project-structure)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Install
+
+Node.js 22 or later is required.
+
+```bash
+pnpm add @vvfx/lottie2ir
+```
+
+## Usage
+
+### Convert JSON
+
+```ts
+import { convertLottieToIR } from '@vvfx/lottie2ir';
+
+const result = convertLottieToIR(lottieJSON, {
+  resourceBaseUrl: 'https://cdn.example.com/animations/data.json',
+});
+
+console.info(result.scene.format); // animation-ir
+```
+
+`convertLottieToIR` accepts either a Lottie JSON object or a serialized JSON string. Relative image and font paths are
+resolved against the absolute `resourceBaseUrl`.
+
+### Extract ZIP input
+
+```ts
+import { convertLottieToIR, extractLottieFromZip } from '@vvfx/lottie2ir';
+
+const extracted = await extractLottieFromZip(zipArrayBuffer);
+const result = convertLottieToIR(extracted.json, { zipResources: extracted });
+```
+
+## API
+
+### `convertLottieToIR(input, options?)`
+
+- `input`: a Lottie JSON object or serialized JSON string.
+- `options.resourceBaseUrl`: absolute base URL for relative image and font paths.
+- `options.zipResources`: ZIP resource directory and Data URL map returned by `extractLottieFromZip`.
+- Returns `{ scene: IRScene; diagnostics: ConversionDiagnostic[] }` after validating the IR scene.
+
+### `extractLottieFromZip(zipData)`
+
+Accepts a ZIP `ArrayBuffer` and returns the serialized JSON, resource Data URL map, and JSON directory.
+
+### Errors
+
+`LottieConverterError` and `LOTTIE_CONVERTER_ERROR_CODES` are exported from the package root for JSON, ZIP, conversion
+pipeline, and IR validation failures.
+
+## Project structure
+
+```text
+src/
+├── convert-lottie-to-ir.ts            # Public conversion flow and IR boundary validation
+├── assemble-ir-scene.ts               # IRScene and Composition assembly
+├── extract-lottie-from-zip.ts         # Lottie JSON and resource extraction from ZIP input
+├── parser/                             # Input, layer stack, and property parsing
+├── converter/                          # Layer, asset, mask, shape, text, and transform conversion
+├── common/                             # Types, error model, and identifier generation
+└── 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/assemble-ir-scene.d.ts

@@ -0,0 +1,12 @@
+import type { LottieJSON, LottieToIRResult } from './common/conversion-types';
+interface AssembleLottieIRSceneOptions {
+    resolveResourceUrl?: (url: string) => string;
+}
+/**
+ * Assembles a Lottie animation into one root Composition plus one Composition per precomposition asset.
+ *
+ * Layer references are resolved before conversion, while image and font resources are collected into the shared Scene
+ * asset registry. Unsupported or approximated source features are returned as diagnostics.
+ */
+export declare function assembleLottieIRScene(json: LottieJSON, options?: AssembleLottieIRSceneOptions): LottieToIRResult;
+export {};

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

@@ -0,0 +1,11 @@
+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';
+interface CreateLottieDiagnosticOptions {
+    code: LottieDiagnosticCode;
+    message: string;
+    layerInd?: number;
+    featureKinds?: string[];
+}
+/** Creates a source-scoped warning for a normalized, approximated, or dropped Lottie feature. */
+export declare function createLottieDiagnostic(options: CreateLottieDiagnosticOptions): ConversionDiagnostic;
+export {};

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

@@ -0,0 +1,31 @@
+import type { IRScene } from '@vvfx/animation-ir';
+import type { ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
+import type { Animation, Layer, Asset, Text, AnimatedProperty, Shape } from '@lottie-animation-community/lottie-types';
+export type LottieJSON = Animation;
+export type LottieLayer = Layer.Value;
+export type LottieAsset = Asset.Value;
+export type LottieVisualLayer = Layer.Precomposition | Layer.SolidColor | Layer.Image | Layer.Null | Layer.Shape | Layer.Text;
+export type LottiePrecompAsset = Asset.Precomposition & {
+    w?: number;
+    h?: number;
+};
+export type LottieImageAsset = Asset.Image;
+export type LottieFont = Text.Font;
+export type LottieGradientData = AnimatedProperty.GradientColors;
+export type LottieShapeElement = Shape.Value;
+/** Resources extracted from the directory containing a Lottie JSON file in a ZIP archive. */
+export interface LottieZipResources {
+    resources: Record<string, string>;
+    dirPath: string;
+}
+export interface LottieToIROptions {
+    /** Absolute base URL used to resolve relative image and font paths. */
+    resourceBaseUrl?: string;
+    /** Resources extracted from the same ZIP archive as the Lottie JSON. */
+    zipResources?: LottieZipResources;
+}
+/** Conversion output and non-fatal diagnostics. */
+export interface LottieToIRResult {
+    scene: IRScene;
+    diagnostics: ConversionDiagnostic[];
+}

package/dist/common/converter-error.d.ts

@@ -0,0 +1,17 @@
+/** Stable error codes for public control flow. */
+export declare const LOTTIE_CONVERTER_ERROR_CODES: {
+    readonly INVALID_LOTTIE_JSON: "INVALID_LOTTIE_JSON";
+    readonly ZIP_PARSE_FAILED: "ZIP_PARSE_FAILED";
+    readonly ZIP_JSON_NOT_FOUND: "ZIP_JSON_NOT_FOUND";
+    readonly IR_VALIDATION_FAILED: "IR_VALIDATION_FAILED";
+    readonly CONVERT_PIPELINE_FAILED: "CONVERT_PIPELINE_FAILED";
+};
+export type LottieConverterErrorCode = (typeof LOTTIE_CONVERTER_ERROR_CODES)[keyof typeof LOTTIE_CONVERTER_ERROR_CODES];
+/** Error raised by Lottie parsing, conversion, and ZIP input handling. */
+export declare class LottieConverterError extends Error {
+    readonly code: LottieConverterErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(code: LottieConverterErrorCode, message: string, details?: Record<string, unknown>);
+}
+/** Normalizes an unknown failure under the caller-selected public error code. */
+export declare function normalizeToConverterError(error: unknown, fallbackCode: LottieConverterErrorCode, fallbackMessage: string, details?: Record<string, unknown>): LottieConverterError;

package/dist/common/id.d.ts

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

package/dist/convert-lottie-to-ir.d.ts

@@ -0,0 +1,10 @@
+import type { LottieJSON, LottieToIROptions, LottieToIRResult } from './common/conversion-types';
+/**
+ * Converts a Lottie JSON object or serialized JSON string to Animation IR.
+ *
+ * ZIP resources take precedence over URLs resolved through `resourceBaseUrl`. The generated Scene is validated before
+ * it is returned.
+ *
+ * @throws `LottieConverterError` when parsing, conversion, or IR validation fails.
+ */
+export declare function convertLottieToIR(input: string | LottieJSON, options?: LottieToIROptions): LottieToIRResult;

package/dist/converter/convert-lottie-image-assets.d.ts

@@ -0,0 +1,4 @@
+import { type IRImageAsset } from '@vvfx/animation-ir';
+import type { LottieImageAsset } from '../common/conversion-types';
+/** Converts Lottie image assets with resource paths into the shared IR Asset registry. */
+export declare function convertLottieImageAssets(assets: LottieImageAsset[], resolveResourceUrl?: (url: string) => string): IRImageAsset[];

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

@@ -0,0 +1,28 @@
+import { type IRLayer, type IRLayerMatte } from '@vvfx/animation-ir';
+import type { ConversionDiagnostic } from '@vvfx/animation-ir/adapter';
+import type { LottieImageAsset, LottiePrecompAsset, LottieVisualLayer } from '../common/conversion-types';
+interface CompositionFrameRange {
+    inPoint: number;
+    outPoint: number;
+}
+interface ConvertLottieLayerOptions {
+    layer: LottieVisualLayer;
+    asset?: LottieImageAsset | LottiePrecompAsset;
+    id: string;
+    parentLayerId?: string;
+    matte?: IRLayerMatte;
+    compositionRange: CompositionFrameRange;
+    precompCompositionId?: string;
+    fontAssetIdByName: ReadonlyMap<string, string>;
+}
+interface ConvertLottieLayerResult {
+    layer: IRLayer;
+    diagnostics: ConversionDiagnostic[];
+}
+/**
+ * Lowers one supported Lottie Layer after its parent, matte, and precomposition references have been resolved.
+ *
+ * Fidelity limitations are returned with the converted Layer for Scene-level diagnostic assembly.
+ */
+export declare function convertLottieLayer(options: ConvertLottieLayerOptions): ConvertLottieLayerResult;
+export {};

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

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

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

@@ -0,0 +1,17 @@
+import type { LottieShapeElement } from '../common/conversion-types';
+import type { IRShape } from '@vvfx/animation-ir';
+/** Stable diagnostic labels for unsupported Lottie shape operators. */
+export declare const SHAPE_FEATURE_LABELS: Record<string, string>;
+interface LottieShapeConversion {
+    shapes: IRShape[];
+    approximatedFeatures: string[];
+    hasRenderableGeometry: boolean;
+    unsupportedFeatures: string[];
+}
+/**
+ * Converts supported visible shape geometry into IR painter order.
+ *
+ * Top-level paints are inherited by groups that do not define their own fills or strokes.
+ */
+export declare function convertLottieShapes(shapes: LottieShapeElement[]): LottieShapeConversion;
+export {};

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

@@ -0,0 +1,20 @@
+import { type IRFontAsset, type IRLocalBounds, type IRTextContent } from '@vvfx/animation-ir';
+import type { LottieFont, LottieLayer } from '../common/conversion-types';
+interface LottieTextConversion {
+    content: IRTextContent;
+    localBounds: IRLocalBounds;
+}
+interface LottieFontAssetRegistry {
+    assets: IRFontAsset[];
+    assetIdByFontName: ReadonlyMap<string, string>;
+}
+/** Builds Font Assets for the Text Layers that participate in conversion. */
+export declare function buildLottieFontAssetRegistry(layers: LottieLayer[], fonts: LottieFont[], resolveResourceUrl?: (url: string) => string): LottieFontAssetRegistry;
+/**
+ * Converts the first Lottie Text Document keyframe and returns its IR content and local display bounds.
+ *
+ * The referenced font is resolved from the Scene-level registry. Non-text Layers and Layers without usable Text
+ * Document data return `undefined`.
+ */
+export declare function convertLottieText(layer: LottieLayer, fontAssetIdByName: ReadonlyMap<string, string>): LottieTextConversion | undefined;
+export {};

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

@@ -0,0 +1,10 @@
+import type { IRTransform } from '@vvfx/animation-ir';
+import type { LottieVisualLayer } from '../common/conversion-types';
+export declare function hasAnimatedAnchor(layer: LottieVisualLayer): boolean;
+/**
+ * Converts Lottie transform properties and keyframes to IR units and tangent ownership.
+ *
+ * Scale and opacity percentages become normalized factors. Animated anchors use their first keyframe because IR anchors
+ * are static.
+ */
+export declare function convertLottieTransform(layer: LottieVisualLayer): IRTransform;

package/dist/extract-lottie-from-zip.d.ts

@@ -0,0 +1,11 @@
+import type { LottieZipResources } from './common/conversion-types';
+/**
+ * Extracts Lottie JSON and supported image or font resources from a ZIP archive.
+ *
+ * Resource Data URLs are keyed by archive path, and `dirPath` identifies the JSON file's parent directory.
+ *
+ * @throws `LottieConverterError` when the archive is invalid or contains no JSON file.
+ */
+export declare function extractLottieFromZip(zipData: ArrayBuffer): Promise<LottieZipResources & {
+    json: string;
+}>;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { convertLottieToIR } from './convert-lottie-to-ir';
+export { extractLottieFromZip } from './extract-lottie-from-zip';
+export { LottieConverterError, LOTTIE_CONVERTER_ERROR_CODES } from './common/converter-error';
+export type { LottieConverterErrorCode } from './common/converter-error';
+export type { LottieJSON, LottieToIROptions, LottieToIRResult, LottieZipResources, } from './common/conversion-types';