@uptimizr/replay 0.1.0

package/dist/drivers/babylon-lite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"babylon-lite.js","sourceRoot":"","sources":["../../src/drivers/babylon-lite.ts"],"names":[],"mappings":"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"}

package/dist/drivers/babylon.d.ts

@@ -0,0 +1,99 @@
+import type { Camera, Scene } from "@babylonjs/core";
+import type { CustomPropValue } from "@uptimizr/schema";
+import type { ReplayDriver } from "../types.js";
+export interface BabylonReplayDriverOptions {
+    /** Scene to re-drive. */
+    scene: Scene;
+    /** Camera to move. Defaults to `scene.activeCamera`. */
+    camera?: Camera;
+    /** Called for each replayed pointer event, so the host can render a marker. */
+    onPointer?: (screen: [number, number] | undefined, hitPoint: [number, number, number] | undefined, hitMesh: string | undefined, type: "pointer_move" | "pointer_click" | "pointer_down" | "pointer_up") => void;
+    /** Called for each replayed mesh interaction, so the host can highlight it. */
+    onMeshInteraction?: (mesh: string, kind: string, point: [number, number, number] | undefined) => void;
+    /**
+     * Scene-actor resolvers for `node_transform` drive-back (ADR 0027). Maps a
+     * recorded `nodeId` to the live Babylon node to re-drive — a direct
+     * `TransformNode`/`AbstractMesh` or a `() => node` resolver (robust to load
+     * order). Tier-1 samples set the node's world transform; Tier-2 samples
+     * (`boneId` present) set the matching skeleton bone's local transform.
+     */
+    nodes?: Record<string, BabylonReplayNode | (() => BabylonReplayNode | null | undefined)>;
+    /**
+     * Called for **every** replayed `node_transform` (Tier 1 and Tier 2), after any
+     * node/bone drive-back. Lets a host render a proxy marker for an actor it has
+     * no live node for, or annotate the timeline. `boneId` is set for Tier-2 bone
+     * samples; the transform is in the sample's frame (world for Tier 1,
+     * skeleton-local for Tier 2).
+     */
+    onNodeTransform?: (nodeId: string, transform: {
+        boneId: string | undefined;
+        childPath: string | undefined;
+        position: [number, number, number];
+        rotation: [number, number, number, number];
+        scale: [number, number, number] | undefined;
+    }, ts: number) => void;
+    /**
+     * Called for each replayed developer-defined `custom` event. The driver can't
+     * know how to render an arbitrary domain event, so it forwards the name,
+     * props, and timestamp for the host to visualize (marker, toast, log, ...).
+     */
+    onCustom?: (name: string, props: Record<string, CustomPropValue> | undefined, ts: number) => void;
+    /**
+     * Called for each replayed `input_action` (discrete keyboard/gamepad action,
+     * ADR 0023). The driver can't re-drive an app-defined action, so it forwards
+     * the action, raw `code`/`button`, source, and timestamp for the host to
+     * annotate the timeline.
+     */
+    onInputAction?: (input: {
+        action: string;
+        code: string | undefined;
+        button: number | undefined;
+        pressed: boolean | undefined;
+        source: string | undefined;
+    }, ts: number) => void;
+    /**
+     * Called for each replayed browser/engine lifecycle event (viewport resize,
+     * tab visibility, window focus, GPU context loss/restore). The driver doesn't
+     * re-drive these — it forwards them so a replay UI can annotate the timeline
+     * with what was happening around the scene.
+     */
+    onLifecycle?: (event: {
+        type: "viewport_resize";
+        width: number;
+        height: number;
+        dpr: number | undefined;
+    } | {
+        type: "visibility_change";
+        state: "visible" | "hidden";
+    } | {
+        type: "focus_change";
+        focused: boolean;
+    } | {
+        type: "context_lost";
+    } | {
+        type: "context_restored";
+    }, ts: number) => void;
+    /**
+     * Called for each replayed `runtime_error` event (opt-in capture, ADR 0013).
+     * Forwarded so a replay UI can mark where a JS error or unhandled rejection
+     * interrupted the session.
+     */
+    onError?: (error: {
+        kind: "error" | "unhandledrejection";
+        message: string;
+        source: string | undefined;
+        lineno: number | undefined;
+        colno: number | undefined;
+        stack: string | undefined;
+    }, ts: number) => void;
+}
+/** A Babylon node a replay can drive (a `TransformNode` or `AbstractMesh`). */
+export type BabylonReplayNode = object;
+/**
+ * Babylon replay driver. Re-drives camera pose (and surfaces pointer/mesh events
+ * to host callbacks) in the user's own scene.
+ *
+ * It only reads/writes the scene — it never emits analytics events (ADR 0006).
+ */
+export declare function createBabylonReplayDriver(options: BabylonReplayDriverOptions): ReplayDriver;
+//# sourceMappingURL=babylon.d.ts.map

package/dist/drivers/babylon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"babylon.d.ts","sourceRoot":"","sources":["../../src/drivers/babylon.ts"],"names":[],"mappings":"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"}

package/dist/drivers/babylon.js

@@ -0,0 +1,176 @@
+import { Vector3 } from "@babylonjs/core/Maths/math.vector.js";
+import { Quaternion } from "@babylonjs/core/Maths/math.vector.js";
+/** Resolve a node entry (direct ref or `() => node`) to a live node, or `null`. */
+function resolveReplayNode(entry) {
+    if (!entry)
+        return null;
+    if (typeof entry === "function") {
+        return entry() ?? null;
+    }
+    return entry;
+}
+/**
+ * Walk a `/`-separated {@link NodeTransformEvent.childPath} from a resolved root
+ * actor to the descendant node, matching each segment against direct children by
+ * `name` (ADR 0033). Returns `null` if any segment is missing.
+ */
+function resolveChildByPath(root, childPath) {
+    let cur = root;
+    for (const segment of childPath.split("/")) {
+        if (!segment)
+            continue;
+        const children = cur?.getChildren?.();
+        if (!Array.isArray(children))
+            return null;
+        cur = children.find((c) => c.name === segment) ?? null;
+        if (!cur)
+            return null;
+    }
+    return cur;
+}
+/**
+ * Babylon replay driver. Re-drives camera pose (and surfaces pointer/mesh events
+ * to host callbacks) in the user's own scene.
+ *
+ * It only reads/writes the scene — it never emits analytics events (ADR 0006).
+ */
+export function createBabylonReplayDriver(options) {
+    const target = new Vector3();
+    const position = new Vector3();
+    const nodePosition = new Vector3();
+    return {
+        reset() {
+            // Camera state is fully determined by the next camera_sample, so there is
+            // nothing to restore; host-rendered markers are the host's responsibility.
+        },
+        apply(event) {
+            switch (event.type) {
+                case "camera_sample": {
+                    const cam = (options.camera ??
+                        options.scene.activeCamera);
+                    if (!cam)
+                        return;
+                    const [px, py, pz] = event.position;
+                    if (event.target) {
+                        target.set(event.target[0], event.target[1], event.target[2]);
+                    }
+                    else {
+                        const [dx, dy, dz] = event.direction;
+                        target.set(px + dx, py + dy, pz + dz);
+                    }
+                    // Set the target first so ArcRotateCamera derives alpha/beta/radius
+                    // relative to it, then place the camera.
+                    cam.setTarget?.(target);
+                    if (typeof cam.setPosition === "function") {
+                        position.set(px, py, pz);
+                        cam.setPosition(position);
+                    }
+                    else {
+                        cam.position.set(px, py, pz);
+                    }
+                    break;
+                }
+                case "pointer_move":
+                case "pointer_click":
+                case "pointer_down":
+                case "pointer_up":
+                    options.onPointer?.(event.screen, event.hitPoint, event.hitMesh, event.type);
+                    break;
+                case "mesh_interaction":
+                    options.onMeshInteraction?.(event.mesh, event.kind, event.point);
+                    break;
+                case "custom":
+                    options.onCustom?.(event.name, event.props, event.ts);
+                    break;
+                case "input_action":
+                    options.onInputAction?.({
+                        action: event.action,
+                        code: event.code,
+                        button: event.button,
+                        pressed: event.pressed,
+                        source: event.source,
+                    }, event.ts);
+                    break;
+                case "viewport_resize":
+                    options.onLifecycle?.({ type: "viewport_resize", width: event.width, height: event.height, dpr: event.dpr }, event.ts);
+                    break;
+                case "visibility_change":
+                    options.onLifecycle?.({ type: "visibility_change", state: event.state }, event.ts);
+                    break;
+                case "focus_change":
+                    options.onLifecycle?.({ type: "focus_change", focused: event.focused }, event.ts);
+                    break;
+                case "context_lost":
+                    options.onLifecycle?.({ type: "context_lost" }, event.ts);
+                    break;
+                case "context_restored":
+                    options.onLifecycle?.({ type: "context_restored" }, event.ts);
+                    break;
+                case "runtime_error":
+                    options.onError?.({
+                        kind: event.kind,
+                        message: event.message,
+                        source: event.source,
+                        lineno: event.lineno,
+                        colno: event.colno,
+                        stack: event.stack,
+                    }, event.ts);
+                    break;
+                case "camera_gesture":
+                    // Derived navigation annotation (ADR 0025); the camera trajectory is
+                    // reconstructed from camera_sample, so replay intentionally ignores it.
+                    break;
+                case "node_transform": {
+                    const node = resolveReplayNode(options.nodes?.[event.nodeId]);
+                    if (node) {
+                        if (event.boneId !== undefined) {
+                            // Tier 2: drive the matching skeleton bone's LOCAL pose.
+                            const bone = node.skeleton?.bones?.find((b) => b.name === event.boneId);
+                            if (bone) {
+                                bone.position?.set(event.position[0], event.position[1], event.position[2]);
+                                bone.rotationQuaternion = new Quaternion(event.rotation[0], event.rotation[1], event.rotation[2], event.rotation[3]);
+                                if (event.scale) {
+                                    bone.scaling?.set(event.scale[0], event.scale[1], event.scale[2]);
+                                }
+                                bone.markAsDirty?.();
+                            }
+                        }
+                        else {
+                            // Tier 1: the declared root (no childPath) or a subtree child resolved
+                            // by its relative path (ADR 0033). Both carry a world-frame pose;
+                            // `setAbsolutePosition` honours any parent, a plain root falls back
+                            // to `position`.
+                            const target = event.childPath === undefined ? node : resolveChildByPath(node, event.childPath);
+                            if (target) {
+                                if (typeof target.setAbsolutePosition === "function") {
+                                    nodePosition.set(event.position[0], event.position[1], event.position[2]);
+                                    target.setAbsolutePosition(nodePosition);
+                                }
+                                else {
+                                    target.position?.set(event.position[0], event.position[1], event.position[2]);
+                                }
+                                // Babylon ignores `rotation` (Euler) once a quaternion is present;
+                                // assign a fresh one so the world orientation is applied verbatim.
+                                target.rotationQuaternion = new Quaternion(event.rotation[0], event.rotation[1], event.rotation[2], event.rotation[3]);
+                                if (event.scale) {
+                                    target.scaling?.set(event.scale[0], event.scale[1], event.scale[2]);
+                                }
+                            }
+                        }
+                    }
+                    options.onNodeTransform?.(event.nodeId, {
+                        boneId: event.boneId,
+                        childPath: event.childPath,
+                        position: event.position,
+                        rotation: event.rotation,
+                        scale: event.scale,
+                    }, event.ts);
+                    break;
+                }
+                default:
+                    break;
+            }
+        },
+    };
+}
+//# sourceMappingURL=babylon.js.map

package/dist/drivers/babylon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"babylon.js","sourceRoot":"","sources":["../../src/drivers/babylon.ts"],"names":[],"mappings":"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"}

package/dist/drivers/playcanvas.d.ts

@@ -0,0 +1,122 @@
+import type { CustomPropValue } from "@uptimizr/schema";
+import type { ReplayDriver } from "../types.js";
+/**
+ * Structural view of the PlayCanvas objects this driver writes to. Kept minimal and
+ * structural so `playcanvas` stays an **optional peer dependency** — the driver
+ * never imports PlayCanvas at runtime; the host page owns the app and the real
+ * Entity.
+ */
+interface PlayCanvasReplayCamera {
+    /** `Entity.setPosition(x, y, z)` — world-space move. */
+    setPosition(x: number, y: number, z: number): void;
+    /** `Entity.lookAt(x, y, z)` — orients the entity's forward axis at the point. */
+    lookAt(x: number, y: number, z: number): void;
+    /** The camera component; `fov` is the vertical FOV in **degrees** (PlayCanvas). */
+    camera?: {
+        fov?: number;
+    };
+}
+/** A PlayCanvas node a replay can drive (an `Entity`). */
+export type PlayCanvasReplayNode = object;
+export interface PlayCanvasReplayDriverOptions {
+    /**
+     * Camera Entity to move. PlayCanvas has no single active camera, so the one to
+     * re-drive is required. (Read/write only — the driver never emits analytics.)
+     */
+    camera: PlayCanvasReplayCamera;
+    /** Called for each replayed pointer event, so the host can render a marker. */
+    onPointer?: (screen: [number, number] | undefined, hitPoint: [number, number, number] | undefined, hitMesh: string | undefined, type: "pointer_move" | "pointer_click" | "pointer_down" | "pointer_up") => void;
+    /** Called for each replayed mesh interaction, so the host can highlight it. */
+    onMeshInteraction?: (mesh: string, kind: string, point: [number, number, number] | undefined) => void;
+    /**
+     * Scene-actor resolvers for `node_transform` drive-back (ADR 0027). Maps a
+     * recorded `nodeId` to the live PlayCanvas `Entity` to re-drive — a direct
+     * reference or a `() => entity` resolver. Tier-1 (world-frame) samples are
+     * converted canonical → PlayCanvas and applied via `setPosition`/`setRotation`.
+     * Tier-2 bone samples drive the matching named bone of the entity's skin in its
+     * local frame; every sample is also forwarded via {@link onNodeTransform}.
+     */
+    nodes?: Record<string, PlayCanvasReplayNode | (() => PlayCanvasReplayNode | null | undefined)>;
+    /**
+     * Called for **every** replayed `node_transform` (Tier 1 and Tier 2), after any
+     * node drive-back. The position/rotation are converted into PlayCanvas'
+     * right-handed frame; `boneId` is set for Tier-2 samples.
+     */
+    onNodeTransform?: (nodeId: string, transform: {
+        boneId: string | undefined;
+        childPath: string | undefined;
+        position: [number, number, number];
+        rotation: [number, number, number, number];
+        scale: [number, number, number] | undefined;
+    }, ts: number) => void;
+    /**
+     * Called for each replayed developer-defined `custom` event. The driver can't
+     * know how to render an arbitrary domain event, so it forwards the name, props,
+     * and timestamp for the host to visualize (marker, toast, log, ...).
+     */
+    onCustom?: (name: string, props: Record<string, CustomPropValue> | undefined, ts: number) => void;
+    /**
+     * Called for each replayed `input_action` (discrete keyboard/gamepad action,
+     * ADR 0023). Forwarded with the action, raw `code`/`button`, source, and
+     * timestamp so a replay UI can annotate the timeline.
+     */
+    onInputAction?: (input: {
+        action: string;
+        code: string | undefined;
+        button: number | undefined;
+        pressed: boolean | undefined;
+        source: string | undefined;
+    }, ts: number) => void;
+    /**
+     * Called for each replayed browser/engine lifecycle event (viewport resize, tab
+     * visibility, window focus, GPU context loss/restore). The driver doesn't
+     * re-drive these — it forwards them so a replay UI can annotate the timeline.
+     */
+    onLifecycle?: (event: {
+        type: "viewport_resize";
+        width: number;
+        height: number;
+        dpr: number | undefined;
+    } | {
+        type: "visibility_change";
+        state: "visible" | "hidden";
+    } | {
+        type: "focus_change";
+        focused: boolean;
+    } | {
+        type: "context_lost";
+    } | {
+        type: "context_restored";
+    }, ts: number) => void;
+    /**
+     * Called for each replayed `runtime_error` event (opt-in capture, ADR 0013).
+     * Forwarded so a replay UI can mark where a JS error or unhandled rejection
+     * interrupted the session.
+     */
+    onError?: (error: {
+        kind: "error" | "unhandledrejection";
+        message: string;
+        source: string | undefined;
+        lineno: number | undefined;
+        colno: number | undefined;
+        stack: string | undefined;
+    }, ts: number) => void;
+}
+/**
+ * PlayCanvas replay driver. Re-drives camera pose (and surfaces pointer/mesh events
+ * to host callbacks) in the user's own PlayCanvas app.
+ *
+ * ## Coordinate frame (canonical → PlayCanvas)
+ * Events arrive in the canonical **left-handed, y-up** frame (ADR 0018); PlayCanvas
+ * is **right-handed**, so world-space data is converted back with the shared
+ * `fromCanonical*` helpers (the Z-negation reflection is its own inverse). Camera
+ * orientation is applied via `camera.lookAt(target)` — `lookAt` resolves
+ * PlayCanvas' forward-axis convention internally, so the driver does **not**
+ * re-derive a forward axis from the recorded direction (avoiding the orientation
+ * trap documented in sdk-core `coordinates.ts`).
+ *
+ * It only reads/writes the scene — it never emits analytics events (ADR 0006).
+ */
+export declare function createPlayCanvasReplayDriver(options: PlayCanvasReplayDriverOptions): ReplayDriver;
+export {};
+//# sourceMappingURL=playcanvas.d.ts.map

package/dist/drivers/playcanvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playcanvas.d.ts","sourceRoot":"","sources":["../../src/drivers/playcanvas.ts"],"names":[],"mappings":"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"}

package/dist/drivers/playcanvas.js

@@ -0,0 +1,206 @@
+import { fromCanonicalDirection, fromCanonicalPosition, fromCanonicalQuat, } from "@uptimizr/sdk-core";
+/** Find a skeleton bone of `entity` by name across its mesh-instance skins, or `null`. */
+function findEntityBone(entity, boneId) {
+    const instances = [
+        ...(entity.render?.meshInstances ?? []),
+        ...(entity.model?.meshInstances ?? []),
+    ];
+    for (const mi of instances) {
+        const bone = mi.skinInstance?.bones?.find((b) => b?.name === boneId);
+        if (bone)
+            return bone;
+    }
+    return null;
+}
+/** Resolve a node entry (direct ref or `() => node`) to a live Entity, or `null`. */
+function resolveReplayNode(entry) {
+    if (!entry)
+        return null;
+    if (typeof entry === "function") {
+        return entry() ?? null;
+    }
+    return entry;
+}
+/**
+ * Walk a `/`-separated {@link NodeTransformEvent.childPath} from a resolved root
+ * actor to the descendant entity, matching each segment against direct children
+ * by `name` (ADR 0033). Returns `null` if any segment is missing.
+ */
+function resolveChildByPath(root, childPath) {
+    let cur = root;
+    for (const segment of childPath.split("/")) {
+        if (!segment)
+            continue;
+        const children = cur?.children;
+        if (!Array.isArray(children))
+            return null;
+        cur = children.find((c) => c.name === segment) ?? null;
+        if (!cur)
+            return null;
+    }
+    return cur;
+}
+/**
+ * PlayCanvas replay driver. Re-drives camera pose (and surfaces pointer/mesh events
+ * to host callbacks) in the user's own PlayCanvas app.
+ *
+ * ## Coordinate frame (canonical → PlayCanvas)
+ * Events arrive in the canonical **left-handed, y-up** frame (ADR 0018); PlayCanvas
+ * is **right-handed**, so world-space data is converted back with the shared
+ * `fromCanonical*` helpers (the Z-negation reflection is its own inverse). Camera
+ * orientation is applied via `camera.lookAt(target)` — `lookAt` resolves
+ * PlayCanvas' forward-axis convention internally, so the driver does **not**
+ * re-derive a forward axis from the recorded direction (avoiding the orientation
+ * trap documented in sdk-core `coordinates.ts`).
+ *
+ * It only reads/writes the scene — it never emits analytics events (ADR 0006).
+ */
+export function createPlayCanvasReplayDriver(options) {
+    return {
+        reset() {
+            // Camera state is fully determined by the next camera_sample, so there is
+            // nothing to restore; host-rendered markers are the host's responsibility.
+        },
+        apply(event) {
+            switch (event.type) {
+                case "camera_sample": {
+                    const cam = options.camera;
+                    if (!cam)
+                        return;
+                    // Position: canonical → PlayCanvas (Z-negated).
+                    const [px, py, pz] = fromCanonicalPosition(event.position, "right");
+                    cam.setPosition(px, py, pz);
+                    // Look target: an explicit recorded target, else position + direction —
+                    // both converted to PlayCanvas' frame. lookAt handles the forward axis.
+                    let tx;
+                    let ty;
+                    let tz;
+                    if (event.target) {
+                        [tx, ty, tz] = fromCanonicalPosition(event.target, "right");
+                    }
+                    else {
+                        const [dx, dy, dz] = fromCanonicalDirection(event.direction, "right");
+                        tx = px + dx;
+                        ty = py + dy;
+                        tz = pz + dz;
+                    }
+                    cam.lookAt(tx, ty, tz);
+                    // PlayCanvas' camera FOV is in degrees; the wire carries radians.
+                    if (cam.camera && typeof event.fov === "number") {
+                        cam.camera.fov = (event.fov * 180) / Math.PI;
+                    }
+                    break;
+                }
+                case "pointer_move":
+                case "pointer_click":
+                case "pointer_down":
+                case "pointer_up": {
+                    // Convert the world-space hit point back into PlayCanvas' frame so a host
+                    // marker lands correctly; screen coords are engine-independent.
+                    const hitPoint = event.hitPoint
+                        ? fromCanonicalPosition(event.hitPoint, "right")
+                        : undefined;
+                    options.onPointer?.(event.screen, hitPoint, event.hitMesh, event.type);
+                    break;
+                }
+                case "mesh_interaction": {
+                    const point = event.point ? fromCanonicalPosition(event.point, "right") : undefined;
+                    options.onMeshInteraction?.(event.mesh, event.kind, point);
+                    break;
+                }
+                case "custom":
+                    options.onCustom?.(event.name, event.props, event.ts);
+                    break;
+                case "input_action":
+                    options.onInputAction?.({
+                        action: event.action,
+                        code: event.code,
+                        button: event.button,
+                        pressed: event.pressed,
+                        source: event.source,
+                    }, event.ts);
+                    break;
+                case "viewport_resize":
+                    options.onLifecycle?.({ type: "viewport_resize", width: event.width, height: event.height, dpr: event.dpr }, event.ts);
+                    break;
+                case "visibility_change":
+                    options.onLifecycle?.({ type: "visibility_change", state: event.state }, event.ts);
+                    break;
+                case "focus_change":
+                    options.onLifecycle?.({ type: "focus_change", focused: event.focused }, event.ts);
+                    break;
+                case "context_lost":
+                    options.onLifecycle?.({ type: "context_lost" }, event.ts);
+                    break;
+                case "context_restored":
+                    options.onLifecycle?.({ type: "context_restored" }, event.ts);
+                    break;
+                case "runtime_error":
+                    options.onError?.({
+                        kind: event.kind,
+                        message: event.message,
+                        source: event.source,
+                        lineno: event.lineno,
+                        colno: event.colno,
+                        stack: event.stack,
+                    }, event.ts);
+                    break;
+                case "camera_gesture":
+                    // Derived navigation annotation (ADR 0025); the camera trajectory is
+                    // reconstructed from camera_sample, so replay intentionally ignores it.
+                    break;
+                case "node_transform": {
+                    const node = resolveReplayNode(options.nodes?.[event.nodeId]);
+                    if (node) {
+                        if (event.boneId !== undefined) {
+                            // Tier 2: drive the named bone's parent-relative LOCAL pose. The
+                            // canonical reflection conjugates a local transform the same way it
+                            // does a world one, so the same convert applies (ADR 0027).
+                            const bone = findEntityBone(node, event.boneId);
+                            if (bone) {
+                                const [px, py, pz] = fromCanonicalPosition(event.position, "right");
+                                bone.setLocalPosition?.(px, py, pz);
+                                const [qx, qy, qz, qw] = fromCanonicalQuat(event.rotation, "right");
+                                bone.setLocalRotation?.(qx, qy, qz, qw);
+                                if (event.scale) {
+                                    bone.setLocalScale?.(event.scale[0], event.scale[1], event.scale[2]);
+                                }
+                            }
+                        }
+                        else {
+                            // Tier 1: the declared root (no childPath) or a subtree child resolved
+                            // by its relative path (ADR 0033). Both carry a world-frame pose;
+                            // `setPosition`/`setRotation` are world setters, correct for either.
+                            const target = event.childPath === undefined ? node : resolveChildByPath(node, event.childPath);
+                            if (target) {
+                                const [px, py, pz] = fromCanonicalPosition(event.position, "right");
+                                target.setPosition?.(px, py, pz);
+                                const [qx, qy, qz, qw] = fromCanonicalQuat(event.rotation, "right");
+                                target.setRotation?.(qx, qy, qz, qw);
+                                if (event.scale) {
+                                    target.setLocalScale?.(event.scale[0], event.scale[1], event.scale[2]);
+                                }
+                            }
+                        }
+                    }
+                    // Forward the (frame-converted) sample so the host can render a proxy
+                    // marker or annotate the timeline; `boneId` is set for Tier-2 samples,
+                    // `childPath` for Tier-1 subtree children (ADR 0033).
+                    const fwdPos = fromCanonicalPosition(event.position, "right");
+                    const fwdRot = fromCanonicalQuat(event.rotation, "right");
+                    options.onNodeTransform?.(event.nodeId, {
+                        boneId: event.boneId,
+                        childPath: event.childPath,
+                        position: fwdPos,
+                        rotation: fwdRot,
+                        scale: event.scale,
+                    }, event.ts);
+                    break;
+                }
+                default:
+                    break;
+            }
+        },
+    };
+}
+//# sourceMappingURL=playcanvas.js.map