@nuanu-ai/agentbrowse 0.2.12 → 0.2.14

package/dist/commands/observe-persistence.js

@@ -1,5 +1,5 @@
 import { ensureRuntimeState, markSurfaceLifecycle, markTargetLifecycle, replaceSurfacesForPage, setSurfaceAvailability, setTargetAvailability, } from '../runtime-state.js';
-import { collectSurfaceDescriptors, pushUniqueLocatorCandidate, surfaceReplacementKey } from './observe-surfaces.js';
+import { buildSyntheticFormSurfaceId, collectSurfaceDescriptors, pushUniqueLocatorCandidate, surfaceReplacementKey, } from './observe-surfaces.js';
 export function toDomDescriptor(pageRef, target, surfaceRefMap) {
     const locatorCandidates = [];
     if (target.role && target.label) {
@@ -168,3 +168,54 @@ export function reconcileObservedTargetsForPage(session, pageRef, observedTarget
         setTargetAvailability(session, target.ref, 'hidden', 'target-not-observed');
     }
 }
+function pushUniqueRef(map, key, ref) {
+    const refs = map.get(key) ?? [];
+    if (!refs.includes(ref)) {
+        refs.push(ref);
+        map.set(key, refs);
+    }
+}
+export function linkObservedSurfaceGraph(session, pageRef, domTargets, persistedTargets, observedScopes, surfaceRefMap) {
+    const runtime = ensureRuntimeState(session);
+    const activeSurfaceRefs = new Set(observedScopes.map((scope) => scope.ref));
+    const targetRefsBySurface = new Map();
+    const parentBySurface = new Map();
+    const childRefsByParent = new Map();
+    for (const [index, persistedTarget] of persistedTargets.entries()) {
+        if (persistedTarget.pageRef !== pageRef) {
+            continue;
+        }
+        if (persistedTarget.surfaceRef) {
+            pushUniqueRef(targetRefsBySurface, persistedTarget.surfaceRef, persistedTarget.ref);
+        }
+        const domTarget = domTargets[index];
+        if (!domTarget) {
+            continue;
+        }
+        const syntheticFormSurfaceId = buildSyntheticFormSurfaceId(domTarget);
+        const formSurfaceRef = syntheticFormSurfaceId
+            ? surfaceRefMap.get(syntheticFormSurfaceId)
+            : undefined;
+        if (!formSurfaceRef || !persistedTarget.surfaceRef || persistedTarget.surfaceRef === formSurfaceRef) {
+            continue;
+        }
+        parentBySurface.set(persistedTarget.surfaceRef, formSurfaceRef);
+        pushUniqueRef(childRefsByParent, formSurfaceRef, persistedTarget.surfaceRef);
+    }
+    for (const surface of Object.values(runtime.surfaces)) {
+        if (surface.pageRef !== pageRef) {
+            continue;
+        }
+        runtime.surfaces[surface.ref] = {
+            ...surface,
+            parentSurfaceRef: activeSurfaceRefs.has(surface.ref)
+                ? parentBySurface.get(surface.ref)
+                : undefined,
+            childSurfaceRefs: activeSurfaceRefs.has(surface.ref)
+                ? [...(childRefsByParent.get(surface.ref) ?? [])]
+                : [],
+            targetRefs: activeSurfaceRefs.has(surface.ref) ? [...(targetRefsBySurface.get(surface.ref) ?? [])] : [],
+        };
+    }
+    return observedScopes.map((scope) => runtime.surfaces[scope.ref] ?? scope);
+}

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

@@ -1,5 +1,5 @@
 import type { SurfaceDescriptor, TargetDescriptor, TargetValidationEvidence } from '../runtime-state.js';
-import type { FillableFormGuidanceHint, PersistedFillableForm, ProtectedBindingValueHint } from '../secrets/types.js';
+import type { PersistedFillableForm, ProtectedBindingValueHint } from '../secrets/types.js';
 import type { DomObservedTarget, ObservedPageSignal } from './observe-inventory.js';
 export type GoalObserveScopeCandidate = {
     goalInventoryType: 'scope';
@@ -20,7 +20,7 @@ export type GoalObserveTargetCandidate = DomObservedTarget & {
     goalTargetKey: string;
 };
 export type GoalObserveInventoryCandidate = GoalObserveTargetCandidate | GoalObserveScopeCandidate;
-export declare function compactTargets(targets: ReadonlyArray<Pick<TargetDescriptor, 'ref' | 'kind' | 'label' | 'displayLabel' | 'placeholder' | 'inputName' | 'inputType' | 'autocomplete' | 'validation' | 'context' | 'semantics' | 'structure' | 'capability' | 'availability'>>): Array<{
+export declare function compactTargets(targets: ReadonlyArray<Pick<TargetDescriptor, 'ref' | 'kind' | 'label' | 'displayLabel' | 'placeholder' | 'inputName' | 'inputType' | 'autocomplete' | 'validation' | 'context' | 'semantics' | 'structure' | 'capability' | 'availability' | 'surfaceRef'>>): Array<{
     ref: string;
     kind?: string;
     label?: string;
@@ -36,23 +36,45 @@ export declare function compactTargets(targets: ReadonlyArray<Pick<TargetDescrip
     capability?: TargetDescriptor['capability'];
     availability?: string;
     availabilityReason?: string;
+    surfaceRef?: string;
     source?: 'dom' | 'stagehand' | 'aria-snapshot' | 'cdp-ax';
 }>;
-export declare function compactScopes(scopes: ReadonlyArray<Pick<SurfaceDescriptor, 'ref' | 'kind' | 'label' | 'availability'>>): Array<{
+export type CompactObservedTarget = ReturnType<typeof compactTargets>[number];
+export declare function compactScopes(scopes: ReadonlyArray<Pick<SurfaceDescriptor, 'ref' | 'kind' | 'label' | 'availability' | 'parentSurfaceRef' | 'childSurfaceRefs' | 'targetRefs'>>): Array<{
     ref: string;
     kind?: string;
     label?: string;
     capability: 'scope';
     availability?: string;
     availabilityReason?: string;
+    parentSurfaceRef?: string;
+    childSurfaceRefs?: string[];
+    targetRefs?: string[];
     source: 'dom';
 }>;
+export type CompactObservedScope = {
+    ref: string;
+    kind?: string;
+    label?: string;
+    capability: 'scope';
+    availability?: string;
+    availabilityReason?: string;
+    parentSurfaceRef?: string;
+    childSurfaceRefs?: string[];
+    targets: CompactObservedTarget[];
+    source: 'dom' | 'stagehand' | 'aria-snapshot' | 'cdp-ax';
+};
+type BuildGroupedObserveScopesOptions = {
+    pageRef: string;
+    title?: string;
+    scopes: ReadonlyArray<Pick<SurfaceDescriptor, 'ref' | 'kind' | 'label' | 'availability' | 'parentSurfaceRef' | 'childSurfaceRefs'>>;
+    targets: ReadonlyArray<Pick<TargetDescriptor, 'ref' | 'kind' | 'label' | 'displayLabel' | 'placeholder' | 'inputName' | 'inputType' | 'autocomplete' | 'validation' | 'context' | 'semantics' | 'structure' | 'capability' | 'availability' | 'surfaceRef'>>;
+};
+export declare function buildGroupedObserveScopes(options: BuildGroupedObserveScopesOptions): CompactObservedScope[];
 export declare function compactFillableForms(forms: ReadonlyArray<PersistedFillableForm>): Array<{
     fillRef: string;
     scopeRef?: string;
     purpose: string;
-    recommendedTiming?: 'late';
-    guidance?: FillableFormGuidanceHint;
     fields: Array<{
         fieldKey: string;
         targetRef: string;
@@ -82,4 +104,5 @@ export declare function selectTargetsForGoalMatches(allTargets: ReadonlyArray<Do
 };
 export declare function buildExplicitScopeRefs(selectedSurfaceIds: ReadonlySet<string>, surfaceRefMap: ReadonlyMap<string, string>): Set<string>;
 export declare function projectPersistedTargetsForGoal(domTargets: ReadonlyArray<DomObservedTarget>, persistedTargets: ReadonlyArray<TargetDescriptor>, selectedTargets: ReadonlyArray<DomObservedTarget>): TargetDescriptor[];
+export {};
 //# sourceMappingURL=observe-projection.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"observe-projection.d.ts","sourceRoot":"","sources":["../../src/commands/observe-projection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"observe-projection.d.ts","sourceRoot":"","sources":["../../src/commands/observe-projection.ts"],"names":[],"mappings":"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"}

package/dist/commands/observe-projection.js

@@ -1,5 +1,98 @@
 import { observedTargetKey } from './observe-semantics.js';
-import { summarizeContext } from './observe-surfaces.js';
+import { buildSyntheticFormSurfaceId, summarizeContext } from './observe-surfaces.js';
+function normalizeClusterText(value) {
+    const normalized = value?.replace(/\s+/g, ' ').trim().toLowerCase();
+    return normalized ? normalized : undefined;
+}
+function isActionLikeGoalTarget(target) {
+    const actions = target.allowedActions ?? [];
+    const kind = (target.kind ?? '').trim().toLowerCase();
+    const role = (target.role ?? '').trim().toLowerCase();
+    const isValueControl = actions.includes('fill') || actions.includes('type') || actions.includes('select');
+    if (isValueControl) {
+        return false;
+    }
+    return (actions.includes('click') ||
+        actions.includes('press') ||
+        kind === 'button' ||
+        role === 'button' ||
+        kind === 'link' ||
+        role === 'link');
+}
+function goalActionClusterKey(target) {
+    const itemKey = normalizeClusterText(target.context?.item?.label ?? target.context?.item?.text);
+    const groupKey = normalizeClusterText(target.context?.group?.label ?? target.context?.group?.text);
+    const containerKey = normalizeClusterText(target.context?.container?.label ?? target.context?.container?.text);
+    const parts = [
+        target.surfaceRef ? `surface:${target.surfaceRef}` : undefined,
+        itemKey ? `item:${itemKey}` : undefined,
+        groupKey ? `group:${groupKey}` : undefined,
+        containerKey ? `container:${containerKey}` : undefined,
+    ].filter((value) => Boolean(value));
+    return parts.length > 0 ? parts.join('|') : undefined;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function stripSiblingLabels(value, siblingLabels) {
+    if (!value) {
+        return value;
+    }
+    let sanitized = value;
+    for (const label of siblingLabels) {
+        if (!label) {
+            continue;
+        }
+        sanitized = sanitized.replace(new RegExp(escapeRegExp(label), 'gi'), ' ');
+    }
+    const collapsed = sanitized.replace(/\s+[—-]\s+/g, ' ').replace(/\s+/g, ' ').trim();
+    return collapsed || undefined;
+}
+function sanitizeGoalTargetContext(target, siblingLabelsByCluster) {
+    if (!isActionLikeGoalTarget(target)) {
+        return target;
+    }
+    const clusterKey = goalActionClusterKey(target);
+    if (!clusterKey) {
+        return target;
+    }
+    const ownLabel = normalizeClusterText(target.label);
+    const siblingLabels = (siblingLabelsByCluster.get(clusterKey) ?? []).filter((label) => label !== ownLabel);
+    if (siblingLabels.length === 0 || !target.context) {
+        return target;
+    }
+    return {
+        ...target,
+        context: {
+            ...target.context,
+            item: target.context.item
+                ? {
+                    ...target.context.item,
+                    text: stripSiblingLabels(target.context.item.text, siblingLabels),
+                }
+                : target.context.item,
+            group: target.context.group
+                ? {
+                    ...target.context.group,
+                    text: stripSiblingLabels(target.context.group.text, siblingLabels),
+                }
+                : target.context.group,
+            container: target.context.container
+                ? {
+                    ...target.context.container,
+                    text: stripSiblingLabels(target.context.container.text, siblingLabels),
+                }
+                : target.context.container,
+            landmark: target.context.landmark
+                ? {
+                    ...target.context.landmark,
+                    text: stripSiblingLabels(target.context.landmark.text, siblingLabels),
+                }
+                : target.context.landmark,
+            hintText: stripSiblingLabels(target.context.hintText, siblingLabels),
+        },
+    };
+}
 export function compactTargets(targets) {
     return targets.map((target) => ({
         ref: target.ref,
@@ -17,6 +110,7 @@ export function compactTargets(targets) {
         capability: target.capability,
         availability: target.availability?.state,
         availabilityReason: target.availability?.reason,
+        surfaceRef: target.surfaceRef,
         source: target.semantics?.source,
     }));
 }
@@ -28,16 +122,69 @@ export function compactScopes(scopes) {
         capability: 'scope',
         availability: scope.availability?.state,
         availabilityReason: scope.availability?.reason,
+        parentSurfaceRef: scope.parentSurfaceRef,
+        childSurfaceRefs: scope.childSurfaceRefs ? [...scope.childSurfaceRefs] : [],
+        targetRefs: scope.targetRefs ? [...scope.targetRefs] : [],
         source: 'dom',
     }));
 }
+function compactScopeSource(targets) {
+    return targets.find((target) => typeof target.source === 'string')?.source ?? 'dom';
+}
+export function buildGroupedObserveScopes(options) {
+    const compactedTargets = compactTargets(options.targets);
+    const scopeRefs = new Set(options.scopes.map((scope) => scope.ref));
+    const compactedTargetsByScope = new Map();
+    const unscopedTargets = [];
+    for (const target of compactedTargets) {
+        if (target.surfaceRef && scopeRefs.has(target.surfaceRef)) {
+            const grouped = compactedTargetsByScope.get(target.surfaceRef) ?? [];
+            grouped.push(target);
+            compactedTargetsByScope.set(target.surfaceRef, grouped);
+            continue;
+        }
+        unscopedTargets.push(target);
+    }
+    const groupedScopes = options.scopes.map((scope) => {
+        const scopeTargets = compactedTargetsByScope.get(scope.ref) ?? [];
+        const visibleChildSurfaceRefs = (scope.childSurfaceRefs ?? []).filter((ref) => scopeRefs.has(ref));
+        return {
+            ref: scope.ref,
+            kind: scope.kind,
+            label: scope.label,
+            capability: 'scope',
+            availability: scope.availability?.state,
+            availabilityReason: scope.availability?.reason,
+            parentSurfaceRef: scope.parentSurfaceRef && scopeRefs.has(scope.parentSurfaceRef)
+                ? scope.parentSurfaceRef
+                : undefined,
+            childSurfaceRefs: visibleChildSurfaceRefs,
+            targets: scopeTargets,
+            source: compactScopeSource(scopeTargets),
+        };
+    });
+    if (unscopedTargets.length === 0) {
+        return groupedScopes;
+    }
+    return [
+        ...groupedScopes,
+        {
+            ref: `page:${options.pageRef}`,
+            kind: 'page',
+            label: options.title ?? 'Page',
+            capability: 'scope',
+            availability: 'available',
+            childSurfaceRefs: [],
+            targets: unscopedTargets,
+            source: compactScopeSource(unscopedTargets),
+        },
+    ];
+}
 export function compactFillableForms(forms) {
     return forms.map((form) => ({
         fillRef: form.fillRef,
         scopeRef: form.scopeRef,
         purpose: form.purpose,
-        recommendedTiming: form.recommendedTiming,
-        guidance: form.guidance,
         fields: form.fields.map((field) => ({
             fieldKey: field.fieldKey,
             targetRef: field.targetRef,
@@ -64,11 +211,42 @@ export function compactSignals(signals) {
     }));
 }
 export function buildGoalObserveInventoryCandidates(targets, surfaces) {
-    const targetCandidates = targets.map((target) => ({
-        ...target,
-        goalInventoryType: 'target',
-        goalTargetKey: observedTargetKey(target),
-    }));
+    const siblingLabelsByCluster = new Map();
+    for (const target of targets) {
+        if (!isActionLikeGoalTarget(target)) {
+            continue;
+        }
+        const clusterKey = goalActionClusterKey(target);
+        const normalizedLabel = normalizeClusterText(target.label);
+        if (!clusterKey || !normalizedLabel) {
+            continue;
+        }
+        const labels = siblingLabelsByCluster.get(clusterKey) ?? [];
+        if (!labels.includes(normalizedLabel)) {
+            labels.push(normalizedLabel);
+            siblingLabelsByCluster.set(clusterKey, labels);
+        }
+    }
+    const targetCandidates = targets.map((target) => {
+        const sanitized = sanitizeGoalTargetContext(target, siblingLabelsByCluster);
+        const syntheticFormSurfaceId = buildSyntheticFormSurfaceId(sanitized);
+        const surfaceRef = sanitized.surfaceRef ?? syntheticFormSurfaceId;
+        const surfaceKind = sanitized.surfaceKind ?? (syntheticFormSurfaceId ? 'form' : undefined);
+        const surfaceLabel = sanitized.surfaceLabel ??
+            (syntheticFormSurfaceId
+                ? sanitized.context?.landmark?.label ?? sanitized.context?.group?.label ?? 'Form'
+                : undefined);
+        const surfacePriority = sanitized.surfacePriority ?? (surfaceKind === 'form' ? 70 : undefined);
+        return {
+            ...sanitized,
+            surfaceRef,
+            surfaceKind,
+            surfaceLabel,
+            surfacePriority,
+            goalInventoryType: 'target',
+            goalTargetKey: observedTargetKey(target),
+        };
+    });
     const scopeCandidates = surfaces.map((surface) => {
         const linkedTargets = targets.filter((target) => target.surfaceRef === surface.surfaceId);
         const primaryLinkedTarget = linkedTargets[0];
@@ -134,7 +312,9 @@ export function selectTargetsForGoalMatches(allTargets, rerankedCandidates) {
     const scopeTargets = allTargets.filter((target) => {
         const directMatch = typeof target.ordinal === 'number' && directTargetOrdinals.has(target.ordinal);
         const directKeyMatch = directTargetKeys.has(observedTargetKey(target));
-        const scopeMatch = target.surfaceRef ? selectedSurfaceIds.has(target.surfaceRef) : false;
+        const syntheticFormSurfaceId = buildSyntheticFormSurfaceId(target);
+        const scopeMatch = (target.surfaceRef ? selectedSurfaceIds.has(target.surfaceRef) : false) ||
+            (syntheticFormSurfaceId ? selectedSurfaceIds.has(syntheticFormSurfaceId) : false);
         if (directMatch || directKeyMatch) {
             return false;
         }

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

@@ -1 +1 @@
-{"version":3,"file":"observe-semantics.d.ts","sourceRoot":"","sources":["../../src/commands/observe-semantics.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAYjF;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CA6B7E;AAgBD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAQ/E;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAMnE;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,EACzC,eAAe,EAAE,aAAa,CAAC,iBAAiB,CAAC,GAChD,iBAAiB,EAAE,CAyCrB;AAkFD,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,aAAa,CAAC,iBAAiB,CAAC,GAChD,iBAAiB,EAAE,CA6BrB;AAqBD,wBAAgB,oCAAoC,CAClD,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,GACxC,iBAAiB,EAAE,CAuBrB;AAkGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,GAAG,iBAAiB,EAAE,CAmDjG;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,GACxC,iBAAiB,EAAE,CAsFrB"}
+{"version":3,"file":"observe-semantics.d.ts","sourceRoot":"","sources":["../../src/commands/observe-semantics.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAYjF;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CA6B7E;AAgBD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAQ/E;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAMnE;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,EACzC,eAAe,EAAE,aAAa,CAAC,iBAAiB,CAAC,GAChD,iBAAiB,EAAE,CAyCrB;AAkFD,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,aAAa,CAAC,iBAAiB,CAAC,GAChD,iBAAiB,EAAE,CA6BrB;AAqBD,wBAAgB,oCAAoC,CAClD,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,GACxC,iBAAiB,EAAE,CAuBrB;AAkGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,GAAG,iBAAiB,EAAE,CAiEjG;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,GACxC,iBAAiB,EAAE,CAsFrB"}

package/dist/commands/observe-semantics.js

@@ -1,5 +1,5 @@
 import { inferAcceptancePolicyFromFacts, inferAllowedActionsFromFacts, inferAvailabilityFromFacts, inferControlFamilyFromFacts, } from '../control-semantics.js';
-import { buildSurfaceRef } from './observe-surfaces.js';
+import { buildSurfaceRef, buildSyntheticFormSurfaceId } from './observe-surfaces.js';
 export function normalizeSemanticDuplicateLabel(target) {
     return (target.displayLabel ??
         target.label ??
@@ -299,9 +299,20 @@ export function annotateDomTargets(targets) {
         const availability = inferAvailability(target);
         const capability = inferCapability(target, allowedActions);
         const acceptancePolicy = inferAcceptancePolicy(target, allowedActions);
-        const surfaceRef = buildSurfaceRef(target);
+        const explicitSurfaceRef = buildSurfaceRef(target);
+        const syntheticFormSurfaceRef = explicitSurfaceRef === undefined ? buildSyntheticFormSurfaceId(target) : undefined;
+        const surfaceRef = explicitSurfaceRef ?? syntheticFormSurfaceRef;
+        const surfaceKind = target.surfaceKind ?? (syntheticFormSurfaceRef ? 'form' : undefined);
+        const surfaceLabel = target.surfaceLabel ??
+            (syntheticFormSurfaceRef
+                ? target.context?.landmark?.label ?? target.context?.group?.label ?? 'Form'
+                : undefined);
+        const surfacePriority = target.surfacePriority ?? (surfaceKind === 'form' ? 70 : undefined);
         return {
             ...target,
+            surfaceKind,
+            surfaceLabel,
+            surfacePriority,
             capability,
             availability,
             allowedActions,

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

@@ -2,6 +2,7 @@ import type { LocatorCandidate, SurfaceDescriptor, TargetContext, TargetDescript
 import type { DomObservedTarget } from './observe-inventory.js';
 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 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 summarizeContext(context: TargetContext | undefined): string | undefined;
 export declare function pushUniqueLocatorCandidate(acc: LocatorCandidate[], candidate: LocatorCandidate | undefined): void;

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,EACV,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAahE,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,CA+CrB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAa7E;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,CA4CvF;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,oCAoC1C"}
+{"version":3,"file":"observe-surfaces.d.ts","sourceRoot":"","sources":["../../src/commands/observe-surfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAgBhE,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,CA+CrB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAa7E;AAyBD,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,IAAI,CAAC,iBAAiB,EAAE,eAAe,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,GAAG,SAAS,CAAC,GACvG,MAAM,GAAG,SAAS,CAiBpB;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,CA4CvF;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,oCAoE1C"}

package/dist/commands/observe-surfaces.js

@@ -1,5 +1,6 @@
 import { locatorCandidateKey } from '../runtime-state.js';
 const HIGH_SIGNAL_SCOPE_KINDS = new Set([
+    'form',
     'dialog',
     'listbox',
     'menu',
@@ -8,6 +9,8 @@ const HIGH_SIGNAL_SCOPE_KINDS = new Set([
     'popover',
     'dropdown',
     'datepicker',
+    'floating-panel',
+    'sticky-panel',
 ]);
 export function selectScopesForOutput(scopes, targets, preferredScopeRefs) {
     if (scopes.length === 0) {
@@ -63,6 +66,39 @@ export function buildSurfaceRef(target) {
         target.surfaceLabel ?? '',
     ].join('|');
 }
+function normalizeSurfaceText(value) {
+    const normalized = value?.replace(/\s+/g, ' ').trim();
+    return normalized ? normalized : undefined;
+}
+function semanticFormContextLabel(target) {
+    for (const node of [
+        target.context?.landmark,
+        target.context?.container,
+        target.context?.group,
+        target.context?.item,
+    ]) {
+        const kind = (node?.kind ?? '').trim().toLowerCase();
+        if (kind !== 'form') {
+            continue;
+        }
+        return normalizeSurfaceText(node?.label ?? node?.text);
+    }
+    return undefined;
+}
+export function buildSyntheticFormSurfaceId(target) {
+    const pageKey = normalizeSurfaceText(target.pageSignature);
+    if (!pageKey) {
+        return undefined;
+    }
+    const formKey = normalizeSurfaceText(target.formSelector) ??
+        semanticFormContextLabel(target)?.toLowerCase();
+    if (!formKey) {
+        return undefined;
+    }
+    const frameKey = target.framePath?.join('>') ??
+        (normalizeSurfaceText(target.frameUrl) ? `url:${normalizeSurfaceText(target.frameUrl)}` : 'top');
+    return `${pageKey}|${frameKey}|form|${formKey}`;
+}
 export function surfaceReplacementKey(surface) {
     const pageKey = surface.pageSignature ?? surface.pageRef;
     const frameKey = surface.framePath?.join('>') ?? 'top';
@@ -191,5 +227,34 @@ export function collectSurfaceDescriptors(pageRef, targets) {
             pageSignature: existing?.pageSignature ?? target.pageSignature,
         });
     }
+    for (const target of targets) {
+        const surfaceId = buildSyntheticFormSurfaceId(target);
+        if (!surfaceId) {
+            continue;
+        }
+        const existing = descriptors.get(surfaceId);
+        const locatorCandidates = existing ? [...existing.locatorCandidates] : [];
+        const formSelector = target.formSelector?.trim();
+        if (formSelector) {
+            pushUniqueLocatorCandidate(locatorCandidates, {
+                strategy: formSelector.startsWith('xpath=') ? 'xpath' : 'css',
+                value: formSelector,
+                scope: 'root',
+            });
+        }
+        descriptors.set(surfaceId, {
+            surfaceId,
+            pageRef,
+            framePath: existing?.framePath ?? target.framePath,
+            frameUrl: existing?.frameUrl ?? target.frameUrl,
+            kind: 'form',
+            label: existing?.label ?? semanticFormContextLabel(target) ?? 'Form',
+            lifecycle: 'live',
+            availability: { state: 'available' },
+            locatorCandidates,
+            createdAt: existing?.createdAt ?? Date.now(),
+            pageSignature: existing?.pageSignature ?? target.pageSignature,
+        });
+    }
     return [...descriptors.values()];
 }

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,aAAa,EAAE,MAAM,eAAe,CAAC;AAgDnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAU/D,eAAO,MAAM,yBAAyB;;;;iBA6OguF,CAAC;gBAAwB,CAAC;;;;;iBAAq7vE,CAAC;gBAAwB,CAAC;;;CA7O1q1E,CAAC;AACtE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAGrC,CAAC;AAEF,wBAAsB,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsOzF"}
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/commands/observe.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAgDnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAU/D,eAAO,MAAM,yBAAyB;;;;iBAyR+wD,CAAC;gBAAwB,CAAC;;;;;iBAAirzE,CAAC;gBAAwB,CAAC;;;CAzRr92E,CAAC;AACtE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAGrC,CAAC;AAEF,wBAAsB,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkRzF"}