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

package/dist/svg2ir/converter/layers/registry.d.ts

@@ -0,0 +1,4 @@
+import type { Element } from '@svgdotjs/svg.js';
+import { type SVGConversionSession } from './conversion-session';
+export type SVGElementConverter = (element: Element) => void;
+export declare function createSVGElementConverterRegistry(session: SVGConversionSession): ReadonlyMap<string, SVGElementConverter>;

package/dist/svg2ir/converter/paint/resolve-gradient.d.ts

@@ -0,0 +1,29 @@
+/**
+ * SVG 渐变 paint 解析 → IRGradientPaint。
+ *
+ * 支持 linearGradient 的 userSpaceOnUse/objectBoundingBox。radialGradient 因 IR 仅有
+ * gradientStart/End，使用水平直径近似；gradientTransform 只处理可稳定映射的子集。
+ *
+ * 坐标(IR gradient 使用归一化 UV 空间):效果运行时 shape 片元着色器用 uv0(顶点位置按 shape bbox
+ * 归一化到 0-1)比对 _StartPoint/_EndPoint。故渐变起止点必须是相对 shape bbox 的 0-1 UV,
+ * 不是 world-local 单位。这里把 userSpaceOnUse / objectBoundingBox 坐标统一转成 UV 存进 IR;
+ * GE 适配阶段再将这些 UV 坐标映射到运行时渐变参数。
+ */
+import type EditableSVG from '../../../parse-svg/svg-parser';
+import type { Element } from '@svgdotjs/svg.js';
+import type { IRColor, IRGradientPaint } from '@vvfx/animation-ir';
+export interface ShapeBBox {
+    minX: number;
+    minY: number;
+    width: number;
+    height: number;
+}
+/** 从渐变取 t=0.5 的颜色,作为文本 fill=url(#渐变) 的降级纯色。
+ *  返回归一化 [r,g,b,a] 或 null(目标不是渐变/未找到)。
+ */
+export declare function getGradientMidpointColor(es: EditableSVG, raw: string | number | null | undefined, opacity?: number): IRColor | null;
+/** 尝试把 fill/stroke 属性值解析为渐变 paint;非 url(#id) 返回 null。 */
+export declare function resolveGradientPaint(es: EditableSVG, raw: string | number | null | undefined, opacity: number, bbox: ShapeBBox): IRGradientPaint | null;
+/** IR 当前仅表达 pad 渐变语义；repeat 和 reflect 没有对应的 shader 参数，因此保持未映射并报告 warning。 */
+/** 读取渐变 stop 的 alpha 值。 */
+export declare function gradientStopColorAlpha(el: Element, rawPaint: string): number[];

package/dist/svg2ir/converter/shape/convert-annulus.d.ts

@@ -0,0 +1,10 @@
+import type EditableSVG from '../../../parse-svg/svg-parser';
+import type { Element } from '@svgdotjs/svg.js';
+import type { IRShape, IREllipseShape } from '@vvfx/animation-ir';
+/**
+ * 将精确的 SVG 环形结构 `outer-circle + inner-circle` 转换为椭圆中心线和描边。
+ *
+ * 该判断比通用嵌套轮廓转换更严格：渐变填充、paint 动画、非圆形路径和任意圆角图形
+ * 继续使用 custom path，避免改变这些 SVG 的填充语义。
+ */
+export declare function convertCircularAnnulusToEllipseStroke(es: EditableSVG, el: Element, shape: IRShape): IREllipseShape | null;

package/dist/svg2ir/converter/shape/parse-dash.d.ts

@@ -0,0 +1,23 @@
+/**
+ * SVG stroke-dasharray 到 IR open subpath 的转换。
+ *
+ * 该模块只处理虚线判断和几何切分，不负责普通 shape 的解析或样式组装。
+ */
+import type EditableSVG from '../../../parse-svg/svg-parser';
+import type { Element } from '@svgdotjs/svg.js';
+import type { IRBezierPath, IRShapeStroke, IRShapeStyle } from '@vvfx/animation-ir';
+type IRShapePaint = NonNullable<IRShapeStyle['fills']>[number];
+/** 解析 stroke-dasharray / stroke-dashoffset → { dash(偶数长), offset∈[0,patternLen), patternLen }。null=无有效虚线。
+ *  SVG spec:dash 奇数个时复制一遍(e.g. "7" → "7 7");偶索引是 on(实)、奇索引是 off(虚)。 */
+export declare function parseDashArray(es: EditableSVG, el: Element): {
+    dash: number[];
+    offset: number;
+    patternLen: number;
+} | null;
+/** 共享虚线合成判断，并决定是否生成对应 warning。
+ *  合成 ROI:有虚线描边、无 fill、无 0 长度 on-dash、所有 subpath 全直线(切线恒 {0,0})且 open。任一不满足返 false。 */
+export declare function canSynthesizeDash(es: EditableSVG, el: Element, fills: IRShapePaint[], strokes: IRShapeStroke[], strokeWidth: number | undefined, customPaths: IRBezierPath[] | undefined): boolean;
+/** 把直线 open subpath 按虚线 on-区间切成多条 open 子路径(绝对 SVG 坐标,之后照常 -cx/-cy 转相对)。
+ *  SVG dash 跨顶点连续:一个跨顶点的 on-dash 是一条横跨该顶点的段(join 在此渲,只在 dash 自身端点渲 cap)。 */
+export declare function synthesizeDashSubpaths(paths: IRBezierPath[], dash: number[], offset: number, patternLen: number): IRBezierPath[];
+export {};

package/dist/svg2ir/converter/shape/parse-shape-element.d.ts

@@ -0,0 +1,4 @@
+import type EditableSVG from '../../../parse-svg/svg-parser';
+import type { Element } from '@svgdotjs/svg.js';
+import type { IRShape } from '@vvfx/animation-ir';
+export declare function parseShapeElement(es: EditableSVG, el: Element, tag: string): IRShape | null;

package/dist/svg2ir/converter/shape/parse-shape-primitives.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 将 SVG 基本形状元素解析为 IRShape。
+ *
+ * 支持 rect、circle、ellipse、line、polygon、polyline 和 path；坐标使用 SVG 设计像素。
+ */
+import type EditableSVG from '../../../parse-svg/svg-parser';
+import type { Element } from '@svgdotjs/svg.js';
+import type { IRCustomShape, IREllipseShape, IRRectangleShape } from '@vvfx/animation-ir';
+/** 读 borderRadius 风格字段:返 number 或 undefined(解析底座数值属性返 number)。 */
+/** SVG <rect x y width height rx ry> → IRRectangleShape。 */
+export declare function parseRect(es: EditableSVG, el: Element): IRRectangleShape;
+/** SVG <circle cx cy r> / <ellipse cx cy rx ry> → IREllipseShape。 */
+export declare function parseEllipse(es: EditableSVG, el: Element, isCircle: boolean): IREllipseShape;
+/** SVG <path d> / <polygon points> / <polyline points> / <line x1 y1 x2 y2> → IRCustomShape。 */
+export declare function parseCustomPath(es: EditableSVG, el: Element, kind: 'path' | 'polygon' | 'polyline' | 'line'): IRCustomShape | null;

package/dist/svg2ir/converter/smil/apply-opacity-composition.d.ts

@@ -0,0 +1,6 @@
+import type { IRTransform } from '@vvfx/animation-ir';
+import { type BeginTimeCache, type SMILAnimation, type TransformStage } from './types';
+export declare function readStaticOpacity(node: globalThis.Element): number;
+export declare function readStaticVisibility(node: globalThis.Element): number;
+export declare function collectOpacityAnimations(stage: TransformStage, root: globalThis.Element, beginCache: BeginTimeCache, comparisonDuration?: number): SMILAnimation[];
+export declare function applySampledOpacityComposition(stages: TransformStage[], animationsByStage: SMILAnimation[][], transform: IRTransform, frameRate: number): void;

package/dist/svg2ir/converter/smil/apply-transform-animation.d.ts

@@ -0,0 +1,14 @@
+import type { IRTransform } from '@vvfx/animation-ir';
+import { type TransformContext } from './types';
+export declare function applySMILToTransform(el: {
+    node?: globalThis.Element | null;
+}, transform: IRTransform, outDuration: {
+    value: number;
+}, frameRate: number, context: TransformContext): void;
+export declare function applySMILToTransformWithOuter(innerEl: {
+    node?: globalThis.Element | null;
+}, outerEl: {
+    node?: globalThis.Element | null;
+}, transform: IRTransform, outDuration: {
+    value: number;
+}, frameRate: number, innerContext: TransformContext, outerContext: TransformContext): void;

package/dist/svg2ir/converter/smil/apply-transform-composition.d.ts

@@ -0,0 +1,4 @@
+import type { IRTransform } from '@vvfx/animation-ir';
+import { type SVGMatrix } from '../../matrix';
+import { type TransformContext, type TransformStage } from './types';
+export declare function applySampledTransformComposition(stages: TransformStage[], baseMatrix: SVGMatrix, transform: IRTransform, frameRate: number, context: TransformContext): void;

package/dist/svg2ir/converter/smil/build-keyframes.d.ts

@@ -0,0 +1,10 @@
+import type { IRAnimatedProperty, IRKeyframe, IRPropertyValue, IRVec3 } from '@vvfx/animation-ir';
+import { type SVGMatrix } from '../../matrix';
+import { type SMILAnimation } from './types';
+export declare function makeKeyframes<T extends IRPropertyValue>(animation: SMILAnimation, frameRate: number, mapValue: (value: number[], index: number) => T, baseValue?: T): IRKeyframe<T>[];
+export declare function matrixForTransformValue(type: string, value: number[]): SVGMatrix;
+export declare function applyRotateSpatialTangents(animation: SMILAnimation, keyframes: IRKeyframe<IRVec3>[], baseMatrix: SVGMatrix, localCenter: [number, number]): void;
+export declare function staticValue<T extends number | IRVec3>(property: IRAnimatedProperty<T> | undefined, fallback: T): T;
+export declare function subdivideFullTurn(animation: SMILAnimation): SMILAnimation;
+export declare function unwrapRotationValues(animation: SMILAnimation, matrices: SVGMatrix[]): number[];
+export declare function sampleAnimationValue(animation: SMILAnimation, time: number): number[] | null;

package/dist/svg2ir/converter/smil/collect-geometry-animation.d.ts

@@ -0,0 +1,7 @@
+import { type BeginTimeCache, type GeometryAnimation, type TransformContext, type TransformStage } from './types';
+declare const LINE_ATTRIBUTES: readonly ["x1", "y1", "x2", "y2"];
+type LineAttribute = typeof LINE_ATTRIBUTES[number];
+export declare function isLineGeometryAttribute(attributeName: string): attributeName is LineAttribute;
+export declare function canConvertLineGeometryAnimations(target: globalThis.Element, root: globalThis.Element): boolean;
+export declare function collectGeometryAnimation(stage: TransformStage, root: globalThis.Element, beginCache: BeginTimeCache, context: TransformContext): GeometryAnimation | null;
+export {};

package/dist/svg2ir/converter/smil/inspect-animation.d.ts

@@ -0,0 +1,6 @@
+import type { Element } from '@svgdotjs/svg.js';
+export declare function isMappedSMILAnimationElement(el: Element, tag: string): boolean;
+/** 判断元素或祖先是否存在 opacity 动画。 */
+export declare function hasDirectOpacityAnimation(node: globalThis.Element | null | undefined): boolean;
+export declare function hasAnimatedVisibility(el: Element): boolean;
+export declare function hasAnimatedAncestorOpacity(el: Element): boolean;

package/dist/svg2ir/converter/smil/parse-motion.d.ts

@@ -0,0 +1,4 @@
+import type { SVGMatrix } from '../../matrix';
+import { type BeginTimeCache, type MotionAnimation } from './types';
+export declare function parseMotionAnimation(tag: globalThis.Element, root: globalThis.Element, beginCache: BeginTimeCache, comparisonDuration?: number): MotionAnimation | null;
+export declare function motionMatrixAtTime(animation: MotionAnimation, time: number): SVGMatrix | null;

package/dist/svg2ir/converter/smil/parse-paint-animation.d.ts

@@ -0,0 +1,13 @@
+import type { SVGPreservedPaintAnimation } from '../../../svg-preserved-data';
+export declare function parseSMILPaintAnimations(el: {
+    node?: globalThis.Element | null;
+}, frameRate: number, comparisonDuration: number, baseOpacity: {
+    fill: number;
+    stroke: number;
+}, alphaBase: {
+    fill: number;
+    stroke: number;
+}, paintSources: {
+    fill?: string;
+    stroke?: string;
+}, baseStrokeWidth?: number): SVGPreservedPaintAnimation[];

package/dist/svg2ir/converter/smil/parse-shape-animation.d.ts

@@ -0,0 +1,4 @@
+import type { IRShape } from '@vvfx/animation-ir';
+import type { Element } from '@svgdotjs/svg.js';
+import type { SVGPreservedShapeAnimation } from '../../../svg-preserved-data';
+export declare function parseShapeGeometryAnimation(el: Element, shape: IRShape, comparisonDuration: number): SVGPreservedShapeAnimation | undefined;

package/dist/svg2ir/converter/smil/parse-timeline.d.ts

@@ -0,0 +1,4 @@
+import type { BeginTimeCache, SMILAnimation, SMILValueParser } from './types';
+export { cubicBezierRatio, interpolateValues, parseColorValue, parseNumberList, parsePointValue, parseKeySplines, parseValue, sampleExpandedValue, splitCubicAtRatio, valuesEqual, } from './timeline-values';
+export { activeDuration, comparisonEnd, findAnimationById, parseClockValue, resolveBegin, resolveBeginTimes, } from './timeline-schedule';
+export declare function parseSMILTag(tag: globalThis.Element, root: globalThis.Element, beginCache: BeginTimeCache, comparisonDuration?: number, valueParser?: SMILValueParser, underlyingValue?: number[]): SMILAnimation | null;

package/dist/svg2ir/converter/smil/resolve-animation-target.d.ts

@@ -0,0 +1,4 @@
+/** Resolve the element animated by a direct or href-targeted SMIL element. */
+export declare function resolveSMILAnimationTarget(animation: globalThis.Element, root: globalThis.Element): globalThis.Element | null;
+/** Collect direct and href-targeted SMIL elements for one SVG element in document order. */
+export declare function collectSMILAnimationElements(target: globalThis.Element, root: globalThis.Element, tags?: ReadonlySet<string>): globalThis.Element[];

package/dist/svg2ir/converter/smil/sample-composition-frames.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 单个图层烘焙组合变换时的采样点上限。
+ *
+ * 组合变换只能栅格化，采样密度直接决定 IR 与 GE 的体积：长时间线会转出上百 MB
+ * 场景数据，Effects 解析时锁死主线程。与 COMPOSITION_SAMPLE_STEP 共同决定切换点，
+ * 1024 点约合 256 帧（30fps 下 8.5 秒）之后转入误差驱动细分。
+ */
+export declare const MAX_COMPOSITION_SAMPLES = 1024;
+/** 烘焙组合变换的基准采样间隔（帧）。 */
+export declare const COMPOSITION_SAMPLE_STEP = 0.25;
+export interface CompositionFrameSample<T> {
+    frame: number;
+    value: T;
+}
+export interface CompositionFrameSamplingOptions<T> {
+    /** 时间线末帧。 */
+    endFrame: number;
+    /** 承载语义、必须保留的时刻：源关键帧、区间边界、动画起止。 */
+    anchorFrames: number[];
+    /** 瞬时跳变时刻。跨越它的区间不参与细分，否则误差必然超限并耗尽预算。 */
+    jumpFrames?: number[];
+    /** 求指定帧的组合值。 */
+    evaluate: (frame: number) => T;
+    /** 把值对齐到左邻所在分支，例如角度跨过 ±180° 时补整圈。 */
+    unwrapForMeasure?: (value: T, left: T) => T;
+    /** 相对线性插值的误差，1 表示刚好达到容忍度；t 为区间内的归一化位置。 */
+    normalizeError: (value: T, left: T, right: T, t: number) => number;
+}
+/**
+ * 组合变换的采样入口。
+ *
+ * 均匀网格装得进预算时照常铺网；超出预算时按误差细分，保留全部锚点，只加密
+ * 线性插值误差超限的区间。
+ */
+export declare function sampleCompositionFrames<T>(options: CompositionFrameSamplingOptions<T>): CompositionFrameSample<T>[];
+/**
+ * 在锚点之间按误差细分。
+ *
+ * 锚点全部保留；只有相对两端线性插值的误差超限时才继续二分，因此线性区间不会
+ * 增加采样点，而曲线路径（如绕远端支点旋转的圆心轨迹）会被检测到。
+ */
+export declare function refineCompositionFrames<T>(options: CompositionFrameSamplingOptions<T>): CompositionFrameSample<T>[];

package/dist/svg2ir/converter/smil/scan-duration.d.ts

@@ -0,0 +1,4 @@
+/** 返回 root 下全部 SMIL 动画的有限比较区间。 */
+export declare function getSMILDuration(element: {
+    node?: globalThis.Element | null;
+}): number;

package/dist/svg2ir/converter/smil/timeline-schedule.d.ts

@@ -0,0 +1,17 @@
+/**
+ * SMIL begin/end、repeat 和 syncbase 时间调度。
+ *
+ * 本模块不负责动画值插值，只负责确定动画何时开始、结束以及哪些 interval 需要展开。
+ */
+import { type BeginTimeCache } from './types';
+export declare function parseClockValue(raw: string): number | null;
+export declare function activeDuration(tag: globalThis.Element): number;
+export declare function findAnimationById(root: globalThis.Element, id: string): globalThis.Element | null;
+export declare function getBeginTimeCache(root: globalThis.Element, comparisonDuration?: number): BeginTimeCache;
+export declare function resolveBeginTimes(tag: globalThis.Element, root: globalThis.Element, cache: BeginTimeCache, comparisonDuration?: number): number[];
+export declare function resolveBegin(tag: globalThis.Element, root: globalThis.Element, cache: BeginTimeCache): number | null;
+export declare function comparisonEnd(tag: globalThis.Element, begin: number): number;
+export declare function buildAnimationWindows(tag: globalThis.Element, beginTimes: number[], totalDuration: number, comparisonDuration?: number): Array<{
+    begin: number;
+    end: number;
+}>;

package/dist/svg2ir/converter/smil/timeline-values.d.ts

@@ -0,0 +1,20 @@
+import type { IRBezierHandle } from '@vvfx/animation-ir';
+import { type SMILAnimation, type SMILSample, type SMILValueParser } from './types';
+export declare function parseNumberList(value: string): number[];
+export declare function parseValue(value: string, type: string): number[];
+export declare function parseColorValue(value: string): number[] | null;
+export declare function parsePointValue(value: string): [number, number];
+export declare function parseKeySplines(tag: globalThis.Element, segmentCount: number): IRBezierHandle[][];
+/** 根据相邻值的数值距离计算 paced 动画的时间节点，忽略 authored keyTimes。 */
+export declare function parsePacedKeyTimes(values: number[][]): number[];
+export declare function parseValues(tag: globalThis.Element, type: string, valueParser?: SMILValueParser, underlyingValue?: number[]): number[][];
+export declare function valuesEqual(a: number[], b: number[]): boolean;
+export declare function interpolateValues(from: number[], to: number[], ratio: number): number[];
+export declare function cubicBezierRatio(ratio: number, handles: IRBezierHandle[]): number;
+export declare function splitCubicAtRatio(ratio: number, handles: IRBezierHandle[]): {
+    out: IRBezierHandle;
+    in: IRBezierHandle;
+};
+export declare function sampleExpandedValue(samples: SMILSample[], time: number, calcMode: SMILAnimation['calcMode'], keySplines: IRBezierHandle[][]): SMILSample | null;
+export declare function clipSamplesToComparisonWindow(samples: SMILSample[], end: number, calcMode: SMILAnimation['calcMode'], keySplines: IRBezierHandle[][], fill: SMILAnimation['fill']): SMILSample[];
+export declare function expandSamples(values: number[][], keyTimes: number[], begin: number, duration: number, totalDuration: number, accumulate: boolean, calcMode?: SMILAnimation['calcMode'], keySplines?: IRBezierHandle[][]): SMILSample[];

package/dist/svg2ir/converter/smil/types.d.ts

@@ -0,0 +1,129 @@
+import type { IRAnimatedProperty, IRBezierHandle, IRVec3 } from '@vvfx/animation-ir';
+import type { SVGMatrix } from '../../matrix';
+export interface SMILSample {
+    time: number;
+    value: number[];
+    cycle: number;
+    sourceIndex: number;
+    /**
+     * fractional active interval 结束位置的合成样本 metadata。
+     * 该值已经按 authored simple-time 计算，不能作为普通 keyframe 再次应用 spline 缓动。
+     */
+    activeEndSegment?: {
+        cycleStartTime: number;
+        segmentIndex: number;
+        startTime: number;
+        endTime: number;
+        startValue: number[];
+        endValue: number[];
+    };
+}
+export interface SMILInterval {
+    begin: number;
+    end: number;
+    sampleStart: number;
+    sampleEnd: number;
+}
+/** 解析后的 active SMIL interval，已展开有限 repeat。 */
+export interface SMILAnimation {
+    attributeName: string;
+    type: string;
+    begin: number;
+    end: number;
+    fill: 'remove' | 'freeze';
+    additive: 'replace' | 'sum';
+    byOnly: boolean;
+    indefinite: boolean;
+    calcMode: 'linear' | 'discrete' | 'spline' | 'paced';
+    keySplines: IRBezierHandle[][];
+    samples: SMILSample[];
+    intervals: SMILInterval[];
+}
+export interface TransformContext {
+    ancestorMatrix: SVGMatrix;
+    selfMatrix: SVGMatrix;
+    localCenter: [number, number];
+    ancestorStopNode?: globalThis.Element | null;
+    preserveAncestorTransforms?: boolean;
+    geometry?: GeometryContext;
+    geometryScaleSink?: {
+        value?: IRAnimatedProperty<IRVec3>;
+    };
+    comparisonDuration?: number;
+    /** 将文本 paint alpha 与图层 opacity 分离，并在图层轨道上合成各级 authored opacity。 */
+    composeOpacityAcrossStages?: boolean;
+}
+export interface GeometryContext {
+    kind: 'rect' | 'circle' | 'ellipse' | 'line' | 'use';
+    base: Record<string, number>;
+    referenceWidth: number;
+    referenceHeight: number;
+}
+export interface GeometryAnimation {
+    animations: SMILAnimation[];
+    matrixAtTime: (time: number) => SVGMatrix;
+    scaleAtTime: (time: number) => {
+        x: number;
+        y: number;
+    };
+}
+export interface GeometrySample {
+    centerX: number;
+    centerY: number;
+    scaleX: number;
+    scaleY: number;
+}
+export interface TransformStage {
+    node: globalThis.Element;
+    staticMatrix: SVGMatrix;
+    animations: SMILAnimation[];
+    motions: MotionAnimation[];
+    geometry?: GeometryAnimation;
+    ignoreOpacity?: boolean;
+}
+export interface MotionPathSegment {
+    p0: [number, number];
+    p1: [number, number];
+    p2: [number, number];
+    p3: [number, number];
+    length: number;
+    samples: Array<{
+        t: number;
+        length: number;
+    }>;
+}
+export interface MotionPath {
+    segments: MotionPathSegment[];
+    totalLength: number;
+    vertexProgress: number[];
+}
+export interface MotionAnimation {
+    begin: number;
+    end: number;
+    simpleDuration: number;
+    activeDuration: number;
+    fill: 'remove' | 'freeze';
+    additive: 'replace' | 'sum';
+    indefinite: boolean;
+    calcMode: SMILAnimation['calcMode'];
+    keySplines: IRBezierHandle[][];
+    keyTimes: number[];
+    keyPoints: number[];
+    usesKeyPoints: boolean;
+    path: MotionPath;
+    pointValues?: Array<[number, number]>;
+    rotate: 'auto' | 'auto-reverse' | number;
+}
+export declare const EPSILON = 1e-9;
+export declare const BEGIN_TIME_EPSILON = 1e-7;
+export declare const LINEAR_OUT_TANGENT: IRBezierHandle;
+export declare const LINEAR_IN_TANGENT: IRBezierHandle;
+export declare const MAX_SYNCBASE_EVENTS = 10000;
+export type BeginTimeCache = Map<globalThis.Element, number[]>;
+export interface SyncbaseDependency {
+    source: globalThis.Element;
+    target: globalThis.Element;
+    event: 'begin' | 'end';
+    offset: number;
+}
+export type SMILValueParser = (value: string, type: string) => number[] | null;

package/dist/svg2ir/converter/switch-branch.d.ts

@@ -0,0 +1,3 @@
+import type { Element } from '@svgdotjs/svg.js';
+export declare function getActiveSwitchChild(switchNode: globalThis.Element): globalThis.Element | null;
+export declare function isInInactiveSwitchBranch(element: Element): boolean;

package/dist/svg2ir/converter/text/build-per-line-text-layers.d.ts

@@ -0,0 +1,11 @@
+/** 将各行具有独立水平锚点的多行文本拆分为多个 IR 文本图层。 */
+import type EditableSVG from '../../../parse-svg/svg-parser';
+import type { Element } from '@svgdotjs/svg.js';
+import type { IRTextLayer } from '@vvfx/animation-ir';
+import { type TextMeasure } from './font-metrics';
+import type { TextContentResult } from './inspect-content';
+import type { SVGPreservedTextData } from '../../../svg-preserved-data';
+export declare function buildPerLineTextLayers(es: EditableSVG, el: Element, textContent: TextContentResult, measureText?: TextMeasure): {
+    layers: Array<Omit<IRTextLayer, 'id' | 'name' | 'time'>>;
+    infos: SVGPreservedTextData[];
+} | null;

package/dist/svg2ir/converter/text/build-single-text-layer.d.ts

@@ -0,0 +1,11 @@
+/** 构造普通文本图层。 */
+import type EditableSVG from '../../../parse-svg/svg-parser';
+import type { Element } from '@svgdotjs/svg.js';
+import type { IRTextLayer } from '@vvfx/animation-ir';
+import { type TextMeasure } from './font-metrics';
+import type { TextContentResult } from './inspect-content';
+import type { SVGPreservedTextData } from '../../../svg-preserved-data';
+export declare function buildSingleTextLayer(es: EditableSVG, el: Element, textContent: TextContentResult, measureText?: TextMeasure): {
+    layer: Omit<IRTextLayer, 'id' | 'name' | 'time'> | null;
+    info: SVGPreservedTextData | null;
+};

package/dist/svg2ir/converter/text/build-split-text-layers.d.ts

@@ -0,0 +1,11 @@
+/** 构造需要独立定位的单行文本图层。 */
+import type EditableSVG from '../../../parse-svg/svg-parser';
+import type { Element } from '@svgdotjs/svg.js';
+import type { IRTextLayer } from '@vvfx/animation-ir';
+import { type TextMeasure } from './font-metrics';
+import type { TextContentResult } from './inspect-content';
+import type { SVGPreservedTextData } from '../../../svg-preserved-data';
+export declare function buildSplitTextLayers(es: EditableSVG, el: Element, textContent: TextContentResult, measureText: TextMeasure): {
+    layers: Array<Omit<IRTextLayer, 'id' | 'name' | 'time'>>;
+    infos: SVGPreservedTextData[];
+} | null;

package/dist/svg2ir/converter/text/build-vertical-text-layers.d.ts

@@ -0,0 +1,10 @@
+/** 将竖排文本按字符拆分为独立 IR 文本图层。 */
+import type EditableSVG from '../../../parse-svg/svg-parser';
+import type { Element } from '@svgdotjs/svg.js';
+import type { IRTextLayer } from '@vvfx/animation-ir';
+import { type TextMeasure } from './font-metrics';
+import type { SVGPreservedTextData } from '../../../svg-preserved-data';
+export declare function buildVerticalTextLayers(es: EditableSVG, el: Element, measureText?: TextMeasure): {
+    layers: Array<Omit<IRTextLayer, 'id' | 'name' | 'time'>>;
+    infos: SVGPreservedTextData[];
+} | null;

package/dist/svg2ir/converter/text/font-metrics.d.ts

@@ -0,0 +1,53 @@
+/**
+ * SVG 文本到 Effects 文本组件共用的字体、度量和宽度估算逻辑。
+ *
+ * 这些函数不读取 SVG DOM，只根据字体属性和可选的 measureText 回调计算文本布局数据。
+ */
+type IRFontWeight = 'normal' | 'bold' | 'lighter';
+interface TextMeasureResult {
+    width: number;
+    fontBoundingBoxAscent?: number;
+    fontBoundingBoxDescent?: number;
+    actualBoundingBoxAscent?: number;
+    hangingBaseline?: number;
+}
+export type TextMeasure = (fontDesc: string, text: string) => TextMeasureResult;
+export declare function mapFontWeight(raw: string, fontFamily?: string): IRFontWeight;
+/** 从字体族名中推断数值字重(100-950)。
+ *  优先级:关键词 > Linotype 数字代码 > 裸 100-900 数字 > AlibabaPuHuiTi 单字母后缀。 */
+export declare function inferNumericWeightFromFamily(family: string): number | null;
+/** 解析 Effects RichText strategies 所需的字体 asc/desc 与 x-height。
+ * 有 measureText 回调时使用当前字体指标；没有回调时使用字族比例估算。
+ * SVG 的 precise baseline 指标按实际字号读取，Effects layout metric 按字号比例缩放。 */
+export declare function resolveFontMetrics(measureText: TextMeasure | undefined, fontFamily: string, fontWeight: IRFontWeight, fontStyle: string, fontSize: number): {
+    asc: number;
+    desc: number;
+    xHeight: number;
+    hanging?: number;
+    svgAsc?: number;
+    svgDesc?: number;
+};
+/** 将 SVG dominant-baseline 转换为 Effects alphabetic baseline 的 y 偏移。
+ * Effects 没有独立的 dominant-baseline 字段，因此复用字体 asc/desc、x-height 和可用的 hangingBaseline。 */
+export declare function dominantBaselineDelta(baseline: string | undefined, asc: number, desc: number, xHeight: number, precise?: {
+    hanging?: number;
+    svgAsc?: number;
+    svgDesc?: number;
+}): number;
+/** 读取各空格字符在目标字体下的 advance，返回去重后的候选表。 */
+export declare function buildSpaceCharTable(measureText: TextMeasure, fd: string): Array<{
+    ch: string;
+    w: number;
+}>;
+/** 选择 advance 最接近目标值的单个空格字符。 */
+export declare function greedySpaceForDx(target: number, table: Array<{
+    ch: string;
+    w: number;
+}>): string;
+/** 构造与 Effects Runtime getFontDesc 一致的 CSS font 简写字符串,用于 Canvas measureText。 */
+export declare function buildCanvasFontDesc(fontSize: number, fontFamily: string, fontWeight: IRFontWeight, fontStyle: string): string;
+/** 文本宽度估算。优先使用调用方提供的 Canvas measureText，否则使用字符级启发式系数。 */
+export declare function estimateTextWidth(content: string, fontSize: number, letterSpacing: number, measureText: ((fontDesc: string, text: string) => {
+    width: number;
+}) | undefined, fontFamily: string, fontWeight: IRFontWeight, fontStyle: string): number;
+export {};

package/dist/svg2ir/converter/text/inspect-content.d.ts

@@ -0,0 +1,42 @@
+/**
+ * SVG text/tspan 内容读取与偏移、拆段结构判定。
+ *
+ * 该模块只解释 SVG 文本 DOM，不负责创建 IR layer 或计算 Effects 文本布局。
+ * 拆段结构判定结果供文本布局模块使用。
+ */
+import type EditableSVG from '../../../parse-svg/svg-parser';
+import type { Element } from '@svgdotjs/svg.js';
+import type { SVGPreservedTextSpan } from '../../../svg-preserved-data';
+/** SVG tspan dx 属性原串是否为 svg2ir 可处理形态。
+ *  - 'unsupported':列表(含空格多值,逐字偏移)/百分比(含 %)/非 px 单位(em/ex/pt 等)。parseFloat 会静默
+ *    只取首数或剥离单位当成 px(如 '50%'→50),与 SVG 语义不符 → 走 ge-capability 旁路,不拆不烘焙。
+ *  - 'ok':单数值 px(含负值,拆段 leftEdge 累加负值表达段叠,多 comp z-order=文档序与 SVG 一致)。
+ *  空串(无 dx)不算 unsupported,调用方先判空。 */
+export declare function isUnsupportedTextOffset(dxRaw: string): boolean;
+/** 是否存在非首段 tspan 显式 x(绝对锚点重置,与 leftEdge 累加矛盾→不拆)。首段 x 已由 blockLeft 处理。 */
+export declare function hasNonFirstTspanExplicitX(el: Element): boolean;
+/** 是否竖排(writing-mode=vertical-rl/lr/tb-rl/tb-lr 等)。Effects 富文本无竖排原生布局,需逐字拆层;拆段路径不重复处理。
+ *  用 es.getAttr 读取以保留解析底座的继承语义,不切换到 raw getAttribute(会丢继承值)。 */
+export declare function hasWritingMode(es: EditableSVG, el: Element): boolean;
+/** 是否有直接子 tspan 带 transform 或 rotate 属性(markup 无旋转/矩阵,拆段各 comp 用 <text> 矩阵会丢→不拆)。 */
+export declare function hasTspanTransformOrRotate(el: Element): boolean;
+/** 是否存在嵌套 tspan(tspan 含元素子节点)。readTextContent 不递归,嵌套文字会错并进父段→不拆。 */
+export declare function hasNestedTspan(el: Element): boolean;
+/** 读 <text> 直接子文本 + 子 <tspan>。单 <text> 多 <tspan y=不同> 是 SVG 多行:
+ *  按 tspan 的 y(绝对,相对 <text>)分行,\n 连接给 Effects TextComponent 多行渲染(lineCount/lineHeight)。
+ *  无 y 的 tspan 连排(同行)。返回 {content(\n 连接),lineHeight(首两行 y 差,0=单行),lineCount,lineTexts}。
+ *  per-span 样式需要富文本表达；无法表达的样式差异由 warning 报告。
+ */
+export interface TextContentResult {
+    content: string;
+    lineHeight: number;
+    lineCount: number;
+    lineTexts: string[];
+    firstTspanX: number | null;
+    firstTspanY: number | null;
+    spans: SVGPreservedTextSpan[];
+    isPathText: boolean;
+    lineXs: Array<number | null>;
+    lineYs: number[];
+}
+export declare function readTextContent(el: Element): TextContentResult;

package/dist/svg2ir/converter/text/parse.d.ts

@@ -0,0 +1,10 @@
+/** 选择文本布局并构造 IR 文本图层。 */
+import type EditableSVG from '../../../parse-svg/svg-parser';
+import type { Element } from '@svgdotjs/svg.js';
+import type { IRTextLayer } from '@vvfx/animation-ir';
+import type { SVGPreservedTextData } from '../../../svg-preserved-data';
+import type { TextMeasure } from './font-metrics';
+export declare function parseTextLayers(es: EditableSVG, el: Element, measureText?: TextMeasure): {
+    layers: Array<Omit<IRTextLayer, 'id' | 'name' | 'time'>>;
+    infos: SVGPreservedTextData[];
+} | null;

package/dist/svg2ir/converter/text/text-layout.d.ts

@@ -0,0 +1,29 @@
+import type EditableSVG from '../../../parse-svg/svg-parser';
+import type { Element } from '@svgdotjs/svg.js';
+import type { IRColor } from '@vvfx/animation-ir';
+import type { SVGPreservedTextData, SVGPreservedTextSpan } from '../../../svg-preserved-data';
+export declare const TEXT_ANCHOR_MAP: Record<string, 'left' | 'center' | 'right'>;
+export declare const FONT_STYLE_MAP: Record<string, 'normal' | 'italic' | 'oblique'>;
+export type TextFontWeight = 'normal' | 'bold' | 'lighter';
+/** 构造 SVG 文本的保留数据。 */
+export declare function buildSVGPreservedTextData(spans: SVGPreservedTextSpan[], isPathText: boolean, fontFamily: string, fontWeight: TextFontWeight, fontStyle: SVGPreservedTextData['fontStyle']): SVGPreservedTextData;
+/** 根据 direction=rtl 调整 text-anchor 的水平对齐。 */
+export declare function resolveEffectiveTextAlign(es: EditableSVG, el: Element, textAlign: 'left' | 'center' | 'right'): 'left' | 'center' | 'right';
+/** 合并文本元素及祖先变换，并分解出 IR 支持的缩放和旋转。 */
+export declare function buildTextWorldMatrix(el: Element): {
+    sx: number;
+    sy: number;
+    rotation: number;
+    m: import("../../matrix").SVGMatrix;
+};
+/** 解析 text 级 fill 颜色；渐变使用中点色，缺省或 none 使用黑色。 */
+export declare function resolveTextFillColor(es: EditableSVG, fillRaw: string | number | null | undefined, fillOpacity: number): IRColor;
+/** 读取 text 自身和祖先组的 opacity，以及 fill-opacity。 */
+export declare function readTextOpacity(es: EditableSVG, el: Element): {
+    totalOpacity: number;
+    fillOpacity: number;
+};
+/** 将 IR 颜色编码为十六进制字符串。 */
+export declare function irColorToHex(c: IRColor): string;
+/** 读取 letter-spacing，并转换为像素值。 */
+export declare function readLetterSpacing(es: EditableSVG, el: Element, fontSize: number): number;

package/dist/svg2ir/converter/transform/build-transform.d.ts

@@ -0,0 +1,15 @@
+import type EditableSVG from '../../../parse-svg/svg-parser';
+import type { Element } from '@svgdotjs/svg.js';
+import type { IRAnimatedProperty, IRShape, IRTransform, IRVec3 } from '@vvfx/animation-ir';
+import type { GeometryContext } from '../smil/types';
+export declare function readRawNumberAttribute(el: Element, name: string, fallback?: number): number;
+export declare function prepareSMILShapeGeometry(el: Element, shape: IRShape): void;
+export declare function buildTransformGeometry(el: Element, shape: IRShape): GeometryContext | undefined;
+export declare function buildTransform(es: EditableSVG, el: Element, shape: IRShape, smilDurationSink: {
+    value: number;
+}, frameRate: number, geometryScaleSink?: {
+    value?: IRAnimatedProperty<IRVec3>;
+}): IRTransform;
+export declare function applySMILToParsedTransform(el: Element, transform: IRTransform | undefined, smilDurationSink: {
+    value: number;
+}, frameRate: number, composeOpacityAcrossStages?: boolean): void;