@rig-c/review 1.2.1 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -10,7 +10,7 @@ order. Adapter means downstream consumer integration through the published
10
10
  on them. Existing producer formats and playback dependencies
11
11
  remain authoritative.
12
12
 
13
- The CLI also accepts an existing output directory. It reads a root `review.json` when present. Otherwise it constructs this contract in memory: optional root `skeleton.model.json`, otherwise the fixed rigc build path `build/skeleton.model.json`; read-only `skeleton.*`, `motion.json` and `report.json` links; root videos (`mp4`, `webm`, `mov`); image filenames containing strip/contact/sheet/filmstrip/띠; and canonical `*pose*.json` references. The root compiled model takes precedence over the build path. These are the only two automatically recognized model paths; discovery never searches recursively. One fixed layout redirects instead (#149): a folder with neither model path that is a `rig-parts build` output root — regular `parts.json` and `rig/rig.json`, a real (not symlinked) `check/` directory, and an existing `check/build/skeleton.model.json` entry — opens as its `check/` package. The package root is then `check/`, exactly as if `check/` had been opened: the same manifest, source hash, `reviewedSource`, session and open key. A folder missing any of those files is not a build root and is refused or adapted as before; a build root that also holds a model of its own opens as itself. The opened directory remains the package root, so root motion/references accompany the build model and its model-relative pages. An existing selected model with an invalid type, dangling symlink, escaping symlink or invalid model envelope is refused rather than skipped. Each reference is shown separately; no source relationship, FPS or video synchronization is inferred. It never inserts or rewrites a manifest or motion file in the source folder. Raw Spine JSON/skel remains read-only evidence with playback unavailable. The folder revision is `folder-adapter/1`; actual changed file bytes are distinguished by the source hash.
13
+ The CLI also accepts an existing output directory. It reads a root `review.json` when present. Otherwise it constructs this contract in memory: optional root `skeleton.model.json`, otherwise the fixed rigc build path `build/skeleton.model.json`; read-only `skeleton.*`, `motion.json` and `report.json` links; root videos (`mp4`, `webm`, `mov`); image filenames containing strip/contact/sheet/filmstrip/띠; and canonical `*pose*.json` references. The root compiled model takes precedence over the build path. These are the only two automatically recognized model paths; discovery never searches recursively. One fixed layout redirects instead (#149): a folder with neither model path that is a `rig-parts build` output root — regular `parts.json` and `rig/rig.json`, a real (not symlinked) `check/` directory, and an existing `check/build/skeleton.model.json` entry — opens as its `check/` package. The package root is then `check/`, exactly as if `check/` had been opened: the same manifest, source hash, `reviewedSource`, session and open key. A folder missing any of those files is not a build root and is refused or adapted as before; a build root that also holds a model of its own opens as itself. The opened directory remains the package root, so root motion/references accompany the build model and its model-relative pages. An existing selected model with an invalid type, dangling symlink, escaping symlink or invalid model envelope is refused rather than skipped. Each reference is shown separately; no source relationship, FPS or video synchronization is inferred. When the producer handoff knows the source painting (#329: a declared `source`, or `painting.png` beside a discovered config — *Producer handoff*, below), that painting is the first reference, labelled `Original painting · <file name>`, and the first checkpoint, so it is the reference selected on open; the contact sheet and every other adapted reference follow it unchanged. It sits outside the package, so it is never a package asset: it is served at the fixed read-only route `/review-painting` (the managed front passes it through for single reviews) by the SHA-256 pinned at load (a changed file is refused, HTTP 409), and `/api/review` names it as `sourcePainting: {id, path, sha256, url}` with the record's relative path. Its hash enters `sourceHash` and the handoff record, so changed painting bytes start a new session. When the handoff knows no painting, the references, checkpoints and source hash are exactly what they were before. A review.json package keeps its own checkpoints: the painting is listed first and is selected on open only when the first checkpoint names no reference. It never inserts or rewrites a manifest or motion file in the source folder. Raw Spine JSON/skel remains read-only evidence with playback unavailable. The folder revision is `folder-adapter/1`; actual changed file bytes are distinguished by the source hash.
14
14
 
15
15
  `review.json` is UTF-8 JSON. Its directory is the package root. Required keys are `schema: "rig-review/1"`, `id`, `title`, and `revision`. `id` and every entry ID match `[A-Za-z0-9][A-Za-z0-9._-]{0,127}`. Titles and revision strings are nonempty. Optional collections normalize to empty arrays.
16
16
 
@@ -152,11 +152,13 @@ An Apply rebuilds through the installed producer from the files the inspected ri
152
152
  3. **Discovered inside the opened folder**: `config.json`, then `rig/config.json`.
153
153
  4. **Discovered beside an opened `out/`**: `../config.json`. It is outside the opened folder, so the record says `"how": "discovered", "outside": true` and the editor bar says *discovered outside the opened folder*, with its path and SHA-256. This step runs only when the opened folder is named `out`, and only for a regular file there (a symlink is refused).
154
154
 
155
- 5. **The build's own config, for the `check/` package of a `rig-parts build` output root** (#149): `../config.json` (in the build root), then `../../config.json` (beside it). A `rig-parts build` records no config path or hash, so "the producer's own config for that build" is defined by place, bounded by the build's own files: the opened package root is named `check` and its parent is a build root as recognized above, and the config is the regular file named `config.json` directly in that build root or directly in the folder holding it — the two places `rig-parts build --config <dir>/config.json --out <dir>/out` leaves it. No other parent and no other file name is looked at; a symlink there is refused (`HANDOFF_SYMLINK_ESCAPE`), never followed. The root for this step is the config's folder, the parts directory is the build root, and the record says `"how": "discovered", "outside": true` with the path (`../../config.json`) and SHA-256. Place is not proof that the config built the rig: the session baseline below is that check (`reproduced` or `not-reproduced`, by name). Declaring `--config` at exactly one of those two files (as written, its parent chain canonicalized) is taken the same way with `"how": "declared"`; that file's folder is then the root for `--parts`, `--source`, `--full`, `--head` and `--keypoints`. The build records none of those, so they stay declared-only. When nothing is at either place the refusal lists them: `MODELING_INPUT_UNAVAILABLE: config.json — looked at config.json, rig/config.json, ../config.json (in the build root), ../../config.json (beside the build root); declare it with …`.
155
+ 5. **The build's own config, for the `check/` package of a `rig-parts build` output root** (#149): `../config.json` (in the build root), then `../../config.json` (beside it). A `rig-parts build` records no config path or hash, so "the producer's own config for that build" is defined by place, bounded by the build's own files: the opened package root is named `check` and its parent is a build root as recognized above, and the config is the regular file named `config.json` directly in that build root or directly in the folder holding it — the two places `rig-parts build --config <dir>/config.json --out <dir>/out` leaves it. No other parent and no other file name is looked at; a symlink there is refused (`HANDOFF_SYMLINK_ESCAPE`), never followed. The root for this step is the config's folder, the parts directory is the build root, and the record says `"how": "discovered", "outside": true` with the path (`../../config.json`) and SHA-256. Place is not proof that the config built the rig: the session baseline below is that check (`reproduced` or `not-reproduced`, by name). Declaring `--config` at exactly one of those two files (as written, its parent chain canonicalized) is taken the same way with `"how": "declared"`; that file's folder is then the root for `--parts`, `--source`, `--full`, `--head` and `--keypoints`. The build records none of those, so they stay declared-only — except the source painting, which is discovered by one fixed name (below). When nothing is at either place the refusal lists them: `MODELING_INPUT_UNAVAILABLE: config.json — looked at config.json, rig/config.json, ../config.json (in the build root), ../../config.json (beside the build root); declare it with …`.
156
+
157
+ **Source painting (#329).** A discovered handoff (steps 3–5) takes as its source painting the file named `painting.png` directly beside the config it found — `painting.png` or `rig/painting.png` inside the opened folder, `../painting.png` beside an opened `out/`, and for a build's `check/` package `../painting.png` (in the build root) or `../../painting.png` (beside it) — and nothing else: no other name, no other folder, no search (a painting in `inputs/` is declared with `--source`). It is held to the config's own rules at that place: it must stay inside the same root, must be a regular file (`HANDOFF_INPUT_INVALID`), and at the places outside the opened folder (steps 4 and 5) any symlink is refused (`HANDOFF_SYMLINK_ESCAPE`), never followed; inside the opened folder a symlink that leaves the root is refused the same way. The field names the place (`../../painting.png`). When present it is the record's `source`, exactly as a declared `--source` is, and is the handoff source the Bones check's `propose --from-config` reads; it declares no `--full`, so a `build` Apply still refuses for the See-through runs. Absent, the record's `source` stays `null` and nothing else changes.
156
158
 
157
159
  Without `--parts` the parts directory is `out/` beside the config (for step 4, the opened `out/` itself; for step 5, the build root). A declared or discovered path that is missing, outside its root (the package root; for step 4 the folder holding `out/`; for step 5 the config's folder), or a symlink that leaves it is refused by name: `HANDOFF_PATH_OUTSIDE_ROOT`, `HANDOFF_SYMLINK_ESCAPE`, `HANDOFF_INPUT_MISSING`, `HANDOFF_INPUT_INVALID`, `HANDOFF_PATH_INVALID` (`open` prefixes `OPEN_HANDOFF_INVALID <flag or path>`). `rig-review open` verifies at start (before spawning or reusing a worker) that every inspected package has a compiled `model` that `@rig-c/play` loads and decodes, and in single mode by default also requires a complete producer handoff (`handoffGap`, `producerInputs`, `resolveProducer`, `contourParts`), exiting non-zero with `OPEN_MODEL_UNAVAILABLE: <reason>` when the model or handoff is missing or broken. Passing `--view-only` explicitly permits opening a compiled model that has no producer handoff at all (`handoff === null`), in which case `/api/rebuild` reports the neutral status `"view only, no producer handoff"` (with `viewOnly: true`) and no panel renders a `MODELING_*` error string; a declared or partially-present handoff with a gap still refuses `OPEN_MODEL_UNAVAILABLE: <reason>` even with `--view-only`. When `startServer` runs directly without `--view-only` and no handoff is found, `/api/rebuild` reports `MODELING_INPUT_UNAVAILABLE: config.json — looked at config.json, rig/config.json, ../config.json (beside an opened out/); declare it with rig-review open <dir> --config <path> [--parts <dir>] or the review.json "producer" block`, and Apply refuses `MODELING_HANDOFF_MISSING`.
158
160
 
159
- **Hashed files.** The config; the files the config names that the producer resolves against the config's directory (`motion.animations_from`, `generation.control.skeleton`; each must stay inside the root, a missing one is listed in `missing`); `parts.json` and every regular file directly in `parts/`; every regular file directly in the inspected `rig/` (`rig.json`, `motion.json`, `mesh_report.json`, `sets.json`, …) and `rig/images/`; with `--source`/`--full`/`--head`, that PNG and the regular files directly in those directories; with `--keypoints` (#111; the review.json block's `keypoints`), that file — the same path rules as `--source` (literal, inside the root, no symlink escape).
161
+ **Hashed files.** The config; the files the config names that the producer resolves against the config's directory (`motion.animations_from`, `generation.control.skeleton`; each must stay inside the root, a missing one is listed in `missing`); `parts.json` and every regular file directly in `parts/`; every regular file directly in the inspected `rig/` (`rig.json`, `motion.json`, `mesh_report.json`, `sets.json`, …) and `rig/images/`; with `--source`/`--full`/`--head`, that PNG and the regular files directly in those directories; for a discovered handoff, the `painting.png` beside its config when there is one; with `--keypoints` (#111; the review.json block's `keypoints`), that file — the same path rules as `--source` (literal, inside the root, no symlink escape).
160
162
 
161
163
  **Record and identity.** `reviewedSource.handoff` (absent when there is no handoff, so earlier identities are unchanged):
162
164
 
@@ -248,7 +250,7 @@ Play retains the standing patch across new play, seek, skin replay and composed-
248
250
 
249
251
  The issue export adds an `Applied:` line for a valid record (`patch <hash>… (rig; replace /constraints/0/damping) with @rig-c/parts 1.42.0 · check PASS · rig.json differs at 1 path(s) · motion.json, sets.json, mesh_report.json unchanged · 31 images unchanged · model <hash>…`; a record without `files` says `rig.json differs at N path(s)` alone); the raw context follows it. The review's `reviewedSource` still names the inspected build.
250
252
 
251
- **Bones (#109).** `GET /api/rebuild` also returns `bones`: the handoff config's `bones` list as written (or `null` without a handoff). The Bones block's edits are ordinary config patch ops, `{op:"replace", path, value:[x, y], name}` with `path` one of `/bones/<i>/at`, `/bones/<i>/points/<k>`, `/bones/<i>/tip` (rig px) and `name` the entry's `name` — a chain entry, which has none, is named by its `chain`, and `EDIT_PATCH_NAME_MISMATCH` checks it the same way. Apply sends them as one `rig` patch (no flag), so it needs the reproduced baseline. `POST /api/bones-check` (single review; same-origin, capability, 64 KiB) takes exactly `{ops, configHash}`; every op must be such a `replace` (anything else is HTTP 400 `BONES_OP_OUT_OF_SCOPE`), and the patch refusals apply (`EDIT_PATCH_STALE`, `EDIT_PATCH_NAME_MISMATCH`, `EDIT_PATCH_PATH_MISSING`, `EDIT_PATCH_PATH_HELD`; producer resolution refusals verbatim; `BONES_CHECK_BUSY`), as HTTP 200 `{status:"refused", error}`. It writes the patched config (`scratchConfigText`) to `<state>/bones-check/<package hash>/<ops hash>/config.json`, runs `rig-parts propose --parts <handoff parts> --source <handoff source> --out propose --from-config config.json` and `rig-parts compare --left <handoff config> --right config.json` there, removes the directory, and returns `{schema:"rig-review-bones-check/1", status:"checked", request:{configHash, opsSha256, ops}, producer, propose:{status:"ran"|"unavailable", exitCode, wallMs, lint[], summary, coverage[], line}, compare:{exitCode, wallMs, origins:[{bone, distance|null, tip|null, text}], summary[], line}}`. `propose.line` is the LINT count line, propose's named refusal when it exits non-zero without a LINT line, or — when the handoff declares no source painting — `MODELING_INPUT_UNAVAILABLE: source painting — propose --from-config reads the painting (--source) and the handoff declares none; declare it with rig-review open <dir> --config <path> --source <png> --full <dir> or the review.json "producer" block`. Nothing is written into the package.
253
+ **Bones (#109).** `GET /api/rebuild` also returns `bones`: the handoff config's `bones` list as written (or `null` without a handoff). The Bones block's edits are ordinary config patch ops, `{op:"replace", path, value:[x, y], name}` with `path` one of `/bones/<i>/at`, `/bones/<i>/points/<k>`, `/bones/<i>/tip` (rig px) and `name` the entry's `name` — a chain entry, which has none, is named by its `chain`, and `EDIT_PATCH_NAME_MISMATCH` checks it the same way. Apply sends them as one `rig` patch (no flag), so it needs the reproduced baseline. `POST /api/bones-check` (single review; same-origin, capability, 64 KiB) takes exactly `{ops, configHash}`; every op must be such a `replace` (anything else is HTTP 400 `BONES_OP_OUT_OF_SCOPE`), and the patch refusals apply (`EDIT_PATCH_STALE`, `EDIT_PATCH_NAME_MISMATCH`, `EDIT_PATCH_PATH_MISSING`, `EDIT_PATCH_PATH_HELD`; producer resolution refusals verbatim; `BONES_CHECK_BUSY`), as HTTP 200 `{status:"refused", error}`. It writes the patched config (`scratchConfigText`) to `<state>/bones-check/<package hash>/<ops hash>/config.json`, runs `rig-parts propose --parts <handoff parts> --source <handoff source> --out propose --from-config config.json` and `rig-parts compare --left <handoff config> --right config.json` there, removes the directory, and returns `{schema:"rig-review-bones-check/1", status:"checked", request:{configHash, opsSha256, ops}, producer, propose:{status:"ran"|"unavailable", exitCode, wallMs, lint[], summary, coverage[], line}, compare:{exitCode, wallMs, origins:[{bone, distance|null, tip|null, text}], summary[], line}}`. `propose.line` is the LINT count line, propose's named refusal when it exits non-zero without a LINT line, or — when the handoff has no source painting, declared or discovered (#329) — `MODELING_INPUT_UNAVAILABLE: source painting — propose --from-config reads the painting (--source) and the handoff declares none; declare it with rig-review open <dir> --config <path> --source <png> --full <dir> or the review.json "producer" block`. Nothing is written into the package.
252
254
 
253
255
  **Rig fields (#110).** `GET /api/rebuild` also returns `fields`: the handoff config's `regions`, `motion.blink` (as `{motion:{blink}}`), `stops`, `bones` and `turn` as written, an absent section left out (or `null` without a handoff). The Rig fields block's edits are ordinary config patch ops, each at its field's pointer (rig-parts AUTHORING §3): `{op:"replace", path:"/regions/<part>", value:<bone>}`; `{op:"add", path:"/motion/blink/still/<part>", value:{row, bone}}` (preceded by `{op:"add", path:"/motion/blink/still", value:{}}` when the config states no `still`) or `{op:"remove", path:"/motion/blink/still/<part>"}`; `{op:"replace", path:"/stops/<i>", value:<the entry with inward / outward changed>, name:<its chain>}`; `{op:"add"|"remove", path:"/bones/<i>/inherit", value:<mode>, name}` or `path:"/bones/<i>/link_inherit", value:{<link>: mode}`; `{op:"replace", path:"/turn/pivot"|"/turn/depths/<part>", value:<number>}`. A `stops` entry is named by its `chain` and `EDIT_PATCH_NAME_MISMATCH` checks it as it checks a `bones` entry. The page refuses anything else before sending (`RIG_FIELDS_OP_OUT_OF_SCOPE`; `turn.deform` is out of scope) and sends the ops as one `rig` patch (no flag), so it needs the reproduced baseline: none of its pointers is in retune's scope (*Routing*). The producer judges every value and its refusal comes back verbatim as the job's `producerLine`. The turn dial is play's `adjust` on the drawn build's `turn` bone; it is not a patch op and nothing records it. Nothing is written into the package.
254
256
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rig-c/review",
3
- "version": "1.2.1",
3
+ "version": "1.3.0",
4
4
  "type": "module",
5
5
  "description": "Local human rig inspection and structured feedback export",
6
6
  "license": "MIT",
package/src/front.ts CHANGED
@@ -55,7 +55,7 @@ export function frontRoute(mode:'single'|'compare',method:string,path:string):Ro
55
55
  const session=mode==='single'?'/api/session':'/api/compare/session',strip=mode==='single'?'/api/strip':'/api/compare/strip';
56
56
  if(path===session)return read?get:method==='PUT'?{mutation:true,limit:1024*1024,timeoutMs:30000,control:false}:null;
57
57
  if(path===strip)return method==='POST'?{mutation:true,limit:1024*1024,timeoutMs:120000,control:false}:null;
58
- const reads=mode==='single'?['/api/review','/review-reference']:['/api/compare','/api/compare/reference-frames','/compare-reference'];
58
+ const reads=mode==='single'?['/api/review','/review-reference','/review-painting']:['/api/compare','/api/compare/reference-frames','/compare-reference'];
59
59
  if(reads.includes(path))return read?get:null;
60
60
  if((mode==='single'?/^\/assets\/[^/]/:/^\/compare-assets\/(a|b)\/[^/]/).test(path))return read?get:null;
61
61
  // Apply · Rebuild and producer checks: un-prefixed in single mode, side-scoped (/api/compare/(a|b)/*, /compare-rebuild/(a|b)/*) in compare mode (#234).
package/src/handoff.ts CHANGED
@@ -16,6 +16,11 @@
16
16
  * config, so this is a location rule bounded by the build's own files, not a proof: the session baseline (the producer
17
17
  * rebuilding the inspected rig from that config) is the check. Discovered there, or declared with `--config` at exactly
18
18
  * one of those two files, the handoff's root is that file's folder and the parts directory is the build root.
19
+ *
20
+ * #329: a discovered handoff knows its source painting by one fixed name beside the config it found, `painting.png`
21
+ * (so `../painting.png` beside an opened `out/`, `../../painting.png` beside a build root), never by a search. It is
22
+ * held to the config's own refusals at that place — inside the same root, and at the two places outside the opened
23
+ * folder no symlink at all — and when present it is the record's `source` like a declared one.
19
24
  */
20
25
  import { createHash } from 'node:crypto';
21
26
  import { lstat, readdir, readFile, realpath, stat } from 'node:fs/promises';
@@ -34,6 +39,8 @@ export const CONFIG_NAMED_FILES = [['motion', 'animations_from'], ['generation',
34
39
  /** 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. */
35
40
  export const RIG_FILES = ['rig.json', 'motion.json', 'mesh_report.json'] as const;
36
41
  const MAX_LISTED = 4096;
42
+ /** #329: the fixed name a discovered handoff's source painting has beside its config. */
43
+ export const DISCOVERED_PAINTING = 'painting.png';
37
44
 
38
45
  export interface HandoffDeclaration { config: string; parts?: string; source?: string; full?: string; head?: string; keypoints?: string }
39
46
  export type HandoffFlags = HandoffDeclaration;
@@ -127,6 +134,18 @@ async function blockPath(root: string, value: unknown, field: string, kind: 'fil
127
134
  return contained(root, join(root, value), field, kind, true);
128
135
  }
129
136
 
137
+ /**
138
+ * #329: the painting beside a discovered config — `field` is the config's own place with its file name swapped — or
139
+ * undefined when nothing is there. `strict` (a place outside the opened folder) refuses any symlink, as for the config.
140
+ */
141
+ async function discoveredPainting(base: string, config: string, configField: string, strict: boolean): Promise<string | undefined> {
142
+ const path = join(dirname(config), DISCOVERED_PAINTING), field = posix.join(posix.dirname(configField), DISCOVERED_PAINTING);
143
+ if (!(await exists(path))) return undefined;
144
+ const real = await contained(base, path, field, 'file', true);
145
+ if (strict && real !== path) throw new HandoffError('HANDOFF_SYMLINK_ESCAPE', field, `${path} is a symlink; only the file beside the config is discovered`);
146
+ return real;
147
+ }
148
+
130
149
  /** `producer: {config, parts?, source?, full?, head?, keypoints?}` — strings only, no other key. Paths are checked at load. */
131
150
  export function parseHandoffDeclaration(value: unknown): HandoffDeclaration | undefined {
132
151
  if (value === undefined) return undefined;
@@ -241,7 +260,8 @@ export async function resolveHandoff(root: string, declared: HandoffDeclaration
241
260
  const path = join(root, name);
242
261
  if (!(await exists(path))) continue;
243
262
  const config = await contained(root, path, name, 'file', true);
244
- return { handoff: await record(root, root, 'discovered', 'discovery', config, join(dirname(path), 'out'), {}, false), reason: null };
263
+ const source = await discoveredPainting(root, path, name, false);
264
+ return { handoff: await record(root, root, 'discovered', 'discovery', config, join(dirname(path), 'out'), { source }, false), reason: null };
245
265
  }
246
266
  // #149: the check package of a rig-parts build root — the build's own config, in the build root, else beside it.
247
267
  const build = await buildPlaces(root);
@@ -250,7 +270,8 @@ export async function resolveHandoff(root: string, declared: HandoffDeclaration
250
270
  if (!(await exists(place.config))) continue;
251
271
  const config = await contained(place.base, place.config, place.field, 'file', true);
252
272
  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`);
253
- return { handoff: await record(root, place.base, 'discovered', 'discovery', config, build.build, {}, false), reason: null };
273
+ const source = await discoveredPainting(place.base, config, place.field, true);
274
+ return { handoff: await record(root, place.base, 'discovered', 'discovery', config, build.build, { source }, false), reason: null };
254
275
  }
255
276
  return { handoff: null, reason: BUILD_MODELING_INPUT_UNAVAILABLE };
256
277
  }
@@ -260,7 +281,8 @@ export async function resolveHandoff(root: string, declared: HandoffDeclaration
260
281
  if (await exists(path)) {
261
282
  const config = await contained(parent, path, '../config.json', 'file', true);
262
283
  if (config !== path) throw new HandoffError('HANDOFF_SYMLINK_ESCAPE', '../config.json', `${path} is a symlink; only the file beside out/ is discovered`);
263
- return { handoff: await record(root, parent, 'discovered', 'discovery', config, root, {}, false), reason: null };
284
+ const source = await discoveredPainting(parent, config, '../config.json', true);
285
+ return { handoff: await record(root, parent, 'discovered', 'discovery', config, root, { source }, false), reason: null };
264
286
  }
265
287
  }
266
288
  return { handoff: null, reason: MODELING_INPUT_UNAVAILABLE };
package/src/manifest.ts CHANGED
@@ -28,7 +28,9 @@ export interface ReviewPackage { referenceHashes?:Record<string,string>; root: s
28
28
  /** #187: the rig-parts build root ({@link isBuildRoot}) whose `check/` this package is, however it was opened; review state stays outside it. */
29
29
  buildRoot?: string;
30
30
  /** #305: viewer-only open (`--view-only`). */
31
- viewOnly?: boolean }
31
+ viewOnly?: boolean;
32
+ /** #329: the handoff's source painting, served at a fixed route by its pinned hash; absent when the handoff knows none. */
33
+ sourcePainting?: SourcePainting }
32
34
  function fail(field: string, expected: string): never { throw new Error(`${field}: expected ${expected}`); }
33
35
  export function object(value: unknown, field: string): Record<string, unknown> { if (!value || typeof value !== 'object' || Array.isArray(value)) fail(field, 'object'); return value as Record<string, unknown>; }
34
36
  export function string(value: unknown, field: string): string { if (typeof value !== 'string' || !value.trim() || value.length > 10000) fail(field, 'nonempty string (at most 10000 characters)'); return value; }
@@ -106,21 +108,42 @@ export async function loadReview(input: string, options: { handoff?: HandoffFlag
106
108
  for(const j of joints) if(j.parent&&!joints.some(v=>v.id===j.parent&&v.id!==j.id)) fail(`pose ${r.id} joint ${j.id}.parent`,'another declared joint id');
107
109
  }
108
110
  const reportPath=files.has('report.json')?'report.json':authoringPath('report.json');let report:ReportSeeds|null=null;let modelMetadata:Record<string,unknown>|null=null;
111
+ // The handoff files are hashed beside the package: their record joins the reviewed identity (and so the session file).
112
+ const {handoff,reason:handoffReason}=await resolveHandoff(root,manifest.producer,options.handoff);
113
+ // #329: the source painting the handoff knows is the first reference, outside the package's own files.
114
+ const painting=sourcePainting(manifest,handoff,directory);
109
115
  const hash = createHash('sha256');hash.update(JSON.stringify(manifest));hash.update('\0');const fileHashes=new Map<string,string>();
110
116
  for(const p of [...files].sort()) { const full=await safeFile(root,p); const before=await stat(full); hash.update(p);hash.update('\0');hash.update(String(before.size));hash.update('\0'); const fileHash=createHash('sha256');const metadataChunks:Buffer[]=[];for await(const chunk of createReadStream(full)){hash.update(chunk);fileHash.update(chunk);if(p===reportPath||p===manifest.model)metadataChunks.push(chunk);}fileHashes.set(p,fileHash.digest('hex')); const after=await stat(full); if(before.size!==after.size||before.mtimeMs!==after.mtimeMs) throw new Error(`Asset ${p} changed while hashing; retry with stable package inputs`);
111
117
  // The parser and package hash consume the same bytes, never two file reads.
112
118
  if(p===manifest.model){if(fileHashes.get(p)!==modelBytesHash)throw new Error(`Model ${p} changed while hashing; retry with stable package inputs`);modelMetadata=object(JSON.parse(Buffer.concat(metadataChunks).toString('utf8')),'model');}
113
119
  if(p===reportPath){let value:unknown;try{value=JSON.parse(Buffer.concat(metadataChunks).toString('utf8'));}catch(e){throw new Error(`${p}: ${e instanceof Error?e.message:String(e)}`);}report=parseReport(value,p);}
114
120
  }
115
- // The handoff files are hashed beside the package: their record joins the reviewed identity (and so the session file).
116
- const {handoff,reason:handoffReason}=await resolveHandoff(root,manifest.producer,options.handoff);
121
+ if(painting){hash.update(SOURCE_PAINTING_ID);hash.update('\0');hash.update(painting.sha256);hash.update('\0');}
117
122
  // #192: the root is `check/` whether the folder or its review.json was opened, so the build root is kept either way.
118
123
  const buildRoot=basename(root)==='check'&&await isBuildRoot(dirname(root))?dirname(root):undefined;
119
124
  const reviewedSource:ReviewedSource={packageRevision:manifest.revision,...await toolVersions(),rig:rigPath?{path:rigPath,sha256:fileHashes.get(rigPath)!}:null,motion:motionPath?{path:motionPath,sha256:fileHashes.get(motionPath)!}:null,...(handoff?{handoff:handoff.record}:{})};
120
125
  const feedbackCatalog:FeedbackCatalog={rig:manifest.id,bones:modelNames(modelMetadata,'bones'),slots:modelNames(modelMetadata,'slots'),animations:modelAnimations(modelMetadata),clock:report?.clock??null,clockAnimation:report?.animation??null,...(discoverTurnDials(modelMetadata).length?{turnDials:discoverTurnDials(modelMetadata)}:{})};
121
- return {referenceHashes:Object.fromEntries(manifest.references.map(r=>[r.id,fileHashes.get(r.path)!])),root,manifestPath,manifest,sourceHash:hash.digest('hex'),reviewedSource,files,report,feedbackCatalog,handoff,handoffReason,...(handoff?.flags?{handoffInputs:handoff.flags}:{}),...(buildRoot?{buildRoot}:{})};
126
+ return {referenceHashes:Object.fromEntries(manifest.references.map(r=>[r.id,r.id===painting?.id?painting.sha256:fileHashes.get(r.path)!])),root,manifestPath,manifest,sourceHash:hash.digest('hex'),reviewedSource,files,report,feedbackCatalog,handoff,handoffReason,...(handoff?.flags?{handoffInputs:handoff.flags}:{}),...(buildRoot?{buildRoot}:{}),...(painting?{sourcePainting:painting}:{})};
122
127
  }
123
128
 
129
+ /** #329: the reference id and served path of the handoff's source painting; the path is a name, never a package file. */
130
+ export const SOURCE_PAINTING_ID='source-painting';
131
+ export const SOURCE_PAINTING_PATH='__review_source_painting__.png';
132
+ export interface SourcePainting {id:string;path:string;sha256:string}
133
+ /**
134
+ * #329: when the handoff knows the source painting (declared `source`, or `painting.png` beside a discovered config),
135
+ * it becomes the first reference, labelled as the original, and — for the folder adapter, whose checkpoints are one per
136
+ * reference — the first checkpoint, so it is the reference selected on open. The manifest is changed in place before it
137
+ * is hashed; with no painting nothing is added. `path` is the handoff record's own display path.
138
+ */
139
+ function sourcePainting(manifest:ReviewManifest,handoff:Handoff|null,folder:boolean):SourcePainting|null{
140
+ const record=handoff?.record.source;if(!record)return null;
141
+ if(manifest.references.some(r=>r.id===SOURCE_PAINTING_ID)||manifest.checkpoints.some(c=>c.id===SOURCE_PAINTING_ID))fail(`references ${SOURCE_PAINTING_ID}`,'an id the handoff source painting does not take');
142
+ const reference:Reference={id:SOURCE_PAINTING_ID,label:'Original painting · '+posix.basename(record.path),type:'image',path:SOURCE_PAINTING_PATH};
143
+ manifest.references.unshift(reference);
144
+ if(folder)manifest.checkpoints.unshift({id:reference.id,title:'Inspect '+reference.label,reference:reference.id,workspace:'motion'});
145
+ return {id:reference.id,path:record.path,sha256:record.sha256};
146
+ }
124
147
  /**
125
148
  * #149: the `check/` package of a rig-parts build root ({@link isBuildRoot}), when the folder has neither of the two
126
149
  * adapter model paths itself (a folder that does keeps opening as before). Fixed names, no search.
package/src/server.ts CHANGED
@@ -122,7 +122,7 @@ export async function startServer(p:ReviewPackage,options:{port?:number;stateDir
122
122
  return new Response(result.png?new Uint8Array(result.png):stripJson(result),{headers:{...headers,'Content-Type':result.png?'image/png':'application/json; charset=utf-8','Content-Disposition':`attachment; filename="review-strip.${result.png?'png':'json'}"`}});
123
123
  }
124
124
  if(req.method!=='GET'&&req.method!=='HEAD')return json({error:'Method not allowed'},405);
125
- if(url.pathname==='/api/review'){await unchanged();return json({manifest:p.manifest,initialAnimation:options.initialAnimation??null,sourceHash:p.sourceHash,reviewedSource:p.reviewedSource,...(referenceBinding(p)?{referenceBinding:referenceBinding(p),explicitReference:{...referenceBinding(p)!.reference,url:'/review-reference'}}:{}),referenceHashes:{...p.referenceHashes,...(referenceBinding(p)?{[referenceBinding(p)!.reference.id]:referenceBinding(p)!.reference.sha256}:{})},report:p.report,feedbackCatalog:p.feedbackCatalog,assetsBase:'/assets/',capabilities:{playback:!!p.manifest.model,modeling:false,motion:false,feedback:true,audio:true}});}
125
+ if(url.pathname==='/api/review'){await unchanged();return json({manifest:p.manifest,initialAnimation:options.initialAnimation??null,sourceHash:p.sourceHash,reviewedSource:p.reviewedSource,...(referenceBinding(p)?{referenceBinding:referenceBinding(p),explicitReference:{...referenceBinding(p)!.reference,url:'/review-reference'}}:{}),...(p.sourcePainting?{sourcePainting:{...p.sourcePainting,url:'/review-painting'}}:{}),referenceHashes:{...p.referenceHashes,...(referenceBinding(p)?{[referenceBinding(p)!.reference.id]:referenceBinding(p)!.reference.sha256}:{})},report:p.report,feedbackCatalog:p.feedbackCatalog,assetsBase:'/assets/',capabilities:{playback:!!p.manifest.model,modeling:false,motion:false,feedback:true,audio:true}});}
126
126
  if(url.pathname==='/api/session'){await unchanged();return json(await readSession(p,options.stateDir));}
127
127
  if(url.pathname==='/api/rebuild')return json(await rebuilds.describe());
128
128
  if(url.pathname==='/api/rebuild/history')return json(await rebuilds.history());
@@ -149,6 +149,8 @@ export async function startServer(p:ReviewPackage,options:{port?:number;stateDir
149
149
  const file=Bun.file(full);return new Response(req.method==='HEAD'?null:file,{headers:{...headers,'Content-Security-Policy':"default-src 'none'; script-src 'none'; sandbox",'Content-Type':file.type||'application/octet-stream','Content-Length':String(file.size)}});
150
150
  }
151
151
  if(url.pathname==='/review-reference')return await serveReference(req,await safeSelectedReference(p),referenceBinding(p)!.reference.sha256,headers);
152
+ // #329: the handoff's source painting sits outside the package, so it is served by its pinned hash at one fixed route.
153
+ if(url.pathname==='/review-painting'&&p.sourcePainting&&p.handoff?.source)return await serveReference(req,p.handoff.source,p.sourcePainting.sha256,headers);
152
154
  if(url.pathname.startsWith('/assets/')){
153
155
  const path=packagePath(decodeURIComponent(url.pathname.slice('/assets/'.length)));if(!p.files.has(path))return json({error:'Asset not declared by package'},404);
154
156
  const file=Bun.file(await safeFile(p.root,path));const size=file.size;
package/web/catalog-en.ts CHANGED
@@ -1035,6 +1035,7 @@ export const enCatalog: Readonly<Record<string, string>> = {
1035
1035
  "Ordered compare provenance:": "Ordered compare provenance:",
1036
1036
  "Original identifiers: {0}": "Original identifiers: {0}",
1037
1037
  "Original input pose sequence · joint states and confidence preserved": "Original input pose sequence · joint states and confidence preserved",
1038
+ "Original painting": "Original painting",
1038
1039
  "Original set": "Original set",
1039
1040
  "Other bones": "Other bones",
1040
1041
  "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": "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",
package/web/catalog-ko.ts CHANGED
@@ -1035,6 +1035,7 @@ export const koCatalog: Readonly<Record<string, string>> = {
1035
1035
  "Ordered compare provenance:": "순서가 지정된 비교 출처:",
1036
1036
  "Original identifiers: {0}": "원본 식별자: {0}",
1037
1037
  "Original input pose sequence · joint states and confidence preserved": "원본 입력 포즈 시퀀스 · 관절 상태 및 신뢰도 보존됨",
1038
+ "Original painting": "원본 그림",
1038
1039
  "Original set": "원본 세트",
1039
1040
  "Other bones": "기타 본",
1040
1041
  "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": "출력 폴더: 인식된 skeleton.*, build/skeleton.model.json, rig-parts 빌드 루트(check/build/skeleton.model.json), motion.json, report.json, 소스 비디오, 포즈 시퀀스 또는 컨택트 스트립이 없습니다",
package/web/main.ts CHANGED
@@ -66,7 +66,7 @@ import {assertRigFieldOps,RIG_FIELDS_READOUT_BARS,TURN_BONE} from '../src/rig-fi
66
66
  import {IDLE_READOUT_BARS,type LocalChannel} from '../src/idle-tracks.ts';
67
67
  import type {PatchOp} from '../src/config-patch.ts';
68
68
 
69
- interface ReviewResponse { referenceHashes?:Record<string,string>; initialAnimation?:string|null; manifest: ReviewManifest; referenceBinding?:ReferenceBinding; explicitReference?:{id:string;name:string;sha256:string;url:string}; sourceHash: string; reviewedSource: ReviewedSource; report: ReportSeeds | null; feedbackCatalog: FeedbackCatalog; assetsBase: string; capabilities: { playback: boolean; modeling: false; motion: false; feedback: boolean; audio: boolean } }
69
+ interface ReviewResponse { referenceHashes?:Record<string,string>; initialAnimation?:string|null; manifest: ReviewManifest; referenceBinding?:ReferenceBinding; explicitReference?:{id:string;name:string;sha256:string;url:string}; sourcePainting?:{id:string;path:string;sha256:string;url:string}; sourceHash: string; reviewedSource: ReviewedSource; report: ReportSeeds | null; feedbackCatalog: FeedbackCatalog; assetsBase: string; capabilities: { playback: boolean; modeling: false; motion: false; feedback: boolean; audio: boolean } }
70
70
  interface PoseReference { schema: 'rig-review-pose/1'; coordinateSystem: 'image-pixels-y-down'; width: number; height: number; joints: { id: string; x: number; y: number; parent?: string }[] }
71
71
  interface SequenceJoint { state: 'observed' | 'occluded' | 'missing' | 'inferred'; at?: [number, number]; score?: number }
72
72
  interface PoseSequence { spec: 'rig-pose-sequence/1'; space: { units: 'picture-px'; origin: 'top-left'; y: 'down' }; width: number; height: number; source?: string; frames: { t: number; people: { id: string; joints: Record<string, SequenceJoint> }[] }[]; camera?: { s: number; tx: number; ty: number; inliers: number }[]; cameraSource?: unknown }
@@ -194,7 +194,7 @@ async function api<T>(path: string, init?: RequestInit): Promise<T> {
194
194
  return await response.json() as T;
195
195
  }
196
196
 
197
- function referenceUrl(reference:Reference):string {return data.explicitReference?.id===reference.id?access.route(data.explicitReference.url):assetUrl(reference.path);}
197
+ function referenceUrl(reference:Reference):string {return data.explicitReference?.id===reference.id?access.route(data.explicitReference.url):data.sourcePainting?.id===reference.id?access.route(data.sourcePainting.url):assetUrl(reference.path);}
198
198
 
199
199
  function assetUrl(path: string): string {
200
200
  if (!path || path.startsWith('/') || /[\\%?#\x00-\x1f]/.test(path) || /^[a-zA-Z]:/.test(path) || path.split('/').some(part => !part || part === '.' || part === '..')) throw new Error(`Unsupported package asset path: ${path}`);
@@ -356,7 +356,7 @@ async function showReference(id: string): Promise<void> {
356
356
  if (!reference) { text('reference-empty', 'No reference supplied.'); text('reference-info', 'Add image, video or input-pose references to the package.'); return; }
357
357
  text('reference-label', reference.label + (reference.type === 'pose' ? ' · Static input pose' : ' · Reference'));
358
358
  text('reference-empty', 'Loading reference…');
359
- text('reference-info', `${reference.type} · ${reference.path}`);
359
+ text('reference-info', `${reference.type} · ${data.sourcePainting?.id === reference.id ? data.sourcePainting.path : reference.path}`);
360
360
  const fail = (reason='reference could not render') => { if (generation !== referenceGeneration) return; setReferenceInput({state:'failed',reason}); el('reference-empty').hidden = false; text('reference-empty', 'Could not open the reference. Check the package files.'); };
361
361
  try {
362
362
  if (reference.type === 'pose') {