@rig-c/review 0.7.1 → 0.8.1

package/src/cloth-recipe.ts

@@ -0,0 +1,199 @@
+/**
+ * Cloth recipe form (#111): the producer config's `cloth` block — one recipe per tag (`bottomwear`, `back hair`,
+ * `front hair`, whatever the installed reader accepts) — edited as config patch ops at `/cloth/<tag>/…`. An Apply runs
+ * the installed producer's `rig-parts propose --cloth <patched config> --keypoints <handoff keypoints> --write-config
+ * <scratch>/config.json`, which writes the config's own text with what the recipe drafts spliced in (rig-parts
+ * AUTHORING, *The config written*, issues #537 and #552), then builds that written config through the shared tail.
+ * Review never reads the producer's draft file and never merges a draft itself: the written config is the producer's
+ * one output review consumes. Pure: no IO.
+ */
+import { formatPointer, jsonDiff, parsePointer, type JsonValue, type PatchOp } from './config-patch.ts';
+
+/** The first `@rig-c/parts` release whose `propose --cloth --write-config` splices bones, constraints and tracks entry by entry (its CHANGELOG: 1.49.1, parts#552). */
+export const CLOTH_WRITE_SINCE = '1.49.1';
+/** The config section a cloth patch edits. */
+export const CLOTH_PATH = 'cloth';
+/** Decision 1 (#111): without the declared keypoints the draft moves the body bones, so a cloth Apply is refused before anything runs. */
+export const CLOTH_KEYPOINTS_UNDECLARED = 'CLOTH_KEYPOINTS_UNDECLARED: a cloth recipe Apply runs rig-parts propose, which places the body bones from the figure\'s keypoints; without them the draft moves the body bones the config states — declare the keypoint file with rig-review open <dir> --config <path> --keypoints <file> or the review.json "producer" block\'s "keypoints"';
+/** A cloth patch holds only `/cloth` ops: what else the patch edits would be routed and gated differently. */
+export const CLOTH_PATCH_MIXED = 'CLOTH_PATCH_MIXED: a cloth recipe patch holds /cloth ops only; apply the other edits separately';
+/** propose reads the painting the parts were assembled from (`--source`). */
+export const CLOTH_SOURCE_UNAVAILABLE = 'MODELING_INPUT_UNAVAILABLE: source painting — rig-parts propose reads the painting the parts were assembled from (--source), and the handoff declares none; declare it with rig-review open <dir> --config <path> --source <png> --full <dir> [--head <dir>] or the review.json "producer" block';
+
+const isObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+const under = (tokens: readonly string[], prefix: readonly string[]) => prefix.length <= tokens.length && prefix.every((t, i) => tokens[i] === t);
+
+/** True when the op's pointer lies under `/cloth` (the whole block included). */
+export const isClothOp = (op: Pick<PatchOp, 'path'>) => parsePointer(op.path)[0] === CLOTH_PATH;
+/** `cloth` when every op is a cloth op, `mixed` when some are, else `none`. */
+export function clothPatchKind(ops: readonly Pick<PatchOp, 'path'>[]): 'cloth' | 'mixed' | 'none' {
+  const n = ops.filter(isClothOp).length;
+  return n === 0 ? 'none' : n === ops.length ? 'cloth' : 'mixed';
+}
+
+/**
+ * The tags the installed reader accepts, read from its own source text (`export const CLOTH_TARGETS = [...]`), or null
+ * when the text does not state them in that form.
+ */
+export function readClothTargets(sourceText: string): string[] | null {
+  const m = /export const CLOTH_TARGETS\s*=\s*\[([^\]]*)\]/.exec(sourceText);
+  if (!m) return null;
+  const tags = [...m[1]!.matchAll(/'([^']+)'|"([^"]+)"/g)].map(x => x[1] ?? x[2]!);
+  return tags.length ? tags : null;
+}
+
+/** One recipe field the form edits: its pointer below `/cloth/<tag>` and how it is typed. The producer judges every value. */
+export interface RecipeField { key: string; path: readonly string[]; kind: 'int' | 'number' | 'bool' | 'pair' | 'list' | 'names' | 'shape'; label: string; required?: boolean }
+/** The reader's fields (rig-parts `checkCloth`, AUTHORING §3 `cloth` row), in its order. */
+export const RECIPE_FIELDS: readonly RecipeField[] = [
+  { key: 'chains', path: ['chains'], kind: 'int', label: 'chains' },
+  { key: 'links', path: ['links'], kind: 'int', label: 'links', required: true },
+  { key: 'split.at', path: ['split', 'at'], kind: 'int', label: 'split at' },
+  { key: 'split.into', path: ['split', 'into'], kind: 'int', label: 'split into' },
+  { key: 'split.hold_tip', path: ['split', 'hold_tip'], kind: 'bool', label: 'hold tip' },
+  { key: 'length_ratio', path: ['length_ratio'], kind: 'number', label: 'length ratio' },
+  { key: 'strength.trunk', path: ['strength', 'trunk'], kind: 'number', label: 'strength trunk' },
+  { key: 'strength.branch', path: ['strength', 'branch'], kind: 'number', label: 'strength branch' },
+  { key: 'strength.edge', path: ['strength', 'edge'], kind: 'number', label: 'strength edge' },
+  { key: 'damping', path: ['damping'], kind: 'number', label: 'damping' },
+  { key: 'alternate_damping', path: ['alternate_damping'], kind: 'number', label: 'alternate damping' },
+  { key: 'wind', path: ['wind'], kind: 'pair', label: 'wind [root, tip]', required: true },
+  { key: 'gravity', path: ['gravity'], kind: 'pair', label: 'gravity [root, tip]', required: true },
+  { key: 'translate', path: ['translate'], kind: 'number', label: 'translate' },
+  { key: 'swing.scales', path: ['swing', 'scales'], kind: 'list', label: 'swing scales' },
+  { key: 'part', path: ['part'], kind: 'names', label: 'part' },
+  { key: 'parts', path: ['parts'], kind: 'names', label: 'parts' },
+  { key: 'influence.across', path: ['influence', 'across'], kind: 'bool', label: 'influence across' },
+  { key: 'influence.max', path: ['influence', 'max'], kind: 'int', label: 'influence max' },
+  { key: 'influence.shape', path: ['influence', 'shape'], kind: 'shape', label: 'influence shape' },
+  { key: 'influence.radius', path: ['influence', 'radius'], kind: 'number', label: 'influence radius' },
+];
+
+export class ClothFieldError extends Error { constructor(readonly field: string, detail: string) { super(`CLOTH_FIELD_INVALID ${field}: ${detail}`); } }
+
+/** A field's text as the form shows it, from the recipe as written ('' when absent). */
+export function fieldText(recipe: unknown, field: RecipeField): string {
+  let v: unknown = recipe;
+  for (const k of field.path) v = isObject(v) ? v[k] : undefined;
+  if (v === undefined) return '';
+  if (field.kind === 'pair' || field.kind === 'list') return Array.isArray(v) ? v.join(', ') : JSON.stringify(v);
+  if (field.kind === 'names') return Array.isArray(v) ? v.join(', ') : String(v);
+  return typeof v === 'string' ? v : JSON.stringify(v);
+}
+
+/** A field's typed value from the form's text; `undefined` for an empty field. Only the type is checked here. */
+export function fieldValue(field: RecipeField, text: string): JsonValue | undefined {
+  const raw = text.trim();
+  if (!raw) return undefined;
+  const num = (s: string) => { const n = Number(s.trim()); if (!s.trim() || !Number.isFinite(n)) throw new ClothFieldError(field.key, `${JSON.stringify(s.trim())} is not a number`); return n; };
+  switch (field.kind) {
+    case 'int': { const n = num(raw); if (!Number.isInteger(n)) throw new ClothFieldError(field.key, `${raw} is not a whole number`); return n; }
+    case 'number': return num(raw);
+    case 'bool': if (raw === 'true' || raw === 'false') return raw === 'true'; throw new ClothFieldError(field.key, 'true or false');
+    case 'shape': return raw;
+    case 'pair': { const parts = raw.split(',').map(num); if (parts.length !== 2) throw new ClothFieldError(field.key, 'two numbers, root and tip'); return parts; }
+    case 'list': return raw.split(',').map(num);
+    case 'names': { const names = raw.split(',').map(s => s.trim()).filter(Boolean); return field.key === 'part' && names.length === 1 && !raw.includes(',') ? names[0]! : names; }
+  }
+}
+
+/** The recipe object the form states: every non-empty field set at its path; `{}` when every field is empty. */
+export function recipeFromFields(values: Readonly<Record<string, string>>): Record<string, JsonValue> {
+  const out: Record<string, JsonValue> = {};
+  for (const f of RECIPE_FIELDS) {
+    const v = fieldValue(f, values[f.key] ?? '');
+    if (v === undefined) continue;
+    let holder = out;
+    for (const k of f.path.slice(0, -1)) { if (!isObject(holder[k])) holder[k] = {}; holder = holder[k] as Record<string, JsonValue>; }
+    holder[f.path.at(-1)!] = v;
+  }
+  return out;
+}
+
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
+/**
+ * The ops that turn the config's recipe for `tag` into `next` (null: the tag's recipe removed). Keys the form does not
+ * know (an annotation, a record) are kept: only form keys are replaced, added or removed. A tag the config does not
+ * state is added whole; a config without a `cloth` block gets one.
+ */
+export function recipeOps(config: unknown, tag: string, next: Record<string, JsonValue> | null): PatchOp[] {
+  const cloth = isObject(config) ? config.cloth : undefined;
+  const current = isObject(cloth) ? cloth[tag] : undefined;
+  const at = (...tokens: string[]) => formatPointer([CLOTH_PATH, tag, ...tokens]);
+  if (next === null) return current === undefined ? [] : [{ op: 'remove', path: at() }];
+  if (!isObject(cloth)) return [{ op: 'add', path: formatPointer([CLOTH_PATH]), value: { [tag]: next } }];
+  if (!isObject(current)) return [{ op: current === undefined ? 'add' : 'replace', path: at(), value: next }];
+  const known = new Set(RECIPE_FIELDS.map(f => f.path[0]!));
+  const ops: PatchOp[] = [];
+  for (const key of [...new Set([...Object.keys(current), ...Object.keys(next)])]) {
+    if (!known.has(key)) continue;
+    const was = current[key], now = next[key];
+    if (same(was, now)) continue;
+    if (now === undefined) { ops.push({ op: 'remove', path: at(key) }); continue; }
+    if (was === undefined) { ops.push({ op: 'add', path: at(key), value: now }); continue; }
+    // An object field (split, strength, swing, influence) is edited key by key, so its other keys keep their place.
+    if (isObject(was) && isObject(now)) {
+      for (const sub of [...new Set([...Object.keys(was), ...Object.keys(now)])]) {
+        if (same(was[sub], now[sub])) continue;
+        const known2 = RECIPE_FIELDS.some(f => f.path[0] === key && f.path[1] === sub);
+        if (!known2) continue;
+        if (now[sub] === undefined) ops.push({ op: 'remove', path: at(key, sub) });
+        else ops.push({ op: was[sub] === undefined ? 'add' : 'replace', path: at(key, sub), value: now[sub] as JsonValue });
+      }
+      continue;
+    }
+    ops.push({ op: 'replace', path: at(key), value: now });
+  }
+  return ops;
+}
+
+/** One chain of links as the config states it: its name and its points then its tip, in rig px. */
+export interface ClothChain { chain: string; points: [number, number][] }
+/** Per tag: the parts the recipe drafts on (by See-through tag, plus any part the recipe names) and their chains' links. */
+export interface ClothTagView { tag: string; parts: string[]; chains: ClothChain[] }
+const point = (p: unknown): [number, number] | null => Array.isArray(p) && p.length === 2 && p.every(n => typeof n === 'number' && Number.isFinite(n)) ? [p[0] as number, p[1] as number] : null;
+/**
+ * The link preview's data (#111): for each tag, the parts tagged with it in `parts.json` (`from` "<run>:<tag>") and the
+ * parts its recipe names, and every chain those parts' `meshes.<part>.segments` name, with the chain's `points` and
+ * `tip` from `bones` as written. Read off whatever config is given — the inspected one, or the config the producer wrote.
+ */
+export function clothLinks(config: unknown, partsJson: unknown, tags: readonly string[]): ClothTagView[] {
+  const cfg = isObject(config) ? config : {};
+  const parts = isObject(partsJson) && Array.isArray(partsJson.parts) ? partsJson.parts : [];
+  const recipes = isObject(cfg.cloth) ? cfg.cloth : {};
+  const meshes = isObject(cfg.meshes) ? cfg.meshes : {};
+  const bones = Array.isArray(cfg.bones) ? cfg.bones : [];
+  return tags.map(tag => {
+    const names = new Set<string>();
+    for (const p of parts) if (isObject(p) && typeof p.name === 'string' && typeof p.from === 'string' && p.from.slice(p.from.indexOf(':') + 1) === tag) names.add(p.name);
+    const recipe = recipes[tag];
+    if (isObject(recipe)) for (const key of ['part', 'parts']) { const v = recipe[key]; for (const n of Array.isArray(v) ? v : [v]) if (typeof n === 'string' && n) names.add(n); }
+    const chains: ClothChain[] = [], seen = new Set<string>();
+    for (const part of names) {
+      const entry = meshes[part], segments = isObject(entry) && Array.isArray(entry.segments) ? entry.segments : [];
+      for (const s of segments) {
+        if (typeof s !== 'string' || seen.has(s)) continue;
+        const bone = bones.find(b => isObject(b) && b.chain === s);
+        if (!isObject(bone) || !Array.isArray(bone.points)) continue;
+        const pts = [...bone.points.map(point), point(bone.tip)].filter((x): x is [number, number] => !!x);
+        if (pts.length >= 2) { chains.push({ chain: s, points: pts }); seen.add(s); }
+      }
+    }
+    return { tag, parts: [...names].sort(), chains };
+  });
+}
+
+/**
+ * The sections `propose --write-config` splices (rig-parts `PROPOSAL_CONFIG_SECTIONS`, and of `motion` only `tracks`,
+ * AUTHORING *The config written*): a written config may differ from its input only at or under these.
+ */
+export const DRAFTED_PREFIXES: readonly (readonly string[])[] = [['bones'], ['constraints'], ['meshes'], ['regions'], ['limbs'], ['motion', 'tracks'], ['turn'], ['proposed_rig_scale']];
+export const MAX_WRITTEN_PATHS = 200;
+/** Bar 1: every JSON Pointer at which the written config differs from its input, and those outside the drafted sections. */
+export interface WrittenDiff { count: number; paths: string[]; outside: string[]; sections: string[] }
+export function writtenDiff(input: unknown, written: unknown): WrittenDiff {
+  const paths = jsonDiff(input, written);
+  const outside = paths.filter(p => !DRAFTED_PREFIXES.some(prefix => under(parsePointer(p), prefix)));
+  const sections = [...new Set(paths.map(p => { const t = parsePointer(p); return t[0] === 'motion' ? t.slice(0, 2).join('.') : t[0] === 'meshes' || t[0] === 'regions' ? t.slice(0, 2).join('.') : t[0] ?? ''; }))];
+  return { count: paths.length, paths: paths.slice(0, MAX_WRITTEN_PATHS), outside: outside.slice(0, MAX_WRITTEN_PATHS), sections };
+}

package/src/compare-server.ts

@@ -36,7 +36,7 @@ export async function startCompareServer(p:ComparePackage,options:{port?:number;
   const handle=async(req:Request,port:number|undefined):Promise<Response>=>{try{
     const url=new URL(req.url),origin=`http://127.0.0.1:${port}`;
     if(url.origin!==origin)return json({error:'Loopback host required'},403);
-    const refused=openNonceGate(req,options.open)??accessGate(req,options.capability);if(refused)return refused;
+    const refused=openNonceGate(req,options.open)??accessGate(req,options.capability,!!control);if(refused)return refused;
     const controlled=await control?.(req,origin);if(controlled)return controlled;
     options.activity?.();const gate=openGate(req,options.open);if(gate){if(gate.status===200){try{await assertCompareUnchanged(p);}catch{return staleOpenStatus(options.open!);}}return gate;}
     if(req.method==='PUT'&&url.pathname==='/api/compare/session'){

package/src/environment-check.ts

@@ -0,0 +1,149 @@
+/**
+ * `POST /api/environment-check` (issue #112): "Check under this world". The Environment block's exported
+ * `rigc-environment/1` schedule is written by review into `<state>/environment-check/<package hash>/<id>/environment.json`,
+ * then `rig-parts check --rig <rig> --out out --parts <handoff parts> --page-edges free --pack-shape polygon
+ * --environment environment.json` runs with the installed producer (@rig-c/parts 1.48.0 or later, parts#538), on the
+ * inspected rig spec (the handoff's, read only) or on the session's latest scratch revision. The pack flags are the
+ * inspected build's own background check's (`src/baseline.ts`), so the default-world line beside it differs only by the
+ * world. The job keeps what check said: its `environment:` line, check.json's `environment` record (path, sha256, steps),
+ * the ANIMATIONS_DO_NOT_FOLD and TEXTURE_STRETCH lines, the summary, and a `CHECK_ENVIRONMENT` refusal verbatim. The
+ * check's output directory is removed after the run; the result is stored so the same schedule on the same build is read
+ * back. The client sends `{build, schedule}` only — never a path or a flag. Nothing is written into the package.
+ */
+import { createHash } from 'node:crypto';
+import { isAbsolute, join, relative } from 'node:path';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import type { ReviewPackage } from './manifest.ts';
+import { firstRefusal, modelingProducerTooOld, resolveProducer, runTool, versionAtLeast } from './producer.ts';
+import { producerInputs, RebuildError } from './rebuild.ts';
+import { checkSummary, type CheckSummary } from './applied-context.ts';
+import { barLine, READOUT_BARS } from './physics-tuning.ts';
+import { CHECK_ENVIRONMENT_SINCE, parseSchedule, ScheduleError, scheduleText } from './environment-schedule.ts';
+
+export const ENVIRONMENT_CHECK_SCHEMA = 'rig-review-environment-check/1';
+export const ENVIRONMENT_CHECK_LIMIT = 64 * 1024;
+const MAX_LINES = 4000;
+const sha256 = (text: string) => createHash('sha256').update(text).digest('hex');
+const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+
+export class EnvironmentCheckError extends Error { constructor(readonly code: string, detail: string) { super(`${code}: ${detail}`); } }
+export type EnvironmentCheckBuild = 'inspected' | 'scratch';
+export interface EnvironmentCheckRequest { build: EnvironmentCheckBuild; text: string }
+/** `{build, schedule}` only: the schedule as data (re-serialized here, so its hash is the exported bytes'), never a path. */
+export function parseEnvironmentCheckRequest(input: unknown): EnvironmentCheckRequest {
+  if (!isRecord(input) || Object.keys(input).sort().join(',') !== 'build,schedule') throw new EnvironmentCheckError('ENVIRONMENT_CHECK_REQUEST_INVALID', 'expected exactly {build, schedule}');
+  if (input.build !== 'inspected' && input.build !== 'scratch') throw new EnvironmentCheckError('ENVIRONMENT_CHECK_REQUEST_INVALID', 'build must be inspected or scratch');
+  try { return { build: input.build, text: scheduleText(parseSchedule(input.schedule)) }; }
+  catch (e) { if (e instanceof ScheduleError) throw new EnvironmentCheckError('ENVIRONMENT_CHECK_REQUEST_INVALID', e.message); throw e; }
+}
+/** check's argv as `rig-parts check --help` states it (1.48.0); every path the server's. */
+export const environmentCheckArgs = (r: { rig: string; parts: string; out: string; environment: string }): string[] =>
+  ['check', '--rig', r.rig, '--out', r.out, '--parts', r.parts, '--page-edges', 'free', '--pack-shape', 'polygon', '--environment', r.environment];
+
+/** What check.json records under `--environment` (parts#538): the path as given, the bytes' sha256, the step count. */
+export interface CheckEnvironmentRecord { path: string; sha256: string; steps: number }
+export function checkEnvironmentRecord(checkJson: unknown): CheckEnvironmentRecord | null {
+  const e = isRecord(checkJson) && isRecord(checkJson.environment) ? checkJson.environment : null;
+  return e && typeof e.path === 'string' && typeof e.sha256 === 'string' && Number.isSafeInteger(e.steps) ? { path: e.path, sha256: e.sha256, steps: e.steps as number } : null;
+}
+/** check's `environment: <path>, rigc-environment/1, <n> step(s), sha256 <16 hex> — …` line, verbatim (trimmed). */
+export const environmentLineOf = (lines: readonly string[]) => lines.map(l => l.trim()).find(l => /^environment: \S.*rigc-environment\/1, \d+ step\(s\), sha256 [0-9a-f]{16}/.test(l)) ?? null;
+
+export interface EnvironmentCheckJob {
+  schema: typeof ENVIRONMENT_CHECK_SCHEMA; id: string; status: 'running' | 'checked' | 'refused' | 'failed';
+  build: EnvironmentCheckBuild; buildId: string | null;
+  /** The schedule as written: its sha256, byte length, step count. */
+  schedule: { sha256: string; size: number; steps: number };
+  producer: { package: string; version: string };
+  exitCode: number | null; wallMs: number | null;
+  check: CheckSummary | null;
+  /** check.json's `environment`; its sha256 must be the schedule's (a mismatch fails the job). */
+  environment: CheckEnvironmentRecord | null;
+  environmentLine: string | null;
+  /** The readout bars' lines (ANIMATIONS_DO_NOT_FOLD, TEXTURE_STRETCH) as check printed them. */
+  bars: { name: string; line: string }[];
+  /** A named refusal verbatim (`FAIL  CHECK_ENVIRONMENT: …`), or why the run failed. */
+  error: string | null;
+  lines: string[];
+}
+export interface EnvironmentCheckOptions {
+  stateDir: string; starts: readonly string[]; unchanged: () => Promise<void>;
+  latest: () => { id: string; spec: string } | null;
+}
+export const environmentCheckRoot = (stateDir: string, sourceHash: string) => join(stateDir, 'environment-check', sourceHash);
+
+/** One check at a time per review instance; finished jobs stay readable by id, and a stored result is read back. */
+export function createEnvironmentCheck(p: ReviewPackage, options: EnvironmentCheckOptions) {
+  const jobs = new Map<string, EnvironmentCheckJob>();
+  let running: string | null = null;
+  const snapshot = (job: EnvironmentCheckJob): EnvironmentCheckJob => JSON.parse(JSON.stringify(job)) as EnvironmentCheckJob;
+  function assertStateOutside(): void {
+    for (const root of [p.root, ...(p.handoff ? [p.handoff.root] : [])]) {
+      const inside = relative(root, options.stateDir);
+      if (inside === '' || !inside.startsWith('..') && !isAbsolute(inside)) throw new EnvironmentCheckError('ENVIRONMENT_CHECK_STATE_INSIDE_PACKAGE', 'the review state directory is inside the inspected package; set RIG_REVIEW_STATE_DIR outside it');
+    }
+  }
+
+  async function execute(job: EnvironmentCheckJob, dir: string, bin: string, rig: string, parts: string, text: string): Promise<void> {
+    try {
+      await rm(dir, { recursive: true, force: true });
+      await mkdir(dir, { recursive: true, mode: 0o700 });
+      await writeFile(join(dir, 'environment.json'), text, { mode: 0o600 });
+      const run = await runTool(bin, environmentCheckArgs({ rig, parts, out: 'out', environment: 'environment.json' }), { cwd: dir, onLine: line => { if (job.lines.length < MAX_LINES) job.lines.push(line); } });
+      let checkJson: unknown = null;
+      try { checkJson = JSON.parse(await readFile(join(dir, 'out', 'check.json'), 'utf8')); } catch { /* refused before check.json; the lines say why */ }
+      const refusal = firstRefusal(run.lines);
+      Object.assign(job, { exitCode: run.exitCode, wallMs: run.wallMs, environmentLine: environmentLineOf(run.lines), environment: checkEnvironmentRecord(checkJson) });
+      try { await options.unchanged(); } catch { throw new EnvironmentCheckError('ENVIRONMENT_CHECK_INPUTS_CHANGED', 'the package or its producer handoff changed during the check'); }
+      if (checkJson === null) { job.status = 'refused'; job.error = refusal ?? `rig-parts check exited ${run.exitCode} without a named refusal`; }
+      else {
+        job.check = checkSummary(checkJson, run.exitCode, run.lines, refusal);
+        job.bars = READOUT_BARS.map(name => ({ name, line: barLine(name, run.lines, job.check) }));
+        if (!job.environment || job.environment.sha256 !== job.schedule.sha256) throw new EnvironmentCheckError('ENVIRONMENT_CHECK_UNRECORDED', `check.json's environment ${job.environment ? `sha256 ${job.environment.sha256}` : 'is absent'}; the schedule written was sha256 ${job.schedule.sha256}`);
+        job.status = 'checked';
+      }
+      await writeFile(join(dir, 'result.json'), JSON.stringify({ ...job, lines: job.lines.slice(-MAX_LINES) }, null, 1) + '\n', { mode: 0o600 });
+    } catch (error) { job.status = 'failed'; job.error = error instanceof Error ? error.message : String(error); }
+    finally { await rm(join(dir, 'out'), { recursive: true, force: true }).catch(() => {}); if (job.status === 'failed') await rm(dir, { recursive: true, force: true }).catch(() => {}); }
+  }
+
+  /** Refusals before anything runs; a malformed request is ENVIRONMENT_CHECK_REQUEST_INVALID (400 at the route). */
+  async function start(input: unknown): Promise<{ status: number; body: unknown }> {
+    const request = parseEnvironmentCheckRequest(input);
+    assertStateOutside();
+    await options.unchanged();
+    let inputs: Awaited<ReturnType<typeof producerInputs>>;
+    try { inputs = await producerInputs(p.handoff, p.handoffReason); } catch (e) { if (e instanceof RebuildError) return { status: 200, body: { status: 'refused', error: e.message } }; throw e; }
+    let rig = inputs.rig, buildId: string | null = null;
+    if (request.build === 'scratch') {
+      const latest = options.latest();
+      if (!latest) return { status: 200, body: { status: 'refused', error: 'ENVIRONMENT_CHECK_NO_SCRATCH: no scratch build in this session yet; Apply builds one, or check the inspected rig' } };
+      rig = latest.spec; buildId = latest.id;
+    }
+    const resolved = resolveProducer(options.starts);
+    if (!resolved.ok) return { status: 200, body: { status: 'refused', error: resolved.error } };
+    const producer = { package: resolved.producer.package, version: resolved.producer.version };
+    if (!versionAtLeast(producer.version, CHECK_ENVIRONMENT_SINCE)) return { status: 200, body: { status: 'refused', error: modelingProducerTooOld(producer.version || 'unknown', CHECK_ENVIRONMENT_SINCE, 'rig-parts check --environment') } };
+    const fileSha = sha256(request.text);
+    const id = sha256(JSON.stringify([ENVIRONMENT_CHECK_SCHEMA, p.sourceHash, fileSha, request.build, buildId, inputs.configHash, `${producer.package}@${producer.version}`]));
+    const current = jobs.get(id);
+    if (current && current.status !== 'failed') return { status: current.status === 'running' ? 202 : 200, body: snapshot(current) };
+    const dir = join(environmentCheckRoot(options.stateDir, p.sourceHash), id);
+    try { const stored = JSON.parse(await readFile(join(dir, 'result.json'), 'utf8')) as EnvironmentCheckJob; if (stored.schema === ENVIRONMENT_CHECK_SCHEMA && stored.id === id) { jobs.set(id, stored); return { status: 200, body: snapshot(stored) }; } } catch { /* not run yet */ }
+    if (running) return { status: 200, body: { status: 'refused', error: `ENVIRONMENT_CHECK_BUSY: check ${running} is still running` } };
+    const job: EnvironmentCheckJob = {
+      schema: ENVIRONMENT_CHECK_SCHEMA, id, status: 'running', build: request.build, buildId,
+      schedule: { sha256: fileSha, size: Buffer.byteLength(request.text), steps: (JSON.parse(request.text) as { steps: unknown[] }).steps.length }, producer,
+      exitCode: null, wallMs: null, check: null, environment: null, environmentLine: null, bars: [], error: null, lines: [],
+    };
+    jobs.set(id, job); running = id;
+    void execute(job, dir, resolved.producer.bin, rig, inputs.parts, request.text).finally(() => { if (running === id) running = null; });
+    return { status: 202, body: snapshot(job) };
+  }
+  function read(id: string): EnvironmentCheckJob {
+    const job = jobs.get(id);
+    if (!job) throw new EnvironmentCheckError('ENVIRONMENT_CHECK_NOT_FOUND', id);
+    return snapshot(job);
+  }
+  return { start, read, running: () => running };
+}

package/src/environment-schedule.ts

@@ -0,0 +1,183 @@
+/**
+ * The Environment block's wind as a `rigc-environment/1` schedule (issue #112): what `rigc render --environment` and
+ * `rig-parts check --environment` (@rig-c/parts 1.48.0, parts#538) read — `{spec, steps: [{t, wind?, gravity?}]}`, each
+ * step holding from its `t` until the next, x right and y down, the runtime's wind [1, 0] and gravity [0, 1] before the
+ * first. Pure: no DOM, no IO, no clock.
+ *
+ * The panel's wind (`./environment.ts`) is `base + breeze(t) + gust(t)` on a clock the player's steps advance. From a
+ * fresh clock (`restore`, which starts a repeating gust at 0) that is a function of time alone, so a schedule can carry
+ * it with t = 0 at the animation's first frame:
+ *  - the step form (no breeze, no repeating gust): one step, the standing world — exact;
+ *  - the sampled form (breeze and/or repeat on): one step per frame of the render's grid (`SCHEDULE_FPS`), each the
+ *    panel's wind at that frame's time. rigc sets a step before the physics step that poses its frame, as the panel sets
+ *    the wind before the player's step, so the two agree at every frame time; between frames rigc holds the frame's
+ *    value, within `scheduleTolerance` of the panel's.
+ * A one-off Gust (Repeat off) is an event on the live clock, not part of the settings, and is not in the schedule.
+ */
+import { breezeAt, gustEnvelope, gustPeriod, type WindSnapshot } from './environment.ts';
+
+export const ENVIRONMENT_SPEC = 'rigc-environment/1';
+/** The grid the schedule is sampled on: `rigc render`'s default fps and `rig-parts check`'s IDLE_FPS. */
+export const SCHEDULE_FPS = 12;
+/** At most this many steps (50 s at 12 fps, ~36 KiB of JSON); a longer clip is refused by name. */
+export const MAX_SCHEDULE_STEPS = 600;
+/** The first `@rig-c/parts` release whose `check` reads `--environment` (its CHANGELOG: 1.48.0, parts#538). */
+export const CHECK_ENVIRONMENT_SINCE = '1.48.0';
+/** The runtime's world before the first step (rig-c `src/environment.ts`). */
+export const RUNTIME_WORLD = { wind: [1, 0] as [number, number], gravity: [0, 1] as [number, number] };
+
+export interface EnvironmentStep { t: number; wind?: [number, number]; gravity?: [number, number] }
+export interface EnvironmentSchedule { spec: typeof ENVIRONMENT_SPEC; steps: EnvironmentStep[] }
+export class ScheduleError extends Error { constructor(readonly code: string, detail: string) { super(`${code}: ${detail}`); } }
+
+/** The standing world as one step from t = 0 (#108's readings schedule; the step form below is this). */
+export const standingSchedule = (e: { wind: [number, number]; gravity: [number, number] }): EnvironmentSchedule => ({ spec: ENVIRONMENT_SPEC, steps: [{ t: 0, wind: e.wind, gravity: e.gravity }] });
+
+/** The panel's wind at clock time `t` from a fresh clock (`createWindModel().restore(snapshot)`, then advanced to `t`). */
+export function windAt(s: WindSnapshot, t: number): number {
+  const gentle = s.breeze ? breezeAt(t) : 0;
+  let gust = 0;
+  if (s.repeat) {
+    const period = gustPeriod(s.gustDuration), age = t - Math.floor(t / period) * period;
+    gust = (s.base < 0 ? -1 : 1) * gustEnvelope(age, s.gustPeak, s.gustDuration);
+  }
+  return s.base + gentle + gust;
+}
+/** Whether the wind changes in time (breeze or a repeating gust): the sampled form. */
+export const windVaries = (s: WindSnapshot) => s.breeze || (s.repeat && s.gustPeak > 0);
+/**
+ * The largest difference between the panel's wind and the schedule's held value inside one frame interval:
+ * max |dw/dt| / fps, with |breeze'| <= 2·2.2 + 0.8·5.1 and |gust'| <= peak·π / duration. 0 for the step form.
+ */
+export function scheduleTolerance(s: WindSnapshot, fps = SCHEDULE_FPS): number {
+  if (!windVaries(s)) return 0;
+  return ((s.breeze ? 2 * 2.2 + 0.8 * 5.1 : 0) + (s.repeat ? s.gustPeak * Math.PI / s.gustDuration : 0)) / fps;
+}
+
+export type ScheduleForm = 'step' | 'sampled';
+export interface WindScheduleExport { schedule: EnvironmentSchedule; form: ScheduleForm; tolerance: number; fps: number; duration: number }
+/**
+ * The panel's settings and gravity (the slider's value, applied as [0, g]) as a schedule over a clip of `duration`
+ * seconds: the step form when nothing varies, else one step per frame of `fps` up to the clip's last frame (rigc refuses a
+ * step after it), a step whose wind equals the one before left out.
+ */
+export function windSchedule(s: WindSnapshot, gravity: number, duration: number, fps = SCHEDULE_FPS): WindScheduleExport {
+  const g: [number, number] = [0, gravity];
+  if (!windVaries(s)) return { schedule: standingSchedule({ wind: [s.base, 0], gravity: g }), form: 'step', tolerance: 0, fps, duration };
+  if (!(duration > 0) || !Number.isFinite(duration)) throw new ScheduleError('ENVIRONMENT_SCHEDULE_NO_CLIP', 'a breeze or a repeating gust is sampled over a clip; no clip with a duration is drawn');
+  const last = Math.round(duration * fps);
+  if (last + 1 > MAX_SCHEDULE_STEPS) throw new ScheduleError('ENVIRONMENT_SCHEDULE_TOO_LONG', `${duration} s at ${fps} fps is ${last + 1} steps; at most ${MAX_SCHEDULE_STEPS}`);
+  const steps: EnvironmentStep[] = [];
+  let previous = NaN;
+  for (let k = 0; k <= last; k++) {
+    const t = k / fps, w = windAt(s, t);
+    if (k === 0) steps.push({ t, wind: [w, 0], gravity: g });
+    else if (w !== previous) steps.push({ t, wind: [w, 0] });
+    previous = w;
+  }
+  return { schedule: { spec: ENVIRONMENT_SPEC, steps }, form: 'sampled', tolerance: scheduleTolerance(s, fps), fps, duration };
+}
+
+/** The exported bytes: what is downloaded, written for rigc and rig-parts, and hashed into feedback. */
+export const scheduleText = (s: EnvironmentSchedule) => JSON.stringify(s, null, 1) + '\n';
+
+const bad = (detail: string): never => { throw new ScheduleError('ENVIRONMENT_SCHEDULE_INVALID', detail); };
+const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+const pair = (v: unknown, field: string): [number, number] => {
+  if (!Array.isArray(v) || v.length !== 2 || !v.every(n => typeof n === 'number' && Number.isFinite(n) && Math.abs(n) <= 1e4)) bad(`${field} must be [x, y], finite`);
+  return [(v as number[])[0]!, (v as number[])[1]!];
+};
+/** A schedule as rig-c's reader takes it (exact keys, ascending t from 0, a half stated per step), bounded; data only. */
+export function parseSchedule(value: unknown): EnvironmentSchedule {
+  if (!isRecord(value) || Object.keys(value).sort().join(',') !== 'spec,steps') return bad('expected exactly {spec, steps}');
+  if (value.spec !== ENVIRONMENT_SPEC) bad(`spec must be ${ENVIRONMENT_SPEC}`);
+  if (!Array.isArray(value.steps) || value.steps.length < 1 || value.steps.length > MAX_SCHEDULE_STEPS) bad(`steps must hold 1–${MAX_SCHEDULE_STEPS} entries`);
+  const steps: EnvironmentStep[] = [];
+  (value.steps as unknown[]).forEach((raw, i) => {
+    if (!isRecord(raw) || !Object.keys(raw).every(k => k === 't' || k === 'wind' || k === 'gravity')) bad(`steps[${i}] holds only t, wind, gravity`);
+    const step = raw as Record<string, unknown>, t = step.t;
+    if (typeof t !== 'number' || !Number.isFinite(t) || t < 0 || t > 3600) bad(`steps[${i}].t must be seconds in [0, 3600]`);
+    if (i > 0 && !((t as number) > steps[i - 1]!.t)) bad(`steps[${i}].t must come after steps[${i - 1}].t`);
+    if (step.wind === undefined && step.gravity === undefined) bad(`steps[${i}] states neither wind nor gravity`);
+    steps.push({ t: t as number, ...(step.wind === undefined ? {} : { wind: pair(step.wind, `steps[${i}].wind`) }), ...(step.gravity === undefined ? {} : { gravity: pair(step.gravity, `steps[${i}].gravity`) }) });
+  });
+  return { spec: ENVIRONMENT_SPEC, steps };
+}
+
+/** rig-c's `environmentFrame`: the first frame `i` whose time `i / fps` is at or after `t`. */
+export function environmentFrame(t: number, fps: number): number {
+  let i = Math.max(0, Math.ceil(t * fps));
+  while (i > 0 && (i - 1) / fps >= t) i--;
+  while (i / fps < t) i++;
+  return i;
+}
+/**
+ * The world as rigc reads the schedule at time `t` on the `fps` grid: the physics step that ends on frame
+ * `environmentFrame(t)` runs under every step that lands on that frame or before (the runtime's world before the first).
+ */
+export function scheduleWorldAt(s: EnvironmentSchedule, t: number, fps = SCHEDULE_FPS): { wind: [number, number]; gravity: [number, number] } {
+  const frame = environmentFrame(t, fps);
+  let wind = RUNTIME_WORLD.wind, gravity = RUNTIME_WORLD.gravity;
+  for (const step of s.steps) { if (environmentFrame(step.t, fps) > frame) break; if (step.wind) wind = step.wind; if (step.gravity) gravity = step.gravity; }
+  return { wind, gravity };
+}
+
+/** One line: form, steps, the hash's first 16 hex (as check's `environment:` line prints it), the tolerance. */
+export function scheduleSummary(e: WindScheduleExport, sha256: string): string {
+  const form = e.form === 'step' ? 'step form (exact)' : `sampled at ${e.fps} fps over ${e.duration.toFixed(3)} s (held between frames, within ${e.tolerance.toFixed(3)} of the panel)`;
+  return `${ENVIRONMENT_SPEC}, ${e.schedule.steps.length} step(s), sha256 ${sha256.slice(0, 16)} · ${form}`;
+}
+
+/** `context.environmentSchedule` (#112): the exported bytes by hash and content, and whether readings and Apply used them. */
+export const SCHEDULE_CONTEXT_SCHEMA = 'rig-review-environment-schedule/1';
+export interface ScheduleContext { schema: typeof SCHEDULE_CONTEXT_SCHEMA; sha256: string; size: number; text: string; usedForReadings: boolean }
+const ctx = (detail: string): never => { throw new Error(`feedback.context.environmentSchedule: ${detail}`); };
+/** The context's exact shape, its sha256 recomputed over `text` (`hash` is the caller's) and `text` a schedule. */
+export function parseScheduleContext(value: unknown, hash: (text: string) => string): ScheduleContext | null {
+  if (value === null) return null;
+  if (!isRecord(value) || Object.keys(value).sort().join(',') !== 'schema,sha256,size,text,usedForReadings') return ctx('expected exactly {schema, sha256, size, text, usedForReadings}');
+  if (value.schema !== SCHEDULE_CONTEXT_SCHEMA) ctx(`schema must be ${SCHEDULE_CONTEXT_SCHEMA}`);
+  if (typeof value.text !== 'string' || value.text.length > 128 * 1024) ctx('text must be the exported schedule, at most 128 KiB');
+  const text = value.text as string;
+  if (typeof value.sha256 !== 'string' || value.sha256 !== hash(text)) ctx('sha256 is not the sha256 of text');
+  if (value.size !== new TextEncoder().encode(text).length) ctx('size is not the byte length of text');
+  if (typeof value.usedForReadings !== 'boolean') ctx('usedForReadings must be a boolean');
+  let doc: unknown;
+  try { doc = JSON.parse(text); } catch { return ctx('text does not parse as JSON'); }
+  try { parseSchedule(doc); } catch (e) { ctx(`text is not a ${ENVIRONMENT_SPEC} schedule (${e instanceof Error ? e.message : String(e)})`); }
+  return value as unknown as ScheduleContext;
+}
+/** "41 step(s) · sha256 … · used for readings": one line for the issue export. */
+export function scheduleContextLine(value: unknown): string | null {
+  if (!isRecord(value) || value.schema !== SCHEDULE_CONTEXT_SCHEMA || typeof value.sha256 !== 'string' || typeof value.text !== 'string') return null;
+  let steps = 0;
+  try { const doc = JSON.parse(value.text) as { steps?: unknown[] }; steps = Array.isArray(doc.steps) ? doc.steps.length : 0; } catch { return null; }
+  return `${ENVIRONMENT_SPEC}, ${steps} step(s) · schedule sha256 ${value.sha256}${value.usedForReadings ? ' · used for readings and Apply' : ' · not used for readings'}`;
+}
+
+/** SHA-256 of a string's UTF-8 bytes, hex — synchronous, so the page can hash the exported bytes where it records them. */
+export function sha256Hex(text: string): string {
+  const bytes = new TextEncoder().encode(text), K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2]);
+  const h = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+  const length = Math.ceil((bytes.length + 9) / 64) * 64, m = new Uint8Array(length);
+  m.set(bytes); m[bytes.length] = 0x80;
+  const view = new DataView(m.buffer), bits = bytes.length * 8;
+  view.setUint32(length - 8, Math.floor(bits / 0x100000000)); view.setUint32(length - 4, bits >>> 0);
+  const w = new Uint32Array(64), rot = (x: number, n: number) => (x >>> n) | (x << (32 - n));
+  for (let o = 0; o < length; o += 64) {
+    for (let i = 0; i < 16; i++) w[i] = view.getUint32(o + i * 4);
+    for (let i = 16; i < 64; i++) { const a = w[i - 15]!, b = w[i - 2]!; w[i] = (w[i - 16]! + (rot(a, 7) ^ rot(a, 18) ^ (a >>> 3)) + w[i - 7]! + (rot(b, 17) ^ rot(b, 19) ^ (b >>> 10))) >>> 0; }
+    let [a, b, c, d, e, f, g, hh] = h as unknown as number[];
+    for (let i = 0; i < 64; i++) {
+      const t1 = (hh! + (rot(e!, 6) ^ rot(e!, 11) ^ rot(e!, 25)) + ((e! & f!) ^ (~e! & g!)) + K[i]! + w[i]!) >>> 0;
+      const t2 = ((rot(a!, 2) ^ rot(a!, 13) ^ rot(a!, 22)) + ((a! & b!) ^ (a! & c!) ^ (b! & c!))) >>> 0;
+      hh = g; g = f; f = e; e = (d! + t1) >>> 0; d = c; c = b; b = a; a = (t1 + t2) >>> 0;
+    }
+    h[0] += a!; h[1] += b!; h[2] += c!; h[3] += d!; h[4] += e!; h[5] += f!; h[6] += g!; h[7] += hh!;
+  }
+  return [...h].map(x => x.toString(16).padStart(8, '0')).join('');
+}

package/src/feedback-export.ts

@@ -7,6 +7,7 @@ import type { ReferenceBinding } from './reference.ts';
 import { environmentSummary, parseEnvironmentContext } from './environment.ts';
 import { appliedSummary } from './applied-context.ts';
 import { requirementsSummaryLine } from './requirements.ts';
+import { scheduleContextLine } from './environment-schedule.ts';
 type Category = Feedback['category'];
 type Side = 'single' | 'a' | 'b';
 type ParsedFeedbackSession = FeedbackHistory<ReviewSession | CompareSession>;
@@ -176,6 +177,12 @@ function requirementsLine(context: Json | undefined): string[] {
   const text = requirementsSummaryLine(context.requirements);
   return text === null ? [] : [`- Requirements: ${feedbackMarkdownText(text)}`];
 }
+/** "Environment schedule: rigc-environment/1, 41 step(s) · schedule sha256 …": the exported world the note carries (#112). */
+function scheduleLine(context: Json | undefined): string[] {
+  if (context === undefined || context === null || typeof context !== 'object' || Array.isArray(context) || !('environmentSchedule' in context)) return [];
+  const text = scheduleContextLine(context.environmentSchedule);
+  return text === null ? [] : [`- Environment schedule: ${feedbackMarkdownText(text)}`];
+}
 /** Local issue-ready text only. No issue creation, clock inference or source IO. */
 export function formatFeedbackIssues(input: ParsedFeedbackSession): string {
   const model = groupFeedbackIssues(input), md = feedbackMarkdownText;
@@ -209,7 +216,7 @@ export function formatFeedbackIssues(input: ParsedFeedbackSession): string {
           `- Summary: ${md(item.summary)}`,
           ...environmentLine(item.context),
           ...appliedLine(item.context),
-          ...requirementsLine(item.context), '',
+          ...requirementsLine(item.context), ...scheduleLine(item.context), '',
           'Selected build identity:', '', jsonBlock(item.selectedSource));
         if (model.pairedBinding) lines.push('', 'Paired comparison binding:', '', jsonBlock(model.pairedBinding));
         if (item.warnings.length) lines.push('', 'Validation warnings (record retained):', '', jsonBlock(item.warnings));

package/src/frame-clock.ts

@@ -34,3 +34,33 @@ export function frameAtTime(clock:FrameClock|null|undefined,time:number):number|
   while(low<=high){const middle=low+Math.floor((high-low)/2);const sample=timeAtFrame(clock,middle);if(sample===null)return null;if(sample<=time)low=middle+1;else high=middle-1;}
   return high>=0?high:null;
 }
+
+/** The most frame times a scratch build's report may state (a bound for the served job, not a timing claim). */
+export const MAX_STAGE_FRAME_TIMES=100_000;
+
+/** A producer report's `frameTimes`, kept only when it is a bounded, finite, strictly increasing list; else null. */
+export function samplesClock(times:unknown):FrameClock|null {
+  if(!Array.isArray(times)||!times.length||times.length>MAX_STAGE_FRAME_TIMES)return null;
+  for(let i=0;i<times.length;i++){const t=times[i];if(typeof t!=='number'||!Number.isFinite(t)||(i>0&&t<=times[i-1]))return null;}
+  return {kind:'samples',frameTimes:[...times as number[]]};
+}
+
+/** The clock a scratch build states for one of its animations (a retarget's `motion.report.json`), bound to that build. */
+export interface StageClock {animation:string;modelHash:string;clock:FrameClock}
+
+/**
+ * The transport's clock. The package report's clock when it names the active animation; else, with a player, the
+ * clock the build on the stage states for the active animation (#164: a retarget's own report frameTimes). The
+ * stage clock binds by animation and by the drawn model's hash, so a reset or another rebuild drops it.
+ */
+export function transportClock(report:{clock:FrameClock|null|undefined;animation:string|undefined},active:string,hasPlayer:boolean,stage:StageClock|null,stageModelHash:string|null):{clock:FrameClock;source:'report'|'stage'}|null {
+  const own=clockForAnimation(report.clock,report.animation,active,hasPlayer);if(own)return {clock:own,source:'report'};
+  if(hasPlayer&&stage&&active&&stage.animation===active&&stage.modelHash===stageModelHash)return {clock:stage.clock,source:'stage'};
+  return null;
+}
+
+/** The rig pane's header: the animation, frame and time the drawn pose is at — the transport's clock, the one a seek sets. */
+export function rigPaneLabel(state:{hasPlayer:boolean;animation:string;time:number;frame:number|null}):string {
+  if(!state.hasPlayer)return 'Generated rig · read only';
+  return ['Generated rig',state.animation||'no animation',...(state.frame===null?[]:[`F${state.frame}`]),`${state.time.toFixed(3)} s`].join(' · ');
+}