@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/browser/runtime/local-cloak/session-manager.test.js

@@ -0,0 +1,92 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { CloakSessionManager } from './session-manager.js';
+function fakeContext() {
+    const page = {
+        goto: vi.fn().mockResolvedValue(undefined),
+        evaluate: vi.fn().mockResolvedValue('ok'),
+        title: vi.fn().mockResolvedValue('Title'),
+        url: vi.fn().mockReturnValue('https://example.com/'),
+        screenshot: vi.fn().mockResolvedValue(Buffer.from('png')),
+        isClosed: vi.fn().mockReturnValue(false),
+        close: vi.fn().mockResolvedValue(undefined),
+    };
+    return {
+        context: {
+            pages: vi.fn().mockReturnValue([page]),
+            newPage: vi.fn().mockResolvedValue(page),
+            cookies: vi.fn().mockResolvedValue([{ name: 'sid', value: '1', domain: 'example.com', path: '/' }]),
+            close: vi.fn().mockResolvedValue(undefined),
+        },
+        page,
+    };
+}
+describe('CloakSessionManager', () => {
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    it('launches one persistent context per profile and reuses named sessions', async () => {
+        const launched = fakeContext();
+        const launchPersistentContext = vi.fn().mockResolvedValue(launched.context);
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext,
+        });
+        const first = await manager.getPage({ profileId: 'default', session: 'work', surface: 'browser' });
+        const second = await manager.getPage({ profileId: 'default', session: 'work', surface: 'browser' });
+        expect(first.page).toBe(second.page);
+        expect(launchPersistentContext).toHaveBeenCalledTimes(1);
+        expect(launchPersistentContext.mock.calls[0][0]).toMatchObject({ headless: false });
+    });
+    it('closes ephemeral adapter sessions when released', async () => {
+        const launched = fakeContext();
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext: vi.fn().mockResolvedValue(launched.context),
+        });
+        const lease = await manager.getPage({ profileId: 'default', session: 'site:x:uuid', surface: 'adapter', siteSession: 'ephemeral' });
+        await manager.release({ profileId: 'default', session: 'site:x:uuid', surface: 'adapter' });
+        expect(lease.page.close).toHaveBeenCalled();
+    });
+    it('closes non-persistent leases when their idle timeout expires', async () => {
+        vi.useFakeTimers();
+        const launched = fakeContext();
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext: vi.fn().mockResolvedValue(launched.context),
+        });
+        const lease = await manager.getPage({ profileId: 'default', session: 'work', surface: 'browser', idleTimeout: 25 });
+        await vi.advanceTimersByTimeAsync(24);
+        expect(lease.page.close).not.toHaveBeenCalled();
+        await vi.advanceTimersByTimeAsync(1);
+        expect(lease.page.close).toHaveBeenCalled();
+        expect(await manager.listPages({ profileId: 'default' })).toEqual([]);
+    });
+    it('refreshes an idle timeout when a lease is reused', async () => {
+        vi.useFakeTimers();
+        const launched = fakeContext();
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext: vi.fn().mockResolvedValue(launched.context),
+        });
+        const first = await manager.getPage({ profileId: 'default', session: 'work', surface: 'browser', idleTimeout: 25 });
+        await vi.advanceTimersByTimeAsync(20);
+        const second = await manager.getPage({ profileId: 'default', session: 'work', surface: 'browser', idleTimeout: 25 });
+        expect(second.page).toBe(first.page);
+        await vi.advanceTimersByTimeAsync(20);
+        expect(first.page.close).not.toHaveBeenCalled();
+        await vi.advanceTimersByTimeAsync(5);
+        expect(first.page.close).toHaveBeenCalled();
+    });
+    it('does not close persistent site sessions when their idle timeout expires', async () => {
+        vi.useFakeTimers();
+        const launched = fakeContext();
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext: vi.fn().mockResolvedValue(launched.context),
+        });
+        const lease = await manager.getPage({ profileId: 'default', session: 'site:x:uuid', surface: 'adapter', siteSession: 'persistent', idleTimeout: 25 });
+        await vi.advanceTimersByTimeAsync(25);
+        expect(lease.page.close).not.toHaveBeenCalled();
+        expect(await manager.listPages({ profileId: 'default' })).toHaveLength(1);
+    });
+});

package/dist/src/browser/runtime/provider.d.ts

@@ -0,0 +1,9 @@
+import type { BrowserRuntimeCommand, BrowserRuntimeResult, BrowserRuntimeStatus } from '../protocol.js';
+export interface RuntimeStatusOptions {
+    contextId?: string;
+}
+export interface BrowserRuntimeProvider {
+    status(opts?: RuntimeStatusOptions): Promise<BrowserRuntimeStatus>;
+    dispatch(command: BrowserRuntimeCommand): Promise<BrowserRuntimeResult>;
+    shutdown(): Promise<void>;
+}

package/dist/src/browser/runtime/provider.js

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

package/dist/src/browser/runtime/provider.test.d.ts

@@ -0,0 +1,2 @@
+import '../protocol.js';
+import './provider.js';

package/dist/src/browser/runtime/provider.test.js

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import '../protocol.js';
+import './provider.js';
+class EchoProvider {
+    async status() {
+        return {
+            runtimeConnected: true,
+            runtimeName: 'fake',
+            runtimeVersion: 'test',
+            profiles: [{ contextId: 'default', runtimeConnected: true, pending: 0 }],
+            pending: 0,
+        };
+    }
+    async dispatch(command) {
+        return {
+            id: command.id,
+            ok: true,
+            data: { action: command.action, session: command.session },
+            page: command.page ?? 'page-1',
+        };
+    }
+    async shutdown() {
+        return undefined;
+    }
+}
+describe('BrowserRuntimeProvider contract', () => {
+    it('uses runtime-named status fields and the existing result envelope', async () => {
+        const provider = new EchoProvider();
+        await expect(provider.status()).resolves.toMatchObject({
+            runtimeConnected: true,
+            runtimeName: 'fake',
+            profiles: [{ contextId: 'default', runtimeConnected: true }],
+        });
+        await expect(provider.dispatch({
+            id: 'cmd-1',
+            action: 'navigate',
+            session: 'work',
+            surface: 'browser',
+            url: 'https://example.com',
+            contextId: 'default',
+            profileId: 'default',
+        })).resolves.toEqual({
+            id: 'cmd-1',
+            ok: true,
+            data: { action: 'navigate', session: 'work' },
+            page: 'page-1',
+        });
+    });
+});

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/stealth.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Stealth anti-detection module.
+ *
+ * Generates JS code that patches browser globals to hide automation
+ * fingerprints (e.g. navigator.webdriver, missing chrome object, empty
+ * plugin list). Injected before page scripts run so that websites cannot
+ * detect CDP / extension-based control.
+ *
+ * Inspired by puppeteer-extra-plugin-stealth.
+ */
+export declare function generateStealthJs(): string;