@rig-c/review 2.8.0 → 2.9.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,128 @@
1
1
  /** Native evidence is cut from the bound original PNG, never from a displayed alpha mask. */
2
- import {createHash} from 'node:crypto';
3
- import {readFile} from 'node:fs/promises';
4
- import {PNG} from 'pngjs';
5
- import {parsePartsComment,assertPartsCommentBinding,type PartsComment} from './parts-comment.ts';
6
- import {validatePngCrop,storePngCrop,readPngCrop} from './comment-crops.ts';
7
- import {assertPartsUnchanged,partsDifference,verdictSource,type PartsViewPackage} from './parts-view.ts';
8
- export async function preparePartsComment(pkg:PartsViewPackage,raw:unknown,requireNative=false):Promise<PartsComment>{return resolvePartsComment(pkg,raw,requireNative,true);}
9
- export async function validateStoredPartsComment(pkg:PartsViewPackage,raw:unknown):Promise<PartsComment>{return resolvePartsComment(pkg,raw,true,false);}
10
- async function resolvePartsComment(pkg:PartsViewPackage,raw:unknown,requireNative:boolean,persist:boolean):Promise<PartsComment>{
11
- const c=parsePartsComment(raw,requireNative),item=pkg.items.find(i=>i.name===c.part);
12
- if(pkg.mode!=='parts'||!item)throw new Error('PARTS_COMMENT_UNAVAILABLE: original part image required');
13
- const path=pkg.imagePaths[item.index],file=pkg.files.find(f=>f.abs===path);if(!path||!file)throw new Error('PARTS_COMMENT_UNAVAILABLE: bound original PNG required');
14
- assertPartsCommentBinding(c,item,file.sha256,verdictSource(pkg).sha256);
15
- if(c.view.comparison?.mode==='overlay'&&!pkg.painting)throw new Error('PARTS_COMPARISON_UNAVAILABLE: original painting required');
16
- if(c.view.comparison?.mode==='difference')await partsDifference(pkg,item.index,c.view.comparison.threshold,c.view.footprints);
17
- const bytes=await readFile(path);if(createHash('sha256').update(bytes).digest('hex')!==file.sha256)throw new Error('PARTS_COMMENT_STALE_SOURCE: original PNG changed');
18
- await assertPartsUnchanged(pkg);
19
- validatePngCrop(c.crop);
20
- const original=PNG.sync.read(bytes),r=c.imageRegion;
21
- if(original.width!==item.w||original.height!==item.h)throw new Error('PARTS_COMMENT_IMAGE_SIZE: original dimensions differ from placement');
22
- if(r.width*r.height>16777216)throw new Error('PARTS_COMMENT_CROP_LIMIT: native crop exceeds 16 million pixels');
23
- const native=new PNG({width:r.width,height:r.height});for(let y=0;y<r.height;y++)original.data.copy(native.data,y*r.width*4,((r.y+y)*original.width+r.x)*4,((r.y+y)*original.width+r.x+r.width)*4);
24
- if(requireNative){
25
- const stored=await readPngCrop(c.nativeCrop!),decoded=PNG.sync.read(stored);
26
- if(decoded.width!==r.width||decoded.height!==r.height||!decoded.data.equals(native.data))throw new Error('PARTS_COMMENT_NATIVE_CROP_TAMPERED: native crop differs from bound original');
27
- if(persist)await storePngCrop(c.crop);else await readPngCrop(c.crop);
28
- return c;
29
- }
30
- const png=PNG.sync.write(native),sha256=createHash('sha256').update(png).digest('hex'),nativeCrop={path:`comment-crops/${sha256}.png`,sha256,width:r.width,height:r.height};
31
- await storePngCrop(c.crop);await storePngCrop({...nativeCrop,png:'data:image/png;base64,'+png.toString('base64')});
32
- return {...c,nativeCrop};
2
+ import { createHash } from 'node:crypto';
3
+ import { readFile } from 'node:fs/promises';
4
+ import { PNG } from 'pngjs';
5
+ import { parsePartsIssue, assertPartsIssueBinding, type PartsIssue } from './parts-comment.ts';
6
+ import { validatePngCrop, storePngCrop, readPngCrop, type PngCrop } from './comment-crops.ts';
7
+ import { assertPartsUnchanged, partsDifference, verdictSource, type PartsViewPackage } from './parts-view.ts';
8
+
9
+ export interface PartsCommentBindingOptions {
10
+ readonly sourceHash?: string;
11
+ }
12
+
13
+ export async function preparePartsComment(
14
+ pkg: PartsViewPackage,
15
+ raw: unknown,
16
+ requireNative = false,
17
+ options?: PartsCommentBindingOptions,
18
+ ): Promise<PartsIssue> {
19
+ return resolvePartsComment(pkg, raw, requireNative, true, false, options);
20
+ }
21
+
22
+ export async function validateStoredPartsComment(
23
+ pkg: PartsViewPackage,
24
+ raw: unknown,
25
+ allowLegacy = false,
26
+ options?: PartsCommentBindingOptions,
27
+ ): Promise<PartsIssue> {
28
+ return resolvePartsComment(pkg, raw, true, false, allowLegacy, options);
29
+ }
30
+
31
+ async function resolvePartsComment(
32
+ pkg: PartsViewPackage,
33
+ raw: unknown,
34
+ requireNative: boolean,
35
+ persist: boolean,
36
+ allowLegacy = false,
37
+ options?: PartsCommentBindingOptions,
38
+ ): Promise<PartsIssue> {
39
+ const c = parsePartsIssue(raw, requireNative, allowLegacy, persist && !requireNative);
40
+ if (pkg.mode !== 'parts') {
41
+ throw new Error('PARTS_COMMENT_UNAVAILABLE: original part image required');
42
+ }
43
+ const itemMap = new Map<
44
+ string,
45
+ { name: string; index: number; x: number; y: number; w: number; h: number; imageHash: string; path: string }
46
+ >();
47
+ for (const item of pkg.items) {
48
+ const path = pkg.imagePaths[item.index];
49
+ const file = path ? pkg.files.find(f => f.abs === path) : undefined;
50
+ if (!path || !file) {
51
+ throw new Error('PARTS_COMMENT_UNAVAILABLE: bound original PNG required');
52
+ }
53
+ itemMap.set(item.name, { ...item, imageHash: file.sha256, path });
54
+ }
55
+ const expectedSourceHash = options?.sourceHash ?? verdictSource(pkg).sha256;
56
+ assertPartsIssueBinding(c, itemMap, expectedSourceHash);
57
+ if (c.view.comparison?.mode === 'overlay' && !pkg.painting) {
58
+ throw new Error('PARTS_COMPARISON_UNAVAILABLE: original painting required');
59
+ }
60
+ if (c.view.comparison?.mode === 'difference') {
61
+ for (const part of c.parts) {
62
+ const item = itemMap.get(part.name)!;
63
+ await partsDifference(pkg, item.index, c.view.comparison.threshold, c.view.footprints);
64
+ }
65
+ }
66
+ const partBuffers = new Map<string, Buffer>();
67
+ for (const part of c.parts) {
68
+ const item = itemMap.get(part.name)!;
69
+ const bytes = await readFile(item.path);
70
+ if (createHash('sha256').update(bytes).digest('hex') !== item.imageHash) {
71
+ throw new Error('PARTS_COMMENT_STALE_SOURCE: original PNG changed');
72
+ }
73
+ partBuffers.set(part.name, bytes);
74
+ }
75
+ await assertPartsUnchanged(pkg);
76
+ if (c.crop.png !== undefined) {
77
+ validatePngCrop(c.crop as PngCrop);
78
+ }
79
+ if (c.view.mode !== 'item') {
80
+ if (persist && c.crop.png !== undefined) {
81
+ await storePngCrop(c.crop as PngCrop);
82
+ } else {
83
+ await readPngCrop(c.crop);
84
+ }
85
+ await assertPartsUnchanged(pkg);
86
+ return { ...c, nativeCrop: null };
87
+ }
88
+ const primary = itemMap.get(c.parts[0]!.name)!;
89
+ const r = c.imageRegion!;
90
+ if (r.width * r.height > 16777216) {
91
+ throw new Error('PARTS_COMMENT_CROP_LIMIT: native crop exceeds 16 million pixels');
92
+ }
93
+ const bytes = partBuffers.get(primary.name)!;
94
+ const original = PNG.sync.read(bytes);
95
+ if (original.width !== primary.w || original.height !== primary.h) {
96
+ throw new Error('PARTS_COMMENT_IMAGE_SIZE: original dimensions differ from placement');
97
+ }
98
+ const native = new PNG({ width: r.width, height: r.height });
99
+ for (let y = 0; y < r.height; y++) {
100
+ original.data.copy(
101
+ native.data,
102
+ y * r.width * 4,
103
+ ((r.y + y) * original.width + r.x) * 4,
104
+ ((r.y + y) * original.width + r.x + r.width) * 4,
105
+ );
106
+ }
107
+ if (requireNative) {
108
+ const stored = await readPngCrop(c.nativeCrop!);
109
+ const decoded = PNG.sync.read(stored);
110
+ if (decoded.width !== r.width || decoded.height !== r.height || !decoded.data.equals(native.data)) {
111
+ throw new Error('PARTS_COMMENT_NATIVE_CROP_TAMPERED: native crop differs from bound original');
112
+ }
113
+ if (persist && c.crop.png !== undefined) {
114
+ await storePngCrop(c.crop as PngCrop);
115
+ } else {
116
+ await readPngCrop(c.crop);
117
+ }
118
+ await assertPartsUnchanged(pkg);
119
+ return c;
120
+ }
121
+ const png = PNG.sync.write(native);
122
+ const sha256 = createHash('sha256').update(png).digest('hex');
123
+ const nativeCrop = { path: `comment-crops/${sha256}.png`, sha256, width: r.width, height: r.height };
124
+ await storePngCrop(c.crop as PngCrop);
125
+ await storePngCrop({ ...nativeCrop, png: 'data:image/png;base64,' + png.toString('base64') });
126
+ await assertPartsUnchanged(pkg);
127
+ return { ...c, nativeCrop };
33
128
  }
@@ -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
  }