@pixodesk/svg-animator-core 1.0.40 → 1.0.43

package/dist/{internal-BZSJtt_h.d.ts → PxDocumentDiagnostic-DkBZYJ7X.d.cts}

@@ -79,12 +79,12 @@ type PxInfer<S> = S extends PxSchema<infer T, any> ? T : never;
  * Useful for strict property-access checking on types that have an open `[key: string]: any`.
  *
  * @example
- * type Strict = RemoveIndex<PxAnimatedSvgDocument>;
+ * type Strict = PxRemoveIndex<PxAnimatedSvgDocument>;
  * Strict['animator']   // PxAnimatorConfig | undefined  ✓
  * Strict['anything']   // compile error  ✓
  * @public @advanced
  */
-type RemoveIndex<T> = {
+type PxRemoveIndex<T> = {
     [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
 };
 type UnionMembers<T extends ReadonlyArray<PxSchema<any, any>>> = {
@@ -208,7 +208,7 @@ declare const px: {
      * The base can be the result of px.object() or px.openObject() — anything with a _shape property.
      *
      * @example
-     * const PxSvgNodeSchema = px.extendedObject(PxNodeBase, { width: px.number().optional() });
+     * const PxSvgNodeSchema = px.extendedObject(PxNodeBaseSchema, { width: px.number().optional() });
      */
     readonly extendedObject: <B extends AnyShape, E extends AnyShape>(base: {
         readonly _shape: B;
@@ -230,9 +230,9 @@ declare const px: {
 };
 
 /** The wire key, under the animator config block. @public @advanced */
-declare const WIRE_VERSION_KEY = "version";
+declare const PX_WIRE_VERSION_KEY = "version";
 /** Parsed form. Compare these, NEVER the strings: `"1.10" < "1.9"` lexically. @public @advanced */
-interface WireVersion {
+interface PxWireVersion {
     /** Generation. A change no conversion can bridge. */
     readonly a: number;
     /** Player schema revision within the generation. */
@@ -241,7 +241,7 @@ interface WireVersion {
     readonly c: number;
 }
 /** How a file's version relates to a reader's. @public @advanced */
-declare enum WireVersionRelation {
+declare enum PxWireVersionRelation {
     /** No stamp — unknown provenance. Assume nothing, migrate nothing. */
     unstamped = "unstamped",
     same = "same",
@@ -255,19 +255,19 @@ declare enum WireVersionRelation {
 /** `"1.2.3"` → `{a:1,b:2,c:3}`; a missing `c` is baseline 0. `undefined` when unparseable —
  *  treated exactly like an absent stamp, never as an error. * @public @advanced
  */
-declare function parseWireVersion(raw: unknown): WireVersion | undefined;
+declare function parseWireVersion(raw: unknown): PxWireVersion | undefined;
 /** @public @advanced */
-declare function formatWireVersion(v: WireVersion): string;
+declare function formatWireVersion(v: PxWireVersion): string;
 /** The version this PLAYER implements, parsed. `c` is 0: the player has no editor extension. @public @advanced */
-declare const PLAYER_WIRE_VERSION: WireVersion;
+declare const PX_WIRE_VERSION: PxWireVersion;
 /** The version stamped on a document, or `undefined` when it carries none. @public @advanced */
-declare function readWireVersion(doc: unknown): WireVersion | undefined;
+declare function readWireVersion(doc: unknown): PxWireVersion | undefined;
 /**
  * How `file` relates to `mine`. `readerReadsEditorPart` separates the two readers: the EDITOR
  * compares all three parts, the PLAYER compares only `a.b` and is blind to `c`.
  * @public @advanced
  */
-declare function compareWireVersion(file: WireVersion | undefined, mine: WireVersion, readerReadsEditorPart: boolean): WireVersionRelation;
+declare function compareWireVersion(file: PxWireVersion | undefined, mine: PxWireVersion, readerReadsEditorPart: boolean): PxWireVersionRelation;
 /**
  * What to TELL the user about a version gap — and only ever alongside unknown content actually
  * met. `undefined` means the version explains nothing, so nothing is said.
@@ -277,9 +277,9 @@ declare function compareWireVersion(file: WireVersion | undefined, mine: WireVer
  * so the worst case is a document missing a feature plus a sentence saying how to close the gap.
  * @public @advanced
  */
-declare function versionAdvice(relation: WireVersionRelation, file: WireVersion | undefined, mine: WireVersion, isPlayer: boolean): string | undefined;
+declare function wireVersionAdvice(relation: PxWireVersionRelation, file: PxWireVersion | undefined, mine: PxWireVersion, isPlayer: boolean): string | undefined;
 /** What a step DOES to documents — and therefore whether it needs conversion code. @public @advanced */
-declare enum WireStepKind {
+declare enum PxWireStepKind {
     /**
      * Only OPTIONAL fields were added. An older reader ignores them; a newer reader finds them
      * absent and defaults. Nothing to convert either way — but it must still be DECLARED, so
@@ -290,16 +290,16 @@ declare enum WireStepKind {
     converted = "converted"
 }
 /** One `b` step of the player schema. @public @advanced */
-interface WireVersionStep {
+interface PxWireVersionStep {
     /** The version this step converts FROM, e.g. `'1.1'`. */
     readonly from: string;
     /** …and TO. Must be the `from` of the next step, so the table is one unbroken chain. */
     readonly to: string;
     /** Why the format moved — the sentence a future reader needs, not a commit hash. */
     readonly reason: string;
-    readonly kind: WireStepKind;
+    readonly kind: PxWireStepKind;
     /**
-     * Older → newer, MUTATING the document in place. Required for {@link WireStepKind.converted}.
+     * Older → newer, MUTATING the document in place. Required for {@link PxWireStepKind.converted}.
      * It may not touch `meta.*`: that subtree is the editor's, and its steps are the `c` part.
      */
     readonly up?: (doc: Record<string, unknown>) => void;
@@ -307,19 +307,19 @@ interface WireVersionStep {
     readonly down?: (doc: Record<string, unknown>) => void;
 }
 /** Where the chain starts: the first RELEASED player schema. Everything older is pre-release. @public @advanced */
-declare const BASELINE_PLAYER_VERSION = "1.1";
+declare const PX_WIRE_BASELINE_VERSION = "1.1";
 /**
- * Every `b` step from {@link BASELINE_PLAYER_VERSION} to {@link PX_PLAYER_SCHEMA_VERSION}.
+ * Every `b` step from {@link PX_WIRE_BASELINE_VERSION} to {@link PX_WIRE_SCHEMA_VERSION}.
  *
  * EMPTY IS CORRECT TODAY: 1.1 is the baseline and nothing has moved since. It exists now because
- * the guard spec keys off it — bump `PX_PLAYER_SCHEMA_VERSION` without adding the matching step
+ * the guard spec keys off it — bump `PX_WIRE_SCHEMA_VERSION` without adding the matching step
  * and the suite fails naming the gap. That is the whole point: the last three renames shipped
  * because nothing forced anyone to say they had happened.
  * @public @advanced
  */
-declare const PLAYER_WIRE_STEPS: ReadonlyArray<WireVersionStep>;
+declare const PX_WIRE_STEPS: ReadonlyArray<PxWireVersionStep>;
 /** What a conversion pass did, so a caller can report it. @public @advanced */
-interface PlayerConversionResult {
+interface PxWireConversionResult {
     /**
      * The document to read. A converted COPY when steps applied, otherwise the input itself,
      * unchanged and identical by reference — the caller's object is never mutated, so a failed
@@ -327,26 +327,26 @@ interface PlayerConversionResult {
      */
     readonly doc: unknown;
     /** The version found on the file, if any. */
-    readonly from: WireVersion | undefined;
-    readonly relation: WireVersionRelation;
+    readonly from: PxWireVersion | undefined;
+    readonly relation: PxWireVersionRelation;
     /** The steps actually applied, oldest first. Empty when nothing was needed. */
-    readonly applied: ReadonlyArray<WireVersionStep>;
+    readonly applied: ReadonlyArray<PxWireVersionStep>;
     /** Set only when the version could not be honored — never a refusal to render. */
     readonly advice?: string;
 }
 /** Which table to run, and what to bring the document up TO. @public @advanced */
-interface WireConversionConfig {
+interface PxWireConversionOptions {
     /** The step table — the player's, or the editor's `meta.*` one. */
-    readonly steps: ReadonlyArray<WireVersionStep>;
+    readonly steps: ReadonlyArray<PxWireVersionStep>;
     /** The version the document should end up at. */
-    readonly target: WireVersion;
+    readonly target: PxWireVersion;
     /** `true` for the EDITOR (compares and stamps `c`), `false` for the PLAYER (blind to it). */
     readonly readerReadsEditorPart: boolean;
 }
 /**
  * THE STEP ENGINE — one implementation, two tables.
  *
- * The player runs it over `PLAYER_WIRE_STEPS`; the editor runs it a second time over its own
+ * The player runs it over `PX_WIRE_STEPS`; the editor runs it a second time over its own
  * `meta.*` table, on the document the player pass returned. Keeping it one function is what
  * stops the two halves from drifting into two different ideas of what conversion means.
  *
@@ -359,30 +359,30 @@ interface WireConversionConfig {
  *                  converted one.
  * @public @advanced
  */
-declare function applyWireSteps(doc: unknown, cfg: WireConversionConfig): PlayerConversionResult;
+declare function applyWireSteps(doc: unknown, cfg: PxWireConversionOptions): PxWireConversionResult;
 /**
  * BRING A DOCUMENT UP TO THIS PLAYER'S SCHEMA — the `playerFixer` half of the pair.
- * Runs {@link applyWireSteps} over {@link PLAYER_WIRE_STEPS}, touching nothing under `meta.*`.
+ * Runs {@link applyWireSteps} over {@link PX_WIRE_STEPS}, touching nothing under `meta.*`.
  * @public @advanced
  */
-declare function convertPlayerDocument(doc: unknown): PlayerConversionResult;
+declare function convertWireDocument(doc: unknown): PxWireConversionResult;
 /**
  * What an EXPLICIT down-conversion did. Unlike reading, this may refuse — it is an output the
  * user asked for ("save for an older player"), and handing back a file that silently lacks what
  * the older schema cannot say would be worse than saying no.
  * @public @advanced
  */
-type WireDowngradeResult = {
+type PxWireDowngradeResult = {
     readonly ok: true;
     readonly doc: unknown;
-    readonly applied: ReadonlyArray<WireVersionStep>;
+    readonly applied: ReadonlyArray<PxWireVersionStep>;
 } | {
     readonly ok: false;
     readonly reason: string;
-    readonly blocking: ReadonlyArray<WireVersionStep>;
+    readonly blocking: ReadonlyArray<PxWireVersionStep>;
 };
 /** Down-convert through the PLAYER table only — `meta.*` is untouched, as on the way up. @public @advanced */
-declare function downgradePlayerDocument(doc: unknown, target: WireVersion): WireDowngradeResult;
+declare function downgradeWireDocument(doc: unknown, target: PxWireVersion): PxWireDowngradeResult;
 
 /** WAAPI `fill` — which values apply outside the active period. @public */
 declare const PxFillMode: {
@@ -479,7 +479,7 @@ type PxAlongPathMode = typeof PxAlongPathMode[keyof typeof PxAlongPathMode];
  * platform's animation API (`native`), or write it from the player's own frame loop (`js`).
  *
  * This is the CORE set. Code that always knows which engine is running takes this (e.g.
- * `getNormalizedBindings`'s `engine` arg gates motion-along-path materialization).
+ * `normalizeBindings`'s `engine` arg gates motion-along-path materialization).
  * @public
  */
 declare const PxTimelineEngine: {
@@ -496,25 +496,25 @@ type PxTimelineEngine = typeof PxTimelineEngine[keyof typeof PxTimelineEngine];
  * drift: every engine is automatically an accepted value, and `auto` is visibly the one extra.
  * @public
  */
-declare const PxTimelineEngineExtra: {
+declare const PxTimelineEngineSetting: {
     readonly auto: "auto";
     readonly native: "native";
     readonly js: "js";
 };
-type PxTimelineEngineExtra = typeof PxTimelineEngineExtra[keyof typeof PxTimelineEngineExtra];
+type PxTimelineEngineSetting = typeof PxTimelineEngineSetting[keyof typeof PxTimelineEngineSetting];
 /** What a requested engine resolves to BEFORE the runtime probes support: `js` pins the frame
  *  loop, anything else starts at `native`. NOTE this is only the STARTING point — `auto` still
  *  falls back to `js` per document when the platform API declines an attribute, which happens at
  *  bind time (see `PxAnimatorBind`), not here. * @public @advanced
  */
-declare function resolveTimelineEngine(engine: PxTimelineEngineExtra | undefined): PxTimelineEngine;
+declare function resolveTimelineEngine(engine: PxTimelineEngineSetting | undefined): PxTimelineEngine;
 /** `native` is a demand, not a preference: no JS fallback when the platform API declines an attribute. @public @advanced */
-declare function isNativeForced(engine: PxTimelineEngineExtra | undefined): boolean;
+declare function isNativeForced(engine: PxTimelineEngineSetting | undefined): boolean;
 /** May the browser's ScrollTimeline/ViewTimeline drive a scroll/view timeline?
  *  `auto` tries it first (falling back to the player's own measurement), `native`
  *  asks for it, `js` never uses it. * @public @advanced
  */
-declare function mayUseNativeScrollTimeline(engine: PxTimelineEngineExtra | undefined): boolean;
+declare function mayUseNativeScrollTimeline(engine: PxTimelineEngineSetting | undefined): boolean;
 /**
  * THE TRIGGER DEFAULTS — what a missing `trigger` field means. One table, declared by
  * `PxTriggerSchema` and applied by {@link resolveTrigger}, which every player calls (the web's
@@ -695,7 +695,7 @@ declare const PxStrokeTrimSubPaths: {
 };
 type PxStrokeTrimSubPaths = typeof PxStrokeTrimSubPaths[keyof typeof PxStrokeTrimSubPaths];
 /** @internal */
-declare const TEXT_CONTENT_ATTR = "textContent";
+declare const PX_TEXT_CONTENT_ATTR = "textContent";
 /** @public */
 declare const PX_TRANSFORM_PART_KEYS: readonly ["translate", "rotate", "scale", "origin"];
 /** Loose enums for `spreadMethod` / gradient `type` — kept on the wire as
@@ -718,7 +718,7 @@ declare const PxGradientType: {
 };
 type PxGradientType = typeof PxGradientType[keyof typeof PxGradientType];
 /** @public @advanced */
-declare function isPxElementFileFormat(fileJson: any): fileJson is PxAnimatedSvgDocument;
+declare function isPxDocument(doc: any): doc is PxAnimatedSvgDocument;
 /**
  * The animator config, at either of its TWO canonical addresses (S4).
  *
@@ -747,12 +747,136 @@ declare function flattenAnimatorTimeline(cfg: PxAnimatorConfig): PxAnimatorConfi
  */
 declare function nestAnimatorTimeline(cfg: PxAnimatorConfig): PxAnimatorConfig;
 /** @public @advanced */
-declare function getDefs(doc: PxAnimatedSvgDocument): PxDefs | undefined;
+declare function getDefinitions(doc: PxAnimatedSvgDocument): PxDefinitions | undefined;
 /** The bind-by-id document's `animator.bindings`, as written — `target` keeps its `#`. @public @advanced */
 declare function getBindings(doc: PxAnimatedSvgDocument): PxBinding[] | undefined;
 /** @public @advanced */
 declare function getChildren(doc: PxAnimatedSvgDocument): PxNode[] | undefined;
 
+/**
+ * Every diagnostic a player can report, as a number a host can switch on.
+ *
+ * The words are not in the build: each code's description lives in the comment on its member and
+ * is compiled into `docs/diagnostics.md`, which every diagnostic's `message` links to.
+ * @public
+ */
+declare enum PxDiagnosticCode {
+    /**
+     * The player could not be built from this document — a document that passed validation but
+     * still broke the builder, or a bug in the player. Report it.
+     * @data the Error
+     */
+    buildFailed = 1001,
+    /**
+     * The file at `src` loaded, but it is not a Pixodesk animation document.
+     * @data the `src` URL
+     */
+    invalidDocumentAtSrc = 1002,
+    /**
+     * The page could not fetch `src`. The file may be perfect — this is the request failing.
+     * @data the `src` URL · the fetch error's message
+     */
+    loadFailed = 1003,
+    /**
+     * One element's animation could not be built, so that element stays static; the rest plays.
+     * @data the Error
+     */
+    animationBuildFailed = 1004,
+    /**
+     * An `effects` bucket does not match the schema, so that effect is ignored or degraded.
+     * @data the problem, with the node's path
+     */
+    effectsShape = 1101,
+    /**
+     * Part of the per-instance `timeline` override could not be applied — most often clock-only
+     * keys aimed at a scroll timeline.
+     * @data what could not be applied
+     */
+    timelineOverrideIgnored = 1102,
+    /**
+     * An SVG tag that can execute or load remote content was dropped from the rendered tree.
+     * @data the tag name
+     */
+    blockedTag = 1103,
+    /**
+     * The browser will not animate these attributes, so the document fell back to the frame loop.
+     * @data the attribute names
+     */
+    unsupportedAnimatedAttrs = 1104,
+    /** A bind-by-id document carries no `animator.bindings`, so nothing is animated. */
+    noBindings = 1105,
+    /**
+     * A binding names no element, or names animations that `definitions.animations` does not have.
+     * @data the binding
+     */
+    unresolvedBinding = 1106,
+    /** `setupAnimationTriggers` was given no root element, so no trigger was wired. */
+    triggersNoRoot = 1201,
+    /**
+     * The container selector matched nothing, so there is nothing to render into.
+     * @data the selector
+     */
+    noRootForSelector = 1202,
+    /** No container was given and the document's `id` matched no element already on the page. */
+    noRootElement = 1203,
+    /**
+     * A binding's selector matched no element, so that binding animates nothing.
+     * @data the selector
+     */
+    noElementsForSelector = 1206,
+    /**
+     * An attribute write found no element for this id — the rendered SVG was probably replaced.
+     * @data the id or selector
+     */
+    setAttributeNoElement = 1207,
+    /** `smoothing` needs the player's own driver, so the browser's scroll timeline was not used. */
+    scrollSmoothingNeedsOwnDriver = 1301,
+    /** The browser refused to build a native scroll timeline; the player measures progress itself. */
+    scrollNativeUnavailable = 1302,
+    /**
+     * `scroll.subject` is not a valid CSS selector, so the SVG itself is measured instead.
+     * @data the subject
+     */
+    scrollSubjectInvalid = 1303,
+    /**
+     * `scroll.subject` matched no element, so the SVG itself is measured instead.
+     * @data the subject
+     */
+    scrollSubjectNoMatch = 1304,
+    /** There is no root element to observe, so a scroll-driven animation stays on its first frame. */
+    scrollNoRootToObserve = 1305,
+    /** `animator.trigger` does not apply to a scroll timeline — the scrollbar is the playhead. */
+    scrollTriggerIgnored = 1306,
+    /** A playback rate of `0`, or a non-finite one, is rejected everywhere — use `pause()`. */
+    rateRejected = 1401,
+    /**
+     * Two control tiers were set at once. The higher one wins and the lower is ignored — see the
+     * control-mode rule.
+     * @data which props conflicted, and which won
+     */
+    controlPropsConflict = 1501,
+    /**
+     * The document could not be compiled into animation tracks, so `fallback` is shown.
+     * @data the Error
+     */
+    rnCompileFailed = 1601,
+    /**
+     * Rendering the compiled document threw, so `fallback` is shown.
+     * @data the Error
+     */
+    rnRenderFailed = 1602,
+    /**
+     * The error boundary caught a render failure below this component.
+     * @data the Error · the React component stack
+     */
+    rnBoundaryCaught = 1603,
+    /**
+     * `react-native-svg` cannot express part of this document, so it was left out or simplified.
+     * @data what was left out
+     */
+    rnUnsupported = 1604
+}
+
 /**
  * Who can do something about a diagnostic.
  *
@@ -773,24 +897,35 @@ declare const PxDiagnosticKind: {
     readonly internal: "internal";
 };
 type PxDiagnosticKind = typeof PxDiagnosticKind[keyof typeof PxDiagnosticKind];
-/** One thing a player has to say. @public */
+/**
+ * One thing a player has to say.
+ *
+ * The TEXT is not here, and is not in the bundle: `code` identifies the diagnostic and
+ * {@link https://github.com/pixodesk/pixodesk-svg-animator/blob/main/docs/diagnostics.md the
+ * codes page} carries the description. That is the trade this library makes — a smaller
+ * download, and a stable number you can switch on instead of matching a sentence that may be
+ * reworded. The specifics are in `data`.
+ * @public
+ */
 interface PxDiagnostic {
+    /** WHICH diagnostic this is — a permanent number; look it up on the codes page. */
+    readonly code: PxDiagnosticCode;
     /** Who can act on it — see {@link PxDiagnosticKind}. */
     readonly kind: PxDiagnosticKind;
-    /** Human-readable, and never carries the console prefix. */
-    readonly message: string;
     /**
-     * Whatever the site had to hand: the offending binding, the element map, the raw error —
-     * or, for a React Native render failure, `{ componentStack }`.
+     * What the site had to hand, in the order the code's `@data` lists: a selector, a URL, the
+     * offending binding, an inner problem. Everything a sentence would have interpolated.
      */
-    readonly detail?: unknown;
-    /** Present on errors: the Error that stopped the player. Its message is `message`. */
+    readonly data?: ReadonlyArray<unknown>;
+    /** The code and a link to its description — NOT the description itself, which is not shipped. */
+    readonly message: string;
+    /** Present on errors: the Error that stopped the player. */
     readonly error?: Error;
 }
 /**
  * Where a player sends what it wants to say. Every field is optional.
  *
- * The SHARED base of every callbacks object (API-SURFACE-REVIEW.md §26.1): `createDiagnostics` reads it directly,
+ * The SHARED base of every callbacks object (dev-docs/reviews/api-surface-review.md §26.1): `createDiagnostics` reads it directly,
  * `PxEngineCallbacks` extends it with the playback lifecycle, `PxAnimatorCallbacks` adds `onStop`
  * on top — so the four diagnostics fields are spelled once, here.
  * @public
@@ -799,15 +934,16 @@ interface PxDiagnosticsConfig {
     /**
      * IT PLAYS, but something was ignored, degraded or misspelled — an unknown easing, an
      * override that could not apply, an attribute the platform will not animate. Each
-     * diagnostic says WHO can act on it via `kind` (`document` / `host` / `platform` / `usage` /
-     * `internal`). Without this: `console.warn`.
+     * diagnostic says WHAT happened via `code` (a number — look it up on the codes page) and
+     * WHO can act on it via `kind` (`document` / `host` / `platform` / `usage` / `internal`);
+     * `data` carries the values the site had. Without this: `console.warn`.
      */
     onWarn?: (diagnostic: PxDiagnostic) => void;
     /**
      * THIS INSTANCE WILL NOT PLAY — the document failed to load, parse or build, or the render
      * threw: nothing rendered, `isReady()` false, the component's `fallback` shown. The player
      * stays inert rather than throwing at the caller. `diagnostic.error` is the Error; on React
-     * Native `diagnostic.detail` carries `{ componentStack }` when the error boundary caught it.
+     * Native `diagnostic.data` carries the component stack when the error boundary caught it.
      * Without this: `console.error`.
      */
     onError?: (diagnostic: PxDiagnostic) => void;
@@ -823,10 +959,13 @@ interface PxDiagnosticsConfig {
 }
 /** The reporting channel a player writes to. @public */
 interface PxDiagnostics {
-    /** Report something survivable — it plays. */
-    warn(kind: PxDiagnosticKind, message: string, detail?: unknown): void;
-    /** Report a failure that stopped this instance — it will not play. */
-    error(kind: PxDiagnosticKind, error: Error | string, detail?: unknown): void;
+    /** Report something survivable — it plays. `data` is whatever the code's `@data` names. */
+    warn(kind: PxDiagnosticKind, code: PxDiagnosticCode, ...data: Array<unknown>): void;
+    /**
+     * Report a failure that stopped this instance — it will not play. An `Error` anywhere in
+     * `data` becomes the diagnostic's `error`, so a site can pass it wherever it reads best.
+     */
+    error(kind: PxDiagnosticKind, code: PxDiagnosticCode, ...data: Array<unknown>): void;
 }
 /**
  * Builds the channel a player reports through.
@@ -968,14 +1107,14 @@ type PxNormalizedKeyframe = _PxNormalizedKeyframe;
  */
 type PxAnyKeyframe = _PxKeyframe | _PxNormalizedKeyframe;
 /** Value, whichever spelling. @internal */
-declare const kfValue: (kf: PxAnyKeyframe) => any;
+declare const keyframeValue: (kf: PxAnyKeyframe) => any;
 /** Easing — resolved on a normalized keyframe, possibly a NAME on a wire one. @internal */
-declare const kfEasing: (kf: PxAnyKeyframe) => PxEasingOrRef | undefined;
+declare const keyframeEasing: (kf: PxAnyKeyframe) => PxEasingOrRef | undefined;
 /**
  * A single animation keyframe defining the state at a specific point in time.
  *
  * Generic over the keyframe `value` type for callers that know the per-property
- * value shape (e.g. `PxKeyframe<Vec2>` in the effect appliers). Defaults to
+ * value shape (e.g. `PxKeyframe<PxVec2>` in the effect appliers). Defaults to
  * `any`, matching the schema (`value` is stored as `px.any()` on the wire).
  * @public
  */
@@ -1380,7 +1519,7 @@ declare const PxGlyphFontSchema: PxSchema<{
 /** @public */
 type PxGlyphFont = PxInfer<typeof PxGlyphFontSchema>;
 /** @public @advanced */
-declare const PxDefsSchema: PxSchema<{} & {
+declare const PxDefinitionsSchema: PxSchema<{} & {
     easings?: Record<string, [number, number, number, number]> | undefined;
     animations?: Record<string, Record<string, {} & {
         value?: string | number | number[] | ({} & {
@@ -1474,7 +1613,7 @@ declare const PxDefsSchema: PxSchema<{} & {
     };
 };
 /** Reusable definitions library for easings, animations and fonts. @public */
-type PxDefs = PxInfer<typeof PxDefsSchema>;
+type PxDefinitions = PxInfer<typeof PxDefinitionsSchema>;
 /** @public @advanced */
 declare const PxScrollRangePointSchema: PxSchema<{} & {
     phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
@@ -1633,8 +1772,8 @@ type PxTimeline = PxInfer<typeof PxTimelineSchema>;
 interface _PxAnimatorConfig {
     /** RUNTIME VIEW ONLY (not wire — the wire spells it `timeline.engine`, on every
      *  timeline type; same word both sides). How the animated attributes get updated;
-     *  see {@link PxTimelineEngineExtra}. */
-    engine?: PxTimelineEngineExtra;
+     *  see {@link PxTimelineEngineSetting}. */
+    engine?: PxTimelineEngineSetting;
     /** RUNTIME VIEW ONLY (not wire — §2.8: the wire spells it `timeline.duration`).
      *  Total animation duration in milliseconds. */
     duration?: number;
@@ -1671,7 +1810,7 @@ interface _PxAnimatorConfig {
     /** Trigger configuration for when animation should start */
     trigger?: PxTrigger;
     /** Named easings, animations and embedded fonts — referenced by elements and bindings */
-    definitions?: PxDefs;
+    definitions?: PxDefinitions;
     /**
      * The bind-by-id document (a pre-rendered SVG + JS export, no `children`): the elements
      * already exist as markup, so instead of carrying them again the document lists WHICH
@@ -1732,7 +1871,7 @@ declare const PxBindingSchema: PxSchema<{
 /** @public */
 type PxBinding = PxInfer<typeof PxBindingSchema>;
 /**
- * RUNTIME VIEW ONLY (not wire) — a binding once `getNormalizedBindings` has resolved it: the
+ * RUNTIME VIEW ONLY (not wire) — a binding once `normalizeBindings` has resolved it: the
  * bare DOM id and the merged, normalized animation. A self-contained document yields the same
  * shape from every animated node, so the engines never see which kind of document they play.
  * @internal
@@ -2036,7 +2175,7 @@ declare const PxAttrValueSchema: PxSchema<string | number | number[] | ({} & {
     value: any;
 } & {}), false>;
 /** Fixed-length 2-number tuple. `[x, y]` for positions, `[sx, sy]` for scale, …. @public */
-type Vec2 = [number, number];
+type PxVec2 = [number, number];
 /**
  * Animatable wire value — the ONE grammar for every animatable slot:
  *
@@ -5717,7 +5856,7 @@ type PxEffects = PxInfer<typeof PxEffectsSchema>;
  * Pass `strict: true` to also flag undeclared keys (useful in dev / tests).
  * @public @advanced
  */
-declare function validateNodeEffects(root: PxNode, opts?: {
+declare function validateNodeEffects(root: PxNode, options?: {
     strict?: boolean;
 }): Array<string>;
 /**
@@ -5728,7 +5867,7 @@ declare function validateNodeEffects(root: PxNode, opts?: {
  * for tooling, CI and agents that want a yes/no answer before shipping a document.
  * @public
  */
-declare function validateDocument(doc: unknown, opts?: {
+declare function validateDocument(doc: unknown, options?: {
     strict?: boolean;
 }): Array<string>;
 /**
@@ -5740,7 +5879,7 @@ declare function validateDocument(doc: unknown, opts?: {
  * `{ type:string, style?:…, [key:string]: string|number|PxPropertyAnimation }`
  * @public @advanced
  */
-declare const PxNodeBase: PxSchema<{
+declare const PxNodeBaseSchema: PxSchema<{
     type: string;
 } & {
     domType?: string | undefined;
@@ -7927,7 +8066,7 @@ declare let PxNodeSchema: PxSchema<any>;
  * Named properties take precedence over the index signature when accessed.
  * @public
  */
-interface PxNode extends PxInfer<typeof PxNodeBase> {
+interface PxNode extends PxInfer<typeof PxNodeBaseSchema> {
     children?: PxNode[];
     [camelCaseDomKey: string]: any;
 }
@@ -7938,7 +8077,7 @@ interface PxNode extends PxInfer<typeof PxNodeBase> {
  * `{ width?:number, height?:number, viewBox?:string, animator?:AnimatorConfig }`
  * @public @advanced
  */
-declare const PxSvgNodeExtra: PxSchema<{} & {
+declare const PxSvgNodeRootSchema: PxSchema<{} & {
     width?: string | number | undefined;
     height?: string | number | undefined;
     viewBox?: string | undefined;
@@ -8199,7 +8338,7 @@ declare const PxSvgNodeExtra: PxSchema<{} & {
  * SVG-root fields.
  * @public
  */
-interface PxSvgNode extends PxNode, Omit<PxInfer<typeof PxSvgNodeExtra>, 'animator'> {
+interface PxSvgNode extends PxNode, Omit<PxInfer<typeof PxSvgNodeRootSchema>, 'animator'> {
     /** The RUNTIME-VIEW type, not the wire shape: in-memory documents may carry the
      *  flat playback fields (`flattenAnimatorTimeline` output, prop overrides in the
      *  RN/React wrappers), while `PxAnimatorConfigSchema` validates only the nested
@@ -10709,7 +10848,7 @@ type PxBezierPath = PxInfer<typeof PxBezierPathSchema>;
  * React Native player to its own view handle. Defaults to `unknown`.
  * @public
  */
-interface PxBasicAnimatorAPI<TRoot = unknown> {
+interface PxPlaybackApi<TRoot = unknown> {
     isReady(): boolean;
     /** Returns the root element for the animation (platform-specific type). */
     getRootElement(): TRoot | null;
@@ -10740,7 +10879,7 @@ interface PxBasicAnimatorAPI<TRoot = unknown> {
  * rather than one per engine.
  * @public
  */
-interface PxAnimatorAPI<TRoot = unknown> extends PxBasicAnimatorAPI<TRoot> {
+interface PxAnimatorApi<TRoot = unknown> extends PxPlaybackApi<TRoot> {
     /** Jumps to the end of the animation and holds the final state. */
     finish(): void;
     /**
@@ -10774,7 +10913,7 @@ interface PxAnimatorAPI<TRoot = unknown> extends PxBasicAnimatorAPI<TRoot> {
  * `setPlaybackRate` comment had already lost "negative plays backwards".
  * @public
  */
-type PxAnimatorHandle = Omit<PxAnimatorAPI, 'isReady' | 'getRootElement' | 'destroy'>;
+type PxAnimatorHandle = Omit<PxAnimatorApi, 'isReady' | 'getRootElement' | 'destroy'>;
 /** @public @advanced */
 interface PxValidationResult {
     valid: boolean;
@@ -10790,7 +10929,7 @@ interface PxValidationResult {
  * this on OPEN, where a key from a newer version is worth a warning, never a refusal.
  * @public @advanced
  */
-declare function isPxElementFileFormatDeep(fileJson: unknown): PxValidationResult;
+declare function isValidPxDocument(doc: unknown): PxValidationResult;
 
 /** @internal */
 declare function generateUniqueId(): string;
@@ -10829,12 +10968,12 @@ declare function generateNewIds(doc: PxAnimatedSvgDocument): PxAnimatedSvgDocume
  * refs on `href` / `src` / `mask` / `marker*`.
  * @internal
  */
-declare const DISALLOWED_SVG_TAGS_LOWER: Set<string>;
+declare const PX_DISALLOWED_SVG_TAGS_LOWER: Set<string>;
 /** CSS-only properties that are NOT SVG presentation attributes — the browser
  *  ignores them via `setAttribute`, so they must be applied through `element.style`.
  *  Keyed camelCase to match the normalized prop names (`element.style.mixBlendMode`). * @internal
  */
-declare const CSS_ONLY_STYLE_PROPS: Set<string>;
+declare const PX_CSS_ONLY_STYLE_PROPS: Set<string>;
 /**
  * Returns the value to pass to `setAttribute`, or `undefined` to drop the
  * attribute entirely. Dropping leaves the DOM clean — the caller skips
@@ -10855,14 +10994,14 @@ declare const CSS_ONLY_STYLE_PROPS: Set<string>;
  */
 declare function sanitizeAttributeValue(name: string, value: any): any | undefined;
 /** @public @advanced */
-declare function getNormalizedProps(props: Record<string, any>): Record<string, any>;
+declare function toDomProps(props: Record<string, any>): Record<string, any>;
 
 /**
  * Time separation between a cycle's snap-back keyframe and the previous repetition's
  * end, in ms.
  *
  * SINGLE SOURCE OF TRUTH — the editor imports this and converts to its own frame unit
- * (`TLoop.smallFrameShift = LOOP_JUMP_SHIFT_MS / FRAME_DURATION_MS`), so the two sides
+ * (`TLoop.smallFrameShift = PX_LOOP_JUMP_SHIFT_MS / FRAME_DURATION_MS`), so the two sides
  * cannot drift apart and materialize different keyframes (B7).
  *
  * 1ms, not one 10ms editor frame: a 10ms snap-back is long enough to read as a visible
@@ -10874,7 +11013,7 @@ declare function getNormalizedProps(props: Record<string, any>): Record<string,
  * editor side keeps the fractional value and must not be re-clamped to a whole frame.
  * @internal
  */
-declare const LOOP_JUMP_SHIFT_MS = 1;
+declare const PX_LOOP_JUMP_SHIFT_MS = 1;
 /**
  * Interpolates between two keyframe values based on property type.
  * Returns the raw interpolated value (not a CSS string).
@@ -10914,7 +11053,7 @@ declare function mergeStaticTransformIntoAnimDef(animDef: PxAnimationDefinition,
  * handling — see {@link PxTimelineEngine}.
  * @public @advanced
  */
-declare function getNormalizedBindings(doc: PxAnimatedSvgDocument, engine?: PxTimelineEngine): PxNormalizedBinding[];
+declare function normalizeBindings(doc: PxAnimatedSvgDocument, engine?: PxTimelineEngine): PxNormalizedBinding[];
 /**
  * Calculates interpolated attribute values for an animation definition.
  * @param animDef The animation definition (with resolved refs and normalized times)
@@ -10954,13 +11093,13 @@ declare function materializeMotionPathInPropAnim(anim: PxPropertyAnimation, opts
 /** Options accepted by {@link materializeAllInTree}. Mostly forwarded to the
  *  per-stage materializers; ordering is fixed (see module doc). * @internal
  */
-interface MaterializeAllOptions {
+interface PxMaterializeAllOptions {
     /** Knobs forwarded to `materializeMotionPathsInTree`. Only consulted for
      *  `engine === waapi` — frames-mode skips that stage entirely. */
     motionPath?: MotionPathMaterializationOptions;
 }
 /** @public @advanced */
-declare function materializeAllInTree(doc: PxAnimatedSvgDocument, engine: PxTimelineEngine, opts?: MaterializeAllOptions): PxAnimatedSvgDocument;
+declare function materializeAllInTree(doc: PxAnimatedSvgDocument, engine: PxTimelineEngine, options?: PxMaterializeAllOptions): PxAnimatedSvgDocument;
 
 /**
  * A document's schema findings. The pre-2026-09 FLAT animator spelling is NOT a category of its
@@ -10984,378 +11123,4 @@ declare function diagnoseDocument(doc: unknown): PxDocumentDiagnosis;
  */
 declare function reportDocumentDiagnostics(doc: unknown, where: string): void;
 
-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 GlyphMaterializeOpts<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 GlyphCharBox {
-    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<GlyphMaterializeOpts, 'glyphs' | 'warnings'> & {
-    alongPath?: GlyphCharBoxAlongPath;
-}): Array<GlyphCharBox>;
-/** @internal */
-declare function materializeGlyphTextAlongPath<E = any>(node: PxNode, pathD: string | undefined, startOffset: PxAnimatable<number> | undefined, opts: GlyphMaterializeOpts<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: GlyphMaterializeOpts<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 ExtendPathOpts {
-    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: ExtendPathOpts): 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 COLOR_ATTR_NAMES: Set<string>;
-/** @internal */
-declare const TRANSFORM_FN_NAMES: Set<string>;
-/** @internal */
-declare const 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 STYLE_ATTR_NAMES: Set<string>;
-/** @internal */
-declare const 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?: WireStepKind;
-    /** 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_PLAYER_SCHEMA_VERSION` — what the source says now. */
-    readonly declared: string;
-    /** The version of the last release record. */
-    readonly lastReleased: string;
-    readonly steps: ReadonlyArray<WireVersionStep>;
-}): 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<WireVersionStep>, declared: string, baseline: string): Array<string>;
-
-export { PxFillMode as $, type PxBezierPath as A, BASELINE_PLAYER_VERSION as B, COLOR_ATTR_NAMES as C, DEFAULT_DURATION_MS as D, PxBezierPathSchema as E, type PxBinding as F, type GlyphCharBox as G, PxClipPathEffectSchema as H, PxCloneEffectSchema as I, PxCloneWithout as J, PxControlMode as K, LOOP_JUMP_SHIFT_MS as L, type MaterializeAllOptions as M, type PxControlProps as N, type PxCreateElement as O, type PxAnimatedSvgDocument as P, type PxDefs as Q, PxDefsSchema as R, type PxDiagnostic as S, PxDiagnosticKind as T, type PxDiagnostics as U, type PxDiagnosticsConfig as V, type PxEffects as W, PxEffectsSchema as X, type PxElementAnimation as Y, PxElementAnimationSchema as Z, PxFillGradientEffectSchema as _, type PxEngineCallbacks as a, TEXT_CONTENT_ATTR as a$, PxFinishAction as a0, type PxGlyph as a1, type PxGlyphFont as a2, PxGradientSpreadMethod as a3, PxGradientStopSchema as a4, PxGradientType as a5, type PxInfer as a6, type PxKeyframe as a7, PxKeyframeSchema as a8, PxKeyframeValueSchema as a9, PxScrollRangePointSchema as aA, PxScrollRangeSchema as aB, PxScrollSchema as aC, PxScrollSource as aD, PxStrokeTrimEffectSchema as aE, PxStrokeTrimSubPaths as aF, type PxSvgNode as aG, PxSvgNodeExtra as aH, PxTextEffectSchema as aI, PxTextPathEffectSchema as aJ, PxTextPathMethod as aK, PxTextPathSpacing as aL, type PxTimeline as aM, PxTimelineEngine as aN, PxTimelineEngineExtra as aO, PxTimelineSchema as aP, PxTransformByEffectSchema as aQ, type PxTransformParts as aR, PxTransformPartsSchema as aS, type PxTransformValue as aT, PxTransformValueSchema as aU, type PxTrigger as aV, PxTriggerSchema as aW, PxUnits as aX, type PxValidationContext as aY, type RemoveIndex as aZ, STYLE_ATTR_NAMES as a_, PxLengthAdjust as aa, type PxLoop as ab, PxLoopDirection as ac, PxLoopRepeatAt as ad, PxLoopSchema as ae, PxMaskType as af, PxMaskedByEffectSchema as ag, PxNodeBase as ah, PxNodeSchema as ai, type PxNormalizedKeyframe as aj, type PxNormalizedPropertyAnimation as ak, PxOutAction as al, PxPathOverflow as am, PxPinAlign as an, PxPlaybackDirection as ao, type PxPropertyAnimation as ap, PxPropertyAnimationSchema as aq, PxRepeaterEffectSchema as ar, PxRetimeEffectSchema as as, type PxSchema as at, type PxSchemaDesc as au, type PxScroll as av, PxScrollAxis as aw, PxScrollKind as ax, PxScrollPhase as ay, type PxScrollRangePoint as az, type PxAnimatorAPI as b, sanitizeAttributeValue as b$, TRANSFORM_FN_NAMES as b0, type Vec2 as b1, WIRE_VERSION_KEY as b2, type WireConversionConfig as b3, WireStepKind as b4, type WireVersion as b5, WireVersionRelation as b6, type WireVersionStep as b7, applyWireSteps as b8, bezierToSvgPath as b9, getNormalizedProps as bA, interpolateValue as bB, isNativeForced as bC, isPxElementFileFormat as bD, isPxElementFileFormatDeep as bE, isScrollTimeline as bF, kebabToCamelCaseWord as bG, kfEasing as bH, kfValue as bI, layoutGlyphTextChars as bJ, materializeAllInTree as bK, materializeGlyphText as bL, materializeGlyphTextAlongPath as bM, materializeMotionPathInPropAnim as bN, mayUseNativeScrollTimeline as bO, mergeStaticTransformIntoAnimDef as bP, nestAnimatorTimeline as bQ, parseWireVersion as bR, planSchemaRelease as bS, px as bT, readWireVersion as bU, releaseLogProblems as bV, reportDocumentDiagnostics as bW, resolveControlMode as bX, resolveTimelineEngine as bY, resolveTrigger as bZ, reverseEasing as b_, calcAnimationValues as ba, camelCaseToKebabWordIfNeeded as bb, clamp as bc, compareWireVersion as bd, composeTransformParts as be, controlModeTakesOverTrigger as bf, convertPlayerDocument as bg, createDiagnostics as bh, createPathSampler as bi, cubicBezier as bj, deepClone as bk, describeSchema as bl, diagnoseDocument as bm, diffFieldUniverse as bn, diffInEffect as bo, downgradePlayerDocument as bp, extendedPathForBrowser as bq, flattenAnimatorTimeline as br, formatWireVersion as bs, generateNewIds as bt, generateUniqueId as bu, getAnimatorConfig as bv, getBindings as bw, getChildren as bx, getDefs as by, getNormalizedBindings as bz, type PxAnimatorConfig as c, schemaFieldUniverse as c0, schemaKeys as c1, scrollOffsetProgress as c2, scrollPhaseInterval as c3, scrollResolveAxis as c4, scrollTotalDurationMs as c5, scrollViewProgress as c6, splitEasing as c7, subdivideCubicBezier as c8, toRGBA as c9, validateDocument as ca, validateNodeEffects as cb, versionAdvice as cc, PxStartOn as d, type PxNode as e, CSS_ONLY_STYLE_PROPS as f, DISALLOWED_SVG_TAGS_LOWER as g, PCT_BASED_ATTR_NAMES as h, PLAYER_WIRE_STEPS as i, PLAYER_WIRE_VERSION as j, PX_ANIM_ATTR_NAME as k, PX_ANIM_SRC_ATTR_NAME as l, PX_TRANSFORM_PART_KEYS as m, PX_TRIGGER_DEFAULTS as n, PX_UNKNOWN_KEY_ERROR as o, type PlayerConversionResult as p, PxAlongPathMode as q, type PxAnimatable as r, PxAnimatedSvgDocumentSchema as s, type PxAnimationDefinition as t, type PxAnimatorCallbacks as u, PxAnimatorConfigSchema as v, type PxAnimatorHandle as w, type PxAnyKeyframe as x, PxAttrValueSchema as y, type PxBasicAnimatorAPI as z };
+export { PxLoopRepeatAt as $, type PxDefinitions as A, PxDefinitionsSchema as B, type PxDiagnostic as C, PxDiagnosticCode as D, PxDiagnosticKind as E, type PxDiagnostics as F, type PxDiagnosticsConfig as G, type PxEffects as H, PxEffectsSchema as I, type PxElementAnimation as J, PxElementAnimationSchema as K, PxFillGradientEffectSchema as L, PxFillMode as M, PxFinishAction as N, type PxGlyph as O, type PxAnimatedSvgDocument as P, type PxGlyphFont as Q, PxGradientSpreadMethod as R, PxGradientStopSchema as S, PxGradientType as T, type PxInfer as U, type PxKeyframe as V, PxKeyframeSchema as W, PxKeyframeValueSchema as X, PxLengthAdjust as Y, type PxLoop as Z, PxLoopDirection as _, type PxEngineCallbacks as a, formatWireVersion as a$, PxLoopSchema as a0, PxMaskType as a1, PxMaskedByEffectSchema as a2, PxNodeBaseSchema as a3, PxNodeSchema as a4, PxOutAction as a5, PxPathOverflow as a6, PxPinAlign as a7, type PxPlaybackApi as a8, PxPlaybackDirection as a9, PxTimelineEngineSetting as aA, PxTimelineSchema as aB, PxTransformByEffectSchema as aC, type PxTransformParts as aD, PxTransformPartsSchema as aE, type PxTransformValue as aF, PxTransformValueSchema as aG, type PxTrigger as aH, PxTriggerSchema as aI, PxUnits as aJ, type PxValidationContext as aK, type PxVec2 as aL, type PxWireConversionOptions as aM, type PxWireConversionResult as aN, PxWireStepKind as aO, type PxWireVersion as aP, PxWireVersionRelation as aQ, type PxWireVersionStep as aR, applyWireSteps as aS, calcAnimationValues as aT, compareWireVersion as aU, controlModeTakesOverTrigger as aV, convertWireDocument as aW, describeSchema as aX, diagnoseDocument as aY, downgradeWireDocument as aZ, flattenAnimatorTimeline as a_, type PxPropertyAnimation as aa, PxPropertyAnimationSchema as ab, type PxRemoveIndex as ac, PxRepeaterEffectSchema as ad, PxRetimeEffectSchema as ae, type PxSchema as af, type PxSchemaDesc as ag, type PxScroll as ah, PxScrollAxis as ai, PxScrollKind as aj, PxScrollPhase as ak, type PxScrollRangePoint as al, PxScrollRangePointSchema as am, PxScrollRangeSchema as an, PxScrollSchema as ao, PxScrollSource as ap, PxStrokeTrimEffectSchema as aq, PxStrokeTrimSubPaths as ar, type PxSvgNode as as, PxSvgNodeRootSchema as at, PxTextEffectSchema as au, PxTextPathEffectSchema as av, PxTextPathMethod as aw, PxTextPathSpacing as ax, type PxTimeline as ay, PxTimelineEngine as az, type PxAnimatorApi as b, generateNewIds as b0, getAnimatorConfig as b1, getBindings as b2, getChildren as b3, getDefinitions as b4, isNativeForced as b5, isPxDocument as b6, isValidPxDocument as b7, materializeAllInTree as b8, mayUseNativeScrollTimeline as b9, deepClone as bA, generateUniqueId as bB, interpolateValue as bC, keyframeEasing as bD, keyframeValue as bE, materializeMotionPathInPropAnim as bF, mergeStaticTransformIntoAnimDef as bG, reportDocumentDiagnostics as bH, sanitizeAttributeValue as bI, nestAnimatorTimeline as ba, normalizeBindings as bb, parseWireVersion as bc, px as bd, readWireVersion as be, resolveControlMode as bf, resolveTimelineEngine as bg, resolveTrigger as bh, schemaKeys as bi, toDomProps as bj, validateDocument as bk, validateNodeEffects as bl, wireVersionAdvice as bm, type PxAnimatable as bn, PX_ANIM_ATTR_NAME as bo, PX_ANIM_SRC_ATTR_NAME as bp, PX_CSS_ONLY_STYLE_PROPS as bq, PX_DISALLOWED_SVG_TAGS_LOWER as br, PX_LOOP_JUMP_SHIFT_MS as bs, PX_TEXT_CONTENT_ATTR as bt, PX_UNKNOWN_KEY_ERROR as bu, type PxAnyKeyframe as bv, type PxMaterializeAllOptions as bw, type PxNormalizedKeyframe as bx, type PxNormalizedPropertyAnimation as by, createDiagnostics as bz, type PxAnimatorConfig as c, PxStartOn as d, type PxNode as e, PX_TRANSFORM_PART_KEYS as f, PX_TRIGGER_DEFAULTS as g, PX_WIRE_BASELINE_VERSION as h, PX_WIRE_STEPS as i, PX_WIRE_VERSION as j, PX_WIRE_VERSION_KEY as k, PxAlongPathMode as l, PxAnimatedSvgDocumentSchema as m, type PxAnimationDefinition as n, type PxAnimatorCallbacks as o, PxAnimatorConfigSchema as p, type PxAnimatorHandle as q, PxAttrValueSchema as r, type PxBezierPath as s, PxBezierPathSchema as t, type PxBinding as u, PxClipPathEffectSchema as v, PxCloneEffectSchema as w, PxCloneWithout as x, PxControlMode as y, type PxControlProps as z };