rig-review 2.8.0 → 2.10.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.
@@ -1,33 +1,326 @@
1
1
  /** Closed parts evidence. No synthetic model, frame, slot or package identity. */
2
- import {parsePartsComparison,type PartsComparison} from './parts-comparison.ts';
3
- import type {MarkRegion} from './stage-comment.ts';
4
- export interface PartsCrop {path:string;sha256:string;width:number;height:number}
2
+ import { parsePartsComparison, type PartsComparison } from './parts-comparison.ts';
3
+ import type { MarkRegion } from './stage-comment.ts';
4
+
5
+ export const PARTS_COMMENT_SCHEMA = 'rig-review-parts-comment/1' as const;
6
+ export const PARTS_ISSUE_SCHEMA = 'rig-review-parts-comment/2' as const;
7
+
8
+ export interface PartsCrop {
9
+ path: string;
10
+ sha256: string;
11
+ width: number;
12
+ height: number;
13
+ }
14
+
5
15
  export interface PartsComment {
6
- schema:'rig-review-parts-comment/1';id:string;summary:string;part:string;imageHash:string;sourceHash:string;
7
- imageRegion:MarkRegion;rigRegion:MarkRegion;
8
- view:{camera:{zoom:number;center:{x:number;y:number};viewport:{width:number;height:number}};cameraSync:boolean;referenceCamera:{zoom:number;center:{x:number;y:number};viewport:{width:number;height:number}}|null;background:string;alpha:boolean;footprints:boolean;mesh:boolean;comparison?:PartsComparison};
9
- crop:PartsCrop&{png:string};nativeCrop:PartsCrop|null;
10
- }
11
- const fail=(code:string,why:string):never=>{throw new Error(code+': '+why);};
12
- const obj=(v:unknown):Record<string,any>=>v!==null&&typeof v==='object'&&!Array.isArray(v)?v as Record<string,any>:fail('PARTS_COMMENT_INVALID','object required');
13
- const exact=(v:Record<string,any>,keys:string[])=>{if(Object.keys(v).length!==keys.length||keys.some(k=>!Object.hasOwn(v,k)))fail('PARTS_COMMENT_INVALID','unknown or missing fields');};
14
- const finite=(v:unknown):v is number=>typeof v==='number'&&Number.isFinite(v)&&Math.abs(v)<=Number.MAX_SAFE_INTEGER;
15
- const hash=(v:unknown)=>typeof v==='string'&&/^[a-f0-9]{64}$/.test(v);
16
- export function parsePartsComment(raw:unknown,prepared=true):PartsComment {
17
- const v=obj(raw);exact(v,['schema','id','summary','part','imageHash','sourceHash','imageRegion','rigRegion','view','crop','nativeCrop']);
18
- if(v.schema!=='rig-review-parts-comment/1'||typeof v.id!=='string'||!v.id||v.id.length>128||typeof v.summary!=='string'||!v.summary.trim()||v.summary.length>1000||typeof v.part!=='string'||!v.part||v.part.length>512||!hash(v.imageHash)||!hash(v.sourceHash))fail('PARTS_COMMENT_INVALID','schema, text or source binding');
19
- for(const key of ['imageRegion','rigRegion']){const r=obj(v[key]);exact(r,['x','y','width','height']);if(!Object.values(r).every(finite))fail('PARTS_COMMENT_INVALID','finite region required');if(key==='imageRegion'&&!Object.values(r).every(Number.isSafeInteger))fail('PARTS_COMMENT_FRACTIONAL','image coordinates must be integer pixels');if(r.width<=0||r.height<=0)fail('PARTS_COMMENT_EMPTY','positive region required');}
20
- const view=obj(v.view);exact(view,['camera','cameraSync','referenceCamera','background','alpha','footprints','mesh',...(Object.hasOwn(view,'comparison')?['comparison']:[])]);if(Object.hasOwn(view,'comparison'))parsePartsComparison(view.comparison);if(!['green','magenta','black','white','checker'].includes(view.background)||![view.alpha,view.footprints,view.mesh,view.cameraSync].every(n=>typeof n==='boolean'))fail('PARTS_COMMENT_INVALID','view state');
21
- for(const rawCamera of [view.camera,...(view.referenceCamera===null?[]:[view.referenceCamera])]){const c=obj(rawCamera);exact(c,['zoom','center','viewport']);exact(obj(c.center),['x','y']);exact(obj(c.viewport),['width','height']);if(!finite(c.zoom)||c.zoom<=0||c.zoom>16||!Object.values(c.center).every(finite)||!Object.values(c.viewport).every(n=>finite(n)&&n>0&&n<=65536))fail('PARTS_CAMERA_RANGE','native scale or camera extent');}
22
- for(const [crop,inline]of [[v.crop,true],[v.nativeCrop,false]] as const){if(crop===null&&!inline&&!prepared)continue;const p=obj(crop);exact(p,['path','sha256','width','height',...(inline?['png']:[])]);if(!hash(p.sha256)||p.path!==`comment-crops/${p.sha256}.png`||![p.width,p.height].every(n=>Number.isSafeInteger(n)&&n>0&&n<=16384)||inline&&(typeof p.png!=='string'||p.png.length>200000||p.width>1024||p.height>1024))fail('PARTS_COMMENT_CROP_INVALID','bounded content-addressed crop');}
23
- return v as PartsComment;
16
+ schema: typeof PARTS_COMMENT_SCHEMA;
17
+ id: string;
18
+ summary: string;
19
+ part: string;
20
+ imageHash: string;
21
+ sourceHash: string;
22
+ imageRegion: MarkRegion;
23
+ rigRegion: MarkRegion;
24
+ view: {
25
+ camera: { zoom: number; center: { x: number; y: number }; viewport: { width: number; height: number } };
26
+ cameraSync: boolean;
27
+ referenceCamera: { zoom: number; center: { x: number; y: number }; viewport: { width: number; height: number } } | null;
28
+ background: string;
29
+ alpha: boolean;
30
+ footprints: boolean;
31
+ mesh: boolean;
32
+ comparison?: PartsComparison;
33
+ };
34
+ crop: PartsCrop & { png: string };
35
+ nativeCrop: PartsCrop | null;
36
+ }
37
+
38
+ export interface PartsIssue {
39
+ schema: typeof PARTS_ISSUE_SCHEMA;
40
+ id: string;
41
+ summary: string;
42
+ parts: { name: string; imageHash: string }[];
43
+ sourceHash: string;
44
+ rigRegion: MarkRegion;
45
+ imageRegion: MarkRegion | null;
46
+ view: PartsComment['view'] & { mode: 'item' | 'assembled' };
47
+ crop: PartsCrop & { png?: string };
48
+ nativeCrop: PartsCrop | null;
49
+ }
50
+
51
+ const fail = (code: string, why: string): never => {
52
+ throw new Error(code + ': ' + why);
53
+ };
54
+
55
+ const obj = (v: unknown): Record<string, any> =>
56
+ v !== null && typeof v === 'object' && !Array.isArray(v)
57
+ ? (v as Record<string, any>)
58
+ : fail('PARTS_COMMENT_INVALID', 'object required');
59
+
60
+ const exact = (v: Record<string, any>, keys: string[]) => {
61
+ if (Object.keys(v).length !== keys.length || keys.some(k => !Object.hasOwn(v, k))) {
62
+ fail('PARTS_COMMENT_INVALID', 'unknown or missing fields');
63
+ }
64
+ };
65
+
66
+ const finite = (v: unknown): v is number =>
67
+ typeof v === 'number' && Number.isFinite(v) && Math.abs(v) <= Number.MAX_SAFE_INTEGER;
68
+
69
+ const hash = (v: unknown) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
70
+
71
+ const token = (v: unknown): v is string =>
72
+ typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(v);
73
+
74
+ function parseRegion(raw: unknown, integer = false): void {
75
+ const r = obj(raw);
76
+ exact(r, ['x', 'y', 'width', 'height']);
77
+ if (!Object.values(r).every(finite)) {
78
+ fail('PARTS_COMMENT_INVALID', 'finite region required');
79
+ }
80
+ if (integer && !Object.values(r).every(Number.isSafeInteger)) {
81
+ fail('PARTS_COMMENT_FRACTIONAL', 'image coordinates must be integer pixels');
82
+ }
83
+ if (r.width <= 0 || r.height <= 0) {
84
+ fail('PARTS_COMMENT_EMPTY', 'positive region required');
85
+ }
86
+ }
87
+
88
+ function parseView(raw: unknown, withMode: boolean): Record<string, any> {
89
+ const view = obj(raw);
90
+ exact(view, [
91
+ ...(withMode ? ['mode'] : []),
92
+ 'camera',
93
+ 'cameraSync',
94
+ 'referenceCamera',
95
+ 'background',
96
+ 'alpha',
97
+ 'footprints',
98
+ 'mesh',
99
+ ...(Object.hasOwn(view, 'comparison') ? ['comparison'] : []),
100
+ ]);
101
+ if (withMode && view.mode !== 'item' && view.mode !== 'assembled') {
102
+ fail('PARTS_COMMENT_INVALID', 'view mode');
103
+ }
104
+ if (Object.hasOwn(view, 'comparison')) {
105
+ parsePartsComparison(view.comparison);
106
+ }
107
+ if (
108
+ !['green', 'magenta', 'black', 'white', 'checker'].includes(view.background) ||
109
+ ![view.alpha, view.footprints, view.mesh, view.cameraSync].every(n => typeof n === 'boolean')
110
+ ) {
111
+ fail('PARTS_COMMENT_INVALID', 'view state');
112
+ }
113
+ for (const rawCamera of [view.camera, ...(view.referenceCamera === null ? [] : [view.referenceCamera])]) {
114
+ const c = obj(rawCamera);
115
+ exact(c, ['zoom', 'center', 'viewport']);
116
+ exact(obj(c.center), ['x', 'y']);
117
+ exact(obj(c.viewport), ['width', 'height']);
118
+ if (
119
+ !finite(c.zoom) ||
120
+ c.zoom <= 0 ||
121
+ c.zoom > 16 ||
122
+ !Object.values(c.center).every(finite) ||
123
+ !Object.values(c.viewport).every(n => finite(n) && n > 0 && n <= 65536)
124
+ ) {
125
+ fail('PARTS_CAMERA_RANGE', 'native scale or camera extent');
126
+ }
127
+ }
128
+ return view;
129
+ }
130
+
131
+ function parseCrop(crop: unknown, inline: boolean, requireInline = true): void {
132
+ const p = obj(crop);
133
+ const hasPng = inline && Object.hasOwn(p, 'png');
134
+ if (inline && requireInline && !hasPng) {
135
+ fail('PARTS_COMMENT_INVALID', 'unknown or missing fields');
136
+ }
137
+ exact(p, ['path', 'sha256', 'width', 'height', ...(hasPng ? ['png'] : [])]);
138
+ if (
139
+ !hash(p.sha256) ||
140
+ p.path !== `comment-crops/${p.sha256}.png` ||
141
+ ![p.width, p.height].every(n => Number.isSafeInteger(n) && n > 0 && n <= 16384) ||
142
+ (hasPng && (typeof p.png !== 'string' || p.png.length > 200000 || p.width > 1024 || p.height > 1024))
143
+ ) {
144
+ fail('PARTS_COMMENT_CROP_INVALID', 'bounded content-addressed crop');
145
+ }
24
146
  }
147
+
148
+ export function parsePartsComment(raw: unknown, prepared = true): PartsComment {
149
+ const v = obj(raw);
150
+ exact(v, ['schema', 'id', 'summary', 'part', 'imageHash', 'sourceHash', 'imageRegion', 'rigRegion', 'view', 'crop', 'nativeCrop']);
151
+ if (
152
+ v.schema !== PARTS_COMMENT_SCHEMA ||
153
+ typeof v.id !== 'string' ||
154
+ !v.id ||
155
+ v.id.length > 128 ||
156
+ typeof v.summary !== 'string' ||
157
+ !v.summary.trim() ||
158
+ v.summary.length > 1000 ||
159
+ typeof v.part !== 'string' ||
160
+ !v.part ||
161
+ v.part.length > 512 ||
162
+ !hash(v.imageHash) ||
163
+ !hash(v.sourceHash)
164
+ ) {
165
+ fail('PARTS_COMMENT_INVALID', 'schema, text or source binding');
166
+ }
167
+ parseRegion(v.imageRegion, true);
168
+ parseRegion(v.rigRegion, false);
169
+ parseView(v.view, false);
170
+ parseCrop(v.crop, true);
171
+ if (v.nativeCrop !== null || prepared) {
172
+ parseCrop(v.nativeCrop, false);
173
+ }
174
+ return v as PartsComment;
175
+ }
176
+
177
+ export function parsePartsIssue(raw: unknown, prepared = true, allowLegacy = false, requireInlinePng = true): PartsIssue {
178
+ const v = obj(raw);
179
+ if (allowLegacy && v.schema === PARTS_COMMENT_SCHEMA) {
180
+ const c = parsePartsComment(raw, prepared);
181
+ return {
182
+ schema: PARTS_ISSUE_SCHEMA,
183
+ id: c.id,
184
+ summary: c.summary,
185
+ parts: [{ name: c.part, imageHash: c.imageHash }],
186
+ sourceHash: c.sourceHash,
187
+ rigRegion: c.rigRegion,
188
+ imageRegion: c.imageRegion,
189
+ view: { ...c.view, mode: 'item' },
190
+ crop: c.crop,
191
+ nativeCrop: c.nativeCrop,
192
+ };
193
+ }
194
+ exact(v, ['schema', 'id', 'summary', 'parts', 'sourceHash', 'imageRegion', 'rigRegion', 'view', 'crop', 'nativeCrop']);
195
+ if (
196
+ v.schema !== PARTS_ISSUE_SCHEMA ||
197
+ !token(v.id) ||
198
+ typeof v.summary !== 'string' ||
199
+ !v.summary.trim() ||
200
+ v.summary.length > 1000 ||
201
+ !hash(v.sourceHash) ||
202
+ !Array.isArray(v.parts) ||
203
+ v.parts.length < 1 ||
204
+ v.parts.length > 1000
205
+ ) {
206
+ fail('PARTS_COMMENT_INVALID', 'schema, text or source binding');
207
+ }
208
+ const seen = new Set<string>();
209
+ for (const entry of v.parts) {
210
+ const p = obj(entry);
211
+ exact(p, ['name', 'imageHash']);
212
+ if (!token(p.name) || seen.has(p.name) || !hash(p.imageHash)) {
213
+ fail('PARTS_COMMENT_INVALID', 'part binding');
214
+ }
215
+ seen.add(p.name);
216
+ }
217
+ const view = parseView(v.view, true);
218
+ if (view.mode === 'item') {
219
+ if (v.parts.length !== 1 || v.imageRegion === null) {
220
+ fail('PARTS_COMMENT_INVALID', 'item view requires a single part and imageRegion');
221
+ }
222
+ parseRegion(v.imageRegion, true);
223
+ parseRegion(v.rigRegion, false);
224
+ if (v.nativeCrop !== null || prepared) {
225
+ parseCrop(v.nativeCrop, false);
226
+ }
227
+ } else {
228
+ if (v.imageRegion !== null) {
229
+ fail('PARTS_COMMENT_INVALID', 'assembled view requires null imageRegion');
230
+ }
231
+ parseRegion(v.rigRegion, true);
232
+ if (v.nativeCrop !== null) {
233
+ fail('PARTS_COMMENT_CROP_INVALID', 'assembled view requires null nativeCrop');
234
+ }
235
+ }
236
+ parseCrop(v.crop, true, requireInlinePng);
237
+ return v as PartsIssue;
238
+ }
239
+
25
240
  /** Drag edges snap outward to whole native pixels. OOB is refused by the binding check, never clipped. */
26
- export function snapImageRegion(r:MarkRegion):MarkRegion {if(r.width<=0||r.height<=0)return {x:Math.floor(r.x),y:Math.floor(r.y),width:0,height:0};const x=Math.floor(r.x),y=Math.floor(r.y);return {x,y,width:Math.ceil(r.x+r.width)-x,height:Math.ceil(r.y+r.height)-y};}
27
- export function assertPartsCommentBinding(c:PartsComment,item:{name:string;x:number;y:number;w:number;h:number},imageHash:string,sourceHash:string):void {
28
- if(c.part!==item.name)fail('PARTS_COMMENT_PART_MISMATCH','comment belongs to another part');
29
- if(c.imageHash!==imageHash||c.sourceHash!==sourceHash)fail('PARTS_COMMENT_STALE_SOURCE','original image or package source hash differs');
30
- const camera=c.view.camera,fit=Math.max(.001,Math.min((camera.viewport.width-24)/item.w,(camera.viewport.height-24)/item.h));if(camera.zoom<Math.min(fit,1))fail('PARTS_CAMERA_RANGE','native zoom below fit/1 minimum');
31
- const r=c.imageRegion;if(r.x<0||r.y<0||r.x+r.width>item.w||r.y+r.height>item.h)fail('PARTS_COMMENT_OUT_OF_BOUNDS','region exceeds original image');
32
- if(c.rigRegion.x!==item.x+r.x||c.rigRegion.y!==item.y+r.y||c.rigRegion.width!==r.width||c.rigRegion.height!==r.height)fail('PARTS_COMMENT_RIG_REGION','rig region must be exact placement plus image region');
241
+ export function snapImageRegion(r: MarkRegion): MarkRegion {
242
+ if (r.width <= 0 || r.height <= 0) {
243
+ return { x: Math.floor(r.x), y: Math.floor(r.y), width: 0, height: 0 };
244
+ }
245
+ const x = Math.floor(r.x);
246
+ const y = Math.floor(r.y);
247
+ return { x, y, width: Math.ceil(r.x + r.width) - x, height: Math.ceil(r.y + r.height) - y };
248
+ }
249
+
250
+ export function assertPartsCommentBinding(
251
+ c: PartsComment,
252
+ item: { name: string; x: number; y: number; w: number; h: number },
253
+ imageHash: string,
254
+ sourceHash: string,
255
+ ): void {
256
+ if (c.part !== item.name) {
257
+ fail('PARTS_COMMENT_PART_MISMATCH', 'comment belongs to another part');
258
+ }
259
+ if (c.imageHash !== imageHash || c.sourceHash !== sourceHash) {
260
+ fail('PARTS_COMMENT_STALE_SOURCE', 'original image or package source hash differs');
261
+ }
262
+ const camera = c.view.camera;
263
+ const fit = Math.max(0.001, Math.min((camera.viewport.width - 24) / item.w, (camera.viewport.height - 24) / item.h));
264
+ if (camera.zoom < Math.min(fit, 1)) {
265
+ fail('PARTS_CAMERA_RANGE', 'native zoom below fit/1 minimum');
266
+ }
267
+ const r = c.imageRegion;
268
+ if (r.width * r.height > 16777216) {
269
+ fail('PARTS_COMMENT_CROP_LIMIT', 'native crop exceeds 16 million pixels');
270
+ }
271
+ if (r.x < 0 || r.y < 0 || r.x + r.width > item.w || r.y + r.height > item.h) {
272
+ fail('PARTS_COMMENT_OUT_OF_BOUNDS', 'region exceeds original image');
273
+ }
274
+ if (c.rigRegion.x !== item.x + r.x || c.rigRegion.y !== item.y + r.y || c.rigRegion.width !== r.width || c.rigRegion.height !== r.height) {
275
+ fail('PARTS_COMMENT_RIG_REGION', 'rig region must be exact placement plus image region');
276
+ }
277
+ }
278
+
279
+ export function assertPartsIssueBinding(
280
+ c: PartsIssue,
281
+ items: ReadonlyMap<string, { name: string; x: number; y: number; w: number; h: number; imageHash: string }>,
282
+ sourceHash: string,
283
+ ): void {
284
+ if (c.sourceHash !== sourceHash) {
285
+ fail('PARTS_COMMENT_STALE_SOURCE', 'original image or package source hash differs');
286
+ }
287
+ const matchedItems: { name: string; x: number; y: number; w: number; h: number; imageHash: string }[] = [];
288
+ for (const p of c.parts) {
289
+ const item = items.get(p.name);
290
+ if (!item) {
291
+ return fail('PARTS_COMMENT_PART_MISMATCH', 'comment belongs to another part');
292
+ }
293
+ if (p.imageHash !== item.imageHash) {
294
+ return fail('PARTS_COMMENT_STALE_SOURCE', 'original image or package source hash differs');
295
+ }
296
+ matchedItems.push(item);
297
+ }
298
+ if (c.view.mode === 'item') {
299
+ const item = matchedItems[0]!;
300
+ assertPartsCommentBinding(
301
+ {
302
+ ...c,
303
+ schema: PARTS_COMMENT_SCHEMA,
304
+ part: item.name,
305
+ imageHash: c.parts[0]!.imageHash,
306
+ imageRegion: c.imageRegion!,
307
+ crop: { ...c.crop, png: c.crop.png ?? '' },
308
+ },
309
+ item,
310
+ item.imageHash,
311
+ sourceHash,
312
+ );
313
+ return;
314
+ }
315
+ const r = c.rigRegion;
316
+ if (![r.x, r.y, r.width, r.height].every(Number.isSafeInteger)) {
317
+ fail('PARTS_COMMENT_FRACTIONAL', 'rig coordinates must be integer pixels');
318
+ }
319
+ const minX = Math.min(...matchedItems.map(i => i.x));
320
+ const minY = Math.min(...matchedItems.map(i => i.y));
321
+ const maxX = Math.max(...matchedItems.map(i => i.x + i.w));
322
+ const maxY = Math.max(...matchedItems.map(i => i.y + i.h));
323
+ if (r.x < minX || r.y < minY || r.x + r.width > maxX || r.y + r.height > maxY) {
324
+ fail('PARTS_COMMENT_OUT_OF_BOUNDS', 'region exceeds union of issue parts');
325
+ }
33
326
  }