@vvfx/svg2ir 0.0.0-stage → 0.0.1-beta.0

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

@@ -1,3 +1,180 @@
-# Temporary Holding Version
+# @vvfx/svg2ir
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [简体中文](./README-zh_CN.md)
+
+Convert SVG into source-neutral Animation IR, with optional SVG-to-GE and SVG-to-layers adapters in the same package.
+
+
+## Contents
+
+- [@vvfx/svg2ir](#vvfxsvg2ir)
+  - [Contents](#contents)
+  - [Install](#install)
+  - [Usage](#usage)
+    - [SVG to IR](#svg-to-ir)
+    - [Preserve SVG-specific data](#preserve-svg-specific-data)
+    - [SVG to GE](#svg-to-ge)
+    - [SVG to static layers](#svg-to-static-layers)
+  - [API](#api)
+    - [Package API](#package-api)
+  - [Output](#output)
+  - [Support](#support)
+  - [Limitations](#limitations)
+  - [Contributing](#contributing)
+  - [License](#license)
+
+## Install
+
+```bash
+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
+conditional entry automatically supplies the `svgdom` parsing base.
+
+## Usage
+
+### SVG to IR
+
+```ts
+import { convertSVGToIR } from '@vvfx/svg2ir';
+
+const { ir, warnings } = convertSVGToIR(
+  '<svg width="400" height="300"><rect x="20" y="20" width="200" height="120" fill="#1677ff"/></svg>',
+);
+
+console.info(ir.compositions[0].layers, warnings);
+```
+
+`convertSVGToIR` returns the core `IRScene` and warnings. SVG-specific preserved data is not included.
+
+### Preserve SVG-specific data
+
+```ts
+import { splitSVG } from '@vvfx/svg2ir';
+
+const { ir, warnings, preservedData } = splitSVG(svgSource);
+```
+
+`preservedData` is an `SVGPreservedData` sidecar for information that the core IR cannot represent, including rich
+text spans and SMIL paint animation. Static layers export also uses the preserved text spans.
+
+### SVG to GE
+
+```ts
+import { convertSVGToGE, splitSVG } from '@vvfx/svg2ir';
+
+const split = splitSVG(svgSource);
+const { data, warnings } = convertSVGToGE(
+  svgSource,
+  { 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`.
+
+### SVG to static layers
+
+```ts
+import { convertSVG } 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 json = JSON.stringify(layers);
+
+console.info(canvasSize, json, warnings);
+```
+
+With `outputFormat: 'layers'`, `convertSVG` 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.
+
+Layer format:
+
+- Common fields: `id` is generated automatically; `bbox` uses canvas-pixel coordinates
+  `[left, top, right, bottom]`. Geometry is rounded to two decimal places.
+- 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.
+- 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`.
+  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
+authenticated resources and `resourceBaseUrl` for relative image references. Failed reads or invalid resources throw errors.
+
+## API
+
+### Package API
+
+- `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.
+
+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:
+`(url) => Promise<{ data: Uint8Array; mimeType: string }>`; `data` contains the original image bytes.
+
+All public types, including `SVGPreservedData`, `ConvertOptions`, `SVGToGEOptions`, `SVGToLayersOptions`, `SVGStaticLayer`,
+`SVG2IRWarning`, and result types, are exported from `@vvfx/svg2ir`.
+
+## Output
+
+```ts
+convertSVGToIR(source, options?);
+// { ir: IRScene; warnings: SVG2IRWarning[] }
+
+splitSVG(source, options?);
+// { ir: IRScene; warnings: SVG2IRWarning[]; preservedData: SVGPreservedData }
+
+convertSVGToGE(source, options?, preservedData?);
+// { data: JSONScene; warnings: SVG2IRWarning[] }
+
+await convertSVG(source, { outputFormat: 'layers' });
+// { size: [number, number]; data: SVGStaticLayer[]; warnings: SVG2IRWarning[] }
+```
+
+## Support
+
+The converter supports basic shapes (`rect`, `circle`, `ellipse`, `path`, `polygon`, `polyline`, and `line`), images
+with natural sizes and `preserveAspectRatio`, text and tspan styles, text paths, gradients, element masks and clip
+paths, transforms, opacity, `use`/`symbol`, and portions of SMIL animation. Supported paint types include solid,
+linear, radial, angular, and image paints where the target scene can represent them. Group masks and element clip
+paths are supported; group-level `clip-path` is currently a limitation.
+
+## Limitations
+
+- Filters, patterns, markers, skew, and some text decoration are downgraded or reported as warnings.
+- Element-level projection, blur, and inner-shadow effects do not have a general GE Runtime representation.
+- Rich text cannot preserve every text stroke, decoration, or per-span position.
+- Some radial-gradient focal offsets, `spreadMethod`, and `gradientTransform` values are not retained.
+- Group-level `clip-path` is not currently mapped; element clip paths and group masks are supported.
+- IR and GE conversion do not download external resources. Callers own URL resolution, font loading, and runtime
+  resource access. Layers export reads and inlines image resources as described above.
+
+Static layers export supports images and text only. Unsupported animated channels, shapes, solid backgrounds,
+image skew/reflection/cropping, masks, blending, 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.
+`strict: true` turns unsupported content and style downgrades into errors; estimated bounds still produce warnings.
+
+## Contributing
+
+From the monorepo root:
+
+```bash
+pnpm --filter @vvfx/svg2ir test
+pnpm --filter @vvfx/svg2ir build
+```
+
+## License
+
+[MIT](./LICENSE) © 2019-present Ant Group Co., Ltd.

package/dist/common/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * svg2ir 内部转换错误码常量。
+ *
+ * 内部转换阶段使用这些常量区分失败阶段,避免依赖 message 文本。
+ *
+ * 转换器遇到不可继续的错误(解析失败/IR 校验失败/生成失败)抛内部转换错误；
+ * 可丢降级的特性走 warnings,不抛错。
+ */
+/** svg2ir 内部转换错误码,裸字符串(不带包名前缀)。 */
+export declare const SVG_CONVERTER_ERROR_CODES: {
+    /** SVG 串/资源无法解析为合法 SVG DOM。 */
+    readonly INVALID_SVG: "INVALID_SVG";
+    readonly LAYERS_CONVERSION_FAILED: "LAYERS_CONVERSION_FAILED";
+    /** SVG 解析底座(reader/reader)初始化失败。 */
+    readonly PARSE_FAIL: "PARSE_FAIL";
+    /** IR 结构校验失败(animation-ir 内部 IR_xxx 映射到该码)。 */
+    readonly IR_VALIDATION_FAILED: "IR_VALIDATION_FAILED";
+};
+export type SVGConverterErrorCode = (typeof SVG_CONVERTER_ERROR_CODES)[keyof typeof SVG_CONVERTER_ERROR_CODES];
+/**
+ * 判断输入值是否为 {@link SVGConverterErrorCode}。
+ */
+export declare function isSVGConverterErrorCode(code: unknown): code is SVGConverterErrorCode;
+/** svg2ir 内部统一错误类型。 */
+export declare class SVGConverterError extends Error {
+    readonly code: SVGConverterErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(code: SVGConverterErrorCode, message: string, details?: Record<string, unknown>);
+}
+/**
+ * 将任意异常标准化为 {@link SVGConverterError},并尽量保留内部错误码与上下文。
+ */
+export declare function normalizeToConverterError(error: unknown, fallbackCode: SVGConverterErrorCode, fallbackMessage: string, details?: Record<string, unknown>): SVGConverterError;

package/dist/common/types.d.ts

@@ -0,0 +1,89 @@
+import type { IRScene } from '@vvfx/animation-ir';
+/** SVG 字符串。convertSVGToIR 的输入。 */
+export type SVGSource = string;
+/** SVG → Animation IR 转换选项。 */
+export interface ConvertOptions {
+    /** 画布帧率，决定 IR 帧时间。默认 30。 */
+    frameRate?: number;
+    /** 静态 SVG 的展示时长（秒）。动态 SVG 可由 SMIL active interval 覆盖。默认 5。 */
+    durationSeconds?: number;
+    /** 输出 IR composition 的画布底色；未传时保持透明。支持 SVG 颜色字符串。 */
+    backgroundColor?: string | null;
+    /** true 时遇到无法表达的元素中断转换；false(默认)记录 warning 并继续。 */
+    strict?: boolean;
+    /** warning 回调：每条 warning 会先进入 ConvertResult.warnings，再通知调用方。 */
+    onWarning?: (warning: SVG2IRWarning) => void;
+    /** 可选的文本测量回调，用于改进 SVG 文本几何的 IR bounds。 */
+    measureText?: (fontDesc: string, text: string) => {
+        width: number;
+        fontBoundingBoxAscent?: number;
+        fontBoundingBoxDescent?: number;
+        actualBoundingBoxAscent?: number;
+        hangingBaseline?: number;
+    };
+    /** SVG 来源的绝对 URL，用于把相对图片 href 解析为规范化 IR Asset URL。 */
+    resourceBaseUrl?: string;
+    /** 图片 intrinsic(自然)尺寸表,url→{width,height}。用于算 <image> 默认 preserveAspectRatio="xMidYMid meet"
+     *  的 fitted 几何框(svg2ir 不下载图、Node/svgdom 无 HTMLImageElement,自己拿不到自然尺寸)。浏览器调用方通常
+     *  走 inlineSvgImages 给 <image> 盖 data-natural-w/h(优先于此表);Node 调用方读 PNG/JPEG 文件头建此表
+     *  传入。两者都无时，meet 使用 full-fit 拉伸。key 用 <image> href 原值(xlink:href/href/dataURI)。 */
+    imageNaturalSizes?: Map<string, {
+        width: number;
+        height: number;
+    }>;
+}
+/** SVG 转换产出。 */
+export interface ConvertResult {
+    /** SVG 解析后的完整 IRScene。 */
+    ir: IRScene;
+    /** 转换过程丢弃/降级的特性列表。 */
+    warnings: SVG2IRWarning[];
+}
+/** 转换过程中产生的 warning(可丢降级特性,非致命)。 */
+export interface SVG2IRWarning {
+    code: SVG2IRWarningCode;
+    message: string;
+    /** 触发元素在 SVG 里的定位提示(id/tag/索引等)。 */
+    elementSelector?: string;
+}
+/** SVG 转换诊断码。不支持的特性按降级和 warning 处理。 */
+export declare const SVG2IR_WARNING_CODES: {
+    readonly LAYERS_UNSUPPORTED_TYPE: "svg2ge_layers_unsupported_type";
+    readonly LAYERS_UNSUPPORTED_FEATURE: "svg2ge_layers_unsupported_feature";
+    readonly LAYERS_INVALID_DATA: "svg2ge_layers_invalid_data";
+    readonly LAYERS_TEXT_STYLE_DROPPED: "svg2ge_layers_text_style_dropped";
+    readonly LAYERS_TEXT_BOUNDS_ESTIMATED: "svg2ge_layers_text_bounds_estimated";
+    /** 元素整体不渲染也不映射(无法展开的 use、foreignObject、switch 等不支持元素)。 */
+    readonly ELEMENT_DROPPED: "svg2ir_element_dropped";
+    /** stroke-dasharray/dashoffset 无法完整写入当前 IR，按可表达子集处理。 */
+    readonly STROKE_DASH_DROPPED: "svg2ir_stroke_dash_dropped";
+    /** SVG filter(feGaussianBlur 等)没有对应 IR 字段。 */
+    readonly FILTER_DROPPED: "svg2ir_filter_dropped";
+    /** pattern 平铺填充没有对应 IR paint。 */
+    readonly PATTERN_DROPPED: "svg2ir_pattern_dropped";
+    /** skewX/skewY 没有对应 IR transform 通道。 */
+    readonly SKEW_DROPPED: "svg2ir_skew_dropped";
+    /** IRTextContent 只有单色文本填充，渐变文字按中点色处理。 */
+    readonly TEXT_GRADIENT_FILL_FLATTENED: "svg2ir_text_gradient_fill_flattened";
+    /** IRTextContent 没有文本描边字段。 */
+    readonly TEXT_STROKE_DROPPED: "svg2ir_text_stroke_dropped";
+    /** IRTextContent 没有 text-decoration 字段。 */
+    readonly TEXT_DECORATION_DROPPED: "svg2ir_text_decoration_dropped";
+    /** Effects adapter 未获得调用方提供的字体文件，运行时可能使用 fallback。 */
+    readonly TEXT_FONT_NOT_SUPPLIED: "svg2ir_text_font_not_supplied";
+    /** ge-ir 导出阶段报告了规范化或保真降级。 */
+    readonly GE_EXPORT_DIAGNOSTIC: "svg2ir_ge_export_diagnostic";
+    /** clipPathUnits=objectBoundingBox:裁剪实现只接受 userSpaceOnUse。 */
+    readonly CLIP_PATH_UNITS_DROPPED: "svg2ir_clip_path_units_dropped";
+    /** clipPath 内显式 clip-rule/fill-rule 没有对应 IR mask 规则字段。 */
+    readonly CLIP_RULE_DROPPED: "svg2ir_clip_rule_dropped";
+    /** <g clip-path> 组级裁剪:当前仅支持元素级 clip-path 与组级 mask。 */
+    readonly GROUP_CLIP_PATH_DROPPED: "svg2ir_group_clip_path_dropped";
+    /** maskContentUnits=objectBoundingBox:mask 几何只接受 userSpaceOnUse。 */
+    readonly MASK_CONTENT_UNITS_DROPPED: "svg2ir_mask_content_units_dropped";
+    /** maskUnits / x/y/width/height 没有对应 IR mask region 字段。 */
+    readonly MASK_REGION_DROPPED: "svg2ir_mask_region_dropped";
+    /** mask-type=luminance/alpha:当前 IR mask 不保留该模式。 */
+    readonly MASK_TYPE_DROPPED: "svg2ir_mask_type_dropped";
+};
+export type SVG2IRWarningCode = (typeof SVG2IR_WARNING_CODES)[keyof typeof SVG2IR_WARNING_CODES];

package/dist/convert.d.ts

@@ -0,0 +1,19 @@
+import type { ConvertOptions, SVGSource } from './common/types';
+import type { SVGPreservedData } from './svg-preserved-data';
+import type { SVGImageResourceLoader, SVGToLayersResult } from './svg2layers-adapter/types';
+import type { SVGToGEOptions, SVGToGEResult } from './svg2ge-adapter/types';
+export interface SVGConversionOptions extends ConvertOptions {
+    outputFormat?: 'ge' | 'layers';
+    fonts?: SVGToGEOptions['fonts'];
+    /** layers 图片读取回调；默认使用 fetch，已有 data URL 无需读取。 */
+    loadImage?: SVGImageResourceLoader;
+}
+export interface SVGToLayersOptions extends SVGConversionOptions {
+    outputFormat: 'layers';
+}
+/** SVG 多格式输出入口，默认返回 GE 场景。 */
+export declare function convertSVG(source: SVGSource, options: SVGToLayersOptions, preservedData?: SVGPreservedData): Promise<SVGToLayersResult>;
+export declare function convertSVG(source: SVGSource, options?: SVGToGEOptions & {
+    outputFormat?: 'ge';
+}, preservedData?: SVGPreservedData): SVGToGEResult;
+export declare function convertSVG(source: SVGSource, options?: SVGConversionOptions, preservedData?: SVGPreservedData): SVGToGEResult | Promise<SVGToLayersResult>;

package/dist/debug.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 内部调试入口，不属于稳定 API。
+ *
+ * 仅供仓库内 parser、validation 和错误排障使用。
+ */
+export { parseSVGToIRScene } from './svg2ir';
+export { SVGConverterError, SVG_CONVERTER_ERROR_CODES, isSVGConverterErrorCode, normalizeToConverterError, } from './common/errors';
+export type { SVGConverterErrorCode } from './common/errors';

package/dist/helper.d.ts

@@ -0,0 +1,5 @@
+/**
+ * helper 入口：SVG 转换辅助工具，不包含在 `@vvfx/svg2ir` 主入口的最小依赖集合中。
+ */
+/** 从字体族名推断数值字重(100-950)，与 svg2ir 生产路径共用同一套解析逻辑。 */
+export { inferNumericWeightFromFamily } from './svg2ir/converter/text/font-metrics';

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @vvfx/svg2ir — SVG → Animation IR / Effects 转换引擎。
+ *
+ * 根入口提供 SVG→IR、SVG 保留数据拆分及 GE/静态分层输出。
+ */
+export { convertSVGToIR, splitSVG } from './svg2ir/convert';
+export { convertSVG } from './convert';
+export { convertSVGToGE } from './svg2ge-adapter/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 { 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';