@rig-c/review 0.8.0 → 0.9.0

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(' · ');
+}

package/src/front.ts

@@ -57,6 +57,9 @@ export function frontRoute(mode:'single'|'compare',method:string,path:string):Ro
  if((mode==='single'?/^\/assets\/[^/]/:/^\/compare-assets\/(a|b)\/[^/]/).test(path))return read?get:null;
  // Apply · Rebuild (single only): status, one typed request, a job's status and its served scratch build.
  if(mode==='single'&&path==='/api/rebuild')return read?get:method==='POST'?{mutation:true,limit:64*1024,timeoutMs:30000,control:false}:null;
+ // #166 (single only): the applied records, and undo of the last one ({from}).
+ if(mode==='single'&&path==='/api/rebuild/history')return read?get:null;
+ if(mode==='single'&&path==='/api/rebuild/undo')return method==='POST'?{mutation:true,limit:1024,timeoutMs:30000,control:false}:null;
  if(mode==='single'&&(/^\/api\/rebuild\/[a-f0-9]{64}$/.test(path)||/^\/rebuild\/[a-f0-9]{64}\/[^/]/.test(path)))return read?get:null;
  // Bones check (#109, single only): one typed request {ops, configHash}, answered in the response.
  if(mode==='single'&&path==='/api/bones-check')return method==='POST'?{mutation:true,limit:64*1024,timeoutMs:60000,control:false}:null;

package/src/handoff.ts

@@ -9,6 +9,13 @@
  * 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.
+ *
+ * A rig-parts build root (#149, {@link isBuildRoot}) opens as its `check/` package. For that package the producer's own
+ * config for the build is the regular file `config.json` in the build root, else in the folder that holds it — the two
+ * places `rig-parts build --config <dir>/config.json --out <dir>/out` leaves it. The build writes no record of its
+ * config, so this is a location rule bounded by the build's own files, not a proof: the session baseline (the producer
+ * rebuilding the inspected rig from that config) is the check. Discovered there, or declared with `--config` at exactly
+ * one of those two files, the handoff's root is that file's folder and the parts directory is the build root.
  */
 import { createHash } from 'node:crypto';
 import { lstat, readdir, readFile, realpath, stat } from 'node:fs/promises';
@@ -19,6 +26,9 @@ export const HANDOFF_SCHEMA = 'rig-review-handoff/1';
 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}`;
+/** #149: the places looked at for the check package of a rig-parts build root, after the in-folder ones. */
+export const BUILD_DISCOVERY_PLACES = ['../config.json (in the build root)', '../../config.json (beside the build root)'] as const;
+export const BUILD_MODELING_INPUT_UNAVAILABLE = `MODELING_INPUT_UNAVAILABLE: config.json — looked at ${[...DISCOVERY_PLACES.slice(0, 2), ...BUILD_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. */
@@ -56,6 +66,33 @@ const inside = (base: string, path: string, allowSelf = false) => { const 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; } }
 
+/** A path's own entry (never followed) is of this kind; absent or another kind is false. */
+async function entryIs(path: string, kind: 'file' | 'dir'): Promise<boolean> {
+  try { const info = await lstat(path); return kind === 'file' ? info.isFile() : info.isDirectory(); } catch (e) { if (code(e) === 'ENOENT' || code(e) === 'ENOTDIR') return false; throw e; }
+}
+/**
+ * #149: a rig-parts build root — the folder `rig-parts build --out` wrote — recognised by fixed names the build owns, never
+ * by a search: regular `parts.json` and `rig/rig.json`, a real (not symlinked) `check/` directory, and an existing
+ * `check/build/skeleton.model.json` entry (its validity is the package adapter's to refuse). A folder lacking any of
+ * these is not a build root.
+ */
+export async function isBuildRoot(dir: string): Promise<boolean> {
+  if (!(await entryIs(join(dir, 'parts.json'), 'file')) || !(await entryIs(join(dir, 'rig'), 'dir')) || !(await entryIs(join(dir, 'rig', 'rig.json'), 'file')) || !(await entryIs(join(dir, 'check'), 'dir'))) return false;
+  return exists(join(dir, 'check', 'build', 'skeleton.model.json'));
+}
+/** The producer's own config places for the build whose check package is `root` (canonical), or null when `root` is not one. */
+interface BuildPlace { config: string; base: string; field: string }
+async function buildPlaces(root: string): Promise<{ build: string; places: BuildPlace[] } | null> {
+  if (basename(root) !== 'check' || !(await isBuildRoot(dirname(root)))) return null;
+  const build = dirname(root);
+  return { build, places: [{ config: join(build, 'config.json'), base: build, field: '../config.json' }, { config: join(dirname(build), 'config.json'), base: dirname(build), field: '../../config.json' }] };
+}
+/** The path as written with its parent chain canonicalized (so /tmp → /private/tmp is not an escape); null when the parent is missing. */
+async function writtenPath(value: string): Promise<string | null> {
+  const lexical = resolve(value);
+  try { return join(await realpath(dirname(lexical)), basename(lexical)); } catch (e) { if (code(e) === 'ENOENT' || code(e) === 'ENOTDIR') return null; 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.
@@ -175,13 +212,17 @@ export async function resolveHandoff(root: string, declared: HandoffDeclaration
   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 keypoints = flags.keypoints !== undefined ? await flagPath(root, flags.keypoints, '--keypoints', 'file') : undefined;
-    const handoff = await record(root, root, 'declared', 'open --config', config, parts, { source, full, head, keypoints }, flags.parts !== undefined);
+    // #149: a --config written as exactly one of the build's own config places takes that place's folder as its root.
+    const build = await buildPlaces(root), written = build ? await writtenPath(flags.config) : null;
+    const place = build?.places.find(p => p.config === written) ?? null, base = place?.base ?? root;
+    const config = await flagPath(base, flags.config, '--config', 'file');
+    if (place && config !== place.config) throw new HandoffError('HANDOFF_SYMLINK_ESCAPE', '--config', `${flags.config} is a symlink; only the build's own ${place.field} is taken`);
+    const parts = flags.parts !== undefined ? await flagPath(base, flags.parts, '--parts', 'dir') : place ? build!.build : join(dirname(config), 'out');
+    const source = flags.source !== undefined ? await flagPath(base, flags.source, '--source', 'file') : undefined;
+    const full = flags.full !== undefined ? await flagPath(base, flags.full, '--full', 'dir') : undefined;
+    const head = flags.head !== undefined ? await flagPath(base, flags.head, '--head', 'dir') : undefined;
+    const keypoints = flags.keypoints !== undefined ? await flagPath(base, flags.keypoints, '--keypoints', 'file') : undefined;
+    const handoff = await record(root, base, 'declared', 'open --config', config, parts, { source, full, head, keypoints }, 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 } : {}), ...(keypoints ? { keypoints } : {}) };
     return { handoff, reason: null };
@@ -202,6 +243,17 @@ export async function resolveHandoff(root: string, declared: HandoffDeclaration
     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 };
   }
+  // #149: the check package of a rig-parts build root — the build's own config, in the build root, else beside it.
+  const build = await buildPlaces(root);
+  if (build) {
+    for (const place of build.places) {
+      if (!(await exists(place.config))) continue;
+      const config = await contained(place.base, place.config, place.field, 'file', true);
+      if (config !== place.config) throw new HandoffError('HANDOFF_SYMLINK_ESCAPE', place.field, `${place.config} is a symlink; only the build's own config file is discovered`);
+      return { handoff: await record(root, place.base, 'discovered', 'discovery', config, build.build, {}, false), reason: null };
+    }
+    return { handoff: null, reason: BUILD_MODELING_INPUT_UNAVAILABLE };
+  }
   // 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');

package/src/manifest.ts

@@ -6,7 +6,7 @@ import { parseReport, type ReportSeeds } from './report.ts';
 import { readFile, realpath, stat, lstat, readdir } from 'node:fs/promises';
 import { createReadStream } from 'node:fs';
 import { basename, dirname, isAbsolute, relative, resolve, posix } from 'node:path';
-import { parseHandoffDeclaration, resolveHandoff, type Handoff, type HandoffDeclaration, type HandoffFlags, type HandoffRecord } from './handoff.ts';
+import { isBuildRoot, parseHandoffDeclaration, resolveHandoff, type Handoff, type HandoffDeclaration, type HandoffFlags, type HandoffRecord } from './handoff.ts';
 
 export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
 export interface Reference { id: string; label: string; type: 'image' | 'video' | 'pose'; path: string; width?: number; height?: number }
@@ -74,7 +74,9 @@ export function parseManifest(input: unknown): ReviewManifest {
 /** `options.handoff` are the explicit `--config …` flags; they win over the manifest block and discovery. */
 export async function loadReview(input: string, options: { handoff?: HandoffFlags } = {}): Promise<ReviewPackage> {
   const inputPath=await realpath(resolve(input));const directory=(await stat(inputPath)).isDirectory();
-  if(directory){try{await stat(resolve(inputPath,'review.json'));return loadReview(resolve(inputPath,'review.json'),options);}catch(e){if((e as NodeJS.ErrnoException).code!=='ENOENT')throw e;}}
+  if(directory){try{await stat(resolve(inputPath,'review.json'));return loadReview(resolve(inputPath,'review.json'),options);}catch(e){if((e as NodeJS.ErrnoException).code!=='ENOENT')throw e;}
+    // #149: a rig-parts build root without a model of its own opens as its check package, exactly as opening check/ does.
+    const check=await buildCheckPackage(inputPath);if(check)return loadReview(check,options);}
   const manifestPath=inputPath;const root=directory?inputPath:await realpath(dirname(inputPath));
   const manifest=directory?await folderManifest(root):parseManifest(JSON.parse(await readFile(manifestPath,'utf8')));
   const files = new Set([...(directory?[]:[relative(root,manifestPath)]),...manifest.references.map(v=>v.path),...manifest.authoring.map(v=>v.path),...manifest.audio.clips.map(v=>v.path)]);
@@ -112,9 +114,17 @@ export async function loadReview(input: string, options: { handoff?: HandoffFlag
   return {root,manifestPath,manifest,sourceHash:hash.digest('hex'),reviewedSource,files,report,feedbackCatalog,handoff,handoffReason,...(handoff?.flags?{handoffInputs:handoff.flags}:{})};
 }
 
+/**
+ * #149: the `check/` package of a rig-parts build root ({@link isBuildRoot}), when the folder has neither of the two
+ * adapter model paths itself (a folder that does keeps opening as before). Fixed names, no search.
+ */
+export async function buildCheckPackage(dir:string):Promise<string|null>{
+  for(const candidate of ['skeleton.model.json','build/skeleton.model.json']){try{await lstat(resolve(dir,candidate));return null;}catch(e){if(!['ENOENT','ENOTDIR'].includes((e as NodeJS.ErrnoException).code??''))throw e;}}
+  return await isBuildRoot(dir)?resolve(dir,'check'):null;
+}
 /** Same text for every command; `root` lets the open launcher name the refused input. */
 export class UnrecognizedOutputError extends Error {
-  constructor(readonly root:string){super('Output folder: no recognized skeleton.*, build/skeleton.model.json, motion.json, report.json, source video, pose sequence or contact strip');}
+  constructor(readonly root:string){super('Output folder: no recognized skeleton.*, build/skeleton.model.json, rig-parts build root (check/build/skeleton.model.json), motion.json, report.json, source video, pose sequence or contact strip');}
 }
 /** An adapter over an existing output directory; never writes a manifest there. */
 async function folderManifest(root:string):Promise<ReviewManifest>{

package/src/open-protocol.ts

@@ -18,10 +18,11 @@ export const capabilityHeader='X-Review-Capability',openNonceHeader='X-Review-Op
 export const capabilityPattern=/^[a-f0-9]{64}$/;
 export function sameSecret(actual:string|null,expected:string):boolean{const a=Buffer.from(actual??''),b=Buffer.from(expected);return a.length===b.length&&timingSafeEqual(a,b);}
 /** Every non-GET request needs this instance's page capability, compared in constant time before any
- * Origin check. GET /api/access only says whether one is required; no endpoint ever returns it. */
-export function accessGate(req:Request,capability:string|undefined):Response|null{
+ * Origin check. GET /api/access only says whether one is required; no endpoint ever returns it. It also says
+ * whether this instance serves agent control, so a page without it never probes `/api/control/config` (#164). */
+export function accessGate(req:Request,capability:string|undefined,control=false):Response|null{
  const url=new URL(req.url),headers={'Cache-Control':'no-store','X-Content-Type-Options':'nosniff'};
- if(url.pathname==='/api/access')return req.method==='GET'||req.method==='HEAD'?Response.json({schema:'rig-review-access/1',capabilityRequired:!!capability},{headers}):Response.json({error:'Method not allowed'},{status:405,headers});
+ if(url.pathname==='/api/access')return req.method==='GET'||req.method==='HEAD'?Response.json({schema:'rig-review-access/1',capabilityRequired:!!capability,control},{headers}):Response.json({error:'Method not allowed'},{status:405,headers});
  if(!capability||req.method==='GET'||req.method==='HEAD')return null;
  return sameSecret(req.headers.get(capabilityHeader),capability)?null:Response.json({error:'REVIEW_CAPABILITY_REQUIRED: reopen with rig-review open to edit'},{status:403,headers});
 }

package/src/open.ts

@@ -16,7 +16,14 @@ import {selectAnimation,AnimationSelectionError,type AnimationSelection} from '.
 import {capabilityHeader,capabilityPattern,type OpenIdentity} from './open-protocol.ts';
 import {ensureFront,frontPort} from './front.ts';
 import {playPackagePath} from './versions.ts';
-import {HandoffError,HANDOFF_FLAGS,type HandoffFlags} from './handoff.ts';
+import {HandoffError,HANDOFF_FLAGS,isBuildRoot,type HandoffFlags,type HandoffRecord} from './handoff.ts';
+/** #149: an opened rig-parts build check package — its canonical path and the handoff record (or the refusal line). */
+export interface BuildOpen {package:string;handoff:HandoffRecord|null;reason:string|null}
+/** The stderr diagnostic for {@link BuildOpen}: the package opened, then how the config was found, its package-relative path and full SHA-256. */
+export function buildOpenDiagnostic(build:BuildOpen):string{
+ const h=build.handoff,how=!h?'':h.how==='declared'?`declared (${h.via})`:h.outside?'discovered outside the opened folder':'discovered';
+ return `Package: rig-parts build check package ${build.package}\n${h?`Handoff ${how}: ${h.config.path} sha256 ${h.config.sha256}${h.parts?` · parts ${h.parts}`:''}`:`Handoff: ${build.reason??'none'}`}`;
+}
 /** `direct` chooses how the page is reached (own port instead of the managed front); it is not part of the instance identity. */
 export interface OpenInputs {input:string;compare?:string;reference?:string;animation?:string;control?:boolean;direct?:boolean;config?:string;parts?:string;source?:string;full?:string;head?:string;keypoints?:string}
 /** The producer handoff flags (#101) among the inputs, or undefined when none was given. */
@@ -97,7 +104,7 @@ async function openRefusal(error:unknown,inputs:OpenInputs):Promise<unknown>{
 }
 /** Managed is the default: the printed URL goes through the one loopback front (127.0.0.1:4318, or
  * RIG_REVIEW_FRONT_PORT) so browser storage keeps one origin across reopens. `direct` keeps the worker's own port. */
-export async function openReview(inputs:OpenInputs,options:{stateDir?:string;idleMs?:number;direct?:boolean;frontPort?:number;frontIdleMs?:number}={}):Promise<{url:string;reused:boolean;nonce:string;inputs:OpenInputs;selection:AnimationSelection|null;direct:boolean}>{
+export async function openReview(inputs:OpenInputs,options:{stateDir?:string;idleMs?:number;direct?:boolean;frontPort?:number;frontIdleMs?:number}={}):Promise<{url:string;reused:boolean;nonce:string;inputs:OpenInputs;selection:AnimationSelection|null;direct:boolean;build:BuildOpen|null}>{
  const direct=options.direct??inputs.direct??false,port=direct?0:frontPort(options.frontPort);
  for(const path of [inputs.input,...(inputs.compare!==undefined?[inputs.compare]:[])])await assertOpenInput(path);
  if(inputs.compare!==undefined&&!inputs.reference)throw new Error('OPEN_REFERENCE_REQUIRED: compare: explicit --reference required');
@@ -108,7 +115,9 @@ export async function openReview(inputs:OpenInputs,options:{stateDir?:string;idl
  const control=join(stateDir,'open');await mkdir(control,{recursive:true,mode:0o700});const canonicalControl=await realpath(control);if((await lstat(control)).isSymbolicLink())throw new Error('open.state: control directory cannot be a symlink');
  const worker=await ensureWorker(p,key,fingerprint,stateDir,canonicalControl,options.idleMs??30*60*1000);
  const url=direct?openUrl(worker.row):openUrl(worker.row,await ensureFront({control:canonicalControl,port,fingerprint,idleMs:options.frontIdleMs}));
- return {url,reused:worker.reused,nonce:worker.row.nonce,inputs:p.inputs,selection:p.selection,direct};
+ // #149: the check package of a rig-parts build root says which package it opened and which config the handoff took.
+ const build=p.mode==='single'&&basename(p.p.root)==='check'&&await isBuildRoot(dirname(p.p.root))?{package:p.p.root,handoff:p.p.reviewedSource.handoff??null,reason:p.p.handoffReason}:null;
+ return {url,reused:worker.reused,nonce:worker.row.nonce,inputs:p.inputs,selection:p.selection,direct,build};
 }
 async function ensureWorker(p:OpenPackage,key:string,fingerprint:string,stateDir:string,canonicalControl:string,idleMs:number):Promise<{row:RecordFile;reused:boolean}>{
  const registry=join(canonicalControl,key+'.json'),claim=join(canonicalControl,key+'.claim'),nonce=randomUUID(),deadline=performance.now()+20000;