@vvfx/svg2ir 0.0.1-beta.11 → 0.0.1-beta.12

package/README.md

@@ -21,7 +21,7 @@ Convert SVG into source-neutral Animation IR, with optional SVG-to-GE and SVG-to
 pnpm add @vvfx/svg2ir @vvfx/ge-ir
 ```
 
-Node.js 22 or later and pnpm 10 or later are required. Browser and Node callers use the same root import; the Node
+Node.js 24 or later and pnpm 10 or later are required. Browser and Node callers use the same root import; the Node
 conditional entry automatically supplies the `svgdom` parsing base.
 
 ## Usage
@@ -58,28 +58,31 @@ import { convertSVGToGE, splitSVG } from '@vvfx/svg2ir';
 
 const split = splitSVG(svgSource);
 const { data, warnings } = convertSVGToGE(
-  svgSource,
+  split,
   { fonts: [{ fontFamily: 'Custom Sans', fontURL: 'https://example.com/fonts/custom-sans.woff2' }] },
-  split.preservedData,
 );
 ```
 
 `convertSVGToGE` uses `@vvfx/ge-ir` to build the base scene. Passing the sidecar enables SVG-specific rich-text,
-paint-animation, and gradient-UV post-processing. Font definitions are supplied independently through `fonts`.
+paint-animation, and gradient-UV post-processing. Passing the `SVGConversionContext` returned by `splitSVG` reuses its
+parsed IR and preserved data without parsing the SVG again. Passing an SVG string keeps source-specific post-processing
+disabled unless `preservedData` is supplied separately. Pass parse options such as `frameRate`, `durationSeconds`, and
+`measureText` to `splitSVG`; options passed to `convertSVGToGE` apply to GE output and diagnostics. Font definitions are
+supplied independently through `fonts`.
 
 ### SVG to static layers
 
 ```ts
-import { convertSVG } from '@vvfx/svg2ir';
+import { convertSVGToLayers } from '@vvfx/svg2ir';
 
 const svgSource = '<svg width="400" height="300"><text x="20" y="40" font-size="24">Hello</text></svg>';
-const { size: canvasSize, data: layers, warnings } = await convertSVG(svgSource, { outputFormat: 'layers' });
+const { size: canvasSize, data: layers, warnings } = await convertSVGToLayers(svgSource);
 const json = JSON.stringify(layers);
 
 console.info(canvasSize, json, warnings);
 ```
 
-With `outputFormat: 'layers'`, `convertSVG` converts Animation IR and SVG preserved text data directly into
+`convertSVGToLayers` converts Animation IR and SVG preserved text data directly into
 static layers and asynchronously returns `{ size, data, warnings }`.
 `data` is a flat array of image and text layers; `size` is the separate canvas width and height in pixels.
 SVG images become image layers, and native text becomes editable text layers. Text inside images is not recognized.
@@ -98,14 +101,20 @@ and `foreignObject` are not baked.
 Layer format:
 
 - Common fields: `id` is generated automatically; `bbox` uses canvas-pixel coordinates
-  `[left, top, right, bottom]`. Native geometry is rounded to two decimal places.
+  `[left, top, right, bottom]`.
 - Image layers: `type: 'image'`, `role: 'content'`, and a Base64 data URL in `url`.
   `size` holds display dimensions before rotation; `rotation` holds XYZ Euler angles in degrees (positive Z is
   clockwise). `width` and `height` are the bbox dimensions.
-  Baked geometry follows raster resolution; transforms are included in the pixels, with `rotation: [0, 0, 0]`.
+  Native image geometry is rounded to two decimal places. Baked geometry follows raster resolution;
+  transforms are included in the pixels, with `rotation: [0, 0, 0]`.
 - Text layers: `type: 'text'`, `state: 'active'`, full text in `content`, and `fragments` containing text runs,
   fonts, sizes, colors, and spacing. Fragment `bbox` and `polygon` are relative to the text layer's top-left corner;
   polygon contains the layout corners. Rotation uses degrees and colors use `#RRGGBB`.
+  `font_family` contains the family name without enclosing CSS quotes.
+  Preserve `font_size` and `letter_spacing` on import.
+  Text positions, font sizes, spacing, and rotation retain precision.
+  Frame widths use per-code-point measurements at the transformed font size, with spacing only between characters.
+  No width padding is added; consumers should preserve this precision when saving and restoring text.
   Native text requires no image erasure, so `erase_operations` is empty.
 
 External images are fetched and inlined; browser fetch requires CORS. Supply `loadImage` for local files or
@@ -117,21 +126,20 @@ authenticated resources and `resourceBaseUrl` for relative image references. Fai
 
 - `convertSVGToIR(source, options?)` returns `{ ir, warnings }`.
 - `splitSVG(source, options?)` returns `{ ir, warnings, preservedData }`.
-- `convertSVGToGE(source, options?, preservedData?)` returns `{ data, warnings }`.
-- `convertSVG(source, options?, preservedData?)` returns `{ data, warnings }` synchronously for GE, or
-  `Promise<SVGToLayersResult>` for layers.
+- `convertSVGToGE(sourceOrContext, options?, preservedData?)` returns `{ data, warnings }`.
+- `convertSVGToLayers(source, options?, preservedData?)` returns `Promise<SVGToLayersResult>`.
 - `inferNumericWeightFromFamily(fontFamily)` infers a numeric font weight, or returns `null`.
 
 Important options include `frameRate` (default `30`), `durationSeconds` (default `5` for static SVG),
 `backgroundColor`, `resourceBaseUrl`, `imageNaturalSizes`, `measureText`, `strict`, `onWarning`, and the GE-only
 `fonts` list. `resourceBaseUrl` must be absolute when used to resolve relative image references.
-`convertSVG` also accepts `outputFormat` (`'ge'` by default or `'layers'`) and a layers-only `loadImage` callback:
+`convertSVGToLayers` accepts a `loadImage` callback:
 `(url) => Promise<{ data: Uint8Array; mimeType: string }>`; `data` contains the original image bytes.
 
 The layers-only `rasterScale` option controls PNG resolution without changing display size; it defaults to `2`
 and must be finite and positive. The working raster is limited to 16 megapixels.
 
-All public types, including `SVGPreservedData`, `ConvertOptions`, `SVGToGEOptions`, `SVGToLayersOptions`, `SVGStaticLayer`,
+All public types, including `SVGConversionContext`, `SVGPreservedData`, `ConvertOptions`, `SVGToGEOptions`, `SVGToLayersOptions`, `SVGStaticLayer`,
 `SVG2IRWarning`, and result types, are exported from `@vvfx/svg2ir`.
 
 ## Output
@@ -143,10 +151,10 @@ convertSVGToIR(source, options?);
 splitSVG(source, options?);
 // { ir: IRScene; warnings: SVG2IRWarning[]; preservedData: SVGPreservedData }
 
-convertSVGToGE(source, options?, preservedData?);
+convertSVGToGE(sourceOrContext, options?, preservedData?);
 // { data: JSONScene; warnings: SVG2IRWarning[] }
 
-await convertSVG(source, { outputFormat: 'layers' });
+await convertSVGToLayers(source, options?, preservedData?);
 // { size: [number, number]; data: SVGStaticLayer[]; warnings: SVG2IRWarning[] }
 ```
 
@@ -199,7 +207,8 @@ Invalid SVG and failed layer image loads throw errors. An empty warning list is
 Static layers export supports images and text only. SMIL animation elements are removed with a warning; unsupported animated channels, unbaked shapes, solid backgrounds,
 image skew/reflection/cropping, masks, opacity, nonuniform text scaling, and text paths are skipped with warnings.
 Bold and italic styles are downgraded with warnings; vertical text is split into character layers with horizontal fragments.
-Supply `measureText` for font metrics; incomplete metrics produce estimated bounds and warnings.
+Load the fonts used by `measureText` before conversion; the callback is synchronous and does not load fonts.
+Incomplete metrics produce estimated bounds and warnings.
 `strict: true` turns unsupported content and style downgrades into errors; estimated bounds still produce warnings.
 
 Images are retained when a straight rectangular mask covers the full image without inversion or subtraction.

package/dist/{svg2ge-adapter → adapter/svg2ge}/assemble.d.ts

@@ -1,5 +1,5 @@
-import { type ConvertResult } from '../common/types';
-import type { SVGPreservedData } from '../svg-preserved-data';
+import { type ConvertResult } from '../../common/types';
+import type { SVGPreservedData } from '../../svg-preserved-data';
 import type { SVGToGEOptions, SVGToGEResult } from './types';
 /** 从已解析的 IR 和 SVG 保留数据生成 GE 场景。 */
 export declare function assembleSVGGE(parsed: ConvertResult, options?: SVGToGEOptions, preservedData?: SVGPreservedData): SVGToGEResult;

package/dist/adapter/svg2ge/convert.d.ts

@@ -0,0 +1,7 @@
+import type { SVGSource } from '../../common/types';
+import type { SVGConversionContext } from '../../svg2ir/convert';
+import type { SVGPreservedData } from '../../svg-preserved-data';
+import type { SVGToGEOptions, SVGToGEResult } from './types';
+/** SVG→GE 显式入口。传入 preservedData 时应用 SVG 专属后处理。 */
+export declare function convertSVGToGE(source: SVGSource, options?: SVGToGEOptions, preservedData?: SVGPreservedData): SVGToGEResult;
+export declare function convertSVGToGE(context: SVGConversionContext, options?: SVGToGEOptions, preservedData?: SVGPreservedData): SVGToGEResult;

package/dist/{svg2ge-adapter → adapter/svg2ge}/normalize-shape-animation.d.ts

@@ -1,2 +1,2 @@
-import type { SVGPreservedShapeAnimation } from '../svg-preserved-data';
+import type { SVGPreservedShapeAnimation } from '../../svg-preserved-data';
 export declare function normalizeShapeAnimationForGE(animation: SVGPreservedShapeAnimation): SVGPreservedShapeAnimation | undefined;

package/dist/{svg2ge-adapter → adapter/svg2ge}/post-process/apply-shape-geometry-animation.d.ts

@@ -1,4 +1,4 @@
 import type { IRScene } from '@vvfx/animation-ir';
 import { type JSONScene } from '@galacean/effects-specification';
-import type { SVGPreservedShapeAnimation } from '../../svg-preserved-data';
+import type { SVGPreservedShapeAnimation } from '../../../svg-preserved-data';
 export declare function applyShapeGeometryAnimations(scene: JSONScene, ir: IRScene, animationsByLayerId: ReadonlyMap<string, SVGPreservedShapeAnimation> | undefined): void;

package/dist/{svg2ge-adapter → adapter/svg2ge}/post-process/apply-shape-paint-animation.d.ts

@@ -1,4 +1,4 @@
 import type { IRScene } from '@vvfx/animation-ir';
 import { type JSONScene } from '@galacean/effects-specification';
-import type { SVGPreservedPaintAnimation } from '../../svg-preserved-data';
+import type { SVGPreservedPaintAnimation } from '../../../svg-preserved-data';
 export declare function applyShapePaintAnimation(scene: JSONScene, ir: IRScene, paintAnimationByLayerIndex: ReadonlyMap<string, readonly SVGPreservedPaintAnimation[]>): void;

package/dist/{svg2ge-adapter → adapter/svg2ge}/post-process/rewrite-text-components.d.ts

@@ -3,7 +3,7 @@
  * 文本尺寸字段和 textPath 标记保留在 Effects 场景中。
  */
 import { type JSONScene } from '@galacean/effects-specification';
-import type { SVGPreservedTextData } from '../../svg-preserved-data';
+import type { SVGPreservedTextData } from '../../../svg-preserved-data';
 interface RewriteTextComponentsToRichTextInput {
     textDataByLayerId: ReadonlyMap<string, SVGPreservedTextData>;
     itemLayerIds: Readonly<Record<string, string>>;

package/dist/{svg2ge-adapter → adapter/svg2ge}/pre-process.d.ts

@@ -1,5 +1,5 @@
 import type { IRScene } from '@vvfx/animation-ir';
-import type { SVGPreservedPaintAnimation, SVGPreservedShapeAnimation } from '../svg-preserved-data';
+import type { SVGPreservedPaintAnimation, SVGPreservedShapeAnimation } from '../../svg-preserved-data';
 export declare function applyShapeAnimationBasePaths(ir: IRScene, animationsByLayerId: ReadonlyMap<string, SVGPreservedShapeAnimation> | undefined): void;
 /** convertIRToGE 用 IR 副本展开 hold 过渡点,result.ir 仍保留解析原始关键帧。 */
 export declare function expandIRHoldTransitions(ir: IRScene): IRScene;

package/dist/{svg2ge-adapter → adapter/svg2ge}/types.d.ts

@@ -1,6 +1,6 @@
 import type { JSONScene } from '@galacean/effects-specification';
-import type { ConvertOptions, SVG2IRWarning } from '../common/types';
-import type { SVGFontDefinition } from '../svg-preserved-data';
+import type { ConvertOptions, SVG2IRWarning } from '../../common/types';
+import type { SVGFontDefinition } from '../../svg-preserved-data';
 export interface SVGToGEOptions extends ConvertOptions {
     fonts?: readonly SVGFontDefinition[];
 }

package/dist/{svg2layers-adapter → adapter/svg2layers}/assemble.d.ts

@@ -1,19 +1,21 @@
 import type { IRScene } from '@vvfx/animation-ir';
-import { type ConvertOptions, type SVG2IRWarning } from '../common/types';
-import type { SVGPreservedData } from '../svg-preserved-data';
+import { type ConvertOptions, type SVG2IRWarning } from '../../common/types';
+import type { SVGPreservedData } from '../../svg-preserved-data';
+import type { SVGConversionContext } from '../../svg2ir/convert';
 import type { BakedLayersResult } from './baking/build-baked-layers';
 import type { SVGStaticLayer, SVGToLayersResult } from './types';
 export declare function assembleSVGStaticLayers(scene: IRScene, options: ConvertOptions, warnings: SVG2IRWarning[], preservedData?: SVGPreservedData, sourceIds?: Map<SVGStaticLayer, string>): {
     size: [number, number];
     data: SVGStaticLayer[];
 };
-interface SVGLayerAssemblyInput {
-    scene: IRScene;
-    options: ConvertOptions;
-    warnings: SVG2IRWarning[];
-    preservedData: SVGPreservedData;
+export interface SVGStaticLayerConversionContext extends SVGConversionContext {
+    source: string;
     layerSources: ReadonlyMap<string, string>;
     warningSources: ReadonlyMap<SVG2IRWarning, string>;
+}
+interface SVGLayerAssemblyInput {
+    context: SVGStaticLayerConversionContext;
+    options: ConvertOptions;
     baking: BakedLayersResult;
 }
 /** Replace baked sources, combine native and raster layers in painter order, then report final diagnostics. */

package/dist/{svg2layers-adapter → adapter/svg2layers}/baking/build-baked-layers.d.ts

@@ -1,4 +1,4 @@
-import { type ConvertOptions, type SVG2IRWarning } from '../../common/types';
+import { type ConvertOptions, type SVG2IRWarning } from '../../../common/types';
 import type { SVGImageLayer } from '../types';
 export interface BakedLayersResult {
     layers: Array<{

package/dist/{svg2layers-adapter → adapter/svg2layers}/baking/plan-graphic-baking.d.ts

@@ -1,4 +1,4 @@
-import type { SVGSnapshotContext } from '../../svg-rasterizer/prepare-snapshot';
+import type { SVGSnapshotContext } from '../../../svg-rasterizer/prepare-snapshot';
 interface GraphicBakeScope {
     path: string;
     selector: string;

package/dist/adapter/svg2layers/convert.d.ts

@@ -0,0 +1,4 @@
+import { type SVGSource } from '../../common/types';
+import type { SVGPreservedData } from '../../svg-preserved-data';
+import type { SVGToLayersOptions, SVGToLayersResult } from './types';
+export declare function convertSVGToLayers(source: SVGSource, options?: SVGToLayersOptions, preservedData?: SVGPreservedData): Promise<SVGToLayersResult>;

package/dist/{svg2layers-adapter → adapter/svg2layers}/converter/diagnostics/collect-warnings.d.ts

@@ -1,5 +1,5 @@
 import type { IRLayer } from '@vvfx/animation-ir';
-import { type ConvertOptions, type SVG2IRWarning, type SVG2IRWarningCode } from '../../../common/types';
+import { type ConvertOptions, type SVG2IRWarning, type SVG2IRWarningCode } from '../../../../common/types';
 export declare class LayerConversionError extends Error {
     readonly code: SVG2IRWarningCode;
     constructor(code: SVG2IRWarningCode, message: string);

package/dist/{svg2layers-adapter → adapter/svg2layers}/converter/layers/conversion-session.d.ts

@@ -1,6 +1,6 @@
 import type { IRAsset, IRComposition, IRLayer, IRScene } from '@vvfx/animation-ir';
-import type { ConvertOptions, SVG2IRWarning } from '../../../common/types';
-import type { SVGPreservedData } from '../../../svg-preserved-data';
+import type { ConvertOptions, SVG2IRWarning } from '../../../../common/types';
+import type { SVGPreservedData } from '../../../../svg-preserved-data';
 import { type StaticLayerState } from '../transform/build-transform';
 export interface LayerConversionSession {
     readonly composition: IRComposition;

package/dist/{svg2layers-adapter → adapter/svg2layers}/converter/text/parse-text-runs.d.ts

@@ -1,5 +1,5 @@
 import type { IRFontAsset, IRTextLayer } from '@vvfx/animation-ir';
-import type { SVGPreservedTextData } from '../../../svg-preserved-data';
+import type { SVGPreservedTextData } from '../../../../svg-preserved-data';
 export interface TextRun {
     text: string;
     fontSize: number;

package/dist/{svg2layers-adapter → adapter/svg2layers}/converter/text/text-layout.d.ts

@@ -1,9 +1,9 @@
 import type { IRTextContent } from '@vvfx/animation-ir';
-import { type ConvertOptions, type SVG2IRWarning } from '../../../common/types';
+import { type ConvertOptions, type SVG2IRWarning } from '../../../../common/types';
 import type { SVGLayerBBox } from '../../types';
 import type { TextRun } from './parse-text-runs';
 export interface PositionedTextRun {
     run: TextRun;
     box: SVGLayerBBox;
 }
-export declare function buildTextRunLayout(runs: TextRun[], family: string, spacing: number, content: IRTextContent, size: [number, number], conversionOptions: ConvertOptions, warnings: SVG2IRWarning[], id: string, segmented?: boolean): PositionedTextRun[];
+export declare function buildTextRunLayout(runs: TextRun[], family: string, spacing: number, content: IRTextContent, size: [number, number], conversionOptions: ConvertOptions, warnings: SVG2IRWarning[], id: string, segmented?: boolean, renderScale?: readonly [number, number]): PositionedTextRun[];

package/dist/{svg2layers-adapter → adapter/svg2layers}/matrix.d.ts

@@ -12,5 +12,5 @@ export declare const IDENTITY_MATRIX: LayerMatrix;
 export declare function multiplyMatrices(parent: LayerMatrix, local: LayerMatrix): LayerMatrix;
 export declare function transformPoint(matrix: LayerMatrix, x: number, y: number): LayerPoint;
 export declare function transformBoxCorners(matrix: LayerMatrix, box: SVGLayerBBox): LayerPoint[];
-export declare function mapPointsToBBox(points: readonly LayerPoint[]): SVGLayerBBox;
+export declare function mapPointsToBBox(points: readonly LayerPoint[], roundCoordinates?: boolean): SVGLayerBBox;
 export declare function roundPixel(value: number): number;

package/dist/{svg2layers-adapter → adapter/svg2layers}/types.d.ts

@@ -1,4 +1,4 @@
-import type { SVG2IRWarning } from '../common/types';
+import type { ConvertOptions, SVG2IRWarning } from '../../common/types';
 /** 图片读取结果；data 为原始文件字节，不是 Base64 字符串。 */
 export interface SVGImageResource {
     data: Uint8Array;
@@ -6,6 +6,12 @@ export interface SVGImageResource {
 }
 /** 读取外链、本地文件或需要鉴权的图片资源。 */
 export type SVGImageResourceLoader = (url: string) => Promise<SVGImageResource>;
+export interface SVGToLayersOptions extends ConvertOptions {
+    /** 外链图片读取回调，默认使用 fetch。 */
+    loadImage?: SVGImageResourceLoader;
+    /** 烘焙分辨率倍数，默认 2，不改变显示尺寸。 */
+    rasterScale?: number;
+}
 /** 像素边界：[左、上、右、下]。 */
 export type SVGLayerBBox = [number, number, number, number];
 export interface SVGImageLayer {
@@ -30,6 +36,7 @@ export interface SVGTextFragment {
     bbox: SVGLayerBBox;
     /** 相对文字层的布局四边形，依次为变换前的左上、右上、右下、左下角；不是字形轮廓。 */
     polygon: Array<[number, number]> | null;
+    /** 字体名，不含 CSS 外层引号。 */
     font_family: string;
     font_size: number;
     color: string;

package/dist/common/types.d.ts

@@ -13,7 +13,7 @@ export interface ConvertOptions {
     strict?: boolean;
     /** warning 回调：每条 warning 会先进入 ConvertResult.warnings，再通知调用方。 */
     onWarning?: (warning: SVG2IRWarning) => void;
-    /** 可选的文本测量回调，用于改进 SVG 文本几何的 IR bounds。 */
+    /** 同步文本测量回调，用于计算文字边界；调用转换前需加载测量使用的字体。 */
     measureText?: (fontDesc: string, text: string) => {
         width: number;
         fontBoundingBoxAscent?: number;

package/dist/index.d.ts

@@ -4,12 +4,11 @@
  * 根入口提供 SVG→IR、SVG 保留数据拆分及 GE/静态分层输出。
  */
 export { convertSVGToIR, splitSVG } from './svg2ir/convert';
-export { convertSVG } from './convert';
-export { convertSVGToGE } from './svg2ge-adapter/convert';
+export { convertSVGToLayers } from './adapter/svg2layers/convert';
+export { convertSVGToGE } from './adapter/svg2ge/convert';
 export type { ConvertOptions, ConvertResult, SVG2IRWarning, SVG2IRWarningCode, SVGSource, } from './common/types';
-export type { SplitSVGOptions, SplitSVGResult } from './svg2ir/convert';
-export type { SVGToGEOptions, SVGToGEResult } from './svg2ge-adapter/types';
-export type { SVGConversionOptions, SVGToLayersOptions } from './convert';
+export type { SplitSVGOptions, SplitSVGResult, SVGConversionContext } from './svg2ir/convert';
+export type { SVGToGEOptions, SVGToGEResult } from './adapter/svg2ge/types';
 export type { SVGPreservedData, SVGFontDefinition, SVGPreservedPaintAnimation, SVGPreservedShapeAnimation, SVGPreservedTextData, SVGPreservedTextSpan, } from './svg-preserved-data';
-export type { SVGStaticLayer, SVGImageLayer, SVGTextLayer, SVGTextFragment, SVGLayerBBox, SVGToLayersResult, SVGLayerEraseOperation, SVGImageResource, SVGImageResourceLoader, } from './svg2layers-adapter/types';
+export type { SVGStaticLayer, SVGImageLayer, SVGTextLayer, SVGTextFragment, SVGLayerBBox, SVGToLayersOptions, SVGToLayersResult, SVGLayerEraseOperation, SVGImageResource, SVGImageResourceLoader, } from './adapter/svg2layers/types';
 export { inferNumericWeightFromFamily } from './svg2ir/converter/text/font-metrics';