pi-agent-browser-native 0.2.48 → 0.2.49

package/dist/extensions/agent-browser/lib/results/recovery-actions.js

@@ -0,0 +1,107 @@
+/**
+ * Purpose: Centralize recovery-oriented nextAction ids and action construction.
+ * Responsibilities: Build tab/about:blank/no-active-page/connected-session follow-ups and rich-input recovery ids.
+ * Scope: Recovery action contracts only; result category classification and artifact follow-ups live elsewhere.
+ * Usage: Imported by shared result action builders and the extension entrypoint.
+ * Invariants/Assumptions: Ids are public machine-readable contracts mirrored by docs and tests.
+ */
+import { buildNextToolAction, withOptionalSessionArgs } from "./next-actions.js";
+export const AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS = {
+    aboutBlankListTabs: "list-tabs-for-about-blank-recovery",
+    connectedSessionListTabs: "list-connected-session-tabs",
+    genericTabDriftListTabs: "list-tabs-for-recovery",
+    noActivePageListTabs: "list-tabs-after-no-active-page",
+    selectIntendedTabAfterDrift: "select-intended-tab-after-drift",
+    snapshotAfterTabRecovery: "snapshot-after-tab-recovery",
+    tabDriftListTabs: "list-tabs-for-tab-drift-recovery",
+};
+export const AGENT_BROWSER_RICH_INPUT_RECOVERY_NEXT_ACTION_IDS = {
+    click: "click-current-editable-ref",
+    focus: "focus-current-editable-ref",
+};
+function getNumberedAgentBrowserNextActionId(baseId, index, total) {
+    return total > 1 ? `${baseId}-${index + 1}` : baseId;
+}
+export function getAgentBrowserRichInputRecoveryNextActionId(kind, index, candidateCount) {
+    return getNumberedAgentBrowserNextActionId(AGENT_BROWSER_RICH_INPUT_RECOVERY_NEXT_ACTION_IDS[kind], index, candidateCount);
+}
+export function getAgentBrowserRichInputRecoveryNextActionIds(candidateCount) {
+    const ids = [];
+    for (let index = 0; index < candidateCount; index += 1) {
+        ids.push(getAgentBrowserRichInputRecoveryNextActionId("focus", index, candidateCount), getAgentBrowserRichInputRecoveryNextActionId("click", index, candidateCount));
+    }
+    return ids;
+}
+function getRecoveryTargetDescription(recovery) {
+    const target = [recovery.targetTitle, recovery.targetUrl].filter((item) => item !== undefined && item.length > 0).join(" at ");
+    return target.length > 0 ? target : "the intended tab";
+}
+function isStableTabId(tab) {
+    return /^t\d+$/.test(tab ?? "");
+}
+function buildTabSnapshotRecoveryAction(options) {
+    if (options.recovery.recoveryApplied === true) {
+        return buildNextToolAction({
+            args: options.sessionArgs(["snapshot", "-i"]),
+            id: options.id,
+            reason: options.reason,
+            safety: options.safety,
+        });
+    }
+    return buildNextToolAction({
+        args: options.sessionArgs(["batch"]),
+        id: options.id,
+        reason: `${options.reason} The batch selects the stable tab before snapshotting.`,
+        safety: `${options.safety} The snapshot retry is atomic with tab selection, so it does not assume the intended tab is already active.`,
+        stdin: JSON.stringify([["tab", options.tabId], ["snapshot", "-i"]]),
+    });
+}
+export function buildRecoveryNextActions(recovery) {
+    const sessionArgs = (args) => withOptionalSessionArgs(recovery.sessionName, args);
+    if (recovery.kind === "connected-session") {
+        return [
+            buildNextToolAction({
+                args: sessionArgs(["tab", "list"]),
+                id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.connectedSessionListTabs,
+                reason: "Inspect tabs exposed by the connected CDP endpoint before assuming the app surface is active.",
+                safety: "Read-only. Raw connect can succeed before the desktop app has an active rendered page.",
+            }),
+        ];
+    }
+    if (recovery.kind === "no-active-page") {
+        return [
+            buildNextToolAction({
+                args: sessionArgs(["tab", "list"]),
+                id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.noActivePageListTabs,
+                reason: "The snapshot found no active page; inspect the session tabs before retrying refs.",
+                safety: "Read-only tab listing for the same connected session.",
+            }),
+        ];
+    }
+    const targetDescription = getRecoveryTargetDescription(recovery);
+    const listAction = buildNextToolAction({
+        args: sessionArgs(["tab", "list"]),
+        id: recovery.kind === "about-blank" ? AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.aboutBlankListTabs : AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.tabDriftListTabs,
+        reason: `Inspect tabs for ${targetDescription} before continuing after tab drift.`,
+        safety: "Read-only tab listing; prefer stable tN tab ids over positional tab guesses.",
+    });
+    if (!isStableTabId(recovery.selectedTab))
+        return [listAction];
+    return [
+        listAction,
+        buildNextToolAction({
+            args: sessionArgs(["tab", recovery.selectedTab]),
+            id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.selectIntendedTabAfterDrift,
+            reason: `Re-select ${targetDescription} with the stable tab id already observed by the wrapper.`,
+            safety: "Switches only the active tab in this browser session; it does not mutate page content.",
+        }),
+        buildTabSnapshotRecoveryAction({
+            id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.snapshotAfterTabRecovery,
+            reason: "Refresh interactive refs on the recovered tab before using @e refs again.",
+            recovery,
+            safety: "Read-only snapshot. Treat previous refs as stale until this succeeds.",
+            sessionArgs,
+            tabId: recovery.selectedTab,
+        }),
+    ];
+}

package/dist/extensions/agent-browser/lib/results/recovery-next-actions.js

@@ -0,0 +1,50 @@
+/**
+ * Purpose: Build session-aware recovery nextActions that combine result category policy with known session/tab context.
+ * Responsibilities: Prefix recovery argv with the active session and adapt tab/about:blank/no-active/stale-ref contexts into stable nextAction lists.
+ * Scope: Recovery nextAction assembly only; diagnostic detection and action-list merge ordering stay in the extension entrypoint.
+ * Usage: Imported by the extension entrypoint when adding recovery nextActions to tool details.
+ * Invariants/Assumptions: Action ids and argv ordering are public contracts; session prefixing must not double-prefix explicit --session args.
+ */
+import { buildAgentBrowserNextActions } from "./action-recommendations.js";
+import { withOptionalSessionArgs } from "./next-actions.js";
+export function buildConnectedSessionNextActions(sessionName) {
+    if (!sessionName)
+        return [];
+    return buildAgentBrowserNextActions({
+        recovery: { kind: "connected-session", sessionName },
+        resultCategory: "success",
+        successCategory: "completed",
+    }) ?? [];
+}
+export function buildNoActivePageNextActions(sessionName) {
+    if (!sessionName)
+        return [];
+    return buildAgentBrowserNextActions({
+        recovery: { kind: "no-active-page", sessionName },
+        resultCategory: "failure",
+    }) ?? [];
+}
+export function buildSessionTabRecoveryNextActions(options) {
+    const resultCategory = options.resultCategory ?? "success";
+    return buildAgentBrowserNextActions({
+        recovery: {
+            kind: options.kind,
+            recoveryApplied: options.recoveryApplied,
+            selectedTab: options.tabCorrection?.selectedTab,
+            sessionName: options.sessionName,
+            targetTitle: options.tabCorrection?.targetTitle ?? options.target?.title,
+            targetUrl: options.tabCorrection?.targetUrl ?? options.target?.url,
+        },
+        resultCategory,
+        successCategory: resultCategory === "success" ? "completed" : undefined,
+    }) ?? [];
+}
+export function buildSessionAwareStaleRefNextActions(sessionName) {
+    return (buildAgentBrowserNextActions({ failureCategory: "stale-ref", resultCategory: "failure" }) ?? []).map((action) => {
+        const actionArgs = action.params?.args;
+        return {
+            ...action,
+            params: action.params && actionArgs ? { ...action.params, args: withOptionalSessionArgs(sessionName, actionArgs) } : action.params,
+        };
+    });
+}

package/dist/extensions/agent-browser/lib/results/selector-recovery.js

@@ -0,0 +1,225 @@
+/**
+ * Purpose: Own pure selector-miss recovery diagnostics for visible refs and rich editable inputs.
+ * Responsibilities: Parse find/semantic action targets, match current snapshot refs, build public diagnostics, text, and safe nextActions.
+ * Scope: Selector recovery policy only; subprocess snapshot probing and result orchestration stay in the extension entrypoint.
+ * Usage: The extension entrypoint supplies command tokens plus snapshot data after a selector-not-found failure.
+ * Invariants/Assumptions: Public fill recovery must never echo or auto-submit the user-provided fill text; guarded semanticAction fill pre-resolution may execute only one exact current editable ref.
+ */
+import { isRecord } from "../parsing.js";
+import { extractRefSnapshotFromData } from "../session-page-state.js";
+import { getEditableRefEvidence } from "./editable-ref-evidence.js";
+import { withOptionalSessionArgs } from "./next-actions.js";
+import { getAgentBrowserRichInputRecoveryNextActionId, getAgentBrowserRichInputRecoveryNextActionIds, } from "./recovery-actions.js";
+import { getSnapshotLineTextByRef, getSnapshotRefRecord, getSnapshotRefRole, } from "./snapshot-refs.js";
+import { compareRefIds } from "./text.js";
+const SELECTOR_RECOVERY_ACTION_NAMES = new Set(["check", "click", "fill", "select", "uncheck"]);
+const VISIBLE_REF_FALLBACK_CANDIDATE_LIMIT = 3;
+const EDITABLE_CONTROL_ROLES = new Set(["combobox", "searchbox", "textbox"]);
+const RICH_INPUT_RECOVERY_EDITABLE_ROLES = new Set(["searchbox", "textbox"]);
+const RICH_INPUT_RECOVERY_HINT = "After the editable ref is focused, use keyboard inserttext or keyboard type with the intended text in a separate call, and do not press Enter or otherwise submit unless the user flow explicitly calls for it.";
+function isSelectorRecoveryActionName(action) {
+    return SELECTOR_RECOVERY_ACTION_NAMES.has(action);
+}
+function getFindNameFlagValue(args, startIndex) {
+    const nameFlagIndex = args.indexOf("--name", startIndex);
+    const name = nameFlagIndex >= 0 ? args[nameFlagIndex + 1] : undefined;
+    return name && !name.startsWith("-") ? name : undefined;
+}
+function getFindVisibleRefFallbackTarget(args, options = {}) {
+    const findIndex = args[0] === "--session" ? 2 : 0;
+    if (args[findIndex] !== "find")
+        return undefined;
+    const locator = args[findIndex + 1];
+    const value = args[findIndex + 2];
+    const action = args[findIndex + 3];
+    if (!locator || !value || !isSelectorRecoveryActionName(action) || action === "select")
+        return undefined;
+    const text = action === "fill" ? args[findIndex + 4] : undefined;
+    if (action === "fill" && (!text || (!options.allowLeadingDashFillText && text.startsWith("-"))))
+        return undefined;
+    if (locator === "role") {
+        const targetName = getFindNameFlagValue(args, findIndex + 4);
+        return targetName ? { action, roles: [value], targetName, text } : undefined;
+    }
+    if (locator === "text" && action === "click") {
+        return { action, roles: ["button", "link"], targetName: value };
+    }
+    if (locator === "text" && action === "fill") {
+        return { action, roles: ["searchbox", "textbox"], targetName: value, text };
+    }
+    if (locator === "label" && action === "fill") {
+        return { action, roles: ["textbox"], targetName: value, text };
+    }
+    if (locator === "placeholder" && action === "fill") {
+        return { action, roles: ["searchbox", "textbox"], targetName: value, text };
+    }
+    return undefined;
+}
+export function getVisibleRefFallbackTarget(options) {
+    return getFindVisibleRefFallbackTarget(options.commandTokens, { allowLeadingDashFillText: true }) ?? (options.compiledSemanticAction ? getFindVisibleRefFallbackTarget(options.compiledSemanticAction.args, { allowLeadingDashFillText: true }) : undefined);
+}
+function getVisibleRefFallbackCandidates(target, snapshotData) {
+    const refs = getSnapshotRefRecord(snapshotData);
+    if (!refs)
+        return [];
+    const snapshotLineByRef = getSnapshotLineTextByRef(snapshotData);
+    const roleOrder = target.roles.map((role) => role.toLowerCase());
+    const targetName = normalizeSemanticActionAccessibleName(target.targetName);
+    const candidates = Object.entries(refs).flatMap(([ref, entry]) => {
+        if (!/^e\d+$/.test(ref) || !isRecord(entry))
+            return [];
+        const snapshotLine = snapshotLineByRef.get(ref);
+        const editableEvidence = getEditableRefEvidence({ ref: entry, text: snapshotLine });
+        const role = getSnapshotRefRole(entry, editableEvidence);
+        const name = typeof entry.name === "string" ? entry.name : undefined;
+        if (!role || !name || !roleOrder.includes(role.toLowerCase()) || normalizeSemanticActionAccessibleName(name) !== targetName)
+            return [];
+        if (target.action === "fill" && editableEvidence === false && EDITABLE_CONTROL_ROLES.has(role.toLowerCase()))
+            return [];
+        const directRefArgs = target.action === "fill" ? undefined : [target.action, `@${ref}`];
+        return [{
+                action: target.action,
+                ...(directRefArgs ? { args: directRefArgs } : {}),
+                name,
+                reason: `Current snapshot shows ${role} ${JSON.stringify(name)} at @${ref}, matching the failed ${target.action} locator exactly.`,
+                ref: `@${ref}`,
+                role,
+                ...(editableEvidence !== undefined ? { editableEvidence } : {}),
+            }];
+    });
+    candidates.sort((left, right) => roleOrder.indexOf(left.role.toLowerCase()) - roleOrder.indexOf(right.role.toLowerCase()) || compareRefIds(left.ref.slice(1), right.ref.slice(1)));
+    return candidates.slice(0, VISIBLE_REF_FALLBACK_CANDIDATE_LIMIT);
+}
+export function buildVisibleRefFallbackDiagnosticFromSnapshot(options) {
+    const snapshot = extractRefSnapshotFromData(options.snapshotData);
+    if (!snapshot)
+        return undefined;
+    const candidates = getVisibleRefFallbackCandidates(options.target, options.snapshotData);
+    if (candidates.length === 0)
+        return undefined;
+    return {
+        candidates,
+        snapshot,
+        summary: candidates.length === 1
+            ? `Current snapshot has one exact visible ref match for ${options.target.action} ${JSON.stringify(options.target.targetName)}.`
+            : `Current snapshot has ${candidates.length} exact visible ref matches for ${options.target.action} ${JSON.stringify(options.target.targetName)}; choose only if the intended control is unambiguous.`,
+        target: { action: options.target.action, roles: options.target.roles, targetName: options.target.targetName },
+    };
+}
+export function resolveVisibleRefActionFromSnapshot(options) {
+    const target = getFindVisibleRefFallbackTarget(options.compiledAction.args, { allowLeadingDashFillText: true });
+    if (!target || target.action === "select")
+        return undefined;
+    const snapshot = extractRefSnapshotFromData(options.snapshotData);
+    if (!snapshot)
+        return undefined;
+    const candidates = getVisibleRefFallbackCandidates(target, options.snapshotData);
+    if (target.action === "fill") {
+        if (!options.allowFill || candidates.length !== 1 || target.text === undefined)
+            return undefined;
+        const [candidate] = candidates;
+        if (!candidate || candidate.editableEvidence === false || !EDITABLE_CONTROL_ROLES.has(candidate.role.toLowerCase()))
+            return undefined;
+        return { args: ["fill", candidate.ref, target.text], snapshot };
+    }
+    const candidate = candidates.find((item) => item.args !== undefined);
+    if (!candidate?.args)
+        return undefined;
+    return { args: candidate.args, snapshot };
+}
+export function buildVisibleRefFallbackNextActions(options) {
+    const ambiguous = options.diagnostic.candidates.length > 1;
+    return options.diagnostic.candidates.flatMap((candidate, index) => candidate.args ? [{
+            id: ambiguous ? `try-current-visible-ref-${index + 1}` : "try-current-visible-ref",
+            params: { args: withOptionalSessionArgs(options.sessionName, candidate.args) },
+            reason: candidate.reason,
+            safety: ambiguous
+                ? "Several current refs share the same exact role/name. Inspect the snapshot and use only the ref that clearly matches the intended target."
+                : "Use only while this current snapshot still represents the page; refresh refs first if the page changed.",
+            tool: "agent_browser",
+        }] : []);
+}
+export function formatVisibleRefFallbackText(diagnostic) {
+    if (!diagnostic)
+        return undefined;
+    return [
+        "Current snapshot ref fallback:",
+        ...diagnostic.candidates.map((candidate) => `- ${candidate.ref}${candidate.role ? ` ${candidate.role}` : ""} ${JSON.stringify(candidate.name)}: ${candidate.reason}`),
+    ].join("\n");
+}
+export function sanitizeVisibleRefFallbackDiagnostic(diagnostic) {
+    return {
+        candidates: diagnostic.candidates.map(({ editableEvidence: _editableEvidence, ...candidate }) => candidate),
+        snapshot: diagnostic.snapshot,
+        summary: diagnostic.summary,
+        target: diagnostic.target,
+    };
+}
+function isRichInputRecoveryCandidate(candidate) {
+    return candidate.action === "fill" && candidate.editableEvidence !== false && RICH_INPUT_RECOVERY_EDITABLE_ROLES.has(candidate.role.toLowerCase());
+}
+export function buildRichInputRecoveryDiagnostic(diagnostic) {
+    if (!diagnostic || diagnostic.target.action !== "fill")
+        return undefined;
+    const candidates = diagnostic.candidates.filter(isRichInputRecoveryCandidate).map((candidate) => ({
+        clickArgs: ["click", candidate.ref],
+        focusArgs: ["focus", candidate.ref],
+        name: candidate.name,
+        reason: `Current snapshot shows editable ${candidate.role} ${JSON.stringify(candidate.name)} at ${candidate.ref}; focus or click it before keyboard insertion instead of retrying fill with copied text.`,
+        ref: candidate.ref,
+        role: candidate.role,
+    }));
+    if (candidates.length === 0)
+        return undefined;
+    return {
+        candidates,
+        inputMethodHint: RICH_INPUT_RECOVERY_HINT,
+        nextActionIds: getAgentBrowserRichInputRecoveryNextActionIds(candidates.length),
+        summary: candidates.length === 1
+            ? "Fill locator missed, but the current snapshot has one exact editable ref candidate for safe keyboard-based recovery."
+            : `Fill locator missed, but the current snapshot has ${candidates.length} exact editable ref candidates; choose only if the intended input is unambiguous.`,
+        target: { roles: diagnostic.target.roles, targetName: diagnostic.target.targetName },
+    };
+}
+export function buildRichInputRecoveryNextActions(options) {
+    const candidateCount = options.diagnostic.candidates.length;
+    const ambiguous = candidateCount > 1;
+    return options.diagnostic.candidates.flatMap((candidate, index) => {
+        const focusId = getAgentBrowserRichInputRecoveryNextActionId("focus", index, candidateCount);
+        const clickId = getAgentBrowserRichInputRecoveryNextActionId("click", index, candidateCount);
+        const safety = ambiguous
+            ? `Several editable refs share the same exact name. Inspect the current snapshot and use only the ${candidate.ref} ${candidate.role} if it is clearly the intended input. No fill text or submit key is included.`
+            : "Does not include fill text or submit the form. After focus/click succeeds, use keyboard inserttext or keyboard type with the intended text only if this is the right input.";
+        return [
+            {
+                id: focusId,
+                params: { args: withOptionalSessionArgs(options.sessionName, candidate.focusArgs) },
+                reason: candidate.reason,
+                safety,
+                tool: "agent_browser",
+            },
+            {
+                id: clickId,
+                params: { args: withOptionalSessionArgs(options.sessionName, candidate.clickArgs) },
+                reason: `Click ${candidate.ref} to focus the editable ${candidate.role} before keyboard insertion when focus alone is insufficient.`,
+                safety: `${safety} A click may run normal focus/click handlers, but this action does not press Enter or auto-submit.`,
+                tool: "agent_browser",
+            },
+        ];
+    });
+}
+export function formatRichInputRecoveryText(diagnostic) {
+    if (!diagnostic)
+        return undefined;
+    return [
+        "Rich input recovery:",
+        ...diagnostic.candidates.map((candidate, index) => {
+            const [focusId, clickId] = diagnostic.nextActionIds.slice(index * 2, index * 2 + 2);
+            return `- ${candidate.ref} ${candidate.role} ${JSON.stringify(candidate.name)}: use ${focusId} or ${clickId}; then use keyboard inserttext/type with the intended text.`;
+        }),
+        `- ${diagnostic.inputMethodHint}`,
+    ].join("\n");
+}
+export function normalizeSemanticActionAccessibleName(name) {
+    return name.replace(/\s+/g, " ").trim().toLowerCase();
+}

package/{extensions/agent-browser/lib/results/shared.ts → dist/extensions/agent-browser/lib/results/shared.js}

@@ -5,7 +5,6 @@
  * Usage: Existing internal imports may keep using this path during migration, while new code should prefer focused modules.
  * Invariants/Assumptions: This file intentionally contains no business logic so `shared` cannot grow back into a catch-all module.
  */
-
 export * from "./contracts.js";
 export * from "./categories.js";
 export * from "./action-recommendations.js";

package/dist/extensions/agent-browser/lib/results/snapshot-high-value-controls.js

@@ -0,0 +1,208 @@
+/**
+ * Purpose: Select the omitted snapshot refs most likely to be actionable controls.
+ * Responsibilities: Classify editable, surface, primary-action, and role-based control refs with deterministic diversity and top-up rules.
+ * Scope: High-value control ranking only; snapshot parsing, noise filtering, and presentation text live in neighboring modules.
+ * Usage: Snapshot presentation passes already-visible, non-noise omitted refs and receives the bounded high-value subset to surface.
+ * Invariants/Assumptions: Ranking must preserve scarce control categories before filling dominant buckets so dense desktop hosts stay navigable.
+ */
+import { compareRefIds } from "./text.js";
+const SNAPSHOT_HIGH_VALUE_EDITABLE_REF_FILL_TARGET_LINES = 4;
+const SNAPSHOT_HIGH_VALUE_SURFACE_REF_FILL_TARGET_LINES = 3;
+const SNAPSHOT_HIGH_VALUE_PRIMARY_ACTION_REF_FILL_TARGET_LINES = 3;
+const SNAPSHOT_HIGH_VALUE_CONTROL_ROLES = new Set([
+    "button",
+    "checkbox",
+    "combobox",
+    "link",
+    "menuitem",
+    "option",
+    "radio",
+    "searchbox",
+    "tab",
+    "textbox",
+]);
+const SNAPSHOT_HIGH_VALUE_CONTROL_ROLE_PRIORITY = {
+    searchbox: 0,
+    textbox: 1,
+    combobox: 2,
+    button: 3,
+    link: 4,
+    tab: 5,
+    checkbox: 6,
+    radio: 7,
+    option: 8,
+    menuitem: 9,
+};
+const SNAPSHOT_SURFACE_CONTROL_NAME_PATTERNS = [
+    /\b(?:agents?|browser|canvas|chat|editor|panel|pane|preview|surface|tab|terminal|thread|view|window|workspace)\b/i,
+];
+const SNAPSHOT_PRIMARY_ACTION_BUTTON_NAME_PATTERNS = [
+    /^(?:add|apply|ask|attach|choose|confirm|connect|continue|create|deploy|done|download|go|insert|launch|log in|new|next|ok|open|publish|refresh|retry|run|save|search|select|send|sign in|sign up|start|submit|upload)$/i,
+    /^(?:add|apply|ask|confirm|connect|continue|create|launch|new|open|refresh|retry|run|save|search|send|start|submit)\b/i,
+];
+const SNAPSHOT_HIGH_VALUE_LINK_NAME_PATTERNS = [
+    /^[a-z0-9_.-]+\/[a-z0-9_.-]+$/i,
+];
+function getHighValueControlRole(entry) {
+    return entry.isEditable === true && (entry.role === "unknown" || entry.role === "generic") ? "textbox" : entry.role;
+}
+function isEditableControlRef(entry) {
+    if (entry.isEditable === false)
+        return false;
+    const role = getHighValueControlRole(entry);
+    return entry.isEditable === true || role === "searchbox" || role === "textbox" || role === "combobox";
+}
+function isNamedSurfaceControlRef(entry) {
+    if (entry.name.length === 0)
+        return false;
+    const role = getHighValueControlRole(entry);
+    if (role === "tab")
+        return true;
+    if (role !== "button" && role !== "menuitem" && role !== "option")
+        return false;
+    return SNAPSHOT_SURFACE_CONTROL_NAME_PATTERNS.some((pattern) => pattern.test(entry.name));
+}
+function isPrimaryActionButtonRef(entry) {
+    return (getHighValueControlRole(entry) === "button" &&
+        entry.name.length > 0 &&
+        SNAPSHOT_PRIMARY_ACTION_BUTTON_NAME_PATTERNS.some((pattern) => pattern.test(entry.name)));
+}
+const SNAPSHOT_HIGH_VALUE_CONTROL_CATEGORY_RULES = [
+    {
+        bucketKey: () => "editable",
+        fillTarget: SNAPSHOT_HIGH_VALUE_EDITABLE_REF_FILL_TARGET_LINES,
+        id: "editable",
+        matches: (entry) => isEditableControlRef(entry),
+        priority: 0,
+    },
+    {
+        bucketKey: () => "named-surface",
+        fillTarget: SNAPSHOT_HIGH_VALUE_SURFACE_REF_FILL_TARGET_LINES,
+        id: "named-surface",
+        matches: (entry) => isNamedSurfaceControlRef(entry),
+        priority: 1,
+    },
+    {
+        bucketKey: () => "primary-action",
+        fillTarget: SNAPSHOT_HIGH_VALUE_PRIMARY_ACTION_REF_FILL_TARGET_LINES,
+        id: "primary-action",
+        matches: (entry) => isPrimaryActionButtonRef(entry),
+        priority: 2,
+    },
+    {
+        bucketKey: (_entry, role) => role,
+        id: "role",
+        matches: () => true,
+        priority: 3,
+    },
+];
+function isHighValueLinkRef(entry) {
+    return entry.name.length > 0 && SNAPSHOT_HIGH_VALUE_LINK_NAME_PATTERNS.some((pattern) => pattern.test(entry.name));
+}
+export function isHighValueControlEntry(entry) {
+    const role = getHighValueControlRole(entry);
+    if (!SNAPSHOT_HIGH_VALUE_CONTROL_ROLES.has(role))
+        return false;
+    if (role === "link")
+        return isHighValueLinkRef(entry);
+    if (entry.isEditable === false && (role === "searchbox" || role === "textbox" || role === "combobox"))
+        return false;
+    return entry.name.length > 0 || isEditableControlRef(entry);
+}
+function getHighValueControlCategoryRule(entry, role) {
+    return SNAPSHOT_HIGH_VALUE_CONTROL_CATEGORY_RULES.find((rule) => rule.matches(entry, role));
+}
+function classifyHighValueControlRef(entry) {
+    if (!isHighValueControlEntry(entry))
+        return undefined;
+    const role = getHighValueControlRole(entry);
+    const rule = getHighValueControlCategoryRule(entry, role);
+    if (!rule)
+        return undefined;
+    return {
+        entry,
+        score: {
+            category: rule.id,
+            categoryPriority: rule.priority,
+            diversityBucketKey: `${rule.priority}:${rule.bucketKey(entry, role)}`,
+            lineIndex: entry.lineIndex ?? Number.MAX_SAFE_INTEGER,
+            namePriority: entry.name.length > 0 ? 0 : 1,
+            refId: entry.id,
+            role,
+            rolePriority: SNAPSHOT_HIGH_VALUE_CONTROL_ROLE_PRIORITY[role] ?? 50,
+            roundRobinBucketKey: `${rule.priority}:${role}`,
+        },
+    };
+}
+function compareHighValueControlCandidates(left, right) {
+    return (left.score.categoryPriority - right.score.categoryPriority ||
+        left.score.rolePriority - right.score.rolePriority ||
+        left.score.namePriority - right.score.namePriority ||
+        left.score.lineIndex - right.score.lineIndex ||
+        compareRefIds(left.score.refId, right.score.refId));
+}
+function takeHighValueCandidate(candidate, selected, selectedIds) {
+    selected.push(candidate);
+    selectedIds.add(candidate.entry.id);
+}
+function takeFirstPerDiversityBucket(candidates, selected, selectedIds, limit) {
+    const seenBuckets = new Set();
+    for (const candidate of candidates) {
+        if (selected.length >= limit)
+            break;
+        if (seenBuckets.has(candidate.score.diversityBucketKey))
+            continue;
+        seenBuckets.add(candidate.score.diversityBucketKey);
+        takeHighValueCandidate(candidate, selected, selectedIds);
+    }
+}
+function topUpHighValueCategory(candidates, selected, selectedIds, category, target, limit) {
+    let count = selected.filter((candidate) => candidate.score.category === category).length;
+    for (const candidate of candidates) {
+        if (selected.length >= limit || count >= target)
+            break;
+        if (selectedIds.has(candidate.entry.id) || candidate.score.category !== category)
+            continue;
+        takeHighValueCandidate(candidate, selected, selectedIds);
+        count += 1;
+    }
+}
+function buildRemainingHighValueBuckets(candidates, selectedIds) {
+    const buckets = new Map();
+    for (const candidate of candidates) {
+        if (selectedIds.has(candidate.entry.id))
+            continue;
+        const bucket = buckets.get(candidate.score.roundRobinBucketKey);
+        if (bucket)
+            bucket.push(candidate);
+        else
+            buckets.set(candidate.score.roundRobinBucketKey, [candidate]);
+    }
+    return [...buckets.values()].sort((left, right) => compareHighValueControlCandidates(left[0], right[0]));
+}
+function roundRobinHighValueBuckets(buckets, selected, selectedIds, limit) {
+    let bucketIndex = 0;
+    while (selected.length < limit && buckets.some((bucket) => bucket.length > 0)) {
+        const bucket = buckets[bucketIndex % buckets.length];
+        const candidate = bucket.shift();
+        if (candidate)
+            takeHighValueCandidate(candidate, selected, selectedIds);
+        bucketIndex += 1;
+    }
+}
+export function selectHighValueControlEntries(entries, limit) {
+    const candidates = entries
+        .map(classifyHighValueControlRef)
+        .filter((candidate) => Boolean(candidate))
+        .sort(compareHighValueControlCandidates);
+    const selected = [];
+    const selectedIds = new Set();
+    takeFirstPerDiversityBucket(candidates, selected, selectedIds, limit);
+    for (const rule of SNAPSHOT_HIGH_VALUE_CONTROL_CATEGORY_RULES) {
+        if (rule.fillTarget === undefined)
+            continue;
+        topUpHighValueCategory(candidates, selected, selectedIds, rule.id, rule.fillTarget, limit);
+    }
+    roundRobinHighValueBuckets(buildRemainingHighValueBuckets(candidates, selectedIds), selected, selectedIds, limit);
+    return selected.map((candidate) => candidate.entry);
+}