@pixodesk/svg-animator-core 1.0.41 → 1.0.43

package/dist/{PxDocumentDiagnostic-COGEjBbg.d.cts → PxDocumentDiagnostic-DkBZYJ7X.d.cts}

@@ -753,6 +753,130 @@ declare function getBindings(doc: PxAnimatedSvgDocument): PxBinding[] | undefine
 /** @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,18 +897,29 @@ 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;
 }
 /**
@@ -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.
@@ -10984,4 +11123,4 @@ declare function diagnoseDocument(doc: unknown): PxDocumentDiagnosis;
  */
 declare function reportDocumentDiagnostics(doc: unknown, where: string): void;
 
-export { PxLoopSchema as $, type PxDefinitions as A, PxDefinitionsSchema as B, type PxDiagnostic as C, PxDiagnosticKind as D, type PxDiagnostics as E, type PxDiagnosticsConfig as F, type PxEffects as G, PxEffectsSchema as H, type PxElementAnimation as I, PxElementAnimationSchema as J, PxFillGradientEffectSchema as K, PxFillMode as L, PxFinishAction as M, type PxGlyph as N, type PxGlyphFont as O, type PxAnimatedSvgDocument as P, PxGradientSpreadMethod as Q, PxGradientStopSchema as R, PxGradientType as S, type PxInfer as T, type PxKeyframe as U, PxKeyframeSchema as V, PxKeyframeValueSchema as W, PxLengthAdjust as X, type PxLoop as Y, PxLoopDirection as Z, PxLoopRepeatAt as _, type PxEngineCallbacks as a, generateNewIds as a$, PxMaskType as a0, PxMaskedByEffectSchema as a1, PxNodeBaseSchema as a2, PxNodeSchema as a3, PxOutAction as a4, PxPathOverflow as a5, PxPinAlign as a6, type PxPlaybackApi as a7, PxPlaybackDirection as a8, type PxPropertyAnimation as a9, PxTimelineSchema as aA, PxTransformByEffectSchema as aB, type PxTransformParts as aC, PxTransformPartsSchema as aD, type PxTransformValue as aE, PxTransformValueSchema as aF, type PxTrigger as aG, PxTriggerSchema as aH, PxUnits as aI, type PxValidationContext as aJ, type PxVec2 as aK, type PxWireConversionOptions as aL, type PxWireConversionResult as aM, PxWireStepKind as aN, type PxWireVersion as aO, PxWireVersionRelation as aP, type PxWireVersionStep as aQ, applyWireSteps as aR, calcAnimationValues as aS, compareWireVersion as aT, controlModeTakesOverTrigger as aU, convertWireDocument as aV, describeSchema as aW, diagnoseDocument as aX, downgradeWireDocument as aY, flattenAnimatorTimeline as aZ, formatWireVersion as a_, PxPropertyAnimationSchema as aa, type PxRemoveIndex as ab, PxRepeaterEffectSchema as ac, PxRetimeEffectSchema as ad, type PxSchema as ae, type PxSchemaDesc as af, type PxScroll as ag, PxScrollAxis as ah, PxScrollKind as ai, PxScrollPhase as aj, type PxScrollRangePoint as ak, PxScrollRangePointSchema as al, PxScrollRangeSchema as am, PxScrollSchema as an, PxScrollSource as ao, PxStrokeTrimEffectSchema as ap, PxStrokeTrimSubPaths as aq, type PxSvgNode as ar, PxSvgNodeRootSchema as as, PxTextEffectSchema as at, PxTextPathEffectSchema as au, PxTextPathMethod as av, PxTextPathSpacing as aw, type PxTimeline as ax, PxTimelineEngine as ay, PxTimelineEngineSetting as az, type PxAnimatorApi as b, getAnimatorConfig as b0, getBindings as b1, getChildren as b2, getDefinitions as b3, isNativeForced as b4, isPxDocument as b5, isValidPxDocument as b6, materializeAllInTree as b7, mayUseNativeScrollTimeline as b8, nestAnimatorTimeline as b9, generateUniqueId as bA, interpolateValue as bB, keyframeEasing as bC, keyframeValue as bD, materializeMotionPathInPropAnim as bE, mergeStaticTransformIntoAnimDef as bF, reportDocumentDiagnostics as bG, sanitizeAttributeValue as bH, normalizeBindings as ba, parseWireVersion as bb, px as bc, readWireVersion as bd, resolveControlMode as be, resolveTimelineEngine as bf, resolveTrigger as bg, schemaKeys as bh, toDomProps as bi, validateDocument as bj, validateNodeEffects as bk, wireVersionAdvice as bl, type PxAnimatable as bm, PX_ANIM_ATTR_NAME as bn, PX_ANIM_SRC_ATTR_NAME as bo, PX_CSS_ONLY_STYLE_PROPS as bp, PX_DISALLOWED_SVG_TAGS_LOWER as bq, PX_LOOP_JUMP_SHIFT_MS as br, PX_TEXT_CONTENT_ATTR as bs, PX_UNKNOWN_KEY_ERROR as bt, type PxAnyKeyframe as bu, type PxMaterializeAllOptions as bv, type PxNormalizedKeyframe as bw, type PxNormalizedPropertyAnimation as bx, createDiagnostics as by, deepClone 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 };
+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 };

package/dist/{PxDocumentDiagnostic-COGEjBbg.d.ts → PxDocumentDiagnostic-DkBZYJ7X.d.ts}

@@ -753,6 +753,130 @@ declare function getBindings(doc: PxAnimatedSvgDocument): PxBinding[] | undefine
 /** @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,18 +897,29 @@ 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;
 }
 /**
@@ -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.
@@ -10984,4 +11123,4 @@ declare function diagnoseDocument(doc: unknown): PxDocumentDiagnosis;
  */
 declare function reportDocumentDiagnostics(doc: unknown, where: string): void;
 
-export { PxLoopSchema as $, type PxDefinitions as A, PxDefinitionsSchema as B, type PxDiagnostic as C, PxDiagnosticKind as D, type PxDiagnostics as E, type PxDiagnosticsConfig as F, type PxEffects as G, PxEffectsSchema as H, type PxElementAnimation as I, PxElementAnimationSchema as J, PxFillGradientEffectSchema as K, PxFillMode as L, PxFinishAction as M, type PxGlyph as N, type PxGlyphFont as O, type PxAnimatedSvgDocument as P, PxGradientSpreadMethod as Q, PxGradientStopSchema as R, PxGradientType as S, type PxInfer as T, type PxKeyframe as U, PxKeyframeSchema as V, PxKeyframeValueSchema as W, PxLengthAdjust as X, type PxLoop as Y, PxLoopDirection as Z, PxLoopRepeatAt as _, type PxEngineCallbacks as a, generateNewIds as a$, PxMaskType as a0, PxMaskedByEffectSchema as a1, PxNodeBaseSchema as a2, PxNodeSchema as a3, PxOutAction as a4, PxPathOverflow as a5, PxPinAlign as a6, type PxPlaybackApi as a7, PxPlaybackDirection as a8, type PxPropertyAnimation as a9, PxTimelineSchema as aA, PxTransformByEffectSchema as aB, type PxTransformParts as aC, PxTransformPartsSchema as aD, type PxTransformValue as aE, PxTransformValueSchema as aF, type PxTrigger as aG, PxTriggerSchema as aH, PxUnits as aI, type PxValidationContext as aJ, type PxVec2 as aK, type PxWireConversionOptions as aL, type PxWireConversionResult as aM, PxWireStepKind as aN, type PxWireVersion as aO, PxWireVersionRelation as aP, type PxWireVersionStep as aQ, applyWireSteps as aR, calcAnimationValues as aS, compareWireVersion as aT, controlModeTakesOverTrigger as aU, convertWireDocument as aV, describeSchema as aW, diagnoseDocument as aX, downgradeWireDocument as aY, flattenAnimatorTimeline as aZ, formatWireVersion as a_, PxPropertyAnimationSchema as aa, type PxRemoveIndex as ab, PxRepeaterEffectSchema as ac, PxRetimeEffectSchema as ad, type PxSchema as ae, type PxSchemaDesc as af, type PxScroll as ag, PxScrollAxis as ah, PxScrollKind as ai, PxScrollPhase as aj, type PxScrollRangePoint as ak, PxScrollRangePointSchema as al, PxScrollRangeSchema as am, PxScrollSchema as an, PxScrollSource as ao, PxStrokeTrimEffectSchema as ap, PxStrokeTrimSubPaths as aq, type PxSvgNode as ar, PxSvgNodeRootSchema as as, PxTextEffectSchema as at, PxTextPathEffectSchema as au, PxTextPathMethod as av, PxTextPathSpacing as aw, type PxTimeline as ax, PxTimelineEngine as ay, PxTimelineEngineSetting as az, type PxAnimatorApi as b, getAnimatorConfig as b0, getBindings as b1, getChildren as b2, getDefinitions as b3, isNativeForced as b4, isPxDocument as b5, isValidPxDocument as b6, materializeAllInTree as b7, mayUseNativeScrollTimeline as b8, nestAnimatorTimeline as b9, generateUniqueId as bA, interpolateValue as bB, keyframeEasing as bC, keyframeValue as bD, materializeMotionPathInPropAnim as bE, mergeStaticTransformIntoAnimDef as bF, reportDocumentDiagnostics as bG, sanitizeAttributeValue as bH, normalizeBindings as ba, parseWireVersion as bb, px as bc, readWireVersion as bd, resolveControlMode as be, resolveTimelineEngine as bf, resolveTrigger as bg, schemaKeys as bh, toDomProps as bi, validateDocument as bj, validateNodeEffects as bk, wireVersionAdvice as bl, type PxAnimatable as bm, PX_ANIM_ATTR_NAME as bn, PX_ANIM_SRC_ATTR_NAME as bo, PX_CSS_ONLY_STYLE_PROPS as bp, PX_DISALLOWED_SVG_TAGS_LOWER as bq, PX_LOOP_JUMP_SHIFT_MS as br, PX_TEXT_CONTENT_ATTR as bs, PX_UNKNOWN_KEY_ERROR as bt, type PxAnyKeyframe as bu, type PxMaterializeAllOptions as bv, type PxNormalizedKeyframe as bw, type PxNormalizedPropertyAnimation as bx, createDiagnostics as by, deepClone 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 };
+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 };

package/dist/{chunk-L6GJ6Y2M.js → chunk-BOTZI36B.js}

@@ -4373,32 +4373,34 @@ var PxDiagnosticKind = {
   /** The player failed where it did not expect to — report it to us. */
   internal: "internal"
 };
-function asError(error) {
-  return typeof error === "string" ? new Error(error) : error;
+var DOCS_URL = "https://github.com/pixodesk/pixodesk-svg-animator/blob/main/docs/diagnostics.md";
+function codeLine(code) {
+  return "PX" + code + " " + DOCS_URL + "#px" + code;
+}
+function errorIn(data) {
+  return data.find((d) => d instanceof Error);
 }
 function createDiagnostics(config, prefix) {
   const tag = prefix ? prefix + " " : "";
   return {
-    warn: (kind, message, detail) => {
+    warn: (kind, code, ...data) => {
+      const message = codeLine(code);
       if (config == null ? void 0 : config.onWarn) {
-        config.onWarn({ kind, message, detail });
+        config.onWarn({ code, kind, data, message });
         return;
       }
       if (config == null ? void 0 : config.muteWarn) return;
-      const line = tag + kind + ": " + message;
-      if (detail === void 0) console.warn(line);
-      else console.warn(line, detail);
+      console.warn(tag + kind + " " + message, ...data);
     },
-    error: (kind, error, detail) => {
-      const err = asError(error);
+    error: (kind, code, ...data) => {
+      const message = codeLine(code);
+      const error = errorIn(data);
       if (config == null ? void 0 : config.onError) {
-        config.onError({ kind, message: err.message, error: err, detail });
+        config.onError({ code, kind, data, message, error });
         return;
       }
       if (config == null ? void 0 : config.muteError) return;
-      const line = tag + kind + ": " + err.message;
-      if (detail === void 0) console.error(line);
-      else console.error(line, detail);
+      console.error(tag + kind + " " + message, ...data);
     }
   };
 }
@@ -4592,4 +4594,4 @@ export {
   diagnoseDocument,
   reportDocumentDiagnostics
 };
-//# sourceMappingURL=chunk-L6GJ6Y2M.js.map
+//# sourceMappingURL=chunk-BOTZI36B.js.map