@rig-c/pose 0.5.0 → 0.7.0

package/README.md

@@ -45,15 +45,15 @@ and what the run cannot decide for you it lists:
 - `BEND` — with `--bends clamp`, a hinge bent the wrong way is straightened on that frame instead of refusing.
 - `FOLD` — `rigc render --folds` over the new animation: every mesh that folds, and when. A reading, not a gate.
 - `POSTURE` — when the map has a pelvis chain (joints `r_hip`, `l_hip`) and a `translate`: the hip line's tilt range, and the sway — the x-range of mid_hip − mid_shoulder — in rig units and in shoulder widths, the pose's beside the posed rig's. A reading, not a gate.
-- `SWITCH` — with `alternates` in the map ([below](#alternate-drawings-alternates)): each span on which a set of alternate drawings shows, its slots, its frames, how far the pose was from the set's key skeleton, and how far each bone with a `drawn` angle was turned from it.
+- `SWITCH` — with `alternates` in the map ([below](#alternate-drawings-alternates)): each span on which a set of alternate drawings shows, its slots, its frames, how far the pose was from the set's key skeleton, how far each bone with a `drawn` angle was turned from it, and where each of its boundaries was moved to (`moved`, [below](#alternate-drawings-alternates)).
 - `UNCOVERED` — with `alternates` in the map: every fold on a frame where no switch took the folding mesh off screen. This is the list of poses still to paint.
 - `RANGE` — a chain's `range` ([below](#a-joints-range-range)): a bone whose rotate key the pose asks past its range, outside every span of a set depicting its chain, is clamped at the limit; one line per run, with the frames, the seconds and the largest overflow. The demand for an alternate.
 - `ART-RANGE` — inside a set's span: a bone with a `drawn` angle in the set, turned from it past its limits — the set's `turn` for that bone (held at the limit) or, without one, its chain's `range` (the bone follows the pose). Listed as the pose asked it either way: the demand for another drawing of that set.
 - `TURN` — a line across the body (hips, shoulders, eyes) shorter in the picture than 0.5 of its median length, or reversed, for at least 0.15 s: the body or the head turned. A reading of the pose, made whether or not the map uses the line; it changes no key. The demand for a turned-body drawing, as `END-ON` is for a foreshortened limb.
 
-`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `options` (every figure the run used, `switchTolerance` and `switchMin` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate`, `landings`, `posture`, `folds`, and the demand lists:
+`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `options` (every figure the run used, `switchTolerance`, `switchMin` and `switchAt` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate`, `landings`, `posture`, `folds`, and the demand lists:
 
-- `switches: [{ set, chains, slots, hides, offsets, from, to, frames: [first, last], distance: { max, median }, artTurn: { <bone>: { max, median } } }]` — one per span shown; `from` is the first frame's time, `to` the time the base art comes back (the animation's end when the span runs to it), `distance` in degrees over the frames shown, `artTurn` |wrap(target − drawn)| in degrees per bone the set has a `drawn` angle for.
+- `switches: [{ set, chains, slots, hides, offsets, from, to, frames: [first, last], distance: { max, median }, artTurn: { <bone>: { max, median } }, moved: { on, off } }]` — one per span shown; `from` is the first frame's time, `to` the time the base art comes back (the animation's end when the span runs to it), `distance` in degrees over the frames shown, `artTurn` |wrap(target − drawn)| in degrees per bone the set has a `drawn` angle for. `moved.on` is the boundary the span starts on (null from the first frame), `moved.off` the one the base art or the next set comes back on (null to the end), each `{ frame: [selected, keyed], frames, seconds, window: [first, last], speed: { old, new } }`: signed frames and seconds, the frames it could move to, and the speed in degrees per frame on the old and the new frame. A boundary between two sets is the same entry in both.
 - `uncovered: [{ slot, attachment, chains, times }]` — every entry of `folds` on the times its slot still shows that mesh, with the map's chains that move it (the deepest: the arm, not the trunk it hangs from). `rigc render --folds` reads only what the pose shows, so a mesh swapped out or hidden by a switch is not read on those frames at all; `uncovered` is the fold times less the switched ones.
 - `endOn` — above, under the short hold.
 - `turns: [{ line, joints, frames, seconds, minFraction, reversed }]` — `line` is `hip`, `shoulder` or `eye`.
@@ -167,11 +167,19 @@ Bone rotation cannot carry every pose: an arm behind the head, a forearm toward
 
 **When one shows.** Per frame and per set, the distance is the largest difference, in degrees, between a segment of its chains as the retarget asked for it (after holds, smoothing, the short hold, the flip guard and the hinge check; before any range clamp) and the same segment in its key skeleton. On each frame the nearest set within `--switch-tolerance` (default 25°) shows, ties going to the map's order; a run of one set shorter than `--switch-min` (default 0.25 s) is dropped and the base art shows there. Both figures were fixed before a run ([#6](https://github.com/rig-c/pose/issues/6)). Sets compete only with those they share a slot (shown or hidden) or an offset bone with, so a drawing of each arm can show at once; two that compete never overlap.
 
+**Where a switch is keyed: `--switch-at`.** By default (`first`) a boundary — the frame a set starts showing on, and the frame the base art or the next set comes back on — is where the selection above puts it: the first frame within the tolerance, often a frame where the arm is slowing into the pose, so the change of drawing can be seen on a nearly still arm. `--switch-at peak` moves each boundary to the frame within ±`--switch-min`/2 (±3 frames at 24 fps with the default 0.25 s) where the chains it changes turn fastest, so the cut lands in motion ([#31](https://github.com/rig-c/pose/issues/31)). The speed on a frame is the largest |angular speed| in degrees per frame, a central difference of the target world angles (one-sided on the first and last frame), over every segment of the leaving set's and the arriving set's chains; it is read on the same targets as the distance, before the range clamp and any set's `turn`, which depend on where the spans are. The window is clipped so every span keeps `--switch-min`, a gap between two spans of one set keeps it too (the bridging holds), no boundary reaches its neighbour, and a set with `frames` shows only inside them. In it, a frame qualifies only if the set the move newly shows is within **2 × `--switch-tolerance`** of its key skeleton on every frame it newly shows it on; the boundary goes to the fastest qualifying frame, and stays when none qualifies. A tie goes to the frame nearest the original, then the earlier. A boundary between two sets moves once.
+
+The bound exists because speed alone rewarded showing art far from its pose. Unbounded, on HQ's dancer, the peak sat mid-swing: the largest distance over the frames a set showed rose from 25° to 135° (K2), 24° to 64° (K4), 21° to 59° (K1) and 21° to 38° (K3), the sets' `turn` held the arms hard against the pose (`ART-RANGE` runs 24 → 36), and the rig snapped to a hands-low drawing two frames before the arms came down. Bounded, every set stays within 50° (the largest is 43°, K4) and the median speed at the boundaries still rises from 9.7 to 14.2°/frame, but `ART-RANGE` runs still rise, 24 → 31 (K4 1 → 3, K1 6 → 8, K2 6 → 7, K3 2 → 4). That is why `first` is the default and `peak` an option ([#31](https://github.com/rig-c/pose/issues/31), round 2).
+
+Either way the `SWITCH` line ends with `moved on …, off …`: each boundary's old and new frame (the same under `first`), the frames and seconds it moved, the speed on both and its window, and the report carries the same under `moved`.
+
 **What is written.** An `attachment` track per slot whose picture changes: the set's attachment (or `null` for a hidden slot) where a span starts, and the slot's setup attachment, as the compiled model states it, where it ends. A direct switch from one set to another puts the first set's slots back to setup on the second's first frame, so an extra slot that is empty at setup goes empty. A switch onto frame *i* is keyed halfway between frames *i*−1 and *i*: a stepped key on the frame's own time fires a frame late wherever a player's accumulated time lands just below it (rig-c's docs/AUTHORING.md §4.5), and halfway both the pose's times and a renderer's `i / fps` see it on frame *i*. Before the first key a slot shows its setup attachment, so no key is written at 0 unless a span starts there. Offsets are `translate` keys at the same times, `stepped`. rig-c's gate checks these keys like any other.
 
 **TURN.** The cutoff was measured on the three lines across the body before it was fixed ([#6](https://github.com/rig-c/pose/issues/6)): on the 13 s front-facing dance their picture length never drops under 0.81 of its median and none reverses; on a second sequence the hip line falls to 0.17 at frames 465–491 (side-on) and the eye line to 0.22 at 26–58 (head in profile), and 3 frames reverse. 0.5 lies between. A line is reversed when it points more than 90° from the subject's right joint to the left (front-facing, it points at 0°). The lines are read after holds and smoothing, held and smoothed as the map's points are even where the map does not use them; a line whose points are good on no frame is named as not measured.
 
 
+**A stopgap window: `frames`.** A set may state `"frames": [[first, last], …]`: it shows only inside those windows, and on them it is chosen over any set within tolerance that has no window. It is for two sets whose key skeletons the angles cannot tell apart. Measured on HQ's dancer, the hands clasped behind the back and the hands low in front differ by only 2–21°, and the wrist and hand-point scores do not separate them either; the cue that might is #33's depth state. It is recorded in the map as a stopgap, not a selection rule.
+
 **How far a set's art may turn: `turn`.** A drawing reads right only near the angle it was painted at. A set may state, per bone with a `drawn` angle, how far its art may turn from it, `"turn": { "sleeve_r0": [-20, 20] }`. While the set shows, the bone is held within it: its target becomes drawn + clamp(wrap(target − drawn), min, max), each bone on its own world angle, so a forearm under a held upper arm keeps its own target. The landing check measures against the held angle. The overflow the pose asked for is listed as `ART-RANGE`. A `turn` on a bone the set has no `drawn` angle for is refused (`MAP_ALT_TURN`).
 ## Requirements
 

package/cli.ts

@@ -49,6 +49,10 @@ retarget
   --switch-tolerance <d>  a set of alternate drawings (the map's "alternates") may show on a frame where
                         every segment of its chains is within d degrees of its key skeleton (default: 25)
   --switch-min <s>      a run of one set shorter than s seconds is dropped (default: 0.25)
+  --switch-at first|peak  where a switch is keyed: first (default) keeps the frame the selection gave it;
+                        peak moves each boundary to the frame within ±switch-min/2 where the chains it
+                        changes turn fastest, among those that newly show a set only on frames within
+                        2 × the switch tolerance of its key skeleton (it stays when none qualifies)
   --profile spine|spine-html  rigc's gate profile (default: spine, rigc's own default)
   --build <dir>         keep the gated build (skeleton.json, .atlas, .model.json) here
   --render <dir>        keep rigc's render of the animation (frames, contact.png, folds.json) here
@@ -124,9 +128,11 @@ function shortOf(f: Map<string, string>): number | 'off' {
 }
 
 function retargetArgs(argv: string[]): RetargetArgs {
-  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'min-score', 'smooth', 'flip', 'short', 'bends', 'bend-tolerance', 'switch-tolerance', 'switch-min', 'profile', 'build', 'render', 'report'], ['coco']);
+  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'min-score', 'smooth', 'flip', 'short', 'bends', 'bend-tolerance', 'switch-tolerance', 'switch-min', 'switch-at', 'profile', 'build', 'render', 'report'], ['coco']);
   const bends = f.get('bends') ?? 'refuse';
   if (bends !== 'refuse' && bends !== 'clamp') throw new Usage(`--bends is "${bends}"; it must be refuse or clamp`);
+  const switchAt = f.get('switch-at') ?? 'first';
+  if (switchAt !== 'peak' && switchAt !== 'first') throw new Usage(`--switch-at is "${switchAt}"; it must be peak or first`);
   const profile = f.get('profile') ?? 'spine';
   if (profile !== 'spine' && profile !== 'spine-html') throw new Usage(`--profile is "${profile}"; it must be spine or spine-html`);
   const name = f.get('name') ?? 'dance';
@@ -148,6 +154,7 @@ function retargetArgs(argv: string[]): RetargetArgs {
     bendTolerance: num(f, 'bend-tolerance', 0, (n) => n >= 0 && n < 180, 'degrees in [0, 180)'),
     switchTolerance: num(f, 'switch-tolerance', 25, (n) => n >= 0 && n < 180, 'degrees in [0, 180)'),
     switchMin: num(f, 'switch-min', 0.25, (n) => n >= 0, 'seconds ≥ 0'),
+    switchAt,
     profile,
     build: f.get('build'),
     render: f.get('render'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Puts motion from a body-18 pose sequence onto a rig built with rig-c: bone keys in rig-c's motion format, checked through rig-c's gate before anything is written. A CLI for agents that cannot see the rig.",
   "type": "module",
   "bin": {

package/src/map.ts

@@ -93,6 +93,8 @@ export interface AlternateSet {
   offsets: Record<string, [number, number]>;
   /** Bone → how far its art may turn from `drawn` while the set shows, [min, max] degrees: the bone is clamped there, and the overflow is ART-RANGE demand. */
   turn: Record<string, [number, number]>;
+  /** A stopgap: the only frames the set may show on, a list of [first, last] windows; on them it is chosen over any set without windows. Null: any frame. */
+  frames: Array<[number, number]> | null;
 }
 export interface JointMap {
   chains: Chain[];
@@ -226,7 +228,7 @@ export function readMap(text: string, where: string): JointMap {
   return { chains, translate, alternates };
 }
 
-const SET_SHAPE = '{ name, slots: { "<slot>": "<attachment>" }, hides?: [slot], chains: [chain], pose: { "<joint>": [x, y] }, drawn?: { "<bone>": deg }, offsets?: { "<bone>": [dx, dy] }, turn?: { "<bone>": [min, max] } }';
+const SET_SHAPE = '{ name, slots: { "<slot>": "<attachment>" }, hides?: [slot], chains: [chain], pose: { "<joint>": [x, y] }, drawn?: { "<bone>": deg }, offsets?: { "<bone>": [dx, dy] }, turn?: { "<bone>": [min, max] }, frames?: [[first, last], …] }';
 
 /** `alternates`: each set's shape, its chains against the map's, its key skeleton against those chains' joints, and its bones against those chains' bones. */
 function readAlternates(p: Problems, where: string, raw: unknown, chains: readonly Chain[], translate: Translate | null): AlternateSet[] {
@@ -243,7 +245,7 @@ function readAlternates(p: Problems, where: string, raw: unknown, chains: readon
       p.add('MAP_ALT_SHAPE', `${aw} is ${typeName(a)}; a set is ${SET_SHAPE}`);
       return;
     }
-    refuseUnknownKeys(p, 'MAP_KEYS', aw, a, ['name', 'note', 'slots', 'hides', 'chains', 'pose', 'drawn', 'offsets', 'turn']);
+    refuseUnknownKeys(p, 'MAP_KEYS', aw, a, ['name', 'note', 'slots', 'hides', 'chains', 'pose', 'drawn', 'offsets', 'turn', 'frames']);
     const name = typeof a.name === 'string' && a.name !== '' ? a.name : null;
     if (name === null) p.add('MAP_ALT_NAME', `${aw} "name" is ${typeName(a.name)}; it must be a non-empty string`);
     else if (names.has(name)) p.add('MAP_ALT_NAME', `${aw} "name" "${name}" names two sets`);
@@ -344,7 +346,15 @@ function readAlternates(p: Problems, where: string, raw: unknown, chains: readon
         }
       }
     }
-    if (ok && name !== null && cs !== null) out.push({ name, slots, hides, chains: cs, pose, drawn, offsets, turn });
+    let frames: Array<[number, number]> | null = null;
+    if ('frames' in a) {
+      const f = a.frames;
+      const pair = (w: unknown): w is [number, number] => Array.isArray(w) && w.length === 2 && w.every((x) => Number.isInteger(x) && (x as number) >= 0) && (w[0] as number) <= (w[1] as number);
+      if (!Array.isArray(f) || f.length === 0 || !f.every(pair)) {
+        p.add('MAP_ALT_FRAMES', `${label} "frames" is ${JSON.stringify(f)}; it must be a non-empty list of windows [[first, last], …], whole frame numbers ≥ 0 with first ≤ last`);
+      } else frames = (f as Array<[number, number]>).map((w) => [w[0], w[1]]);
+    }
+    if (ok && name !== null && cs !== null) out.push({ name, slots, hides, chains: cs, pose, drawn, offsets, turn, frames });
   });
   return out;
 }

package/src/retarget.ts

@@ -41,7 +41,8 @@
  *
  * Then the switches (rig-c/pose#6, `switch.ts`): with every target known —
  * reaches included — each alternate set's distance to the pose is read, and the
- * spans each set shows are chosen. Only then the range clamp: outside the spans
+ * spans each set shows are chosen, each boundary keyed at its window's speed
+ * peak (#31). Only then the range clamp: outside the spans
  * of a set depicting its chain, a bone whose rotate key would leave its
  * `range` is clamped at the limit (its target becomes the clamped world angle),
  * in depth order, so a bone below takes the clamped parent into its own key

package/src/run.ts

@@ -154,7 +154,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         animation: a.name,
         frames: seq.frames.length,
         duration: r.animation.duration,
-        options: { minScore: a.minScore, smooth: a.smooth, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, profile: a.profile },
+        options: { minScore: a.minScore, smooth: a.smooth, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile },
         scale: r.scale,
         holds: r.holds,
         short: r.short,

package/src/switch.ts

@@ -31,6 +31,26 @@
  * time lands below it (rig-c docs/AUTHORING.md §4.5), and the pose's times and
  * a renderer's `i / fps` are two grids that disagree by more than that.
  * Halfway, both see it on frame i.
+ *
+ * Where a switch is keyed (rig-c/pose#31): a boundary — a frame where a set
+ * starts showing, or where the base art or the next set comes back — is moved,
+ * after the selection above, to the fastest frame within ±`switchMin`/2 of it,
+ * so the change of drawing lands in motion, not on an arm slowing into the
+ * pose. The speed on a frame is the largest |angular speed|, degrees per frame
+ * (central difference of the target world angles; one-sided on the first and
+ * last frame), over the segments of the chains the boundary changes, the
+ * leaving set's and the arriving set's; read on the same targets as the
+ * distance, before the range clamp and any set's `turn`, which depend on where
+ * the spans are. The window is clipped so every span keeps `switchMin` (a gap
+ * between two spans of one set too, so the bridging holds), no boundary
+ * reaches its neighbour, and a set with `frames` shows only inside them; and
+ * a frame qualifies only if the set the move newly shows is within twice the
+ * tolerance of its key skeleton on every frame it newly shows it on (speed
+ * alone showed art up to 135° from its pose on the dancer). Ties
+ * go to the frame nearest the original, then the earlier. A boundary between
+ * two sets moves once. `switchAt: 'first'` keeps every boundary where the
+ * selection put it; it is the CLI's default, because on HQ's dancer the bounded
+ * peak still raised the sets' ART-RANGE runs from 24 to 31 (#31, round 2).
  */
 import type { AlternateSet, JointMap, Rest, RigSlots } from './map.ts';
 import { descends } from './map.ts';
@@ -43,6 +63,21 @@ export interface SwitchOptions {
   switchTolerance: number;
   /** Seconds: a run of one set shorter than this is dropped. */
   switchMin: number;
+  /** Where a boundary is keyed: 'first' (the CLI's default) keeps the frame the selection gave it; 'peak' moves it to the fastest qualifying frame of its window (#31). */
+  switchAt: 'peak' | 'first';
+}
+
+/** One boundary of a span: where the selection put it, where it is keyed, and how fast the chains it changes move on each. */
+export interface Move {
+  /** The frame the boundary showed on as selected, then as keyed. */
+  frame: [number, number];
+  /** Signed: frames, and the seconds between the two frames' times. */
+  frames: number;
+  seconds: number;
+  /** The frames it could move to, after clipping: first and last. */
+  window: [number, number];
+  /** Degrees per frame on the old and the new frame: the largest |angular speed| over the segments of the chains it changes. */
+  speed: { old: number; new: number };
 }
 
 export interface Switch {
@@ -63,6 +98,8 @@ export interface Switch {
   distance: { max: number; median: number };
   /** Per bone the set has a `drawn` angle for: |wrap(target − drawn)| over the frames shown, degrees. */
   artTurn: Record<string, { max: number; median: number }>;
+  /** The boundary it starts on (null from the first frame) and the one it ends on (null to the end); a boundary between two sets is in both. */
+  moved: { on: Move | null; off: Move | null };
 }
 
 export interface AttachmentKey {
@@ -169,6 +206,89 @@ function competing(sets: readonly AlternateSet[]): AlternateSet[][] {
   return [...groups.values()];
 }
 
+/**
+ * Per frame, the largest |angular speed| over the given bones' target world
+ * angles, degrees per frame: a central difference, one-sided on the first and
+ * the last frame.
+ */
+export function speeds(bones: readonly string[], targets: ReadonlyMap<string, readonly number[]>, n: number): number[] {
+  const out: number[] = [];
+  for (let k = 0; k < n; k++) {
+    const lo = Math.max(0, k - 1);
+    const hi = Math.min(n - 1, k + 1);
+    let v = 0;
+    if (hi > lo) for (const b of bones) v = Math.max(v, Math.abs(wrap(targets.get(b)![hi]! - targets.get(b)![lo]!)) / (hi - lo));
+    out.push(v);
+  }
+  return out;
+}
+
+/** A moved boundary may newly show a set only on frames within this many times the tolerance of its key skeleton (#31). */
+export const MOVE_BOUND = 2;
+
+/**
+ * Move each boundary of one group's segments to the fastest frame of its
+ * window (`switchAt: 'peak'`), in time order, each clipped against its
+ * neighbours as they stand; `vals[s]` is what segment s shows (null: the base
+ * art) and `pos[m]` the frame boundary m shows on, between segments m and m+1.
+ * A candidate frame qualifies only if every frame the move newly shows a set
+ * on is within `MOVE_BOUND` × the tolerance of it; none qualifying, the
+ * boundary stays. Returns one `Move` per boundary.
+ */
+function moveBoundaries(vals: ReadonlyArray<AlternateSet | null>, pos: readonly number[], map: JointMap, targets: ReadonlyMap<string, readonly number[]>, distances: ReadonlyMap<string, readonly number[]>, times: readonly number[], duration: number, opts: SwitchOptions): Move[] {
+  const n = times.length;
+  const at = [...pos];
+  const end = (b: number) => (b < n ? times[b]! : duration);
+  const len = (a: number, b: number) => end(b) - times[a]!;
+  /** What a segment must keep: the minimum span for a set's, and for a gap between two spans of one set (the bridging); never less than it had. */
+  const need = (s: number, had: number): number => {
+    const v = vals[s];
+    const kept = v !== null || (s > 0 && s + 1 < vals.length && vals[s - 1] !== null && vals[s - 1] === vals[s + 1]);
+    return kept ? Math.min(opts.switchMin, had) : 0;
+  };
+  const allowed = (a: AlternateSet | null, k: number) => a === null || a.frames === null || a.frames.some(([f, l]) => k >= f && k <= l);
+  const bonesOf = (a: AlternateSet | null): string[] => (a === null ? [] : a.chains.flatMap((cn) => map.chains.find((c) => c.name === cn)!.bones));
+  const moves: Move[] = [];
+  for (let m = 0; m < at.length; m++) {
+    const b = at[m]!;
+    const prev = m === 0 ? 0 : at[m - 1]!;
+    const next = m + 1 < at.length ? at[m + 1]! : n;
+    const leaving = vals[m] ?? null;
+    const arriving = vals[m + 1] ?? null;
+    const needPrev = need(m, len(prev, b));
+    const needNext = need(m + 1, len(b, next));
+    // The pose's times are read to the microsecond, so a frame exactly half a minimum span away may read a hair past it.
+    const half = opts.switchMin / 2 + 1e-6;
+    // Earlier: frames b' … b−1 show the arriving segment.
+    let lo = b;
+    while (lo - 1 > prev && times[b]! - times[lo - 1]! <= half && len(prev, lo - 1) >= needPrev - 1e-9 && allowed(arriving, lo - 1)) lo--;
+    // Later: frames b … b'−1 show the leaving one.
+    let hi = b;
+    while (hi + 1 < next && times[hi + 1]! - times[b]! <= half && len(hi + 1, next) >= needNext - 1e-9 && allowed(leaving, hi)) hi++;
+    const sp = speeds([...new Set([...bonesOf(leaving), ...bonesOf(arriving)])], targets, n);
+    // A frame qualifies only if the set it newly shows is within twice the tolerance of its key skeleton on every
+    // frame it newly shows it on (round 1 on the dancer: speed alone showed a set up to 135° from its pose).
+    const near = (a: AlternateSet | null, from: number, to: number): boolean => {
+      if (a === null) return true;
+      const d = distances.get(a.name)!;
+      for (let k = from; k < to; k++) if (d[k]! > MOVE_BOUND * opts.switchTolerance) return false;
+      return true;
+    };
+    const qualifies = (k: number) => (k < b ? near(arriving, k, b) : near(leaving, b, k));
+    let best = b;
+    if (opts.switchAt === 'peak') {
+      for (let k = lo; k <= hi; k++) {
+        if (!qualifies(k)) continue;
+        const d = sp[k]! - sp[best]!;
+        if (d > 1e-9 || (Math.abs(d) <= 1e-9 && (Math.abs(k - b) < Math.abs(best - b) || (Math.abs(k - b) === Math.abs(best - b) && k < best)))) best = k;
+      }
+    }
+    at[m] = best;
+    moves.push({ frame: [b, best], frames: best - b, seconds: r6(times[best]! - times[b]!), window: [lo, hi], speed: { old: r3(sp[b]!), new: r3(sp[best]!) } });
+  }
+  return moves;
+}
+
 /** The key time for a change that shows on frame i: half a frame before it, 0 on the first frame. */
 const changeAt = (times: readonly number[], i: number): number => (i === 0 ? 0 : r6((times[i - 1]! + times[i]!) / 2));
 
@@ -186,13 +306,20 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
   for (const group of competing(map.alternates)) {
     const pick: Array<AlternateSet | null> = [];
     for (let i = 0; i < n; i++) {
+      // A set with a `frames` window shows only inside it, and there it is chosen
+      // over any set without one (a stopgap for what the angles cannot tell apart).
       let best: AlternateSet | null = null;
       let bestD = Infinity;
+      let bestWindowed = false;
       for (const a of group) {
+        if (a.frames !== null && !a.frames.some(([f, l]) => i >= f && i <= l)) continue;
         const d = distances.get(a.name)![i]!;
-        if (d <= opts.switchTolerance && d < bestD) {
+        if (d > opts.switchTolerance) continue;
+        const windowed = a.frames !== null;
+        if ((windowed && !bestWindowed) || (windowed === bestWindowed && d < bestD)) {
           best = a;
           bestD = d;
+          bestWindowed = windowed;
         }
       }
       pick.push(best);
@@ -213,20 +340,34 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
       }
       i = j + 1;
     }
+    // A run shorter than the minimum span shows the base art.
     for (let i = 0; i < n;) {
       const a = pick[i];
       let j = i;
       while (j + 1 < n && pick[j + 1] === a) j++;
-      if (a !== null && a !== undefined) {
-        const from = times[i]!;
-        const to = j + 1 < n ? times[j + 1]! : duration;
-        if (to - from >= opts.switchMin - 1e-9) {
-          const ds = distances.get(a.name)!.slice(i, j + 1);
-          switches.push({ set: a.name, chains: a.chains, slots: a.slots, hides: a.hides, offsets: a.offsets, from, to, frames: [i, j], distance: { max: r3(Math.max(...ds)), median: r3(median(ds)) }, artTurn: {} });
-        }
-      }
+      const to = j + 1 < n ? times[j + 1]! : duration;
+      if (a !== null && a !== undefined && to - times[i]! < opts.switchMin - 1e-9) for (let k = i; k <= j; k++) pick[k] = null;
       i = j + 1;
     }
+    // The segments between boundaries, then each boundary moved (#31).
+    const vals: Array<AlternateSet | null> = [pick[0] ?? null];
+    const pos: number[] = [];
+    for (let i = 1; i < n; i++) {
+      if (pick[i] === pick[i - 1]) continue;
+      pos.push(i);
+      vals.push(pick[i] ?? null);
+    }
+    const moves = moveBoundaries(vals, pos, map, targets, distances, times, duration, opts);
+    for (let s = 0; s < vals.length; s++) {
+      const a = vals[s];
+      if (a === null || a === undefined) continue;
+      const i = s === 0 ? 0 : moves[s - 1]!.frame[1];
+      const j = s < pos.length ? moves[s]!.frame[1] - 1 : n - 1;
+      const from = times[i]!;
+      const to = j + 1 < n ? times[j + 1]! : duration;
+      const ds = distances.get(a.name)!.slice(i, j + 1);
+      switches.push({ set: a.name, chains: a.chains, slots: a.slots, hides: a.hides, offsets: a.offsets, from, to, frames: [i, j], distance: { max: r3(Math.max(...ds)), median: r3(median(ds)) }, artTurn: {}, moved: { on: s === 0 ? null : moves[s - 1]!, off: s < pos.length ? moves[s]! : null } });
+    }
   }
   const order = (name: string) => map.alternates.findIndex((a) => a.name === name);
   switches.sort((x, y) => x.frames[0] - y.frames[0] || order(x.set) - order(y.set));
@@ -426,9 +567,18 @@ export function switchLine(s: Switch, times: readonly number[]): string {
   if (offs.length > 0) parts.push(`offsets ${offs.map(([b, o]) => `"${b}" (${o[0]}, ${o[1]})`).join(', ')}`);
   const art = Object.entries(s.artTurn);
   if (art.length > 0) parts.push(`art turn ${art.map(([b, a]) => `"${b}" max ${deg(a.max)}, median ${deg(a.median)}`).join('; ')}`);
+  const moves = (['on', 'off'] as const).filter((k) => s.moved[k] !== null).map((k) => `${k} ${moveText(s.moved[k]!)}`);
+  if (moves.length > 0) parts.push(`moved ${moves.join(', ')}`);
   return parts.join('; ');
 }
 
+const spd = (v: number) => `${v.toFixed(1)}°/frame`;
+const win = (w: [number, number]) => (w[0] === w[1] ? `window frame ${w[0]}` : `window frames ${w[0]}–${w[1]}`);
+function moveText(m: Move): string {
+  if (m.frames === 0) return `frame ${m.frame[0]} stays (${spd(m.speed.old)}; ${win(m.window)})`;
+  return `frame ${m.frame[0]} → ${m.frame[1]} (${m.frames > 0 ? '+' : '−'}${Math.abs(m.frames)} frame${Math.abs(m.frames) === 1 ? '' : 's'}, ${m.seconds > 0 ? '+' : '−'}${Math.abs(m.seconds).toFixed(3)}s; ${spd(m.speed.old)} → ${spd(m.speed.new)}; ${win(m.window)})`;
+}
+
 export function artRangeLine(e: ArtRange, times: readonly number[]): string {
   return `set "${e.set}" chain "${e.chain}" bone "${e.bone}" turned ${sg(e.turn)} from drawn (range [${e.limits[0]}, ${e.limits[1]}]) ${spanOf(e.frames, times)}: ${e.seconds.toFixed(3)}s, up to ${deg(e.maxOverflow)} past it; ${e.clamped ? 'held at the limit' : 'the bone follows the pose'} — demand for another drawing of the set`;
 }