@realsee/dnalogel 3.81.12-alpha.1 → 3.81.12

package/libs/DigitalPerformancePlugin/core/DigitalPerformanceNameplate.d.ts

@@ -0,0 +1,115 @@
+import type { Five } from '@realsee/five';
+import * as THREE from 'three';
+import type { DigitalModelPlayer } from './DigitalStateMachine';
+export declare const DEFAULT_DIGITAL_PERFORMANCE_NAME_MAX_LENGTH = 30;
+/** 规范化名牌文本，使用 Unicode code point 计数，避免 emoji 被截成半个字符。 */
+export declare function normalizeDigitalPerformanceName(value: unknown, maxLength?: number): string;
+export interface DigitalPerformanceNameplateBinding {
+    id: string;
+    player: DigitalModelPlayer;
+    /** 用于计算包围盒和世界坐标的数字人模型根节点。 */
+    model: THREE.Object3D;
+}
+export interface DigitalPerformanceNameplateRenderContext {
+    id: string;
+    text: string;
+    player: DigitalModelPlayer;
+    model: THREE.Object3D;
+}
+export interface DigitalPerformanceNameplateOptions {
+    /** 名牌最多展示的 Unicode 字符数，默认 30。 */
+    maxLength?: number;
+    /** 相对模型包围盒顶部的世界坐标偏移，默认 [0, 0.12, 0]。 */
+    offset?: [number, number, number];
+    /** 自定义名牌文本，默认使用 displayName ?? name。 */
+    getText?: (player: DigitalModelPlayer) => string | undefined | null;
+    /** 自定义名牌元素；不传时创建默认气泡 div。 */
+    createElement?: (context: DigitalPerformanceNameplateRenderContext) => HTMLElement;
+    /** 自定义名牌更新逻辑；不传时将 textContent 更新为当前文本。 */
+    updateElement?: (element: HTMLElement, context: DigitalPerformanceNameplateRenderContext) => void;
+    /** 名牌元素 class。 */
+    className?: string;
+    /** 名牌元素的额外内联样式。 */
+    style?: Record<string, string>;
+    /** overlay 容器 class。 */
+    containerClassName?: string;
+    /** overlay 容器的额外内联样式。 */
+    containerStyle?: Record<string, string>;
+    /**
+     * 调试：是否显示每个绑定模型的世界包围盒（THREE.BoxHelper），用于核对名牌锚点。
+     * 默认 false，不影响名牌本身。
+     */
+    debugBoundingBox?: boolean;
+}
+/**
+ * DigitalPerformance 的 2D 名牌层。
+ *
+ * 它只负责「模型世界坐标 → 播放器 overlay DOM」和名牌生命周期，
+ * 由 Legacy/V2 controller 在各自的模型帧更新完成后调用 update()，因此两个播放器共用同一套 DOM 规则。
+ */
+export declare class DigitalPerformanceNameplate {
+    private readonly five;
+    private options;
+    private parent;
+    private container;
+    private bindings;
+    private nameOverrides;
+    private enabled;
+    /** 是否由本层自动挂载到 five canvas 父容器（插件内置模式），无需调用方提供容器。 */
+    private autoMount;
+    private readonly onResize;
+    private readonly anchor;
+    private readonly box;
+    private readonly offset;
+    private readonly debugBoxes;
+    private debugBoxesVisible;
+    constructor(five: Five, options?: DigitalPerformanceNameplateOptions);
+    /** 将 overlay 挂到 Five canvas 的父级或业务提供的全屏相对定位容器。 */
+    mount(parent: HTMLElement, options?: DigitalPerformanceNameplateOptions): void;
+    /**
+     * 内置自动挂载：把 overlay 挂到 five canvas 的父容器（与 canvas 同级），调用方无需提供容器。
+     * canvas 尚未进入 DOM 时不报错，会在后续 update() 中自动重试挂载。
+     */
+    enableAutoMount(options?: DigitalPerformanceNameplateOptions): void;
+    /** 移除 overlay，但保留 bindings；重新挂载（含换容器）时会复用 bindings。 */
+    unmount(): void;
+    /** 更新当前章节的角色绑定；id 是角色唯一键，同一模型复用时也不会互相覆盖。 */
+    setBindings(bindings: DigitalPerformanceNameplateBinding[]): void;
+    /** 实时更新指定角色名称，不需要重新加载模型或动画资源。 */
+    updateName(id: string, value: string): void;
+    setEnabled(enabled: boolean): void;
+    /**
+     * 调试：显示/隐藏每个绑定模型的世界包围盒（THREE.BoxHelper）。
+     * 包围盒与名牌锚点使用的是同一个 Box3（setFromObject(model)），用于核对名牌定位。
+     * 默认关闭；不影响名牌本身。
+     */
+    setBoundingBoxVisible(visible: boolean): void;
+    /** 应用 `options.debugBoundingBox`；未配置时保持现状（不覆盖运行时的 setBoundingBoxVisible）。 */
+    private applyDebugBoundingBoxOption;
+    isEnabled(): boolean;
+    /** 在数字人模型变换完成后调用，更新所有当前章节名牌的位置和可见性。 */
+    update(): void;
+    dispose(): void;
+    /** 内置自动挂载的实际执行：解析 five canvas 的父容器并 mount；条件不满足时静默跳过。 */
+    private tryAutoMount;
+    private getMaxLength;
+    private getText;
+    private ensureElement;
+    private applyElementContent;
+    private hideElement;
+    private applyContainerStyle;
+    private applyElementStyle;
+    /**
+     * 注入名牌气泡箭头的伪元素样式。
+     * 该样式是模块级全局资源（选择器为 .digital-performance-nameplate::after），
+     * 因此只在 mount 时按 id 幂等注入一次，而不是在每个名牌元素创建时重复注入。
+     * 当调用方完全自定义了 className 时，箭头选择器不会命中，也就无需注入。
+     */
+    private injectArrowStyle;
+    private isObjectVisible;
+    /** 同步单个绑定的调试包围盒；未开启时 no-op。 */
+    private syncDebugBox;
+    private removeDebugBox;
+    private clearDebugBoxes;
+    private getScreenPosition;
+}

package/libs/DigitalPerformancePlugin/core/DigitalPerformanceNameplate.js

@@ -0,0 +1,266 @@
+var N = Object.defineProperty, D = Object.defineProperties;
+var O = Object.getOwnPropertyDescriptors;
+var v = Object.getOwnPropertySymbols;
+var T = Object.prototype.hasOwnProperty, S = Object.prototype.propertyIsEnumerable;
+var d = (r, e, t) => e in r ? N(r, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : r[e] = t, c = (r, e) => {
+  for (var t in e || (e = {}))
+    T.call(e, t) && d(r, t, e[t]);
+  if (v)
+    for (var t of v(e))
+      S.call(e, t) && d(r, t, e[t]);
+  return r;
+}, w = (r, e) => D(r, O(e));
+var a = (r, e, t) => (d(r, typeof e != "symbol" ? e + "" : e, t), t);
+import * as u from "three";
+const m = 30;
+function M(r, e = m) {
+  const t = typeof r == "string" ? r.trim() : "", n = Number.isFinite(e) ? Math.max(0, Math.floor(e)) : m;
+  return Array.from(t).slice(0, n).join("");
+}
+const C = [0, 0.12, 0], f = "digital-performance-nameplate", _ = "digital-performance-nameplates", L = "digital-performance-nameplate-arrow-style", R = {
+  position: "absolute",
+  "z-index": "1",
+  display: "block",
+  padding: "6px 8px",
+  color: "#fff",
+  background: "rgba(0, 0, 0, 0.85)",
+  "border-radius": "6px",
+  "box-shadow": "0 6px 16px 0 rgba(0, 0, 0, 0.08),0 3px 6px -4px rgba(0, 0, 0, 0.12),0 9px 28px 8px rgba(0, 0, 0, 0.05)",
+  fontSize: "14px",
+  "line-height": "22px",
+  whiteSpace: "nowrap",
+  "pointer-events": "none",
+  transform: "translate3d(0, 0, 0) translate(-50%, calc(-100% - 8px))",
+  "will-change": "transform"
+}, j = {
+  position: "absolute",
+  inset: "0",
+  "z-index": "5",
+  overflow: "hidden",
+  "pointer-events": "none"
+};
+class z {
+  constructor(e, t = {}) {
+    a(this, "five");
+    a(this, "options");
+    a(this, "parent", null);
+    a(this, "container", null);
+    a(this, "bindings", /* @__PURE__ */ new Map());
+    a(this, "nameOverrides", /* @__PURE__ */ new Map());
+    a(this, "enabled", !0);
+    /** 是否由本层自动挂载到 five canvas 父容器（插件内置模式），无需调用方提供容器。 */
+    a(this, "autoMount", !1);
+    a(this, "onResize", () => this.update());
+    a(this, "anchor", new u.Vector3());
+    a(this, "box", new u.Box3());
+    a(this, "offset", new u.Vector3());
+    a(this, "debugBoxes", /* @__PURE__ */ new Map());
+    a(this, "debugBoxesVisible", !1);
+    this.five = e, this.options = c({}, t), this.applyDebugBoundingBoxOption();
+  }
+  /** 将 overlay 挂到 Five canvas 的父级或业务提供的全屏相对定位容器。 */
+  mount(e, t) {
+    var n;
+    if (t && (this.options = c(c({}, this.options), t)), this.parent === e && this.container) {
+      this.applyContainerStyle(), this.applyDebugBoundingBoxOption(), this.update();
+      return;
+    }
+    this.unmount(), this.parent = e, this.container = document.createElement("div"), this.container.className = (n = this.options.containerClassName) != null ? n : _, this.applyContainerStyle(), this.injectArrowStyle(), e.appendChild(this.container), typeof window != "undefined" && window.addEventListener("resize", this.onResize, !1), this.applyDebugBoundingBoxOption(), this.update();
+  }
+  /**
+   * 内置自动挂载：把 overlay 挂到 five canvas 的父容器（与 canvas 同级），调用方无需提供容器。
+   * canvas 尚未进入 DOM 时不报错，会在后续 update() 中自动重试挂载。
+   */
+  enableAutoMount(e) {
+    e && (this.options = c(c({}, this.options), e)), this.autoMount = !0, this.applyDebugBoundingBoxOption(), this.tryAutoMount();
+  }
+  /** 移除 overlay，但保留 bindings；重新挂载（含换容器）时会复用 bindings。 */
+  unmount() {
+    var e;
+    typeof window != "undefined" && window.removeEventListener("resize", this.onResize, !1), (e = this.container) == null || e.remove(), this.container = null, this.parent = null, this.bindings.forEach((t) => {
+      t.element = void 0;
+    });
+  }
+  /** 更新当前章节的角色绑定；id 是角色唯一键，同一模型复用时也不会互相覆盖。 */
+  setBindings(e) {
+    const t = new Set(e.map((i) => i.id)), n = this.bindings, s = /* @__PURE__ */ new Map();
+    e.forEach((i) => {
+      const o = n.get(i.id);
+      s.set(i.id, w(c({}, i), { element: o == null ? void 0 : o.element }));
+    }), n.forEach((i, o) => {
+      var l;
+      t.has(o) || ((l = i.element) == null || l.remove(), this.removeDebugBox(o), this.nameOverrides.delete(o));
+    }), this.bindings = s, this.update();
+  }
+  /** 实时更新指定角色名称，不需要重新加载模型或动画资源。 */
+  updateName(e, t) {
+    const n = M(t, this.getMaxLength());
+    this.nameOverrides.set(e, n), this.update();
+  }
+  setEnabled(e) {
+    this.enabled = e, this.container && (this.container.style.display = e ? "" : "none"), e && this.update();
+  }
+  /**
+   * 调试：显示/隐藏每个绑定模型的世界包围盒（THREE.BoxHelper）。
+   * 包围盒与名牌锚点使用的是同一个 Box3（setFromObject(model)），用于核对名牌定位。
+   * 默认关闭；不影响名牌本身。
+   */
+  setBoundingBoxVisible(e) {
+    this.debugBoxesVisible = e, e || this.clearDebugBoxes(), this.five.needsRender = !0, this.update();
+  }
+  /** 应用 `options.debugBoundingBox`；未配置时保持现状（不覆盖运行时的 setBoundingBoxVisible）。 */
+  applyDebugBoundingBoxOption() {
+    const e = this.options.debugBoundingBox;
+    e !== void 0 && this.setBoundingBoxVisible(e);
+  }
+  isEnabled() {
+    return this.enabled;
+  }
+  /** 在数字人模型变换完成后调用，更新所有当前章节名牌的位置和可见性。 */
+  update() {
+    this.autoMount && this.tryAutoMount(), this.container && (this.container.style.display = this.enabled ? "" : "none", this.enabled && this.bindings.forEach((e) => {
+      this.syncDebugBox(e);
+      const t = this.getText(e.player, e.id), n = {
+        id: e.id,
+        text: t,
+        player: e.player,
+        model: e.model
+      };
+      if (!t || !this.isObjectVisible(e.model)) {
+        this.hideElement(e);
+        return;
+      }
+      const s = this.ensureElement(e, n), i = this.getScreenPosition(e.model);
+      if (!i) {
+        this.hideElement(e);
+        return;
+      }
+      this.applyElementContent(s, n), s.style.display = "block", s.style.transform = `translate3d(${i.x}px, ${i.y}px, 0) translate(-50%, calc(-100% - 8px))`;
+    }));
+  }
+  dispose() {
+    this.autoMount = !1, this.unmount(), this.clearDebugBoxes(), this.bindings.clear(), this.nameOverrides.clear();
+  }
+  /** 内置自动挂载的实际执行：解析 five canvas 的父容器并 mount；条件不满足时静默跳过。 */
+  tryAutoMount() {
+    var t, n, s;
+    if (!this.autoMount || this.container || typeof document == "undefined")
+      return;
+    const e = (s = (n = (t = this.five).getElement) == null ? void 0 : n.call(t)) == null ? void 0 : s.parentElement;
+    e && this.mount(e);
+  }
+  getMaxLength() {
+    var e;
+    return (e = this.options.maxLength) != null ? e : m;
+  }
+  getText(e, t) {
+    var o, l, h, p;
+    const n = this.nameOverrides.get(t), s = (l = (o = this.options).getText) == null ? void 0 : l.call(o, e), i = (h = e.displayName) != null ? h : e.name;
+    return M((p = n != null ? n : s) != null ? p : i, this.getMaxLength());
+  }
+  ensureElement(e, t) {
+    var i, o, l, h;
+    if (e.element)
+      return e.element;
+    const n = (l = (o = (i = this.options).createElement) == null ? void 0 : o.call(i, t)) != null ? l : document.createElement("div");
+    return ((h = this.options.className) != null ? h : f).split(/\s+/).filter(Boolean).forEach((p) => n.classList.add(p)), n.setAttribute("data-digital-performance-nameplate-id", e.id), n.setAttribute("role", "status"), this.applyElementStyle(n), this.container.appendChild(n), e.element = n, n;
+  }
+  applyElementContent(e, t) {
+    this.options.updateElement ? this.options.updateElement(e, t) : e.textContent = t.text, e.setAttribute("aria-label", t.text);
+  }
+  hideElement(e) {
+    e.element && (e.element.style.display = "none");
+  }
+  applyContainerStyle() {
+    var e;
+    this.container && (Object.entries(j).forEach(([t, n]) => this.container.style.setProperty(t, n)), Object.entries((e = this.options.containerStyle) != null ? e : {}).forEach(([t, n]) => this.container.style.setProperty(t, n)));
+  }
+  applyElementStyle(e) {
+    var t;
+    Object.entries(R).forEach(([n, s]) => e.style.setProperty(n, s)), Object.entries((t = this.options.style) != null ? t : {}).forEach(([n, s]) => e.style.setProperty(n, s));
+  }
+  /**
+   * 注入名牌气泡箭头的伪元素样式。
+   * 该样式是模块级全局资源（选择器为 .digital-performance-nameplate::after），
+   * 因此只在 mount 时按 id 幂等注入一次，而不是在每个名牌元素创建时重复注入。
+   * 当调用方完全自定义了 className 时，箭头选择器不会命中，也就无需注入。
+   */
+  injectArrowStyle() {
+    var n;
+    if (typeof document == "undefined" || !document.head || !((n = this.options.className) != null ? n : f).split(/\s+/).includes(f) || document.getElementById(L))
+      return;
+    const t = document.createElement("style");
+    t.id = L, t.textContent = `
+      .digital-performance-nameplate::after {
+        content: '';
+        width: 16px;
+        height: 8px;
+        position: absolute;
+        top: 100%;
+        left: 50%;
+        transform: translateX(-50%) translateY(-1px) rotate(180deg);
+        background-color: rgba(0, 0, 0, 0.85);
+        clip-path: path('M 0 8 A 4 4 0 0 0 2.82842712474619 6.82842712474619 L 6.585786437626905 3.0710678118654755 A 2 2 0 0 1 9.414213562373096 3.0710678118654755 L 13.17157287525381 6.82842712474619 A 4 4 0 0 0 16 8 Z')
+      }
+    `, document.head.appendChild(t);
+  }
+  isObjectVisible(e) {
+    let t = e;
+    for (; t; ) {
+      if (!t.visible)
+        return !1;
+      t = t.parent;
+    }
+    return !0;
+  }
+  /** 同步单个绑定的调试包围盒；未开启时 no-op。 */
+  syncDebugBox(e) {
+    if (!this.debugBoxesVisible)
+      return;
+    let t = this.debugBoxes.get(e.id);
+    if (!t) {
+      t = new u.BoxHelper(e.model, 16726832);
+      const n = t.material;
+      n && (n.depthTest = !1, n.transparent = !0, n.opacity = 0.9), this.five.scene.add(t), this.debugBoxes.set(e.id, t);
+    }
+    t.update();
+  }
+  removeDebugBox(e) {
+    var n, s;
+    const t = this.debugBoxes.get(e);
+    t && (this.five.scene.remove(t), (n = t.geometry) == null || n.dispose(), (s = t.material) == null || s.dispose(), this.debugBoxes.delete(e));
+  }
+  clearDebugBoxes() {
+    this.debugBoxes.forEach((e) => {
+      var t, n;
+      this.five.scene.remove(e), (t = e.geometry) == null || t.dispose(), (n = e.material) == null || n.dispose();
+    }), this.debugBoxes.clear();
+  }
+  getScreenPosition(e) {
+    var x, g, y, E, b;
+    if (e.updateMatrixWorld(!0), this.box.setFromObject(e), this.box.isEmpty())
+      return null;
+    this.box.getCenter(this.anchor), this.anchor.y = this.box.max.y;
+    const t = (x = this.options.offset) != null ? x : C;
+    this.offset.fromArray(t), this.anchor.add(this.offset);
+    const n = this.anchor.clone().project(this.five.camera);
+    if (n.z < -1 || n.z > 1)
+      return null;
+    const s = this.five.project2d(this.anchor);
+    if (!s)
+      return null;
+    let i = s.x, o = s.y;
+    const l = this.five.getElement();
+    if (l && this.parent) {
+      const B = l.getBoundingClientRect(), A = this.parent.getBoundingClientRect();
+      i += B.left - A.left, o += B.top - A.top;
+    }
+    const h = (y = (g = this.parent) == null ? void 0 : g.clientWidth) != null ? y : 0, p = (b = (E = this.parent) == null ? void 0 : E.clientHeight) != null ? b : 0;
+    return h > 0 && p > 0 && (i < -200 || i > h + 200 || o < -100 || o > p + 100) ? null : { x: i, y: o };
+  }
+}
+export {
+  m as DEFAULT_DIGITAL_PERFORMANCE_NAME_MAX_LENGTH,
+  z as DigitalPerformanceNameplate,
+  M as normalizeDigitalPerformanceName
+};

package/libs/DigitalPerformancePlugin/core/DigitalStateMachine.d.ts

@@ -32,7 +32,9 @@ interface DigitalModelPlayerEffect {
 }
 interface DigitalModelPlayer {
     id: string;
+    /** 兼容已有 name；业务需要独立展示字段时优先使用 displayName。 */
     name: string;
+    displayName?: string;
     type: 'model';
     model: string;
     keyframes: DigitalModelKeyframe[];

package/libs/DigitalPerformancePlugin/index.d.ts

@@ -1,10 +1,15 @@
 import type { Five } from '@realsee/five';
 import DigitalPerformancePluginController from './controller';
+export { DigitalPerformanceNameplate, normalizeDigitalPerformanceName, DEFAULT_DIGITAL_PERFORMANCE_NAME_MAX_LENGTH, } from './core/DigitalPerformanceNameplate';
+export type { DigitalPerformanceNameplateBinding, DigitalPerformanceNameplateOptions, DigitalPerformanceNameplateRenderContext, } from './core/DigitalPerformanceNameplate';
 export { DigitalHuman } from './core/DigitalHuman';
 export { DigitalPlayground } from './core/DigitalPlayground';
 export { DigitalStateMachine } from './core/DigitalStateMachine';
 export * from './controller';
 export * from './typings';
+export * from './animation-script-adapter';
+export * from './movement-track-classifier';
+export * from './transform-script-data';
 export type DigitalPerformancePluginExportInterface = InstanceType<typeof DigitalPerformancePluginController>;
 export type DigitalPerformancePluginParamsInterface = ConstructorParameters<typeof DigitalPerformancePluginController>[1];
 export declare const DigitalPerformancePlugin: (five: Five, params?: DigitalPerformancePluginParamsInterface) => DigitalPerformancePluginController;

package/libs/DigitalPerformancePlugin/index.js

@@ -1,18 +1,36 @@
 import o from "./controller/index.js";
-import { DigitalHuman as D } from "./core/DigitalHuman.js";
-import { DigitalPlayground as c } from "./core/DigitalPlayground.js";
-import { DigitalStateMachine as d } from "./core/DigitalStateMachine.js";
+import { DEFAULT_DIGITAL_PERFORMANCE_NAME_MAX_LENGTH as c, DigitalPerformanceNameplate as g, normalizeDigitalPerformanceName as D } from "./core/DigitalPerformanceNameplate.js";
+import { DigitalHuman as P } from "./core/DigitalHuman.js";
+import { DigitalPlayground as A } from "./core/DigitalPlayground.js";
+import { DigitalStateMachine as O } from "./core/DigitalStateMachine.js";
+import { AnimationScriptAdapterSafetyError as T, transformAnimationDetailToDigitalScript as s } from "./animation-script-adapter.js";
+import { MOVEMENT_OCCURRENCE_EPSILON as C, MOVEMENT_POSITION_EPSILON as I, MOVEMENT_SCHEMA_VERSION as v, classifyMovementTrack as L, getEffectivePointActionDuration as R, getMovementActionDuration as V, hasMovementV2Signal as d, isConverterSafeMovementMatrix as y } from "./movement-track-classifier.js";
+import { transformScriptData as h } from "./transform-script-data.js";
 import "three";
-import "./mock.js";
-import "../shared-utils/five/transformPosition.js";
 import "@realsee/five/gltf-loader";
 import "./core/Trace.js";
 import "@realsee/five";
-const g = (r, t) => new o(r, t);
+import "./mock.js";
+import "../shared-utils/five/transformPosition.js";
+const l = (t, r) => new o(t, r);
 export {
-  D as DigitalHuman,
-  g as DigitalPerformancePlugin,
-  c as DigitalPlayground,
-  d as DigitalStateMachine,
-  g as default
+  T as AnimationScriptAdapterSafetyError,
+  c as DEFAULT_DIGITAL_PERFORMANCE_NAME_MAX_LENGTH,
+  P as DigitalHuman,
+  g as DigitalPerformanceNameplate,
+  l as DigitalPerformancePlugin,
+  A as DigitalPlayground,
+  O as DigitalStateMachine,
+  C as MOVEMENT_OCCURRENCE_EPSILON,
+  I as MOVEMENT_POSITION_EPSILON,
+  v as MOVEMENT_SCHEMA_VERSION,
+  L as classifyMovementTrack,
+  l as default,
+  R as getEffectivePointActionDuration,
+  V as getMovementActionDuration,
+  d as hasMovementV2Signal,
+  y as isConverterSafeMovementMatrix,
+  D as normalizeDigitalPerformanceName,
+  s as transformAnimationDetailToDigitalScript,
+  h as transformScriptData
 };

package/libs/DigitalPerformancePlugin/movement-track-classifier.d.ts

@@ -0,0 +1,52 @@
+export declare const MOVEMENT_SCHEMA_VERSION: 2;
+export declare const MOVEMENT_POSITION_EPSILON = 0.001;
+export declare const MOVEMENT_OCCURRENCE_EPSILON = 1e-9;
+export type MovementPosition = {
+    x: number;
+    y: number;
+    z: number;
+};
+export type PointAction = {
+    animationUrl?: string;
+    duration?: number;
+    repeat?: boolean;
+    [key: string]: unknown;
+};
+export type MovementConfig = {
+    duration: number;
+    animationUrl: string;
+    repeat: 'loop' | 'once';
+    restartOnEnter?: boolean;
+};
+export type TrackPoint = {
+    point: MovementPosition;
+    actions?: PointAction[];
+    outgoingMovement?: MovementConfig;
+    [key: string]: unknown;
+};
+export type MovementTrackProjection = {
+    segmentIndex: number;
+    distance: number;
+};
+export type CanonicalMovementTrackPlan = {
+    path: MovementPosition[];
+    points: Array<TrackPoint & {
+        actions: PointAction[];
+    }>;
+    projections: MovementTrackProjection[];
+};
+export type MovementTrackConflictReason = 'unsupported-schema' | 'invalid-path' | 'invalid-points' | 'invalid-matrix' | 'invalid-actions' | 'invalid-movement' | 'terminal-movement' | 'invalid-projection' | 'matrix-origin-mismatch' | 'legacy-summary-mismatch';
+export type MovementTrackClassification = {
+    kind: 'canonical-v2';
+    plan: CanonicalMovementTrackPlan;
+} | {
+    kind: 'pure-legacy';
+} | {
+    kind: 'conflict-invalid';
+    reason: MovementTrackConflictReason;
+};
+export declare function getEffectivePointActionDuration(action: PointAction): number;
+export declare function getMovementActionDuration(actions: PointAction[]): number;
+export declare function isConverterSafeMovementMatrix(value: unknown): value is number[];
+export declare function hasMovementV2Signal(player: unknown): boolean;
+export declare function classifyMovementTrack(player: unknown): MovementTrackClassification;