publishport-opencli 1.8.4-pp.1

package/dist/src/browser/html-tree.js

@@ -0,0 +1,112 @@
+/**
+ * Client-side HTML → structured tree serializer.
+ *
+ * Returned as a JS string that gets passed to `page.evaluate`. The expression
+ * walks the DOM subtree rooted at the first selector match (or documentElement
+ * when no selector is given) and emits a compact `{tag, attrs, text, children}`
+ * tree for agents to consume instead of re-parsing raw HTML.
+ *
+ * Text handling: `text` is the concatenated text of direct text children only,
+ * whitespace-collapsed. Nested element text is left inside `children[].text`.
+ * Ordering between text and elements is not preserved — agents that need it
+ * should fall back to raw HTML mode.
+ *
+ * Budget knobs let the caller bound the output on large pages — previously an
+ * unscoped `get html --as json` could return a giant tree. Callers set any
+ * combination of `depth` / `childrenMax` / `textMax`; each hit is reported in
+ * the `truncated` envelope so agents know to narrow their selector or raise
+ * the budget.
+ *
+ * Compound controls (date / time / datetime-local / month / week / select /
+ * file) gain a `compound` field so agents inspecting the JSON tree see the
+ * full contract — date format, full option list (up to cap) with selections
+ * preserved for options beyond the cap, file `accept` and `multiple`. Without
+ * this wiring agents repeatedly guess values on these controls from the raw
+ * attributes, which is the failure mode compound.ts was built to eliminate.
+ */
+import { COMPOUND_INFO_JS } from './compound.js';
+/**
+ * Returns a JS expression string. When evaluated in a page context the
+ * expression resolves to either
+ *   `{selector, matched, tree, truncated}` on success, or
+ *   `{selector, invalidSelector: true, reason}` when `querySelectorAll`
+ *   throws a `SyntaxError` for an unparseable selector.
+ *
+ * Callers must branch on `invalidSelector` to convert it into the CLI's
+ * `invalid_selector` structured error; otherwise the browser-level exception
+ * would bubble out of `page.evaluate` and bypass the structured-error
+ * contract that agents rely on.
+ */
+export function buildHtmlTreeJs(opts = {}) {
+    const selectorLiteral = opts.selector ? JSON.stringify(opts.selector) : 'null';
+    const depthLiteral = Number.isFinite(opts.depth) && opts.depth >= 0
+        ? String(opts.depth)
+        : 'null';
+    const childrenMaxLiteral = Number.isFinite(opts.childrenMax) && opts.childrenMax >= 0
+        ? String(opts.childrenMax)
+        : 'null';
+    const textMaxLiteral = Number.isFinite(opts.textMax) && opts.textMax >= 0
+        ? String(opts.textMax)
+        : 'null';
+    return `(() => {
+  ${COMPOUND_INFO_JS}
+  const selector = ${selectorLiteral};
+  const maxDepth = ${depthLiteral};
+  const maxChildren = ${childrenMaxLiteral};
+  const maxText = ${textMaxLiteral};
+  let matches;
+  if (selector) {
+    try { matches = document.querySelectorAll(selector); }
+    catch (e) {
+      return { selector: selector, invalidSelector: true, reason: (e && e.message) || String(e) };
+    }
+  } else {
+    matches = [document.documentElement];
+  }
+  const matched = matches.length;
+  const root = matches[0] || null;
+  const trunc = { depth: false, children_dropped: 0, text_truncated: 0 };
+  function serialize(el, depth) {
+    if (!el || el.nodeType !== 1) return null;
+    const attrs = {};
+    for (const a of el.attributes) attrs[a.name] = a.value;
+    let text = '';
+    for (const n of el.childNodes) {
+      if (n.nodeType === 3) text += n.nodeValue;
+    }
+    text = text.replace(/\\s+/g, ' ').trim();
+    if (maxText !== null && text.length > maxText) {
+      text = text.slice(0, maxText);
+      trunc.text_truncated++;
+    }
+    const children = [];
+    if (maxDepth === null || depth < maxDepth) {
+      const childEls = [];
+      for (const n of el.childNodes) if (n.nodeType === 1) childEls.push(n);
+      const keep = maxChildren === null ? childEls.length : Math.min(childEls.length, maxChildren);
+      for (let i = 0; i < keep; i++) {
+        const child = serialize(childEls[i], depth + 1);
+        if (child) children.push(child);
+      }
+      if (maxChildren !== null && childEls.length > maxChildren) {
+        trunc.children_dropped += childEls.length - maxChildren;
+      }
+    } else {
+      // Budget hit: we're at max depth. Count any element children we would have visited.
+      for (const n of el.childNodes) if (n.nodeType === 1) { trunc.depth = true; break; }
+    }
+    const node = { tag: el.tagName.toLowerCase(), attrs, text, children };
+    const compound = compoundInfoOf(el);
+    if (compound) node.compound = compound;
+    return node;
+  }
+  const tree = root ? serialize(root, 0) : null;
+  const truncatedOut = {};
+  if (trunc.depth) truncatedOut.depth = true;
+  if (trunc.children_dropped > 0) truncatedOut.children_dropped = trunc.children_dropped;
+  if (trunc.text_truncated > 0) truncatedOut.text_truncated = trunc.text_truncated;
+  const envelope = { selector: selector, matched: matched, tree: tree };
+  if (Object.keys(truncatedOut).length > 0) envelope.truncated = truncatedOut;
+  return envelope;
+})()`;
+}

package/dist/src/browser/html-tree.test.d.ts

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

package/dist/src/browser/html-tree.test.js

@@ -0,0 +1,181 @@
+import { describe, expect, it } from 'vitest';
+import { buildHtmlTreeJs } from './html-tree.js';
+/**
+ * The serializer runs in a page context via `page.evaluate`. In unit tests we
+ * substitute `document` with a minimal stub that mirrors the DOM surface used
+ * by the expression, then Function-eval the returned JS.
+ */
+function runTreeJs(root, selectorMatches, selector, budgets = {}) {
+    const js = buildHtmlTreeJs({ selector, ...budgets });
+    const fakeDocument = {
+        querySelectorAll: () => selectorMatches,
+        documentElement: root,
+    };
+    const fn = new Function('document', `return ${js};`);
+    return fn(fakeDocument);
+}
+function runTreeJsInvalid(selector, errorMessage) {
+    const js = buildHtmlTreeJs({ selector });
+    const fakeDocument = {
+        querySelectorAll: () => { const e = new Error(errorMessage); e.name = 'SyntaxError'; throw e; },
+        documentElement: null,
+    };
+    const fn = new Function('document', `return ${js};`);
+    return fn(fakeDocument);
+}
+function el(tag, attrs, children, extras = {}) {
+    return {
+        nodeType: 1,
+        tagName: tag.toUpperCase(),
+        attributes: Object.entries(attrs).map(([name, value]) => ({ name, value })),
+        childNodes: children,
+        getAttribute: (name) => (name in attrs ? attrs[name] : null),
+        value: extras.value,
+        multiple: extras.multiple,
+        files: extras.files,
+        options: extras.options,
+    };
+}
+function txt(value) { return { nodeType: 3, nodeValue: value }; }
+describe('buildHtmlTreeJs', () => {
+    it('serializes a simple element into {tag, attrs, text, children}', () => {
+        const root = el('div', { class: 'hero', id: 'x' }, [txt('Hello')]);
+        const result = runTreeJs(root, [root], null);
+        expect(result.selector).toBeNull();
+        expect(result.matched).toBe(1);
+        expect(result.tree).toEqual({
+            tag: 'div',
+            attrs: { class: 'hero', id: 'x' },
+            text: 'Hello',
+            children: [],
+        });
+    });
+    it('collapses whitespace in direct text content only', () => {
+        const root = el('p', {}, [
+            txt('  line  \n  one  '),
+            el('span', {}, [txt('inner text')]),
+            txt('\tline two\t'),
+        ]);
+        const result = runTreeJs(root, [root], null);
+        expect(result.tree?.text).toBe('line one line two');
+        expect(result.tree?.children[0].text).toBe('inner text');
+    });
+    it('recurses into element children and preserves their attrs', () => {
+        const root = el('ul', { role: 'list' }, [
+            el('li', { 'data-id': '1' }, [txt('first')]),
+            el('li', { 'data-id': '2' }, [txt('second')]),
+        ]);
+        const result = runTreeJs(root, [root], null);
+        expect(result.tree?.children).toHaveLength(2);
+        expect(result.tree?.children[0]).toEqual({
+            tag: 'li',
+            attrs: { 'data-id': '1' },
+            text: 'first',
+            children: [],
+        });
+    });
+    it('returns matched=N and serializes only the first match', () => {
+        const first = el('article', { id: 'a' }, [txt('first')]);
+        const second = el('article', { id: 'b' }, [txt('second')]);
+        const result = runTreeJs(null, [first, second], 'article');
+        expect(result.matched).toBe(2);
+        expect(result.tree?.attrs.id).toBe('a');
+    });
+    it('returns tree=null and matched=0 when selector matches nothing', () => {
+        const result = runTreeJs(null, [], '.nothing');
+        expect(result.matched).toBe(0);
+        expect(result.tree).toBeNull();
+    });
+    it('catches SyntaxError from querySelectorAll and returns {invalidSelector:true, reason}', () => {
+        const result = runTreeJsInvalid('##$@@', "'##$@@' is not a valid selector");
+        expect(result.invalidSelector).toBe(true);
+        expect(result.selector).toBe('##$@@');
+        expect(result.reason).toContain('not a valid selector');
+    });
+    it('omits `truncated` when no budget is hit', () => {
+        const root = el('div', {}, [el('span', {}, [txt('ok')])]);
+        const result = runTreeJs(root, [root], null, { depth: 5, childrenMax: 10, textMax: 100 });
+        expect(result.truncated).toBeUndefined();
+    });
+});
+describe('buildHtmlTreeJs budget knobs', () => {
+    it('caps tree at `depth` and reports truncated.depth', () => {
+        const deep = el('a', {}, [
+            el('b', {}, [
+                el('c', {}, [el('d', {}, [txt('deep')])]),
+            ]),
+        ]);
+        // depth=1 → root + one level of children; grandchildren should be dropped.
+        const result = runTreeJs(deep, [deep], null, { depth: 1 });
+        expect(result.tree?.tag).toBe('a');
+        expect(result.tree?.children).toHaveLength(1);
+        expect(result.tree?.children[0].tag).toBe('b');
+        // The "b" node had element children but we hit the depth budget before
+        // recursing into them — children array is empty, truncated.depth is true.
+        expect(result.tree?.children[0].children).toEqual([]);
+        expect(result.truncated?.depth).toBe(true);
+    });
+    it('depth=0 keeps only the root', () => {
+        const root = el('ul', {}, [
+            el('li', {}, [txt('a')]),
+            el('li', {}, [txt('b')]),
+        ]);
+        const result = runTreeJs(root, [root], null, { depth: 0 });
+        expect(result.tree?.children).toEqual([]);
+        expect(result.truncated?.depth).toBe(true);
+    });
+    it('caps children per node at `childrenMax` and reports children_dropped count', () => {
+        const root = el('ul', {}, [
+            el('li', {}, [txt('1')]),
+            el('li', {}, [txt('2')]),
+            el('li', {}, [txt('3')]),
+            el('li', {}, [txt('4')]),
+            el('li', {}, [txt('5')]),
+        ]);
+        const result = runTreeJs(root, [root], null, { childrenMax: 2 });
+        expect(result.tree?.children).toHaveLength(2);
+        expect(result.truncated?.children_dropped).toBe(3);
+    });
+    it('caps direct text per node at `textMax` and reports text_truncated count', () => {
+        const root = el('p', {}, [
+            txt('a'.repeat(50)),
+            el('span', {}, [txt('b'.repeat(50))]),
+        ]);
+        const result = runTreeJs(root, [root], null, { textMax: 10 });
+        expect(result.tree?.text).toHaveLength(10);
+        expect(result.tree?.children[0].text).toHaveLength(10);
+        expect(result.truncated?.text_truncated).toBe(2);
+    });
+    // Blocker B regression: compound contract must ride along with the
+    // json tree so `browser get html --as json` surfaces the full contract
+    // to agents without an extra round-trip.
+    it('attaches compound info to date/file/select nodes and omits it elsewhere', () => {
+        const date = el('input', { type: 'date', min: '2026-01-01' }, [], { value: '2026-04-21' });
+        const file = el('input', { type: 'file', accept: 'image/*' }, [], { multiple: true, files: [{ name: 'a.png' }] });
+        const sel = el('select', { name: 'country' }, [], {
+            options: [
+                { value: 'us', label: 'United States', selected: true },
+                { value: 'ca', label: 'Canada' },
+            ],
+        });
+        const plain = el('input', { type: 'text' }, [], { value: 'hi' });
+        const root = el('form', {}, [date, file, sel, plain]);
+        const result = runTreeJs(root, [root], null);
+        expect(result.tree?.children[0].compound).toMatchObject({ control: 'date', format: 'YYYY-MM-DD', current: '2026-04-21', min: '2026-01-01' });
+        expect(result.tree?.children[1].compound).toMatchObject({ control: 'file', multiple: true, current: ['a.png'], accept: 'image/*' });
+        expect(result.tree?.children[2].compound).toMatchObject({ control: 'select', multiple: false, current: 'United States' });
+        expect(result.tree?.children[3].compound).toBeUndefined();
+    });
+    it('combines budgets and reports every hit', () => {
+        const root = el('ul', {}, [
+            el('li', {}, [txt('x'.repeat(20)), el('em', {}, [txt('y')])]),
+            el('li', {}, []),
+            el('li', {}, []),
+        ]);
+        const result = runTreeJs(root, [root], null, { depth: 1, childrenMax: 2, textMax: 5 });
+        expect(result.tree?.children).toHaveLength(2);
+        expect(result.truncated?.children_dropped).toBe(1);
+        expect(result.truncated?.text_truncated).toBe(1);
+        expect(result.truncated?.depth).toBe(true);
+    });
+});

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

@@ -0,0 +1,14 @@
+/**
+ * Browser module — public API re-exports.
+ *
+ * This barrel replaces the former monolithic browser.ts.
+ * External code should import from './browser/index.js' (or './browser.js' via Node resolution).
+ */
+export { Page } from './page.js';
+export { BrowserBridge } from './bridge.js';
+export { CDPBridge } from './cdp.js';
+export { getDaemonHealth } from './daemon-client.js';
+export type { DaemonHealth } from './daemon-client.js';
+export { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
+export { generateStealthJs } from './stealth.js';
+export type { DomSnapshotOptions } from './dom-snapshot.js';

package/dist/src/browser/index.js

@@ -0,0 +1,12 @@
+/**
+ * Browser module — public API re-exports.
+ *
+ * This barrel replaces the former monolithic browser.ts.
+ * External code should import from './browser/index.js' (or './browser.js' via Node resolution).
+ */
+export { Page } from './page.js';
+export { BrowserBridge } from './bridge.js';
+export { CDPBridge } from './cdp.js';
+export { getDaemonHealth } from './daemon-client.js';
+export { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
+export { generateStealthJs } from './stealth.js';

package/dist/src/browser/network-cache.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Persistent cache for browser network captures.
+ *
+ * The live capture buffer (JS interceptor / daemon ring) can be cleared
+ * by navigation or lost between CLI invocations. Agents still need
+ * stable references to request bodies after running other commands,
+ * so every `browser network` call snapshots its results to disk.
+ *
+ * Layout: <cacheDir>/browser-network/<session>.json
+ * Entries expire after DEFAULT_TTL_MS (24h).
+ */
+export declare const DEFAULT_TTL_MS: number;
+export interface CachedNetworkEntry {
+    key: string;
+    url: string;
+    method: string;
+    status: number;
+    /** Full body size in chars (may exceed stored body length when truncated). */
+    size: number;
+    ct: string;
+    body: unknown;
+    /**
+     * Truncation signals use snake_case so `--raw` (which emits cache entries
+     * verbatim) matches the agent-facing contract used by list / --detail.
+     */
+    body_truncated?: boolean;
+    body_full_size?: number;
+    timestamp?: number;
+}
+export interface NetworkCacheFile {
+    version: 1;
+    session: string;
+    savedAt: string;
+    entries: CachedNetworkEntry[];
+}
+export declare function getCachePath(session: string, baseDir?: string): string;
+export declare function saveNetworkCache(session: string, entries: CachedNetworkEntry[], baseDir?: string): void;
+export interface LoadOptions {
+    baseDir?: string;
+    ttlMs?: number;
+    now?: number;
+}
+export interface LoadResult {
+    status: 'ok' | 'missing' | 'expired' | 'corrupt';
+    file?: NetworkCacheFile;
+    ageMs?: number;
+}
+export declare function loadNetworkCache(session: string, opts?: LoadOptions): LoadResult;
+export declare function findEntry(file: NetworkCacheFile, key: string): CachedNetworkEntry | null;

package/dist/src/browser/network-cache.js

@@ -0,0 +1,78 @@
+/**
+ * Persistent cache for browser network captures.
+ *
+ * The live capture buffer (JS interceptor / daemon ring) can be cleared
+ * by navigation or lost between CLI invocations. Agents still need
+ * stable references to request bodies after running other commands,
+ * so every `browser network` call snapshots its results to disk.
+ *
+ * Layout: <cacheDir>/browser-network/<session>.json
+ * Entries expire after DEFAULT_TTL_MS (24h).
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+export const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+function getDefaultCacheDir() {
+    return process.env.OPENCLI_CACHE_DIR || path.join(os.homedir(), '.opencli', 'cache');
+}
+export function getCachePath(session, baseDir = getDefaultCacheDir()) {
+    const safe = session.replace(/[^a-zA-Z0-9_-]+/g, '_');
+    return path.join(baseDir, 'browser-network', `${safe}.json`);
+}
+export function saveNetworkCache(session, entries, baseDir) {
+    const target = getCachePath(session, baseDir);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const payload = {
+        version: 1,
+        session,
+        savedAt: new Date().toISOString(),
+        entries,
+    };
+    // 0o600: entries can include auth tokens and PII from captured response
+    // bodies. fchmod before writing also tightens a pre-existing broad file.
+    let fd;
+    try {
+        fd = fs.openSync(target, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC, 0o600);
+        fs.fchmodSync(fd, 0o600);
+        fs.writeFileSync(fd, JSON.stringify(payload), 'utf8');
+    }
+    finally {
+        if (fd !== undefined) {
+            fs.closeSync(fd);
+        }
+    }
+}
+export function loadNetworkCache(session, opts = {}) {
+    const target = getCachePath(session, opts.baseDir);
+    let raw;
+    try {
+        raw = fs.readFileSync(target, 'utf-8');
+    }
+    catch {
+        return { status: 'missing' };
+    }
+    let parsed;
+    try {
+        const obj = JSON.parse(raw);
+        if (!obj || obj.version !== 1 || !Array.isArray(obj.entries)) {
+            return { status: 'corrupt' };
+        }
+        parsed = obj;
+    }
+    catch {
+        return { status: 'corrupt' };
+    }
+    const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+    const now = opts.now ?? Date.now();
+    const savedAt = Date.parse(parsed.savedAt);
+    if (!Number.isFinite(savedAt))
+        return { status: 'corrupt' };
+    const ageMs = now - savedAt;
+    if (ageMs > ttl)
+        return { status: 'expired', file: parsed, ageMs };
+    return { status: 'ok', file: parsed, ageMs };
+}
+export function findEntry(file, key) {
+    return file.entries.find((e) => e.key === key) ?? null;
+}

package/dist/src/browser/network-cache.test.d.ts

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

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

@@ -0,0 +1,75 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { DEFAULT_TTL_MS, findEntry, getCachePath, loadNetworkCache, saveNetworkCache, } from './network-cache.js';
+function makeEntry(key, body = { ok: true }) {
+    return { key, url: `https://x.com/${key}`, method: 'GET', status: 200, size: 2, ct: 'application/json', body };
+}
+describe('network-cache', () => {
+    let baseDir;
+    beforeEach(() => {
+        baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-netcache-'));
+    });
+    afterEach(() => {
+        fs.rmSync(baseDir, { recursive: true, force: true });
+    });
+    it('sanitizes session names into safe filenames', () => {
+        const p = getCachePath('twitter/agent 1', baseDir);
+        expect(path.basename(p)).toBe('twitter_agent_1.json');
+    });
+    it('round-trips entries through save + load', () => {
+        saveNetworkCache('ws', [makeEntry('UserTweets'), makeEntry('UserByScreenName')], baseDir);
+        const res = loadNetworkCache('ws', { baseDir });
+        expect(res.status).toBe('ok');
+        expect(res.file?.entries).toHaveLength(2);
+        expect(res.file?.entries[0].key).toBe('UserTweets');
+    });
+    it('reports missing when cache file does not exist', () => {
+        expect(loadNetworkCache('nope', { baseDir }).status).toBe('missing');
+    });
+    it('reports expired when the cache is older than ttl', () => {
+        saveNetworkCache('ws', [makeEntry('A')], baseDir);
+        const future = Date.now() + DEFAULT_TTL_MS + 60_000;
+        const res = loadNetworkCache('ws', { baseDir, now: future });
+        expect(res.status).toBe('expired');
+        expect(res.file?.entries).toHaveLength(1);
+    });
+    it('reports corrupt for malformed json', () => {
+        const file = getCachePath('ws', baseDir);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, '{not json');
+        expect(loadNetworkCache('ws', { baseDir }).status).toBe('corrupt');
+    });
+    it('reports corrupt for wrong schema version', () => {
+        const file = getCachePath('ws', baseDir);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ version: 0, entries: [] }));
+        expect(loadNetworkCache('ws', { baseDir }).status).toBe('corrupt');
+    });
+    it('findEntry returns matching entry or null', () => {
+        const file = {
+            version: 1, session: 'ws', savedAt: new Date().toISOString(),
+            entries: [makeEntry('A'), makeEntry('B')],
+        };
+        expect(findEntry(file, 'B')?.key).toBe('B');
+        expect(findEntry(file, 'missing')).toBeNull();
+    });
+    it.skipIf(process.platform === 'win32')('writes the cache file with 0o600 owner-only permissions', () => {
+        saveNetworkCache('ws', [makeEntry('UserTweets')], baseDir);
+        const target = getCachePath('ws', baseDir);
+        const mode = fs.statSync(target).mode & 0o777;
+        expect(mode).toBe(0o600);
+    });
+    it.skipIf(process.platform === 'win32')('tightens an existing cache file before rewriting it', () => {
+        const target = getCachePath('ws', baseDir);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, '{"version":1,"session":"ws","savedAt":"old","entries":[]}', { mode: 0o644 });
+        saveNetworkCache('ws', [makeEntry('UserTweets')], baseDir);
+        const mode = fs.statSync(target).mode & 0o777;
+        expect(mode).toBe(0o600);
+        const reloaded = loadNetworkCache('ws', { baseDir });
+        expect(reloaded.status).toBe('ok');
+        expect(reloaded.file?.entries[0].key).toBe('UserTweets');
+    });
+});

package/dist/src/browser/network-key.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Stable keys for network capture entries.
+ *
+ * Agents reference entries by key (e.g. `UserTweets`, `GET api.x.com/1.1/home`)
+ * instead of array index, so the mapping survives new captures.
+ *
+ * Rules:
+ *   GraphQL (URL contains `/graphql/`): key = operationName derived from URL path
+ *                                       (the segment after a 22-char query id, or the last segment)
+ *   Everything else: key = `METHOD host+pathname`
+ *
+ * On collision assignKeys suffixes duplicates as `base#2`, `base#3`, ... —
+ * the first occurrence stays bare (there is no `#1`).
+ */
+export interface KeyableRequest {
+    url: string;
+    method: string;
+}
+export declare function deriveKey(req: KeyableRequest): string;
+export declare function assignKeys<T extends KeyableRequest>(requests: T[]): Array<T & {
+    key: string;
+}>;

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

@@ -0,0 +1,66 @@
+/**
+ * Stable keys for network capture entries.
+ *
+ * Agents reference entries by key (e.g. `UserTweets`, `GET api.x.com/1.1/home`)
+ * instead of array index, so the mapping survives new captures.
+ *
+ * Rules:
+ *   GraphQL (URL contains `/graphql/`): key = operationName derived from URL path
+ *                                       (the segment after a 22-char query id, or the last segment)
+ *   Everything else: key = `METHOD host+pathname`
+ *
+ * On collision assignKeys suffixes duplicates as `base#2`, `base#3`, ... —
+ * the first occurrence stays bare (there is no `#1`).
+ */
+export function deriveKey(req) {
+    const parsed = safeParseUrl(req.url);
+    if (!parsed)
+        return `${req.method.toUpperCase()} ${truncate(req.url, 120)}`;
+    const path = parsed.pathname;
+    if (path.includes('/graphql/')) {
+        const op = graphqlOperationName(path);
+        if (op)
+            return op;
+    }
+    return `${req.method.toUpperCase()} ${parsed.host}${path}`;
+}
+export function assignKeys(requests) {
+    const counts = new Map();
+    const out = [];
+    for (const req of requests) {
+        const base = deriveKey(req);
+        const n = counts.get(base) ?? 0;
+        counts.set(base, n + 1);
+        const key = n === 0 ? base : `${base}#${n + 1}`;
+        out.push({ ...req, key });
+    }
+    return out;
+}
+function graphqlOperationName(pathname) {
+    // Patterns we've seen in the wild:
+    //   /i/api/graphql/<queryId>/UserTweets
+    //   /graphql/<queryId>/SomeOp
+    //   /graphql/SomeOp                       (rare, no id)
+    const segments = pathname.split('/').filter(Boolean);
+    const idx = segments.indexOf('graphql');
+    if (idx < 0)
+        return null;
+    const tail = segments.slice(idx + 1);
+    if (tail.length === 0)
+        return null;
+    if (tail.length === 1)
+        return tail[0];
+    // tail[0] is usually a query id; the operation name is the next segment.
+    return tail[1] || tail[0];
+}
+function safeParseUrl(url) {
+    try {
+        return new URL(url);
+    }
+    catch {
+        return null;
+    }
+}
+function truncate(s, max) {
+    return s.length <= max ? s : `${s.slice(0, max - 1)}…`;
+}

package/dist/src/browser/network-key.test.d.ts

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