lecodes-assets 0.1.2 → 0.2.1

package/src/retarget/marks.ts

@@ -0,0 +1,581 @@
+// FOOT MARKS — where a clip's feet touch the ground, stand still, and lift off; and, for a stair
+// clip, the staircase its plants sit on. Measured OFFLINE and written into the GLB with the clip
+// (`extras.lecodes.contacts`), so every host reads one truth and the retargeter can enforce it
+// (`retarget.ts` locks each foot through its still window). The runtime keeps a copy of these rules
+// (creator-anim `curves.cpp`) for clips that carry no marks.
+//
+// Per foot, per frame: the CONTACT bone (a humanoid's ball — the toe base) and the ANKLE. A frame is
+// DOWN when the contact bone is horizontally slow AND low, or holds still for a quarter second
+// whatever its height, or the whole clip is still (an idle). The thresholds are fractions of the
+// clip's own speed / height range (a sprint's planted toe still rolls; an absolute gate misses it),
+// FLOORED by absolute constants: a range only means something when the clip contains a swing — a
+// combat idle's toe never exceeds 6.5 cm/s, and 20 % of that is noise.
+//
+// Inside a touch span the STILL window is the longest run under absolute stillness thresholds on
+// the toe's speed (both axes), the toe's height and the ankle's height — the ankle is the heel's
+// witness: it descends while the heel lowers and rises the moment the heel does, while the toe stays
+// low through both. The touch is the phase anchor; the still window is what a lock may trust.
+//
+// STAIRS (a clip the build labels as one): every plant sits on a tread, and the treads are a regular
+// staircase — one riser, one depth. Pass 1 finds provisional plants and their heights, a regular
+// staircase is FITTED to them (base + k · riser, least squares), pass 2 judges "low" against the
+// nearest tread instead of the clip's global bottom half, and every span gets its step index.
+//
+// A PLATFORM take also carries its LEDGE (`fitPlatform` → `platform`): a HANG — both hands still
+// and overhead, no foot on the floor — keeps dangling feet out of the fit and, where the feet never
+// stand on the top, names it from the grip (hands + `gripUnder`); the face is bounded by what is
+// inside it (plants on the top, hands resting on it) and outside it (gripping wrists, the body
+// below the top), its normal from the two levels' plants, else across the two gripping wrists,
+// else the facing. The edge is written relative to the root at frame 0.
+
+import type { Vec3 } from './rig'
+
+export interface FootTrack {
+  /** the contact bone's world position per frame (a humanoid's ball) */
+  contact: Vec3[]
+  /** the ankle's world position per frame (the foot bone) */
+  ankle: Vec3[]
+  /** a hand: its LOWEST descendant per frame (a fingertip) — a roll lands on the fingers with the
+   *  wrist 10–20 cm up, and the contact is theirs */
+  tip?: Vec3[]
+}
+
+export interface MarksInput {
+  /** seconds per frame */
+  dt: number
+  /** the root's world position per frame (`at` is expressed relative to its x/z) */
+  root: Vec3[]
+  /** the root's heading per frame (radians about +Y, +Z forward at 0) — lets an in-place clip's
+   *  backward-travelling planted foot read as "slow"; optional */
+  heading?: number[]
+  feet: { l?: FootTrack; r?: FootTrack }
+  /** the HANDS: `contact` = the hand, `ankle` = the forearm (the wrist's witness). A hand is down when
+   *  it is slow AND within HAND_LOW of the feet's floor — nothing else (a hand held still in the air
+   *  is a stance, not a contact). Cartwheels, rolls, vaults, hangs. */
+  hands?: { l?: FootTrack; r?: FootTrack }
+  /** fit a staircase to the plants (a clip labeled as stairs), or a PLATFORM: exactly two levels —
+   *  the floor and the top — and a foot slow at any other height (against the wall) is no plant */
+  stairs?: boolean | 'platform'
+  /** the GROUND's height in the tracks' space (a platform's level 0 is the ground, never "the lowest
+   *  the feet got": feet dangling under a ledge are still and low and not planted at all) */
+  floor?: number
+  /** the pelvis per frame (default: `root`) — the HANG rule reads the hands against it */
+  hips?: Vec3[]
+  /** every joint per frame — the body's envelope bounds a platform's face (the body below the top
+   *  is never inside the platform); optional, the fit does without */
+  body?: Vec3[][]
+  /** how far under the ledge's top a hanging hand's contact bone holds (m, default 0.15: the
+   *  fingers over the lip, the wrist against the face) — the level a hang alone defines */
+  gripUnder?: number
+}
+
+/** A platform take's ledge: the top's height, and its EDGE — a point on the top edge relative to the
+ *  root at frame 0 (world axes, like `at`), the face's outward horizontal normal — so a runtime can
+ *  place the character against a real ledge at clip start. `width` = how tightly the edge was
+ *  pinned (the gap between the inside and outside bounds, m). */
+export interface PlatformMark {
+  height: number            // the top over level 0 (the riser)
+  top: number               // the top's absolute height in the tracks' space
+  edge: [ number, number ]  // x/z of a point on the top edge, relative to the root at frame 0
+  normal: [ number, number ] // horizontal unit normal of the face, pointing away from the platform
+  width: number
+  from: 'both' | 'inside' | 'outside'
+  /** what fixed the edge: the HANDS on the ledge (a grip under it, a palm on top of it — known to a
+   *  few cm) or the FEET and the body alone (a jump onto or off a box: an estimate, see `width`) */
+  pinned: 'hands' | 'feet'
+}
+
+/** One foot-on-ground: `from`/`to` = the touch (seconds), `still` = the window it is genuinely
+ *  stationary in (null: never), `at` = the contact bone at the strike (x/z relative to the root that
+ *  frame, y absolute), `step` = the tread index on a stair clip. */
+export interface MarkSpan { from: number; to: number; still: [ number, number ] | null; at: Vec3; step?: number }
+
+/** The regular staircase a stair clip's plants sit on: tread k is at `base + k · riser`. */
+export interface Stairs {
+  riser: number
+  /** horizontal distance between successive treads (metres; 0 when it could not be measured) */
+  tread: number
+  base: number
+  dir: 'up' | 'down'
+}
+
+export interface ClipMarks {
+  feet: { l: string | null; r: string | null }
+  l: MarkSpan[]
+  r: MarkSpan[]
+  /** the hands' contact bones and spans (absent: not measured) */
+  hands?: { l: string | null; r: string | null }
+  hl?: MarkSpan[]
+  hr?: MarkSpan[]
+  /** planted at t = 0 */
+  first: 'l' | 'r' | 'both' | null
+  stairs?: Stairs
+  /** a platform take's ledge (see `PlatformMark`) */
+  platform?: PlatformMark
+}
+
+// ---- the constants (kept in step with creator-anim/src/curves.cpp) ----------------------------------
+/** absolute floors under the clip-relative touch gates: horizontal speed (m/s), height above the
+ *  clip's lowest foot height (m) — 2 cm: a pivot on the spot lifts its toe ~3.5 cm, a planted toe
+ *  wanders ~1.2 cm */
+const TOUCH_SPEED = 0.15, TOUCH_HEIGHT = 0.02
+/** a foot under this speed on both axes for HELD_SECONDS is down whatever its height */
+const STILL_SPEED = 0.12, HELD_SECONDS = 0.25
+/** the still window must last this long — a velocity reversal passes every gate for 2 samples */
+const STILL_MIN = 0.08
+/** stairs: candidate plants shorter than this do not vote for a tread */
+const CAND_MIN = 0.1
+/** a hand is on the ground within this of the feet's floor (m) */
+const HAND_LOW = 0.06
+/** a HANG: both hands still and at least this far above the pelvis, no foot on the floor (m) */
+const HANG_OVER = 0.5
+/** a hanging hand's contact bone (the wrist) hangs this far in FRONT of the ledge's face (m): the
+ *  fingers curl over the lip, the palm's heel presses the face, the wrist is outside it */
+const GRIP_OUT = 0.04
+
+const hyp2 = (a: number, b: number): number => Math.sqrt(a * a + b * b)
+const median = (v: number[]): number => { const s = [ ...v ].sort((a, b) => a - b); return s.length ? s[s.length >> 1]! : 0 }
+
+interface Series { sp: number[]; vv: number[]; vf: number[]; hs: number[]; ah: number[]; lo: number; hi: number; hLo: number; hHi: number; aLo: number; aHi: number }
+
+const seriesOf = (ft: FootTrack, dt: number, heading: number[] | undefined): Series => {
+  const n = ft.contact.length
+  const sp: number[] = [], vv: number[] = [], vf: number[] = [], hs: number[] = [], ah: number[] = []
+  for (let k = 0; k < n; k++) {
+    const a = Math.max(0, k - 1), b = Math.min(n - 1, k + 1)
+    const inv = 1 / ((b - a) * dt || dt)
+    const d = [ (ft.contact[b]![0] - ft.contact[a]![0]) * inv, (ft.contact[b]![1] - ft.contact[a]![1]) * inv, (ft.contact[b]![2] - ft.contact[a]![2]) * inv ]
+    sp.push(hyp2(d[0]!, d[2]!)); vv.push(Math.abs(d[1]!)); hs.push(ft.contact[k]![1]); ah.push(ft.ankle[k]![1])
+    const yaw = heading?.[k] ?? 0
+    vf.push(d[0]! * Math.sin(yaw) + d[2]! * Math.cos(yaw))
+  }
+  return { sp, vv, vf, hs, ah, lo: Math.min(...sp), hi: Math.max(...sp), hLo: Math.min(...hs), hHi: Math.max(...hs), aLo: Math.min(...ah), aHi: Math.max(...ah) }
+}
+
+/** ±window local minimum / range of a series (the stair pass-1 height gate). */
+const localMin = (v: number[], w: number): { mn: number[]; range: number[] } => {
+  const mn: number[] = [], range: number[] = []
+  for (let k = 0; k < v.length; k++) {
+    let lo = Infinity, hi = -Infinity
+    for (let q = Math.max(0, k - w); q <= Math.min(v.length - 1, k + w); q++) { lo = Math.min(lo, v[q]!); hi = Math.max(hi, v[q]!) }
+    mn.push(lo); range.push(hi - lo)
+  }
+  return { mn, range }
+}
+
+const runsOf = (flag: boolean[]): { start: number; end: number }[] => {
+  const out: { start: number; end: number }[] = []
+  let s = -1
+  for (let k = 0; k <= flag.length; k++) {
+    const on = k < flag.length && flag[k]!
+    if (on && s < 0) s = k
+    if (!on && s >= 0) { out.push({ start: s, end: k }); s = -1 }
+  }
+  return out
+}
+
+/**
+ * Fit a regular staircase to plant heights: `levels` = (height, weight). Returns null when the
+ * plants do not span two treads. Least squares on base + k·riser with k re-assigned each round.
+ */
+export const fitStaircase = (levels: { y: number; w: number }[], mode: 'stairs' | 'platform' = 'stairs', floor?: number): { base: number; riser: number; steps: (y: number) => number } | null => {
+  if (levels.length < 2) return null
+  const sorted = [ ...levels ].sort((a, b) => a.y - b.y)
+  // initial levels: gap-based clusters (candidates within 8 cm chain into one tread)
+  const clusters: { y: number; w: number }[] = []
+  for (const l of sorted) {
+    const last = clusters[clusters.length - 1]
+    if (last && l.y - last.y < 0.08) { const w = last.w + l.w; last.y = (last.y * last.w + l.y * l.w) / w; last.w = w }
+    else clusters.push({ ...l })
+  }
+  if (mode === 'platform') {
+    // a platform has two levels: the floor (the ground when known, else the lowest cluster) and the
+    // top (the highest cluster); a plant is on one of them or it is not a plant (a foot pressed
+    // against the wall on the way up, feet dangling under a ledge)
+    const lo = floor ?? clusters[0]!.y, hi = clusters[clusters.length - 1]!.y, riser = hi - lo
+    if (riser < 0.05) return null
+    const eps = 0.08   // ON a level means within 8 cm of it — not a share of a 2.5 m platform's height (that let feet dangling 23 cm over the floor count as planted on it)
+    return { base: lo, riser, steps: (y) => (Math.abs(y - lo) < eps ? 0 : Math.abs(y - hi) < eps ? 1 : NaN) }
+  }
+  if (clusters.length < 2) return null
+  const gaps: number[] = []
+  for (let i = 1; i < clusters.length; i++) gaps.push(clusters[i]!.y - clusters[i - 1]!.y)
+  let riser = median(gaps), base = clusters[0]!.y
+  if (riser < 0.05) return null
+  for (let round = 0; round < 4; round++) {
+    // assign k, then weighted least squares for (base, riser)
+    let sw = 0, sk = 0, sy = 0, skk = 0, sky = 0
+    for (const l of levels) {
+      const k = Math.round((l.y - base) / riser)
+      sw += l.w; sk += l.w * k; sy += l.w * l.y; skk += l.w * k * k; sky += l.w * k * l.y
+    }
+    const det = sw * skk - sk * sk
+    if (Math.abs(det) < 1e-9) break
+    const nb = (sy * skk - sk * sky) / det, nr = (sw * sky - sk * sy) / det
+    if (nr < 0.05) break
+    base = nb; riser = nr
+  }
+  // k = 0 at the lowest plant
+  const kMin = Math.min(...levels.map((l) => Math.round((l.y - base) / riser)))
+  base += kMin * riser
+  return { base, riser, steps: (y) => Math.round((y - base) / riser) }
+}
+
+/** Detect one clip's marks from its foot tracks. */
+export const detectMarks = (input: MarksInput): { l: MarkSpan[]; r: MarkSpan[]; hl: MarkSpan[]; hr: MarkSpan[]; first: ClipMarks['first']; stairs?: Stairs; platform?: PlatformMark; hang: boolean[]; warnings: string[] } => {
+  const { dt, root } = input
+  const n = root.length
+  const warnings: string[] = []
+  const sides: ('l' | 'r')[] = [ 'l', 'r' ]
+  const series: Partial<Record<'l' | 'r', Series>> = {}
+  for (const s of sides) { const ft = input.feet[s]; if (ft && ft.contact.length === n) series[s] = seriesOf(ft, dt, input.heading) }
+  // in place = the root barely travels: a treadmill clip's planted foot travels backward at gait speed
+  let travel = 0
+  for (let k = 1; k < n; k++) travel += hyp2(root[k]![0] - root[k - 1]![0], root[k]![2] - root[k - 1]![2])
+  const inPlace = travel < 0.05
+
+  // ---- a HANG: both hands still, overhead, no foot on the floor ------------------------------------
+  // Dangling feet are still and low and used to vote a "platform" a quarter metre high (the hang
+  // idles); a hang frame's feet are no plant candidates, and where the feet never reach a top the
+  // grip alone names the level: the hands' height plus what a hand holds under a lip.
+  const hangAt = new Array<boolean>(n).fill(false)
+  const hipsY = (k: number): number => (input.hips ?? root)[k]![1]
+  const floorY0 = input.floor ?? Math.min(...sides.map((s) => series[s]?.hLo ?? Infinity))
+  const handSeries: Partial<Record<'l' | 'r', Series>> = {}
+  for (const s of sides) { const ft = input.hands?.[s]; if (ft && ft.contact.length === n) handSeries[s] = seriesOf(ft, dt, undefined) }
+  if (handSeries.l && handSeries.r) {
+    const hl = handSeries.l, hr = handSeries.r
+    const flags: boolean[] = []
+    for (let k = 0; k < n; k++) {
+      const still = hl.sp[k]! < STILL_SPEED && hl.vv[k]! < STILL_SPEED && hr.sp[k]! < STILL_SPEED && hr.vv[k]! < STILL_SPEED
+      const overhead = hl.hs[k]! > hipsY(k) + HANG_OVER && hr.hs[k]! > hipsY(k) + HANG_OVER
+      const feetUp = Number.isFinite(floorY0) ? sides.every((s) => !series[s] || series[s]!.hs[k]! > floorY0 + 0.1) : true
+      flags.push(still && overhead && feetUp)
+    }
+    // a run at the clip's edge is a pose held before / after the take (a drop from a hang starts
+    // hanging for 0.2 s): three frames suffice there
+    for (const r of runsOf(flags)) if ((r.end - r.start) * dt >= HELD_SECONDS || ((r.start === 0 || r.end === n) && r.end - r.start >= 3)) for (let k = r.start; k < r.end; k++) hangAt[k] = true
+  }
+  const hangFrames: number[] = []
+  hangAt.forEach((h, k) => { if (h) hangFrames.push(k) })
+
+  // ---- stairs, pass 1: provisional plants → tread candidates → one regular staircase ---------------
+  let stairs: Stairs | undefined
+  let stepOf: ((y: number) => number) | null = null
+  let levelOf: ((k: number) => number) | null = null
+  if (input.stairs) {
+    const W = Math.max(1, Math.round(0.3 / dt))
+    const minCand = Math.max(2, Math.round(CAND_MIN / dt))
+    const cand: { y: number; w: number; t: number; x: number; z: number }[] = []
+    for (const s of sides) {
+      const se = series[s]; if (!se) continue
+      const ft = input.feet[s]!
+      const { mn, range } = localMin(se.hs, W)
+      const dn: boolean[] = []
+      for (let k = 0; k < n; k++) dn.push(!hangAt[k] && se.sp[k]! < se.lo + 0.2 * (se.hi - se.lo) && se.hs[k]! - mn[k]! < Math.max(0.04, 0.3 * range[k]!))
+      for (const r of runsOf(dn)) {
+        if (r.end - r.start < minCand) continue
+        const ys = se.hs.slice(r.start, r.end)
+        const mid = (r.start + r.end) >> 1
+        cand.push({ y: median(ys), w: r.end - r.start, t: mid * dt, x: ft.contact[mid]![0], z: ft.contact[mid]![2] })
+      }
+    }
+    let fit = fitStaircase(cand.map((c) => ({ y: c.y, w: c.w })), input.stairs === 'platform' ? 'platform' : 'stairs', input.floor)
+    // a PLATFORM the feet never stand on (a hang idle, a drop from a hang): the grip names the top
+    if (!fit && input.stairs === 'platform' && hangFrames.length && handSeries.l && handSeries.r) {
+      const gripY = median(hangFrames.map((k) => Math.min(handSeries.l!.hs[k]!, handSeries.r!.hs[k]!)))
+      const lo = input.floor ?? Math.min(...sides.map((s) => series[s]?.hLo ?? Infinity))
+      const hi = gripY + (input.gripUnder ?? 0.15)
+      if (Number.isFinite(lo) && hi - lo >= 0.3) {
+        const eps = 0.08
+        fit = { base: lo, riser: hi - lo, steps: (y) => (Math.abs(y - lo) < eps ? 0 : Math.abs(y - hi) < eps ? 1 : NaN) }
+        if (process.env.LECODES_MARKS_TRACE) console.log(`[marks] platform from the GRIP: hands at ${gripY.toFixed(3)} over ${hangFrames.length} hang frames → top ${hi.toFixed(3)}`)
+      }
+    }
+    if (process.env.LECODES_MARKS_TRACE) console.log(`[marks] stairs candidates: ${cand.map((c) => `${c.t.toFixed(2)}s y ${c.y.toFixed(3)} w ${c.w}`).join(' | ') || 'none'} → ${fit ? `base ${fit.base.toFixed(3)} riser ${fit.riser.toFixed(3)}` : 'no fit'}`)
+    if (!fit) warnings.push('labeled as stairs but its plants sit on one level — flat rules used')
+    else {
+      stepOf = fit.steps
+      levelOf = (k) => fit.base + k * fit.riser
+      // tread depth: the horizontal distance between plants one step apart, in time order
+      const byT = [ ...cand ].sort((a, b) => a.t - b.t)
+      const depths: number[] = []
+      for (let i = 1; i < byT.length; i++) {
+        const a = byT[i - 1]!, b = byT[i]!
+        if (Math.abs(fit.steps(b.y) - fit.steps(a.y)) === 1) depths.push(hyp2(b.x - a.x, b.z - a.z))
+      }
+      const first = byT[0], last = byT[byT.length - 1]
+      stairs = { riser: fit.riser, tread: depths.length ? median(depths) : 0, base: fit.base, dir: first && last && fit.steps(last.y) < fit.steps(first.y) ? 'down' : 'up' }
+    }
+  }
+  const riser = stairs?.riser ?? 0
+  const treadEps = Math.max(0.04, 0.3 * riser)
+
+  // ---- the spans -----------------------------------------------------------------------------
+  const out: { l: MarkSpan[]; r: MarkSpan[] } = { l: [], r: [] }
+  for (const s of sides) {
+    const se = series[s]; if (!se) continue
+    const ft = input.feet[s]!
+    const { sp, vv, vf, hs, ah, lo, hi, hLo, hHi, aLo, aHi } = se
+    const still = hi - lo < 0.05
+    // held still on both axes for a quarter second: down whatever the height
+    const held = new Array<boolean>(n).fill(false)
+    for (const r of runsOf(sp.map((v, k) => v < STILL_SPEED && vv[k]! < STILL_SPEED))) {
+      if ((r.end - r.start) * dt >= HELD_SECONDS) for (let k = r.start; k < r.end; k++) held[k] = true
+    }
+    const spThr = Math.max(TOUCH_SPEED, lo + 0.2 * (hi - lo))
+    const down: boolean[] = []
+    for (let k = 0; k < n; k++) {
+      const slow = sp[k]! < spThr || (inPlace && input.heading !== undefined && vf[k]! <= 0.15 * hi)
+      let low: boolean, vOk = true
+      if (levelOf && stepOf) {
+        // on a staircase: within reach of the nearest tread AND not moving vertically THROUGH it
+        // (a foot stepping down onto its tread is mostly vertical — horizontally slow and near the
+        // level while still falling); on a platform a height that is no level is no plant
+        const kk = stepOf(hs[k]!)
+        low = Number.isFinite(kk) && Math.abs(hs[k]! - levelOf(kk)) < treadEps
+        vOk = vv[k]! < 0.3
+      } else low = hs[k]! < hLo + Math.max(TOUCH_HEIGHT, 0.5 * (hHi - hLo))
+      down.push(still || held[k]! || (slow && low && vOk))
+    }
+    for (const r of runsOf(down)) {
+      const interior = r.start > 0 && r.end < n
+      const minSpan = !stairs ? 2 : interior ? Math.max(2, Math.round(0.08 / dt)) : Math.max(2, Math.round(0.06 / dt))
+      if (r.end - r.start < minSpan) continue
+      // the still window: the longest run under the absolute stillness gates
+      const thr = Math.max(STILL_SPEED, lo + 0.05 * (hi - lo))
+      let mnH = Infinity, mnA = Infinity
+      for (let q = r.start; q < r.end; q++) { mnH = Math.min(mnH, hs[q]!); mnA = Math.min(mnA, ah[q]!) }
+      const hThr = mnH + (stairs ? Math.max(0.02, 0.1 * riser) : Math.max(0.015, 0.04 * (hHi - hLo)))
+      const aThr = mnA + (stairs ? Math.max(0.015, 0.075 * riser) : Math.max(0.01, 0.04 * (aHi - aLo)))
+      let best: { start: number; end: number } | null = null
+      for (const w of runsOf(sp.slice(r.start, r.end).map((v, i) => { const q = r.start + i; return v < thr && vv[q]! < thr && hs[q]! < hThr && ah[q]! < aThr }))) {
+        if (!best || w.end - w.start > best.end - best.start) best = w
+      }
+      const stillWin: [ number, number ] | null = best && (best.end - 1 - best.start) * dt >= STILL_MIN
+        ? [ (r.start + best.start) * dt, (r.start + best.end - 1) * dt ] : null
+      const c = ft.contact[r.start]!, rt = root[r.start]!
+      const span: MarkSpan = { from: r.start * dt, to: (r.end - 1) * dt, still: stillWin, at: [ c[0] - rt[0], c[1], c[2] - rt[2] ] }
+      if (stepOf) { const kk = stepOf(median(hs.slice(r.start, r.end))); if (!Number.isFinite(kk)) continue; span.step = kk }
+      out[s].push(span)
+    }
+  }
+  const downAt0 = (s: 'l' | 'r'): boolean => out[s].some((x) => x.from <= 1e-6)
+  const first: ClipMarks['first'] = downAt0('l') && downAt0('r') ? 'both' : downAt0('l') ? 'l' : downAt0('r') ? 'r' : null
+
+  // ---- the hands: slow AND on the feet's floor ------------------------------------------------
+  const hands: { hl: MarkSpan[]; hr: MarkSpan[] } = { hl: [], hr: [] }
+  const floorY = Math.min(...sides.map((s) => series[s]?.hLo ?? Infinity))
+  // the heights a hand can be on: the floor, and every level of a fitted staircase / platform. On
+  // the floor a hand is down within HAND_LOW above it; on a level above the floor also in the band
+  // below its edge — a hand hanging from a ledge holds it 10–20 cm under the top (fingers over the
+  // lip, the wrist against the face), the donor's hang measured 15 cm.
+  const handLevels: { y: number; step: number }[] = []
+  if (levelOf && stepOf) {
+    const ks = new Set<number>()
+    for (const s of sides) for (const sp of out[s]) if (sp.step !== undefined) ks.add(sp.step)
+    if (!ks.size) ks.add(0)
+    for (const k of ks) handLevels.push({ y: levelOf(k), step: k })
+    if (stairs && input.stairs === 'platform' && !ks.has(1)) handLevels.push({ y: levelOf(1), step: 1 })
+  } else if (floorY < Infinity) handLevels.push({ y: floorY, step: -1 })
+  const handLevelAt = (y: number): { y: number; step: number } | null => {
+    let best: { y: number; step: number } | null = null, bd = Infinity
+    for (const l of handLevels) {
+      const above = y - l.y
+      const ok = above < HAND_LOW && (l.step > 0 ? above > -0.25 : above > -0.05)
+      if (ok && Math.abs(above) < bd) { bd = Math.abs(above); best = l }
+    }
+    return best
+  }
+  if (input.hands && handLevels.length) for (const s of sides) {
+    const ft = input.hands[s]
+    if (!ft || ft.contact.length !== n) continue
+    const { sp, vv, hs, ah, lo, hi } = seriesOf(ft, dt, undefined)
+    const spThr = Math.max(TOUCH_SPEED, lo + 0.2 * (hi - lo))
+    const down: boolean[] = []
+    const lowest = (k: number): number => (ft.tip ? Math.min(hs[k]!, ft.tip[k]![1]) : hs[k]!)
+    for (let k = 0; k < n; k++) down.push(sp[k]! < spThr && handLevelAt(lowest(k)) !== null)
+    for (const r of runsOf(down)) {
+      if (r.end - r.start < 2) continue
+      // the still window: absolute gates (a hand's height range spans the body — no relative widths)
+      const thr = STILL_SPEED
+      let mnH = Infinity, mnA = Infinity
+      for (let q = r.start; q < r.end; q++) { mnH = Math.min(mnH, hs[q]!); mnA = Math.min(mnA, ah[q]!) }
+      let best: { start: number; end: number } | null = null
+      for (const w of runsOf(sp.slice(r.start, r.end).map((v, i) => { const q = r.start + i; return v < thr && vv[q]! < thr && hs[q]! < mnH + 0.02 && ah[q]! < mnA + 0.03 }))) {
+        if (!best || w.end - w.start > best.end - best.start) best = w
+      }
+      const stillWin: [ number, number ] | null = best && (best.end - 1 - best.start) * dt >= STILL_MIN
+        ? [ (r.start + best.start) * dt, (r.start + best.end - 1) * dt ] : null
+      const c = ft.contact[r.start]!, rt = root[r.start]!
+      const lvl = handLevelAt(median(Array.from({ length: r.end - r.start }, (_, i) => lowest(r.start + i))))
+      const span: MarkSpan = { from: r.start * dt, to: (r.end - 1) * dt, still: stillWin, at: [ c[0] - rt[0], c[1], c[2] - rt[2] ] }
+      if (lvl && lvl.step >= 0) span.step = lvl.step
+      hands[s === 'l' ? 'hl' : 'hr'].push(span)
+    }
+  }
+  // ---- the platform's edge (a platform take with a fitted top) -------------------------------------
+  let platform: PlatformMark | undefined
+  if (stairs && input.stairs === 'platform') {
+    const feet = sides.filter((s) => input.feet[s] && input.feet[s]!.contact.length === n).map((s) => ({ track: input.feet[s]!, spans: out[s] }))
+    const hs = sides.filter((s) => input.hands?.[s] && input.hands[s]!.contact.length === n).map((s) => ({ track: input.hands![s]!, spans: hands[s === 'l' ? 'hl' : 'hr'] }))
+    platform = fitPlatform({ dt, root, hips: input.hips, heading: input.heading, level0: stairs.base, level1: stairs.base + stairs.riser, feet, hands: hs, hang: hangAt, body: input.body }) ?? undefined
+    if (!platform) warnings.push('platform take: the ledge\'s edge could not be placed (no plant, hand or body near it)')
+  }
+  return { l: out.l, r: out.r, hl: hands.hl, hr: hands.hr, first, ...(stairs ? { stairs } : {}), ...(platform ? { platform } : {}), hang: hangAt, warnings }
+}
+
+export interface PlatformFitInput {
+  dt: number
+  root: Vec3[]
+  hips?: Vec3[]
+  heading?: number[]
+  level0: number
+  level1: number
+  /** each foot: its track and its marked spans (`step` 1 = on the top) */
+  feet: { track: FootTrack; spans: MarkSpan[] }[]
+  /** each hand: its track and its spans (`step` 1 = on the top, or gripping under its edge) */
+  hands: { track: FootTrack; spans: MarkSpan[] }[]
+  /** per frame: a hang (both hands overhead, still, feet off the floor) */
+  hang: boolean[]
+  /** every joint per frame (optional): the body below the top is never inside the platform */
+  body?: Vec3[][]
+}
+
+/**
+ * Where a platform's FACE is. Two bounds along the face's outward normal `n`: INSIDE points — the
+ * balls of the plants on the top, the wrists of hands resting on the top — lie behind the face;
+ * OUTSIDE points — hanging hands' wrists (plus GRIP_OUT), every joint of the body while below the
+ * top — lie in front of it. The face is midway between the two nearest; with one bound only, a
+ * couple of centimetres beyond it. `n` = from the top's plants toward the ground's (a climb, a drop),
+ * else from a hang's grip toward the hanging pelvis, else the root's facing at a hang frame.
+ */
+export const fitPlatform = (input: PlatformFitInput): PlatformMark | null => {
+  const { level0, level1, root } = input
+  const n = root.length
+  const framesOf = (sp: MarkSpan): number[] => { const a = Math.round(sp.from / input.dt), b = Math.min(n - 1, Math.round(sp.to / input.dt)); const out: number[] = []; for (let k = a; k <= b; k++) out.push(k); return out }
+  const meanXZ = (pts: Vec3[]): [ number, number ] | null => (pts.length ? [ pts.reduce((a, p) => a + p[0], 0) / pts.length, pts.reduce((a, p) => a + p[2], 0) / pts.length ] : null)
+  const topPlants: Vec3[] = [], groundPlants: Vec3[] = []
+  for (const f of input.feet) for (const sp of f.spans) { const dst = sp.step === 1 ? topPlants : sp.step === 0 ? groundPlants : null; if (dst) for (const k of framesOf(sp)) dst.push(f.track.contact[k]!) }
+  const topHands: Vec3[] = [], grips: Vec3[] = []
+  const gripsOf: Vec3[][] = input.hands.map(() => [])
+  // (a hand REST: a running arm's swing pauses for three frames at a low platform's height and
+  // read as a palm on the top — a real palm or grip holds for a good fraction of a second)
+  input.hands.forEach((h, hi) => { for (const sp of h.spans) {
+    if (sp.step !== 1 || sp.to - sp.from < 0.12) continue
+    const ks = framesOf(sp)
+    const y = median(ks.map((k) => h.track.contact[k]![1]))
+    const dst = y < level1 - 0.05 ? grips : topHands
+    for (const k of ks) { dst.push(h.track.contact[k]!); if (dst === grips) gripsOf[hi]!.push(h.track.contact[k]!) }
+  } })
+  const hangKs: number[] = []
+  input.hang.forEach((h, k) => { if (h) hangKs.push(k) })
+  // when the character is ON the top: between its first and last top plant (the body bound skips
+  // those frames — a foot dragged low over the top is not a wall), and whether it LEAVES the top
+  // (a drop: the last top plant's toes hang over the edge) or ARRIVES on it (a landing foot comes
+  // down some way past the edge)
+  let firstTop = Infinity, lastTop = -Infinity
+  for (const f of input.feet) for (const sp of f.spans) if (sp.step === 1) { const ks = framesOf(sp); firstTop = Math.min(firstTop, ks[0]!); lastTop = Math.max(lastTop, ks[ks.length - 1]!) }
+  let firstOut = Infinity
+  for (const f of input.feet) for (const sp of f.spans) if (sp.step === 0) firstOut = Math.min(firstOut, framesOf(sp)[0]!)
+  if (hangKs.length) firstOut = Math.min(firstOut, hangKs[0]!)
+  const leaving = Number.isFinite(lastTop) && Number.isFinite(firstOut) && firstOut > lastTop
+  // the outward normal: from the top's plants toward the ground's, else toward the grip (a top
+  // walked to its edge and dropped from), else from a hang's grip toward the hanging pelvis when
+  // that offset is readable, else the facing (a hang faces its wall; the pelvis offset signs it)
+  let nx = 0, nz = 0
+  const tp = meanXZ(topPlants), gp = meanXZ(groundPlants), gr = meanXZ(grips), th = meanXZ(topHands)
+  const inside = tp ?? th
+  const hp = hangKs.length ? meanXZ(hangKs.map((k) => (input.hips ?? root)[k]!)) : null
+  // plants on both levels half a metre apart: their line (a walk along the top toward the edge and
+  // a hang under it gave a 30° skew from the top plants' mean — a hang trusts the facing instead)
+  if (inside && gp && hyp2(gp[0] - inside[0], gp[1] - inside[1]) >= 0.5) { nx = gp[0] - inside[0]; nz = gp[1] - inside[1] }
+  else {
+    // two hands gripping the same edge: the line between the wrists IS the edge, the normal is
+    // across it, signed toward the hanging pelvis (else backward from the facing)
+    const gl = gripsOf.map((g) => meanXZ(g)).filter((g): g is [ number, number ] => !!g)
+    if (gl.length >= 2 && hyp2(gl[1]![0] - gl[0]![0], gl[1]![1] - gl[0]![1]) >= 0.15) {
+      const tx = gl[1]![0] - gl[0]![0], tz = gl[1]![1] - gl[0]![1]
+      let px = tz, pz = -tx
+      const ks = hangKs.length ? hangKs : [ 0 ]
+      let fx = 0, fz = 0
+      for (const k of ks) { const yaw = input.heading?.[k] ?? 0; fx += Math.sin(yaw); fz += Math.cos(yaw) }
+      const off = hp && gr ? [ hp[0] - gr[0], hp[1] - gr[1] ] : null
+      const dot = off && hyp2(off[0]!, off[1]!) >= 0.1 ? off[0]! * px + off[1]! * pz : -(fx * px + fz * pz)
+      if (dot < 0) { px = -px; pz = -pz }
+      nx = px; nz = pz
+    }
+  }
+  if (hyp2(nx, nz) < 0.05) {
+    // the facing over the hang frames (a hang faces its wall: the normal points backward), signed
+    // by the pelvis' offset from the grip when it reads, else at frame 0 signed by the plants
+    const ks = hangKs.length ? hangKs : [ 0 ]
+    let fx = 0, fz = 0
+    for (const k of ks) { const yaw = input.heading?.[k] ?? 0; fx += Math.sin(yaw); fz += Math.cos(yaw) }
+    const fl = hyp2(fx, fz) || 1
+    const fwd = [ fx / fl, fz / fl ]
+    const off = gr && hp ? [ hp[0] - gr[0], hp[1] - gr[1] ] : null
+    const dot = off && hyp2(off[0]!, off[1]!) >= 0.1 ? off[0]! * fwd[0]! + off[1]! * fwd[1]! : tp && gp ? (gp[0] - tp[0]) * fwd[0]! + (gp[1] - tp[1]) * fwd[1]! : -1
+    const sign = Math.sign(dot) || -1
+    nx = fwd[0]! * sign; nz = fwd[1]! * sign
+  }
+  const nl = hyp2(nx, nz); nx /= nl; nz /= nl
+  const s = (p: Vec3): number => p[0] * nx + p[2] * nz
+  // the bounds: the face lies ahead of the inside points by what each kind leaves over the edge,
+  // and never past the outside ones
+  let lo = -Infinity, hi = Infinity
+  // a LANDING on the top: the first strike's HEEL is at the edge (the foot comes down just past
+  // it; the heel's back sits ~3 cm behind the ankle) — the owner's rule for hand-less takes; a
+  // DEPARTURE: the last plant's toes hang over the edge
+  if (Number.isFinite(firstTop) && !leaving) {
+    for (const f of input.feet) for (const sp of f.spans) if (sp.step === 1 && framesOf(sp)[0] === firstTop) lo = Math.max(lo, s(f.track.ankle[firstTop]!) - 0.03)
+  } else for (const p of topPlants) lo = Math.max(lo, s(p) + 0.12)
+  for (const p of topHands) lo = Math.max(lo, s(p) + 0.08)
+  // a gripping wrist hangs GRIP_OUT in front of the face (the fingers over the lip): the face is
+  // exactly there — the grip decides, the body bound is for takes without one (a retargeted
+  // rig's unconstrained dangling feet reached 10 cm into the wall and pushed the face out)
+  for (const p of grips) hi = Math.min(hi, s(p) - GRIP_OUT)
+  let hiAt = ''
+  if (input.body && !grips.length) for (let k = 0; k < n; k++) {
+    if (k >= firstTop && k <= lastTop) continue
+    // well under the lip: a gripping hand's fingers curl over it, a mantling foot dips into the top
+    input.body[k]!.forEach((p, j) => { if (p[1] < level1 - 0.3 && s(p) - 0.02 < hi) { hi = s(p) - 0.02; hiAt = `body f${k} joint ${j} y ${p[1].toFixed(2)}` } })
+  }
+  if (!Number.isFinite(lo) && !Number.isFinite(hi)) return null
+  const from: PlatformMark['from'] = Number.isFinite(lo) && Number.isFinite(hi) ? 'both' : Number.isFinite(lo) ? 'inside' : 'outside'
+  const sf = from === 'both' ? Math.min(lo, hi) : from === 'inside' ? lo : hi
+  // a point on the edge: the reference (inside points, else the grip, else the hanging pelvis) projected onto the face
+  const ref = inside ?? gr ?? meanXZ(hangKs.map((k) => (input.hips ?? root)[k]!)) ?? [ root[0]![0], root[0]![2] ]
+  const rs = ref[0] * nx + ref[1] * nz
+  const ex = ref[0] + nx * (sf - rs), ez = ref[1] + nz * (sf - rs)
+  if (process.env.LECODES_MARKS_TRACE) console.log(`[marks] platform: normal (${nx.toFixed(2)}, ${nz.toFixed(2)}) inside ${Number.isFinite(lo) ? lo.toFixed(3) : '-'} outside ${Number.isFinite(hi) ? hi.toFixed(3) : '-'} → face ${sf.toFixed(3)} (${from}${hiAt ? `, ${hiAt}` : ''}) · top plants ${topPlants.length} ground ${groundPlants.length} grips ${grips.length} top hands ${topHands.length} hang frames ${hangKs.length}`)
+  return { height: level1 - level0, top: level1, edge: [ ex - root[0]![0], ez - root[0]![2] ], normal: [ nx, nz ], width: from === 'both' ? Math.max(0, hi - lo) : Infinity, from, pinned: grips.length || topHands.length ? 'hands' : 'feet' }
+}
+
+/** The marks written to / read from a GLB animation's `extras.lecodes`. */
+export const readMarks = (extras: unknown): ClipMarks | null => {
+  const lec = (extras as { lecodes?: { contacts?: ClipMarks } } | null)?.lecodes
+  return lec?.contacts ?? null
+}
+
+export type LevelKind = 'stairs' | 'platform' | false
+/** What kind of LEVELS a clip name labels: a staircase (`stairs` pattern, default "stair"), a platform
+ *  (`platforms` pattern, default "platform": exactly two levels) or none. A pattern is a regex
+ *  source, 'all' or 'none'. */
+export const stairsMatcher = (stairs: string | undefined, platforms: string | undefined = undefined): ((name: string) => LevelKind) => {
+  const mk = (p: string | undefined, def: string): ((n: string) => boolean) => {
+    if (p === 'none') return () => false
+    if (p === 'all') return () => true
+    const re = new RegExp(p ?? def, 'i')
+    return (n) => re.test(n)
+  }
+  const isStairs = mk(stairs, 'stair'), isPlatform = mk(platforms, 'platform')
+  return (name) => (isPlatform(name) ? 'platform' : isStairs(name) ? 'stairs' : false)
+}
+
+/** One line per clip for a log. */
+export const describeMarks = (m: { l: MarkSpan[]; r: MarkSpan[]; hl?: MarkSpan[]; hr?: MarkSpan[]; stairs?: Stairs }): string => {
+  const side = (s: 'l' | 'r' | 'hl' | 'hr'): string => (m[s] ?? []).map((x) => `${s.toUpperCase()} ${x.from.toFixed(2)}-${x.to.toFixed(2)}${x.still ? ` still(${x.still[0].toFixed(2)}-${x.still[1].toFixed(2)})` : ''}${x.step !== undefined ? ` k${x.step}` : ''}`).join(' | ')
+  const st = m.stairs ? `  stairs ${m.stairs.dir} riser ${(m.stairs.riser * 100).toFixed(1)} cm tread ${(m.stairs.tread * 100).toFixed(0)} cm` : ''
+  return `${[ side('l'), side('r'), side('hl'), side('hr') ].filter(Boolean).join(' | ') || 'no contacts'}${st}`
+}