@jackwener/opencli 1.7.5 → 1.7.7

package/dist/src/browser/network-key.test.js

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { assignKeys, deriveKey } from './network-key.js';
+describe('deriveKey', () => {
+    it('extracts operationName from Twitter-style graphql URLs', () => {
+        expect(deriveKey({
+            method: 'GET',
+            url: 'https://x.com/i/api/graphql/6fWQaBPK51aGyC_VC7t9GQ/UserTweets?variables=...',
+        })).toBe('UserTweets');
+    });
+    it('handles graphql URLs without a query id', () => {
+        expect(deriveKey({
+            method: 'POST',
+            url: 'https://example.com/graphql/MyOp?vars=1',
+        })).toBe('MyOp');
+    });
+    it('uses METHOD host+pathname for REST calls', () => {
+        expect(deriveKey({
+            method: 'get',
+            url: 'https://api.example.com/v1/users?page=1',
+        })).toBe('GET api.example.com/v1/users');
+    });
+    it('falls back to truncated raw url when URL parsing fails', () => {
+        const key = deriveKey({ method: 'GET', url: 'not-a-valid-url' });
+        expect(key.startsWith('GET ')).toBe(true);
+        expect(key).toContain('not-a-valid-url');
+    });
+});
+describe('assignKeys', () => {
+    it('disambiguates collisions with #N suffixes', () => {
+        const out = assignKeys([
+            { url: 'https://x.com/i/api/graphql/a/UserTweets', method: 'GET' },
+            { url: 'https://x.com/i/api/graphql/b/UserTweets', method: 'GET' },
+            { url: 'https://api.example.com/v1/u', method: 'GET' },
+            { url: 'https://api.example.com/v1/u', method: 'GET' },
+            { url: 'https://api.example.com/v1/u', method: 'GET' },
+        ]);
+        expect(out.map(o => o.key)).toEqual([
+            'UserTweets',
+            'UserTweets#2',
+            'GET api.example.com/v1/u',
+            'GET api.example.com/v1/u#2',
+            'GET api.example.com/v1/u#3',
+        ]);
+    });
+    it('preserves extra fields on each request', () => {
+        const out = assignKeys([{ url: 'https://a.com/x', method: 'GET', status: 200 }]);
+        expect(out[0]).toMatchObject({ status: 200, key: 'GET a.com/x' });
+    });
+});

package/dist/src/browser/shape-filter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Shape-based field filter for `browser network --filter <fields>`.
+ *
+ * Agents know what fields a target request's body should contain
+ * (e.g. "author, text, likes") but not which of the captured requests
+ * carries that body. This module lets the network command filter
+ * entries down to those whose inferred shape exposes every requested
+ * field name as some path segment.
+ *
+ * Matching is "any-segment" (not last-segment-only): a field matches
+ * if it equals any segment name of any path in the shape map. This
+ * keeps nested-container fields (e.g. `legacy`, `author` used as an
+ * object key with further nesting) findable.
+ */
+import type { Shape } from './shape.js';
+export interface ParsedFilter {
+    /** Deduped, order-preserving, trimmed non-empty field names. */
+    fields: string[];
+}
+export interface FilterParseError {
+    /** `invalid_filter` structured error reason for agents. */
+    reason: string;
+}
+/**
+ * Parse `--filter` argument value. Splits on `,`, trims, drops empties,
+ * and dedupes (first-seen wins). Returns `FilterParseError` when the
+ * result is empty after cleaning — which means the caller passed only
+ * whitespace, commas, or an empty string.
+ */
+export declare function parseFilter(raw: string): ParsedFilter | FilterParseError;
+/**
+ * Extract named segments from a shape path. Drops the leading `$`,
+ * strips `[N]` array indices, and unwraps `["key"]` bracket-quoted
+ * keys back to their raw string.
+ *
+ * Examples:
+ *   `$`                              → []
+ *   `$.data.items[0].author`         → ['data','items','author']
+ *   `$.data.user["nick name"]`       → ['data','user','nick name']
+ *   `$.rows[0][1]`                   → ['rows']
+ */
+export declare function extractSegments(path: string): string[];
+/**
+ * Collect the set of segment names used anywhere in a shape map.
+ * The returned set is what we test field membership against.
+ */
+export declare function collectShapeSegments(shape: Shape): Set<string>;
+/**
+ * True iff every field in `fields` equals some segment name in `shape`.
+ * AND semantics: all fields must be present.
+ */
+export declare function shapeMatchesFilter(shape: Shape, fields: string[]): boolean;

package/dist/src/browser/shape-filter.js

@@ -0,0 +1,101 @@
+/**
+ * Parse `--filter` argument value. Splits on `,`, trims, drops empties,
+ * and dedupes (first-seen wins). Returns `FilterParseError` when the
+ * result is empty after cleaning — which means the caller passed only
+ * whitespace, commas, or an empty string.
+ */
+export function parseFilter(raw) {
+    if (typeof raw !== 'string') {
+        return { reason: `--filter value must be a non-empty comma-separated field list` };
+    }
+    const parts = raw.split(',').map((p) => p.trim()).filter((p) => p.length > 0);
+    if (parts.length === 0) {
+        return { reason: `--filter value must be a non-empty comma-separated field list (got "${raw}")` };
+    }
+    const seen = new Set();
+    const fields = [];
+    for (const p of parts) {
+        if (!seen.has(p)) {
+            seen.add(p);
+            fields.push(p);
+        }
+    }
+    return { fields };
+}
+/**
+ * Extract named segments from a shape path. Drops the leading `$`,
+ * strips `[N]` array indices, and unwraps `["key"]` bracket-quoted
+ * keys back to their raw string.
+ *
+ * Examples:
+ *   `$`                              → []
+ *   `$.data.items[0].author`         → ['data','items','author']
+ *   `$.data.user["nick name"]`       → ['data','user','nick name']
+ *   `$.rows[0][1]`                   → ['rows']
+ */
+export function extractSegments(path) {
+    if (!path || path === '$')
+        return [];
+    const out = [];
+    // Start past the leading `$`; if path doesn't start with `$` treat
+    // it as a raw segment list (keeps us robust to unexpected input).
+    let i = path.startsWith('$') ? 1 : 0;
+    while (i < path.length) {
+        const c = path[i];
+        if (c === '.') {
+            i++;
+            continue;
+        }
+        if (c === '[') {
+            // Either `[N]` (numeric) or `["key"]` (quoted key). Handle both.
+            const end = path.indexOf(']', i);
+            if (end === -1)
+                break;
+            const inner = path.slice(i + 1, end);
+            i = end + 1;
+            if (inner.length >= 2 && inner.startsWith('"') && inner.endsWith('"')) {
+                try {
+                    out.push(JSON.parse(inner));
+                }
+                catch {
+                    out.push(inner.slice(1, -1));
+                }
+            }
+            // numeric index: drop
+            continue;
+        }
+        // Bare identifier: read up to next `.` or `[`
+        let j = i;
+        while (j < path.length && path[j] !== '.' && path[j] !== '[')
+            j++;
+        out.push(path.slice(i, j));
+        i = j;
+    }
+    return out;
+}
+/**
+ * Collect the set of segment names used anywhere in a shape map.
+ * The returned set is what we test field membership against.
+ */
+export function collectShapeSegments(shape) {
+    const acc = new Set();
+    for (const p of Object.keys(shape)) {
+        for (const seg of extractSegments(p))
+            acc.add(seg);
+    }
+    return acc;
+}
+/**
+ * True iff every field in `fields` equals some segment name in `shape`.
+ * AND semantics: all fields must be present.
+ */
+export function shapeMatchesFilter(shape, fields) {
+    if (fields.length === 0)
+        return true;
+    const segs = collectShapeSegments(shape);
+    for (const f of fields) {
+        if (!segs.has(f))
+            return false;
+    }
+    return true;
+}

package/dist/src/browser/shape-filter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/shape-filter.test.js

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+import { collectShapeSegments, extractSegments, parseFilter, shapeMatchesFilter, } from './shape-filter.js';
+describe('parseFilter', () => {
+    it('splits comma-separated fields, trims, and drops empty tokens', () => {
+        const r = parseFilter('author, text , likes');
+        expect(r).toEqual({ fields: ['author', 'text', 'likes'] });
+    });
+    it('dedupes while preserving first-seen order', () => {
+        const r = parseFilter('a,b,a,c,b');
+        expect(r).toEqual({ fields: ['a', 'b', 'c'] });
+    });
+    it('rejects empty string as invalid_filter', () => {
+        const r = parseFilter('');
+        expect(r).toMatchObject({ reason: expect.stringContaining('non-empty') });
+    });
+    it('rejects whitespace-only as invalid_filter', () => {
+        const r = parseFilter('   ');
+        expect(r).toMatchObject({ reason: expect.stringContaining('non-empty') });
+    });
+    it('rejects commas-only as invalid_filter', () => {
+        const r = parseFilter(',,,');
+        expect(r).toMatchObject({ reason: expect.stringContaining('non-empty') });
+    });
+    it('accepts a single field', () => {
+        expect(parseFilter('author')).toEqual({ fields: ['author'] });
+    });
+});
+describe('extractSegments', () => {
+    it('returns empty for root', () => {
+        expect(extractSegments('$')).toEqual([]);
+    });
+    it('splits dotted path and drops $', () => {
+        expect(extractSegments('$.data.user.name')).toEqual(['data', 'user', 'name']);
+    });
+    it('drops numeric array indices', () => {
+        expect(extractSegments('$.items[0].author')).toEqual(['items', 'author']);
+        expect(extractSegments('$.rows[0][12]')).toEqual(['rows']);
+    });
+    it('unwraps bracket-quoted keys', () => {
+        expect(extractSegments('$.data["weird key"]')).toEqual(['data', 'weird key']);
+    });
+    it('handles bracket-quoted keys at root', () => {
+        expect(extractSegments('$["123bad"]')).toEqual(['123bad']);
+    });
+    it('mixes bracket keys and dot segments', () => {
+        expect(extractSegments('$.data.user["nick name"].age'))
+            .toEqual(['data', 'user', 'nick name', 'age']);
+    });
+});
+describe('collectShapeSegments', () => {
+    it('collects every segment name from every path in a shape', () => {
+        const shape = {
+            '$': 'object',
+            '$.data': 'object',
+            '$.data.items': 'array(3)',
+            '$.data.items[0]': 'object',
+            '$.data.items[0].author': 'string',
+            '$.data.items[0].text': 'string',
+        };
+        const segs = collectShapeSegments(shape);
+        expect(segs.has('data')).toBe(true);
+        expect(segs.has('items')).toBe(true);
+        expect(segs.has('author')).toBe(true);
+        expect(segs.has('text')).toBe(true);
+        expect(segs.has('$')).toBe(false);
+        expect(segs.has('[0]')).toBe(false);
+    });
+    it('returns an empty set for an empty shape', () => {
+        expect(collectShapeSegments({}).size).toBe(0);
+    });
+});
+describe('shapeMatchesFilter', () => {
+    const shape = {
+        '$': 'object',
+        '$.data': 'object',
+        '$.data.items': 'array(1)',
+        '$.data.items[0].author': 'string',
+        '$.data.items[0].text': 'string',
+        '$.data.items[0].likes': 'number',
+    };
+    it('returns true when every field matches some path segment (AND)', () => {
+        expect(shapeMatchesFilter(shape, ['author', 'text', 'likes'])).toBe(true);
+    });
+    it('matches nested container names, not just leaves (any-segment rule)', () => {
+        // `data` and `items` are container segments, not leaves; still must match.
+        expect(shapeMatchesFilter(shape, ['data', 'items'])).toBe(true);
+    });
+    it('returns false when any field is missing', () => {
+        expect(shapeMatchesFilter(shape, ['author', 'missing'])).toBe(false);
+    });
+    it('is case-sensitive', () => {
+        expect(shapeMatchesFilter(shape, ['Author'])).toBe(false);
+        expect(shapeMatchesFilter(shape, ['author'])).toBe(true);
+    });
+    it('empty filter list vacuously matches', () => {
+        expect(shapeMatchesFilter(shape, [])).toBe(true);
+    });
+    it('rejects requests whose shape has no body (empty shape)', () => {
+        expect(shapeMatchesFilter({}, ['author'])).toBe(false);
+    });
+});

package/dist/src/browser/shape.d.ts

@@ -0,0 +1,23 @@
+/**
+ * JSON shape inference for browser network response previews.
+ *
+ * Produces a flat path → type descriptor map so agents can understand
+ * response structure without paying the token cost of the full body.
+ *
+ * Descriptors:
+ *   string | number | boolean | null              primitives
+ *   string(len=N)                                 strings longer than sampleStringLen
+ *   array(0) | array(N)                           array at depth cap or summarized
+ *   object | object(empty)                        objects at depth cap or summarized
+ *   (truncated)                                   output size budget exceeded
+ */
+export interface InferShapeOptions {
+    /** Max path depth to descend into (default 6) */
+    maxDepth?: number;
+    /** Byte budget for the serialized output; truncates when exceeded (default 2048) */
+    maxBytes?: number;
+    /** Strings longer than this get summarized as `string(len=N)` (default 80) */
+    sampleStringLen?: number;
+}
+export type Shape = Record<string, string>;
+export declare function inferShape(value: unknown, opts?: InferShapeOptions): Shape;

package/dist/src/browser/shape.js

@@ -0,0 +1,95 @@
+/**
+ * JSON shape inference for browser network response previews.
+ *
+ * Produces a flat path → type descriptor map so agents can understand
+ * response structure without paying the token cost of the full body.
+ *
+ * Descriptors:
+ *   string | number | boolean | null              primitives
+ *   string(len=N)                                 strings longer than sampleStringLen
+ *   array(0) | array(N)                           array at depth cap or summarized
+ *   object | object(empty)                        objects at depth cap or summarized
+ *   (truncated)                                   output size budget exceeded
+ */
+const ROOT = '$';
+export function inferShape(value, opts = {}) {
+    const maxDepth = opts.maxDepth ?? 6;
+    const maxBytes = opts.maxBytes ?? 2048;
+    const sampleStringLen = opts.sampleStringLen ?? 80;
+    const out = {};
+    let bytes = 2; // account for `{}` braces when serialized
+    let truncated = false;
+    const add = (path, desc) => {
+        if (truncated)
+            return false;
+        const entryBytes = JSON.stringify(path).length + JSON.stringify(desc).length + 2; // ":" + ","
+        if (bytes + entryBytes > maxBytes) {
+            out['(truncated)'] = `reached ${maxBytes}B budget`;
+            truncated = true;
+            return false;
+        }
+        out[path] = desc;
+        bytes += entryBytes;
+        return true;
+    };
+    const walk = (node, path, depth) => {
+        if (truncated)
+            return;
+        if (node === null) {
+            add(path, 'null');
+            return;
+        }
+        const t = typeof node;
+        if (t === 'string') {
+            const s = node;
+            add(path, s.length > sampleStringLen ? `string(len=${s.length})` : 'string');
+            return;
+        }
+        if (t === 'number' || t === 'boolean') {
+            add(path, t);
+            return;
+        }
+        if (t === 'undefined' || t === 'function' || t === 'symbol' || t === 'bigint') {
+            add(path, t);
+            return;
+        }
+        if (Array.isArray(node)) {
+            if (node.length === 0) {
+                add(path, 'array(0)');
+                return;
+            }
+            if (depth >= maxDepth) {
+                add(path, `array(${node.length})`);
+                return;
+            }
+            if (!add(path, `array(${node.length})`))
+                return;
+            walk(node[0], `${path}[0]`, depth + 1);
+            return;
+        }
+        // plain object
+        const obj = node;
+        const keys = Object.keys(obj);
+        if (keys.length === 0) {
+            add(path, 'object(empty)');
+            return;
+        }
+        if (depth >= maxDepth) {
+            add(path, `object(keys=${keys.length})`);
+            return;
+        }
+        if (!add(path, 'object'))
+            return;
+        for (const k of keys) {
+            if (truncated)
+                return;
+            const childPath = isSafeIdent(k) ? `${path}.${k}` : `${path}[${JSON.stringify(k)}]`;
+            walk(obj[k], childPath, depth + 1);
+        }
+    };
+    walk(value, ROOT, 0);
+    return out;
+}
+function isSafeIdent(key) {
+    return /^[A-Za-z_$][\w$]*$/.test(key);
+}

package/dist/src/browser/shape.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/shape.test.js

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+import { inferShape } from './shape.js';
+describe('inferShape', () => {
+    it('describes primitives at root', () => {
+        expect(inferShape('hello')).toEqual({ $: 'string' });
+        expect(inferShape(42)).toEqual({ $: 'number' });
+        expect(inferShape(true)).toEqual({ $: 'boolean' });
+        expect(inferShape(null)).toEqual({ $: 'null' });
+    });
+    it('summarizes long strings with their length', () => {
+        const long = 'x'.repeat(200);
+        expect(inferShape(long, { sampleStringLen: 80 })).toEqual({ $: 'string(len=200)' });
+    });
+    it('walks nested objects and emits dotted paths', () => {
+        const shape = inferShape({ user: { id: 1, name: 'bob' } });
+        expect(shape).toEqual({
+            $: 'object',
+            '$.user': 'object',
+            '$.user.id': 'number',
+            '$.user.name': 'string',
+        });
+    });
+    it('quotes unsafe keys using bracket notation', () => {
+        const shape = inferShape({ 'weird key': 1, '123bad': 2 });
+        expect(shape['$["weird key"]']).toBe('number');
+        expect(shape['$["123bad"]']).toBe('number');
+    });
+    it('samples the first array element and reports length', () => {
+        const shape = inferShape({ items: [{ a: 1 }, { a: 2 }, { a: 3 }] });
+        expect(shape['$.items']).toBe('array(3)');
+        expect(shape['$.items[0]']).toBe('object');
+        expect(shape['$.items[0].a']).toBe('number');
+    });
+    it('marks empty containers explicitly', () => {
+        const shape = inferShape({ arr: [], obj: {} });
+        expect(shape['$.arr']).toBe('array(0)');
+        expect(shape['$.obj']).toBe('object(empty)');
+    });
+    it('collapses subtrees past maxDepth', () => {
+        const deep = { a: { b: { c: { d: { e: { f: 'too deep' } } } } } };
+        const shape = inferShape(deep, { maxDepth: 2 });
+        expect(shape['$.a.b']).toMatch(/^object/);
+        expect(shape['$.a.b.c']).toBeUndefined();
+    });
+    it('truncates when the byte budget is exhausted', () => {
+        const wide = {};
+        for (let i = 0; i < 500; i++)
+            wide[`field_${i}`] = i;
+        const shape = inferShape(wide, { maxBytes: 256 });
+        expect(shape['(truncated)']).toMatch(/256B/);
+        expect(Object.keys(shape).length).toBeLessThan(500);
+    });
+    it('stops descending into an array once the budget is hit by its own descriptor', () => {
+        // Budget just large enough for `$` + one deep array descriptor, not its element.
+        const shape = inferShape({ items: [{ deep: 1 }] }, { maxBytes: 40 });
+        expect(shape['$.items[0]']).toBeUndefined();
+        expect(shape['(truncated)']).toBeDefined();
+    });
+    it('handles the Twitter UserTweets payload envelope', () => {
+        const payload = {
+            data: {
+                user: {
+                    result: {
+                        rest_id: '42',
+                        timeline_v2: {
+                            timeline: {
+                                instructions: [
+                                    { type: 'TimelinePinEntry', entries: [] },
+                                    { entries: [{ entryId: 'tweet-1', content: { entryType: 'TimelineTimelineItem' } }] },
+                                ],
+                            },
+                        },
+                    },
+                },
+            },
+        };
+        const shape = inferShape(payload, { maxDepth: 10 });
+        expect(shape['$.data.user.result.rest_id']).toBe('string');
+        expect(shape['$.data.user.result.timeline_v2.timeline.instructions']).toBe('array(2)');
+        expect(shape['$.data.user.result.timeline_v2.timeline.instructions[0]']).toBe('object');
+    });
+});

package/dist/src/browser/target-errors.d.ts

@@ -5,18 +5,31 @@
  * goes through the unified resolver. When resolution fails, one of these
  * structured errors is thrown so that AI agents and adapter authors get
  * actionable diagnostics instead of a generic "Element not found".
+ *
+ * Numeric-ref codes (from snapshot indices):
+ *   - not_found: the ref no longer exists in the DOM
+ *   - stale_ref: the ref still exists but points to a different element
+ *
+ * CSS-selector codes (from `--selector <css>` entrypoints):
+ *   - invalid_selector:       selector syntax rejected by querySelectorAll
+ *   - selector_not_found:     0 matches
+ *   - selector_ambiguous:     >1 matches for a write op without --nth
+ *   - selector_nth_out_of_range: --nth beyond matches_n
  */
-export type TargetErrorCode = 'not_found' | 'ambiguous' | 'stale_ref';
+export type TargetErrorCode = 'not_found' | 'stale_ref' | 'invalid_selector' | 'selector_not_found' | 'selector_ambiguous' | 'selector_nth_out_of_range';
 export interface TargetErrorInfo {
     code: TargetErrorCode;
     message: string;
     hint: string;
     candidates?: string[];
+    /** CSS-path match count, when the error was raised mid-resolution */
+    matches_n?: number;
 }
 export declare class TargetError extends Error {
     readonly code: TargetErrorCode;
     readonly hint: string;
     readonly candidates?: string[];
+    readonly matches_n?: number;
     constructor(info: TargetErrorInfo);
     /** Serialize for structured output to AI agents */
     toJSON(): TargetErrorInfo;

package/dist/src/browser/target-errors.js

@@ -5,17 +5,29 @@
  * goes through the unified resolver. When resolution fails, one of these
  * structured errors is thrown so that AI agents and adapter authors get
  * actionable diagnostics instead of a generic "Element not found".
+ *
+ * Numeric-ref codes (from snapshot indices):
+ *   - not_found: the ref no longer exists in the DOM
+ *   - stale_ref: the ref still exists but points to a different element
+ *
+ * CSS-selector codes (from `--selector <css>` entrypoints):
+ *   - invalid_selector:       selector syntax rejected by querySelectorAll
+ *   - selector_not_found:     0 matches
+ *   - selector_ambiguous:     >1 matches for a write op without --nth
+ *   - selector_nth_out_of_range: --nth beyond matches_n
  */
 export class TargetError extends Error {
     code;
     hint;
     candidates;
+    matches_n;
     constructor(info) {
         super(info.message);
         this.name = 'TargetError';
         this.code = info.code;
         this.hint = info.hint;
         this.candidates = info.candidates;
+        this.matches_n = info.matches_n;
     }
     /** Serialize for structured output to AI agents */
     toJSON() {
@@ -24,6 +36,7 @@ export class TargetError extends Error {
             message: this.message,
             hint: this.hint,
             ...(this.candidates && { candidates: this.candidates }),
+            ...(this.matches_n !== undefined && { matches_n: this.matches_n }),
         };
     }
 }

package/dist/src/browser/target-errors.test.js

@@ -14,16 +14,47 @@ describe('TargetError', () => {
         expect(err.hint).toContain('fresh snapshot');
         expect(err.candidates).toBeUndefined();
     });
-    it('creates ambiguous error with candidates', () => {
+    it('creates selector_ambiguous error with candidates + matches_n', () => {
         const err = new TargetError({
-            code: 'ambiguous',
+            code: 'selector_ambiguous',
             message: 'CSS selector ".btn" matched 3 elements',
-            hint: 'Use a more specific selector.',
+            hint: 'Use a more specific selector, or pass --nth.',
             candidates: ['<button> "Login"', '<button> "Sign Up"', '<button> "Cancel"'],
+            matches_n: 3,
         });
-        expect(err.code).toBe('ambiguous');
+        expect(err.code).toBe('selector_ambiguous');
         expect(err.candidates).toHaveLength(3);
         expect(err.candidates[0]).toContain('Login');
+        expect(err.matches_n).toBe(3);
+    });
+    it('creates invalid_selector error', () => {
+        const err = new TargetError({
+            code: 'invalid_selector',
+            message: 'Invalid CSS selector: >>> (unexpected token)',
+            hint: 'Check the selector syntax.',
+        });
+        expect(err.code).toBe('invalid_selector');
+        expect(err.message).toContain('Invalid CSS selector');
+    });
+    it('creates selector_not_found error with matches_n=0', () => {
+        const err = new TargetError({
+            code: 'selector_not_found',
+            message: 'CSS selector ".missing" matched 0 elements',
+            hint: 'Check the page or use browser find.',
+            matches_n: 0,
+        });
+        expect(err.code).toBe('selector_not_found');
+        expect(err.matches_n).toBe(0);
+    });
+    it('creates selector_nth_out_of_range error', () => {
+        const err = new TargetError({
+            code: 'selector_nth_out_of_range',
+            message: 'matched 3 elements, but --nth=5 is out of range',
+            hint: 'Use --nth between 0 and 2.',
+            matches_n: 3,
+        });
+        expect(err.code).toBe('selector_nth_out_of_range');
+        expect(err.matches_n).toBe(3);
     });
     it('creates stale_ref error', () => {
         const err = new TargetError({
@@ -36,17 +67,19 @@ describe('TargetError', () => {
     });
     it('serializes to JSON for structured output', () => {
         const err = new TargetError({
-            code: 'ambiguous',
+            code: 'selector_ambiguous',
             message: 'matched 3',
             hint: 'be specific',
             candidates: ['a', 'b'],
+            matches_n: 3,
         });
         const json = err.toJSON();
         expect(json).toEqual({
-            code: 'ambiguous',
+            code: 'selector_ambiguous',
             message: 'matched 3',
             hint: 'be specific',
             candidates: ['a', 'b'],
+            matches_n: 3,
         });
     });
     it('omits candidates from JSON when not present', () => {