@vvfx/dsl-ir 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,240 @@
+# @vvfx/dsl-ir
+
+Bidirectional conversion and validation for editable DSL and source-neutral Animation IR.
+
+The package owns the DSL boundary only. Importing and exporting Galacean Effects JSONScene, including preservation of
+GE-only data, is handled by `@vvfx/ge-ir`.
+
+## Contents
+
+- [Install](#install)
+- [Usage](#usage)
+- [Data and editing boundaries](#data-and-editing-boundaries)
+- [API](#api)
+- [Project structure](#project-structure)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Install
+
+Node.js 22 or later is required.
+
+```bash
+pnpm add @vvfx/dsl-ir
+```
+
+Install `@vvfx/ge-ir` as well when working with Galacean Effects:
+
+```bash
+pnpm add @vvfx/dsl-ir @vvfx/ge-ir
+```
+
+## Usage
+
+### Convert DSL to Animation IR
+
+A DSL document created from scratch does not need preserved data:
+
+```ts
+import { convertDSLToIR, type Composition } from '@vvfx/dsl-ir';
+
+const dsl: Composition = {
+  meta: {
+    name: 'example',
+    duration: 2,
+    fps: 30,
+    width: 512,
+    height: 512,
+    loop: true,
+    background_color: null,
+  },
+  layers: [],
+};
+
+const { scene, diagnostics } = convertDSLToIR(dsl);
+```
+
+DSL timing is expressed in seconds. Animation IR timing is expressed in frames, using `dsl.meta.fps` as the frame
+rate. Adjacent animation segments may have different end and start values to represent an instantaneous reset.
+
+DSL uses the initial `position.z` as a sibling stacking value: higher values render above lower values.
+Array order does not control stacking. Equal values retain the imported order with preserved data; standalone DSL
+uses layer IDs as a deterministic tie-breaker. Imported DSL exposes painter ranks in Z, while the paired sidecar
+retains source spatial depth. Changing only Z reorders whole sibling subtrees without moving them toward the camera.
+Standalone DSL positions are placed on the IR 2D plane (`z = 0`). Animated position uses its first segment's start Z
+as a fixed rank. Editing XY on a layer with varying source depth retains depth at matching keyframe times;
+changing that position's timing or replacing it with a static position is unsupported.
+
+### Convert Animation IR to DSL
+
+`convertIRToDSL` always returns the editable DSL, diagnostics, and an `IRToDSLPreservedData` sidecar:
+
+```ts
+import { convertIRToDSL } from '@vvfx/dsl-ir';
+
+const { dsl, preservedData, diagnostics } = convertIRToDSL(scene);
+```
+
+The sidecar retains IR data and write-back relationships that DSL cannot represent completely. It is adapter-owned
+data rather than business data. It can be persisted with `JSON.stringify` and `JSON.parse`, but applications should not
+modify or depend on its internal structure.
+
+### Write edited DSL back to its source IR
+
+Pass the DSL and sidecar produced by the same conversion back to `convertDSLToIR`:
+
+```ts
+const converted = convertIRToDSL(scene);
+const editedDSL = structuredClone(converted.dsl);
+
+editedDSL.layers[0].opacity = { a: false, value: 0.5 };
+
+const { scene: updatedScene, diagnostics } = convertDSLToIR(editedDSL, {
+  preservedData: converted.preservedData,
+  onChange: change => console.info(change),
+  onWarning: warning => console.warn(warning),
+});
+```
+
+When `preservedData` is supplied, the converter applies DSL-representable changes to the retained IR snapshot while
+keeping information outside the DSL contract. `strict: true` promotes conversion warnings and unsupported edits to
+errors.
+
+### Combine with `@vvfx/ge-ir`
+
+The application coordinates the adapters and keeps their sidecars paired.
+
+```ts
+import { convertGEToIR, convertIRToGE, updateGEToIRPreservedData } from '@vvfx/ge-ir';
+import { convertIRToDSL, convertDSLToIR } from '@vvfx/dsl-ir';
+
+const ge = convertGEToIR(geScene, { frameRate: 30 });
+const dsl = convertIRToDSL(ge.scene);
+const edited = structuredClone(dsl.dsl);
+
+edited.meta.duration = 4;
+
+const updated = convertDSLToIR(edited, { preservedData: dsl.preservedData });
+const preservedData = updateGEToIRPreservedData(ge.scene, updated.scene, ge.preservedData);
+const restored = convertIRToGE(updated.scene, { preservedData });
+```
+
+### Particle layers
+
+`Composition` and `Layer` define the DSL for all layer types. Particle layers use `type: 'particle'` and the same
+transform semantics as other layers. All layers may omit `time_range`, `rotation`, `scale`, `anchor`, and
+`opacity`. Preserved write-back leaves omitted channels unchanged; fresh conversion uses composition timing and
+identity transforms. Input DSL objects are not completed or mutated. `convertIRToDSL` produces complete layers;
+`validateDSL` and `convertDSLToIR` validate and convert them through the common pipeline. `parseParticleShape` parses optional,
+read-only emitter geometry supplied by a source adapter.
+
+Applications compose source effects, target layout, model requests and GE resource restoration through public adapter APIs.
+
+## Data and editing boundaries
+
+- `@vvfx/animation-ir` is the single source of truth for Animation IR types and validation.
+- DSL is an editing-oriented subset, not a mirror of any source format schema.
+- `convertIRToDSL` expands precompositions and stores the write-back relationships in `IRToDSLPreservedData`.
+- Fidelity-preserving write-back supports field edits, deletion, and reordering of existing layers under the same
+  parent. Unsafe edits are reported through diagnostics or warnings.
+- Both conversion directions validate their IR boundary. Every successfully returned `scene` satisfies the Animation
+  IR contract.
+- External images entering Animation IR must use absolute URLs or Data URLs. DSL font families become system font
+  assets.
+  Inline SVG assets use their SVG content when `url` is omitted or empty.
+- Particle Layers use the same `convertIRToDSL` and `convertDSLToIR` workflow as other supported Layers. Editable
+  `options` and `emission` values are represented in DSL. Source adapters may also expose an optional read-only
+  `shape` block for model context; renderer, resources, and other GE-only fields remain in the GE adapter sidecar.
+- Burst `cycles` defaults to one; zero means unbounded repetition until the Layer ends. Repeated bursts require a
+  positive `interval` in seconds.
+- Particle lifetime and emission values use the DSL subset of GE `NumberExpression`: constant tag `0` and
+  random-range tag `4`. IR curves are projected with diagnostics and retained in the DSL sidecar until the
+  corresponding field is edited. A projected `shape` block is not written into Animation IR; the source adapter
+  remains responsible for restoring the original emitter geometry.
+
+Further documentation:
+
+- [DSL format](../../docs/dsl_definition.md)
+- [DSL and IR guide](../../docs/dsl-ir-guide.md)
+- [DSL and IR editing capabilities](../../docs/dsl-ir-editing-capabilities.md)
+- [DSL, IR, and GE package boundaries](../../docs/dsl-ir-ge-ir-boundary.md)
+- [Animation IR particle contract](../../docs/particle-ir-contract.md)
+
+## API
+
+### Runtime exports
+
+| Export | Purpose |
+| --- | --- |
+| `convertDSLToIR` | Convert a new DSL document to IR, or write DSL values back to retained IR |
+| `convertIRToDSL` | Convert IR to editable DSL and return the sidecar needed for write-back |
+| `validateDSL` | Validate an unknown value against the DSL contract |
+| `DSLValidationError` | Structured error thrown when conversion cannot continue |
+
+Core signatures:
+
+```ts
+function convertDSLToIR(composition: Composition, options?: ConvertDSLToIROptions): DSLToIRResult;
+
+function convertIRToDSL(scene: IRScene): IRToDSLResult;
+
+function validateDSL(dsl: unknown, options?: ValidateDSLOptions): DSLValidationResult;
+```
+
+### Type exports
+
+All public types are imported from the package root:
+
+- DSL schema: `AnimationCurve`, `AnimatedProperty`, `Asset`, `Composition`, `CompositionMeta`, `Description`, `Layer`,
+  `LLMSVGAsset`, `NumberExpression`, the `Particle*` types, `TextProperties`, `UserAsset`, and
+  `ValueType`.
+- Validation: `DSLValidationIssue`, `DSLValidationResult`, and `ValidateDSLOptions`.
+- DSL to IR: `ConvertDSLToIROptions`, `DSLToIRChange`, `DSLToIRResult`, and `DSLToIRWarning`.
+- IR to DSL: `IRToDSLPreservedData` and `IRToDSLResult`.
+
+Important result and option types:
+
+```ts
+interface IRToDSLResult {
+  dsl: Composition;
+  preservedData: IRToDSLPreservedData;
+  diagnostics: ConversionDiagnostic[];
+}
+
+interface DSLToIRResult {
+  scene: IRScene;
+  diagnostics: ConversionDiagnostic[];
+}
+
+interface ConvertDSLToIROptions {
+  preservedData?: IRToDSLPreservedData;
+  strict?: boolean;
+  onWarning?: (warning: DSLToIRWarning) => void;
+  onChange?: (change: DSLToIRChange) => void;
+}
+```
+
+## Project structure
+
+```text
+src/
+  dsl/          DSL schema and validation
+  dsl2ir/       DSL to Animation IR
+    recombine/  Preserved-data write-back into retained IR
+  ir2dsl/       Animation IR to DSL and precomposition expansion
+  common/       Value mappings shared by both directions
+```
+
+## 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/dsl-ir test
+pnpm --filter @vvfx/dsl-ir build
+```
+
+## License
+
+[MIT](./LICENSE) © 2019-present Ant Group Co., Ltd.

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

@@ -0,0 +1,6 @@
+import type { IRParticleScalarExpression } from '@vvfx/animation-ir';
+import { type NumberExpression } from '../dsl/number-expression';
+export declare function mapDSLParticleExpressionToIR(expression: NumberExpression): IRParticleScalarExpression;
+export declare function mapIRParticleExpressionToDSL(expression: IRParticleScalarExpression): NumberExpression;
+export declare function isDSLCompatibleParticleExpression(expression: IRParticleScalarExpression): boolean;
+export declare function isDSLNumberExpressionEqual(left: NumberExpression, right: NumberExpression): boolean;

package/dist/common/transform.d.ts

@@ -0,0 +1,11 @@
+import type { Layer } from '../dsl/schema';
+/** Static defaults for absent transform channels. */
+export declare const TRANSFORM_FALLBACK: {
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: [number, number, number];
+    anchor: [number, number, number];
+    opacity: number;
+};
+export declare function getLayerStackingOrder(layer: Layer): number;
+export declare function withPositionZ(position: Layer['position'], depth: number): Layer['position'];

package/dist/common/utils.d.ts

@@ -0,0 +1,19 @@
+import type { IRColor } from '@vvfx/animation-ir';
+export declare const EPSILON = 0.000001;
+export type HexColorInput = readonly [number, number, number] | readonly [number, number, number, number] | IRColor;
+/** Generate a 32-character hexadecimal UUID v4. */
+export declare function createId(): string;
+/** Convert normalized RGB(A) channels to a canonical hex color. */
+export declare function colorToHex(color: HexColorInput): string;
+/** Normalize supported hex forms for semantic comparison. */
+export declare function normalizeHex(hexColor: string): string;
+/** Compare nullable hex colors after normalization. */
+export declare function isHexEqual(leftHex: string | null | undefined, rightHex: string | null | undefined): boolean;
+export declare function isValidHexColor(value: unknown): value is string;
+export declare function hexToIRColor(hexColor: string): IRColor;
+export declare function resolveFiniteNumber(value: unknown, fallback: number): number;
+export declare function secondsToFrames(seconds: number, frameRate: number): number;
+export declare function isScalarEqual(leftValue: number, rightValue: number): boolean;
+export declare function isNumberArrayEqual(leftValues: readonly number[], rightValues: readonly number[]): boolean;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function toJSONPath(path: string): string;

package/dist/dsl/number-expression.d.ts

@@ -0,0 +1,7 @@
+export declare enum ValueType {
+    CONSTANT = 0,
+    RANDOM = 4
+}
+export type NumberExpression = ConstantNumber | RandomValue;
+export type ConstantNumber = [type: ValueType.CONSTANT, value: number];
+export type RandomValue = [type: ValueType.RANDOM, value: [min: number, max: number]];

package/dist/dsl/parse-particle-shape.d.ts

@@ -0,0 +1,2 @@
+import type { ParticleShape } from './particle-shape';
+export declare function parseParticleShape(value: unknown): ParticleShape | undefined;

package/dist/dsl/particle-shape.d.ts

@@ -0,0 +1,86 @@
+export type ParticleShapeArcMode = 0 | 1 | 2 | 3;
+export type ParticleShapeName = ParticleShape['shape'];
+/** Source expression retained only to describe emitter direction. */
+export type ParticleShapeNumberExpression = [type: number, value: unknown];
+interface ParticleShapeBase {
+    arcMode: ParticleShapeArcMode;
+    alignSpeedDirection?: boolean;
+    upDirection?: [x: number, y: number, z: number];
+    turbulenceX?: ParticleShapeNumberExpression;
+    turbulenceY?: ParticleShapeNumberExpression;
+    turbulenceZ?: ParticleShapeNumberExpression;
+}
+interface ParticleShapeNone {
+    type: 0;
+    shape: 'None';
+    turbulenceX?: ParticleShapeNumberExpression;
+    turbulenceY?: ParticleShapeNumberExpression;
+    turbulenceZ?: ParticleShapeNumberExpression;
+    upDirection?: number[];
+}
+interface ParticleShapeSphere extends ParticleShapeBase {
+    type: 1;
+    shape: 'Sphere';
+    radius: number;
+    arc: number;
+}
+interface ParticleShapeCone extends ParticleShapeBase {
+    type: 2;
+    shape: 'Cone';
+    angle: number;
+    radius: number;
+    arc: number;
+}
+interface ParticleShapeHemisphere extends ParticleShapeBase {
+    type: 3;
+    shape: 'Hemisphere';
+    radius: number;
+    arc: number;
+}
+interface ParticleShapeCircle extends ParticleShapeBase {
+    type: 4;
+    shape: 'Circle';
+    radius: number;
+    arc: number;
+}
+interface ParticleShapeDonut extends ParticleShapeBase {
+    type: 5;
+    shape: 'Donut';
+    radius: number;
+    donutRadius: number;
+    arc: number;
+}
+interface ParticleShapeRectangle extends ParticleShapeBase {
+    type: 6;
+    shape: 'Rectangle';
+    width: number;
+    height: number;
+}
+interface ParticleShapeRectangleEdge extends ParticleShapeBase {
+    type: 7;
+    shape: 'RectangleEdge';
+    width: number;
+    height: number;
+}
+interface ParticleShapeEdge extends ParticleShapeBase {
+    type: 8;
+    shape: 'Edge';
+    width: number;
+}
+export interface ParticleTextureShapeDetail {
+    width: number;
+    height: number;
+    block: [width: number, height: number];
+    anchors: number[];
+}
+interface ParticleShapeTexture extends ParticleShapeBase {
+    type: 9;
+    shape: 'Texture';
+    detail: ParticleTextureShapeDetail;
+    random: number;
+    width: number;
+    height: number;
+}
+/** Particle emitter geometry projected from a source adapter for model context. */
+export type ParticleShape = ParticleShapeNone | ParticleShapeSphere | ParticleShapeCone | ParticleShapeHemisphere | ParticleShapeCircle | ParticleShapeDonut | ParticleShapeRectangle | ParticleShapeRectangleEdge | ParticleShapeEdge | ParticleShapeTexture;
+export {};

package/dist/dsl/schema.d.ts

@@ -0,0 +1,100 @@
+import type { NumberExpression } from './number-expression';
+import type { ParticleShape } from './particle-shape';
+export interface AnimationCurve {
+    t: [number, number];
+    start: number[];
+    end: number[];
+    easing: [number, number, number, number];
+    in?: [number, number, number];
+    out?: [number, number, number];
+}
+export type AnimatedProperty = {
+    a: false;
+    value: number | number[];
+} | {
+    a: true;
+    animation: AnimationCurve[];
+};
+export interface Description {
+    self: string;
+    composite: string;
+}
+export interface UserAsset {
+    source: 'user';
+    url: string;
+    prompt: '';
+}
+export interface LLMSVGAsset {
+    source: 'llm_svg';
+    format: 'svg';
+    svg: string;
+    prompt: string;
+    url?: string;
+}
+export type Asset = UserAsset | LLMSVGAsset;
+export interface TextProperties {
+    content: string;
+    font?: string;
+    size: number;
+    color: string;
+    align?: 'left' | 'center' | 'right';
+    line_height?: number;
+    letter_spacing?: number;
+}
+export interface ParticleOptions {
+    maxCount: number;
+    startLifetime: NumberExpression;
+}
+export interface ParticleBurst {
+    time: number;
+    count: number;
+    /** Total cycles. Omitted means one cycle; zero means unbounded repetition. */
+    cycles?: number;
+    /** Seconds between repeated cycles. Required to be positive when repetition is enabled. */
+    interval?: number;
+}
+export interface ParticleEmissionProperties {
+    rateOverTime: NumberExpression;
+    bursts?: ParticleBurst[];
+}
+export interface ParticleProperties {
+    /** Read-only emitter geometry supplied by source adapters when available. */
+    shape?: ParticleShape;
+    options: ParticleOptions;
+    emission: ParticleEmissionProperties;
+}
+export interface Layer {
+    id: string;
+    name: string;
+    type: 'null' | 'layer' | 'text' | 'particle';
+    width: number;
+    height: number;
+    description: Description;
+    parent?: string | null;
+    /** Omission retains source timing during preserved write-back, otherwise uses the composition duration. */
+    time_range?: [number, number];
+    position: AnimatedProperty;
+    /** Omitted channels retain source values during preserved write-back, otherwise use identity defaults. */
+    rotation?: AnimatedProperty;
+    scale?: AnimatedProperty;
+    anchor?: AnimatedProperty;
+    opacity?: AnimatedProperty;
+    asset?: Asset;
+    text?: TextProperties;
+    particle?: ParticleProperties;
+    children?: Layer[];
+}
+export interface CompositionMeta {
+    name: string;
+    duration: number;
+    fps: number;
+    width: number;
+    height: number;
+    loop: boolean;
+    background_color?: string | null;
+}
+/** Public DSL document. Its runtime shape matches the persisted DSL JSON. */
+export interface Composition {
+    meta: CompositionMeta;
+    layers: Layer[];
+}

package/dist/dsl/validator/index.d.ts

@@ -0,0 +1,2 @@
+export { DSLValidationError, validateDSL } from './validation';
+export type { DSLValidationIssue, DSLValidationResult, ValidateDSLOptions } from './types';

package/dist/dsl/validator/labels.d.ts

@@ -0,0 +1 @@
+export declare const DSL_CODE_LABELS: Readonly<Record<string, string>>;

package/dist/dsl/validator/particle.d.ts

@@ -0,0 +1,8 @@
+type DSLRecord = Record<string, unknown>;
+export interface ParticleValidationIssue {
+    code: string;
+    message: string;
+    path: string;
+}
+export declare function lintParticle(particle: DSLRecord, layer: DSLRecord, particlePath: string): ParticleValidationIssue[];
+export {};

package/dist/dsl/validator/types.d.ts

@@ -0,0 +1,33 @@
+export type DSLSeverity = 'ERROR' | 'WARNING';
+export interface DSLLintIssue {
+    severity: DSLSeverity;
+    code: string;
+    message: string;
+    path: string;
+    layerId: string | null;
+}
+export interface DSLLintReport {
+    ok: boolean;
+    hasErrors: boolean;
+    counts: {
+        ERROR: number;
+        WARNING: number;
+    };
+    issues: DSLLintIssue[];
+}
+export interface DSLValidationIssue {
+    code: string;
+    label: string;
+    message: string;
+    path: string;
+    layerId: string | null;
+}
+export interface DSLValidationResult {
+    result: 'pass' | 'fail';
+    summary: string;
+    errors: DSLValidationIssue[];
+    warnings: DSLValidationIssue[];
+}
+export interface ValidateDSLOptions {
+    strict?: boolean;
+}

package/dist/dsl/validator/validation.d.ts

@@ -0,0 +1,15 @@
+import type { DSLLintReport, DSLValidationIssue, DSLValidationResult, ValidateDSLOptions } from './types';
+/** Lint an unnormalized DSL value while preserving issue severity. */
+export declare function lintDSL(dsl: unknown): DSLLintReport;
+/**
+ * Validate DSL and return the public validation result.
+ * Strings are interpreted as raw JSON. File-system paths are intentionally not
+ * accepted so the same validator works unchanged in Node.js and browsers.
+ */
+export declare function validateDSL(dsl: unknown, options?: ValidateDSLOptions): DSLValidationResult;
+/** Error thrown when a value cannot be used as a valid DSL composition. */
+export declare class DSLValidationError extends TypeError {
+    readonly issues: DSLValidationIssue[];
+    constructor(issues: DSLValidationIssue[]);
+    static fromValidationResult(validationResult: DSLValidationResult): DSLValidationError;
+}

package/dist/dsl2ir/assemble.d.ts

@@ -0,0 +1,3 @@
+import { type IRComposition } from '@vvfx/animation-ir';
+import type { Composition } from '../dsl/schema';
+export declare function assembleIRComposition(composition: Composition, layers: IRComposition['layers']): IRComposition;

package/dist/dsl2ir/content-conversion.d.ts

@@ -0,0 +1,11 @@
+import type { IRAsset, IRFontAsset, IRTextContent } from '@vvfx/animation-ir';
+import type { Asset } from '../dsl/schema';
+interface EstimatedTextBounds {
+    width: number;
+    height: number;
+}
+export declare function normalizeDSLFontFamily(family: string | undefined): string;
+export declare function ensureSystemFontAsset(assets: IRAsset[], family: string, style: IRFontAsset['style'], weight: number): string;
+export declare function estimateTextBounds(text: IRTextContent): EstimatedTextBounds;
+export declare function resolveAssetUrl(asset: Asset): string;
+export {};

package/dist/dsl2ir/convert-layers.d.ts

@@ -0,0 +1,4 @@
+import { type IRImageAsset, type IRFontAsset, type IRLayer } from '@vvfx/animation-ir';
+import type { Composition } from '../dsl/schema';
+/** Convert authored 2D DSL sibling groups to flat IR layers in bottom-to-top painter order. */
+export declare function convertDSLLayersToIR(composition: Composition, imageAssets?: IRImageAsset[], fontAssets?: IRFontAsset[]): IRLayer[];

package/dist/dsl2ir/convert-particle.d.ts

@@ -0,0 +1,4 @@
+import type { IRParticleBurst, IRParticleContent } from '@vvfx/animation-ir';
+import type { ParticleBurst, ParticleProperties } from '../dsl/schema';
+export declare function convertDSLParticleToIRContent(particle: ParticleProperties, frameRate: number): IRParticleContent;
+export declare function mapDSLParticleBurstsToIR(bursts: ParticleBurst[], frameRate: number): IRParticleBurst[];

package/dist/dsl2ir/convert-property.d.ts

@@ -0,0 +1,6 @@
+import type { IRAnimatedProperty, IRRotation, IRStaticProperty, IRVec3 } from '@vvfx/animation-ir';
+import type { AnimatedProperty } from '../dsl/schema';
+export declare function convertDSLPropertyToIRVec3(property: AnimatedProperty | undefined, frameRate: number, fallback: IRVec3, includeSpatialTangents?: boolean): IRAnimatedProperty<IRVec3>;
+export declare function convertDSLPropertyToStaticIRVec3(property: AnimatedProperty | undefined, fallback: IRVec3): IRStaticProperty<IRVec3>;
+export declare function convertDSLPropertyToIRNumber(property: AnimatedProperty | undefined, frameRate: number, fallback: number): IRAnimatedProperty<number>;
+export declare function convertDSLPropertyToIRRotation(property: AnimatedProperty | undefined, frameRate: number, fallback: IRVec3): IRRotation;

package/dist/dsl2ir/convert.d.ts

@@ -0,0 +1,4 @@
+import type { Composition } from '../dsl/schema';
+import type { ConvertDSLToIROptions, DSLToIRResult } from './types';
+/** Convert an editable DSL composition into a shared Animation IR scene. */
+export declare function convertDSLToIR(composition: Composition, options?: ConvertDSLToIROptions): DSLToIRResult;

package/dist/dsl2ir/recombine/compare-properties.d.ts

@@ -0,0 +1,18 @@
+import type { AnimatedProperty, Asset, Layer, TextProperties } from '../../dsl/schema';
+declare const TEXT_PROPERTY_FIELDS: readonly ["content", "font", "size", "color", "align", "line_height", "letter_spacing"];
+interface TextPropertyChange {
+    field: (typeof TEXT_PROPERTY_FIELDS)[number];
+    oldValue: TextProperties[(typeof TEXT_PROPERTY_FIELDS)[number]];
+    newValue: TextProperties[(typeof TEXT_PROPERTY_FIELDS)[number]];
+}
+/**
+ * Structural, epsilon-tolerant equality between two editable-DSL properties.
+ *
+ * Used for preserved-data change detection so writeback replaces only edited
+ * fields in the IR snapshot.
+ */
+export declare function isAnimatedPropertyEqual(leftProperty: AnimatedProperty | undefined, rightProperty: AnimatedProperty | undefined): boolean;
+export declare function collectTextPropertyChanges(baselineText: TextProperties, editedText: TextProperties): TextPropertyChange[];
+export declare function readTextProperties(layer: Layer): TextProperties | undefined;
+export declare function isAssetEqual(leftAsset: Asset, rightAsset: Asset): boolean;
+export {};

package/dist/dsl2ir/recombine/convert.d.ts

@@ -0,0 +1,5 @@
+import type { Composition } from '../../dsl/schema';
+import type { IRToDSLPreservedData } from '../../ir2dsl/types';
+import type { ConvertDSLToIROptions, DSLToIRResult } from '../types';
+/** Convert DSL to a clone of the baseline IR carried by the adapter-owned preserved data. */
+export declare function convertDSLToIRWithPreservedData(composition: Composition, preservedData: IRToDSLPreservedData, options?: ConvertDSLToIROptions): DSLToIRResult;

package/dist/dsl2ir/recombine/update-ir.d.ts

@@ -0,0 +1,6 @@
+import { type IRScene } from '@vvfx/animation-ir';
+import type { Composition } from '../../dsl/schema';
+import type { IRToDSLLayerMapping } from '../../ir2dsl/types';
+import type { ConvertDSLToIROptions } from '../types';
+/** Apply previously validated DSL to a clone of the baseline IR. */
+export declare function updateValidatedIRFromDSL(baselineScene: IRScene, editedDocument: Composition, layerMapping: IRToDSLLayerMapping, options?: ConvertDSLToIROptions): IRScene;

package/dist/dsl2ir/recombine/update-layer-order.d.ts

@@ -0,0 +1,5 @@
+import type { IRComposition } from '@vvfx/animation-ir';
+import type { Layer } from '../../dsl/schema';
+import type { DSLToIRChangeReporter } from '../types';
+/** Apply edited sibling order without changing parent relationships. */
+export declare function updateLayerOrder(updatedIR: IRComposition, editedLayers: Layer[], irLayerIdByEditedLayer: Map<Layer, string>, reportChange: DSLToIRChangeReporter, rootDSLParentId?: string): void;

package/dist/dsl2ir/recombine/update-layer.d.ts

@@ -0,0 +1,4 @@
+import type { IRLayer, IRScene } from '@vvfx/animation-ir';
+import type { Layer } from '../../dsl/schema';
+import type { DSLToIRChangeReporter, DSLToIRWarningReporter } from '../types';
+export declare function updateIRLayer(irLayer: IRLayer, irScene: IRScene, editedLayer: Layer, baselineLayer: Layer, dslPath: string, frameRate: number, strict: boolean, reportWarning: DSLToIRWarningReporter, reportChange: DSLToIRChangeReporter): void;