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

package/README.md

@@ -1,5 +1,7 @@
 # @vvfx/dsl-ir
 
+English | [简体中文](./README-zh_CN.md)
+
 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
@@ -12,12 +14,11 @@ GE-only data, is handled by `@vvfx/ge-ir`.
 - [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.
+Node.js 24 or later is required.
 
 ```bash
 pnpm add @vvfx/dsl-ir
@@ -55,7 +56,10 @@ 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.
+rate. Frame rates and canvas dimensions accept finite positive fractional values. Adjacent animation segments may have different end and start values to represent an instantaneous reset.
+
+Preserved write-back retains each source composition's frame rate unless `meta.fps` is edited. An explicit FPS edit
+resamples all compositions to the requested rate while preserving durations and precomposition source offsets in seconds.
 
 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
@@ -97,8 +101,10 @@ const { scene: updatedScene, diagnostics } = convertDSLToIR(editedDSL, {
 ```
 
 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.
+keeping information outside the DSL contract. Warnings do not stop conversion. Edits that can be safely ignored, such as
+new layers or type changes, are skipped and reported through diagnostics and `onWarning`; supported edits still apply.
+Invalid input, invalid preserved data, or edits that cannot retain source depth throw.
+Applications should catch conversion failures and retain their last valid scene, replacing it only after conversion succeeds.
 
 ### Combine with `@vvfx/ge-ir`
 
@@ -130,11 +136,59 @@ 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.
 
+### Convert a complete DSL with particle sources
+
+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 { 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 `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.
+
+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.
+
+`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.
+
 ## 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`.
+  Shared instances edit the same source layers. Conflicting values for one field retain that field's original value
+  with a warning; other edits apply. Deleting a shared child affects every instance and produces a warning.
+- Independent rotation axes are sampled at their combined keyframe times and linearly interpolated with a diagnostic.
+  Original easing and curves remain in the sidecar until rotation is edited.
+- Text size and line height are positive composition-pixel values; letter spacing uses the same units and may be negative.
+  Omitted line height uses the font size.
 - 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
@@ -154,11 +208,9 @@ Applications compose source effects, target layout, model requests and GE resour
 
 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)
+- [DSL schema types](./src/dsl/schema.ts)
+- [Animation IR contract](../animation-ir/README.md)
+- [GE adapter and package boundaries](../ge-ir/README.md)
 
 ## API
 
@@ -169,16 +221,18 @@ Further documentation:
 | `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 |
+| `DSLValidationError` | Structured error for invalid DSL; conversion may also throw IR validation or other errors |
+| `parseParticleShape` | Project GE-style numeric shape tags into optional read-only DSL context |
+| `ValueType` | Runtime particle expression tags: `CONSTANT = 0`, `RANDOM = 4` |
 
 Core signatures:
 
 ```ts
-function convertDSLToIR(composition: Composition, options?: ConvertDSLToIROptions): DSLToIRResult;
+function convertDSLToIR(composition: Composition, options?: DSLToIROptions): DSLToIRResult;
 
 function convertIRToDSL(scene: IRScene): IRToDSLResult;
 
-function validateDSL(dsl: unknown, options?: ValidateDSLOptions): DSLValidationResult;
+function validateDSL(dsl: unknown): DSLValidationResult;
 ```
 
 ### Type exports
@@ -188,8 +242,8 @@ 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`.
+- Validation: `DSLValidationIssue` and `DSLValidationResult`.
+- DSL to IR: `DSLToIROptions`, `DSLParticleSource`, `DSLToIRChange`, `DSLToIRResult`, and `DSLToIRWarning`.
 - IR to DSL: `IRToDSLPreservedData` and `IRToDSLResult`.
 
 Important result and option types:
@@ -202,39 +256,41 @@ interface IRToDSLResult {
 }
 
 interface DSLToIRResult {
+  sourceInstances?: { sourceIndex: number; idMap: Record<string, string> }[];
   scene: IRScene;
   diagnostics: ConversionDiagnostic[];
 }
 
-interface ConvertDSLToIROptions {
+interface DSLParticleSource {
+  preservedData: IRToDSLPreservedData;
+  layers: Readonly<Record<string, string>>;
+  authoringBounds?: readonly [x: number, y: number, width: number, height: number];
+}
+
+interface DSLToIROptions {
   preservedData?: IRToDSLPreservedData;
-  strict?: boolean;
+  particleSources?: readonly DSLParticleSource[];
   onWarning?: (warning: DSLToIRWarning) => void;
   onChange?: (change: DSLToIRChange) => void;
 }
 ```
 
+TypeScript callers should use `Layer['position']` or `AnimatedProperty<[number, number, number]>` for vector tracks
+and `AnimatedProperty<number>` for opacity. `anchor` is static. Construct each `Layer` variant together with its required
+`asset`, `text`, or `particle` content. Zero font size and non-positive explicit line height are rejected;
+omit `line_height` to use the font size.
+
 ## Project structure
 
 ```text
 src/
-  dsl/          DSL schema and validation
+  dsl/          DSL schema, emitter shape parsing, 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/dsl/parse-particle-shape.d.ts

@@ -1,2 +1,9 @@
 import type { ParticleShape } from './particle-shape';
+/**
+ * Project a GE-style emitter shape (numeric type 0..9) into read-only DSL context.
+ * Shape names come from the type tag; missing arcMode defaults to 0. Other numeric
+ * fields retain source units. Unsupported types or invalid required fields return
+ * undefined; invalid optional fields are omitted. Direction expressions are cloned,
+ * so their payloads must be structured-cloneable. No geometry is written into IR.
+ */
 export declare function parseParticleShape(value: unknown): ParticleShape | undefined;

package/dist/dsl/schema.d.ts

@@ -1,19 +1,22 @@
 import type { NumberExpression } from './number-expression';
 import type { ParticleShape } from './particle-shape';
-export interface AnimationCurve {
+type Vector3 = [number, number, number];
+export interface AnimationCurve<T extends number | number[] = number | number[]> {
     t: [number, number];
-    start: number[];
-    end: number[];
+    start: T extends number ? [number] : T;
+    end: T extends number ? [number] : T;
+    /** Cubic Bezier [x1, y1, x2, y2] over normalized segment time and progress. */
     easing: [number, number, number, number];
+    /** Incoming/outgoing spatial offsets for position segments, in composition pixels. */
     in?: [number, number, number];
     out?: [number, number, number];
 }
-export type AnimatedProperty = {
+export type AnimatedProperty<T extends number | number[] = number | number[]> = {
     a: false;
-    value: number | number[];
+    value: T;
 } | {
     a: true;
-    animation: AnimationCurve[];
+    animation: AnimationCurve<T>[];
 };
 export interface Description {
     self: string;
@@ -35,10 +38,13 @@ export type Asset = UserAsset | LLMSVGAsset;
 export interface TextProperties {
     content: string;
     font?: string;
+    /** Font size in composition pixels; finite and greater than zero. */
     size: number;
     color: string;
     align?: 'left' | 'center' | 'right';
+    /** Absolute line height in composition pixels; greater than zero. Omission uses size. */
     line_height?: number;
+    /** Additional spacing in composition pixels, independent of size; negative values are allowed. */
     letter_spacing?: number;
 }
 export interface ParticleOptions {
@@ -63,31 +69,53 @@ export interface ParticleProperties {
     options: ParticleOptions;
     emission: ParticleEmissionProperties;
 }
-export interface Layer {
+/** Missing optional transform channels retain source values on write-back; fresh conversion uses identity defaults. */
+interface LayerBase {
     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;
+    /** XY are composition pixels; initial Z is the fixed sibling stacking rank, not spatial depth. */
+    position: AnimatedProperty<Vector3>;
+    /** Euler angles in degrees. */
+    rotation?: AnimatedProperty<Vector3>;
+    /** Unitless axis multipliers. */
+    scale?: AnimatedProperty<Vector3>;
+    /** Static anchor in layer-local pixels. */
+    anchor?: {
+        a: false;
+        value: Vector3;
+    };
+    /** Unitless opacity in [0, 1]; animated endpoints are single-element arrays. */
+    opacity?: AnimatedProperty<number>;
     asset?: Asset;
     text?: TextProperties;
     particle?: ParticleProperties;
     children?: Layer[];
 }
+export type Layer = LayerBase & ({
+    type: 'null';
+} | {
+    type: 'layer';
+    asset: Asset;
+} | {
+    type: 'text';
+    text: TextProperties;
+} | {
+    type: 'particle';
+    particle: ParticleProperties;
+});
 export interface CompositionMeta {
     name: string;
+    /** Finite positive duration in seconds. */
     duration: number;
+    /** Finite positive frames per second; fractional rates are supported. */
     fps: number;
+    /** Finite positive canvas dimensions in composition pixels; fractional sizes are supported. */
     width: number;
     height: number;
     loop: boolean;
@@ -98,3 +126,4 @@ export interface Composition {
     meta: CompositionMeta;
     layers: Layer[];
 }
+export {};

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

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

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

@@ -28,6 +28,3 @@ export interface DSLValidationResult {
     errors: DSLValidationIssue[];
     warnings: DSLValidationIssue[];
 }
-export interface ValidateDSLOptions {
-    strict?: boolean;
-}

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

@@ -1,4 +1,4 @@
-import type { DSLLintReport, DSLValidationIssue, DSLValidationResult, ValidateDSLOptions } from './types';
+import type { DSLLintReport, DSLValidationIssue, DSLValidationResult } from './types';
 /** Lint an unnormalized DSL value while preserving issue severity. */
 export declare function lintDSL(dsl: unknown): DSLLintReport;
 /**
@@ -6,7 +6,7 @@ export declare function lintDSL(dsl: unknown): DSLLintReport;
  * 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;
+export declare function validateDSL(dsl: unknown): DSLValidationResult;
 /** Error thrown when a value cannot be used as a valid DSL composition. */
 export declare class DSLValidationError extends TypeError {
     readonly issues: DSLValidationIssue[];

package/dist/dsl2ir/convert-source-instances.d.ts

@@ -0,0 +1,4 @@
+import type { Composition } from '../dsl/schema';
+import type { DSLToIROptions, DSLToIRResult } from './types';
+/** Source bindings distinguish target layout from edits to source-local emitter transforms. */
+export declare function convertDSLWithParticleSources(document: Composition, options: DSLToIROptions): DSLToIRResult;

package/dist/dsl2ir/convert.d.ts

@@ -1,4 +1,9 @@
 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;
+import type { DSLToIROptions, DSLToIRResult } from './types';
+/**
+ * Convert DSL into a new IR scene, or apply edits to its paired preserved snapshot.
+ * Inputs are not mutated. Recoverable unsupported edits produce diagnostics.
+ * Invalid DSL throws DSLValidationError; IR validation, invalid sidecars, unsafe
+ * depth edits, and caller callbacks may throw other errors.
+ */
+export declare function convertDSLToIR(composition: Composition, options?: DSLToIROptions): DSLToIRResult;

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

@@ -1,5 +1,5 @@
 import type { Composition } from '../../dsl/schema';
 import type { IRToDSLPreservedData } from '../../ir2dsl/types';
-import type { ConvertDSLToIROptions, DSLToIRResult } from '../types';
+import type { DSLToIROptions, 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;
+export declare function convertDSLToIRWithPreservedData(composition: Composition, preservedData: IRToDSLPreservedData, options?: DSLToIROptions): DSLToIRResult;

package/dist/dsl2ir/recombine/resolve-shared-edits.d.ts

@@ -0,0 +1,11 @@
+import type { Layer } from '../../dsl/schema';
+import type { IRToDSLLayerMapping } from '../../ir2dsl/types';
+import type { DSLToIRWarningReporter } from '../types';
+interface SharedLayerEdit {
+    baseline: Layer;
+    edited: Layer | undefined;
+    path: string;
+}
+/** Resolve linked edits before mutating IR; conflicting fields retain their baseline values. */
+export declare function resolveSharedPrecompEdits(entries: SharedLayerEdit[], mapping: IRToDSLLayerMapping, reportWarning: DSLToIRWarningReporter): void;
+export {};

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

@@ -1,6 +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';
+import type { DSLToIROptions } 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;
+export declare function updateValidatedIRFromDSL(baselineScene: IRScene, editedDocument: Composition, layerMapping: IRToDSLLayerMapping, options?: DSLToIROptions): IRScene;

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

@@ -1,4 +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;
+export declare function updateIRLayer(irLayer: IRLayer, irScene: IRScene, editedLayer: Layer, baselineLayer: Layer, dslPath: string, frameRate: number, reportWarning: DSLToIRWarningReporter, reportChange: DSLToIRChangeReporter, applySupportedEdits?: boolean): void;

package/dist/dsl2ir/types.d.ts

@@ -22,9 +22,16 @@ export interface DSLToIRChange {
     note?: string;
 }
 export type DSLToIRChangeReporter = (change: DSLToIRChange) => void;
-export interface ConvertDSLToIROptions {
+/** One source group or independent particle system placed in the target DSL. */
+export interface DSLParticleSource {
+    preservedData: IRToDSLPreservedData;
+    /** Target DSL layer ID -> source DSL layer ID. */
+    layers: Readonly<Record<string, string>>;
+    authoringBounds?: readonly [x: number, y: number, width: number, height: number];
+}
+export interface DSLToIROptions {
     preservedData?: IRToDSLPreservedData;
-    strict?: boolean;
+    particleSources?: readonly DSLParticleSource[];
     onWarning?: (warning: DSLToIRWarning) => void;
     onChange?: (change: DSLToIRChange) => void;
 }
@@ -32,4 +39,9 @@ export interface ConvertDSLToIROptions {
 export interface DSLToIRResult {
     scene: IRScene;
     diagnostics: ConversionDiagnostic[];
+    /** Source identities for adapters restoring data outside the IR contract. */
+    sourceInstances?: {
+        sourceIndex: number;
+        idMap: Record<string, string>;
+    }[];
 }

package/dist/index.d.ts

@@ -2,9 +2,10 @@ export { convertDSLToIR } from './dsl2ir/convert';
 export { convertIRToDSL } from './ir2dsl/convert';
 export { DSLValidationError, validateDSL } from './dsl/validator';
 export type { AnimationCurve, AnimatedProperty, Asset, Composition, CompositionMeta, Description, Layer, LLMSVGAsset, ParticleBurst, ParticleEmissionProperties, ParticleOptions, ParticleProperties, TextProperties, UserAsset, } from './dsl/schema';
-export type { ConstantNumber, NumberExpression, RandomValue, ValueType, } from './dsl/number-expression';
+export { ValueType } from './dsl/number-expression';
+export type { ConstantNumber, NumberExpression, RandomValue, } from './dsl/number-expression';
 export type { ParticleShape, ParticleShapeArcMode, ParticleShapeName, ParticleShapeNumberExpression, ParticleTextureShapeDetail, } from './dsl/particle-shape';
-export type { DSLValidationIssue, DSLValidationResult, ValidateDSLOptions } from './dsl/validator';
-export type { ConvertDSLToIROptions, DSLToIRChange, DSLToIRResult, DSLToIRWarning, } from './dsl2ir/types';
+export type { DSLValidationIssue, DSLValidationResult } from './dsl/validator';
+export type { DSLToIROptions, DSLParticleSource, DSLToIRChange, DSLToIRResult, DSLToIRWarning, } from './dsl2ir/types';
 export type { IRToDSLPreservedData, IRToDSLResult } from './ir2dsl/types';
 export { parseParticleShape } from './dsl/parse-particle-shape';