@ishlabs/cli 0.13.0 → 0.14.1

package/dist/lib/enums.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Enum-value normalisation for CLI flags.
+ *
+ * Agents (and humans) reach for hyphen-style values on the command line —
+ * `--screen-format mobile-portrait`, `--kind text-file`, `--chat-mode
+ * tester-pair` — even when the canonical backend value is underscored (or
+ * vice versa for the ask-question `type` field, which is hyphenated). Rather
+ * than fail with a 422, each parse site funnels the raw value through
+ * `normalizeEnumValue` and gets back the canonical form (or `null` for a
+ * genuine typo, so the caller can throw a clean ValidationError).
+ *
+ * Scope: apply this only to flags whose allowed values are explicitly enumerated
+ * client-side. Don't blanket-rewrite arbitrary strings — that would mask real
+ * typos (`mobil_portrait` ≠ `mobile_portrait`) and silently coerce values the
+ * backend hasn't agreed to.
+ */
+/**
+ * Case-insensitively match `raw` against `allowed`, treating hyphens and
+ * underscores as interchangeable. Returns the canonical form from `allowed`
+ * if matched, `null` otherwise.
+ */
+export declare function normalizeEnumValue<T extends string>(raw: string | undefined | null, allowed: readonly T[]): T | null;
+/** Interactive-iteration screen format. Canonical underscored. */
+export declare const SCREEN_FORMATS: readonly ["desktop", "mobile_portrait"];
+export type ScreenFormat = typeof SCREEN_FORMATS[number];
+/**
+ * Interview-question types. Canonical is **hyphenated** for the multi-word
+ * values (`single-choice`, `multiple-choice`) — that's what the backend
+ * accepts. The normaliser folds underscored variants back to the canonical
+ * hyphenated form.
+ */
+export declare const QUESTION_TYPES: readonly ["text", "slider", "likert", "single-choice", "multiple-choice", "number"];
+export type QuestionType = typeof QUESTION_TYPES[number];
+/**
+ * TesterProfile structured enums (profile-enums.v1.json). Values are
+ * snake_case and match the spec byte-for-byte; agents pass them verbatim
+ * via CLI flags.
+ */
+export declare const EDUCATION_LEVELS: readonly ["less_than_secondary", "secondary", "some_post_secondary", "vocational_or_associate", "bachelor", "graduate"];
+export type EducationLevel = typeof EDUCATION_LEVELS[number];
+export declare const HOUSEHOLDS: readonly ["single", "couple_no_kids", "couple_with_kids", "single_parent", "shared_housing", "adult_with_parents", "multi_generational"];
+export type Household = typeof HOUSEHOLDS[number];
+export declare const LOCALE_TYPES: readonly ["urban", "suburban", "small_town", "rural"];
+export type LocaleType = typeof LOCALE_TYPES[number];
+export declare const INCOME_LEVELS: readonly ["lower", "lower_middle", "middle", "upper_middle", "upper", "prefer_not_to_say"];
+export type IncomeLevel = typeof INCOME_LEVELS[number];
+export declare const EMPLOYMENT_STATUSES: readonly ["employed_full_time", "employed_part_time", "self_employed", "unemployed_seeking", "student", "homemaker", "retired", "unable_to_work", "other"];
+export type EmploymentStatus = typeof EMPLOYMENT_STATUSES[number];
+/**
+ * Strict enum check for CLI flag values. Snake_case-only; no hyphen folding,
+ * because the spec values are the wire format and agents are expected to
+ * pass them verbatim.
+ */
+export declare function assertEnumValue<T extends string>(raw: string, allowed: readonly T[], flagName: string): T;

package/dist/lib/enums.js

@@ -0,0 +1,100 @@
+/**
+ * Enum-value normalisation for CLI flags.
+ *
+ * Agents (and humans) reach for hyphen-style values on the command line —
+ * `--screen-format mobile-portrait`, `--kind text-file`, `--chat-mode
+ * tester-pair` — even when the canonical backend value is underscored (or
+ * vice versa for the ask-question `type` field, which is hyphenated). Rather
+ * than fail with a 422, each parse site funnels the raw value through
+ * `normalizeEnumValue` and gets back the canonical form (or `null` for a
+ * genuine typo, so the caller can throw a clean ValidationError).
+ *
+ * Scope: apply this only to flags whose allowed values are explicitly enumerated
+ * client-side. Don't blanket-rewrite arbitrary strings — that would mask real
+ * typos (`mobil_portrait` ≠ `mobile_portrait`) and silently coerce values the
+ * backend hasn't agreed to.
+ */
+/**
+ * Case-insensitively match `raw` against `allowed`, treating hyphens and
+ * underscores as interchangeable. Returns the canonical form from `allowed`
+ * if matched, `null` otherwise.
+ */
+export function normalizeEnumValue(raw, allowed) {
+    if (raw === undefined || raw === null)
+        return null;
+    const key = String(raw).trim().toLowerCase().replace(/-/g, "_");
+    for (const a of allowed) {
+        if (a.toLowerCase().replace(/-/g, "_") === key)
+            return a;
+    }
+    return null;
+}
+/** Interactive-iteration screen format. Canonical underscored. */
+export const SCREEN_FORMATS = ["desktop", "mobile_portrait"];
+/**
+ * Interview-question types. Canonical is **hyphenated** for the multi-word
+ * values (`single-choice`, `multiple-choice`) — that's what the backend
+ * accepts. The normaliser folds underscored variants back to the canonical
+ * hyphenated form.
+ */
+export const QUESTION_TYPES = [
+    "text",
+    "slider",
+    "likert",
+    "single-choice",
+    "multiple-choice",
+    "number",
+];
+/**
+ * TesterProfile structured enums (profile-enums.v1.json). Values are
+ * snake_case and match the spec byte-for-byte; agents pass them verbatim
+ * via CLI flags.
+ */
+export const EDUCATION_LEVELS = [
+    "less_than_secondary",
+    "secondary",
+    "some_post_secondary",
+    "vocational_or_associate",
+    "bachelor",
+    "graduate",
+];
+export const HOUSEHOLDS = [
+    "single",
+    "couple_no_kids",
+    "couple_with_kids",
+    "single_parent",
+    "shared_housing",
+    "adult_with_parents",
+    "multi_generational",
+];
+export const LOCALE_TYPES = ["urban", "suburban", "small_town", "rural"];
+export const INCOME_LEVELS = [
+    "lower",
+    "lower_middle",
+    "middle",
+    "upper_middle",
+    "upper",
+    "prefer_not_to_say",
+];
+export const EMPLOYMENT_STATUSES = [
+    "employed_full_time",
+    "employed_part_time",
+    "self_employed",
+    "unemployed_seeking",
+    "student",
+    "homemaker",
+    "retired",
+    "unable_to_work",
+    "other",
+];
+/**
+ * Strict enum check for CLI flag values. Snake_case-only; no hyphen folding,
+ * because the spec values are the wire format and agents are expected to
+ * pass them verbatim.
+ */
+export function assertEnumValue(raw, allowed, flagName) {
+    if (!allowed.includes(raw)) {
+        throw new Error(`Invalid ${flagName}: "${raw}". Allowed values: ${allowed.join(", ")}.`);
+    }
+    return raw;
+}

package/dist/lib/local-sim/actions.d.ts

@@ -8,10 +8,11 @@
  */
 import type { Page } from "playwright-core";
 import type { LocalStepAction, ActionResult, ContextValue, TreeData } from "./types.js";
+import type { TabManager } from "./tabs.js";
 /**
  * Execute a single action on the page.
  */
-export declare function executeAction(page: Page, action: LocalStepAction, treeData: TreeData, contextValues: ContextValue[]): Promise<ActionResult>;
+export declare function executeAction(page: Page, action: LocalStepAction, treeData: TreeData, contextValues: ContextValue[], tabs?: TabManager): Promise<ActionResult>;
 /**
  * Compare two base64 screenshots to detect visible change.
  */

package/dist/lib/local-sim/actions.js

@@ -8,6 +8,37 @@
  */
 import { resolveNodeToBoundingBox } from "./browser.js";
 import { isDebugEnabled } from "./debug.js";
+// Agent-facing modifier names → Playwright keyboard modifier names.
+// Mirrors backend `_PLAYWRIGHT_MODIFIERS` in
+// ish-backend/app/simulation/executors/browser.py.
+const PLAYWRIGHT_MODIFIERS = {
+    cmd: "Meta", ctrl: "Control", shift: "Shift", alt: "Alt",
+};
+function toPWModifiers(mods) {
+    if (!mods?.length)
+        return [];
+    const out = [];
+    for (const m of mods) {
+        const mapped = PLAYWRIGHT_MODIFIERS[m.toLowerCase()];
+        if (mapped)
+            out.push(mapped);
+    }
+    return out;
+}
+async function withModifiers(page, mods, fn) {
+    if (!mods.length)
+        return fn();
+    for (const m of mods)
+        await page.keyboard.down(m);
+    try {
+        return await fn();
+    }
+    finally {
+        for (const m of [...mods].reverse()) {
+            await page.keyboard.up(m).catch(() => { });
+        }
+    }
+}
 // --- ARIA role → Playwright role mapping ---
 const ELEMENT_TYPE_TO_ROLE = {
     BUTTON: "button",
@@ -26,7 +57,7 @@ const ELEMENT_TYPE_TO_ROLE = {
 /**
  * Execute a single action on the page.
  */
-export async function executeAction(page, action, treeData, contextValues) {
+export async function executeAction(page, action, treeData, contextValues, tabs) {
     try {
         // Intercept "back button" taps — the LLM often tries to tap the browser
         // back button which doesn't exist in the viewport. Convert to page.goBack().
@@ -71,6 +102,18 @@ export async function executeAction(page, action, treeData, contextValues) {
             case "think":
                 // No-op: model is reasoning without acting
                 break;
+            case "keyboard_shortcut":
+                await executeKeyboardShortcut(page, action);
+                break;
+            case "switch_tab":
+            case "close_tab":
+                if (tabs && action.tab_id) {
+                    if (action.type === "switch_tab")
+                        await tabs.switchTab(action.tab_id);
+                    else
+                        await tabs.closeTab(action.tab_id);
+                }
+                break;
             case "pinch_zoom":
             case "rotate_device":
                 // Not supported in desktop browser
@@ -178,9 +221,12 @@ async function executeTap(page, action, treeData) {
     const count = action.count ?? 1;
     const coords = await resolveElement(page, action, treeData);
     if (coords) {
-        for (let i = 0; i < count; i++) {
-            await page.mouse.click(coords.x, coords.y);
-        }
+        const pwMods = toPWModifiers(action.modifiers);
+        await withModifiers(page, pwMods, async () => {
+            for (let i = 0; i < count; i++) {
+                await page.mouse.click(coords.x, coords.y);
+            }
+        });
         return coords;
     }
     else {
@@ -295,22 +341,40 @@ async function executeLongPress(page, action, treeData) {
     const coords = await resolveElement(page, action, treeData);
     if (!coords)
         throw new Error(`Cannot locate element for long press: ${action.element_name ?? "unknown"}`);
-    await page.mouse.move(coords.x, coords.y);
-    await page.mouse.down();
-    await page.waitForTimeout(action.duration_ms ?? 500);
-    await page.mouse.up();
+    const pwMods = toPWModifiers(action.modifiers);
+    await withModifiers(page, pwMods, async () => {
+        await page.mouse.move(coords.x, coords.y);
+        await page.mouse.down();
+        await page.waitForTimeout(action.duration_ms ?? 500);
+        await page.mouse.up();
+    });
     return coords;
 }
 async function executeDoubleTap(page, action, treeData) {
     const coords = await resolveElement(page, action, treeData);
     if (coords) {
-        await page.mouse.dblclick(coords.x, coords.y);
+        const pwMods = toPWModifiers(action.modifiers);
+        await withModifiers(page, pwMods, async () => {
+            await page.mouse.dblclick(coords.x, coords.y);
+        });
         return coords;
     }
     else {
         throw new Error(`Cannot locate element for double tap: ${action.element_name ?? "unknown"}`);
     }
 }
+/**
+ * Press a key combination on the currently focused element.
+ * Mirrors backend BrowserActionExecutor.execute_keyboard_shortcut.
+ */
+async function executeKeyboardShortcut(page, action) {
+    if (!action.key) {
+        throw new Error("keyboard_shortcut missing key");
+    }
+    const pwMods = toPWModifiers(action.modifiers);
+    const combo = pwMods.length ? `${pwMods.join("+")}+${action.key}` : action.key;
+    await page.keyboard.press(combo);
+}
 // --- Helpers ---
 /**
  * Resolve the actual text to type from an action, handling var/secret value types.
@@ -343,11 +407,12 @@ export function detectNoVisibleChange(before, after) {
  */
 export function describeAction(action) {
     const element = action.element_name || "element";
+    const modSuffix = action.modifiers?.length ? ` [${action.modifiers.join("+")}]` : "";
     switch (action.type) {
         case "tap":
             return action.count && action.count > 1
-                ? `tap on '${element}' x${action.count}`
-                : `tap on '${element}'`;
+                ? `tap on '${element}' x${action.count}${modSuffix}`
+                : `tap on '${element}'${modSuffix}`;
         case "text_input": {
             const val = action.value_type === "secret" ? "***" : `"${(action.value ?? "").slice(0, 30)}"`;
             const modeStr = action.mode ? ` (${action.mode}${action.submit ? ", submit" : ""})` : "";
@@ -364,15 +429,25 @@ export function describeAction(action) {
         case "navigate_back":
             return "navigate back";
         case "long_press":
-            return `long_press on '${element}'`;
+            return `long_press on '${element}'${modSuffix}`;
         case "double_tap":
-            return `double_tap on '${element}'`;
+            return `double_tap on '${element}'${modSuffix}`;
         case "drag":
             return `drag '${element}'`;
         case "think":
             return `think: "${(action.thoughts ?? "").slice(0, 50)}"`;
         case "pull_to_refresh":
             return "pull_to_refresh";
+        case "keyboard_shortcut": {
+            const combo = action.modifiers?.length
+                ? `${action.modifiers.join("+")}+${action.key ?? "?"}`
+                : (action.key ?? "?");
+            return `keyboard_shortcut '${combo}'`;
+        }
+        case "switch_tab":
+            return `switch_tab '${action.tab_id ?? "?"}'`;
+        case "close_tab":
+            return `close_tab '${action.tab_id ?? "?"}'`;
         default:
             return `${action.type} on '${element}'`;
     }

package/dist/lib/local-sim/loop.js

@@ -7,6 +7,7 @@
 import { launchBrowser, launchSharedBrowser, createTab, captureObservation, takeScreenshot, takeScreenshotJpeg, navigateWithRetry, closeBrowser } from "./browser.js";
 import { uploadScreenshot } from "./upload.js";
 import { executeAction, detectNoVisibleChange, describeAction } from "./actions.js";
+import { TabManager } from "./tabs.js";
 import { enableDebug, isDebugEnabled, debugObservation, debugRawResponse, debugNormalizedActions, debugActionExecution, debugForwards, debugStepSummary, debugRecord, } from "./debug.js";
 /**
  * Convert a raw action (from either resolved_actions or output.action.actions)
@@ -32,6 +33,9 @@ function flattenAction(raw, nodeId = null, nodeDescription = null) {
         count: a.count ?? null,
         duration_ms: a.duration_ms ?? null,
         thoughts: a.thoughts ?? null,
+        modifiers: Array.isArray(a.modifiers) ? a.modifiers : null,
+        key: a.key ?? null,
+        tab_id: a.tab_id ?? null,
     };
 }
 /**
@@ -199,7 +203,10 @@ async function runSingleSimulation(client, testerId, testerName, opts, log, isCa
     const browserSession = sharedBrowser
         ? await createTab(sharedBrowser, browserOpts)
         : await launchBrowser(browserOpts);
-    const { page } = browserSession;
+    // Active page can swap when a popup auto-focuses or the LLM issues
+    // switch_tab/close_tab. TabManager wires the context popup listener.
+    const tabs = new TabManager(browserSession.context, browserSession.page);
+    let page = tabs.activePage();
     const history = [];
     const interactions = [];
     const debugSteps = [];
@@ -218,7 +225,8 @@ async function runSingleSimulation(client, testerId, testerName, opts, log, isCa
             let step = 0;
             let assignmentCompleted = false;
             while (step < maxSteps && !assignmentCompleted && !isCancelled()) {
-                // OBSERVE
+                // OBSERVE — refresh active page in case a popup or switch_tab changed it
+                page = tabs.activePage();
                 const obs = await captureObservation(page);
                 const lastTreeData = obs.treeData;
                 const currentScreenshot = obs.screenshot;
@@ -236,6 +244,9 @@ async function runSingleSimulation(client, testerId, testerName, opts, log, isCa
                 if (forwards.length > 0)
                     debugForwards(forwards);
                 const viewportSize = page.viewportSize() ?? viewport;
+                // Snapshot open tabs so the backend can prompt the LLM with tab ids
+                // (used by switch_tab/close_tab and to disambiguate cmd+click results).
+                const tabsSnapshot = await tabs.list();
                 // REASON (remote)
                 let stepResponse;
                 try {
@@ -258,6 +269,7 @@ async function runSingleSimulation(client, testerId, testerName, opts, log, isCa
                         agent_model: session.agent_model,
                         dom_model: session.dom_model,
                         llm_provider: session.llm_provider,
+                        tabs: tabsSnapshot,
                     };
                     stepResponse = normalizeStepResponse(await client.localSimStep(stepReqBody));
                 }
@@ -285,6 +297,7 @@ async function runSingleSimulation(client, testerId, testerName, opts, log, isCa
                             agent_model: session.agent_model,
                             dom_model: session.dom_model,
                             llm_provider: session.llm_provider,
+                            tabs: tabsSnapshot,
                         };
                         stepResponse = normalizeStepResponse(await client.localSimStep(stepReqBody));
                     }
@@ -304,10 +317,17 @@ async function runSingleSimulation(client, testerId, testerName, opts, log, isCa
                 for (let i = 0; i < stepResponse.actions.length; i++) {
                     if (isCancelled())
                         break;
+                    // Pick up popup auto-switch / explicit tab switch from prior actions.
+                    page = tabs.activePage();
                     const action = stepResponse.actions[i];
-                    const result = await executeAction(page, action, lastTreeData, session.context_values);
+                    const tabsBefore = (await tabs.list()).length;
+                    const result = await executeAction(page, action, lastTreeData, session.context_values, tabs);
                     const desc = describeAction(action);
                     debugActionExecution(i, action, result, action.node_id ? "cdp" : "playwright");
+                    // The action may have flipped the active tab — re-read.
+                    page = tabs.activePage();
+                    const tabsAfter = (await tabs.list()).length;
+                    const openedNewTab = action.type === "tap" && tabsAfter > tabsBefore;
                     let normalizedCoords = null;
                     if (result.coordinates) {
                         const vp = page.viewportSize() ?? viewport;
@@ -317,22 +337,29 @@ async function runSingleSimulation(client, testerId, testerName, opts, log, isCa
                         };
                     }
                     const actionType = action.type || "unknown";
-                    actionDatas.push({
-                        action_type: actionType,
-                        element_label: action.element_name ?? null,
-                        element_type: action.element_type ?? null,
-                        coordinates: normalizedCoords,
-                        data: {
-                            ...(action.value !== undefined && action.value !== null && { value: action.value_type === "secret" ? "***" : action.value }),
-                            ...(action.mode && { mode: action.mode }),
-                            ...(action.submit && { submit: action.submit }),
-                            ...(action.direction && { direction: action.direction }),
-                            ...(action.amount && { amount: action.amount }),
-                            ...(action.count && action.count > 1 && { count: action.count }),
-                            ...(action.duration_ms && { duration_ms: action.duration_ms }),
-                        },
-                        order: i,
-                    });
+                    const INTERNAL_ACTIONS = new Set(["think"]);
+                    if (!INTERNAL_ACTIONS.has(actionType)) {
+                        actionDatas.push({
+                            action_type: actionType,
+                            element_label: action.element_name ?? null,
+                            element_type: action.element_type ?? null,
+                            coordinates: normalizedCoords,
+                            data: {
+                                ...(action.value !== undefined && action.value !== null && { value: action.value_type === "secret" ? "***" : action.value }),
+                                ...(action.mode && { mode: action.mode }),
+                                ...(action.submit && { submit: action.submit }),
+                                ...(action.direction && { direction: action.direction }),
+                                ...(action.amount && { amount: action.amount }),
+                                ...(action.count && action.count > 1 && { count: action.count }),
+                                ...(action.duration_ms && { duration_ms: action.duration_ms }),
+                                ...(action.modifiers?.length && { modifiers: action.modifiers }),
+                                ...(action.key && { key: action.key }),
+                                ...(action.tab_id && { tab_id: action.tab_id }),
+                                ...(openedNewTab && { opened_new_tab: true }),
+                            },
+                            order: i,
+                        });
+                    }
                     actionDebugEntries.push({
                         type: actionType,
                         elementName: action.element_name ?? null,
@@ -422,6 +449,9 @@ async function runSingleSimulation(client, testerId, testerName, opts, log, isCa
                     actions: actionDatas,
                     current_location: stepResponse.current_location,
                     assignment_completed: stepResponse.assignment_completed,
+                    // Server reduces this to Interaction.tab when N >= 2; omit on
+                    // single-tab steps to keep the payload (and DB column) null.
+                    ...(tabsSnapshot.length >= 2 ? { tabs: tabsSnapshot } : {}),
                 });
                 // Update history for next step
                 history.push({

package/dist/lib/local-sim/tabs.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Tab manager — tracks open pages with stable ids, auto-switches on popup,
+ * falls back to the opener tab when the active tab closes.
+ *
+ * Mirrors backend semantics in
+ * `ish-backend/app/simulation/computers/browser/computer.py` (TabRecord +
+ * _register_tab / _on_new_page / _set_active_tab / _handle_tab_closed).
+ */
+import type { BrowserContext, Page } from "playwright-core";
+import type { LocalTabInfo } from "./types.js";
+export declare class TabManager {
+    private readonly context;
+    private readonly tabs;
+    private activeTabId;
+    private counter;
+    constructor(context: BrowserContext, initialPage: Page);
+    activePage(): Page;
+    activeId(): string | null;
+    list(): Promise<LocalTabInfo[]>;
+    switchTab(tabId: string): Promise<void>;
+    closeTab(tabId: string): Promise<void>;
+    private registerTab;
+    private onNewPage;
+    private afterNewPageFocus;
+    private setActiveTab;
+    private handleTabClosed;
+}

package/dist/lib/local-sim/tabs.js

@@ -0,0 +1,157 @@
+/**
+ * Tab manager — tracks open pages with stable ids, auto-switches on popup,
+ * falls back to the opener tab when the active tab closes.
+ *
+ * Mirrors backend semantics in
+ * `ish-backend/app/simulation/computers/browser/computer.py` (TabRecord +
+ * _register_tab / _on_new_page / _set_active_tab / _handle_tab_closed).
+ */
+import { isDebugEnabled } from "./debug.js";
+const MAX_OPEN_TABS = 10;
+const NEW_TAB_LOAD_TIMEOUT_MS = 5000;
+export class TabManager {
+    context;
+    tabs = new Map();
+    activeTabId = null;
+    counter = 0;
+    constructor(context, initialPage) {
+        this.context = context;
+        this.context.on("page", (page) => this.onNewPage(page));
+        const id = this.registerTab(initialPage, null);
+        this.activeTabId = id;
+    }
+    activePage() {
+        if (!this.activeTabId) {
+            throw new Error("No active tab");
+        }
+        const rec = this.tabs.get(this.activeTabId);
+        if (!rec)
+            throw new Error(`Active tab ${this.activeTabId} not registered`);
+        return rec.page;
+    }
+    activeId() {
+        return this.activeTabId;
+    }
+    async list() {
+        const out = [];
+        const sorted = [...this.tabs.values()].sort((a, b) => a.openedAt - b.openedAt);
+        for (const rec of sorted) {
+            if (rec.page.isClosed())
+                continue;
+            let title = "";
+            try {
+                title = await rec.page.title();
+            }
+            catch {
+                // ignore
+            }
+            out.push({
+                id: rec.id,
+                title: title.slice(0, 80),
+                url: rec.page.url(),
+                active: rec.id === this.activeTabId,
+                opener_id: rec.parentId && this.tabs.has(rec.parentId) ? rec.parentId : null,
+            });
+        }
+        return out;
+    }
+    async switchTab(tabId) {
+        await this.setActiveTab(tabId);
+    }
+    async closeTab(tabId) {
+        const rec = this.tabs.get(tabId);
+        if (!rec) {
+            throw new Error(`Unknown tab id: ${tabId}`);
+        }
+        await rec.page.close().catch(() => { });
+        // page.on('close') drives the rest of the bookkeeping.
+    }
+    registerTab(page, parentId) {
+        this.counter += 1;
+        const id = `t${this.counter}`;
+        this.tabs.set(id, { id, page, parentId, openedAt: Date.now() });
+        page.on("close", () => {
+            void this.handleTabClosed(id);
+        });
+        return id;
+    }
+    onNewPage(page) {
+        if (this.tabs.size >= MAX_OPEN_TABS) {
+            if (isDebugEnabled()) {
+                console.error(`      [tabs] cap reached (${this.tabs.size}), closing extra popup`);
+            }
+            void page.close().catch(() => { });
+            return;
+        }
+        const parentId = this.activeTabId;
+        const tabId = this.registerTab(page, parentId);
+        if (isDebugEnabled()) {
+            console.error(`      [tabs] new tab ${tabId} (parent=${parentId ?? "-"}, url=${page.url()})`);
+        }
+        void this.afterNewPageFocus(tabId, page);
+    }
+    async afterNewPageFocus(tabId, page) {
+        try {
+            await page.waitForLoadState("domcontentloaded", { timeout: NEW_TAB_LOAD_TIMEOUT_MS });
+        }
+        catch {
+            if (isDebugEnabled()) {
+                console.error(`      [tabs] tab ${tabId} did not reach domcontentloaded in ${NEW_TAB_LOAD_TIMEOUT_MS}ms`);
+            }
+        }
+        // The tab may have closed during the wait (OAuth pop-then-redirect, etc).
+        if (!this.tabs.has(tabId))
+            return;
+        await this.setActiveTab(tabId);
+    }
+    async setActiveTab(tabId) {
+        const rec = this.tabs.get(tabId);
+        if (!rec) {
+            throw new Error(`Unknown tab id: ${tabId}`);
+        }
+        if (rec.page.isClosed()) {
+            await this.handleTabClosed(tabId);
+            return;
+        }
+        this.activeTabId = tabId;
+        try {
+            await rec.page.bringToFront();
+        }
+        catch {
+            // Headless or transient — non-fatal.
+        }
+        if (isDebugEnabled()) {
+            console.error(`      [tabs] active → ${tabId} (${rec.page.url()})`);
+        }
+    }
+    async handleTabClosed(tabId) {
+        const rec = this.tabs.get(tabId);
+        if (!rec)
+            return;
+        this.tabs.delete(tabId);
+        if (this.activeTabId !== tabId) {
+            // A background tab closed — no focus change needed.
+            return;
+        }
+        // Prefer the opener tab if it's still around. If not, pick the most
+        // recently opened survivor (closest in time to the just-closed one).
+        let fallbackId = rec.parentId && this.tabs.has(rec.parentId) ? rec.parentId : null;
+        if (!fallbackId && this.tabs.size > 0) {
+            let newest = null;
+            for (const t of this.tabs.values()) {
+                if (!newest || t.openedAt > newest.openedAt)
+                    newest = t;
+            }
+            fallbackId = newest?.id ?? null;
+        }
+        if (fallbackId) {
+            await this.setActiveTab(fallbackId);
+        }
+        else {
+            this.activeTabId = null;
+            if (isDebugEnabled()) {
+                console.error(`      [tabs] all tabs closed; no active page remains`);
+            }
+        }
+    }
+}