feat: BasisAuthoredMotion — batched authored-motion driver for cosmetic/secondary motion (#832)

## Summary
Replaces per-avatar cosmetic/secondary Animators with a batched,
Burst-compiled authored-motion system. A single cosmetic Unity Animator
on the reference avatar measured at roughly **1/5 of scene frame time at
1000 CCU** — almost entirely fixed per-instance Animator overhead, paid
on every replicated copy. This moves that motion into one job over all
avatars.

- **`BasisAuthoredMotion`** (SDK, data-only): a Content-Police-allowed
component holding a list of reusable `Movement`s — no per-instance
`Update`.
- **`BasisAuthoredMotionSystem`** (framework): a static orchestrator +
one Burst `IJobParallelForTransform` over every registered avatar's
driven transforms, a sibling to `RemoteBoneJobSystem`. Registered at
local/remote calibration; pumped from `BasisEventDriver.LateUpdate`
immediately before the jiggle pass, so authored motion is the animated
base and jiggle layers on top.
- **Six movement kinds:** Oscillate (sine/triangle/square/pulse, incl.
chain travelling waves), Rotate, Orbit, Noise, RandomSelect (weighted
random poses, multi-target + idle), Sequence (baked-clip playback).
- **Authoring:** a per-Kind custom inspector (shows only the relevant
fields, localized tooltips) and `BasisMotionClipBaker`, an editor window
that bakes an `AnimationClip` into a shared `BasisMotionClip` for
Sequence.

It drives only non-humanoid transforms (tails, ears, accessories) that
the networked skeleton and IK don't touch, so there's no write
contention with the bone pipeline.

## Required checks
All boxes below must be ticked before this PR can merge. If a check is
genuinely N/A, tick it anyway and explain under **Notes**.

<!-- required-checks-start -->
<!-- Tick the boxes in place — do not edit the line text. The
pr-checklist workflow parses this block; per-PR context goes under
Notes. -->
- [x] **Tested** — I built and ran this locally. The change works in the
editor and (where relevant) in a built player.
- [x] **Transform access is combined and limited** — In hot paths,
transform reads/writes go through `TransformAccessArray` or are
otherwise batched. I have not added per-frame `transform.position` /
`transform.rotation` / `transform.localPosition` calls inside loops.
Whenever I need both position and rotation, I use the combined APIs —
`SetPositionAndRotation` / `SetLocalPositionAndRotation` for writes,
`GetPositionAndRotation` / `GetLocalPositionAndRotation` for reads —
instead of two separate property accesses; the combined call does one
local-to-world matrix traversal instead of two.
- [x] **Addressables used for asset/memory loading** — Any new asset
loads go through Addressables. No new `Resources.Load`, no direct asset
references that pull large content into memory on scene load.
- [x] **No new `GetComponent` / `AddComponent` where avoidable** — Where
unavoidable, the result is cached on a field, and any `GetComponent<T>`
is replaced with `TryGetComponent<T>(out var x)` — bare `GetComponent`
will be denied. `TryGetComponent` is the modern API (Unity 2019.2+) and
skips the Editor-only GC allocation `GetComponent` causes when a
component is missing: Unity wraps the `null` return in a managed "fake
null" object so its overloaded `==` operator can still detect destroyed
C++ objects, and constructing that wrapper allocates; `TryGetComponent`
returns a `bool` plus `out` parameter and never builds the wrapper. None
of these calls run inside `Update`, `LateUpdate`, `FixedUpdate`, jobs,
or other per-frame code paths.
- [x] **Per-frame work is scheduled through `BasisEventDriver`** — Any
new per-frame work hooks into `BasisEventDriver` rather than adding
standalone `Update` / `LateUpdate` / `FixedUpdate` callbacks on a
MonoBehaviour.
- [x] **Considered jobification** — I asked whether this work can be
moved to a Unity Job (Burst-compiled where possible). If it can, it is.
If it cannot, the reason is in **Notes**.
- [x] **No needless `{ get; set; }` properties or access lockdowns** —
Public fields are fine; Basis is meant to be read and modified freely,
so don't wall things off `private`/`internal` without a real reason.
Don't wrap a field in `{ get; set; }` when the accessors do nothing —
property accessors have a real performance cost vs direct field access,
and the lead maintainer prefers plain fields (or a method / setter-only
property when only the setter needs logic) over a noop-getter pair. For
`.Instance` singletons, callers reassigning `Type.Instance` is allowed;
if that would break your code, log a warning or throw — don't block the
assignment. Locking down access is not your call.
- [x] **Camera access goes through `BasisLocalCameraDriver`** — Code
that needs the local camera (transform, projection, rig data, etc.)
pulls it from `BasisLocalCameraDriver` rather than looking one up
itself. Don't roll a separate camera discovery path.
- [x] **Logging uses `BasisDebug`** — All new logging calls go through
`BasisDebug.Log` / `BasisDebug.LogWarning` / `BasisDebug.LogError` (with
an appropriate `LogTag`) instead of `UnityEngine.Debug.Log` /
`Debug.LogWarning` / `Debug.LogError`. `BasisDebug` routes through
Basis's tagged, color-coded logger and respects the project-wide
`LoggingDisabled` toggle so logging can be killed at runtime; bare
`Debug.Log` calls bypass that and will be denied.
- [x] **No scene-wide discovery for dependencies** — New code is
architected so it does not need `FindObjectOfType` / `FindObjectsOfType`
/ `GameObject.Find` / `FindGameObjectsWithTag` to locate what it depends
on. References are wired in — registered through an existing
manager/driver, injected at init, or passed in by the caller — rather
than discovered by scanning the scene at runtime. If a scene scan is
genuinely unavoidable, justify it under **Notes**.
- [x] **No allocations in hot paths** — Per-frame code (Update /
LateUpdate / FixedUpdate, simulation loops, jobs, anything called once
per frame or more) does not allocate. No `new` on reference types, no
LINQ, no `string` concatenation/interpolation, no boxing, no `foreach`
over interface-typed collections. Allocate once at init and reuse the
buffer.
- [x] **No debugging in hot paths** — No log calls of any kind on
per-frame paths, including `BasisDebug`. Hot-path logging floods the
console and incurs cost on every frame regardless of whether the message
is filtered out downstream. If a hot-path log is needed while iterating,
gate it behind `#if UNITY_EDITOR` and remove (or leave gated) before
merge.
- [x] **Hot-path collection access is optimized** — Cache `.Count`
(lists) / `.Length` (arrays) into a local `int` before the loop instead
of re-reading the property each iteration. Prefer `T[]` (with a separate
length int when the array is over-sized) over `List<T>` where the data
is hot — Unity's mono BCL doesn't expose
`CollectionsMarshal.AsSpan(List<T>)`, so a list can't be fed into
`Span<T>` / unsafe paths cleanly. Where the perf justifies it, drop into
`Span<T>` / `ref` locals / `Unsafe.As` / `unsafe` pointer code to skip
bounds checks and copies, and call out the invariants you're relying on
under **Notes** so reviewers can sanity-check them.
<!-- required-checks-end -->

## Testing details
Tick the platforms you actually tested on. Leave the rest unticked —
these are informational and do not block merge.

- [x] Windows
- [ ] Linux
- [ ] Android
- [ ] iOS
- [ ] macOS

Input / control mode coverage:

- [ ] Tested in VR (note headset under **Notes**)
- [x] Tested in desktop / non-VR mode
- [ ] Tested with phone controls (mobile touch input)
- [ ] N/A — change does not touch player/XR/input code

Where applicable, confirm these flows still work after your changes:

- [ ] Hot-switching (desktop ↔ VR mode swap at runtime)
- [ ] Avatar swapping
- [ ] Server swapping (joining / leaving / changing servers)
- [ ] N/A — change does not touch any of the above

## Notes
- **Draft because the perf acceptance bar isn't met yet.** Validated
functionally in-editor (SDK *Test In Editor*) on the reference avatar —
tail wag (baked Sequence) with jiggle layering on top, ear twitch
(multi-target RandomSelect), Oscillate and Rotate. The **1000-CCU load
test** (the whole point — beating the ~1/5-frame-time Animator baseline)
and **built-player** runs are still outstanding.
- **Addressables / Camera boxes are N/A** — the feature loads no assets
at runtime and uses no camera.
- **Component lookup** is a single
`GetComponentsInChildren<BasisAuthoredMotion>` at calibration (gathering
all components on the avatar), never per-frame; no bare `GetComponent`.
- **Allocations** — `Build`/`Rebuild` allocate (managed lists,
flattening config into the SoA) but run only on a structural change at
calibration; the per-frame `Schedule` and the Burst job are
allocation-free.
- **`transform.Find`** — `Sequence` binds a baked clip's transform paths
to bones via `root.Find(path)` **once at registration**, cached into the
`TransformAccessArray` (never per-frame), mirroring how an
`AnimationClip` binds its curves by path. It isn't in checkbox 10's
denial list, but flagging it since STYLE.md mentions `transform.Find`:
this is a scoped, one-shot bind, not scene-wide discovery.
- **Determinism / follow-up** — `RandomSelect` picks and `Sequence`
playheads currently derive from `Time.timeAsDouble`. A shared/networked
clock is needed for bit-identical playback across clients before
multiplayer; tracked as a follow-up. `RandomSelect.preventRepeats` is
serialized but not yet honored by the deterministic picker.
- **Critical-flow boxes left unticked**: avatar-swap re-registration is
wired through the calibration hooks but not yet stress-tested.

## Usage
**On an avatar:** add a `BasisAuthoredMotion` component
(Content-Police-allowed) and one or more **Movements**, each with a
**Kind**:
- **Oscillate** — periodic sway on a bone chain (`axis`, `amplitude`,
`frequencyHz`, `waveform`; one chain entry = a simple sway, multiple = a
travelling wave down the chain).
- **Rotate** — constant spin in place (`target`, `axis`, `speedDeg` in
deg/sec).
- **Orbit** — revolve a `target` around a `pivot` at a `radius`.
- **Noise** — organic simplex drift on a channel.
- **RandomSelect** — on a fixed interval (`intervalRange.x`), pick one
weighted pose `Option`; each option can drive its own bone (or fall back
to `selectTarget`), with an `idleWeight` for the "do nothing" outcome.
Good for ear flicks / blinks.
- **Sequence** — play a baked clip (below).

**Baking a Sequence clip:** `Basis ▸ Authored Motion ▸ Bake Clip` →
choose the source `AnimationClip` and the avatar root → it writes a
shared `BasisMotionClip`. Assign that to the Sequence movement's **Baked
Clip** and set **Sequence Root** to the same root the paths were baked
against.

**Toggling:** a movement group rides the component's own `enabled` — any
toggle system that flips `Behaviour.enabled` (e.g. an HVR.Vixxy
activation) turns it on/off, with no per-frame polling.

**Jiggle:** authored motion writes before the jiggle pass each frame, so
`JiggleRig` physics layers on top of it automatically.

Author: dooly123

Basis/Packages/com.basis.eventdriver/BasisEventDriver.cs

@@ -119,6 +119,7 @@ public void OnDestroy()
             BasisObjectSyncDriver.OnDestroy();
             Application.onBeforeRender -= OnBeforeRender;
             RemoteBoneJobSystem.Dispose();
+            BasisAuthoredMotionSystem.Dispose();
             BasisAvatarBufferPool.Deinitialize();
         }
 
@@ -310,6 +311,9 @@ public void LateUpdate()
             }
             ProfileEnd(PROF_BLENDSHAPE_APPLY);
 
+            // ── Authored motion: write non-humanoid authored bones before jiggle samples them ──
+            BasisAuthoredMotionSystem.Complete(BasisAuthoredMotionSystem.Schedule());
+
             // ── JigglePhysics schedule ──
             ProfileBegin(PROF_JIGGLE_SCHEDULE);
 

Basis/Packages/com.basis.framework/Drivers/AuthoredMotion.meta

@@ -149,6 +149,13 @@ public void InitialLocalCalibration(BasisLocalPlayer player, List<BasisHeadChop.
                 Rig.OnInitialize();
             }
 
+            // Register authored motion (drives non-humanoid transforms IK doesn't touch); rest captured at the current TPose.
+            var authoredMotions = player.BasisAvatar.GetComponentsInChildren<BasisAuthoredMotion>(true);
+            for (int i = 0; i < authoredMotions.Length; i++)
+            {
+                BasisAuthoredMotionSystem.Register(authoredMotions[i]);
+            }
+
             player.LocalRigDriver.Builder = BasisHelpers.GetOrAddComponent<RigBuilder>(AvatarAnimatorParent);
             player.LocalRigDriver.Builder.enabled = false;
 

Basis/Packages/com.basis.framework/Drivers/AuthoredMotion/BasisAuthoredMotionSystem.cs

@@ -138,6 +138,13 @@ public void RemoteCalibration(BasisRemotePlayer RemotePlayer)
                 Rig.OnInitialize();
             }
 
+            // Register authored motion (drives non-humanoid transforms the bone job / IK don't touch); rest captured at the current TPose.
+            var authoredMotions = RemotePlayer.BasisAvatar.GetComponentsInChildren<BasisAuthoredMotion>(true);
+            for (int i = 0; i < authoredMotions.Length; i++)
+            {
+                BasisAuthoredMotionSystem.Register(authoredMotions[i]);
+            }
+
             // Face visibility setup
             Player.FaceIsVisible = false;
             if (RemotePlayer.BasisAvatar == null)

Basis/Packages/com.basis.framework/Drivers/AuthoredMotion/BasisAuthoredMotionSystem.cs.meta

@@ -529,6 +529,17 @@ public void OnDestroy()
 
             OnRemotePlayerDestroying?.Invoke();
 
+            // Unregister authored motion while the avatar transforms are still alive, so the
+            // TransformAccessArray entries drop cleanly before Unity destroys them.
+            if (BasisAvatar != null)
+            {
+                var authoredMotions = BasisAvatar.GetComponentsInChildren<BasisAuthoredMotion>(true);
+                for (int i = 0; i < authoredMotions.Length; i++)
+                {
+                    BasisAuthoredMotionSystem.Unregister(authoredMotions[i]);
+                }
+            }
+
             RemoveFromBoneDriver();
         }
 

Basis/Packages/com.basis.framework/Drivers/Local/BasisLocalAvatarDriver.cs

@@ -193,6 +193,75 @@
     { "key": "sdk.parameterDriver.field.destMin", "value": "Dest Min" },
     { "key": "sdk.parameterDriver.field.destMax", "value": "Dest Max" },
 
+    { "key": "sdk.authoredMotion.movements.header", "value": "Movements  ({0})" },
+    { "key": "sdk.authoredMotion.movements.empty", "value": "No movements — click '+ Add Movement' below." },
+    { "key": "sdk.authoredMotion.movements.add", "value": "+ Add Movement" },
+    { "key": "sdk.authoredMotion.label.placeholder", "value": "<movement>" },
+    { "key": "sdk.authoredMotion.field.kind.label", "value": "Kind" },
+    { "key": "sdk.authoredMotion.field.kind.tooltip", "value": "Which authored-motion primitive this entry drives. The fields below change to match the kind." },
+    { "key": "sdk.authoredMotion.field.label.label", "value": "Label" },
+    { "key": "sdk.authoredMotion.field.label.tooltip", "value": "Author-facing identifier only; has no runtime effect." },
+    { "key": "sdk.authoredMotion.field.enabled.label", "value": "Enabled" },
+    { "key": "sdk.authoredMotion.field.enabled.tooltip", "value": "Author default for this movement. The runtime on/off toggle rides the component's own enabled state." },
+    { "key": "sdk.authoredMotion.field.axis.label", "value": "Axis" },
+    { "key": "sdk.authoredMotion.field.axis.tooltip", "value": "Local axis the movement acts about." },
+    { "key": "sdk.authoredMotion.field.channel.label", "value": "Channel" },
+    { "key": "sdk.authoredMotion.field.channel.tooltip", "value": "What the value drives — Rotation (degrees), Position (metres) or Scale (factor)." },
+    { "key": "sdk.authoredMotion.field.waveform.label", "value": "Waveform" },
+    { "key": "sdk.authoredMotion.field.waveform.tooltip", "value": "Oscillation shape: Sine, Triangle, Square or Pulse." },
+    { "key": "sdk.authoredMotion.field.pulseWidth.label", "value": "Pulse Width" },
+    { "key": "sdk.authoredMotion.field.pulseWidth.tooltip", "value": "Duty cycle (0–1) for the Square and Pulse waveforms." },
+    { "key": "sdk.authoredMotion.field.amplitude.label", "value": "Amplitude" },
+    { "key": "sdk.authoredMotion.field.amplitude.tooltip", "value": "Peak deviation from rest. Units follow Channel: degrees, metres or scale-factor." },
+    { "key": "sdk.authoredMotion.field.frequencyHz.label", "value": "Frequency (Hz)" },
+    { "key": "sdk.authoredMotion.field.frequencyHz.tooltip", "value": "Cycles per second." },
+    { "key": "sdk.authoredMotion.field.phase.label", "value": "Phase" },
+    { "key": "sdk.authoredMotion.field.phase.tooltip", "value": "Starting phase offset, in radians." },
+    { "key": "sdk.authoredMotion.field.chain.label", "value": "Chain" },
+    { "key": "sdk.authoredMotion.field.chain.tooltip", "value": "Transforms this movement drives. One entry is a simple sway on a single bone; multiple entries form a travelling wave down the chain. Oscillate and Noise are driven by this list — not by Target." },
+    { "key": "sdk.authoredMotion.field.chainPhaseStep.label", "value": "Chain Phase Step" },
+    { "key": "sdk.authoredMotion.field.chainPhaseStep.tooltip", "value": "Phase delay (radians) added per element down the chain — produces the travelling-wave look." },
+    { "key": "sdk.authoredMotion.field.chainFalloff.label", "value": "Chain Falloff" },
+    { "key": "sdk.authoredMotion.field.chainFalloff.tooltip", "value": "Amplitude multiplier applied per element down the chain (1 = no falloff)." },
+    { "key": "sdk.authoredMotion.field.target.label", "value": "Target" },
+    { "key": "sdk.authoredMotion.field.target.tooltip", "value": "Transform to drive. Used by Rotate and Orbit; Oscillate and Noise use Chain instead." },
+    { "key": "sdk.authoredMotion.field.speedDeg.label", "value": "Speed (deg/sec)" },
+    { "key": "sdk.authoredMotion.field.speedDeg.tooltip", "value": "Constant angular velocity about Axis, in degrees per second." },
+    { "key": "sdk.authoredMotion.field.pivot.label", "value": "Pivot" },
+    { "key": "sdk.authoredMotion.field.pivot.tooltip", "value": "Point the Target revolves around. Defaults to the Target's own position when unset." },
+    { "key": "sdk.authoredMotion.field.radius.label", "value": "Radius" },
+    { "key": "sdk.authoredMotion.field.radius.tooltip", "value": "Distance from the pivot, in metres." },
+    { "key": "sdk.authoredMotion.field.orbitSpeedDeg.label", "value": "Orbit Speed (deg/sec)" },
+    { "key": "sdk.authoredMotion.field.orbitSpeedDeg.tooltip", "value": "Revolution speed around the pivot, in degrees per second." },
+    { "key": "sdk.authoredMotion.field.selectTarget.label", "value": "Select Target" },
+    { "key": "sdk.authoredMotion.field.selectTarget.tooltip", "value": "Default target for options that don't set their own. Lets one component pose a single bone several ways, while options that name their own target can each drive a different bone." },
+    { "key": "sdk.authoredMotion.field.options.label", "value": "Options" },
+    { "key": "sdk.authoredMotion.field.options.tooltip", "value": "Weighted poses to pick between. Each option may target its own bone (falling back to Select Target) and is chosen in proportion to its weight." },
+    { "key": "sdk.authoredMotion.field.idleWeight.label", "value": "Idle Weight" },
+    { "key": "sdk.authoredMotion.field.idleWeight.tooltip", "value": "Relative weight of the 'pose nothing' outcome. Larger values make a rest cycle (all targets returning to rest) more likely than any single option." },
+    { "key": "sdk.authoredMotion.field.intervalRange.label", "value": "Interval Range" },
+    { "key": "sdk.authoredMotion.field.intervalRange.tooltip", "value": "Time between picks. The X value sets the fixed period in seconds; Y is reserved." },
+    { "key": "sdk.authoredMotion.field.attack.label", "value": "Attack" },
+    { "key": "sdk.authoredMotion.field.attack.tooltip", "value": "Ease-in time toward a newly chosen pose, in seconds." },
+    { "key": "sdk.authoredMotion.field.release.label", "value": "Release" },
+    { "key": "sdk.authoredMotion.field.release.tooltip", "value": "Ease-out time when a target returns to rest, in seconds." },
+    { "key": "sdk.authoredMotion.field.preventRepeats.label", "value": "Prevent Repeats" },
+    { "key": "sdk.authoredMotion.field.preventRepeats.tooltip", "value": "Avoid picking the same option twice in a row. Not yet honored by the deterministic picker." },
+    { "key": "sdk.authoredMotion.field.seed.label", "value": "Seed" },
+    { "key": "sdk.authoredMotion.field.seed.tooltip", "value": "Random seed for Noise and RandomSelect. 0 derives one from the registration index." },
+    { "key": "sdk.authoredMotion.field.noiseSpeed.label", "value": "Noise Speed" },
+    { "key": "sdk.authoredMotion.field.noiseSpeed.tooltip", "value": "How fast the simplex-noise field is sampled." },
+    { "key": "sdk.authoredMotion.field.sequenceTarget.label", "value": "Sequence Target" },
+    { "key": "sdk.authoredMotion.field.sequenceTarget.tooltip", "value": "Transform the timeline drives." },
+    { "key": "sdk.authoredMotion.field.sequenceRoot.label", "value": "Sequence Root" },
+    { "key": "sdk.authoredMotion.field.sequenceRoot.tooltip", "value": "The baked clip's transform paths resolve under this root (e.g. the avatar root the clip was authored against). Defaults to this component's transform when unset." },
+    { "key": "sdk.authoredMotion.field.bakedClip.label", "value": "Baked Clip" },
+    { "key": "sdk.authoredMotion.field.bakedClip.tooltip", "value": "Shared, read-only baked-curve asset produced by the clip baker. Drives every bone the source AnimationClip animated." },
+    { "key": "sdk.authoredMotion.field.keyframes.label", "value": "Keyframes" },
+    { "key": "sdk.authoredMotion.field.keyframes.tooltip", "value": "Inline pose-delta timeline for short motion. Ignored when a Baked Clip is assigned." },
+    { "key": "sdk.authoredMotion.field.loop.label", "value": "Loop" },
+    { "key": "sdk.authoredMotion.field.loop.tooltip", "value": "Loop the sequence, or play it once." },
+
     { "key": "sdk.buildReport.window.title", "value": "Basis Build Report Viewer" },
     { "key": "sdk.buildReport.window.tabTitle", "value": "Basis Bundle Report" },
     { "key": "sdk.buildReport.noDirectory", "value": "No build reports directory found." },

Basis/Packages/com.basis.framework/Drivers/Remote/BasisRemoteAvatarDriver.cs

@@ -92,6 +92,7 @@ public static string GetTagColor(LogTag logTag)
             LogTag.Shims => "#FF00FF",        // Magenta
             LogTag.Props => "#FFB6C1",        // Light Pink
             LogTag.LocalNetwork => "#ff0055",
+            LogTag.AuthoredMotion => "#BA55D3", // Medium Orchid
             _ => "#FFFFFF"                    // Default White
         };
     }
@@ -141,6 +142,7 @@ public enum LogTag
         Shims,
         Props,
         LocalNetwork,
+        AuthoredMotion,
     }
 
     public enum MessageType

Basis/Packages/com.basis.framework/Players/Remote/BasisRemotePlayer.cs

@@ -0,0 +1,111 @@
+using System;
+using UnityEngine;
+
+/// <summary>
+/// Data-only avatar component declaring authored, deterministic dynamic motion on transforms
+/// the humanoid rig and IK don't drive (tail/ear chains, accessories, etc.). It holds pure
+/// serialized configuration and runs no per-instance per-frame <c>Update</c> — all runtime
+/// evaluation happens in the batched <c>BasisAuthoredMotionSystem</c> job, which reads this
+/// component at calibration. The config model mirrors <see cref="BasisParameterDriver"/>'s
+/// <c>Operation[]</c> shape (an enum kind + per-kind fields).
+///
+/// Allow it onto an avatar by adding its type to the Content Police
+/// (<c>ContentPoliceSelector.selectedTypes</c> in <c>AvatarContentPoliceSelector.asset</c>).
+/// Group movements that toggle together into one component; an avatar may carry several.
+/// </summary>
+public class BasisAuthoredMotion : MonoBehaviour
+{
+    /// <summary>
+    /// Raised on enable/disable so a registered motion system can flip this component's slice
+    /// of its valid-mask without a per-frame poll. The system subscribes at registration; the
+    /// component holds no reference to any toggle package, so any actuator that flips
+    /// <see cref="Behaviour.enabled"/> (e.g. an HVR.Vixxy activation) drives it unchanged.
+    /// </summary>
+    public event Action<BasisAuthoredMotion, bool> EnabledStateChanged;
+
+    public Movement[] movements = Array.Empty<Movement>();
+
+    private void OnEnable() => EnabledStateChanged?.Invoke(this, true);
+    private void OnDisable() => EnabledStateChanged?.Invoke(this, false);
+
+    [Serializable]
+    public class Movement
+    {
+        // Open, extensible set — new kinds slot in without disturbing registration / scheduling / toggles.
+        public enum Kind { Oscillate, Rotate, Orbit, RandomSelect, Sequence, Noise }
+        public enum Channel { Rotation, Position, Scale }   // what Oscillate / Noise drive
+        public enum Waveform { Sine, Triangle, Square, Pulse }
+
+        public Kind kind = Kind.Oscillate;
+        public string label;              // author-facing identifier only
+        public bool enabled = true;       // author default; runtime toggle rides the component's own enabled
+        public Vector3 axis = Vector3.up; // local axis the movement acts about
+
+        // Oscillate — periodic motion on `channel`; a chain makes a travelling wave (1 entry = simple sway).
+        public Channel channel = Channel.Rotation; // amplitude unit: deg | metres | scale-factor
+        public Waveform waveform = Waveform.Sine;
+        public float pulseWidth = 0.5f;   // square/pulse duty cycle (0–1)
+        public Transform[] chain;
+        public float amplitude = 15f;
+        public float frequencyHz = 0.5f;
+        public float phase = 0f;
+        public float chainPhaseStep = 0f; // phase delay per element down the chain
+        public float chainFalloff = 1f;   // amplitude scale per element down the chain
+
+        // Rotate — constant angular velocity about `axis`, in place.
+        public Transform target;
+        public float speedDeg = 36f;      // deg/sec
+
+        // Orbit — revolve `target` around `pivot` at `radius` (not a spin-in-place).
+        public Transform pivot;
+        public float radius = 0.1f;
+        public float orbitSpeedDeg = 90f; // deg/sec around the pivot
+
+        // RandomSelect — every `intervalRange.x` seconds, deterministically pick one weighted option (or idle)
+        // and ease the target in/out. Each Option may set its own `target`, else falls back to `selectTarget`.
+        public Transform selectTarget;   // default target for options that leave their own target null
+        public Option[] options = Array.Empty<Option>();
+        public float idleWeight = 0f;     // relative weight of the "pose nothing" outcome
+        public Vector2 intervalRange = new Vector2(2f, 6f);  // x = fixed period (seconds between picks)
+        public float attack = 0.06f, release = 0.25f;        // ease in / out seconds
+        public bool preventRepeats = true;
+        public uint seed = 0;             // 0 = derive from registration index
+
+        // Sequence — authored timeline, loop or one-shot. A baked clip drives many bones via paths under
+        // `sequenceRoot`; inline keyframes (deferred) use `sequenceTarget`.
+        public Transform sequenceTarget; // single-bone inline-keyframe target (inline path; deferred)
+        public Transform sequenceRoot;   // baked-clip paths resolve under this (defaults to the avatar root)
+        public Keyframe[] keyframes = Array.Empty<Keyframe>();
+        public BasisMotionClip bakedClip; // shared baked curves; null when using inline keyframes
+        public bool loop = true;
+
+        // Noise — simplex drift on `channel` about `axis`; reuses amplitude / chain / chainFalloff / seed; `noiseSpeed` = sample rate.
+        public float noiseSpeed = 0.5f;
+    }
+
+    [Serializable]
+    public class Option
+    {
+        [Tooltip("Transform this option poses. Falls back to the movement's Select Target when null.")]
+        public Transform target;
+        [Tooltip("Local axis to rotate about.")]
+        public Vector3 axis = Vector3.up;
+        [Tooltip("Rotation applied about Axis when this option is selected, in degrees.")]
+        public float angleDeg;
+        [Tooltip("Relative likelihood this option is picked.")]
+        public float weight = 1f;
+    }
+
+    [Serializable]
+    public class Keyframe
+    {
+        [Tooltip("Time of this key, in seconds from the start of the sequence.")]
+        public float time;
+        [Tooltip("Rotation delta from rest at this key, in euler degrees.")]
+        public Vector3 eulerDelta;
+        [Tooltip("Local position delta from rest at this key.")]
+        public Vector3 positionDelta;
+        [Tooltip("Local scale delta from rest at this key.")]
+        public Vector3 scaleDelta;
+    }
+}