@trusty-squire/mcp 1.1.13 → 1.1.14-rc.10

package/dist/bot/compact-observation-v2.js

@@ -1,35 +1,169 @@
 import { Buffer } from "node:buffer";
+import { createHmac, randomBytes } from "node:crypto";
 export const OBSERVE_V2_MAX_WIRE_BYTES = 4_096;
 export const OBSERVE_V2_MAX_TOKENS = 1_024;
-const FIRST_PAGE_ROW_LIMIT = 4;
 export function compactV2PayloadWithinBudget(payload) {
     const bytes = Buffer.byteLength(JSON.stringify(payload), "utf8");
-    return bytes <= OBSERVE_V2_MAX_WIRE_BYTES && bytes <= OBSERVE_V2_MAX_TOKENS;
+    if (bytes > OBSERVE_V2_MAX_WIRE_BYTES)
+        return false;
+    // Token estimate at the ~4 bytes/token the wire's enum-only prose runs.
+    // Comparing raw BYTES against the token cap (the old behavior) made the
+    // effective budget 1024 bytes, so a real-world OAuth-shaped URL alone
+    // hard-failed observation — the live "compact-v2 budget metadata exceeded"
+    // session killer. The byte cap bounds the MCP message; the token cap bounds
+    // model context, and both now scale with the page instead of strangling it.
+    return Math.ceil(bytes / 4) <= OBSERVE_V2_MAX_TOKENS;
 }
 /**
- * Semantic essentials are sticky across V2 deltas. A repeat observation only
- * needs to carry them when their already-sealed representation changed; the
- * consumer retains the prior title/heading just like it retains safe_table.
+ * Graceful degradation for a payload whose FIXED metadata (url, semantic
+ * context, start hints) alone exceeds the wire budget. Degrades in order:
+ * shrink the URL, drop the semantic title/heading, drop start-routing hints —
+ * never the safe_table rows or the overflow cursor, which are the actionable
+ * map. Returns null only when code-owned fields (session id / cursor) are
+ * themselves hostile, which the caller fails closed on.
  */
-export function equalSafePageSemanticsV2(left, right) {
-    return left.title === right.title && (left.headings?.[0] ?? "") === (right.headings?.[0] ?? "");
+export function compactV2DegradeMetadata(payload) {
+    if (compactV2PayloadWithinBudget(payload))
+        return payload;
+    let candidate = payload;
+    for (const urlCap of [512, 128]) {
+        const url = typeof candidate.url === "string" ? candidate.url : "";
+        if (url.length > urlCap)
+            candidate = { ...candidate, url: url.slice(0, urlCap) };
+        if (compactV2PayloadWithinBudget(candidate))
+            return candidate;
+    }
+    if ("semantic" in candidate) {
+        const rest = { ...candidate };
+        delete rest.semantic;
+        candidate = rest;
+        if (compactV2PayloadWithinBudget(candidate))
+            return candidate;
+    }
+    if ("hint" in candidate || "user_email" in candidate || "hint_overflow" in candidate) {
+        const rest = { ...candidate };
+        delete rest.hint;
+        delete rest.user_email;
+        delete rest.hint_overflow;
+        candidate = rest;
+        if (compactV2PayloadWithinBudget(candidate))
+            return candidate;
+    }
+    return null;
 }
-/** `@e:` + a truncated session-secret HMAC of (document epoch, fingerprint). */
-export const COMPACT_V2_HANDLE_LENGTH = 10;
+export const COMPACT_V2_HANDLE_LENGTH = 22;
 const COMPACT_V2_HANDLE_RE = new RegExp(`^@e:[A-Za-z0-9_-]{${COMPACT_V2_HANDLE_LENGTH}}$`);
-const COMPACT_V2_LABEL_RE = /^@[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export class StableObservationRefs {
+    secret;
+    document;
+    generation = 0;
+    refs = new Map();
+    identities = new Map();
+    anchors = new Map();
+    aliases = new Map();
+    aliasOwners = new Map();
+    reset(document) {
+        if (this.document === document)
+            return;
+        this.document = document;
+        this.generation++;
+        this.refs.clear();
+        this.identities.clear();
+        this.anchors.clear();
+        this.aliases.clear();
+        this.aliasOwners.clear();
+    }
+    /** Reconcile the full live inventory, retiring absent or materially changed nodes. */
+    actions(document, elements) {
+        this.reset(document);
+        const present = new Set(elements.map((el) => el.observationIdentity));
+        for (const identity of this.anchors.keys()) {
+            if (!present.has(identity))
+                this.anchors.delete(identity);
+        }
+        const counts = new Map();
+        for (const el of elements) {
+            if (el.observationIdentity)
+                counts.set(el.observationIdentity, (counts.get(el.observationIdentity) ?? 0) + 1);
+        }
+        const handles = new Map();
+        for (const el of elements) {
+            const identity = el.observationIdentity;
+            if (!identity || el.observationIntent === undefined || counts.get(identity) !== 1) {
+                if (identity)
+                    this.anchors.delete(identity);
+                continue;
+            }
+            let anchor = this.anchors.get(identity);
+            if (!anchor || anchor.intent !== el.observationIntent) {
+                anchor = {
+                    intent: el.observationIntent,
+                    ref: this.get(document, `action:${randomBytes(32).toString("base64url")}`),
+                };
+                this.anchors.set(identity, anchor);
+            }
+            handles.set(el, anchor.ref);
+        }
+        return handles;
+    }
+    /** Compatibility spelling of one capability; never reassign an old alias. */
+    label(ref, preferred) {
+        const existing = this.aliases.get(ref);
+        if (existing !== undefined || preferred === undefined)
+            return existing;
+        let candidate = preferred;
+        for (let suffix = 2; this.aliasOwners.has(candidate); suffix++)
+            candidate = labelWithOrdinalV2(preferred, suffix);
+        this.aliases.set(ref, candidate);
+        this.aliasOwners.set(candidate, ref);
+        return candidate;
+    }
+    constructor(secret = randomBytes(32)) {
+        this.secret = secret;
+    }
+    get(document, identity) {
+        this.reset(document);
+        let ref = this.refs.get(identity);
+        if (ref === undefined) {
+            for (let collision = 0;; collision++) {
+                const candidate = `@e:${createHmac("sha256", this.secret)
+                    .update(document)
+                    .update("\u0000")
+                    .update(String(this.generation))
+                    .update("\u0000")
+                    .update(identity)
+                    .update("\u0000")
+                    .update(String(collision))
+                    .digest("base64url")
+                    .slice(0, COMPACT_V2_HANDLE_LENGTH)}`;
+                const owner = this.identities.get(candidate);
+                if (owner === undefined || owner === identity) {
+                    ref = candidate;
+                    this.identities.set(ref, identity);
+                    break;
+                }
+            }
+            this.refs.set(identity, ref);
+        }
+        return ref;
+    }
+}
+const LABEL_MAX_CHARS = 32;
+const COMPACT_V2_LABEL_RE = /^@[\p{L}\p{M}\p{N}]+(?:-[\p{L}\p{M}\p{N}]+)*(?:…)?$/u;
 export function isCompactV2Handle(target) {
     return COMPACT_V2_HANDLE_RE.test(target);
 }
 /** The `@label` alias form, distinguishable from a handle by its `@e:` prefix. */
 export function isCompactV2Label(target) {
-    return COMPACT_V2_LABEL_RE.test(target);
+    return (COMPACT_V2_LABEL_RE.test(target) &&
+        /[\p{L}\p{N}]/u.test(target) &&
+        Array.from(target.slice(1)).length <= LABEL_MAX_CHARS);
 }
 /**
  * Resolve a handle only when it is well-formed AND a member of the current
- * snapshot's sealed map. Callers must never turn an unknown @e: value into a
+ * snapshot's action map. Callers must never turn an unknown @e: value into a
  * label or legacy-ref lookup. The handle is document-scoped by construction
- * (the epoch is hashed into it), so a ref from a replaced document finds no
+ * (the allocator retires its document map), so a ref from a replaced document finds no
  * live match rather than resolving onto whatever now occupies its position.
  */
 export function compactV2LegacyRefForHandle(handles, target) {
@@ -37,22 +171,92 @@ export function compactV2LegacyRefForHandle(handles, target) {
         return null;
     return handles.get(target) ?? null;
 }
-const LABEL_MAX_CHARS = 32;
 /**
- * The addressable alias for a screened control description. Slugified so the
- * agent can type it back verbatim; `undefined` when the description screened
- * out or carries no alphanumeric content.
+ * Split a glued "Title + description" accessible name into its leading title,
+ * detected from the ORIGINAL name — by slug time the boundary is gone. The
+ * 2026-09-06 ipinfo docs dogfood produced labels like
+ * `@database-downloadsdownload-ip-da`: two headings (or a heading and its
+ * description) concatenated by the DOM with no whitespace, slugified into one
+ * unreadable run and hard-cut mid-word. The boundaries that mark that seam in
+ * the original name are:
+ * - a newline inside the accessible name,
+ * - sentence/heading punctuation (`.` `!` `?` `:` `)`) directly abutting the
+ *   next word (`(Search Ctrl+K)Navigation`, `Docs.Start here`) — a period
+ *   followed by a lowercase letter ("Node.js") is NOT a boundary,
+ * - a lowercase→uppercase case transition where two headings were joined
+ *   with no space (`DownloadsDownload`).
+ * Returns the original name when no qualifying boundary is found, so ordinary
+ * multi-word names and short glued pairs keep their full slug.
  */
+function leadingTitleFromAccessibleName(name) {
+    // A candidate title must read as a heading — multi-word, or a substantial
+    // standalone word — so camelCase identifiers ("myAccountSettings") and
+    // abbreviation fragments ("U.S. Government") keep their full slug, and a
+    // real description must remain behind the seam.
+    const readsAsHeading = (title) => /[A-Za-z0-9]/.test(title) && (title.includes(" ") || title.length >= 5);
+    const hasDescription = (rest) => /[A-Za-z0-9].*[A-Za-z0-9]/.test(rest);
+    for (let i = 0; i < name.length - 1; i += 1) {
+        const ch = name[i];
+        const next = name[i + 1];
+        if (ch === "\n") {
+            if (readsAsHeading(name.slice(0, i)) && hasDescription(name.slice(i + 1))) {
+                return name.slice(0, i);
+            }
+            continue;
+        }
+        if (".!?:)".includes(ch) && /[A-Za-z0-9]/.test(next)) {
+            // A period followed by a lowercase letter is an abbreviation
+            // ("Node.js"), not a heading seam; require an uppercase letter (or a
+            // closing parenthesis, which abuts a seam regardless of case).
+            if ((ch === ")" || /[A-Z]/.test(next)) && hasDescription(name.slice(i + 1))) {
+                const title = name.slice(0, i);
+                if (readsAsHeading(title))
+                    return title;
+            }
+            continue;
+        }
+        if (/[a-z]/.test(ch) && /[A-Z]/.test(next)) {
+            const title = name.slice(0, i + 1);
+            if (readsAsHeading(title) && hasDescription(name.slice(i + 1)))
+                return title;
+        }
+    }
+    return name;
+}
+/** Addressable slug of the page's control description, with the existing title and length limits. */
 export function controlLabelV2(description) {
     if (description === undefined)
         return undefined;
-    const slug = description
+    const titled = leadingTitleFromAccessibleName(description);
+    let slug = titled
+        .normalize("NFKC")
         .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, LABEL_MAX_CHARS)
-        .replace(/-+$/g, "");
-    return slug.length === 0 ? undefined : `@${slug}`;
+        .replace(/[^\p{L}\p{M}\p{N}]+/gu, "-")
+        .replace(/^-+|-+$/gu, "");
+    let characters = Array.from(slug);
+    const truncated = characters.length > LABEL_MAX_CHARS;
+    const usesUnicode = characters.some((character) => character.charCodeAt(0) > 0x7f);
+    if (truncated) {
+        characters = characters.slice(0, LABEL_MAX_CHARS - Number(usesUnicode));
+        // Never cut mid-word: drop the trailing partial segment at the last word
+        // boundary. A single unbroken run longer than the budget keeps its
+        // mid-run cut — there is no boundary to cut on.
+        const lastBoundary = characters.lastIndexOf("-");
+        if (lastBoundary > 0)
+            characters = characters.slice(0, lastBoundary);
+    }
+    slug = characters.join("").replace(/-+$/g, "");
+    if (slug.length === 0 || !/[\p{L}\p{N}]/u.test(slug))
+        return undefined;
+    return `@${slug}${truncated && usesUnicode ? "…" : ""}`;
+}
+function labelWithOrdinalV2(label, suffix) {
+    const tail = `-${suffix}`;
+    const characters = Array.from(label.slice(1));
+    const truncated = characters.length > LABEL_MAX_CHARS - Array.from(tail).length || characters.at(-1) === "…";
+    const body = truncated ? characters.slice(0, -1) : characters;
+    const limit = LABEL_MAX_CHARS - Array.from(tail).length - Number(truncated);
+    return `@${body.slice(0, limit).join("")}${tail}${truncated ? "…" : ""}`;
 }
 // The protocol is intentionally positional to keep repeated observes small.
 // Tuple schema: [ref, role(b/l/t/s/c/r/tb/m/f), optional compact description].
@@ -61,7 +265,7 @@ export function controlLabelV2(description) {
 // is deliberately one sparse string rather than nullable columns:
 // checked/unchecked, disabled, action, field, card choice, and frame context
 // remain distinguishable without paying for empty slots on every row. The
-// label's slug charset excludes `|` and `=`, so no escaping is needed.
+// label grammar excludes `|` and `=`, so no escaping is needed.
 function wireControl(row) {
     const role = {
         button: "b",
@@ -293,6 +497,15 @@ export function recordableTokenV2(value) {
  * rejects nothing: the truncation is the compactness budget, not redaction.
  */
 export function safeDescriptionV2(value) {
+    const normalized = normalizeDescriptionV2(value);
+    if (normalized === undefined)
+        return undefined;
+    return normalized.length <= SAFE_DESCRIPTION_MAX_CHARS
+        ? normalized
+        : `${normalized.slice(0, SAFE_DESCRIPTION_MAX_CHARS - 1)}…`;
+}
+/** Normalize page descriptions without applying the query row's length limit. */
+export function normalizeDescriptionV2(value) {
     if (typeof value !== "string")
         return undefined;
     // Control characters would break the positional wire encoding; they are not
@@ -301,11 +514,7 @@ export function safeDescriptionV2(value) {
         .replace(/[\p{Cc}\p{Cf}]/gu, " ")
         .replace(/\s+/g, " ")
         .trim();
-    if (normalized.length === 0)
-        return undefined;
-    return normalized.length <= SAFE_DESCRIPTION_MAX_CHARS
-        ? normalized
-        : `${normalized.slice(0, SAFE_DESCRIPTION_MAX_CHARS - 1)}…`;
+    return normalized.length === 0 ? undefined : normalized;
 }
 const SAFE_AUTOCOMPLETE_TOKENS = new Set([
     "address-level1",
@@ -545,7 +754,7 @@ export function sealRetainedInteractiveElementsV2(elements, selectorFor = () =>
 export function safePageSemanticsV2(source) {
     const title = safeDescriptionV2(source.title);
     const headings = source.headings
-        .map((heading) => safeDescriptionV2(heading))
+        .map(safeDescriptionV2)
         .filter((value) => value !== undefined)
         .filter((value, index, all) => all.indexOf(value) === index)
         .slice(0, 1);
@@ -554,48 +763,6 @@ export function safePageSemanticsV2(source) {
         ...(headings.length === 0 ? {} : { headings }),
     };
 }
-/**
- * Diff only the sealed representation.  In particular, raw changes to a
- * field value, card number, live region, or merchant copy cannot cause either
- * the raw data or a page-derived derivative to cross into the delta.
- */
-export function diffSafeControlsV2(previous, stage, rows) {
-    const current = new Map(rows.map((row) => [row.ref, row]));
-    const added = [];
-    const changed = [];
-    for (const row of rows) {
-        const before = previous.byRef.get(row.ref);
-        if (before === undefined)
-            added.push(row);
-        else if (JSON.stringify(wireControl(before)) !== JSON.stringify(wireControl(row)))
-            changed.push(row);
-    }
-    const removed = [...previous.byRef.keys()].filter((ref) => !current.has(ref));
-    return { added, changed, removed, stageChanged: previous.stage !== stage };
-}
-/**
- * Encodes a structural V2 delta. `null` deliberately asks the caller to send
- * a paged full resync instead: a delta must never exceed the hard wire budget.
- */
-export function encodeV2Delta(args) {
-    const payload = {
-        format: "compact-v2",
-        url: args.pageUrl ?? "",
-        text: "",
-        session_id: args.sessionId,
-        delta: true,
-        ...(args.semantics === undefined ? {} : { semantic: args.semantics }),
-        ...(args.delta.stageChanged ? { stage: args.stage } : {}),
-        // `safe_table` follows the established TS delta protocol: rows are
-        // upserts, irrespective of whether their ref is new or changed. This keeps
-        // existing delta consumers compatible while the @e: map itself stays V2.
-        ...(args.delta.added.length + args.delta.changed.length > 0
-            ? { safe_table: [...args.delta.added, ...args.delta.changed].map(wireControl) }
-            : {}),
-        ...(args.delta.removed.length > 0 ? { removed: args.delta.removed } : {}),
-    };
-    return compactV2PayloadWithinBudget(payload) ? payload : null;
-}
 const INTENTS = [
     ["add_to_cart", /add\s+(?:to\s+)?(?:cart|bag|basket)/i],
     ["view_cart", /view\s+(?:cart|bag|basket)/i],
@@ -626,6 +793,41 @@ function controlNamingTexts(el) {
         isButtonInput(el) ? el.value : undefined,
     ];
 }
+function controlLabelNamingTexts(el) {
+    const role = roleOf(el);
+    const names = el.compactNames;
+    if (names) {
+        const accessibleName = normalizeDescriptionV2(names.accessibleName);
+        const visibleText = normalizeDescriptionV2(names.visibleText);
+        const iconLabel = normalizeDescriptionV2(names.iconLabel);
+        const aggregateIconName = visibleText !== undefined &&
+            iconLabel !== undefined &&
+            accessibleName === `${iconLabel} ${visibleText}`;
+        return [
+            aggregateIconName ? undefined : names.accessibleName,
+            names.ariaLabel,
+            names.labelledByText,
+            names.labelText,
+            (el.type ?? "").toLowerCase() === "image" ? names.alt : undefined,
+            names.visibleText,
+            isButtonInput(el) ? names.value : undefined,
+            names.iconLabel,
+            names.title,
+            role === "textbox" ? names.placeholder : undefined,
+            role === "textbox" ? names.name : undefined,
+        ];
+    }
+    return [
+        el.ariaLabel,
+        el.labelText,
+        el.visibleText,
+        isButtonInput(el) ? el.value : undefined,
+        el.iconLabel,
+        el.title,
+        role === "textbox" ? el.placeholder : undefined,
+        role === "textbox" ? el.name : undefined,
+    ];
+}
 function candidateTexts(el) {
     return [
         el.visibleText,
@@ -645,12 +847,53 @@ function candidateTexts(el) {
 function candidateText(el) {
     return candidateTexts(el).join(" ");
 }
-function controlDescription(el) {
-    // Labels are chosen from visible/accessibility naming sources only. Native
-    // button values are names; field values, `name`, and `id` stay excluded.
-    return controlNamingTexts(el)
-        .map((candidate) => safeDescriptionV2(candidate))
+function controlDescription(el, role) {
+    // Prefer authored accessibility names over descendant text. Navigation
+    // toggles and data-row controls often contain an entire menu/card subtree;
+    // choosing textContent first turned their concise aria/label name into a
+    // mashed-together alias. Native button values are names, while field values
+    // and ids remain excluded. Textbox placeholder/name are useful only after
+    // the genuine accessibility and visible-name sources have been exhausted.
+    const chosen = controlLabelNamingTexts(el)
+        .map((candidate) => normalizeDescriptionV2(candidate))
         .find((candidate) => candidate !== undefined);
+    if (chosen !== undefined) {
+        // Add the page's region context to otherwise opaque labels (such as @as15169).
+        const context = regionContextV2(el.compactNames ? el.compactNames.container : el.container, chosen);
+        const description = context === undefined ? chosen : `${chosen} ${context}`;
+        if (controlLabelV2(description) !== undefined)
+            return description;
+    }
+    // Every actionable row still needs a human-usable alias. The nearest
+    // semantic region is the best available immediate context; a genuinely
+    // anonymous control falls back to its role rather than becoming a bare
+    // [ref, role] tuple. This is descriptive only and does not alter identity.
+    const context = namedContainerContextV2(el.compactNames ? el.compactNames.container : el.container);
+    return context === undefined ? `${role} ${el.index + 1}` : `${context} ${role}`;
+}
+/** A description is "uninformative" when it carries no 3+-letter word run: ids, short codes, hex fragments. */
+function isUninformativeDescriptionV2(description) {
+    return (!/[a-zA-Z]{3,}/.test(description) &&
+        !Array.from(description).some((character) => character.charCodeAt(0) > 0x7f && /\p{L}/u.test(character)));
+}
+function regionContextV2(container, chosen) {
+    if (container === null || container === undefined)
+        return undefined;
+    if (!isUninformativeDescriptionV2(chosen))
+        return undefined;
+    const context = namedContainerContextV2(container);
+    if (context === undefined)
+        return undefined;
+    return context.slice(0, 24).replace(/-+$/, "") || undefined;
+}
+function namedContainerContextV2(container) {
+    if (container === null || container === undefined)
+        return undefined;
+    const separator = container.indexOf(":");
+    const kind = separator < 0 ? undefined : container.slice(0, separator).toLowerCase();
+    const raw = separator < 0 ? container : container.slice(separator + 1);
+    const context = safeDescriptionV2(raw.replace(/[-_]+/g, " "));
+    return context === undefined || context.toLowerCase() === kind ? undefined : context;
 }
 function privateQueryTokenV2(value) {
     const normalized = value.normalize("NFKC").trim().toLowerCase();
@@ -679,21 +922,40 @@ export function controlMatchesPrivateQueryV2(el, query) {
     const needles = privateQueryTermsV2(query);
     if (needles === null)
         return false;
-    // The private match also consults the element's name/id slugs so
-    // choice-group members without their own copy — Shopify shipping-rate
-    // radios (name "checkout[shipping_rate][id]", id "checkout_shipping_rate_…")
-    // — stay queryable. These are DOM identifiers, never field values, and each
-    // candidate still passes the full secret-shape gate below before any token
-    // comparison.
-    return [...controlNamingTexts(el), el.name, el.id].some((candidate) => {
-        if (typeof candidate !== "string")
-            return false;
+    // AND-match every needle against the COMBINED token set across all naming
+    // sources — visible text, label, aria label, icon, title, placeholder,
+    // value, plus name/id slugs (so choice-group members without their own copy
+    // — Shopify shipping-rate radios — stay queryable; these are DOM
+    // identifiers, never field values) and the control's own role word.
+    // Requiring each needle to hit ONE source (the old behavior) made generic
+    // multi-term queries — "region dropdown" for a combobox labeled "Region",
+    // "use case textbox" for a textarea — return empty on real pages.
+    const role = roleOf(el);
+    const candidates = [
+        ...controlNamingTexts(el),
+        el.name,
+        el.id,
+        role,
+    ];
+    const combined = new Set();
+    for (const candidate of candidates) {
+        if (typeof candidate !== "string" || candidate.length === 0)
+            continue;
         const tokens = candidate.normalize("NFKC").match(/[\p{L}\p{M}\p{N}]{1,48}/gu);
         if (tokens === null)
-            return false;
-        const safeTokens = new Set(tokens.map(privateQueryTokenV2).filter((token) => token !== null));
-        return needles.every((needle) => safeTokens.has(needle));
-    });
+            continue;
+        for (const token of tokens) {
+            const safe = privateQueryTokenV2(token);
+            if (safe !== null)
+                combined.add(safe);
+        }
+    }
+    if (role === "select") {
+        // Common spoken words for the wire role keep role-term queries reachable.
+        combined.add("dropdown");
+        combined.add("combobox");
+    }
+    return needles.every((needle) => combined.has(needle));
 }
 function roleOf(el) {
     const role = (el.role ?? "").toLowerCase();
@@ -894,14 +1156,54 @@ function frameOf(el, pageOrigin) {
         return "main";
     return el.frameOrigin === pageOrigin ? "same_origin" : "cross_origin";
 }
+/**
+ * Deterministically disambiguate duplicate labels within one snapshot. The
+ * /dashboard/token dogfood returned two distinct rows both labelled
+ * `@curl-example` with nothing to tell them apart — a correct pick was a coin
+ * flip. The first occurrence keeps the plain label; the second and later
+ * occurrences get a stable ordinal suffix (`@curl-example-2`, `-3`, …)
+ * following the map's own row order, so the same page always yields the same
+ * numbering. A suffix that would collide with an existing label (the page
+ * itself rendering "curl example 2" alongside two "curl example" rows) is
+ * skipped, so disambiguation never mints a new ambiguity.
+ */
+export function disambiguateDuplicateLabelsV2(labels) {
+    const occurrences = new Map();
+    for (const label of labels) {
+        if (label === undefined)
+            continue;
+        occurrences.set(label, (occurrences.get(label) ?? 0) + 1);
+    }
+    const assigned = new Set();
+    for (const label of labels)
+        if (label !== undefined)
+            assigned.add(label);
+    const seen = new Map();
+    return labels.map((label) => {
+        if (label === undefined)
+            return undefined;
+        const occurrence = (seen.get(label) ?? 0) + 1;
+        seen.set(label, occurrence);
+        if (occurrence === 1)
+            return label;
+        let suffix = occurrence;
+        let candidate = labelWithOrdinalV2(label, suffix);
+        while (assigned.has(candidate)) {
+            suffix += 1;
+            candidate = labelWithOrdinalV2(label, suffix);
+        }
+        assigned.add(candidate);
+        return candidate;
+    });
+}
 export function buildSafeControlsV2(args) {
     const rows = [];
     const paymentContext = checkoutStageFromUrlV2(args.pageUrl ?? "") !== null ||
         args.elements.some((element) => hasExplicitPaymentFieldSignal(element));
     for (const el of args.elements) {
-        if (el.visible !== true || el.topmost === false)
+        if (el.visible !== true || (!args.canonical && el.topmost === false))
             continue;
-        const role = roleOf(el);
+        const role = roleOf(el) ?? (args.canonical ? "button" : null);
         const legacy = args.legacyRefs.get(el);
         const ref = args.handles.get(el);
         if (role === null || legacy === undefined || ref === undefined)
@@ -914,7 +1216,7 @@ export function buildSafeControlsV2(args) {
         // already CDP-derived interactive inventory supplies each visible control's
         // descendant/accessibility name. This pass binds that name to its own live
         // element, so no cross-serializer tag/role fallback can swap labels.
-        const label = controlLabelV2(controlDescription(el));
+        const label = controlLabelV2(controlDescription(el, role));
         const row = {
             role,
             visibility: el.inViewport ? "viewport" : "near",
@@ -939,80 +1241,22 @@ export function buildSafeControlsV2(args) {
         });
     }
     rows.sort((a, b) => a.priority - b.priority || a.legacy.localeCompare(b.legacy));
+    // The legacy fallback disambiguates after final ordering. Compact-v2 supplies
+    // anchorLabel instead, reserving each alias for its physical-node capability.
+    const disambiguated = disambiguateDuplicateLabelsV2(rows.map(({ row }) => row.label));
     const byRef = new Map();
-    const safeRows = rows.map(({ ref, legacy, row }) => {
+    const safeRows = rows.map(({ ref, legacy, row }, position) => {
+        const label = args.anchorLabel ? args.anchorLabel(ref, row.label) : disambiguated[position];
         byRef.set(ref, legacy);
-        return { ref, ...row };
+        return { ref, ...row, ...(label === undefined ? {} : { label }) };
     });
     return { rows: safeRows, byRef };
 }
-export function encodeV2Page(args) {
+export function encodeV2QueryPage(args) {
     const offset = args.offset ?? 0;
-    if (args.unchanged === true && offset === 0) {
-        const payload = {
-            format: "compact-v2",
-            url: args.pageUrl ?? "",
-            text: "",
-            session_id: args.sessionId,
-            stage: args.stage,
-            ...(args.startMetadata?.hint === undefined ? {} : { hint: args.startMetadata.hint }),
-            ...(args.startMetadata?.userEmail === undefined
-                ? {}
-                : { user_email: args.startMetadata.userEmail }),
-            ...(args.startMetadata?.hintOverflow === undefined
-                ? {}
-                : { hint_overflow: args.startMetadata.hintOverflow }),
-            ...(args.semantics === undefined || Object.keys(args.semantics).length === 0
-                ? {}
-                : { semantic: args.semantics }),
-            delta: true,
-        };
-        if (!compactV2PayloadWithinBudget(payload)) {
-            throw new Error("compact-v2 budget metadata exceeded");
-        }
-        return {
-            payload,
-            nextOffset: 0,
-        };
-    }
-    const visible = [];
-    // Initial observations stay decisively small. Overflow is retrieved through
-    // the in-MCP query cursor, never a shell-readable snapshot file.
-    const pageEnd = offset === 0 ? Math.min(args.rows.length, FIRST_PAGE_ROW_LIMIT) : args.rows.length;
-    for (let index = offset; index < pageEnd; index += 1) {
-        const candidate = args.rows[index];
-        const remainder = args.rows.length - (index + 1);
-        const payload = {
-            format: "compact-v2",
-            url: args.pageUrl ?? "",
-            text: "",
-            session_id: args.sessionId,
-            stage: args.stage,
-            ...(args.startMetadata?.hint === undefined ? {} : { hint: args.startMetadata.hint }),
-            ...(args.startMetadata?.userEmail === undefined
-                ? {}
-                : { user_email: args.startMetadata.userEmail }),
-            ...(args.startMetadata?.hintOverflow === undefined
-                ? {}
-                : { hint_overflow: args.startMetadata.hintOverflow }),
-            ...(args.semantics === undefined || Object.keys(args.semantics).length === 0
-                ? {}
-                : { semantic: args.semantics }),
-            safe_table: [...visible, wireControl(candidate)],
-            ...(remainder > 0
-                ? { overflow: { remaining: remainder, next_cursor: args.cursorFor(index + 1) } }
-                : {}),
-        };
-        if (!compactV2PayloadWithinBudget(payload))
-            break;
-        visible.push(wireControl(candidate));
-    }
-    const nextOffset = offset + visible.length;
-    const remaining = args.rows.length - nextOffset;
-    const payload = {
-        format: "compact-v2",
+    let fixed = {
+        format: "browser-use-control-query",
         url: args.pageUrl ?? "",
-        text: "",
         session_id: args.sessionId,
         stage: args.stage,
         ...(args.startMetadata?.hint === undefined ? {} : { hint: args.startMetadata.hint }),
@@ -1025,13 +1269,58 @@ export function encodeV2Page(args) {
         ...(args.semantics === undefined || Object.keys(args.semantics).length === 0
             ? {}
             : { semantic: args.semantics }),
-        safe_table: visible,
-        ...(remaining > 0 ? { overflow: { remaining, next_cursor: args.cursorFor(nextOffset) } } : {}),
     };
-    // The fixed fields are deliberately tiny, so failure means a hostilely long
-    // session id/cursor. Fail closed rather than exceeding the wire contract.
+    const pageWith = (table, nextOffset) => {
+        const remaining = args.rows.length - nextOffset;
+        return {
+            ...fixed,
+            safe_table: table,
+            ...(remaining > 0
+                ? { overflow: { remaining, next_cursor: args.cursorFor(nextOffset) } }
+                : {}),
+        };
+    };
+    if (offset < args.rows.length) {
+        const probe = pageWith([wireControl(args.rows[offset])], offset + 1);
+        if (!compactV2PayloadWithinBudget(probe)) {
+            const degraded = compactV2DegradeMetadata(probe);
+            if (degraded === null)
+                throw new Error("compact-v2 budget metadata exceeded");
+            const degradedFixed = { ...degraded };
+            delete degradedFixed.safe_table;
+            delete degradedFixed.overflow;
+            fixed = degradedFixed;
+        }
+    }
+    const visible = [];
+    // Every interactive control is a candidate for the default map: rows are
+    // packed in priority order until the wire budget is actually reached, so a
+    // below-the-fold primary CTA is never stranded behind an arbitrary row cap
+    // (the live Xata failure). Overflow remains reachable through the in-MCP
+    // query cursor, never a shell-readable snapshot file.
+    let nextOffset = offset;
+    for (let index = offset; index < args.rows.length; index += 1) {
+        const candidate = wireControl(args.rows[index]);
+        if (!compactV2PayloadWithinBudget(pageWith([...visible, candidate], index + 1)))
+            break;
+        visible.push(candidate);
+        nextOffset = index + 1;
+    }
+    if (visible.length === 0 && offset < args.rows.length) {
+        // Budget-driven packing must never emit an empty page whose cursor points
+        // back at the same offset. Force the first row in and let fixed metadata
+        // degrade around it — on a real page this is unreachable.
+        visible.push(wireControl(args.rows[offset]));
+        nextOffset = offset + 1;
+    }
+    let payload = pageWith(visible, nextOffset);
     if (!compactV2PayloadWithinBudget(payload)) {
-        throw new Error("compact-v2 budget metadata exceeded");
+        // Only hostile fixed metadata (a code-owned session id/cursor) lands here;
+        // degrade the metadata before ever dropping an actionable row.
+        const degraded = compactV2DegradeMetadata(payload);
+        if (degraded === null)
+            throw new Error("compact-v2 budget metadata exceeded");
+        payload = degraded;
     }
     return { payload, nextOffset };
 }