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

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
 
@@ -92,13 +84,25 @@ 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]`. Native 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.
+  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`.
@@ -116,6 +120,7 @@ authenticated resources and `resourceBaseUrl` for relative image references. Fai
 - `convertSVGToGE(source, options?, preservedData?)` returns `{ data, warnings }`.
 - `convertSVG(source, options?, preservedData?)` returns `{ data, warnings }` synchronously for GE, or
   `Promise<SVGToLayersResult>` for layers.
+- `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
@@ -123,6 +128,9 @@ Important options include `frameRate` (default `30`), `durationSeconds` (default
 `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.
 
+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`,
 `SVG2IRWarning`, and result types, are exported from `@vvfx/svg2ir`.
 
@@ -142,13 +150,41 @@ 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.
+## 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 +196,13 @@ 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.
 `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/common/types.d.ts

@@ -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/convert.d.ts

@@ -7,6 +7,8 @@ export interface SVGConversionOptions extends ConvertOptions {
     fonts?: SVGToGEOptions['fonts'];
     /** layers 图片读取回调；默认使用 fetch，已有 data URL 无需读取。 */
     loadImage?: SVGImageResourceLoader;
+    /** Graphic baking resolution; logical layer dimensions remain unchanged. Default: 2. */
+    rasterScale?: number;
 }
 export interface SVGToLayersOptions extends SVGConversionOptions {
     outputFormat: 'layers';

package/dist/index.d.ts

@@ -12,3 +12,4 @@ 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';
+export { inferNumericWeightFromFamily } from './svg2ir/converter/text/font-metrics';