@pixodesk/svg-animator-core 1.0.40 → 1.0.41

package/dist/internal.d.ts

@@ -1 +1,378 @@
-export { C as COLOR_ATTR_NAMES, f as CSS_ONLY_STYLE_PROPS, D as DEFAULT_DURATION_MS, g as DISALLOWED_SVG_TAGS_LOWER, G as GlyphCharBox, L as LOOP_JUMP_SHIFT_MS, M as MaterializeAllOptions, h as PCT_BASED_ATTR_NAMES, k as PX_ANIM_ATTR_NAME, l as PX_ANIM_SRC_ATTR_NAME, o as PX_UNKNOWN_KEY_ERROR, r as PxAnimatable, x as PxAnyKeyframe, O as PxCreateElement, aj as PxNormalizedKeyframe, ak as PxNormalizedPropertyAnimation, a_ as STYLE_ATTR_NAMES, a$ as TEXT_CONTENT_ATTR, b0 as TRANSFORM_FN_NAMES, b9 as bezierToSvgPath, bb as camelCaseToKebabWordIfNeeded, bc as clamp, be as composeTransformParts, bh as createDiagnostics, bi as createPathSampler, bj as cubicBezier, bk as deepClone, bn as diffFieldUniverse, bo as diffInEffect, bq as extendedPathForBrowser, bu as generateUniqueId, bB as interpolateValue, bF as isScrollTimeline, bG as kebabToCamelCaseWord, bH as kfEasing, bI as kfValue, bJ as layoutGlyphTextChars, bL as materializeGlyphText, bM as materializeGlyphTextAlongPath, bN as materializeMotionPathInPropAnim, bP as mergeStaticTransformIntoAnimDef, bS as planSchemaRelease, bV as releaseLogProblems, bW as reportDocumentDiagnostics, b_ as reverseEasing, b$ as sanitizeAttributeValue, c0 as schemaFieldUniverse, c2 as scrollOffsetProgress, c3 as scrollPhaseInterval, c4 as scrollResolveAxis, c5 as scrollTotalDurationMs, c6 as scrollViewProgress, c7 as splitEasing, c8 as subdivideCubicBezier, c9 as toRGBA } from './internal-BZSJtt_h.js';
+import { e as PxNode, O as PxGlyphFont, bm as PxAnimatable, c as PxAnimatorConfig, ag as PxScroll, aj as PxScrollPhase, s as PxBezierPath, aC as PxTransformParts, ae as PxSchema, aQ as PxWireVersionStep, aN as PxWireStepKind } from './PxDocumentDiagnostic-COGEjBbg.js';
+export { bn as PX_ANIM_ATTR_NAME, bo as PX_ANIM_SRC_ATTR_NAME, bp as PX_CSS_ONLY_STYLE_PROPS, bq as PX_DISALLOWED_SVG_TAGS_LOWER, br as PX_LOOP_JUMP_SHIFT_MS, bs as PX_TEXT_CONTENT_ATTR, bt as PX_UNKNOWN_KEY_ERROR, bu as PxAnyKeyframe, bv as PxMaterializeAllOptions, bw as PxNormalizedKeyframe, bx as PxNormalizedPropertyAnimation, by as createDiagnostics, bz as deepClone, bA as generateUniqueId, bB as interpolateValue, bC as keyframeEasing, bD as keyframeValue, bE as materializeMotionPathInPropAnim, bF as mergeStaticTransformIntoAnimDef, bG as reportDocumentDiagnostics, bH as sanitizeAttributeValue } from './PxDocumentDiagnostic-COGEjBbg.js';
+
+interface VmNode {
+    type?: string;
+    children?: Array<VmNode>;
+    [attr: string]: any;
+}
+interface EffectDiff {
+    time: number;
+    onlyInA: Array<string>;
+    onlyInB: Array<string>;
+}
+/**
+ * Compares two trees "in effect" across all keyframe instants found in either.
+ * Returns one entry per time where the painted-primitive multisets differ.
+ * @internal
+ */
+declare function diffInEffect(a: VmNode, b: VmNode): Array<EffectDiff>;
+
+/**
+ * Element-creation factory — abstracts WHAT an "element" is so the same
+ * geometry/layout code (e.g. the glyph text materializer) can emit plain wire
+ * nodes here, or the editor's React / px elements when called from the editor.
+ *
+ * The signature intentionally mirrors the editor's `createPxElement(type,
+ * props, children, fixReactKeysIfNeeded?)` so the editor's own factory drops in
+ * unchanged.
+ * @internal
+ */
+type PxCreateElement<E = any> = (type: string, props: {
+    [k: string]: any;
+}, children?: Array<E> | E | null, fixReactKeysIfNeeded?: boolean) => E;
+
+/** @internal */
+interface PathPoint {
+    x: number;
+    y: number;
+    angle: number;
+}
+/** @internal */
+interface PathSampler {
+    totalLength: number;
+    /** True when the path loops back on itself (explicit `Z` or coincident ends) —
+     *  no open tip to run off, so overflow clamps/wraps rather than clipping. */
+    closed: boolean;
+    sampleAtDistance(dist: number): PathPoint;
+}
+/** @internal */
+declare function createPathSampler(d: string): PathSampler | null;
+
+/**
+ * Glyph text materializer — turns a `<text>`/`<tspan>` subtree into `<path>`
+ * outlines from `definitions.fonts`, so the text renders with no external font.
+ *
+ *  - HORIZONTAL ({@link materializeGlyphTextHorizontal}) — left-to-right by
+ *    advance width; honors font-size, text-anchor, letter/word-spacing,
+ *    per-tspan x/y/dx/dy, fill/stroke, nested tspans.
+ *  - ALONG-PATH ({@link materializeGlyphTextAlongPath}) — each glyph placed and
+ *    rotated to the referenced path's tangent. Static `startOffset` → glyphs
+ *    bake+merge; animated `startOffset` → per-glyph `<path>` with sampled
+ *    `animate.transform`. Text-level `x`/`dx` add distance ALONG the path (≈
+ *    startOffset) and `dy` shifts PERPENDICULAR — matching native `<textPath>`
+ *    (see {@link alongPathNodeOffsets}); `y` and per-tspan positioning are ignored
+ *    (a single run).
+ *
+ * Element creation goes through an injected {@link PxCreateElement} factory, so
+ * the SAME layout produces plain wire nodes here (the effects pipeline) or the
+ * editor's React/px elements when the editor calls it — see
+ * {@link materializeGlyphText}.
+ *
+ * v1 scope (see svga.text.design.md): keyframe-interval easing is linear;
+ * kerning/ligatures, per-tspan opacity, text-level animated fill are out of scope.
+ */
+
+/** Inputs for a glyph materialization, decoupled from the effects `ApplyContext`
+ *  so the editor can call the materializer directly. * @internal
+ */
+interface GlyphMaterializeOptions<E = any> {
+    /** Embedded glyph fonts, keyed by `font-family`. */
+    glyphs: Record<string, PxGlyphFont>;
+    /** Element factory — defaults to plain wire nodes ({@link jsonElementFactory}). */
+    create?: PxCreateElement<E>;
+    /** Optional diagnostics sink. */
+    warnings?: Array<string>;
+}
+/** Per-CHARACTER advance box (local, pre-transform coords). `x,y` = the char's baseline start,
+ *  `width` = its advance, `ascent`/`fontSize` size its bbox. * @internal
+ */
+interface PxGlyphCharBox {
+    x: number;
+    y: number;
+    width: number;
+    ascent: number;
+    fontSize: number;
+    /** Along-path only: baseline END point (leading edge of the next char). Absent for
+     *  horizontal, where the end is `x + width` on the same baseline. */
+    endX?: number;
+    endY?: number;
+    /** Along-path only: char rotation in DEGREES (path tangent; 0 = horizontal). */
+    rotation?: number;
+}
+/** Optional along-path geometry for {@link layoutGlyphTextChars}: when given, chars are
+ *  placed + rotated along `pathD` (mirrors {@link materializeGlyphTextAlongPath}) at the
+ *  STATIC / frame-0 startOffset, so the editor caret follows the path. * @internal
+ */
+interface GlyphCharBoxAlongPath {
+    pathD?: string;
+    startOffset?: PxAnimatable<number>;
+    textLength?: PxAnimatable<number>;
+    pathOverflow?: string;
+}
+/** Per-character layout boxes for a glyph text, in reading/DOM order INCLUDING spaces
+ *  (a space has no glyph but advances the pen) AND one zero-width filler box per EMPTY
+ *  line — the editor's edit canvas renders a zero-width filler char for an empty line
+ *  (so the caret has something to measure), and DOM char indices must stay aligned.
+ *  HORIZONTAL by default — mirrors `materializeGlyphTextHorizontal`'s pen-walk exactly
+ *  (same x/y/dx/dy, spacing and text-anchor). When `opts.alongPath` is given, mirrors
+ *  `materializeGlyphTextAlongPath` (each char placed + rotated to the path tangent). So
+ *  an editor caret built from these lands on the rendered glyphs. Empty for a text with
+ *  no glyph font / unparsable path. * @internal
+ */
+declare function layoutGlyphTextChars(node: PxNode, opts: Pick<GlyphMaterializeOptions, 'glyphs' | 'warnings'> & {
+    alongPath?: GlyphCharBoxAlongPath;
+}): Array<PxGlyphCharBox>;
+/** @internal */
+declare function materializeGlyphTextAlongPath<E = any>(node: PxNode, pathD: string | undefined, startOffset: PxAnimatable<number> | undefined, opts: GlyphMaterializeOptions<E>, textLength?: PxAnimatable<number>, pathOverflow?: string): E | null;
+/** Single entry the EDITOR calls: materializes a glyph `<text>` node into the
+ *  factory's element type, choosing along-path when `alongPath` is given. * @internal
+ */
+declare function materializeGlyphText<E = any>(node: PxNode, opts: GlyphMaterializeOptions<E> & {
+    alongPath?: {
+        pathD?: string;
+        startOffset?: PxAnimatable<number>;
+        textLength?: PxAnimatable<number>;
+        pathOverflow?: string;
+    };
+}): E | null;
+
+/** Inputs for {@link extendedPathForBrowser}. `advance` = the text run-width used to
+ *  size the end extension (caller-measured; the player estimates it from the node,
+ *  the editor from its text model — browser fonts have no glyph metrics available). * @internal
+ */
+interface ExtendPathOptions {
+    pathOverflow?: string;
+    startOffset?: PxAnimatable<number>;
+    textLength?: PxAnimatable<number>;
+    advance?: number;
+}
+/** Result of {@link extendedPathForBrowser}: the (possibly) extended `d`, plus
+ *  `startShift` — the length of the prepended START lead-in. Because that lead-in
+ *  moves the `<textPath>` origin back by `startShift`, EVERY `startOffset` (all
+ *  keyframes) MUST be shifted by `+startShift` so the text lands where it would on
+ *  the un-extended path (`extend` only adds a tail, it must never move the text). * @internal
+ */
+interface ExtendedPath {
+    d: string;
+    startShift: number;
+}
+/** For `pathOverflow:'extend'` (browser-font): extend an OPEN path along its endpoint
+ *  tangents so the browser lays overflow glyphs onto the straight extension (matching
+ *  glyph-mode's tangent behavior) instead of dropping them. `'clip'`/closed paths are
+ *  returned unchanged (browser clips natively). Shared by the player's browser-font
+ *  applier and the editor's live/heavy `<textPath>` def generate (single source of truth).
+ *  Returns the extended `d` AND `startShift` — see {@link ExtendedPath}. * @internal
+ */
+declare function extendedPathForBrowser(pathD: string, opts: ExtendPathOptions): ExtendedPath;
+
+/** Is this document scroll-driven? (`animator.timelineSource === 'scroll'`) @internal */
+declare function isScrollTimeline(config: PxAnimatorConfig | undefined): boolean;
+/**
+ * The seek-space length (ms) a scroll progress of 1 maps to: duration × finite
+ * iterations. `'infinite'` is meaningless on a finite progress timeline (see design doc
+ * D4) — treated as 1 with the read-side warning left to the consumer.
+ * @internal
+ */
+declare function scrollTotalDurationMs(config: PxAnimatorConfig | undefined): number;
+/**
+ * A named phase's interval in `u`-space.
+ *
+ * `u` is the subject's "journey distance": with `sTop` = subject's leading edge in
+ * scrollport coordinates, `u = vpSize − sTop` — 0 exactly when the subject is about to
+ * enter (leading edge at the scrollport's trailing edge), growing as the user scrolls.
+ * The `min`/`max` pairs make every formula valid BOTH for a subject smaller than the
+ * scrollport and one larger than it (where "fully visible" flips to "covers the
+ * scrollport") — the same case split CSS specifies for its named timeline ranges.
+ * @internal
+ */
+declare function scrollPhaseInterval(phase: PxScrollPhase, subjectSize: number, scrollportSize: number): [number, number];
+/**
+ * `kind: 'view'` progress ∈ [0, 1]: where the subject's journey sits within the
+ * configured range.
+ *
+ * @param subjectStart   subject's leading edge in scrollport coordinates
+ *                       (`subjectRect.top − scrollportRect.top` on the resolved axis)
+ * @param subjectSize    subject size on the axis
+ * @param scrollportSize scrollport size on the axis
+ *
+ * A degenerate/inverted range (uStart ≥ uEnd — e.g. zero-size subject with an `entry`
+ * range) reports 1 once the point is passed, 0 before — never NaN.
+ * @internal
+ */
+declare function scrollViewProgress(subjectStart: number, subjectSize: number, scrollportSize: number, range: PxScroll['range'] | undefined): number;
+/**
+ * `kind: 'scroll'` progress ∈ [0, 1]: the scroller's offset ratio mapped through the
+ * range (phases don't exist here — `fraction` is of the total scroll range).
+ *
+ * `maxOffset === 0` (nothing to scroll) reports 1, matching the CSS spec's rule that a
+ * zero-length timeline is at 100%.
+ * @internal
+ */
+declare function scrollOffsetProgress(offset: number, maxOffset: number, range: PxScroll['range'] | undefined): number;
+/**
+ * Resolve a logical axis to a physical one. `block`/`inline` are writing-mode relative:
+ * in horizontal writing (`horizontal-tb`, the default) block flows vertically; in
+ * vertical writing modes it flows horizontally.
+ * @internal
+ */
+declare function scrollResolveAxis(axis: PxScroll['axis'] | undefined, writingMode: string | undefined): 'x' | 'y';
+
+/**
+ * Converts a PxBezierPath to an SVG path string.
+ * Control points (i, o) are treated as ABSOLUTE coordinates.
+ * @param {PxBezierPath} path
+ * @returns {string}
+ */
+/**
+ * @param forceCurves Emit EVERY segment (incl. the closing one) as a cubic `C`, even when
+ *   its control points are degenerate (a straight line). Needed for keyframe values the
+ *   BROWSER interpolates (WAAPI / CSS `path()`): CSS only interpolates paths with
+ *   IDENTICAL command sequences, so an opportunistic `L` in one keyframe vs a `C` in the
+ *   next (e.g. a round-corner radius animating from 0) turns the whole animation
+ *   DISCRETE — it flips at 50% instead of morphing.
+ * @internal
+ */
+declare function bezierToSvgPath(path: PxBezierPath, forceCurves?: boolean): string;
+/**
+ * Creates a cubic-bezier easing function.
+ * @param easing An array of four numbers [x1, y1, x2, y2] defining the bezier curve.
+ * @returns A function that takes a progress value (0-1) and returns an eased value.
+ * @internal
+ */
+declare function cubicBezier(easing: [number, number, number, number]): (x: number) => number;
+type Point2 = [number, number];
+/**
+ * Splits a cubic bezier curve at parameter t using De Casteljau's algorithm.
+ * Returns the left and right sub-curves as 4-point tuples.
+ * @internal
+ */
+declare function subdivideCubicBezier(p0: Point2, p1: Point2, p2: Point2, p3: Point2, t: number): {
+    left: [Point2, Point2, Point2, Point2];
+    right: [Point2, Point2, Point2, Point2];
+};
+type Easing = [number, number, number, number];
+/**
+ * Splits a CSS cubic-bezier easing [x1,y1,x2,y2] at a given x-axis fraction.
+ * Each half is re-normalized to map [0,0]→[1,1].
+ * Returns undefined for either half if the input is undefined (linear) or the split is degenerate.
+ * @internal
+ */
+declare function splitEasing(easing: Easing | undefined, xFraction: number): {
+    left: Easing | undefined;
+    right: Easing | undefined;
+};
+/**
+ * Reverses a cubic-bezier easing for backward playback.
+ * [x1,y1,x2,y2] → [1-x2, 1-y2, 1-x1, 1-y1].
+ * @internal
+ */
+declare function reverseEasing(easing: Easing | undefined): Easing | undefined;
+/**
+ * Converts a color from a [r, g, b, a] array (where values are 0-1) to an rgba() or rgb() CSS string.
+ * @param color The color array.
+ * @internal
+ */
+declare function toRGBA(color: Array<number>): string;
+/** @internal */
+declare const PX_COLOR_ATTR_NAMES: Set<string>;
+/** @internal */
+declare const PX_TRANSFORM_FN_NAMES: Set<string>;
+/** @internal */
+declare const PX_PCT_BASED_ATTR_NAMES: Set<string>;
+/**
+ * Compose a `PxTransformParts` record into a single SVG/CSS transform string in
+ * the canonical order:
+ *
+ *   translate, translate(+origin), rotate, scale, translate(-origin)
+ *
+ * Each part is omitted when not present. `origin` becomes a `translate(+o)` /
+ * `translate(-o)` pair surrounding the rotate/scale segment — the SVG-native
+ * way to render a transform-origin pivot.
+ *
+ * @param parts the parts record (translate / rotate / scale / origin)
+ * @param opts.withUnits  when true (default), translates use `px` and rotate
+ *   uses `deg` — required for CSS / WebAnimations keyframes. When false, no
+ *   units are emitted — required for the SVG `transform` attribute.
+ * @internal
+ */
+declare function composeTransformParts(parts: PxTransformParts | null | undefined, opts?: {
+    withUnits?: boolean;
+}): string;
+/** @internal */
+declare const PX_STYLE_ATTR_NAMES: Set<string>;
+/** @internal */
+declare const PX_DEFAULT_DURATION_MS = 1000;
+/**
+ * Converts a kebab-case string to camelCase.
+ * @param kebab The kebab-case string.
+ * @internal
+ */
+declare function kebabToCamelCaseWord(kebab: string): string;
+/**
+ * Converts a camelCase string to kebab-case.
+ * @param camel The camelCase string.
+ * @internal
+ */
+declare function camelCaseToKebabWordIfNeeded(camel: string): string;
+/**
+ * Clamps a number between a minimum and maximum value.
+ * @param value The number to clamp.
+ * @param min The minimum value.
+ * @param max The maximum value.
+ * @internal
+ */
+declare function clamp(value: number, min: number, max: number): number;
+
+/** Every field identity `root` can carry, as canonical paths, sorted. @internal */
+declare function schemaFieldUniverse(root: PxSchema<any, any>): Array<string>;
+
+/** One entry of the release log — what shipped, when, and what it changed. @internal */
+interface SchemaReleaseRecord {
+    readonly version: string;
+    /** ISO date, `YYYY-MM-DD`. */
+    readonly date: string;
+    /** The first release: nothing to compare it against. */
+    readonly baseline?: boolean;
+    readonly added: ReadonlyArray<string>;
+    readonly removed: ReadonlyArray<string>;
+    readonly note?: string;
+}
+/** Keys that appeared and keys that left between two inventories, each sorted. @internal */
+declare function diffFieldUniverse(previous: ReadonlyArray<string>, current: ReadonlyArray<string>): {
+    added: Array<string>;
+    removed: Array<string>;
+};
+/** What a release must do about the version. `refuse` set means: do not release as-is. @internal */
+interface SchemaReleasePlan {
+    /** Did any key appear or leave since the last release? */
+    readonly changed: boolean;
+    /** Which kind of step the change requires — a removal is never additive. */
+    readonly requiredKind?: PxWireStepKind;
+    /** The version this release must carry. */
+    readonly requiredVersion?: string;
+    readonly refuse?: string;
+}
+/**
+ * THE BUMP RULE. A key change requires `b + 1` and a step that explains it; no key change
+ * requires nothing. The rule never picks the number by taste — the inventory diff does.
+ * @internal
+ */
+declare function planSchemaRelease(p: {
+    readonly added: ReadonlyArray<string>;
+    readonly removed: ReadonlyArray<string>;
+    /** `PX_WIRE_SCHEMA_VERSION` — what the source says now. */
+    readonly declared: string;
+    /** The version of the last release record. */
+    readonly lastReleased: string;
+    readonly steps: ReadonlyArray<PxWireVersionStep>;
+}): SchemaReleasePlan;
+/**
+ * Everything wrong with the release log, as sentences — empty when it is consistent. The log
+ * must start at the baseline, move strictly forward, END at the version the source declares,
+ * and every release after the baseline must have the step that explains it.
+ * @internal
+ */
+declare function releaseLogProblems(releases: ReadonlyArray<SchemaReleaseRecord>, steps: ReadonlyArray<PxWireVersionStep>, declared: string, baseline: string): Array<string>;
+
+export { PX_COLOR_ATTR_NAMES, PX_DEFAULT_DURATION_MS, PX_PCT_BASED_ATTR_NAMES, PX_STYLE_ATTR_NAMES, PX_TRANSFORM_FN_NAMES, PxAnimatable, type PxCreateElement, type PxGlyphCharBox, bezierToSvgPath, camelCaseToKebabWordIfNeeded, clamp, composeTransformParts, createPathSampler, cubicBezier, diffFieldUniverse, diffInEffect, extendedPathForBrowser, isScrollTimeline, kebabToCamelCaseWord, layoutGlyphTextChars, materializeGlyphText, materializeGlyphTextAlongPath, planSchemaRelease, releaseLogProblems, reverseEasing, schemaFieldUniverse, scrollOffsetProgress, scrollPhaseInterval, scrollResolveAxis, scrollTotalDurationMs, scrollViewProgress, splitEasing, subdivideCubicBezier, toRGBA };