@jackwener/opencli 1.7.3 → 1.7.5

package/clis/eastmoney/rank.js

@@ -0,0 +1,94 @@
+// eastmoney rank — market mover list across common segments.
+//
+// Data source: push2.eastmoney.com/api/qt/clist/get (Tier 1 public JSON).
+//   opencli eastmoney rank
+//   opencli eastmoney rank --market cyb --sort turnover --limit 30
+
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CliError } from '@jackwener/opencli/errors';
+
+const MARKETS = {
+  'hs-a':   'm:0+t:6,m:0+t:80,m:1+t:2,m:1+t:23,m:0+t:81+s:2048', // 沪深 A
+  'sh-a':   'm:1+t:2,m:1+t:23',                                   // 沪 A
+  'sz-a':   'm:0+t:6,m:0+t:80',                                   // 深 A
+  'bj-a':   'm:0+t:81+s:2048',                                    // 北证 A
+  'cyb':    'm:0+t:80',                                           // 创业板
+  'kcb':    'm:1+t:23',                                           // 科创板
+  'hk':     'm:116+t:3,m:116+t:4,m:116+t:1,m:116+t:2',            // 港股
+  'us':     'm:105,m:106,m:107',                                  // 美股
+};
+
+const SORTS = {
+  change: { fid: 'f3',  order: 'desc' }, // 涨幅榜
+  drop:   { fid: 'f3',  order: 'asc'  }, // 跌幅榜
+  turnover:{ fid: 'f6', order: 'desc' }, // 成交额
+  volume: { fid: 'f5',  order: 'desc' }, // 成交量
+  amplitude:{ fid:'f7', order: 'desc' }, // 振幅
+  rate:   { fid: 'f8',  order: 'desc' }, // 换手率
+};
+
+const FIELDS =
+  'f2,f3,f4,f5,f6,f7,f8,f9,f10,f12,f13,f14,f15,f16,f17,f18,f20,f21,f23';
+
+cli({
+  site: 'eastmoney',
+  name: 'rank',
+  description: '东财市场涨跌/成交排行（沪深/北证/创/科/港/美）',
+  domain: 'push2.eastmoney.com',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: 'market', type: 'string', default: 'hs-a', help: '市场：hs-a / sh-a / sz-a / bj-a / cyb / kcb / hk / us' },
+    { name: 'sort',   type: 'string', default: 'change', help: '排序：change / drop / turnover / volume / amplitude / rate' },
+    { name: 'limit',  type: 'int',    default: 20,       help: '返回数量 (max 100)' },
+  ],
+  columns: ['rank', 'code', 'name', 'price', 'changePercent', 'change', 'turnover', 'volume', 'turnoverRate', 'peDynamic', 'marketCap'],
+  func: async (_page, args) => {
+    const market = String(args.market ?? 'hs-a').toLowerCase();
+    const sortKey = String(args.sort ?? 'change').toLowerCase();
+    const limit = Math.max(1, Math.min(Number(args.limit) || 20, 100));
+
+    const fs = MARKETS[market];
+    if (!fs) {
+      throw new CliError('INVALID_ARGUMENT', `Unknown market "${market}". Valid: ${Object.keys(MARKETS).join(', ')}`);
+    }
+    const sort = SORTS[sortKey];
+    if (!sort) {
+      throw new CliError('INVALID_ARGUMENT', `Unknown sort "${sortKey}". Valid: ${Object.keys(SORTS).join(', ')}`);
+    }
+
+    const url = new URL('https://push2.eastmoney.com/api/qt/clist/get');
+    url.searchParams.set('pn', '1');
+    url.searchParams.set('pz', String(limit));
+    url.searchParams.set('po', sort.order === 'desc' ? '1' : '0');
+    url.searchParams.set('np', '1');
+    url.searchParams.set('fltt', '2');
+    url.searchParams.set('invt', '2');
+    url.searchParams.set('fid', sort.fid);
+    url.searchParams.set('fs', fs);
+    url.searchParams.set('fields', FIELDS);
+    url.searchParams.set('ut', 'bd1d9ddb04089700cf9c27f6f7426281');
+
+    const resp = await fetch(url, { headers: { 'User-Agent': 'Mozilla/5.0', Accept: 'application/json' } });
+    if (!resp.ok) throw new CliError('HTTP_ERROR', `eastmoney rank failed: HTTP ${resp.status}`);
+    const data = await resp.json();
+    const diff = Array.isArray(data?.data?.diff) ? data.data.diff : [];
+    if (diff.length === 0) {
+      throw new CliError('NO_DATA', 'eastmoney returned no rank data', `market=${market} sort=${sortKey}`);
+    }
+
+    return diff.slice(0, limit).map((it, i) => ({
+      rank: i + 1,
+      code: it.f12,
+      name: it.f14,
+      price: it.f2,
+      changePercent: it.f3,
+      change: it.f4,
+      turnover: it.f6,
+      volume: it.f5,
+      turnoverRate: it.f8,
+      peDynamic: it.f9,
+      marketCap: it.f20,
+    }));
+  },
+});

package/clis/eastmoney/sectors.js

@@ -0,0 +1,76 @@
+// eastmoney sectors — industry / concept / region sector board ranking.
+//
+//   opencli eastmoney sectors
+//   opencli eastmoney sectors --type concept --sort money-flow --limit 30
+
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CliError } from '@jackwener/opencli/errors';
+
+const SECTOR_TYPES = {
+  industry: 'm:90+t:2',
+  concept:  'm:90+t:3',
+  region:   'm:90+t:1',
+};
+
+const SORTS = {
+  change: { fid: 'f3', order: 'desc' },
+  drop:   { fid: 'f3', order: 'asc' },
+  'money-flow': { fid: 'f62', order: 'desc' },
+  'out-flow':   { fid: 'f62', order: 'asc' },
+  turnover: { fid: 'f6', order: 'desc' },
+};
+
+cli({
+  site: 'eastmoney',
+  name: 'sectors',
+  description: '板块排行（行业/概念/地域）按涨跌幅、主力资金或成交额排序',
+  domain: 'push2.eastmoney.com',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: 'type', type: 'string', default: 'industry', help: '板块类型：industry / concept / region' },
+    { name: 'sort', type: 'string', default: 'change',   help: '排序：change / drop / money-flow / out-flow / turnover' },
+    { name: 'limit', type: 'int',   default: 20,         help: '返回数量 (max 100)' },
+  ],
+  columns: ['rank', 'code', 'name', 'price', 'changePercent', 'mainNet', 'leadStock', 'leadChangePercent', 'upCount', 'downCount'],
+  func: async (_page, args) => {
+    const typeKey = String(args.type ?? 'industry').toLowerCase();
+    const fs = SECTOR_TYPES[typeKey];
+    if (!fs) throw new CliError('INVALID_ARGUMENT', `Unknown sector type "${typeKey}". Valid: ${Object.keys(SECTOR_TYPES).join(', ')}`);
+    const sortKey = String(args.sort ?? 'change').toLowerCase();
+    const sort = SORTS[sortKey];
+    if (!sort) throw new CliError('INVALID_ARGUMENT', `Unknown sort "${sortKey}". Valid: ${Object.keys(SORTS).join(', ')}`);
+    const limit = Math.max(1, Math.min(Number(args.limit) || 20, 100));
+
+    const url = new URL('https://push2.eastmoney.com/api/qt/clist/get');
+    url.searchParams.set('pn', '1');
+    url.searchParams.set('pz', String(limit));
+    url.searchParams.set('po', sort.order === 'desc' ? '1' : '0');
+    url.searchParams.set('np', '1');
+    url.searchParams.set('fltt', '2');
+    url.searchParams.set('invt', '2');
+    url.searchParams.set('fid', sort.fid);
+    url.searchParams.set('fs', fs);
+    url.searchParams.set('fields', 'f12,f14,f2,f3,f62,f104,f105,f128,f136,f140,f141');
+    url.searchParams.set('ut', 'b2884a393a59ad64002292a3e90d46a5');
+
+    const resp = await fetch(url, { headers: { 'User-Agent': 'Mozilla/5.0' } });
+    if (!resp.ok) throw new CliError('HTTP_ERROR', `sectors failed: HTTP ${resp.status}`);
+    const data = await resp.json();
+    const diff = Array.isArray(data?.data?.diff) ? data.data.diff : [];
+    if (diff.length === 0) throw new CliError('NO_DATA', 'eastmoney returned no sector data');
+
+    return diff.slice(0, limit).map((it, i) => ({
+      rank: i + 1,
+      code: it.f12,
+      name: it.f14,
+      price: it.f2,
+      changePercent: it.f3,
+      mainNet: it.f62,
+      leadStock: it.f128,
+      leadChangePercent: it.f136,
+      upCount: it.f104,
+      downCount: it.f105,
+    }));
+  },
+});

package/clis/google-scholar/search.js

@@ -0,0 +1,58 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { clampInt, requireNonEmptyQuery } from '../_shared/common.js';
+
+cli({
+    site: 'google-scholar',
+    name: 'search',
+    description: 'Google Scholar 学术搜索',
+    domain: 'scholar.google.com',
+    strategy: Strategy.PUBLIC,
+    browser: true,
+    args: [
+        { name: 'query', positional: true, required: true, help: '搜索关键词' },
+        { name: 'limit', type: 'int', default: 10, help: '返回结果数量 (max 20)' },
+    ],
+    columns: ['rank', 'title', 'authors', 'source', 'year', 'cited', 'url'],
+    navigateBefore: false,
+    func: async (page, kwargs) => {
+        const limit = clampInt(kwargs.limit, 10, 1, 20);
+        const query = requireNonEmptyQuery(kwargs.query);
+        await page.goto(`https://scholar.google.com/scholar?q=${encodeURIComponent(query)}&hl=zh-CN`);
+        await page.wait(3);
+        const data = await page.evaluate(`
+      (() => {
+        const normalize = v => (v || '').replace(/\\s+/g, ' ').trim();
+        const results = [];
+        for (const el of document.querySelectorAll('.gs_r.gs_or.gs_scl, .gs_ri')) {
+          const container = el.querySelector('.gs_ri') || el;
+          const titleEl = container.querySelector('.gs_rt a, h3 a');
+          const title = normalize(titleEl?.textContent);
+          if (!title) continue;
+
+          const url = titleEl?.getAttribute('href') || '';
+          const infoLine = normalize(container.querySelector('.gs_a')?.textContent);
+          const parts = infoLine.split(' - ');
+          const authors = (parts[0] || '').trim();
+          const sourceParts = (parts[1] || '').split(',');
+          const source = sourceParts.slice(0, -1).join(',').trim() || sourceParts[0]?.trim() || '';
+          const year = infoLine.match(/(19|20)\\d{2}/)?.[0] || '';
+          const citedText = normalize(container.querySelector('.gs_fl a[href*="cites"]')?.textContent);
+          const cited = citedText.match(/(\\d+)/)?.[1] || '0';
+
+          results.push({
+            rank: results.length + 1,
+            title,
+            authors: authors.slice(0, 80),
+            source: source.slice(0, 60),
+            year,
+            cited,
+            url,
+          });
+          if (results.length >= ${limit}) break;
+        }
+        return results;
+      })()
+    `);
+        return Array.isArray(data) ? data : [];
+    },
+});

package/clis/google-scholar/search.test.js

@@ -0,0 +1,23 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './search.js';
+
+describe('google-scholar search command', () => {
+    const command = getRegistry().get('google-scholar/search');
+
+    it('registers as a public browser command', () => {
+        expect(command).toBeDefined();
+        expect(command.site).toBe('google-scholar');
+        expect(command.strategy).toBe('public');
+        expect(command.browser).toBe(true);
+    });
+
+    it('rejects empty queries before browser navigation', async () => {
+        const page = { goto: vi.fn() };
+        await expect(command.func(page, { query: '   ' })).rejects.toMatchObject({
+            name: 'ArgumentError',
+            code: 'ARGUMENT',
+        });
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+});

package/clis/gov-law/commands.test.js

@@ -0,0 +1,39 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './search.js';
+import './recent.js';
+
+describe('gov-law commands', () => {
+    const search = getRegistry().get('gov-law/search');
+    const recent = getRegistry().get('gov-law/recent');
+
+    it('registers both commands as public browser commands', () => {
+        expect(search).toBeDefined();
+        expect(recent).toBeDefined();
+        expect(search.strategy).toBe('public');
+        expect(recent.strategy).toBe('public');
+        expect(search.browser).toBe(true);
+        expect(recent.browser).toBe(true);
+    });
+
+    it('rejects empty search queries before browser navigation', async () => {
+        const page = { goto: vi.fn() };
+        await expect(search.func(page, { query: '   ' })).rejects.toMatchObject({
+            name: 'ArgumentError',
+            code: 'ARGUMENT',
+        });
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('throws a descriptive error when Vue Router is unavailable', async () => {
+        const page = {
+            goto: vi.fn(),
+            wait: vi.fn(),
+            evaluate: vi.fn().mockResolvedValue(false),
+        };
+        await expect(recent.func(page, { limit: 3 })).rejects.toMatchObject({
+            name: 'CliError',
+            code: 'FRAMEWORK_CHANGED',
+        });
+    });
+});

package/clis/gov-law/recent.js

@@ -0,0 +1,22 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { clampInt } from '../_shared/common.js';
+import { extractLawResults, navigateViaVueRouter } from './shared.js';
+
+cli({
+    site: 'gov-law',
+    name: 'recent',
+    description: '最新法律法规',
+    domain: 'flk.npc.gov.cn',
+    strategy: Strategy.PUBLIC,
+    browser: true,
+    args: [
+        { name: 'limit', type: 'int', default: 10, help: '返回结果数量 (max 20)' },
+    ],
+    columns: ['rank', 'title', 'status', 'publish_date', 'type', 'department'],
+    navigateBefore: false,
+    func: async (page, kwargs) => {
+        const limit = clampInt(kwargs.limit, 10, 1, 20);
+        await navigateViaVueRouter(page, {});
+        return extractLawResults(page, limit);
+    },
+});

package/clis/gov-law/search.js

@@ -0,0 +1,41 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { clampInt, requireNonEmptyQuery } from '../_shared/common.js';
+import { extractLawResults, navigateViaVueRouter } from './shared.js';
+
+cli({
+    site: 'gov-law',
+    name: 'search',
+    description: '国家法律法规数据库搜索',
+    domain: 'flk.npc.gov.cn',
+    strategy: Strategy.PUBLIC,
+    browser: true,
+    args: [
+        { name: 'query', positional: true, required: true, help: '搜索关键词' },
+        { name: 'limit', type: 'int', default: 10, help: '返回结果数量 (max 20)' },
+    ],
+    columns: ['rank', 'title', 'status', 'publish_date', 'type', 'department'],
+    navigateBefore: false,
+    func: async (page, kwargs) => {
+        const limit = clampInt(kwargs.limit, 10, 1, 20);
+        const query = requireNonEmptyQuery(kwargs.query);
+        await navigateViaVueRouter(page, { searchWord: query });
+
+        const encodedQuery = JSON.stringify(query);
+        await page.evaluate(`
+      (async () => {
+        const input = document.querySelector('.el-input__inner');
+        if (input && !input.value) {
+          const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set;
+          setter.call(input, ${encodedQuery});
+          input.dispatchEvent(new Event('input', { bubbles: true }));
+          input.dispatchEvent(new Event('change', { bubbles: true }));
+          await new Promise(r => setTimeout(r, 300));
+          input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', keyCode: 13, bubbles: true }));
+          input.dispatchEvent(new KeyboardEvent('keyup', { key: 'Enter', keyCode: 13, bubbles: true }));
+        }
+      })()
+    `);
+        await page.wait(3);
+        return extractLawResults(page, limit);
+    },
+});

package/clis/gov-law/shared.js

@@ -0,0 +1,51 @@
+import { CliError } from '@jackwener/opencli/errors';
+
+export async function navigateViaVueRouter(page, query) {
+    await page.goto('https://flk.npc.gov.cn/index.html');
+    await page.wait(4);
+
+    const routerAvailable = await page.evaluate(`
+      (async () => {
+        const app = document.querySelector('#app');
+        const router = app?.__vue_app__?.config?.globalProperties?.$router;
+        if (!router) return false;
+        await router.push({ path: '/search', query: ${JSON.stringify(query)} });
+        return true;
+      })()
+    `);
+
+    if (!routerAvailable) {
+        throw new CliError(
+            'FRAMEWORK_CHANGED',
+            'Could not access Vue Router on flk.npc.gov.cn — the site may have been restructured.',
+            'Please report this issue so the adapter can be updated.',
+        );
+    }
+
+    await page.wait(5);
+}
+
+export async function extractLawResults(page, limit) {
+    const data = await page.evaluate(`
+      (async () => {
+        const normalize = v => (v || '').replace(/\\s+/g, ' ').trim();
+        for (let i = 0; i < 40; i++) {
+          if (document.querySelectorAll('.result-item').length > 0) break;
+          await new Promise(r => setTimeout(r, 500));
+        }
+        const results = [];
+        for (const el of document.querySelectorAll('.result-item')) {
+          const title = normalize(el.querySelector('.title-content')?.textContent);
+          if (!title) continue;
+          const status = normalize(el.querySelector('[class*="status"]')?.textContent);
+          const publish_date = normalize(el.querySelector('.publish-time')?.textContent).replace(/^公布日期[：:]\\s*/, '');
+          const type = normalize(el.querySelector('.type')?.textContent);
+          const department = normalize(el.querySelector('.department')?.textContent);
+          results.push({ rank: results.length + 1, title, status, publish_date, type, department });
+          if (results.length >= ${limit}) break;
+        }
+        return results;
+      })()
+    `);
+    return Array.isArray(data) ? data : [];
+}

package/clis/gov-policy/commands.test.js

@@ -0,0 +1,27 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './search.js';
+import './recent.js';
+
+describe('gov-policy commands', () => {
+    const search = getRegistry().get('gov-policy/search');
+    const recent = getRegistry().get('gov-policy/recent');
+
+    it('registers both commands as public browser commands', () => {
+        expect(search).toBeDefined();
+        expect(recent).toBeDefined();
+        expect(search.browser).toBe(true);
+        expect(recent.browser).toBe(true);
+        expect(search.strategy).toBe('public');
+        expect(recent.strategy).toBe('public');
+    });
+
+    it('rejects empty search queries before browser navigation', async () => {
+        const page = { goto: vi.fn() };
+        await expect(search.func(page, { query: '   ' })).rejects.toMatchObject({
+            name: 'ArgumentError',
+            code: 'ARGUMENT',
+        });
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+});

package/clis/gov-policy/recent.js

@@ -0,0 +1,47 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { clampInt } from '../_shared/common.js';
+
+cli({
+    site: 'gov-policy',
+    name: 'recent',
+    description: '国务院最新政策文件',
+    domain: 'www.gov.cn',
+    strategy: Strategy.PUBLIC,
+    browser: true,
+    args: [
+        { name: 'limit', type: 'int', default: 10, help: '返回结果数量 (max 20)' },
+    ],
+    columns: ['rank', 'title', 'date', 'source', 'url'],
+    navigateBefore: false,
+    func: async (page, kwargs) => {
+        const limit = clampInt(kwargs.limit, 10, 1, 20);
+        await page.goto('https://www.gov.cn/zhengce/zuixin/index.htm');
+        await page.wait(4);
+        const data = await page.evaluate(`
+      (async () => {
+        const normalize = v => (v || '').replace(/\\s+/g, ' ').trim();
+        for (let i = 0; i < 20; i++) {
+          if (document.querySelector('.news_box li, .list li, .list_item, .news-list li')) break;
+          await new Promise(r => setTimeout(r, 500));
+        }
+        const results = [];
+        for (const el of document.querySelectorAll('.news_box li, .list li, .list_item, .news-list li')) {
+          const titleEl = el.querySelector('a');
+          const title = normalize(titleEl?.textContent);
+          if (!title || title.length < 4) continue;
+
+          let url = titleEl?.getAttribute('href') || '';
+          if (url && !url.startsWith('http')) url = 'https://www.gov.cn' + url;
+
+          const date = (el.textContent || '').match(/(\\d{4}[-./]\\d{1,2}[-./]\\d{1,2})/)?.[1] || '';
+          const source = normalize(el.querySelector('.source, .from')?.textContent);
+
+          results.push({ rank: results.length + 1, title, date, source, url });
+          if (results.length >= ${limit}) break;
+        }
+        return results;
+      })()
+    `);
+        return Array.isArray(data) ? data : [];
+    },
+});

package/clis/gov-policy/search.js

@@ -0,0 +1,48 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { clampInt, requireNonEmptyQuery } from '../_shared/common.js';
+
+cli({
+    site: 'gov-policy',
+    name: 'search',
+    description: '中国政府网政策文件搜索',
+    domain: 'sousuo.www.gov.cn',
+    strategy: Strategy.PUBLIC,
+    browser: true,
+    args: [
+        { name: 'query', positional: true, required: true, help: '搜索关键词' },
+        { name: 'limit', type: 'int', default: 10, help: '返回结果数量 (max 20)' },
+    ],
+    columns: ['rank', 'title', 'description', 'date', 'url'],
+    navigateBefore: false,
+    func: async (page, kwargs) => {
+        const limit = clampInt(kwargs.limit, 10, 1, 20);
+        const query = requireNonEmptyQuery(kwargs.query);
+        await page.goto(`https://sousuo.www.gov.cn/sousuo/search.shtml?code=17da70961a7&dataTypeId=107&searchWord=${encodeURIComponent(query)}`);
+        await page.wait(5);
+        const data = await page.evaluate(`
+      (async () => {
+        const normalize = v => (v || '').replace(/\\s+/g, ' ').trim();
+        for (let i = 0; i < 30; i++) {
+          if (document.querySelectorAll('.basic_result_content .item, .js_basic_result_content .item').length > 0) break;
+          await new Promise(r => setTimeout(r, 500));
+        }
+        const results = [];
+        for (const el of document.querySelectorAll('.basic_result_content .item, .js_basic_result_content .item')) {
+          const titleEl = el.querySelector('a.title, .title a, a.log-anchor');
+          const title = normalize(titleEl?.textContent).replace(/<[^>]+>/g, '');
+          if (!title || title.length < 4) continue;
+
+          let url = titleEl?.getAttribute('href') || '';
+          if (url && !url.startsWith('http')) url = 'https://www.gov.cn' + url;
+
+          const description = normalize(el.querySelector('.description')?.textContent).slice(0, 120);
+          const date = (el.textContent || '').match(/(\\d{4}[-./]\\d{1,2}[-./]\\d{1,2})/)?.[1] || '';
+          results.push({ rank: results.length + 1, title, description, date, url });
+          if (results.length >= ${limit}) break;
+        }
+        return results;
+      })()
+    `);
+        return Array.isArray(data) ? data : [];
+    },
+});

package/clis/grok/image.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+import type { IPage } from '@jackwener/opencli/types';
+import { __test__ } from './image.js';
+
+describe('grok image helpers', () => {
+  describe('isOnGrok', () => {
+    const fakePage = (url: string | Error): IPage =>
+      ({ evaluate: () => url instanceof Error ? Promise.reject(url) : Promise.resolve(url) }) as unknown as IPage;
+
+    it('returns true for grok.com URLs', async () => {
+      expect(await __test__.isOnGrok(fakePage('https://grok.com/'))).toBe(true);
+      expect(await __test__.isOnGrok(fakePage('https://grok.com/chat/abc123'))).toBe(true);
+    });
+
+    it('returns true for grok.com subdomains', async () => {
+      expect(await __test__.isOnGrok(fakePage('https://assets.grok.com/foo'))).toBe(true);
+    });
+
+    it('returns false for non-grok domains', async () => {
+      expect(await __test__.isOnGrok(fakePage('https://fakegrok.com/'))).toBe(false);
+      expect(await __test__.isOnGrok(fakePage('about:blank'))).toBe(false);
+    });
+
+    it('returns false when evaluate throws (detached tab)', async () => {
+      expect(await __test__.isOnGrok(fakePage(new Error('detached')))).toBe(false);
+    });
+  });
+
+  it('normalizes boolean flags', () => {
+    expect(__test__.normalizeBooleanFlag(true)).toBe(true);
+    expect(__test__.normalizeBooleanFlag('true')).toBe(true);
+    expect(__test__.normalizeBooleanFlag('1')).toBe(true);
+    expect(__test__.normalizeBooleanFlag('yes')).toBe(true);
+    expect(__test__.normalizeBooleanFlag('on')).toBe(true);
+
+    expect(__test__.normalizeBooleanFlag(false)).toBe(false);
+    expect(__test__.normalizeBooleanFlag('false')).toBe(false);
+    expect(__test__.normalizeBooleanFlag(undefined)).toBe(false);
+  });
+
+  it('dedupes images by src', () => {
+    const deduped = __test__.dedupeBySrc([
+      { src: 'https://a.example/1.jpg', w: 500, h: 500 },
+      { src: 'https://a.example/1.jpg', w: 500, h: 500 },
+      { src: 'https://a.example/2.jpg', w: 500, h: 500 },
+      { src: '', w: 500, h: 500 },
+    ]);
+    expect(deduped.map(i => i.src)).toEqual([
+      'https://a.example/1.jpg',
+      'https://a.example/2.jpg',
+    ]);
+  });
+
+  it('builds a deterministic-ish signature order-independent by src', () => {
+    const sigA = __test__.imagesSignature([
+      { src: 'https://a.example/1.jpg', w: 1, h: 1 },
+      { src: 'https://a.example/2.jpg', w: 1, h: 1 },
+    ]);
+    const sigB = __test__.imagesSignature([
+      { src: 'https://a.example/2.jpg', w: 1, h: 1 },
+      { src: 'https://a.example/1.jpg', w: 1, h: 1 },
+    ]);
+    expect(sigA).toBe(sigB);
+  });
+
+  it('maps content-type to sensible image extensions', () => {
+    expect(__test__.extFromContentType('image/png')).toBe('png');
+    expect(__test__.extFromContentType('image/webp')).toBe('webp');
+    expect(__test__.extFromContentType('image/gif')).toBe('gif');
+    expect(__test__.extFromContentType('image/jpeg')).toBe('jpg');
+    expect(__test__.extFromContentType(undefined)).toBe('jpg');
+    expect(__test__.extFromContentType('')).toBe('jpg');
+  });
+
+  it('builds filenames with a stable sha1 slice tied to the src', () => {
+    const a1 = __test__.buildFilename('https://a.example/1.jpg', 'image/jpeg');
+    const a2 = __test__.buildFilename('https://a.example/1.jpg', 'image/jpeg');
+    const b1 = __test__.buildFilename('https://a.example/2.jpg', 'image/png');
+    // Same URL → same 12-char hash slice (timestamps may differ).
+    expect(a1.split('-')[2].split('.')[0]).toBe(a2.split('-')[2].split('.')[0]);
+    expect(a1.split('-')[2].split('.')[0]).not.toBe(b1.split('-')[2].split('.')[0]);
+    expect(a1.endsWith('.jpg')).toBe(true);
+    expect(b1.endsWith('.png')).toBe(true);
+  });
+
+  it('only accepts image bubbles that appeared after the baseline', () => {
+    const candidate = __test__.pickLatestImageCandidate([
+      [{ src: 'https://a.example/stale.jpg', w: 512, h: 512 }],
+      [],
+      [{ src: 'https://a.example/fresh.jpg', w: 1024, h: 1024 }],
+    ], 1);
+
+    expect(candidate).toEqual([
+      { src: 'https://a.example/fresh.jpg', w: 1024, h: 1024 },
+    ]);
+  });
+
+  it('does not reuse stale images when no new image bubble appears after baseline', () => {
+    const candidate = __test__.pickLatestImageCandidate([
+      [{ src: 'https://a.example/stale.jpg', w: 512, h: 512 }],
+      [],
+      [],
+    ], 1);
+
+    expect(candidate).toEqual([]);
+  });
+});