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

package/README.md

@@ -7,21 +7,13 @@ Convert SVG into source-neutral Animation IR, with optional SVG-to-GE and SVG-to
 
 ## 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](#install)
+- [Usage](#usage)
+- [API](#api)
+- [Output](#output)
+- [Input capabilities](#input-capabilities)
+- [Limitations](#limitations)
+- [License](#license)
 
 ## Install
 
@@ -29,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
@@ -66,42 +58,63 @@ 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.
 
+Self-contained static graphics are baked into transparent PNG layers, preserving fills, gradients,
+patterns, strokes, markers, transforms, filters, clipping, masks, and opacity. Ordinary graphics stay separate;
+group-wide effects may merge child graphics into one PNG. Native text and images are never baked.
+Consumers must create layers in array order to retain SVG painter order.
+
+Non-normal blend modes (such as multiply, screen, and overlay) are downgraded to normal alpha compositing.
+Baking and downgrades produce warnings; successful baking remains advisory in strict mode.
+Baking requires browser SVG, Canvas, and DOM support; Node converts native layers and warns for unbaked graphics.
+Mixed native effect groups, dependencies containing text/images, external paint resources, animations, scripts,
+and `foreignObject` are not baked.
+
 Layer format:
 
 - Common fields: `id` is generated automatically; `bbox` uses canvas-pixel coordinates
-  `[left, top, right, bottom]`. 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.
+  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
@@ -113,17 +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.
 
-All public types, including `SVGPreservedData`, `ConvertOptions`, `SVGToGEOptions`, `SVGToLayersOptions`, `SVGStaticLayer`,
+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 `SVGConversionContext`, `SVGPreservedData`, `ConvertOptions`, `SVGToGEOptions`, `SVGToLayersOptions`, `SVGStaticLayer`,
 `SVG2IRWarning`, and result types, are exported from `@vvfx/svg2ir`.
 
 ## Output
@@ -135,20 +151,48 @@ 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[] }
 ```
 
-## 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.
+## Input capabilities
+
+Supported refers to the listed subset; partial means some attributes are approximated or omitted. Output format
+matters: static layers support a smaller subset than IR and GE.
+
+### IR and GE
+
+| Capability | Status | Behavior |
+| --- | --- | --- |
+| SVG string and shapes | Supported | `rect`, `circle`, `ellipse`, `path`, `polygon`, `polyline`, and `line`. |
+| Groups and references | Supported | Hierarchy, transforms, opacity, and expanded `use` / `symbol` instances. |
+| Images | Partial | URL assets and aspect ratio; supply natural sizes to avoid fitted-geometry fallback. |
+| Text | Partial | Text/tspan, text paths, multiline and vertical text; GE rich text needs the sidecar. |
+| Paints | Partial | Solid and supported gradients; gradient text is flattened, some gradient attributes lost. |
+| Masks and clip paths | Partial | Element clip paths and element/group masks; unit and region limits below. |
+| Group `clip-path` | Unsupported | Omitted with `svg2ir_group_clip_path_dropped`. |
+| SMIL | Partial | Transform, motion, opacity, visibility, selected geometry and paint; GE paint uses sidecar. |
+| Filters / patterns / markers | Unsupported | Effects omitted with warnings; supported content remains. |
+| Skew and text decoration | Unsupported | Dropped with warnings; text stroke is also omitted. |
+| Other elements | Unsupported | Unmapped content such as `foreignObject` is omitted with warnings. |
+
+### Static layers
+
+| Capability | Status | Behavior |
+| --- | --- | --- |
+| Images and native text | Supported | Flat image/text layers; text inside images is not recognized. |
+| Image resources | Supported | Fetches and inlines bytes; use `loadImage` for local or authenticated resources. |
+| Text layout and styles | Partial | Metrics may be estimated; bold/italic are downgraded; vertical text is split. |
+| Shapes and animation | Unsupported | Skipped with warnings; layers export does not rasterize vector shapes. |
+| Masks and visual transforms | Partial | Basic rotation/scale; unsupported opacity, crop, skew, etc. skip layers. |
+
+Read `warnings` and optionally `onWarning`. Examples include `svg2ir_filter_dropped`,
+`svg2ir_text_gradient_fill_flattened`, and `svg2ge_layers_unsupported_feature`.
+`strict: true` rejects reported unsupported features and style downgrades; estimated layer text bounds still warn.
+Invalid SVG and failed layer image loads throw errors. An empty warning list is not a complete rendering-fidelity check.
 
 ## Limitations
 
@@ -160,20 +204,14 @@ paths are supported; group-level `clip-path` is currently a limitation.
 - 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.
+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.
 
-## Contributing
-
-From the monorepo root:
-
-```bash
-pnpm --filter @vvfx/svg2ir test
-pnpm --filter @vvfx/svg2ir build
-```
+Images are retained when a straight rectangular mask covers the full image without inversion or subtraction.
 
 ## License
 

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/adapter/svg2layers/assemble.d.ts

@@ -0,0 +1,23 @@
+import type { IRScene } from '@vvfx/animation-ir';
+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[];
+};
+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. */
+export declare function assembleSVGLayers(input: SVGLayerAssemblyInput): SVGToLayersResult;
+export {};

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

@@ -0,0 +1,13 @@
+import { type ConvertOptions, type SVG2IRWarning } from '../../../common/types';
+import type { SVGImageLayer } from '../types';
+export interface BakedLayersResult {
+    layers: Array<{
+        path: string;
+        layer: SVGImageLayer;
+    }>;
+    warnings: SVG2IRWarning[];
+    replacesSource: (path: string | undefined) => boolean;
+    resolvesWarning: (warning: SVG2IRWarning, path: string | undefined) => boolean;
+}
+/** Rasterize graphics and track the source layers and warnings they replace. */
+export declare function buildBakedLayers(source: string, size: [number, number], options: ConvertOptions, rasterScale: number): Promise<BakedLayersResult>;

package/dist/adapter/svg2layers/baking/normalize-layer-blending.d.ts

@@ -0,0 +1,10 @@
+interface BlendDowngrade {
+    mode: string;
+    selector: string;
+}
+/** Replace non-normal mix-blend-mode declarations with normal and report each downgrade. */
+export declare function normalizeLayerBlending(source: string): {
+    source: string;
+    downgrades: BlendDowngrade[];
+};
+export {};

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

@@ -0,0 +1,18 @@
+import type { SVGSnapshotContext } from '../../../svg-rasterizer/prepare-snapshot';
+interface GraphicBakeScope {
+    path: string;
+    selector: string;
+    isGroup: boolean;
+}
+interface GraphicBakingPlan {
+    scopes: GraphicBakeScope[];
+    warnings: Array<{
+        message: string;
+        selector: string;
+    }>;
+}
+/** Select graphic-only subtrees; keep native text and images as separate layers. */
+export declare function planGraphicBaking(source: string): GraphicBakingPlan;
+/** Reject text/image dependencies and effects that cannot be rendered independently. */
+export declare function validateGraphicSnapshot(context: SVGSnapshotContext): void;
+export {};

package/dist/adapter/svg2layers/baking/resolve-baking-warnings.d.ts

@@ -0,0 +1,4 @@
+/** Mask and clipPath definitions do not produce visible layers. */
+export declare function collectNonRenderingDeclarationPaths(source: string): Set<string>;
+/** A stylesheet diagnostic is resolved only when every element it can affect was baked. */
+export declare function collectBakedStylesheetPaths(source: string, isBaked: (path: string) => boolean): Set<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/adapter/svg2layers/converter/image/inspect-mask.d.ts

@@ -0,0 +1,3 @@
+import type { IRLocalBounds, IRMask } from '@vvfx/animation-ir';
+/** 完全覆盖图片的直边矩形 mask 不改变可见内容。 */
+export declare function maskCoversImage(mask: IRMask, bounds: IRLocalBounds): boolean;

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

@@ -1,3 +1,3 @@
 import type { SVGStaticLayer } from '../../types';
 import type { LayerConversionSession } from './conversion-session';
-export declare function buildIRStaticLayers(session: LayerConversionSession): SVGStaticLayer[];
+export declare function buildIRStaticLayers(session: LayerConversionSession, sourceIds?: Map<SVGStaticLayer, string>): SVGStaticLayer[];

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/adapter/svg2layers/strip-layer-animation.d.ts

@@ -0,0 +1,5 @@
+/** Static layers cannot sample animation; drop SMIL nodes so elements keep their authored state. */
+export declare function stripLayerAnimation(source: string): {
+    source: string;
+    removed: 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;
@@ -39,15 +39,19 @@ export interface ConvertResult {
     /** 转换过程丢弃/降级的特性列表。 */
     warnings: SVG2IRWarning[];
 }
-/** 转换过程中产生的 warning(可丢降级特性,非致命)。 */
+/** 转换过程中产生的烘焙、降级或内容损失诊断。 */
 export interface SVG2IRWarning {
     code: SVG2IRWarningCode;
     message: string;
     /** 触发元素在 SVG 里的定位提示(id/tag/索引等)。 */
     elementSelector?: string;
 }
-/** SVG 转换诊断码。不支持的特性按降级和 warning 处理。 */
+/** SVG 转换诊断码；用于报告烘焙、降级和不支持的特性。 */
 export declare const SVG2IR_WARNING_CODES: {
+    /** 图形或图形组已栅格化，矢量编辑能力变化通过 warning 报告。 */
+    readonly LAYERS_GRAPHIC_BAKED: "svg2ge_layers_graphic_baked";
+    readonly LAYERS_BLEND_MODE_DOWNGRADED: "svg2ge_layers_blend_mode_downgraded";
+    readonly LAYERS_ANIMATION_STRIPPED: "svg2ge_layers_animation_stripped";
     readonly LAYERS_UNSUPPORTED_TYPE: "svg2ge_layers_unsupported_type";
     readonly LAYERS_UNSUPPORTED_FEATURE: "svg2ge_layers_unsupported_feature";
     readonly LAYERS_INVALID_DATA: "svg2ge_layers_invalid_data";

package/dist/index.d.ts

@@ -4,11 +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';