@@ -103,6 +103,17 @@ test('a line that merely mentions the tag in prose is an ordinary comment', () =
103103 assert . deepEqual ( parseTargetAnnotationCommentLine ( '# just a comment' ) , { kind : 'none' } ) ;
104104} ) ;
105105
106+ test ( 'a line that is not a comment at all is not a target annotation' , ( ) => {
107+ assert . deepEqual ( parseTargetAnnotationCommentLine ( 'const x = 1;' ) , { kind : 'none' } ) ;
108+ } ) ;
109+
110+ test ( 'leading and trailing whitespace around the annotation line does not break parsing' , ( ) => {
111+ const result = parseTargetAnnotationCommentLine (
112+ ' # agent-device:target-v1 {"role":"button","verification":"verified"} ' ,
113+ ) ;
114+ assert . equal ( result . kind , 'v1' ) ;
115+ } ) ;
116+
106117// ---------------------------------------------------------------------------
107118// Normalization: NFC, label trim/collapse, normalized-role source
108119// ---------------------------------------------------------------------------
@@ -117,6 +128,27 @@ test('normalizeLabelField treats a whitespace-only label as absent', () => {
117128 assert . equal ( normalizeLabelField ( ' ' ) , undefined ) ;
118129} ) ;
119130
131+ test ( 'an empty-string id is treated as absent, like a whitespace-only label' , ( ) => {
132+ const parsed = parseTargetAnnotationV1Payload (
133+ JSON . stringify ( { id : '' , role : 'button' , verification : 'verified' } ) ,
134+ ) ;
135+ assert . equal ( parsed . id , undefined ) ;
136+ } ) ;
137+
138+ test ( 'scrollRegion.label serializes and round trips like every other label field' , ( ) => {
139+ const evidence = baseEvidence ( {
140+ id : undefined ,
141+ label : undefined ,
142+ scrollRegion : { role : 'scrollview' , id : 'editor-scroll' , label : 'Body' } ,
143+ } ) ;
144+ const json = serializeTargetAnnotationV1 ( evidence ) ;
145+ assert . ok (
146+ json . includes ( '"scrollRegion":{"role":"scrollview","id":"editor-scroll","label":"Body"}' ) ,
147+ ) ;
148+ const parsed = parseTargetAnnotationV1Payload ( json ) ;
149+ assert . equal ( parsed . scrollRegion ?. label , 'Body' ) ;
150+ } ) ;
151+
120152test ( 'embedded quotes and backslashes in labels round trip losslessly' , ( ) => {
121153 const evidence = baseEvidence ( { label : 'Say "hi" \\ backslash' , id : undefined } ) ;
122154 const json = serializeTargetAnnotationV1 ( evidence ) ;
@@ -200,6 +232,38 @@ test('parser rejects more than 8 ancestry entries', () => {
200232 ) ;
201233} ) ;
202234
235+ test ( 'parser accepts a payload landing exactly on the 4 KiB cap boundary' , ( ) => {
236+ // A fixed filler length below the field cap on every other string field,
237+ // plus one tunable ancestry-entry role (also within its own 256-byte field
238+ // cap) sized by exact arithmetic — every character is ASCII, so 1 char is 1
239+ // UTF-8 byte, and the tunable field's required length is computable
240+ // directly rather than searched for.
241+ const FILLER = 'x' . repeat ( 180 ) ;
242+ const build = ( padLength : number ) => {
243+ const ancestry = Array . from ( { length : TARGET_ANNOTATION_MAX_ANCESTRY } , ( _unused , index ) => ( {
244+ role : index === 0 ? 'x' . repeat ( padLength ) : FILLER ,
245+ label : index === 0 ? undefined : FILLER ,
246+ } ) ) ;
247+ return JSON . stringify ( {
248+ id : FILLER ,
249+ role : FILLER ,
250+ label : FILLER ,
251+ ancestry,
252+ scrollRegion : { role : FILLER , id : FILLER , label : FILLER } ,
253+ verification : 'verified' ,
254+ } ) ;
255+ } ;
256+ const base = Buffer . byteLength ( build ( 0 ) , 'utf8' ) ;
257+ const padLength = TARGET_ANNOTATION_MAX_PAYLOAD_BYTES - base ;
258+ assert . ok (
259+ padLength >= 0 && padLength <= TARGET_ANNOTATION_MAX_FIELD_BYTES ,
260+ `fixture no longer straddles the cap (base ${ base } , needs pad ${ padLength } )` ,
261+ ) ;
262+ const json = build ( padLength ) ;
263+ assert . equal ( Buffer . byteLength ( json , 'utf8' ) , TARGET_ANNOTATION_MAX_PAYLOAD_BYTES ) ;
264+ assert . doesNotThrow ( ( ) => parseTargetAnnotationV1Payload ( json ) ) ;
265+ } ) ;
266+
203267test ( 'truncateToUtf8Bytes never splits a surrogate pair' , ( ) => {
204268 const emoji = '\u{1F600}' ; // 4 UTF-8 bytes, a surrogate pair in UTF-16
205269 const truncated = truncateToUtf8Bytes ( `ab${ emoji } ` , 3 ) ;
@@ -210,6 +274,27 @@ test('truncateToUtf8Bytes never splits a surrogate pair', () => {
210274 assert . equal ( / [ \ud800 - \udbff ] $ / . test ( truncated ) , false ) ;
211275} ) ;
212276
277+ test ( 'truncateToUtf8Bytes drops a lone high surrogate at either end of its range' , ( ) => {
278+ // Codepoint 0x10000 encodes to the lowest high surrogate (0xD800); 0x10FFFF
279+ // (the last valid Unicode codepoint) encodes to the highest (0xDBFF). Both
280+ // bound cases must trigger the drop, not just a value in the middle of the
281+ // range.
282+ for ( const codepoint of [ 0x10000 , 0x10ffff ] ) {
283+ const astral = String . fromCodePoint ( codepoint ) ;
284+ const truncated = truncateToUtf8Bytes ( `a${ astral } ` , 4 ) ;
285+ assert . equal ( truncated , 'a' , `codepoint 0x${ codepoint . toString ( 16 ) } left a lone surrogate` ) ;
286+ }
287+ } ) ;
288+
289+ test ( 'truncateToUtf8Bytes keeps a fully-paired surrogate that lands exactly on the byte budget' , ( ) => {
290+ // The budget lands the cut right after a complete surrogate pair (trimming
291+ // only the unrelated trailing "cd"), so nothing here is a split — the
292+ // dangling-high-surrogate guard must NOT also fire on the pair's low half.
293+ const astral = String . fromCodePoint ( 0x10000 ) ;
294+ const truncated = truncateToUtf8Bytes ( `ab${ astral } cd` , 6 ) ;
295+ assert . equal ( truncated , `ab${ astral } ` ) ;
296+ } ) ;
297+
213298// ---------------------------------------------------------------------------
214299// Malformed / unbound annotations
215300// ---------------------------------------------------------------------------
@@ -219,33 +304,190 @@ test('parser rejects non-JSON payloads', () => {
219304} ) ;
220305
221306test ( 'parser rejects a JSON array or scalar payload' , ( ) => {
222- assertInvalidArgs ( ( ) => parseTargetAnnotationV1Payload ( '[]' ) ) ;
223- assertInvalidArgs ( ( ) => parseTargetAnnotationV1Payload ( '"button"' ) ) ;
307+ assertInvalidArgs ( ( ) => parseTargetAnnotationV1Payload ( '[]' ) , / m u s t b e a J S O N o b j e c t / ) ;
308+ assertInvalidArgs ( ( ) => parseTargetAnnotationV1Payload ( '"button"' ) , / m u s t b e a J S O N o b j e c t / ) ;
309+ } ) ;
310+
311+ // `typeof null === 'object'` in JS, so a bare `null` payload passes the
312+ // typeof check above and needs its own explicit rejection — the array/scalar
313+ // test above cannot exercise this branch.
314+ test ( 'parser rejects a null payload' , ( ) => {
315+ assertInvalidArgs ( ( ) => parseTargetAnnotationV1Payload ( 'null' ) , / m u s t b e a J S O N o b j e c t / ) ;
224316} ) ;
225317
226318test ( 'parser rejects a wrong-typed known field' , ( ) => {
227- assertInvalidArgs ( ( ) =>
228- parseTargetAnnotationV1Payload ( JSON . stringify ( { role : 42 , verification : 'verified' } ) ) ,
319+ assertInvalidArgs (
320+ ( ) => parseTargetAnnotationV1Payload ( JSON . stringify ( { role : 42 , verification : 'verified' } ) ) ,
321+ / " r o l e " m u s t b e a s t r i n g / ,
322+ ) ;
323+ } ) ;
324+
325+ test ( 'parser rejects wrong-typed optional id and label fields, naming each in the message' , ( ) => {
326+ assertInvalidArgs (
327+ ( ) =>
328+ parseTargetAnnotationV1Payload (
329+ JSON . stringify ( { id : 42 , role : 'button' , verification : 'verified' } ) ,
330+ ) ,
331+ / " i d " m u s t b e a s t r i n g / ,
332+ ) ;
333+ assertInvalidArgs (
334+ ( ) =>
335+ parseTargetAnnotationV1Payload (
336+ JSON . stringify ( { role : 'button' , label : 42 , verification : 'verified' } ) ,
337+ ) ,
338+ / " l a b e l " m u s t b e a s t r i n g / ,
339+ ) ;
340+ } ) ;
341+
342+ test ( 'parser rejects ancestry that is not an array' , ( ) => {
343+ assertInvalidArgs (
344+ ( ) =>
345+ parseTargetAnnotationV1Payload (
346+ JSON . stringify ( { role : 'button' , ancestry : 'toolbar' , verification : 'verified' } ) ,
347+ ) ,
348+ / " a n c e s t r y " m u s t b e a n a r r a y / ,
349+ ) ;
350+ } ) ;
351+
352+ test ( 'parser rejects an ancestry entry that is not an object' , ( ) => {
353+ assertInvalidArgs (
354+ ( ) =>
355+ parseTargetAnnotationV1Payload (
356+ JSON . stringify ( { role : 'button' , ancestry : [ 'toolbar' ] , verification : 'verified' } ) ,
357+ ) ,
358+ / " a n c e s t r y \[ 0 \] " m u s t b e a n o b j e c t / ,
359+ ) ;
360+ assertInvalidArgs (
361+ ( ) =>
362+ parseTargetAnnotationV1Payload (
363+ JSON . stringify ( { role : 'button' , ancestry : [ null ] , verification : 'verified' } ) ,
364+ ) ,
365+ / " a n c e s t r y \[ 0 \] " m u s t b e a n o b j e c t / ,
366+ ) ;
367+ } ) ;
368+
369+ test ( 'parser rejects a scrollRegion or rect that is not an object' , ( ) => {
370+ assertInvalidArgs (
371+ ( ) =>
372+ parseTargetAnnotationV1Payload (
373+ JSON . stringify ( { role : 'button' , scrollRegion : 'list' , verification : 'verified' } ) ,
374+ ) ,
375+ / " s c r o l l R e g i o n " m u s t b e a n o b j e c t / ,
376+ ) ;
377+ assertInvalidArgs (
378+ ( ) =>
379+ parseTargetAnnotationV1Payload (
380+ JSON . stringify ( { role : 'button' , rect : 'somewhere' , verification : 'verified' } ) ,
381+ ) ,
382+ / " r e c t " m u s t b e a n o b j e c t / ,
383+ ) ;
384+ } ) ;
385+
386+ // `typeof null === 'object'`, so a null scrollRegion/rect needs its own
387+ // explicit rejection — same trap as the top-level null-payload case above.
388+ // Getting this wrong crashes on `null.role`/`null.x` (a raw TypeError)
389+ // instead of a graceful AppError, unlike the string-typed case above.
390+ test ( 'parser rejects a null scrollRegion or rect with AppError, not a native crash on null property access' , ( ) => {
391+ assertInvalidArgs (
392+ ( ) =>
393+ parseTargetAnnotationV1Payload (
394+ JSON . stringify ( { role : 'button' , scrollRegion : null , verification : 'verified' } ) ,
395+ ) ,
396+ / " s c r o l l R e g i o n " m u s t b e a n o b j e c t / ,
397+ ) ;
398+ assertInvalidArgs (
399+ ( ) =>
400+ parseTargetAnnotationV1Payload (
401+ JSON . stringify ( { role : 'button' , rect : null , verification : 'verified' } ) ,
402+ ) ,
403+ / " r e c t " m u s t b e a n o b j e c t / ,
229404 ) ;
230405} ) ;
231406
232407test ( 'parser rejects an invalid verification value' , ( ) => {
233- assertInvalidArgs ( ( ) =>
234- parseTargetAnnotationV1Payload ( JSON . stringify ( { role : 'button' , verification : 'maybe' } ) ) ,
408+ assertInvalidArgs (
409+ ( ) => parseTargetAnnotationV1Payload ( JSON . stringify ( { role : 'button' , verification : 'maybe' } ) ) ,
410+ / " v e r i f i c a t i o n " m u s t b e " v e r i f i e d " o r " u n v e r i f i a b l e " / ,
235411 ) ;
236412} ) ;
237413
238- test ( 'parser rejects a negative or non-integer sibling/viewportOrder' , ( ) => {
239- assertInvalidArgs ( ( ) =>
240- parseTargetAnnotationV1Payload (
241- JSON . stringify ( { role : 'button' , sibling : - 1 , verification : 'verified' } ) ,
242- ) ,
414+ test ( 'parser rejects a negative or non-integer sibling/viewportOrder, naming each in the message' , ( ) => {
415+ assertInvalidArgs (
416+ ( ) =>
417+ parseTargetAnnotationV1Payload (
418+ JSON . stringify ( { role : 'button' , sibling : - 1 , verification : 'verified' } ) ,
419+ ) ,
420+ / " s i b l i n g " m u s t b e a n o n - n e g a t i v e i n t e g e r / ,
243421 ) ;
244- assertInvalidArgs ( ( ) =>
245- parseTargetAnnotationV1Payload (
246- JSON . stringify ( { role : 'button' , viewportOrder : 1.5 , verification : 'verified' } ) ,
247- ) ,
422+ assertInvalidArgs (
423+ ( ) =>
424+ parseTargetAnnotationV1Payload (
425+ JSON . stringify ( { role : 'button' , viewportOrder : 1.5 , verification : 'verified' } ) ,
426+ ) ,
427+ / " v i e w p o r t O r d e r " m u s t b e a n o n - n e g a t i v e i n t e g e r / ,
428+ ) ;
429+ } ) ;
430+
431+ test ( 'parser rejects a wrong-typed scrollRegion.id and scrollRegion.label, naming each in the message' , ( ) => {
432+ assertInvalidArgs (
433+ ( ) =>
434+ parseTargetAnnotationV1Payload (
435+ JSON . stringify ( {
436+ role : 'button' ,
437+ scrollRegion : { role : 'list' , id : 42 } ,
438+ verification : 'verified' ,
439+ } ) ,
440+ ) ,
441+ / " i d " m u s t b e a s t r i n g / ,
442+ ) ;
443+ assertInvalidArgs (
444+ ( ) =>
445+ parseTargetAnnotationV1Payload (
446+ JSON . stringify ( {
447+ role : 'button' ,
448+ scrollRegion : { role : 'list' , label : 42 } ,
449+ verification : 'verified' ,
450+ } ) ,
451+ ) ,
452+ / " s c r o l l R e g i o n \. l a b e l " m u s t b e a s t r i n g / ,
453+ ) ;
454+ } ) ;
455+
456+ test ( 'parser rejects a wrong-typed ancestry entry label, naming it in the message' , ( ) => {
457+ assertInvalidArgs (
458+ ( ) =>
459+ parseTargetAnnotationV1Payload (
460+ JSON . stringify ( {
461+ role : 'button' ,
462+ ancestry : [ { role : 'toolbar' , label : 42 } ] ,
463+ verification : 'verified' ,
464+ } ) ,
465+ ) ,
466+ / " a n c e s t r y \[ 0 \] \. l a b e l " m u s t b e a s t r i n g / ,
467+ ) ;
468+ } ) ;
469+
470+ test ( 'parser rejects a wrong-typed rect field, naming each in the message' , ( ) => {
471+ for ( const field of [ 'x' , 'y' , 'width' , 'height' ] ) {
472+ assertInvalidArgs (
473+ ( ) =>
474+ parseTargetAnnotationV1Payload (
475+ JSON . stringify ( {
476+ role : 'button' ,
477+ rect : { x : 1 , y : 2 , width : 3 , height : 4 , [ field ] : 'nope' } ,
478+ verification : 'verified' ,
479+ } ) ,
480+ ) ,
481+ new RegExp ( `"rect\\.${ field } " must be a finite number` ) ,
482+ ) ;
483+ }
484+ } ) ;
485+
486+ test ( 'a whitespace-only label collapses to absent through the full parse, not just the normalizer' , ( ) => {
487+ const parsed = parseTargetAnnotationV1Payload (
488+ JSON . stringify ( { role : 'button' , label : ' ' , verification : 'verified' } ) ,
248489 ) ;
490+ assert . equal ( parsed . label , undefined ) ;
249491} ) ;
250492
251493// ---------------------------------------------------------------------------
0 commit comments