rig-review 3.7.0 → 4.0.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.
Files changed (109) hide show
  1. package/README.md +1 -1
  2. package/docs/DESIGN.md +145 -74
  3. package/docs/PANELS.md +20 -12
  4. package/docs/PARTS_VIEW.md +133 -76
  5. package/docs/REVIEW_PACKAGE.md +445 -99
  6. package/docs/STABILITY.md +132 -198
  7. package/docs/WORKFLOWS.md +41 -120
  8. package/package.json +4 -3
  9. package/skills/rig-review/SKILL.md +41 -27
  10. package/src/build.ts +10 -2
  11. package/src/cli.ts +17 -16
  12. package/src/comment-crops.ts +6 -1
  13. package/src/compare-html.ts +22 -24
  14. package/src/compare-server.ts +1 -1
  15. package/src/compare-session.ts +41 -3
  16. package/src/correction-handoff.ts +27 -4
  17. package/src/create-pin-gate.ts +3 -0
  18. package/src/direction-inspection.ts +6 -2
  19. package/src/feedback-export.ts +68 -1
  20. package/src/front.ts +5 -200
  21. package/src/handoff.ts +1 -1
  22. package/src/interview-routes.ts +1 -1
  23. package/src/interview-scene.ts +3 -3
  24. package/src/job-act.ts +77 -73
  25. package/src/job-api.ts +326 -13
  26. package/src/job-checkpoint-evidence.ts +113 -0
  27. package/src/job-cli.ts +27 -14
  28. package/src/job-contract.ts +284 -62
  29. package/src/job-front.ts +157 -58
  30. package/src/job-host.ts +23 -4
  31. package/src/job-session.ts +109 -24
  32. package/src/job-source.ts +209 -57
  33. package/src/job-store.ts +80 -6
  34. package/src/job-worker.ts +1 -47
  35. package/src/joined-project.ts +61 -4
  36. package/src/manifest.ts +32 -4
  37. package/src/open-workspace.ts +12 -12
  38. package/src/open.ts +19 -12
  39. package/src/parts-comment-crops.ts +126 -31
  40. package/src/parts-comment.ts +351 -28
  41. package/src/parts-server.ts +19 -7
  42. package/src/parts-view.ts +588 -109
  43. package/src/scene-inspection.ts +50 -0
  44. package/src/server.ts +31 -22
  45. package/src/session.ts +58 -0
  46. package/src/stage-comment.ts +48 -1
  47. package/src/stage-parts.ts +23 -11
  48. package/web/animation-inspection.ts +1 -1
  49. package/web/bones-panel.ts +1 -3
  50. package/web/catalog-en.ts +175 -39
  51. package/web/catalog-ko.ts +175 -39
  52. package/web/cloth-panel.ts +1 -2
  53. package/web/compare.css +3 -13
  54. package/web/compare.html +3 -3
  55. package/web/compare.ts +69 -64
  56. package/web/cuts-panel.ts +1 -3
  57. package/web/density-strip-panel.ts +1 -2
  58. package/web/direction-panel.ts +22 -6
  59. package/web/i18n.ts +13 -1
  60. package/web/idle-panel.ts +1 -2
  61. package/web/index.html +1 -5
  62. package/web/inspection-persistence.ts +2 -1
  63. package/web/inspector-blocks.ts +149 -40
  64. package/web/instance-access.ts +24 -5
  65. package/web/interview-panel.ts +224 -175
  66. package/web/job-rig-capture.ts +164 -21
  67. package/web/job-rig-screen.ts +337 -0
  68. package/web/job-session.ts +611 -1437
  69. package/web/main.ts +614 -151
  70. package/web/mesh-panel.ts +1 -2
  71. package/web/owner-workspace.ts +88 -109
  72. package/web/part-selection.ts +47 -6
  73. package/web/part-thumbnails.ts +20 -6
  74. package/web/parts-render.ts +26 -19
  75. package/web/parts-viewport-provider.ts +181 -7
  76. package/web/physics-panel.ts +1 -2
  77. package/web/readings-panel.ts +1 -2
  78. package/web/requirements-panel.ts +1 -3
  79. package/web/retained-frame-stage.ts +105 -0
  80. package/web/retarget-panel.ts +2 -3
  81. package/web/rig-fields-panel.ts +1 -2
  82. package/web/rig-host.ts +64 -0
  83. package/web/rig-viewport-provider.ts +65 -16
  84. package/web/scene-plates.ts +57 -4
  85. package/web/stage-comments.ts +103 -46
  86. package/web/styles.css +117 -63
  87. package/web/view-controls.ts +201 -12
  88. package/web/viewport-capture.ts +12 -2
  89. package/web/viewport-controller.ts +107 -27
  90. package/web/viewport-pair.ts +2 -1
  91. package/web/workspace-preferences.ts +5 -4
  92. package/web/workspace-ui.ts +151 -19
  93. package/src/front-worker.ts +0 -2
  94. package/src/interview-server.ts +0 -54
  95. package/src/job-hub.ts +0 -304
  96. package/src/job-image-set.ts +0 -50
  97. package/web/interview.css +0 -28
  98. package/web/interview.html +0 -17
  99. package/web/interview.ts +0 -40
  100. package/web/job-hub.css +0 -14
  101. package/web/job-hub.html +0 -5
  102. package/web/job-hub.ts +0 -179
  103. package/web/owner-workspace.css +0 -14
  104. package/web/owner-workspace.html +0 -5
  105. package/web/parts-flags.ts +0 -48
  106. package/web/parts.css +0 -104
  107. package/web/parts.html +0 -49
  108. package/web/parts.ts +0 -604
  109. package/web/stage-nav.ts +0 -136
package/src/job-front.ts CHANGED
@@ -1,15 +1,19 @@
1
+ import {buildWeb} from './build.ts';
2
+ import {PNG} from 'pngjs';
3
+ import {checkpointEvidenceMetadata, readCheckpointEvidenceBytes} from './job-checkpoint-evidence.ts';
1
4
  /** Disjoint live-job routes. The backend receives the original authenticated Request. */
2
5
  import { JOB_API_SCHEMA, JOB_ACT_SCHEMA, type JobErrorCode, type JobHostPorts, type JobId, type JobPublicationMode, type JobResult, type JobReviewerBinding } from './job-contract.ts';
3
6
  import { createJobHostPorts, jobBody, jobHash, jobId, jobObject, jobPartsEnumeratorVersion } from './job-api.ts';
4
7
  import { JobSession } from './job-session.ts';
5
- import { assertJobRoot, captureJobRoot, isRetainedRecordSource, type JobRootIdentity } from './job-source.ts';
8
+ import { assertJobRoot, assertRetainedSnapshotIntact, captureJobRoot, planTextMetadata, isRetainedRecordSource, type JobRootIdentity } from './job-source.ts';
6
9
  import type { JobWorkerOptions } from './job-worker.ts';
7
- import { JobError, JobStore } from './job-store.ts';
10
+ import { JobError, JobStore, jobCropReferences } from './job-store.ts';
8
11
  import { loadReview, safeFile, packagePath, type ReviewPackage } from './manifest.ts';
9
12
  import { serveReference, assertReviewUnchanged } from './reference.ts';
10
- import { loadPartsView, partsViewJson, servedImage, type PartsViewPackage } from './parts-view.ts';
13
+ import {preparePartsComment} from './parts-comment-crops.ts';
14
+ import { loadPartsView, partsViewJson, partsDifference, servedImage, type PartsViewPackage } from './parts-view.ts';
11
15
  import { destinationDirectory, DestinationDirectoryError } from './destination-directory.ts';
12
- import { dirname, isAbsolute, join, relative, sep } from 'node:path';
16
+ import { dirname, extname, isAbsolute, join, relative, sep } from 'node:path';
13
17
  import { constants, openSync, closeSync, readSync, fstatSync, lstatSync, statSync, type Stats } from 'node:fs';
14
18
  import { lstat, mkdir, rename, writeFile } from 'node:fs/promises';
15
19
  import { randomUUID } from 'node:crypto';
@@ -22,8 +26,60 @@ const headers = {
22
26
  'Referrer-Policy': 'no-referrer',
23
27
  'Content-Security-Policy': "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' blob: data:; media-src 'self' blob:; connect-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'",
24
28
  };
25
- function failure(code: string, status: number): Response {
26
- return Response.json({ ok: false, error: { code, message: code } }, { status, headers });
29
+ interface CropFailureDiagnostic {
30
+ field: string;
31
+ expected: string | number[];
32
+ received: string | number[];
33
+ }
34
+ function failure(code: string, status: number, diagnostic?: CropFailureDiagnostic, message = code): Response {
35
+ return Response.json({ ok: false, error: { code, message, ...(diagnostic ? {diagnostic} : {}) } }, { status, headers });
36
+ }
37
+
38
+ /** Explain an existing rejection without returning body text, filesystem paths or PNG bytes. */
39
+ function cropFailureDiagnostic(error: unknown, raw: unknown): CropFailureDiagnostic {
40
+ const message = error instanceof Error ? error.message : '';
41
+ const invariants: Record<string, [string, string]> = {
42
+ 'PARTS_COMMENT_RIG_REGION: rig region must be exact placement plus image region': ['rigRegion', 'exact placement plus imageRegion'],
43
+ 'PARTS_COMMENT_OUT_OF_BOUNDS: region exceeds original image': ['imageRegion', 'inside original image bounds'],
44
+ 'PARTS_COMMENT_OUT_OF_BOUNDS: region exceeds union of issue parts': ['rigRegion', 'inside union of bound parts'],
45
+ 'PARTS_CAMERA_RANGE: native zoom below fit/1 minimum': ['view.camera.zoom', 'at least min(fit, 1)'],
46
+ 'PARTS_CAMERA_RANGE: native scale or camera extent': ['view.camera', 'bounded positive zoom and viewport'],
47
+ 'PARTS_COMMENT_IMAGE_SIZE: original dimensions differ from placement': ['part.image.dimensions', 'equal retained placement dimensions'],
48
+ 'PARTS_COMMENT_CROP_INVALID: bounded content-addressed crop': ['crop', 'bounded content-addressed PNG metadata'],
49
+ 'COMMENT_CROP_INVALID: bounded content-addressed PNG required': ['crop', 'bounded content-addressed PNG'],
50
+ 'COMMENT_CROP_INVALID: expected noninterlaced 8-bit RGB/RGBA': ['crop.png.format', 'noninterlaced 8-bit RGB/RGBA'],
51
+ 'COMMENT_CROP_INVALID: truncated PNG chunk': ['crop.png.chunks', 'complete chunks'],
52
+ 'COMMENT_CROP_INVALID: PNG chunk length': ['crop.png.chunk.length', 'inside PNG byte bounds'],
53
+ 'COMMENT_CROP_INVALID: PNG chunk CRC': ['crop.png.chunk.crc', 'matching CRC'],
54
+ 'COMMENT_CROP_INVALID: static PNG required': ['crop.png.animation', 'static PNG'],
55
+ 'COMMENT_CROP_INVALID: PNG end': ['crop.png.end', 'final empty IEND'],
56
+ 'COMMENT_CROP_INVALID: PNG data/end missing': ['crop.png.data', 'IDAT and IEND present'],
57
+ 'COMMENT_CROP_INVALID: bounded PNG data decode': ['crop.png.data', 'bounded decodable scanlines'],
58
+ 'COMMENT_CROP_INVALID: PNG scanlines': ['crop.png.scanlines', 'exact dimensions and valid filters'],
59
+ 'COMMENT_CROP_PATH: existing crop is not the bound regular PNG': ['crop.storage', 'regular file with matching SHA-256'],
60
+ 'COMMENT_CROP_PATH: regular state directory required': ['crop.storage', 'regular state directory'],
61
+ };
62
+ // Inspect metadata only after the existing validator reports this exact invariant.
63
+ if (message === 'COMMENT_CROP_INVALID: PNG signature, dimensions or SHA-256 differ' &&
64
+ raw && typeof raw === 'object' && 'crop' in raw) {
65
+ const crop = raw.crop as {png?: unknown; sha256?: unknown; width?: unknown; height?: unknown} | null;
66
+ if (crop && typeof crop.png === 'string' && crop.png.length <= 200000 &&
67
+ typeof crop.sha256 === 'string' && /^[a-f0-9]{64}$/.test(crop.sha256)) {
68
+ const bytes = Buffer.from(crop.png.slice('data:image/png;base64,'.length), 'base64');
69
+ const hash = jobHash(bytes);
70
+ if (hash !== crop.sha256) return {field: 'crop.sha256', expected: crop.sha256, received: hash};
71
+ if (bytes.length >= 24 && bytes.subarray(0, 8).toString('hex') === '89504e470d0a1a0a' &&
72
+ typeof crop.width === 'number' && typeof crop.height === 'number' &&
73
+ (crop.width !== bytes.readUInt32BE(16) || crop.height !== bytes.readUInt32BE(20))) {
74
+ return {field: 'crop.dimensions', expected: [crop.width, crop.height],
75
+ received: [bytes.readUInt32BE(16), bytes.readUInt32BE(20)]};
76
+ }
77
+ }
78
+ return {field: 'crop.png.signature', expected: 'PNG signature and IHDR', received: 'invalid'};
79
+ }
80
+ const invariant = Object.hasOwn(invariants, message) ? invariants[message] : undefined;
81
+ return invariant ? {field: invariant[0], expected: invariant[1], received: 'rejected by existing validator'} :
82
+ {field: 'partsComment.prepare', expected: 'valid source-bound crop and writable evidence state', received: 'unclassified rejection'};
27
83
  }
28
84
  const errorStatus: Partial<Record<JobErrorCode, number>> = {
29
85
  JOB_REQUEST_INVALID: 400,
@@ -44,8 +100,7 @@ function result<Value>(value: JobResult<Value>): Response {
44
100
  export function createJobFront(options: {
45
101
  origin: string;
46
102
  ports: JobHostPorts;
47
- hubIncarnation?: string;
48
- resource: (name: 'index.html' | 'job.js' | 'styles.css') => Promise<BodyInit>;
103
+ resource: (name: 'index.html' | 'main.js' | 'styles.css') => Promise<BodyInit>;
49
104
  publication?: (jobId: string, publicationId: string, instanceKey: string, path: string, request: Request) => Promise<Response>;
50
105
  }) {
51
106
  const origin = new URL(options.origin);
@@ -83,11 +138,15 @@ export function createJobFront(options: {
83
138
  return result(await options.ports.ackDisplayed(jobId, request));
84
139
  return result(await options.ports.commitUIAct(jobId, request));
85
140
  }
86
- if (!read)
141
+ const partsCrop = request.method === 'POST' &&
142
+ /^publications\/[A-Za-z0-9][A-Za-z0-9._-]{0,127}\/instances\/[a-f0-9]{64}\/api\/stage-parts\/comment$/.test(route);
143
+ if (!read && !partsCrop)
87
144
  return failure('JOB_REQUEST_INVALID', 405);
145
+ if (partsCrop && sentOrigin !== origin.origin) return failure('JOB_SAME_ORIGIN_REQUIRED', 403);
88
146
  const liveness = await options.ports.jobLiveness(jobId);
89
147
  if (!liveness.ok)
90
148
  return result(liveness);
149
+ if (/^comment-crops\/[a-f0-9]{64}\.png$/.test(route) && request.method === 'GET') return options.ports.handleJobApi(request);
91
150
  if (route === 'events' && request.method === 'GET') {
92
151
  const keys = [...url.searchParams.keys()];
93
152
  if (keys.length > 1 || keys.some(key => key !== 'after'))
@@ -112,7 +171,7 @@ export function createJobFront(options: {
112
171
  controller.close();
113
172
  }
114
173
  else {
115
- controller.enqueue(encoder.encode(JSON.stringify(next.value) + '\n'));
174
+ controller.enqueue(encoder.encode(jobCropReferences(next.value) + '\n'));
116
175
  if (next.value.type === 'closed') {
117
176
  stop();
118
177
  controller.close();
@@ -129,14 +188,7 @@ export function createJobFront(options: {
129
188
  });
130
189
  return new Response(body, { headers: { ...headers, 'Content-Type': 'application/x-ndjson' } });
131
190
  }
132
- const embedded = route === '' && url.searchParams.has('hub');
133
- if (embedded) {
134
- if (!options.hubIncarnation || url.searchParams.get('hub') !== options.hubIncarnation ||
135
- [...url.searchParams.keys()].some(key => !['hub', 'lang'].includes(key) || url.searchParams.getAll(key).length !== 1) ||
136
- url.searchParams.has('lang') && !['en', 'ko'].includes(url.searchParams.get('lang')!)) {
137
- return failure('JOB_REQUEST_INVALID', 400);
138
- }
139
- } else if (url.search && !(route === '' && ['?lang=en', '?lang=ko'].includes(url.search))) {
191
+ if (url.search && !(route === '' && ['?lang=en', '?lang=ko'].includes(url.search))) {
140
192
  return failure('JOB_REQUEST_INVALID', 400);
141
193
  }
142
194
  const instance = /^publications\/([A-Za-z0-9][A-Za-z0-9._-]{0,127})\/instances\/([a-f0-9]{64})\/(.*)$/.exec(route);
@@ -146,14 +198,12 @@ export function createJobFront(options: {
146
198
  const publication = /^publications\/([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/.exec(route);
147
199
  if (publication)
148
200
  return result(await options.ports.readPublication(jobId, publication[1]!));
149
- const name = route === '' ? 'index.html' : route === 'job.js' ? 'job.js' : route === 'styles.css' ? 'styles.css' : null;
201
+ const name = route === '' ? 'index.html' : route === 'main.js' ? 'main.js' : route === 'styles.css' ? 'styles.css' : null;
150
202
  if (!name)
151
203
  return failure('JOB_REQUEST_INVALID', 404);
152
- const type = name === 'index.html' ? 'text/html; charset=utf-8' : name === 'job.js' ? 'text/javascript' : 'text/css';
204
+ const type = name === 'index.html' ? 'text/html; charset=utf-8' : name === 'main.js' ? 'text/javascript' : 'text/css';
153
205
  return new Response(request.method === 'HEAD' ? null : await options.resource(name), {
154
- headers: { ...headers, 'Content-Type': type, ...(embedded ? {
155
- 'Content-Security-Policy': headers['Content-Security-Policy'].replace("frame-ancestors 'none'", "frame-ancestors 'self'"),
156
- } : {}) },
206
+ headers: { ...headers, 'Content-Type': type },
157
207
  });
158
208
  }
159
209
  return {
@@ -165,28 +215,13 @@ export function createJobFront(options: {
165
215
  /** Installed files are fixed here. A job request never selects a local pathname. */
166
216
  export function jobWindowResources() {
167
217
  let bundle: Promise<Blob> | null = null;
168
- return async (name: 'index.html' | 'job.js' | 'styles.css'): Promise<BodyInit> => {
169
- if (name === 'index.html') {
170
- return '<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">' +
171
- '<title>rig-review</title><link rel="stylesheet" href="styles.css"></head>' +
172
- '<body data-job-window><script type="module" src="job.js"></script></body></html>';
173
- }
174
- if (name === 'styles.css')
175
- return Bun.file(new URL('../web/styles.css', import.meta.url));
176
- bundle ??= buildJobWindow();
218
+ return async (name: 'index.html' | 'main.js' | 'styles.css'): Promise<BodyInit> => {
219
+ if (name === 'index.html') return await Bun.file(new URL('../web/index.html', import.meta.url)).text();
220
+ if (name === 'styles.css')return await Bun.file(new URL('../web/styles.css', import.meta.url)).text();
221
+ bundle ??= buildWeb();
177
222
  return bundle;
178
223
  };
179
224
  }
180
- export async function buildJobWindow(): Promise<Blob> {
181
- const source = new URL('../web/job-session.ts', import.meta.url).pathname;
182
- const result = await Bun.build({ entrypoints: [source], target: 'browser', format: 'esm', minify: false });
183
- if (!result.success)
184
- throw new Error(result.logs.map(log => log.message).join('\n'));
185
- const output = result.outputs.find(output => output.path.endsWith('.js'));
186
- if (!output)
187
- throw new Error('JOB_WINDOW_BUNDLE_MISSING');
188
- return output;
189
- }
190
225
 
191
226
  interface RetainedView {
192
227
  review: ReviewPackage;
@@ -199,21 +234,39 @@ export function retainedPublicationRoutes(session: JobSession) {
199
234
  return async (jobId: string, publicationId: string, key: string, path: string, request: Request): Promise<Response> => {
200
235
  if (jobId !== session.jobId) return failure('JOB_UNKNOWN', 404);
201
236
  try {
237
+ const crop = path === 'api/stage-parts/comment' && request.method === 'POST';
238
+ if (crop) session.authorize('ui', request.headers.get('X-Review-Capability'));
202
239
  return await session.readPublicationResponse(publicationId, async retained => {
203
240
  const display = session.displayPublication(publicationId);
204
241
  if (key !== display.publication.instanceKey) return failure('JOB_DISPLAY_MISMATCH', 409);
205
- const json = (value: unknown) => new Response(request.method === 'HEAD' ? null : JSON.stringify(value), {
206
- headers: {...headers, 'Content-Type': 'application/json'},
207
- });
242
+ if (crop && session.status().publication?.publicationId !== publicationId)
243
+ return failure('JOB_ACT_SOURCE_STALE', 409);
244
+ const json = (value: Record<string, unknown>) => {
245
+ const payload = path === 'api/review' ? planTextMetadata(retained, value) : value;
246
+ const body = JSON.stringify(payload);
247
+ return new Response(request.method === 'HEAD' ? null : body, {
248
+ headers: {...headers, 'Content-Type': 'application/json'},
249
+ });
250
+ };
208
251
  const sealedFile = async (relativePath: string) => {
209
252
  const seal = retained.seals.find(file => file.path === relativePath);
210
253
  if (!seal) return failure('JOB_SOURCE_UNRETAINABLE', 404);
211
254
  const file = await safeFile(retained.snapshotRoot, relativePath);
212
255
  return serveReference(request, file, seal.sha256, headers);
213
256
  };
257
+ const evidenceRoute = /^api\/checkpoint-evidence\/([A-Za-z0-9][A-Za-z0-9._-]*)\/(table|tiles\/(0|[1-9]\d*))$/.exec(path);
258
+ if (evidenceRoute) {
259
+ const packet = retained.source.checkpointEvidence?.find(item => item.checkpointId === evidenceRoute[1]);
260
+ const isTable = evidenceRoute[2] === 'table';
261
+ const member = isTable ? packet?.table : packet?.tiles[Number(evidenceRoute[3])];
262
+ if (!member) return failure('JOB_SOURCE_UNRETAINABLE', 404);
263
+ readCheckpointEvidenceBytes(retained.snapshotRoot, member, isTable ? 256 * 1024 : 8 * 1024 * 1024);
264
+ return await sealedFile(member.path);
265
+ }
214
266
  if (isRetainedRecordSource(retained)) {
215
267
  if (path === 'api/review') {
216
268
  return json({
269
+ ...checkpointEvidenceMetadata(retained.snapshotRoot, retained.source.checkpointEvidence),
217
270
  recordSource: retained.source,
218
271
  sourceHash: retained.source.sourceHash,
219
272
  assetsBase: display.routes.assetsBase,
@@ -247,9 +300,21 @@ export function retainedPublicationRoutes(session: JobSession) {
247
300
  if (!pending) {
248
301
  pending = (async () => {
249
302
  const review = await loadReview(retained.manifestPath);
250
- const parts = retained.source.parts
251
- ? await loadPartsView(dirname(join(retained.snapshotRoot, retained.source.parts.manifest.path)))
252
- : null;
303
+ const partsRoot = retained.source.parts
304
+ ? dirname(join(retained.snapshotRoot, retained.source.parts.manifest.path)) : null;
305
+ // Forward only retained producer files. Discovery never reads the live draft.
306
+ const retainedFile = (path: string) => retained.seals.some(file =>
307
+ file.path === relative(retained.snapshotRoot, path).split('\\').join('/')) ? path : undefined;
308
+ const rigRoot = review.handoff?.rig ?? partsRoot;
309
+ const parts = partsRoot ? await loadPartsView(partsRoot, {
310
+ rig: rigRoot ? retainedFile(join(rigRoot, 'rig.json')) : undefined,
311
+ meshReport: rigRoot ? retainedFile(join(rigRoot, 'mesh_report.json')) : undefined,
312
+ // The original SVG stays a sealed Review reference; Parts' optional
313
+ // native-pixel comparison accepts PNG bytes, not vector artwork.
314
+ painting: review.handoff?.source && extname(review.handoff.source).toLowerCase() !== '.svg'
315
+ ? retainedFile(review.handoff.source) : undefined,
316
+ paintingRoot: retained.snapshotRoot,
317
+ }) : null;
253
318
  if (parts) {
254
319
  if (parts.items.length !== retained.partIds.length || parts.items.some(item => !retained.partIds.includes(item.name))) {
255
320
  throw new JobError('JOB_SOURCE_MISMATCH');
@@ -267,14 +332,19 @@ export function retainedPublicationRoutes(session: JobSession) {
267
332
  }
268
333
  const {review, parts} = await pending;
269
334
  await assertReviewUnchanged(review);
335
+ if (retained.checkpointEvidencePackageHash !== undefined && retained.checkpointEvidencePackageHash !== review.sourceHash) {
336
+ throw new JobError('JOB_SOURCE_MISMATCH');
337
+ }
270
338
  if (path === 'api/review') {
271
339
  return json({
340
+ ...checkpointEvidenceMetadata(retained.snapshotRoot, retained.source.checkpointEvidence),
272
341
  manifest: review.manifest,
273
342
  sourceHash: retained.source.sourceHash,
274
343
  reviewedSource: review.reviewedSource,
275
344
  initialAnimation: null,
276
345
  setsHash: review.setsHash,
277
- direction: review.direction,
346
+ direction: review.direction && {...review.direction, ...(retained.source.selector?.kind==='post'?{postVersion:retained.source.selector.version}:{})},
347
+ scene: review.scene,
278
348
  referenceHashes: review.referenceHashes,
279
349
  sourcePainting: review.sourcePainting && {...review.sourcePainting, url: '/review-painting'},
280
350
  feedbackCatalog: review.feedbackCatalog,
@@ -302,17 +372,41 @@ export function retainedPublicationRoutes(session: JobSession) {
302
372
  if (!image) return failure('JOB_SOURCE_UNRETAINABLE', 404);
303
373
  return await sealedFile(image.ref.path);
304
374
  }
305
- const imageSetImage = /^api\/image-set\/(0|[1-9]\d*)$/.exec(path);
306
- if (imageSetImage && retained.source.subject === 'image-set') {
307
- const image = retained.source.imageSet.images[Number(imageSetImage[1])];
308
- if (!image) return failure('JOB_SOURCE_UNRETAINABLE', 404);
309
- return await sealedFile(image.path);
375
+ if (crop) {
376
+ if (!parts) return failure('JOB_SOURCE_UNRETAINABLE', 409);
377
+ if (request.headers.get('origin') !== new URL(request.url).origin)
378
+ return failure('JOB_SAME_ORIGIN_REQUIRED', 403);
379
+ const raw = await jobBody(request);
380
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw) ||
381
+ (raw as {sourceHash?: unknown}).sourceHash !== retained.source.sourceHash)
382
+ return failure('JOB_ACT_SOURCE_STALE', 409);
383
+ // Preserve the exact displayed job identity through native evidence validation.
384
+ assertRetainedSnapshotIntact(retained.snapshotRoot, retained.seals);
385
+ let comment;
386
+ try {
387
+ comment = await preparePartsComment(parts, raw, false, {sourceHash: retained.source.sourceHash});
388
+ } catch (error) {
389
+ if (error instanceof JobError ||
390
+ error instanceof Error && error.message.startsWith('PARTS_COMMENT_STALE_SOURCE:')) throw error;
391
+ return failure('JOB_SOURCE_MISMATCH', 409, cropFailureDiagnostic(error, raw));
392
+ }
393
+ assertRetainedSnapshotIntact(retained.snapshotRoot, retained.seals);
394
+ if (session.status().publication?.publicationId !== publicationId)
395
+ return failure('JOB_ACT_SOURCE_STALE', 409);
396
+ return json({comment});
310
397
  }
311
398
  if (path === 'api/stage-parts') {
312
399
  if (!parts) return failure('JOB_SOURCE_UNRETAINABLE', 409);
313
400
  return json({...partsViewJson(parts, {verdict: null, stale: null}), sourceHash: retained.source.sourceHash,
314
401
  inspectionSourceHash: retained.source.sourceHash, readOnly: true});
315
402
  }
403
+ const difference=/^api\/stage-parts\/difference\/(0|[1-9]\d*)$/.exec(path);
404
+ if(difference&&parts){
405
+ const url=new URL(request.url),threshold=url.searchParams.get('threshold'),footprints=url.searchParams.get('footprints');
406
+ if(!threshold||!/^\d{1,3}$/.test(threshold)||!['true','false'].includes(footprints??''))return failure('JOB_REQUEST_INVALID',400);
407
+ const raster=await partsDifference(parts,Number(difference[1]),Number(threshold),footprints==='true'),png=new PNG({width:raster.width,height:raster.height});png.data=Buffer.from(raster.data);
408
+ return new Response(request.method==='HEAD'?null:new Uint8Array(PNG.sync.write(png)),{headers:{...headers,'Content-Type':'image/png','X-Difference-Count':String(raster.count),'X-Difference-Covered':String(raster.covered),'X-Difference-Compared':String(raster.compared)}});
409
+ }
316
410
  const part = /^api\/stage-parts\/(image|page)\/(0|[1-9]\d*)$/.exec(path);
317
411
  if (part && parts) {
318
412
  const file = servedImage(parts, part[1] as 'image' | 'page', Number(part[2]));
@@ -330,7 +424,12 @@ export function retainedPublicationRoutes(session: JobSession) {
330
424
  return failure('JOB_REQUEST_INVALID', 404);
331
425
  });
332
426
  } catch (error) {
333
- return failure(error instanceof JobError ? error.code : 'JOB_SOURCE_MISMATCH', 409);
427
+ const code = error instanceof JobError ? error.code :
428
+ error instanceof Error && error.message.startsWith('PARTS_COMMENT_STALE_SOURCE:')
429
+ ? 'PARTS_COMMENT_STALE_SOURCE' : 'JOB_SOURCE_MISMATCH';
430
+ const message = error instanceof JobError && /^(CHECKPOINT_EVIDENCE|PLAN_TEXT)_[A-Z_]+$/.test(error.message)
431
+ ? error.message : undefined;
432
+ return failure(code, errorStatus[code as JobErrorCode] ?? 409, undefined, message);
334
433
  }
335
434
  };
336
435
  }
@@ -686,8 +785,8 @@ function attachFailure(error: unknown): Response {
686
785
 
687
786
  /** One live job request context. Its caller publishes it only after descriptor installation. */
688
787
  export function createJobRequestContext(session: JobSession, startup: JobHostOptions, origin: string,
689
- identity: ReturnType<typeof jobHostIdentity>, resource = jobWindowResources(), hubIncarnation?: string,
690
- listenerIncarnation: string = hubIncarnation ?? randomUUID(), accepting: () => boolean = () => true) {
788
+ identity: ReturnType<typeof jobHostIdentity>, resource = jobWindowResources(),
789
+ listenerIncarnation: string = randomUUID(), accepting: () => boolean = () => true) {
691
790
  const ports = createJobHostPorts(session, new URL(origin).origin);
692
791
  // This legacy GET projection and its property order are deliberately unchanged.
693
792
  const record: JobHostRecord = {
@@ -707,7 +806,7 @@ export function createJobRequestContext(session: JobSession, startup: JobHostOpt
707
806
  fingerprint: startup.fingerprint,
708
807
  pid: process.pid,
709
808
  };
710
- const front = createJobFront({origin, ports, resource, hubIncarnation, publication: retainedPublicationRoutes(session)});
809
+ const front = createJobFront({origin, ports, resource, publication: retainedPublicationRoutes(session)});
711
810
  let requests = 0, stopped = false, published = false;
712
811
  let captured: ObservedFiles;
713
812
  let descriptorBytes: string;
package/src/job-host.ts CHANGED
@@ -1,7 +1,5 @@
1
1
  /** Stable installed managed owner host and semantic A/B contract. See docs/STABILITY.md. */
2
2
  export {startJobHost} from './job-front.ts';
3
- export {startJobHub} from './job-hub.ts';
4
- export type {JobHubOptions, JobHubJobOptions, JobHubJob, JobOwnerHub} from './job-hub.ts';
5
3
  export type {
6
4
  JobHostOptions,
7
5
  JobOwnerHost,
@@ -23,6 +21,21 @@ export type {
23
21
  JobRootIdentity,
24
22
  } from './job-source.ts';
25
23
  export {parseRecordAct} from './job-api.ts';
24
+ export {parseCommentsAct, parseContextCommentsAct} from './job-api.ts';
25
+ export {projectComments} from './stage-comment.ts';
26
+ export {parseCommentsSession} from './session.ts';
27
+ export {parseCommentsCompareSession} from './compare-session.ts';
28
+ export {parseCommentsPartsVerdict} from './parts-view.ts';
29
+ export {projectSelectedCommentsFeedback} from './feedback-export.ts';
30
+ export {
31
+ JOB_COMMENTS_ACT_SCHEMA, JOB_COMMENT_CONTEXT_ACT_SCHEMA, REVIEW_COMMENTS_SESSION_SCHEMA,
32
+ REVIEW_COMMENTS_COMPARE_SESSION_SCHEMA, PARTS_COMMENTS_VERDICT_SCHEMA,
33
+ } from './job-contract.ts';
34
+ export type {
35
+ JobComment, JobCommentAnchor, JobCommentFeedbackAnchor, JobCommentPartsAnchor, JobCommentImageAnchor,
36
+ JobCommentsAct, JobCommentsActValues, ReviewCommentsSession,
37
+ JobCommentContext, JobContextComment, JobContextCommentsAct, CompareCommentsSession, PartsCommentsVerdict,
38
+ } from './job-contract.ts';
26
39
  export {prepareJobRecordAct} from './job-act.ts';
27
40
  export {
28
41
  JOB_CAPABILITIES,
@@ -81,6 +94,11 @@ export type {
81
94
  JobActV3,
82
95
  JobLegacyAct,
83
96
  JobRigReviewAct,
97
+ JobPartsVerdictAct,
98
+ JobLegacyPartsVerdictValue,
99
+ PartsVerdictValue,
100
+ JobPanelComposition,
101
+ PanelComponent,
84
102
  JobRigStill,
85
103
  JobRigCapture,
86
104
  JobSubject,
@@ -201,5 +219,6 @@ export type {
201
219
  UISubmissionV3,
202
220
  } from './job-contract.ts';
203
221
 
204
- export {assertJobImageSetCapability} from './job-image-set.ts';
205
- export type {JobCapabilities, JobImageSetInput, JobImageSet, JobImageSourceBinding, JobModelSourceBinding, JobModelReviewValue, JobImageReviewValue} from './job-contract.ts';
222
+ export type {JobCapabilities, JobModelSourceBinding, JobModelReviewValue} from './job-contract.ts';
223
+
224
+ export type {JobCheckpointEvidence, JobCheckpointTable} from './job-contract.ts';