@rig-c/review 0.5.0 → 0.7.0

package/src/handoff.ts

@@ -0,0 +1,208 @@
+/**
+ * Producer handoff (#101): which producer config, parts and inspected rig the package was built from, so an Apply can
+ * rebuild through the installed producer and the AI receiving the review can rebuild exactly that state.
+ *
+ * Declared first — `rig-review open <dir> --config <path> …`, else the `producer` block in review.json — then a fixed
+ * discovery order, never a search: `config.json`, then `rig/config.json` inside the opened folder, and as the last step
+ * `../config.json` beside an opened `out/`. That last one sits outside the opened folder, so the record names it
+ * `discovered` with `outside: true`, its path and its hash. Every path is literal and must stay inside its root (the
+ * package root; for the `../config.json` step, the folder that holds `out/`); a symlink that leaves it is refused by name.
+ * The record (paths relative to the package root, hashes, how it was found) is part of `reviewedSource`, so changing a
+ * handoff file's bytes starts a new pending session.
+ */
+import { createHash } from 'node:crypto';
+import { lstat, readdir, readFile, realpath, stat } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
+
+export const HANDOFF_SCHEMA = 'rig-review-handoff/1';
+/** The fixed discovery order, as the refusal names it. */
+export const DISCOVERY_PLACES = ['config.json', 'rig/config.json', '../config.json (beside an opened out/)'] as const;
+export const HANDOFF_DECLARATION = 'rig-review open <dir> --config <path> [--parts <dir>] or the review.json "producer" block';
+export const MODELING_INPUT_UNAVAILABLE = `MODELING_INPUT_UNAVAILABLE: config.json — looked at ${DISCOVERY_PLACES.join(', ')}; declare it with ${HANDOFF_DECLARATION}`;
+/** Files the producer reads by the config's own naming, resolved against the config's directory (rig-parts `relativeConfigPaths`). */
+export const CONFIG_NAMED_FILES = [['motion', 'animations_from'], ['generation', 'control', 'skeleton']] as const;
+/** What `rig-parts rig` writes into its --out and remesh reads from --rig: the rig spec, its motion, the mesh report and the part images. */
+export const RIG_FILES = ['rig.json', 'motion.json', 'mesh_report.json'] as const;
+const MAX_LISTED = 4096;
+
+export interface HandoffDeclaration { config: string; parts?: string; source?: string; full?: string; head?: string }
+export type HandoffFlags = HandoffDeclaration;
+export const HANDOFF_FLAGS = ['config', 'parts', 'source', 'full', 'head'] as const;
+export interface HandoffFile { path: string; sha256: string }
+/** The identity record: paths relative to the package root (`../` only for the discovered parent config), every hashed file. */
+export interface HandoffRecord {
+  schema: typeof HANDOFF_SCHEMA;
+  how: 'declared' | 'discovered';
+  via: 'open --config' | 'review.json producer' | 'discovery';
+  outside: boolean;
+  config: HandoffFile;
+  parts: string | null; rig: string | null; source: HandoffFile | null; full: string | null; head: string | null;
+  files: HandoffFile[];
+  missing: string[];
+}
+/** The record plus the absolute paths the producer is run with (never served, never in the identity). */
+/** `source` (#109): the declared source painting's absolute path, which `propose --from-config` reads; null when none was declared. */
+/** `full` / `head` (#115): the declared See-through runs' absolute paths, which `rig-parts build` reads; null when none was declared. */
+export interface Handoff { record: HandoffRecord; config: string; parts: string | null; rig: string | null; root: string; flags?: HandoffFlags; source?: string | null; full?: string | null; head?: string | null }
+
+export class HandoffError extends Error {
+  constructor(readonly code: string, readonly field: string, readonly detail: string) { super(`${code} ${field}: ${detail}`); }
+}
+const sha256 = (bytes: Uint8Array | string) => createHash('sha256').update(bytes).digest('hex');
+const inside = (base: string, path: string, allowSelf = false) => { const rel = relative(base, path); return rel === '' ? allowSelf : rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel); };
+const code = (e: unknown) => (e as NodeJS.ErrnoException).code ?? '';
+async function exists(path: string): Promise<boolean> { try { await lstat(path); return true; } catch (e) { if (code(e) === 'ENOENT' || code(e) === 'ENOTDIR') return false; throw e; } }
+
+/**
+ * One handoff path: it must exist, its canonical location must stay inside `base`, and it must be the expected kind.
+ * `lexicalInside` says whether the path as written was inside the root, so a canonical escape is named a symlink escape.
+ */
+async function contained(base: string, path: string, field: string, kind: 'file' | 'dir', lexicalInside: boolean): Promise<string> {
+  if (!(await exists(path))) throw new HandoffError('HANDOFF_INPUT_MISSING', field, `${path} does not exist`);
+  let real: string;
+  try { real = await realpath(path); } catch (e) { if (code(e) === 'ENOENT' || code(e) === 'ELOOP') throw new HandoffError('HANDOFF_SYMLINK_ESCAPE', field, `${path} is a dangling or looping symlink`); throw e; }
+  if (!inside(base, real, kind === 'dir')) {
+    if (lexicalInside) throw new HandoffError('HANDOFF_SYMLINK_ESCAPE', field, `${path} resolves outside ${base} (symlinks may not escape)`);
+    throw new HandoffError('HANDOFF_PATH_OUTSIDE_ROOT', field, `${path} is outside ${base}`);
+  }
+  const info = await stat(real);
+  if (kind === 'file' ? !info.isFile() : !info.isDirectory()) throw new HandoffError('HANDOFF_INPUT_INVALID', field, `${path} is not a ${kind === 'file' ? 'regular file' : 'directory'}`);
+  return real;
+}
+/** A CLI path: written relative to the working directory or absolute; canonical inside the package root. */
+async function flagPath(root: string, value: string, field: string, kind: 'file' | 'dir'): Promise<string> {
+  const lexical = resolve(value);
+  // The parent chain is canonicalized so a platform alias (/tmp → /private/tmp) is not taken for an escape; the last
+  // component is left as written so a symlink there is named as one.
+  let parent: string;
+  try { parent = await realpath(dirname(lexical)); } catch (e) { if (code(e) === 'ENOENT' || code(e) === 'ENOTDIR') throw new HandoffError('HANDOFF_INPUT_MISSING', field, `${value} does not exist`); throw e; }
+  const written = join(parent, basename(lexical));
+  return contained(root, written, field, kind, inside(root, written, kind === 'dir'));
+}
+/** A review.json `producer` path: literal, portable, relative to the package root. */
+async function blockPath(root: string, value: unknown, field: string, kind: 'file' | 'dir'): Promise<string> {
+  if (typeof value !== 'string' || !value) throw new HandoffError('HANDOFF_PATH_INVALID', field, 'expected a nonempty literal relative path');
+  if (isAbsolute(value) || /^[a-zA-Z]:/.test(value) || value.split('/').includes('..')) throw new HandoffError('HANDOFF_PATH_OUTSIDE_ROOT', field, `${value} leaves the package root (absolute or ..)`);
+  if (/[:\\%?#\x00-\x1f]/.test(value) || value.split('/').some(s => !s || s === '.') || posix.normalize(value) !== value) throw new HandoffError('HANDOFF_PATH_INVALID', field, `${value} is not a literal portable relative path`);
+  return contained(root, join(root, value), field, kind, true);
+}
+
+/** `producer: {config, parts?, source?, full?, head?}` — strings only, no other key. Paths are checked at load. */
+export function parseHandoffDeclaration(value: unknown): HandoffDeclaration | undefined {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new HandoffError('HANDOFF_PATH_INVALID', 'producer', 'expected an object {config, parts?, source?, full?, head?}');
+  const v = value as Record<string, unknown>;
+  for (const key of Object.keys(v)) if (!(HANDOFF_FLAGS as readonly string[]).includes(key)) throw new HandoffError('HANDOFF_PATH_INVALID', `producer.${key}`, 'unknown key; expected config, parts, source, full, head');
+  if (typeof v.config !== 'string') throw new HandoffError('HANDOFF_PATH_INVALID', 'producer.config', 'required: the producer config path');
+  const out: HandoffDeclaration = { config: v.config };
+  for (const key of ['parts', 'source', 'full', 'head'] as const) if (v[key] !== undefined) { if (typeof v[key] !== 'string') throw new HandoffError('HANDOFF_PATH_INVALID', `producer.${key}`, 'expected a string path'); out[key] = v[key] as string; }
+  return out;
+}
+/** `--source` and `--full` travel together, `--head` only with them, and everything else only with `--config`. */
+export function checkHandoffFlags(flags: Partial<HandoffFlags>): string | null {
+  const present = HANDOFF_FLAGS.filter(f => flags[f] !== undefined);
+  if (!present.length) return null;
+  if (flags.config === undefined) return `--${present[0]}: requires --config <path>`;
+  if ((flags.source === undefined) !== (flags.full === undefined)) return `--${flags.source === undefined ? 'full' : 'source'}: --source <png> and --full <dir> are given together`;
+  if (flags.head !== undefined && flags.full === undefined) return '--head: requires --source <png> --full <dir>';
+  return null;
+}
+
+async function hashFile(path: string): Promise<string> { return sha256(await readFile(path)); }
+/** Regular files directly in `dir` (a fixed directory, not a search); each must stay inside `base`. */
+async function listed(base: string, dir: string, field: string): Promise<string[]> {
+  const entries = (await readdir(dir, { withFileTypes: true })).filter(e => !e.isDirectory()).map(e => e.name).sort();
+  if (entries.length > MAX_LISTED) throw new HandoffError('HANDOFF_INPUT_INVALID', field, `${dir} holds more than ${MAX_LISTED} files`);
+  const out: string[] = [];
+  for (const name of entries) { const real = await contained(base, join(dir, name), `${field}/${name}`, 'file', true).catch(e => { if (e instanceof HandoffError && e.code === 'HANDOFF_INPUT_INVALID') return null; throw e; }); if (real) out.push(real); }
+  return out;
+}
+
+/** Hash every handoff file and build the record. `root` is the package root (display paths are relative to it). */
+async function record(root: string, base: string, how: HandoffRecord['how'], via: HandoffRecord['via'], config: string, partsPath: string | null, extra: { source?: string; full?: string; head?: string }, partsDeclared: boolean): Promise<Handoff> {
+  const show = (path: string) => relative(root, path).split(sep).join('/') || '.';
+  const files = new Map<string, string>(), missing: string[] = [];
+  const add = async (path: string) => { files.set(show(path), await hashFile(path)); };
+  await add(config);
+  // Files the config names that the producer reads, resolved against the config's own directory.
+  let parsed: unknown = null;
+  try { parsed = JSON.parse(await readFile(config, 'utf8')); } catch { /* the producer refuses an unreadable config by name */ }
+  for (const keys of CONFIG_NAMED_FILES) {
+    let value: unknown = parsed;
+    for (const k of keys) value = value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>)[k] : undefined;
+    if (typeof value !== 'string' || !value) continue;
+    const field = `config ${keys.join('.')}`, lexical = resolve(dirname(config), value);
+    if (!inside(base, lexical)) throw new HandoffError('HANDOFF_PATH_OUTSIDE_ROOT', field, `${value} resolves outside ${base}`);
+    if (!(await exists(lexical))) { missing.push(`${keys.join('.')} ${show(lexical)}`); continue; }
+    await add(await contained(base, lexical, field, 'file', true));
+  }
+  let parts: string | null = null, rig: string | null = null;
+  if (partsPath && (partsDeclared || await exists(partsPath))) {
+    parts = await contained(base, partsPath, partsDeclared ? '--parts' : 'parts', 'dir', true);
+    const partsJson = join(parts, 'parts.json');
+    if (await exists(partsJson)) await add(await contained(base, partsJson, 'parts.json', 'file', true)); else missing.push(`parts.json ${show(partsJson)}`);
+    if (await exists(join(parts, 'parts'))) for (const file of await listed(base, await contained(base, join(parts, 'parts'), 'parts/', 'dir', true), 'parts')) await add(file);
+    const rigDir = join(parts, 'rig');
+    if (await exists(rigDir)) {
+      rig = await contained(base, rigDir, 'rig', 'dir', true);
+      for (const name of RIG_FILES) if (!(await exists(join(rig, name)))) missing.push(`rig ${show(join(rig, name))}`);
+      // Every file remesh carries over: the rig directory's regular files (rig.json, motion.json, mesh_report.json, sets.json, …) and images/.
+      for (const file of await listed(base, rig, 'rig')) await add(file);
+      if (await exists(join(rig, 'images'))) for (const file of await listed(base, await contained(base, join(rig, 'images'), 'rig/images', 'dir', true), 'rig/images')) await add(file);
+    } else missing.push(`rig ${show(rigDir)}`);
+  } else missing.push(`parts ${partsPath ? show(partsPath) : '(none)'}`);
+  let source: HandoffFile | null = null;
+  if (extra.source) { await add(extra.source); source = { path: show(extra.source), sha256: files.get(show(extra.source))! }; }
+  for (const dir of [extra.full, extra.head]) if (dir) for (const file of await listed(base, dir, show(dir))) await add(file);
+  const sorted = [...files].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([path, hash]) => ({ path, sha256: hash }));
+  return {
+    record: { schema: HANDOFF_SCHEMA, how, via, outside: !inside(root, config), config: { path: show(config), sha256: files.get(show(config))! }, parts: parts ? show(parts) : null, rig: rig ? show(rig) : null, source, full: extra.full ? show(extra.full) : null, head: extra.head ? show(extra.head) : null, files: sorted, missing },
+    config, parts, rig, root: base, source: extra.source ?? null, full: extra.full ?? null, head: extra.head ?? null,
+  };
+}
+
+/**
+ * The one handoff lookup (used by load, identity and `/api/rebuild`): CLI flags, else the review.json block, else the
+ * fixed discovery order. `root` is the canonical package root (the opened folder). A declared path that is missing,
+ * outside its root or a symlink escape is refused by name; nothing found is `{handoff: null}` with the refusal line.
+ */
+export async function resolveHandoff(root: string, declared: HandoffDeclaration | undefined, flags: HandoffFlags | undefined): Promise<{ handoff: Handoff | null; reason: string | null }> {
+  if (flags) {
+    const problem = checkHandoffFlags(flags);
+    if (problem) throw new HandoffError('HANDOFF_FLAGS_INVALID', problem.split(':')[0]!, problem);
+    const config = await flagPath(root, flags.config, '--config', 'file');
+    const parts = flags.parts !== undefined ? await flagPath(root, flags.parts, '--parts', 'dir') : join(dirname(config), 'out');
+    const source = flags.source !== undefined ? await flagPath(root, flags.source, '--source', 'file') : undefined;
+    const full = flags.full !== undefined ? await flagPath(root, flags.full, '--full', 'dir') : undefined;
+    const head = flags.head !== undefined ? await flagPath(root, flags.head, '--head', 'dir') : undefined;
+    const handoff = await record(root, root, 'declared', 'open --config', config, parts, { source, full, head }, flags.parts !== undefined);
+    // Canonical absolute flags: the background worker and later reloads read exactly these.
+    handoff.flags = { config, ...(flags.parts !== undefined ? { parts } : {}), ...(source ? { source } : {}), ...(full ? { full } : {}), ...(head ? { head } : {}) };
+    return { handoff, reason: null };
+  }
+  if (declared) {
+    const config = await blockPath(root, declared.config, 'producer.config', 'file');
+    const parts = declared.parts !== undefined ? await blockPath(root, declared.parts, 'producer.parts', 'dir') : join(dirname(config), 'out');
+    const source = declared.source !== undefined ? await blockPath(root, declared.source, 'producer.source', 'file') : undefined;
+    const full = declared.full !== undefined ? await blockPath(root, declared.full, 'producer.full', 'dir') : undefined;
+    const head = declared.head !== undefined ? await blockPath(root, declared.head, 'producer.head', 'dir') : undefined;
+    if ((source === undefined) !== (full === undefined) || (head !== undefined && full === undefined)) throw new HandoffError('HANDOFF_FLAGS_INVALID', 'producer', 'source and full are given together, head only with them');
+    return { handoff: await record(root, root, 'declared', 'review.json producer', config, parts, { source, full, head }, declared.parts !== undefined), reason: null };
+  }
+  for (const name of ['config.json', 'rig/config.json']) {
+    const path = join(root, name);
+    if (!(await exists(path))) continue;
+    const config = await contained(root, path, name, 'file', true);
+    return { handoff: await record(root, root, 'discovered', 'discovery', config, join(dirname(path), 'out'), {}, false), reason: null };
+  }
+  // The last step: an opened `out/` whose config sits beside it, one level up. Outside the folder, so named.
+  if (basename(root) === 'out') {
+    const parent = dirname(root), path = join(parent, 'config.json');
+    if (await exists(path)) {
+      const config = await contained(parent, path, '../config.json', 'file', true);
+      if (config !== path) throw new HandoffError('HANDOFF_SYMLINK_ESCAPE', '../config.json', `${path} is a symlink; only the file beside out/ is discovered`);
+      return { handoff: await record(root, parent, 'discovered', 'discovery', config, root, {}, false), reason: null };
+    }
+  }
+  return { handoff: null, reason: MODELING_INPUT_UNAVAILABLE };
+}

package/src/idle-tracks.ts

@@ -0,0 +1,401 @@
+/**
+ * Idle tracks (#104), the pure half: the config's `motion.tracks` and `motion.blink` as the panel edits them, the sine
+ * the producer keys, the periods it accepts, review's pre-checks under the producer's own names and words, the pending
+ * edits as config patch ops at `/motion/tracks/<i>/…` and `/motion/blink/…`, and what the preview writes through play's
+ * `adjust`. No DOM, no IO, no clock: the producer (`rig --config`, then `check`) judges every value on Apply.
+ *
+ * The sine is rig-parts `src/motion.ts` `sineTrack`: `v(t) = base + amp·sin(2π(t/period − phase))`, keyed at
+ * `KEYS_PER_PERIOD` keys per period with the sine's exact Hermite tangents as bezier handles. A chain track keys
+ * `rotate` on every link, link `i` at phase `phase + lag·i` and amplitude `amps[i]`, about 0 (`idleMotion`).
+ */
+import { formatPointer, parsePointer, type JsonValue, type PatchOp } from './config-patch.ts';
+
+/** rig-parts `SINGLE_PROPS` (`src/config.ts`). */
+export const SINGLE_PROPS = ['rotate', 'translatex', 'translatey', 'scalex', 'scaley', 'shearx', 'sheary'] as const;
+export type SingleProp = typeof SINGLE_PROPS[number];
+/** rig-parts `KEYS_PER_PERIOD` and `IDLE_FPS` (`src/motion.ts`). */
+export const KEYS_PER_PERIOD = 8;
+export const IDLE_FPS = 12;
+/** rig-parts `periodFits` (`src/config.ts`): `duration / period` within this of a whole number. */
+export const PERIOD_SLACK = 1e-9;
+/** The periods the panel offers: `duration / n` for n = 1 … this. A typed period is still checked, never offered. */
+export const MAX_CYCLES_OFFERED = 12;
+/** rig-parts `BLINK` (`src/motion.ts`): the blink's fixed timing after `blink.t`, in seconds. */
+export const BLINK = { shut: 0.07, hold: 0.084, open: 0.16, browShut: 0.08, browHold: 0.084, browOpen: 0.2 } as const;
+/** rig-parts `blinkSpan`: the last blink key after `t`; without brows only the eyes' keys must fit inside the idle. */
+export const blinkSpan = (blink: { brows?: readonly string[] }) => blink.brows === undefined ? BLINK.shut + BLINK.hold + BLINK.open : Math.max(BLINK.shut + BLINK.hold + BLINK.open, BLINK.browShut + BLINK.browHold + BLINK.browOpen);
+/** rig-parts `CONTROL_SUFFIX`: under `--idle-keys ctl` a keyed bone a mesh is weighted to is keyed on `<bone>_ctl`. */
+export const CONTROL_SUFFIX = '_ctl';
+/** The check bars (and check's `loop:` line) the readout shows before and after an Apply. */
+export const IDLE_READOUT_BARS = ['CHAIN_LAG', 'TIP_OVER_ROOT', 'BREATH_VISIBLE', 'loop'] as const;
+/** Slider extents for the panel; every number field takes any finite value. */
+export const AMP_RANGE: Readonly<Record<SingleProp, { min: number; max: number; step: number }>> = {
+  rotate: { min: -10, max: 10, step: 0.05 }, translatex: { min: -10, max: 10, step: 0.1 }, translatey: { min: -10, max: 10, step: 0.1 },
+  scalex: { min: -0.05, max: 0.05, step: 0.001 }, scaley: { min: -0.05, max: 0.05, step: 0.001 }, shearx: { min: -10, max: 10, step: 0.1 }, sheary: { min: -10, max: 10, step: 0.1 },
+};
+
+export interface SingleTrack { bone: string; prop: SingleProp; amp: number; period: number; phase: number; base?: number }
+export interface ChainTrack { chain: string; amps: number[]; period: number; phase: number; lag: number }
+export type IdleTrack = SingleTrack | ChainTrack;
+export interface IdleBlink { t: number; eyes: string[]; brows?: string[]; squash: number; brow_drop?: number; [key: string]: JsonValue | undefined }
+export const isChain = (track: IdleTrack): track is ChainTrack => 'chain' in track;
+
+/** The handoff config's idle as written: duration, tracks (each as written), blink, and the bones and chains it declares. */
+export interface IdleSource { duration: number; tracks: IdleTrack[]; blink: IdleBlink | null; bones: string[]; chains: Record<string, number> }
+export type IdleSourceResult = { available: true; source: IdleSource } | { available: false; reason: string };
+/** One track of the edited idle: `origin` is its index in the handoff config (null for a track the panel added). */
+export interface IdleEntry { key: string; origin: number | null; track: IdleTrack }
+export interface IdleState { entries: IdleEntry[]; blink: IdleBlink | null }
+
+const isObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+const clone = <T>(v: T): T => structuredClone(v);
+const unavailable = (reason: string): IdleSourceResult => ({ available: false, reason: `IDLE_TRACKS_UNAVAILABLE: ${reason}` });
+
+/**
+ * Reads `config.motion` and `config.bones` (shapes only: what the panel needs to draw and edit). Anything the panel
+ * cannot read as the producer's track shapes makes the panel unavailable by name; values are the producer's to judge.
+ */
+export function idleSource(config: unknown): IdleSourceResult {
+  if (!isObject(config)) return unavailable('the handoff config is not an object');
+  const motion = config.motion;
+  if (!isObject(motion)) return unavailable('the handoff config states no motion');
+  if (!finite(motion.duration) || motion.duration <= 0) return unavailable('config.motion.duration is not a positive number');
+  if (!Array.isArray(motion.tracks)) return unavailable('config.motion.tracks is not a list');
+  const tracks: IdleTrack[] = [];
+  for (const [i, raw] of motion.tracks.entries()) {
+    if (!isObject(raw)) return unavailable(`config.motion.tracks[${i}] is not an object`);
+    if ('chain' in raw) {
+      if (typeof raw.chain !== 'string' || !Array.isArray(raw.amps) || !raw.amps.every(finite) || !finite(raw.period) || !finite(raw.phase) || !finite(raw.lag)) return unavailable(`config.motion.tracks[${i}] is not a chain track {chain, amps, period, phase, lag}`);
+    } else if (typeof raw.bone !== 'string' || !SINGLE_PROPS.includes(raw.prop as SingleProp) || !finite(raw.amp) || !finite(raw.period) || !finite(raw.phase) || ('base' in raw && !finite(raw.base))) {
+      return unavailable(`config.motion.tracks[${i}] is not a single track {bone, prop, amp, period, phase, base?}`);
+    }
+    tracks.push(clone(raw) as unknown as IdleTrack);
+  }
+  let blink: IdleBlink | null = null;
+  if (motion.blink !== undefined) {
+    const b = motion.blink;
+    if (!isObject(b) || !finite(b.t) || !finite(b.squash) || !Array.isArray(b.eyes)) return unavailable('config.motion.blink is not {t, eyes, squash, …}');
+    blink = clone(b) as unknown as IdleBlink;
+  }
+  const bones: string[] = [], chains: Record<string, number> = {};
+  for (const entry of Array.isArray(config.bones) ? config.bones : []) {
+    if (!isObject(entry)) continue;
+    if (typeof entry.chain === 'string' && Array.isArray(entry.points)) { chains[entry.chain] = entry.points.length; entry.points.forEach((_, k) => bones.push(`${entry.chain}${k}`)); }
+    else if (typeof entry.name === 'string') bones.push(entry.name);
+  }
+  return { available: true, source: { duration: motion.duration, tracks, blink, bones, chains } };
+}
+
+/** The state the panel starts from: every track as written, in order, keyed by its config index. */
+export const initialState = (source: IdleSource): IdleState => ({ entries: source.tracks.map((track, i) => ({ key: `o${i}`, origin: i, track: clone(track) })), blink: clone(source.blink) });
+
+/** The producer's sine (rig-parts `sineTrack`): `base + amp·sin(2π(t/period − phase))`. */
+export function sineValue(p: { amp: number; period: number; phase: number; base?: number }, t: number): number {
+  return (p.base ?? 0) + p.amp * Math.sin(2 * Math.PI * (t / p.period - p.phase));
+}
+/** A chain's link `i` as the producer keys it (rig-parts `idleMotion`): rotate at phase `phase + lag·i`, amplitude `amps[i]`, about 0. */
+export const linkSine = (track: ChainTrack, i: number) => ({ amp: track.amps[i]!, period: track.period, phase: track.phase + track.lag * i, base: 0 });
+
+/** rig-parts `periodFits`: true when `duration / period` is within 1e-9 of a whole number (and the period is positive). */
+export function periodFits(duration: number, period: number): boolean {
+  if (!finite(period) || period <= 0) return false;
+  const cycles = duration / period;
+  return Math.abs(cycles - Math.round(cycles)) <= PERIOD_SLACK;
+}
+/**
+ * The periods offered: exactly the ones the producer accepts. `duration / period` must be a whole number n (periodFits),
+ * so a period is `duration / n`; n = 0 is no period, so n runs from 1 (the whole idle) up to `MAX_CYCLES_OFFERED`.
+ */
+export function periodOffers(duration: number, max = MAX_CYCLES_OFFERED): { cycles: number; period: number }[] {
+  return Array.from({ length: max }, (_, i) => ({ cycles: i + 1, period: duration / (i + 1) }));
+}
+
+/** rig-parts `pyRound` for the numbers its lines print (`toFixed` rounding; an exact binary tie is not reproduced). */
+const round6 = (x: number) => Number(x.toFixed(6));
+/** The producer's refusal line without its `FAIL  ` lead and its `(see rig-parts guide …)` tail: `CODE: object — detail`. */
+export const producerLine = (code: string, object: string, detail: string) => `${code}: ${object} — ${detail}`;
+
+/** The patched config's track order: the kept tracks in config order, then the added ones (the ops apply in that order). */
+export const orderedEntries = (state: IdleState) => [...state.entries.filter(e => e.origin !== null).sort((a, b) => a.origin! - b.origin!), ...state.entries.filter(e => e.origin === null)];
+
+/**
+ * Review's pre-checks, run before Apply on the idle the patch would produce, under the producer's names and in its words
+ * (rig-parts `checkMotion`, `refuseSharedTargets`, the rig stage's `RIG_BLINK_INSIDE_IDLE`). Each line is the producer's
+ * own line for the same config, less its `FAIL  ` lead and guide tail. Empty when none applies; the producer still
+ * judges everything on Apply (`RIG_KEY_FRAME_UNTURNED` and `RIG_BLINK_HOLD_SPANS_A_FRAME` are left to it).
+ */
+export function precheck(source: IdleSource, state: IdleState): string[] {
+  const out: string[] = [], p = 'config.motion', duration = source.duration, bones = new Set(source.bones);
+  const claims = new Map<string, string[]>();
+  const claim = (target: string, by: string) => claims.set(target, [...(claims.get(target) ?? []), by]);
+  const periodLine = (at: string, period: number) => {
+    if (!finite(period) || period <= 0 || periodFits(duration, period)) return;
+    out.push(producerLine('CONFIG_PERIOD_DIVIDES_DURATION', at, `is ${period} s against a ${duration} s idle, ${(duration / period).toFixed(4)} cycles; a whole number of cycles is required or the loop's last frame is not its first`));
+  };
+  orderedEntries(state).forEach(({ track }, i) => {
+    const at = `${p}.tracks[${i}]`;
+    if (isChain(track)) {
+      periodLine(`${at}.period`, track.period);
+      const links = source.chains[track.chain];
+      if (links === undefined) out.push(producerLine('CONFIG_NAME_RESOLVES', `${at}.chain`, `is ${JSON.stringify(track.chain)}; a chain declared in config.bones is required`));
+      else for (let k = 0; k < links; k++) claim(`${track.chain}${k}.rotate`, `${at} (chain "${track.chain}", link ${k})`);
+      return;
+    }
+    if (!bones.has(track.bone)) out.push(producerLine('CONFIG_NAME_RESOLVES', `${at}.bone`, `is ${JSON.stringify(track.bone)}; a declared bone is required`));
+    else claim(`${track.bone}.${track.prop}`, at);
+    periodLine(`${at}.period`, track.period);
+  });
+  const blink = state.blink;
+  if (blink) {
+    const groups: ['eyes' | 'brows', string][] = [['eyes', 'scaley'], ...(blink.brows !== undefined && blink.brow_drop !== undefined ? [['brows', 'translatey'] as ['brows', string]] : [])];
+    for (const [key, prop] of groups) {
+      const first = new Map<string, number>();
+      (blink[key] ?? []).forEach((name, k) => { if (!first.has(name)) first.set(name, k); });
+      for (const [name, k] of first) if (bones.has(name)) claim(`${name}.${prop}`, `${p}.blink.${key}[${k}] (the blink's ${key} group, which keys ${prop} on every member)`);
+    }
+  }
+  for (const [target, by] of claims) {
+    if (by.length < 2) continue;
+    out.push(producerLine('CONFIG_BONE_PROPERTY_KEYED_ONCE', `bone property "${target}"`, `is keyed by ${by.length} tracks: ${by.join(' and ')}; one track per bone property is required — the idle would hold ${by.length} timelines on ${target}, and rigc refuses two tracks on one bone property. Merge them into one track, or key another property or bone`));
+  }
+  if (blink) {
+    const span = blinkSpan(blink);
+    if (!(blink.t > 0 && blink.t + span < duration)) out.push(producerLine('RIG_BLINK_INSIDE_IDLE', `${p}.blink.t`, `is ${blink.t} s; the blink's keys run from t to t + ${round6(span)} s between the idle's first key at 0 and its last at ${duration} s, so 0 < t < ${round6(duration - span)} is required`));
+  }
+  return out;
+}
+
+// ---- edits (immutable) -------------------------------------------------------------------------------------------
+
+const entryOf = (state: IdleState, key: string) => { const e = state.entries.find(x => x.key === key); if (!e) throw new Error(`IDLE_TRACK_UNKNOWN: ${key}`); return e; };
+const replaceEntry = (state: IdleState, key: string, track: IdleTrack): IdleState => ({ ...state, entries: state.entries.map(e => e.key === key ? { ...e, track } : e) });
+const assertFinite = (value: number, what: string) => { if (!finite(value)) throw new Error(`IDLE_VALUE_INVALID: ${what} must be a finite number`); };
+
+export type SingleField = 'amp' | 'period' | 'phase' | 'base';
+export type ChainField = 'period' | 'phase' | 'lag';
+/** Set one field of a track. `base: null` takes the field out (the sine about 0, as an absent base is written). */
+export function setField(state: IdleState, key: string, field: SingleField | ChainField, value: number | null): IdleState {
+  const entry = entryOf(state, key), track = clone(entry.track) as unknown as Record<string, unknown>;
+  if (isChain(entry.track) ? !['period', 'phase', 'lag'].includes(field) : !['amp', 'period', 'phase', 'base'].includes(field)) throw new Error(`IDLE_FIELD_UNKNOWN: ${field} is not a field of a ${isChain(entry.track) ? 'chain' : 'single'} track`);
+  if (value === null) { if (field !== 'base') throw new Error(`IDLE_VALUE_INVALID: ${field} cannot be absent`); delete track.base; }
+  else { assertFinite(value, field); track[field] = value; }
+  return replaceEntry(state, key, track as unknown as IdleTrack);
+}
+/** Set one chain link's amplitude (`amps[link]`). */
+export function setLinkAmp(state: IdleState, key: string, link: number, value: number): IdleState {
+  const entry = entryOf(state, key);
+  if (!isChain(entry.track)) throw new Error(`IDLE_FIELD_UNKNOWN: ${key} is not a chain track`);
+  if (!Number.isInteger(link) || link < 0 || link >= entry.track.amps.length) throw new Error(`IDLE_LINK_UNKNOWN: link ${link} of ${entry.track.chain}`);
+  assertFinite(value, `amps[${link}]`);
+  const amps = [...entry.track.amps]; amps[link] = value;
+  return replaceEntry(state, key, { ...entry.track, amps });
+}
+/**
+ * Add a track: a single track on `bone`/`prop`, or a chain track on a declared chain (one amplitude per link). It starts
+ * still (amplitude 0) on the whole idle's period at phase 0, so adding it changes nothing until a value is set.
+ */
+export function addTrack(source: IdleSource, state: IdleState, spec: { bone: string; prop: string } | { chain: string }): IdleState {
+  let track: IdleTrack;
+  if ('chain' in spec) {
+    const links = source.chains[spec.chain];
+    if (links === undefined) throw new Error(`IDLE_CHAIN_UNKNOWN: ${spec.chain} is not a chain config.bones declares`);
+    track = { chain: spec.chain, amps: Array.from({ length: links }, () => 0), period: source.duration, phase: 0, lag: 0 };
+  } else {
+    if (!SINGLE_PROPS.includes(spec.prop as SingleProp)) throw new Error(`IDLE_PROP_UNKNOWN: ${spec.prop} (one of ${SINGLE_PROPS.join(', ')})`);
+    if (!spec.bone) throw new Error('IDLE_BONE_UNKNOWN: name a bone');
+    track = { bone: spec.bone, prop: spec.prop as SingleProp, amp: 0, period: source.duration, phase: 0 };
+  }
+  const n = Math.max(-1, ...state.entries.filter(e => e.origin === null).map(e => Number(e.key.slice(1)))) + 1;
+  return { ...state, entries: [...state.entries, { key: `n${n}`, origin: null, track }] };
+}
+export function removeTrack(state: IdleState, key: string): IdleState { entryOf(state, key); return { ...state, entries: state.entries.filter(e => e.key !== key) }; }
+export type BlinkField = 't' | 'squash' | 'brow_drop';
+export function setBlink(state: IdleState, field: BlinkField, value: number): IdleState {
+  if (!state.blink) throw new Error('IDLE_BLINK_ABSENT: the config states no motion.blink');
+  if (field === 'brow_drop' && state.blink.brow_drop === undefined) throw new Error('IDLE_BLINK_ABSENT: the config states no blink.brow_drop (no brows group)');
+  assertFinite(value, `blink.${field}`);
+  return { ...state, blink: { ...state.blink, [field]: value } };
+}
+
+// ---- ops ---------------------------------------------------------------------------------------------------------
+
+/** The order fields are diffed in (then any other key, sorted), so the same edit always gives the same ops. */
+const FIELD_ORDER = ['bone', 'prop', 'chain', 'amp', 'amps', 'period', 'phase', 'lag', 'base', 't', 'squash', 'brow_drop'];
+const keyOrder = (a: Record<string, unknown>, b: Record<string, unknown>) => { const all = [...new Set([...Object.keys(a), ...Object.keys(b)])]; return [...FIELD_ORDER.filter(k => all.includes(k)), ...all.filter(k => !FIELD_ORDER.includes(k)).sort()]; };
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
+function diffObject(path: (string | number)[], before: Record<string, unknown>, after: Record<string, unknown>, ops: PatchOp[]): void {
+  for (const k of keyOrder(before, after)) {
+    const had = Object.hasOwn(before, k), has = Object.hasOwn(after, k), at = formatPointer([...path, k]);
+    if (had && !has) ops.push({ op: 'remove', path: at });
+    else if (!had && has) ops.push({ op: 'add', path: at, value: clone(after[k]) as JsonValue });
+    else if (!same(before[k], after[k])) {
+      const x = before[k], y = after[k];
+      if (k === 'amps' && Array.isArray(x) && Array.isArray(y) && x.length === y.length) y.forEach((v, i) => { if (!same(x[i], v)) ops.push({ op: 'replace', path: formatPointer([...path, k, i]), value: v as JsonValue }); });
+      else ops.push({ op: 'replace', path: at, value: clone(y) as JsonValue });
+    }
+  }
+}
+/**
+ * The pending edits as config patch ops, applied in order: field ops on the kept tracks at their config index, then the
+ * removed tracks from the highest index down, then the added tracks appended (`add /motion/tracks/-`), then the blink's
+ * fields. Empty when the state is the config's own.
+ */
+export function idleOps(source: IdleSource, state: IdleState): PatchOp[] {
+  const ops: PatchOp[] = [];
+  const kept = state.entries.filter(e => e.origin !== null).sort((a, b) => a.origin! - b.origin!);
+  for (const e of kept) diffObject(['motion', 'tracks', e.origin!], source.tracks[e.origin!] as unknown as Record<string, unknown>, e.track as unknown as Record<string, unknown>, ops);
+  const keptOrigins = new Set(kept.map(e => e.origin));
+  for (let i = source.tracks.length - 1; i >= 0; i--) if (!keptOrigins.has(i)) ops.push({ op: 'remove', path: formatPointer(['motion', 'tracks', i]) });
+  for (const e of state.entries.filter(x => x.origin === null)) ops.push({ op: 'add', path: '/motion/tracks/-', value: clone(e.track) as unknown as JsonValue });
+  if (source.blink && state.blink) diffObject(['motion', 'blink'], source.blink as Record<string, unknown>, state.blink as Record<string, unknown>, ops);
+  return ops;
+}
+
+/**
+ * The state back from ops (the draft, a submitted patch): the inverse of `idleOps`. Refused by name unless the ops are
+ * exactly what `idleOps` writes for the state they give back — a hand-made op the panel cannot show is never half-read.
+ */
+export function stateFromOps(source: IdleSource, ops: readonly PatchOp[]): IdleState {
+  let state = initialState(source);
+  const tracks = new Map(state.entries.map(e => [e.origin!, clone(e.track) as unknown as Record<string, JsonValue>]));
+  const removed = new Set<number>(), added: IdleTrack[] = [];
+  let blink = clone(state.blink) as Record<string, JsonValue> | null;
+  const bad = (i: number, why: string): never => { throw new Error(`IDLE_DRAFT_UNREADABLE: ops[${i}] ${why}`); };
+  ops.forEach((op, i) => {
+    const t = parsePointer(op.path);
+    if (t[0] !== 'motion') bad(i, `${op.path} is not under /motion`);
+    if (t[1] === 'tracks') {
+      if (t.length === 3 && t[2] === '-' && op.op === 'add') { added.push(clone(op.value) as unknown as IdleTrack); return; }
+      const index = Number(t[2]);
+      if (!/^(0|[1-9][0-9]*)$/.test(t[2] ?? '') || !tracks.has(index)) bad(i, `${op.path} names no config track`);
+      if (t.length === 3 && op.op === 'remove') { removed.add(index); return; }
+      const track = tracks.get(index)!;
+      if (t.length === 4) { if (op.op === 'remove') delete track[t[3]!]; else track[t[3]!] = clone(op.value!); return; }
+      if (t.length === 5 && t[3] === 'amps' && Array.isArray(track.amps) && op.op === 'replace') { track.amps[Number(t[4])] = clone(op.value!); return; }
+      bad(i, `${op.op} ${op.path} is not an idle track edit`);
+    }
+    if (t[1] === 'blink' && t.length === 3 && blink) { if (op.op === 'remove') delete blink[t[2]!]; else blink[t[2]!] = clone(op.value!); return; }
+    bad(i, `${op.op} ${op.path} is not an idle edit`);
+  });
+  state = { entries: [...[...tracks].filter(([i]) => !removed.has(i)).map(([i, track]) => ({ key: `o${i}`, origin: i, track: track as unknown as IdleTrack })), ...added.map((track, k) => ({ key: `n${k}`, origin: null, track }))], blink: blink as IdleBlink | null };
+  if (!same(idleOps(source, state), ops)) throw new Error('IDLE_DRAFT_UNREADABLE: the ops are not the ones the panel writes for the idle they describe');
+  return state;
+}
+
+/** Whether a track differs from the config's own (a new track always does). */
+export function entryChanged(source: IdleSource, entry: IdleEntry): boolean { return entry.origin === null || !same(source.tracks[entry.origin], entry.track); }
+
+/** The draft's record of the panel: the pending ops (nothing about the preview). */
+export const IDLE_DRAFT_SCHEMA = 'rig-review-idle-draft/1';
+export const idleDraftText = (ops: readonly PatchOp[]) => JSON.stringify({ schema: IDLE_DRAFT_SCHEMA, ops });
+/** The state a draft records, or the config's own when the draft is absent, foreign or no longer applies. */
+export function idleDraftState(text: string, source: IdleSource): IdleState {
+  try {
+    const doc = JSON.parse(text) as unknown;
+    if (!isObject(doc) || doc.schema !== IDLE_DRAFT_SCHEMA || !Array.isArray(doc.ops)) return initialState(source);
+    return stateFromOps(source, doc.ops as PatchOp[]);
+  } catch { return initialState(source); }
+}
+
+// ---- which bone the idle keys, and what the preview writes ---------------------------------------------------------
+
+/**
+ * Where the inspected idle keys each config track (#104): read off the handoff rig's `motion.json` (the idle's track
+ * bones) and `rig.json` (`invariants.idleDrivesMeshes`, which `rig --idle-keys direct` declares). `keyed` maps
+ * `<config bone>.<prop>` to the bone the idle keys — `<bone>_ctl` when the rig stage moved the keys to a control.
+ */
+/** `GET /api/rebuild`'s `idle`: the config's idle and where the inspected idle keys it. */
+export interface IdleStatus { source: IdleSourceResult; keying: IdleKeying | { error: string } }
+export interface IdleKeying { keys: 'ctl' | 'direct'; source: string; keyed: Record<string, string>; controls: string[] }
+export function idleKeying(rig: unknown, motion: unknown): IdleKeying | { error: string } {
+  if (!isObject(rig) || !Array.isArray(rig.bones)) return { error: 'IDLE_KEYS_UNKNOWN: the handoff rig.json has no bones list' };
+  const idle = isObject(motion) && isObject(motion.animations) ? motion.animations.idle : undefined;
+  if (!isObject(idle) || !Array.isArray(idle.tracks)) return { error: 'IDLE_KEYS_UNKNOWN: the handoff motion.json has no idle' };
+  const parent = new Map<string, string | null>(rig.bones.filter(isObject).map(b => [String(b.name), typeof b.parent === 'string' ? b.parent : null]));
+  // A control is `<bone>_ctl` whose child `<bone>` it parents (rig-parts `moveKeysToControls`).
+  const configBone = (keyed: string) => keyed.endsWith(CONTROL_SUFFIX) && parent.get(keyed.slice(0, -CONTROL_SUFFIX.length)) === keyed ? keyed.slice(0, -CONTROL_SUFFIX.length) : keyed;
+  const keyed: Record<string, string> = {}, groups = isObject(motion) && isObject(motion.groups) ? motion.groups : {};
+  for (const t of idle.tracks) {
+    if (!isObject(t) || typeof t.property !== 'string') continue;
+    const members = typeof t.bone === 'string' ? [t.bone] : typeof t.group === 'string' && Array.isArray(groups[t.group]) ? (groups[t.group] as unknown[]).filter((m): m is string => typeof m === 'string') : [];
+    for (const m of members) keyed[`${configBone(m)}.${t.property}`] = m;
+  }
+  const controls = [...parent.keys()].filter(n => configBone(n) !== n).sort();
+  const direct = isObject(rig.invariants) && rig.invariants.idleDrivesMeshes !== undefined;
+  return direct
+    ? { keys: 'direct', source: 'rig.json declares invariants.idleDrivesMeshes (rig --idle-keys direct)', keyed, controls }
+    : { keys: 'ctl', source: `rig.json declares no invariants.idleDrivesMeshes, so the rig was built under --idle-keys ctl (the producer's default; a rig with no mesh-bound keyed bone is the same under both)${controls.length ? `; the idle keys ${controls.length} control(s): ${controls.join(', ')}` : ''}`, keyed, controls };
+}
+
+/**
+ * The bone the preview drives for `<bone>.<prop>`: the bone the inspected idle keys for it; else, for a property the
+ * idle does not key yet, the bone itself under direct keys, `<bone>_ctl` when the model already has that control, the
+ * bone itself when the idle keys it directly on another property (no mesh is weighted to it). Otherwise review cannot
+ * know whether the producer adds a control, and the preview is refused by name.
+ */
+export function previewTarget(bone: string, prop: string, keying: IdleKeying, modelBones: ReadonlySet<string>): { bone: string } | { refusal: string } {
+  const known = keying.keyed[`${bone}.${prop}`];
+  let target: string | null = known ?? null;
+  if (target === null) {
+    if (keying.keys === 'direct') target = bone;
+    else if (modelBones.has(bone + CONTROL_SUFFIX)) target = bone + CONTROL_SUFFIX;
+    else if (Object.values(keying.keyed).includes(bone)) target = bone;
+  }
+  if (target === null) return { refusal: `IDLE_PREVIEW_TARGET_UNKNOWN: ${bone}.${prop} is not keyed by the inspected idle; under --idle-keys ctl the producer keys ${bone}${CONTROL_SUFFIX} instead when a mesh is weighted to ${bone}, which review does not decide — Apply decides` };
+  if (!modelBones.has(target)) return { refusal: `IDLE_PREVIEW_BONE_ABSENT: ${target} is not a bone of the drawn model — Apply decides` };
+  return { bone: target };
+}
+
+export type LocalChannel = 'rotation' | 'x' | 'y' | 'scaleX' | 'scaleY' | 'shearX' | 'shearY';
+/** The bone local a property keys (play's `BoneLocals`). */
+export const CHANNEL: Readonly<Record<SingleProp, LocalChannel>> = { rotate: 'rotation', translatex: 'x', translatey: 'y', scalex: 'scaleX', scaley: 'scaleY', shearx: 'shearX', sheary: 'shearY' };
+/** play's `LOCAL_CHANNELS`: a channel a bone does not state. */
+export const SETUP_DEFAULT: Readonly<Record<LocalChannel, number>> = { rotation: 0, x: 0, y: 0, scaleX: 1, scaleY: 1, shearX: 0, shearY: 0 };
+/** A keyed value as the bone local it poses (the Spine runtime's timelines, setup blend): a scale multiplies the setup, the rest add. */
+export const localValue = (prop: SingleProp, setup: number, v: number) => prop === 'scalex' || prop === 'scaley' ? setup * v : setup + v;
+/** A property with no track: the bone holds its setup value. */
+export const STILL: Readonly<Record<SingleProp, number>> = { rotate: 0, translatex: 0, translatey: 0, scalex: 1, scaley: 1, shearx: 0, sheary: 0 };
+
+export interface PreviewWrite { bone: string; channel: LocalChannel; prop: SingleProp; sine: { amp: number; period: number; phase: number; base: number } | null }
+export interface PreviewPlan { writes: PreviewWrite[]; refusals: string[]; tracks: number }
+/**
+ * What the preview drives: every changed or added track (each chain link), and a removed track's bones held still. Each
+ * write names the bone the idle keys (`previewTarget`) and its sine; a target review cannot know is refused by name and
+ * left to Apply. Blink edits are not previewed (their keys are eased, not sines).
+ */
+export function previewPlan(source: IdleSource, state: IdleState, keying: IdleKeying, modelBones: ReadonlySet<string>): PreviewPlan {
+  const writes: PreviewWrite[] = [], refusals: string[] = [];
+  const add = (bone: string, prop: SingleProp, sine: PreviewWrite['sine']) => {
+    const target = previewTarget(bone, prop, keying, modelBones);
+    if ('refusal' in target) refusals.push(target.refusal); else writes.push({ bone: target.bone, channel: CHANNEL[prop], prop, sine });
+  };
+  const each = (track: IdleTrack, sine: (bone: string, prop: SingleProp, p: { amp: number; period: number; phase: number; base: number }) => void) => {
+    if (isChain(track)) track.amps.forEach((_, i) => sine(`${track.chain}${i}`, 'rotate', linkSine(track, i)));
+    else sine(track.bone, track.prop, { amp: track.amp, period: track.period, phase: track.phase, base: track.base ?? 0 });
+  };
+  let tracks = 0;
+  const kept = new Set(state.entries.map(e => e.origin));
+  source.tracks.forEach((track, i) => { if (!kept.has(i)) { tracks++; each(track, (bone, prop) => add(bone, prop, null)); } });
+  for (const entry of state.entries) if (entryChanged(source, entry)) { tracks++; each(entry.track, (bone, prop, p) => add(bone, prop, p)); }
+  return { writes, refusals, tracks };
+}
+/** The local a write holds at idle time `t` (`setup` is the bone's setup value of the channel). */
+export function previewLocal(write: PreviewWrite, setup: number, t: number): number {
+  return localValue(write.prop, setup, write.sine ? sineValue(write.sine, t) : STILL[write.prop]);
+}
+
+/**
+ * Bar 1's bound, derived from how the producer keys a sine before measuring: within one key span h = period/8 the
+ * bezier with the exact Hermite tangents is the cubic Hermite interpolant, off the sine by at most
+ * h⁴/384·max|v⁗| = |amp|·(π/4)⁴/384; the runtime draws a bezier as 10 straight pieces (`BEZIER_PIECES`), off the
+ * curve by at most (h/10)²/8·max|v''| = |amp|·(π/40)²/8; values and handles are written to 4 decimals (5e-5 between
+ * them, a convex combination) and times to 6 (5e-7 s at slope |amp|·2π/period); the runtime holds the pieces' points
+ * as float32 (`Math.fround`, 2⁻²⁴ relative: |base| + |amp| in value, `duration` in time at that slope). In the
+ * local's units: × |setup| for a scale, and two float32 roundings of the setup-sized local (2·2⁻²⁴·|setup|).
+ */
+export function keySamplingBound(p: { amp: number; period: number; base?: number }, duration: number, prop: SingleProp = 'rotate', setup = 1): number {
+  const a = Math.abs(p.amp), slope = a * 2 * Math.PI / p.period, f32 = 2 ** -24;
+  const v = a * (Math.PI / 4) ** 4 / 384 + a * (Math.PI / 40) ** 2 / 8 + 5e-5 + slope * 5e-7 + (Math.abs(p.base ?? 0) + a) * f32 + slope * duration * f32;
+  return (prop === 'scalex' || prop === 'scaley' ? Math.abs(setup) * (v + (Math.abs(p.base ?? 0) + a) * f32) : v) + Math.abs(setup) * 2 * f32 + 1e-9;
+}