@jackwener/opencli 1.7.13 → 1.7.15

package/clis/twitter/unretweet.js

@@ -0,0 +1,94 @@
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { parseTweetUrl, buildTwitterArticleScopeSource } from './shared.js';
+
+cli({
+    site: 'twitter',
+    name: 'unretweet',
+    access: 'write',
+    description: 'Undo a retweet on a specific tweet',
+    domain: 'x.com',
+    strategy: Strategy.UI,
+    browser: true,
+    args: [
+        { name: 'url', type: 'string', required: true, positional: true, help: 'The URL of the tweet to unretweet' },
+    ],
+    columns: ['status', 'message'],
+    func: async (page, kwargs) => {
+        if (!page)
+            throw new CommandExecutionError('Browser session required for twitter unretweet');
+        const target = parseTweetUrl(kwargs.url);
+        await page.goto(target.url);
+        await page.wait({ selector: '[data-testid="primaryColumn"]' });
+        const result = await page.evaluate(`(async () => {
+        try {
+            ${buildTwitterArticleScopeSource(target.id)}
+            // Poll for the tweet to render. State probes scoped to the article
+            // matching the requested status id — bare querySelector on a
+            // conversation page would silently grab the first article (e.g.
+            // the parent tweet) and unretweet the wrong one.
+            let attempts = 0;
+            let retweetBtn = null;
+            let unretweetBtn = null;
+            let targetArticle = null;
+
+            while (attempts < 20) {
+                targetArticle = findTargetArticle();
+                retweetBtn = targetArticle?.querySelector('[data-testid="retweet"]') || null;
+                unretweetBtn = targetArticle?.querySelector('[data-testid="unretweet"]') || null;
+
+                if (retweetBtn || unretweetBtn) break;
+
+                await new Promise(r => setTimeout(r, 500));
+                attempts++;
+            }
+
+            // Already not retweeted: idempotent success
+            if (retweetBtn) {
+                return { ok: true, message: 'Tweet is not retweeted (already removed).' };
+            }
+
+            if (!unretweetBtn) {
+                return { ok: false, message: 'Could not find the Unretweet button on this tweet after waiting 10 seconds. Are you logged in?' };
+            }
+
+            // Step 1: click Unretweet button → opens menu
+            unretweetBtn.click();
+
+            // Step 2: wait for and click the confirm menu item. The confirm
+            // popover renders at the document root, not inside the article,
+            // so this lookup is intentionally document-scoped.
+            let confirmBtn = null;
+            for (let i = 0; i < 20; i++) {
+                await new Promise(r => setTimeout(r, 250));
+                confirmBtn = document.querySelector('[data-testid="unretweetConfirm"]');
+                if (confirmBtn) break;
+            }
+            if (!confirmBtn) {
+                return { ok: false, message: 'Unretweet menu opened but the confirm option did not appear.' };
+            }
+            confirmBtn.click();
+            await new Promise(r => setTimeout(r, 1000));
+
+            // Verify success by checking if the 'retweet' button reappeared
+            const verifyArticle = findTargetArticle() || targetArticle;
+            const verifyBtn = verifyArticle?.querySelector('[data-testid="retweet"]');
+            if (verifyBtn) {
+                return { ok: true, message: 'Tweet successfully unretweeted.' };
+            } else {
+                return { ok: false, message: 'Unretweet action was initiated but UI did not update as expected.' };
+            }
+        } catch (e) {
+            return { ok: false, message: e.toString() };
+        }
+    })()`);
+        if (result.ok) {
+            // Wait for the unretweet network request to be processed
+            await page.wait(2);
+        }
+        return [{
+                status: result.ok ? 'success' : 'failed',
+                message: result.message
+            }];
+    }
+});

package/clis/twitter/unretweet.test.js

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './unretweet.js';
+import { createPageMock } from '../test-utils.js';
+
+describe('twitter unretweet command', () => {
+    it('clicks the unretweet button then the confirm menu item and reports success', async () => {
+        const cmd = getRegistry().get('twitter/unretweet');
+        expect(cmd?.func).toBeTypeOf('function');
+        const page = createPageMock([
+            { ok: true, message: 'Tweet successfully unretweeted.' },
+        ]);
+        const result = await cmd.func(page, {
+            url: 'https://x.com/alice/status/2040254679301718161',
+        });
+        expect(page.goto).toHaveBeenCalledWith('https://x.com/alice/status/2040254679301718161');
+        expect(page.wait).toHaveBeenNthCalledWith(1, { selector: '[data-testid="primaryColumn"]' });
+        expect(page.wait).toHaveBeenNthCalledWith(2, 2);
+        const script = page.evaluate.mock.calls[0][0];
+        // Two-step UI flow must be present:
+        //   1) click the unretweet button
+        //   2) wait for and click the confirm menu item (data-testid="unretweetConfirm")
+        expect(script).toContain('unretweetBtn.click()');
+        expect(script).toContain("document.querySelector('[data-testid=\"unretweetConfirm\"]')");
+        expect(script).toContain('confirmBtn.click()');
+        // Article scoping comes from the shared helper (buildTwitterArticleScopeSource):
+        // emits __twHasLinkToTarget + __twGetStatusIdFromHref + the anchored
+        // tweet-path regex. JSDOM-level coverage lives in shared.test.js.
+        expect(script).toContain('__twHasLinkToTarget');
+        expect(script).toContain('__twGetStatusIdFromHref');
+        expect(script).toContain("document.querySelectorAll('article')");
+        expect(script).toContain("targetArticle?.querySelector('[data-testid=\"unretweet\"]')");
+        // Idempotency probe: when already not retweeted ([data-testid="retweet"] present),
+        // the script returns ok:true with an "already removed" message.
+        expect(script).toContain("targetArticle?.querySelector('[data-testid=\"retweet\"]')");
+        expect(result).toEqual([
+            { status: 'success', message: 'Tweet successfully unretweeted.' },
+        ]);
+    });
+
+    it('returns a failed row when the confirm menu item never appears', async () => {
+        const cmd = getRegistry().get('twitter/unretweet');
+        expect(cmd?.func).toBeTypeOf('function');
+        const page = createPageMock([
+            { ok: false, message: 'Unretweet menu opened but the confirm option did not appear.' },
+        ]);
+        const result = await cmd.func(page, {
+            url: 'https://x.com/alice/status/2040254679301718161',
+        });
+        expect(result).toEqual([
+            { status: 'failed', message: 'Unretweet menu opened but the confirm option did not appear.' },
+        ]);
+        expect(page.wait).toHaveBeenCalledTimes(1);
+    });
+
+    it('throws CommandExecutionError when no page is provided', async () => {
+        const cmd = getRegistry().get('twitter/unretweet');
+        await expect(cmd.func(undefined, {
+            url: 'https://x.com/alice/status/2040254679301718161',
+        })).rejects.toThrow(CommandExecutionError);
+    });
+
+    it('rejects invalid tweet URLs before navigation', async () => {
+        const cmd = getRegistry().get('twitter/unretweet');
+        const page = createPageMock([]);
+        await expect(cmd.func(page, {
+            url: 'http://x.com/alice/status/2040254679301718161',
+        })).rejects.toThrow(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+});

package/clis/twitter/utils.js

@@ -0,0 +1,286 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { ArgumentError } from '@jackwener/opencli/errors';
+
+/**
+ * Public read-only Twitter web bearer token used by the GraphQL endpoints we
+ * call from the page context. This is the same token the Twitter web app
+ * itself uses; centralising it here keeps the 12+ GraphQL adapters from
+ * drifting when X rotates the value.
+ */
+export const TWITTER_BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
+
+/** File-input selector used by the X /compose/post route for both posts and replies. */
+export const COMPOSER_FILE_INPUT_SELECTOR = 'input[type="file"][data-testid="fileInput"]';
+
+/** Image formats the X composer accepts. */
+export const SUPPORTED_IMAGE_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp']);
+
+/** 20 MB hard cap. Twitter allows ~5MB images / 15MB GIFs; 20MB is a safety net. */
+export const MAX_IMAGE_SIZE_BYTES = 20 * 1024 * 1024;
+
+const CONTENT_TYPE_TO_EXTENSION = {
+    'image/jpeg': '.jpg',
+    'image/jpg': '.jpg',
+    'image/png': '.png',
+    'image/gif': '.gif',
+    'image/webp': '.webp',
+};
+
+/**
+ * Validate a single image path. Throws {@link ArgumentError} on bad input
+ * (typed input failure surfaces before any browser interaction).
+ *
+ * @param {string} imagePath - Local filesystem path, may be relative.
+ * @returns {string} Absolute resolved path.
+ */
+export function resolveImagePath(imagePath) {
+    const absPath = path.resolve(imagePath);
+    if (!fs.existsSync(absPath)) {
+        throw new ArgumentError(`Image file not found: ${absPath}`);
+    }
+    const ext = path.extname(absPath).toLowerCase();
+    if (!SUPPORTED_IMAGE_EXTENSIONS.has(ext)) {
+        throw new ArgumentError(`Unsupported image format "${ext}". Supported: jpg, jpeg, png, gif, webp`);
+    }
+    const stat = fs.statSync(absPath);
+    if (stat.size > MAX_IMAGE_SIZE_BYTES) {
+        throw new ArgumentError(`Image too large: ${(stat.size / 1024 / 1024).toFixed(1)} MB (max ${MAX_IMAGE_SIZE_BYTES / 1024 / 1024} MB)`);
+    }
+    return absPath;
+}
+
+/**
+ * Resolve the file extension to use when persisting a remote image: prefer
+ * Content-Type, fall back to URL pathname.
+ */
+export function resolveImageExtension(url, contentType) {
+    const normalizedContentType = (contentType || '').split(';')[0].trim().toLowerCase();
+    if (normalizedContentType && CONTENT_TYPE_TO_EXTENSION[normalizedContentType]) {
+        return CONTENT_TYPE_TO_EXTENSION[normalizedContentType];
+    }
+    try {
+        const pathname = new URL(url).pathname;
+        const ext = path.extname(pathname).toLowerCase();
+        if (SUPPORTED_IMAGE_EXTENSIONS.has(ext))
+            return ext;
+    } catch {
+        // Fall through to the final error below.
+    }
+    throw new ArgumentError(
+        `Unsupported remote image format "${normalizedContentType || 'unknown'}". Supported: jpg, jpeg, png, gif, webp`,
+    );
+}
+
+/**
+ * Download a remote image to a per-call tmp directory. Returns the absolute
+ * path on success. Caller owns the tmp dir and must clean it up. Throws
+ * {@link ArgumentError} on bad input or download failure.
+ *
+ * @returns {Promise<{ absPath: string, cleanupDir: string }>}
+ */
+export async function downloadRemoteImage(imageUrl) {
+    let parsed;
+    try {
+        parsed = new URL(imageUrl);
+    } catch {
+        throw new ArgumentError(`Invalid image URL: ${imageUrl}`);
+    }
+    if (!/^https?:$/.test(parsed.protocol)) {
+        throw new ArgumentError(`Unsupported image URL protocol: ${parsed.protocol}`);
+    }
+    const response = await fetch(imageUrl);
+    if (!response.ok) {
+        throw new ArgumentError(`Image download failed: HTTP ${response.status}`);
+    }
+    const contentLength = Number(response.headers.get('content-length') || '0');
+    if (contentLength > MAX_IMAGE_SIZE_BYTES) {
+        throw new ArgumentError(`Image too large: ${(contentLength / 1024 / 1024).toFixed(1)} MB (max ${MAX_IMAGE_SIZE_BYTES / 1024 / 1024} MB)`);
+    }
+    const ext = resolveImageExtension(imageUrl, response.headers.get('content-type'));
+    const cleanupDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-twitter-'));
+    const absPath = path.join(cleanupDir, `image${ext}`);
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (buffer.byteLength > MAX_IMAGE_SIZE_BYTES) {
+        fs.rmSync(cleanupDir, { recursive: true, force: true });
+        throw new ArgumentError(`Image too large: ${(buffer.byteLength / 1024 / 1024).toFixed(1)} MB (max ${MAX_IMAGE_SIZE_BYTES / 1024 / 1024} MB)`);
+    }
+    fs.writeFileSync(absPath, buffer);
+    return { absPath, cleanupDir };
+}
+
+/**
+ * Attach a single image to the current /compose/post composer. Tries the
+ * native CDP file-input bridge first; falls back to a base64 DataTransfer
+ * shim if the bridge is missing or rejects with "Unknown action" /
+ * "not supported". Throws on hard failures.
+ *
+ * After upload it polls the DOM briefly to confirm the preview thumbnail
+ * actually rendered — without this, a 200 from setFileInput could mask a
+ * silent-no-attachment post.
+ *
+ * @param {object} page - OpenCLI page handle.
+ * @param {string} absImagePath - Already-validated absolute path.
+ * @param {string} [fileInputSelector] - Override (post.js historically used
+ *   the same selector; default matches the X composer route).
+ */
+export async function attachComposerImage(page, absImagePath, fileInputSelector = COMPOSER_FILE_INPUT_SELECTOR) {
+    let uploaded = false;
+    if (page.setFileInput) {
+        try {
+            await page.setFileInput([absImagePath], fileInputSelector);
+            uploaded = true;
+        } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!msg.includes('Unknown action') && !msg.includes('not supported')) {
+                throw new Error(`Image upload failed: ${msg}`);
+            }
+            // setFileInput not supported by extension — fall through to base64 fallback.
+        }
+    }
+    if (!uploaded) {
+        const ext = path.extname(absImagePath).toLowerCase();
+        const mimeType = ext === '.png'
+            ? 'image/png'
+            : ext === '.gif'
+                ? 'image/gif'
+                : ext === '.webp'
+                    ? 'image/webp'
+                    : 'image/jpeg';
+        const base64 = fs.readFileSync(absImagePath).toString('base64');
+        if (base64.length > 500_000) {
+            console.warn(`[warn] Image base64 payload is ${(base64.length / 1024 / 1024).toFixed(1)}MB. ` +
+                'This may fail with the browser bridge. Update the extension to v1.6+ for CDP-based upload, ' +
+                'or compress the image before attaching.');
+        }
+        const upload = await page.evaluate(`
+      (() => {
+        const input = document.querySelector(${JSON.stringify(fileInputSelector)});
+        if (!input) return { ok: false, error: 'No file input found on page' };
+
+        const binary = atob(${JSON.stringify(base64)});
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+
+        const dt = new DataTransfer();
+        const blob = new Blob([bytes], { type: ${JSON.stringify(mimeType)} });
+        dt.items.add(new File([blob], ${JSON.stringify(path.basename(absImagePath))}, { type: ${JSON.stringify(mimeType)} }));
+
+        Object.defineProperty(input, 'files', { value: dt.files, writable: false });
+        input.dispatchEvent(new Event('change', { bubbles: true }));
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+        return { ok: true };
+      })()
+    `);
+        if (!upload?.ok) {
+            throw new Error(`Image upload failed: ${upload?.error ?? 'unknown error'}`);
+        }
+    }
+    await page.wait(2);
+    const uploadState = await page.evaluate(`
+    (() => {
+      const previewCount = document.querySelectorAll(
+        '[data-testid="attachments"] img, [data-testid="attachments"] video, [data-testid="tweetPhoto"]'
+      ).length;
+      const hasMedia = previewCount > 0
+        || !!document.querySelector('[data-testid="attachments"]')
+        || !!Array.from(document.querySelectorAll('button,[role="button"]')).find((el) =>
+          /remove media|remove image|remove/i.test((el.getAttribute('aria-label') || '') + ' ' + (el.textContent || ''))
+        );
+      return { ok: hasMedia, previewCount };
+    })()
+  `);
+    if (!uploadState?.ok) {
+        throw new Error('Image upload failed: preview did not appear.');
+    }
+}
+
+// ── Engagement scoring (P3) ────────────────────────────────────────────
+//
+// Used by tweet-shaped read commands (search / timeline / likes / bookmarks /
+// list-tweets / tweets / thread). Lets callers ask for the top-N tweets by
+// weighted engagement instead of chronological order, so an agent skimming a
+// noisy timeline can surface the actually-interesting tweets first.
+//
+// The weights bias toward "active engagement": bookmarks > retweets > replies
+// > likes > views. Views are log-dampened because they often dwarf all other
+// signals by 2–4 orders of magnitude on viral tweets and would otherwise
+// drown out the active signals.
+//
+// Pure synchronous — exported via __test__ for unit coverage. Missing fields
+// (some adapters don't surface views/replies/bookmarks) coerce to 0 so the
+// formula stays well-defined across every read command's row shape.
+
+const ENGAGEMENT_WEIGHTS = Object.freeze({
+    likes: 1,
+    retweets: 3,
+    replies: 2,
+    bookmarks: 5,
+    viewsLog: 0.5,
+});
+
+/**
+ * Compute the weighted engagement score for a tweet-shaped row.
+ *
+ * Formula: likes×1 + retweets×3 + replies×2 + bookmarks×5 + log10(views+1)×0.5
+ *
+ * - String fields (e.g. views: '12345') are coerced via Number(); non-numeric
+ *   strings become 0 instead of NaN-poisoning the score.
+ * - log10(views+1) so views=0 maps to 0 (not -Infinity).
+ * - Missing fields default to 0 — search returns no `replies`/`bookmarks`,
+ *   bookmarks returns no `views`/`replies`, etc.
+ *
+ * @param {Record<string, unknown>} row
+ * @returns {number} Score, rounded to 2 decimals for stable test fixtures.
+ */
+export function computeEngagementScore(row) {
+    if (!row || typeof row !== 'object') return 0;
+    const num = (key) => {
+        const raw = row[key];
+        if (raw === undefined || raw === null) return 0;
+        const n = Number(raw);
+        return Number.isFinite(n) ? Math.max(0, n) : 0;
+    };
+    const score
+        = num('likes') * ENGAGEMENT_WEIGHTS.likes
+        + num('retweets') * ENGAGEMENT_WEIGHTS.retweets
+        + num('replies') * ENGAGEMENT_WEIGHTS.replies
+        + num('bookmarks') * ENGAGEMENT_WEIGHTS.bookmarks
+        + Math.log10(num('views') + 1) * ENGAGEMENT_WEIGHTS.viewsLog;
+    return Math.round(score * 100) / 100;
+}
+
+/**
+ * Apply --top-by-engagement post-processing. When `topN > 0` the rows are
+ * sorted DESCENDING by computeEngagementScore() and trimmed to the top N.
+ * When `topN <= 0` (the default), rows are returned unchanged so adapters
+ * that don't pass the flag stay backward compatible.
+ *
+ * Stable for ties: rows with the same score retain their original order
+ * (Array.prototype.sort is guaranteed stable in V8 since 2018).
+ *
+ * @param {Array<Record<string, unknown>>} rows
+ * @param {number} topN
+ * @returns {Array<Record<string, unknown>>}
+ */
+export function applyTopByEngagement(rows, topN) {
+    if (!Array.isArray(rows) || rows.length === 0) return rows;
+    const n = Number(topN);
+    if (!Number.isFinite(n) || n <= 0) return rows;
+    return rows
+        .map((row, idx) => ({ row, idx, score: computeEngagementScore(row) }))
+        .sort((a, b) => b.score - a.score || a.idx - b.idx)
+        .slice(0, Math.floor(n))
+        .map(entry => entry.row);
+}
+
+export const __test__ = {
+    resolveImagePath,
+    resolveImageExtension,
+    downloadRemoteImage,
+    attachComposerImage,
+    computeEngagementScore,
+    applyTopByEngagement,
+    ENGAGEMENT_WEIGHTS,
+};

package/clis/twitter/utils.test.js

@@ -0,0 +1,169 @@
+import { describe, expect, it } from 'vitest';
+import { __test__ } from './utils.js';
+
+const { computeEngagementScore, applyTopByEngagement, ENGAGEMENT_WEIGHTS } = __test__;
+
+describe('computeEngagementScore', () => {
+    it('returns 0 for empty / nullish rows', () => {
+        expect(computeEngagementScore(null)).toBe(0);
+        expect(computeEngagementScore(undefined)).toBe(0);
+        expect(computeEngagementScore({})).toBe(0);
+    });
+
+    it('weights likes ×1', () => {
+        expect(computeEngagementScore({ likes: 10 })).toBe(10);
+    });
+
+    it('weights retweets ×3', () => {
+        expect(computeEngagementScore({ retweets: 5 })).toBe(15);
+    });
+
+    it('weights replies ×2', () => {
+        expect(computeEngagementScore({ replies: 4 })).toBe(8);
+    });
+
+    it('weights bookmarks ×5', () => {
+        expect(computeEngagementScore({ bookmarks: 6 })).toBe(30);
+    });
+
+    it('log-dampens views (log10(v+1) × 0.5)', () => {
+        // log10(99+1) * 0.5 = 1.0
+        expect(computeEngagementScore({ views: 99 })).toBeCloseTo(1.0, 2);
+        // log10(0+1) * 0.5 = 0
+        expect(computeEngagementScore({ views: 0 })).toBe(0);
+    });
+
+    it('coerces string-typed views (search/timeline returns views as a string)', () => {
+        // log10(9999+1) * 0.5 = 2.0
+        expect(computeEngagementScore({ views: '9999' })).toBeCloseTo(2.0, 2);
+    });
+
+    it('treats non-numeric strings as 0 instead of NaN-poisoning the score', () => {
+        expect(computeEngagementScore({ likes: 'abc', retweets: 5 })).toBe(15);
+    });
+
+    it('clamps negative values at 0 (defensive against bogus payloads)', () => {
+        expect(computeEngagementScore({ likes: -100, retweets: 2 })).toBe(6);
+    });
+
+    it('combines all signals additively', () => {
+        // likes×1 + retweets×3 + replies×2 + bookmarks×5 + log10(views+1)×0.5
+        // 10 + 30 + 8 + 25 + log10(1000)*0.5 = 73 + 1.5 = 74.5
+        const row = { likes: 10, retweets: 10, replies: 4, bookmarks: 5, views: 999 };
+        expect(computeEngagementScore(row)).toBeCloseTo(74.5, 2);
+    });
+
+    it('rounds to 2 decimal places for stable test fixtures', () => {
+        // log10(1+1) * 0.5 = 0.5 * log10(2) ≈ 0.150515
+        const score = computeEngagementScore({ views: 1 });
+        expect(score).toBe(0.15);
+    });
+
+    it('handles real search-row shape (no replies/bookmarks columns)', () => {
+        const searchRow = {
+            id: '123',
+            author: 'alice',
+            text: 'hi',
+            likes: 100,
+            views: '9999',
+        };
+        // 100 + log10(10000)*0.5 = 100 + 2.0 = 102.0
+        expect(computeEngagementScore(searchRow)).toBeCloseTo(102.0, 2);
+    });
+
+    it('handles real bookmarks-row shape (no views/replies columns)', () => {
+        const bookmarkRow = {
+            id: '123',
+            author: 'alice',
+            text: 'hi',
+            likes: 50,
+            retweets: 10,
+            bookmarks: 3,
+        };
+        // 50 + 30 + 15 = 95
+        expect(computeEngagementScore(bookmarkRow)).toBe(95);
+    });
+
+    it('exposes the documented weight table', () => {
+        expect(ENGAGEMENT_WEIGHTS).toEqual({
+            likes: 1,
+            retweets: 3,
+            replies: 2,
+            bookmarks: 5,
+            viewsLog: 0.5,
+        });
+    });
+});
+
+describe('applyTopByEngagement', () => {
+    const rows = [
+        { id: 'a', likes: 10 },
+        { id: 'b', likes: 50 },
+        { id: 'c', likes: 30 },
+        { id: 'd', likes: 100 },
+        { id: 'e', likes: 5 },
+    ];
+
+    it('returns rows unchanged when topN is 0 (default)', () => {
+        expect(applyTopByEngagement(rows, 0)).toBe(rows);
+    });
+
+    it('returns rows unchanged when topN is negative', () => {
+        expect(applyTopByEngagement(rows, -3)).toBe(rows);
+    });
+
+    it('returns rows unchanged when topN is non-numeric', () => {
+        expect(applyTopByEngagement(rows, 'foo')).toBe(rows);
+        expect(applyTopByEngagement(rows, null)).toBe(rows);
+        expect(applyTopByEngagement(rows, undefined)).toBe(rows);
+    });
+
+    it('sorts descending by score and trims to top N when topN > 0', () => {
+        const result = applyTopByEngagement(rows, 3);
+        expect(result.map(r => r.id)).toEqual(['d', 'b', 'c']);
+    });
+
+    it('returns all rows when topN exceeds row count', () => {
+        const result = applyTopByEngagement(rows, 99);
+        expect(result.map(r => r.id)).toEqual(['d', 'b', 'c', 'a', 'e']);
+    });
+
+    it('floors fractional topN', () => {
+        const result = applyTopByEngagement(rows, 2.9);
+        expect(result.map(r => r.id)).toEqual(['d', 'b']);
+    });
+
+    it('is stable for ties (preserves original order)', () => {
+        const tieRows = [
+            { id: 'first', likes: 10 },
+            { id: 'second', likes: 10 },
+            { id: 'third', likes: 10 },
+            { id: 'fourth', likes: 100 },
+        ];
+        const result = applyTopByEngagement(tieRows, 4);
+        // 'fourth' first, then ties retain original order
+        expect(result.map(r => r.id)).toEqual(['fourth', 'first', 'second', 'third']);
+    });
+
+    it('handles empty / non-array input gracefully', () => {
+        expect(applyTopByEngagement([], 5)).toEqual([]);
+        expect(applyTopByEngagement(null, 5)).toBeNull();
+        expect(applyTopByEngagement(undefined, 5)).toBeUndefined();
+    });
+
+    it('does not mutate the input array', () => {
+        const before = [...rows];
+        applyTopByEngagement(rows, 2);
+        expect(rows).toEqual(before);
+    });
+
+    it('mixes signals correctly when ranking', () => {
+        // bookmark-heavy row should beat like-heavy row even if likes are higher
+        const mixed = [
+            { id: 'likes-only', likes: 100 },           // score = 100
+            { id: 'bookmark-heavy', likes: 30, bookmarks: 20 }, // score = 30 + 100 = 130
+        ];
+        const result = applyTopByEngagement(mixed, 2);
+        expect(result.map(r => r.id)).toEqual(['bookmark-heavy', 'likes-only']);
+    });
+});

package/dist/src/browser/ax-snapshot.d.ts

@@ -0,0 +1,37 @@
+/**
+ * AX-backed browser snapshot prototype.
+ *
+ * This is intentionally additive to the current DOM snapshot. It learns from
+ * agent-browser's accessibility-tree refs without changing default `state`
+ * output until the AX path proves itself on fixtures and real SaaS workflows.
+ */
+export interface BrowserRef {
+    ref: string;
+    backendNodeId?: number;
+    role: string;
+    name: string;
+    nth?: number;
+    frame?: {
+        frameId?: string;
+        sessionId?: string;
+        url?: string;
+        targetUrl?: string;
+    };
+}
+export interface AxSnapshotTree {
+    tree: unknown;
+    frame?: BrowserRef['frame'];
+}
+export interface AxSnapshotBuildResult {
+    text: string;
+    refs: Map<string, BrowserRef>;
+}
+export declare function buildAxSnapshot(axTree: unknown, opts?: {
+    maxDepth?: number;
+    interactiveOnly?: boolean;
+}): AxSnapshotBuildResult;
+export declare function buildAxSnapshotFromTrees(trees: AxSnapshotTree[], opts?: {
+    maxDepth?: number;
+    interactiveOnly?: boolean;
+}): AxSnapshotBuildResult;
+export declare function findAxRefReplacement(axTree: unknown, ref: BrowserRef): BrowserRef | null;