@mercuryo-ai/agentbrowse 0.2.60 → 0.2.63

package/dist/commands/observe-signals.d.ts

@@ -1,4 +1,4 @@
-import type { Frame } from 'playwright-core';
+import type { ObservedFrameLike } from './observe-inventory.js';
 export type ObservedPageSignal = {
     kind: 'status' | 'alert' | 'dialog' | 'notice' | 'outcome';
     text: string;
@@ -7,7 +7,7 @@ export type ObservedPageSignal = {
     source: 'dom';
 };
 type SignalCollectionContext = {
-    evaluate<T>(pageFunction: string): Promise<T>;
+    evaluate(pageFunction: string): Promise<unknown>;
 };
 export declare function inferObservedSignalKindFromFacts(facts: {
     role?: string;
@@ -34,8 +34,8 @@ declare function collectPageSignalsFromDocument(context: SignalCollectionContext
     frameUrl?: string;
 }): Promise<ObservedPageSignal[]>;
 export declare function collectPageSignals(page: {
-    evaluate<T>(pageFunction: string): Promise<T>;
-    mainFrame?: () => Frame;
+    evaluate(pageFunction: string): Promise<unknown>;
+    mainFrame?: () => ObservedFrameLike;
 }): Promise<ObservedPageSignal[]>;
 export declare const __testObserveSignals: {
     collectPageSignalsFromDocument: typeof collectPageSignalsFromDocument;

package/dist/commands/observe-signals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observe-signals.d.ts","sourceRoot":"","sources":["../../src/commands/observe-signals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAG7C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,KAAK,CAAC;CACf,CAAC;AAEF,KAAK,uBAAuB,GAAG;IAC7B,QAAQ,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC/C,CAAC;AAQF,wBAAgB,gCAAgC,CAAC,KAAK,EAAE;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAuB7B;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAQ7E;AAED,wBAAgB,uCAAuC,CAAC,KAAK,EAAE;IAC7D,+BAA+B,CAAC,EAAE,OAAO,CAAC;IAC1C,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,OAAO,CAQV;AAED,wBAAgB,mCAAmC,CAAC,KAAK,EAAE;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,+BAA+B,CAAC,EAAE,OAAO,CAAC;IAC1C,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAoBV;AAqCD,iBAAe,8BAA8B,CAC3C,OAAO,EAAE,uBAAuB,EAChC,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAwU/B;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,QAAQ,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9C,SAAS,CAAC,EAAE,MAAM,KAAK,CAAC;CACzB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA0DhC;AAED,eAAO,MAAM,oBAAoB;;;;;;CAMhC,CAAC"}
+{"version":3,"file":"observe-signals.d.ts","sourceRoot":"","sources":["../../src/commands/observe-signals.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,KAAK,CAAC;CACf,CAAC;AAEF,KAAK,uBAAuB,GAAG;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAClD,CAAC;AAQF,wBAAgB,gCAAgC,CAAC,KAAK,EAAE;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAuB7B;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAQ7E;AAED,wBAAgB,uCAAuC,CAAC,KAAK,EAAE;IAC7D,+BAA+B,CAAC,EAAE,OAAO,CAAC;IAC1C,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,OAAO,CAQV;AAED,wBAAgB,mCAAmC,CAAC,KAAK,EAAE;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,+BAA+B,CAAC,EAAE,OAAO,CAAC;IAC1C,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAoBV;AAqCD,iBAAe,8BAA8B,CAC3C,OAAO,EAAE,uBAAuB,EAChC,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAwU/B;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,SAAS,CAAC,EAAE,MAAM,iBAAiB,CAAC;CACrC,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA0DhC;AAED,eAAO,MAAM,oBAAoB;;;;;;CAMhC,CAAC"}

package/dist/commands/observe-signals.js

@@ -84,7 +84,7 @@ function applyInheritedSignalMetadata(signal, options) {
 async function collectPageSignalsFromDocument(context, options) {
     const inheritedFramePath = JSON.stringify(options?.framePath ?? []);
     const inheritedFrameUrl = JSON.stringify(options?.frameUrl ?? '');
-    const observedSignals = await context.evaluate(String.raw `(() => {
+    const observedSignals = (await context.evaluate(String.raw `(() => {
     const inheritedFramePath = ${inheritedFramePath};
     const inheritedFrameUrl = ${inheritedFrameUrl};
     const limit = ${DOM_SIGNAL_COLLECTION_LIMIT};
@@ -387,7 +387,7 @@ async function collectPageSignalsFromDocument(context, options) {
     }
 
     return signals;
-  })()`);
+  })()`));
     if (!Array.isArray(observedSignals)) {
         return [];
     }

package/dist/commands/observe-surfaces.d.ts

@@ -3,8 +3,9 @@ import type { DomObservedTarget } from './observe-inventory.js';
 export declare const OUTPUT_LEADING_TARGET_LIMIT = 20;
 export declare function selectScopesForOutput(scopes: ReadonlyArray<SurfaceDescriptor>, targets: ReadonlyArray<Pick<TargetDescriptor, 'surfaceRef' | 'allowedActions' | 'acceptancePolicy'>>, preferredScopeRefs?: ReadonlySet<string>): SurfaceDescriptor[];
 export declare function buildSurfaceRef(target: DomObservedTarget): string | undefined;
+export declare function buildExplicitSurfaceRef(target: DomObservedTarget): string | undefined;
 export declare function buildSyntheticFormSurfaceId(target: Pick<DomObservedTarget, 'pageSignature' | 'framePath' | 'frameUrl' | 'formSelector' | 'context'>): string | undefined;
-export declare function surfaceReplacementKey(surface: Pick<SurfaceDescriptor, 'pageRef' | 'pageSignature' | 'framePath' | 'kind' | 'label'>): string;
+export declare function surfaceReplacementKey(surface: Pick<SurfaceDescriptor, 'surfaceId' | 'pageRef' | 'pageSignature' | 'framePath' | 'kind' | 'label'>): string;
 export declare function summarizeContext(context: TargetContext | undefined): string | undefined;
 export declare function pushUniqueLocatorCandidate(acc: LocatorCandidate[], candidate: LocatorCandidate | undefined): void;
 export declare function collectSurfaceDescriptors(pageRef: string, targets: ReadonlyArray<DomObservedTarget>): Omit<SurfaceDescriptor, "ref">[];

package/dist/commands/observe-surfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observe-surfaces.d.ts","sourceRoot":"","sources":["../../src/commands/observe-surfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AA6BhE,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAkB9C,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,aAAa,CAAC,iBAAiB,CAAC,EACxC,OAAO,EAAE,aAAa,CACpB,IAAI,CAAC,gBAAgB,EAAE,YAAY,GAAG,gBAAgB,GAAG,kBAAkB,CAAC,CAC7E,EACD,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GACvC,iBAAiB,EAAE,CAsErB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAa7E;AAyBD,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,IAAI,CACV,iBAAiB,EACjB,eAAe,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,GAAG,SAAS,CACxE,GACA,MAAM,GAAG,SAAS,CAkBpB;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,SAAS,GAAG,eAAe,GAAG,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC,GAC7F,MAAM,CAMR;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CA8BvF;AAED,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,gBAAgB,EAAE,EACvB,SAAS,EAAE,gBAAgB,GAAG,SAAS,GACtC,IAAI,CAON;AAwDD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,oCAyE1C"}
+{"version":3,"file":"observe-surfaces.d.ts","sourceRoot":"","sources":["../../src/commands/observe-surfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AA6BhE,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAoC9C,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,aAAa,CAAC,iBAAiB,CAAC,EACxC,OAAO,EAAE,aAAa,CACpB,IAAI,CAAC,gBAAgB,EAAE,YAAY,GAAG,gBAAgB,GAAG,kBAAkB,CAAC,CAC7E,EACD,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GACvC,iBAAiB,EAAE,CAsErB;AAgCD,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAS7E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CASrF;AAyBD,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,IAAI,CACV,iBAAiB,EACjB,eAAe,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,GAAG,SAAS,CACxE,GACA,MAAM,GAAG,SAAS,CAkBpB;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,IAAI,CACX,iBAAiB,EACjB,WAAW,GAAG,SAAS,GAAG,eAAe,GAAG,WAAW,GAAG,MAAM,GAAG,OAAO,CAC3E,GACA,MAAM,CAYR;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CA8BvF;AAED,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,gBAAgB,EAAE,EACvB,SAAS,EAAE,gBAAgB,GAAG,SAAS,GACtC,IAAI,CAON;AAqGD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,oCA4F1C"}

package/dist/commands/observe-surfaces.js

@@ -25,6 +25,17 @@ const SNAPSHOT_SCOPE_KINDS = new Set([
     'sticky-panel',
 ]);
 export const OUTPUT_LEADING_TARGET_LIMIT = 20;
+const EXPLICIT_PARENT_SCOPE_KINDS = new Set(HIGH_SIGNAL_SCOPE_KINDS);
+function collectLinkedScopeRefsForOutput(targets) {
+    const linkedScopeRefs = new Set();
+    for (const target of targets) {
+        const surfaceRef = target.surfaceRef;
+        if (typeof surfaceRef === 'string' && surfaceRef.length > 0) {
+            linkedScopeRefs.add(surfaceRef);
+        }
+    }
+    return linkedScopeRefs;
+}
 function inferExtractScopeLifetime(kind, locatorCandidates) {
     const normalizedKind = (kind ?? '').trim().toLowerCase();
     if (SNAPSHOT_SCOPE_KINDS.has(normalizedKind)) {
@@ -39,10 +50,7 @@ export function selectScopesForOutput(scopes, targets, preferredScopeRefs) {
     if (scopes.length === 0) {
         return [];
     }
-    const linkedScopeRefs = new Set(targets
-        .slice(0, OUTPUT_LEADING_TARGET_LIMIT)
-        .map((target) => target.surfaceRef)
-        .filter((value) => typeof value === 'string' && value.length > 0));
+    const linkedScopeRefs = collectLinkedScopeRefsForOutput(targets);
     const explicitlyPreferredScopeRefs = new Set([...(preferredScopeRefs ?? [])].filter((value) => typeof value === 'string' && value.length > 0));
     const scopeByRef = new Map(scopes.map((scope) => [scope.ref, scope]));
     const includedScopeRefs = new Set([...linkedScopeRefs, ...explicitlyPreferredScopeRefs]);
@@ -52,8 +60,13 @@ export function selectScopesForOutput(scopes, targets, preferredScopeRefs) {
             if (includedScopeRefs.has(parentSurfaceRef)) {
                 break;
             }
+            const parentScope = scopeByRef.get(parentSurfaceRef);
+            const parentKind = (parentScope?.kind ?? '').toLowerCase();
+            if (!EXPLICIT_PARENT_SCOPE_KINDS.has(parentKind)) {
+                break;
+            }
             includedScopeRefs.add(parentSurfaceRef);
-            parentSurfaceRef = scopeByRef.get(parentSurfaceRef)?.parentSurfaceRef;
+            parentSurfaceRef = parentScope?.parentSurfaceRef;
         }
     }
     const scored = scopes
@@ -94,18 +107,42 @@ export function selectScopesForOutput(scopes, targets, preferredScopeRefs) {
     }
     return [];
 }
-export function buildSurfaceRef(target) {
-    if (!target.surfaceKind && !target.surfaceSelector && !target.surfaceLabel) {
+function buildStableSurfaceId(input) {
+    if (!input.surfaceKind && !input.surfaceSelector && !input.surfaceLabel) {
         return undefined;
     }
-    const frameKey = target.framePath?.join('>') ?? 'top';
-    return [
-        target.pageSignature ?? 'unknown-page',
-        frameKey,
-        target.surfaceKind ?? 'surface',
-        target.surfaceSelector ?? '',
-        target.surfaceLabel ?? '',
-    ].join('|');
+    const frameKey = input.framePath?.join('>') ??
+        (normalizeSurfaceText(input.frameUrl) ? `url:${normalizeSurfaceText(input.frameUrl)}` : 'top');
+    const pageKey = normalizeSurfaceText(input.pageSignature) ?? 'unknown-page';
+    const selectorKey = normalizeSurfaceText(input.surfaceSelector);
+    if (selectorKey) {
+        return `${pageKey}|${frameKey}|surface|${selectorKey}`;
+    }
+    const kindKey = normalizeSurfaceText(input.surfaceKind)?.toLowerCase() ?? 'surface';
+    const labelKey = normalizeSurfaceText(input.surfaceLabel)?.toLowerCase();
+    return labelKey
+        ? `${pageKey}|${frameKey}|${kindKey}|${labelKey}`
+        : `${pageKey}|${frameKey}|${kindKey}`;
+}
+export function buildSurfaceRef(target) {
+    return buildStableSurfaceId({
+        pageSignature: target.pageSignature,
+        framePath: target.framePath,
+        frameUrl: target.frameUrl,
+        surfaceKind: target.surfaceKind,
+        surfaceSelector: target.surfaceSelector,
+        surfaceLabel: target.surfaceLabel,
+    });
+}
+export function buildExplicitSurfaceRef(target) {
+    return buildStableSurfaceId({
+        pageSignature: target.pageSignature,
+        framePath: target.framePath,
+        frameUrl: target.frameUrl,
+        surfaceKind: target.explicitSurfaceKind,
+        surfaceSelector: target.explicitSurfaceSelector,
+        surfaceLabel: target.explicitSurfaceLabel,
+    });
 }
 function normalizeSurfaceText(value) {
     const normalized = value?.replace(/\s+/g, ' ').trim();
@@ -146,6 +183,12 @@ export function surfaceReplacementKey(surface) {
     const frameKey = surface.framePath?.join('>') ?? 'top';
     const kindKey = (surface.kind ?? 'surface').toLowerCase();
     const labelKey = (surface.label ?? '').trim().toLowerCase();
+    if (HIGH_SIGNAL_SCOPE_KINDS.has(kindKey) && labelKey) {
+        return `${pageKey}|${frameKey}|${kindKey}|${labelKey}`;
+    }
+    if (surface.surfaceId?.trim()) {
+        return surface.surfaceId.trim();
+    }
     return `${pageKey}|${frameKey}|${kindKey}|${labelKey}`;
 }
 export function summarizeContext(context) {
@@ -209,8 +252,16 @@ function surfaceRoleFromKind(kind) {
     }
 }
 function collectSurfaceLocatorCandidates(target) {
+    return collectSurfaceLocatorCandidatesFromInputs({
+        surfaceKind: target.surfaceKind,
+        surfaceLabel: target.surfaceLabel,
+        surfaceSelector: target.surfaceSelector,
+        surfaceSelectors: target.surfaceSelectors,
+    });
+}
+function collectSurfaceLocatorCandidatesFromInputs(input) {
     const candidates = [];
-    const selectors = [target.surfaceSelector, ...(target.surfaceSelectors ?? [])].filter((value) => typeof value === 'string' && value.length > 0);
+    const selectors = [input.surfaceSelector, ...(input.surfaceSelectors ?? [])].filter((value) => typeof value === 'string' && value.length > 0);
     for (const selector of selectors) {
         pushUniqueLocatorCandidate(candidates, {
             strategy: selector.startsWith('xpath=') ? 'xpath' : 'css',
@@ -218,15 +269,39 @@ function collectSurfaceLocatorCandidates(target) {
             scope: 'root',
         });
     }
-    const surfaceRole = surfaceRoleFromKind(target.surfaceKind);
+    const surfaceRole = surfaceRoleFromKind(input.surfaceKind);
     if (surfaceRole) {
-        pushUniqueLocatorCandidate(candidates, target.surfaceLabel
-            ? { strategy: 'role', value: surfaceRole, name: target.surfaceLabel }
+        pushUniqueLocatorCandidate(candidates, input.surfaceLabel
+            ? { strategy: 'role', value: surfaceRole, name: input.surfaceLabel }
             : undefined);
-        pushUniqueLocatorCandidate(candidates, { strategy: 'role', value: surfaceRole });
+        pushUniqueLocatorCandidate(candidates, {
+            strategy: 'role',
+            value: surfaceRole,
+        });
     }
     return candidates;
 }
+function upsertSurfaceDescriptor(descriptors, surfaceId, descriptor) {
+    const existing = descriptors.get(surfaceId);
+    const locatorCandidates = existing ? [...existing.locatorCandidates] : [];
+    for (const candidate of descriptor.locatorCandidates) {
+        pushUniqueLocatorCandidate(locatorCandidates, candidate);
+    }
+    const kind = existing?.kind ?? descriptor.kind ?? 'surface';
+    descriptors.set(surfaceId, {
+        ...descriptor,
+        locatorCandidates,
+        kind,
+        label: existing?.label && existing.label !== 'Active surface'
+            ? existing.label
+            : (descriptor.label ?? existing?.label ?? 'Active surface'),
+        createdAt: existing?.createdAt ?? descriptor.createdAt,
+        pageSignature: existing?.pageSignature ?? descriptor.pageSignature,
+        framePath: existing?.framePath ?? descriptor.framePath,
+        frameUrl: existing?.frameUrl ?? descriptor.frameUrl,
+        extractScopeLifetime: inferExtractScopeLifetime(kind, locatorCandidates),
+    });
+}
 export function collectSurfaceDescriptors(pageRef, targets) {
     const descriptors = new Map();
     for (const target of targets) {
@@ -234,36 +309,59 @@ export function collectSurfaceDescriptors(pageRef, targets) {
         if (!surfaceId) {
             continue;
         }
-        const existing = descriptors.get(surfaceId);
-        const locatorCandidates = existing ? [...existing.locatorCandidates] : [];
-        for (const candidate of collectSurfaceLocatorCandidates(target)) {
-            pushUniqueLocatorCandidate(locatorCandidates, candidate);
-        }
-        descriptors.set(surfaceId, {
+        upsertSurfaceDescriptor(descriptors, surfaceId, {
             surfaceId,
             pageRef,
-            framePath: existing?.framePath ?? target.framePath,
-            frameUrl: existing?.frameUrl ?? target.frameUrl,
-            kind: existing?.kind ?? target.surfaceKind ?? 'surface',
-            label: existing?.label && existing.label !== 'Active surface'
-                ? existing.label
-                : (target.surfaceLabel ?? target.surfaceKind ?? existing?.label ?? 'Active surface'),
+            framePath: target.framePath,
+            frameUrl: target.frameUrl,
+            kind: target.surfaceKind ?? 'surface',
+            label: target.surfaceLabel ?? target.surfaceKind ?? 'Active surface',
             lifecycle: 'live',
             availability: { state: 'available' },
-            locatorCandidates,
-            createdAt: existing?.createdAt ?? Date.now(),
-            pageSignature: existing?.pageSignature ?? target.pageSignature,
-            extractScopeLifetime: inferExtractScopeLifetime(existing?.kind ?? target.surfaceKind ?? 'surface', locatorCandidates),
+            locatorCandidates: collectSurfaceLocatorCandidates(target),
+            createdAt: Date.now(),
+            pageSignature: target.pageSignature,
+            extractScopeLifetime: undefined,
         });
     }
     for (const target of targets) {
+        const explicitSurfaceId = buildExplicitSurfaceRef(target);
+        if (!explicitSurfaceId || explicitSurfaceId === target.surfaceRef) {
+            continue;
+        }
+        upsertSurfaceDescriptor(descriptors, explicitSurfaceId, {
+            surfaceId: explicitSurfaceId,
+            pageRef,
+            framePath: target.framePath,
+            frameUrl: target.frameUrl,
+            kind: target.explicitSurfaceKind ?? 'surface',
+            label: target.explicitSurfaceLabel ??
+                target.explicitFallbackSurfaceLabel ??
+                target.explicitSurfaceKind ??
+                'Active surface',
+            lifecycle: 'live',
+            availability: { state: 'available' },
+            locatorCandidates: collectSurfaceLocatorCandidatesFromInputs({
+                surfaceKind: target.explicitSurfaceKind,
+                surfaceLabel: target.explicitSurfaceLabel ?? target.explicitFallbackSurfaceLabel,
+                surfaceSelector: target.explicitSurfaceSelector,
+                surfaceSelectors: target.explicitSurfaceSelectors,
+            }),
+            createdAt: Date.now(),
+            pageSignature: target.pageSignature,
+            extractScopeLifetime: undefined,
+        });
+    }
+    for (const target of targets) {
+        if ((target.explicitSurfaceKind ?? '').trim().toLowerCase() === 'form') {
+            continue;
+        }
         const surfaceId = buildSyntheticFormSurfaceId(target);
         if (!surfaceId) {
             continue;
         }
-        const existing = descriptors.get(surfaceId);
-        const locatorCandidates = existing ? [...existing.locatorCandidates] : [];
         const formSelector = target.formSelector?.trim();
+        const locatorCandidates = [];
         if (formSelector) {
             pushUniqueLocatorCandidate(locatorCandidates, {
                 strategy: formSelector.startsWith('xpath=') ? 'xpath' : 'css',
@@ -271,19 +369,19 @@ export function collectSurfaceDescriptors(pageRef, targets) {
                 scope: 'root',
             });
         }
-        descriptors.set(surfaceId, {
+        upsertSurfaceDescriptor(descriptors, surfaceId, {
             surfaceId,
             pageRef,
-            framePath: existing?.framePath ?? target.framePath,
-            frameUrl: existing?.frameUrl ?? target.frameUrl,
+            framePath: target.framePath,
+            frameUrl: target.frameUrl,
             kind: 'form',
-            label: existing?.label ?? semanticFormContextLabel(target) ?? 'Form',
+            label: semanticFormContextLabel(target) ?? 'Form',
             lifecycle: 'live',
             availability: { state: 'available' },
             locatorCandidates,
-            createdAt: existing?.createdAt ?? Date.now(),
-            pageSignature: existing?.pageSignature ?? target.pageSignature,
-            extractScopeLifetime: inferExtractScopeLifetime('form', locatorCandidates),
+            createdAt: Date.now(),
+            pageSignature: target.pageSignature,
+            extractScopeLifetime: undefined,
         });
     }
     return [...descriptors.values()];

package/dist/commands/observe.d.ts

@@ -60,12 +60,16 @@ export type ObserveFailureResult = {
 export type ObserveResult = ObserveSuccessResult | ObserveFailureResult;
 export declare const __testDomTargetCollection: {
     collectDomTargetsFromDocument: (context: {
-        evaluate<T>(pageFunction: string): Promise<T>;
+        evaluate(pageFunction: string): Promise<unknown>;
     }, options?: import("./observe-inventory.js").DomTargetCollectionOptions & {
         framePath?: string[];
         frameUrl?: string;
         pageFormSelector?: string;
+        debugStructuralProfileStats?: boolean;
     }) => Promise<import("./observe-inventory.js").DomObservedTarget[]>;
+    collectDomTargetsDebugFromDocument: (context: {
+        evaluate(pageFunction: string): Promise<unknown>;
+    }, options?: import("./observe-inventory.js").DomTargetCollectionOptions) => Promise<import("./observe-inventory.js").DomTargetCollectionDebugResult>;
     inferStructuredCellVariantFromEvidence: typeof import("./observe-inventory.js").inferStructuredCellVariantFromEvidence;
     inferDirectionalControlFallbackFromEvidence: typeof import("./observe-inventory.js").inferDirectionalControlFallbackFromEvidence;
     locatorDomSignatureScript: string;

package/dist/commands/observe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/commands/observe.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAqBzE,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAmCtB,OAAO,EAIL,KAAK,2BAA2B,EAChC,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAM3B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAc/D,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,uFAItB,CAAC;AAEX,2DAA2D;AAC3D,eAAO,MAAM,qBAAqB,4EAIxB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AACpE,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,MAAM,MAAM,oBAAoB,GAC5B,mBAAmB,GACnB,0BAA0B,GAC1B,uBAAuB,GACvB,0BAA0B,CAAC;AAE/B,sDAAsD;AACtD,MAAM,MAAM,aAAa,GAAG,qBAAqB,CAAC;AAElD,wDAAwD;AACxD,MAAM,MAAM,YAAY,GAAG,oBAAoB,CAAC;AAEhD,gEAAgE;AAChE,MAAM,MAAM,mBAAmB,GAAG,2BAA2B,CAAC;AAE9D,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG,qBAAqB,CAAC;AAElD,KAAK,qBAAqB,GAAG,YAAY,GAAG;IAC1C,OAAO,EAAE,IAAI,CAAC;IACd,eAAe,EAAE,oBAAoB,CAAC;IACtC,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACvC,CAAC;AAEF,KAAK,qBAAqB,GAAG;IAC3B,KAAK,EAAE,gBAAgB,CAAC;IACxB,WAAW,EAAE,OAAO,CAAC,kBAAkB,EAAE,SAAS,GAAG,2BAA2B,CAAC,CAAC;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,aAAa,GAAG,oBAAoB,CAAC;IACnD,cAAc,CAAC,EACX,6BAA6B,GAC7B,8BAA8B,GAC9B,kBAAkB,CAAC;IACvB,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,qBAAqB,GAAG;IACzD,OAAO,EAAE,IAAI,CAAC;IACd,eAAe,EAAE,oBAAoB,CAAC;IACtC,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,oBAAoB,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,gEAAgE;AAChE,MAAM,MAAM,oBAAoB,GAAG;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,GAAG,qBAAqB,CAAC;AAE9E,MAAM,MAAM,aAAa,GAAG,oBAAoB,GAAG,oBAAoB,CAAC;AA2JxE,eAAO,MAAM,yBAAyB;;;;iBAoSL,CAAC;gBAAwB,CAAC;wBAC/C,CAAZ;;;;;CArSqE,CAAC;AACtE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAGrC,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,EAC9B,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,aAAa,CAAC,CAodxB;AAED,sFAAsF;AACtF,wBAAsB,OAAO,CAAC,OAAO,EAAE,qBAAqB,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWjG"}
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/commands/observe.ts"],"names":[],"mappings":"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"}