@opensteer/engine-abp 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import { ChildProcess } from 'node:child_process';
+
 declare const brandSymbol: unique symbol;
 type Brand<Value, Name extends string> = Value & {
     readonly [brandSymbol]: Name;
@@ -829,6 +831,40 @@ interface ComputerUseBridge {
     execute(input: ComputerUseBridgeInput): Promise<ComputerUseBridgeOutput>;
 }
 
+type MatchOperator = "exact" | "startsWith" | "contains";
+interface AttributeMatchClause {
+    readonly kind: "attr";
+    readonly key: string;
+    readonly op?: MatchOperator;
+    readonly value?: string;
+}
+interface PositionMatchClause {
+    readonly kind: "position";
+    readonly axis: "nthOfType" | "nthChild";
+}
+type MatchClause = AttributeMatchClause | PositionMatchClause;
+interface PathNodePosition {
+    readonly nthChild: number;
+    readonly nthOfType: number;
+}
+interface PathNode {
+    readonly tag: string;
+    readonly attrs: Readonly<Record<string, string>>;
+    readonly position: PathNodePosition;
+    readonly match: readonly MatchClause[];
+}
+interface ContextHop {
+    readonly kind: "iframe" | "shadow";
+    readonly host: readonly PathNode[];
+}
+interface ElementRouteBase {
+    readonly context: readonly ContextHop[];
+    readonly nodes: readonly PathNode[];
+}
+interface ReplayElementPath extends ElementRouteBase {
+    readonly resolution: "deterministic";
+}
+
 declare const OPENSTEER_DOM_ACTION_BRIDGE_SYMBOL: unique symbol;
 type DomActionScrollAlignment = "start" | "center" | "end" | "nearest";
 interface DomActionTargetInspection {
@@ -863,6 +899,7 @@ interface DomPointerHitAssessment {
     readonly hitOwner?: NodeLocator;
 }
 interface DomActionBridge {
+    buildReplayPath(locator: NodeLocator): Promise<ReplayElementPath>;
     inspectActionTarget(locator: NodeLocator): Promise<DomActionTargetInspection>;
     canonicalizePointerTarget(locator: NodeLocator): Promise<NodeLocator>;
     classifyPointerHit(input: {
@@ -894,6 +931,16 @@ interface AbpBrowserCoreEngineOptions {
     readonly browser?: AdoptedAbpBrowser;
     readonly extraHTTPHeaders?: readonly HeaderEntry[];
 }
+interface LaunchRequestOptions {
+    readonly port: number;
+    readonly userDataDir: string;
+    readonly sessionDir: string;
+    readonly abpExecutablePath?: string;
+    readonly browserExecutablePath?: string;
+    readonly headless: boolean;
+    readonly args: readonly string[];
+    readonly verbose: boolean;
+}
 
 declare class AbpBrowserCoreEngine implements BrowserCoreEngine {
     readonly capabilities: BrowserCapabilities;
@@ -1140,4 +1187,20 @@ declare class AbpBrowserCoreEngine implements BrowserCoreEngine {
 }
 declare function createAbpBrowserCoreEngine(options?: AbpBrowserCoreEngineOptions): Promise<AbpBrowserCoreEngine>;
 
-export { AbpBrowserCoreEngine, type AbpBrowserCoreEngineOptions, type AbpLaunchOptions, type AdoptedAbpBrowser, createAbpBrowserCoreEngine };
+interface LaunchedAbpProcess {
+    readonly process: ChildProcess;
+    readonly baseUrl: string;
+    readonly remoteDebuggingUrl: string;
+}
+interface AbpLaunchCommand {
+    readonly executablePath: string;
+    readonly args: readonly string[];
+}
+declare function allocatePort(): Promise<number>;
+declare function resolveDefaultAbpBrowserExecutablePath(): string | undefined;
+declare function resolveDefaultAbpWrapperExecutablePath(): string | undefined;
+declare function resolveDefaultAbpExecutablePath(): string | undefined;
+declare function buildAbpLaunchCommand(options: LaunchRequestOptions): AbpLaunchCommand;
+declare function launchAbpProcess(options: LaunchRequestOptions): Promise<LaunchedAbpProcess>;
+
+export { AbpBrowserCoreEngine, type AbpBrowserCoreEngineOptions, type AbpLaunchOptions, type AdoptedAbpBrowser, allocatePort, buildAbpLaunchCommand, createAbpBrowserCoreEngine, launchAbpProcess, resolveDefaultAbpBrowserExecutablePath, resolveDefaultAbpExecutablePath, resolveDefaultAbpWrapperExecutablePath };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { ChildProcess } from 'node:child_process';
+
 declare const brandSymbol: unique symbol;
 type Brand<Value, Name extends string> = Value & {
     readonly [brandSymbol]: Name;
@@ -829,6 +831,40 @@ interface ComputerUseBridge {
     execute(input: ComputerUseBridgeInput): Promise<ComputerUseBridgeOutput>;
 }
 
+type MatchOperator = "exact" | "startsWith" | "contains";
+interface AttributeMatchClause {
+    readonly kind: "attr";
+    readonly key: string;
+    readonly op?: MatchOperator;
+    readonly value?: string;
+}
+interface PositionMatchClause {
+    readonly kind: "position";
+    readonly axis: "nthOfType" | "nthChild";
+}
+type MatchClause = AttributeMatchClause | PositionMatchClause;
+interface PathNodePosition {
+    readonly nthChild: number;
+    readonly nthOfType: number;
+}
+interface PathNode {
+    readonly tag: string;
+    readonly attrs: Readonly<Record<string, string>>;
+    readonly position: PathNodePosition;
+    readonly match: readonly MatchClause[];
+}
+interface ContextHop {
+    readonly kind: "iframe" | "shadow";
+    readonly host: readonly PathNode[];
+}
+interface ElementRouteBase {
+    readonly context: readonly ContextHop[];
+    readonly nodes: readonly PathNode[];
+}
+interface ReplayElementPath extends ElementRouteBase {
+    readonly resolution: "deterministic";
+}
+
 declare const OPENSTEER_DOM_ACTION_BRIDGE_SYMBOL: unique symbol;
 type DomActionScrollAlignment = "start" | "center" | "end" | "nearest";
 interface DomActionTargetInspection {
@@ -863,6 +899,7 @@ interface DomPointerHitAssessment {
     readonly hitOwner?: NodeLocator;
 }
 interface DomActionBridge {
+    buildReplayPath(locator: NodeLocator): Promise<ReplayElementPath>;
     inspectActionTarget(locator: NodeLocator): Promise<DomActionTargetInspection>;
     canonicalizePointerTarget(locator: NodeLocator): Promise<NodeLocator>;
     classifyPointerHit(input: {
@@ -894,6 +931,16 @@ interface AbpBrowserCoreEngineOptions {
     readonly browser?: AdoptedAbpBrowser;
     readonly extraHTTPHeaders?: readonly HeaderEntry[];
 }
+interface LaunchRequestOptions {
+    readonly port: number;
+    readonly userDataDir: string;
+    readonly sessionDir: string;
+    readonly abpExecutablePath?: string;
+    readonly browserExecutablePath?: string;
+    readonly headless: boolean;
+    readonly args: readonly string[];
+    readonly verbose: boolean;
+}
 
 declare class AbpBrowserCoreEngine implements BrowserCoreEngine {
     readonly capabilities: BrowserCapabilities;
@@ -1140,4 +1187,20 @@ declare class AbpBrowserCoreEngine implements BrowserCoreEngine {
 }
 declare function createAbpBrowserCoreEngine(options?: AbpBrowserCoreEngineOptions): Promise<AbpBrowserCoreEngine>;
 
-export { AbpBrowserCoreEngine, type AbpBrowserCoreEngineOptions, type AbpLaunchOptions, type AdoptedAbpBrowser, createAbpBrowserCoreEngine };
+interface LaunchedAbpProcess {
+    readonly process: ChildProcess;
+    readonly baseUrl: string;
+    readonly remoteDebuggingUrl: string;
+}
+interface AbpLaunchCommand {
+    readonly executablePath: string;
+    readonly args: readonly string[];
+}
+declare function allocatePort(): Promise<number>;
+declare function resolveDefaultAbpBrowserExecutablePath(): string | undefined;
+declare function resolveDefaultAbpWrapperExecutablePath(): string | undefined;
+declare function resolveDefaultAbpExecutablePath(): string | undefined;
+declare function buildAbpLaunchCommand(options: LaunchRequestOptions): AbpLaunchCommand;
+declare function launchAbpProcess(options: LaunchRequestOptions): Promise<LaunchedAbpProcess>;
+
+export { AbpBrowserCoreEngine, type AbpBrowserCoreEngineOptions, type AbpLaunchOptions, type AdoptedAbpBrowser, allocatePort, buildAbpLaunchCommand, createAbpBrowserCoreEngine, launchAbpProcess, resolveDefaultAbpBrowserExecutablePath, resolveDefaultAbpExecutablePath, resolveDefaultAbpWrapperExecutablePath };

package/dist/index.js

@@ -1769,6 +1769,9 @@ function resolveDefaultAbpWrapperExecutablePath() {
   }
   return resolveExecutablePath([join(root, "dist", "bin", "abp.js")]);
 }
+function resolveDefaultAbpExecutablePath() {
+  return resolveDefaultAbpBrowserExecutablePath() ?? resolveDefaultAbpWrapperExecutablePath();
+}
 function buildAbpLaunchCommand(options) {
   if (options.abpExecutablePath !== void 0 && options.browserExecutablePath !== void 0) {
     throw createBrowserCoreError(
@@ -3164,8 +3167,257 @@ var CLASSIFY_POINTER_HIT_DECLARATION = String.raw`function(hitNode, point) {
     ambiguous,
   };
 }`;
+var LIVE_REPLAY_PATH_MATCH_ATTRIBUTE_PRIORITY = {
+  stablePrimaryExact: 150,
+  stablePrimaryPrefix: 130,
+  attrExact: 100,
+  attrPrefix: 80,
+  tagOnly: 10
+};
+var LIVE_REPLAY_PATH_STABLE_PRIMARY_ATTR_KEYS = [
+  "data-testid",
+  "data-test",
+  "data-qa",
+  "data-cy",
+  "name",
+  "role",
+  "type",
+  "aria-label",
+  "title",
+  "placeholder"
+];
+var LIVE_REPLAY_PATH_DEFERRED_MATCH_ATTR_KEYS = [
+  "href",
+  "src",
+  "srcset",
+  "imagesrcset",
+  "ping",
+  "value",
+  "for",
+  "aria-controls",
+  "aria-labelledby",
+  "aria-describedby"
+];
+var LIVE_REPLAY_PATH_POLICY = {
+  matchAttributePriority: LIVE_REPLAY_PATH_MATCH_ATTRIBUTE_PRIORITY,
+  stablePrimaryAttrKeys: LIVE_REPLAY_PATH_STABLE_PRIMARY_ATTR_KEYS,
+  deferredMatchAttrKeys: LIVE_REPLAY_PATH_DEFERRED_MATCH_ATTR_KEYS
+};
+var BUILD_LIVE_REPLAY_PATH_DECLARATION = String.raw`function(policy, source) {
+  const buildReplayPath = (0, eval)(source);
+  return buildReplayPath(this, policy);
+}`;
+var BUILD_LIVE_REPLAY_PATH_SOURCE = String.raw`(target, policy) => {
+  const MAX_ATTRIBUTE_VALUE_LENGTH = 300;
+
+  function isValidAttrKey(key) {
+    const trimmed = String(key || "").trim();
+    if (!trimmed) return false;
+    if (/[\s"'<>/]/.test(trimmed)) return false;
+    return /^[A-Za-z_][A-Za-z0-9_:\-.]*$/.test(trimmed);
+  }
+
+  function isMediaTag(tag) {
+    return new Set(["img", "video", "source", "iframe"]).has(String(tag || "").toLowerCase());
+  }
+
+  function shouldKeepAttr(tag, key, value) {
+    const normalized = String(key || "").trim().toLowerCase();
+    if (!normalized || !String(value || "").trim()) return false;
+    if (!isValidAttrKey(key)) return false;
+    if (normalized === "c") return false;
+    if (/^on[a-z]/i.test(normalized)) return false;
+    if (new Set(["style", "nonce", "integrity", "crossorigin", "referrerpolicy", "autocomplete"]).has(normalized)) {
+      return false;
+    }
+    if (normalized.startsWith("data-os-") || normalized.startsWith("data-opensteer-")) {
+      return false;
+    }
+    if (
+      isMediaTag(tag) &&
+      new Set([
+        "data-src",
+        "data-lazy-src",
+        "data-original",
+        "data-lazy",
+        "data-image",
+        "data-url",
+        "data-srcset",
+        "data-lazy-srcset",
+        "data-was-processed",
+      ]).has(normalized)
+    ) {
+      return false;
+    }
+    return true;
+  }
+
+  function collectAttrs(node) {
+    const tag = node.tagName.toLowerCase();
+    const attrs = {};
+    for (const attr of Array.from(node.attributes)) {
+      if (!shouldKeepAttr(tag, attr.name, attr.value)) {
+        continue;
+      }
+      const value = String(attr.value || "");
+      if (!value.trim()) continue;
+      if (value.length > MAX_ATTRIBUTE_VALUE_LENGTH) continue;
+      attrs[attr.name] = value;
+    }
+    return attrs;
+  }
+
+  function getSiblings(node, root) {
+    if (node.parentElement) return Array.from(node.parentElement.children);
+    return Array.from(root.children || []);
+  }
+
+  function cssEscape(value) {
+    return String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  }
+
+  function stablePrimaryKey(attrs) {
+    for (const key of policy.stablePrimaryAttrKeys || []) {
+      if (attrs[key]) return key;
+    }
+    return null;
+  }
+
+  function countMatches(root, tag, attrKey, attrValue, mode) {
+    const scope = root instanceof ShadowRoot ? root : root.ownerDocument;
+    if (!scope || typeof scope.querySelectorAll !== "function") return 0;
+    const escapedTag = String(tag || "*");
+    let selector = escapedTag;
+    if (attrKey && attrValue) {
+      const operator = mode === "prefix" ? "^=" : "=";
+      selector += "[" + attrKey + operator + "\\"" + cssEscape(attrValue) + "\\"]";
+    }
+    try {
+      return scope.querySelectorAll(selector).length;
+    } catch {
+      return 0;
+    }
+  }
+
+  function chooseAttribute(tag, attrs, root) {
+    const stableKey = stablePrimaryKey(attrs);
+    if (stableKey) {
+      const exactCount = countMatches(root, tag, stableKey, attrs[stableKey], "exact");
+      if (exactCount === 1) {
+        return {
+          key: stableKey,
+          value: attrs[stableKey],
+          match: "exact",
+        };
+      }
+    }
+
+    const entries = Object.entries(attrs)
+      .filter(([key]) => !policy.deferredMatchAttrKeys.includes(key))
+      .concat(Object.entries(attrs).filter(([key]) => policy.deferredMatchAttrKeys.includes(key)));
+
+    for (const [key, value] of entries) {
+      const exactCount = countMatches(root, tag, key, value, "exact");
+      if (exactCount === 1) {
+        return { key, value, match: "exact" };
+      }
+      if (value.length >= 4) {
+        const prefixLength = Math.min(Math.max(4, Math.floor(value.length / 2)), value.length);
+        const prefix = value.slice(0, prefixLength);
+        const prefixCount = countMatches(root, tag, key, prefix, "prefix");
+        if (prefixCount === 1) {
+          return { key, value: prefix, match: "prefix" };
+        }
+      }
+    }
+
+    return null;
+  }
+
+  function buildChain(node) {
+    const nodes = [];
+    let current = node;
+    while (current && current instanceof Element) {
+      nodes.unshift(current);
+      current = current.parentElement;
+    }
+    return nodes;
+  }
+
+  function finalizePath(chain, root) {
+    const result = [];
+    for (const node of chain) {
+      const tag = node.tagName.toLowerCase();
+      const attrs = collectAttrs(node);
+      const attribute = chooseAttribute(tag, attrs, root);
+      if (attribute) {
+        result.push({
+          tag,
+          attributes: [
+            {
+              name: attribute.key,
+              value: attribute.value,
+              match: attribute.match,
+            },
+          ],
+        });
+        continue;
+      }
+
+      const siblings = getSiblings(node, root).filter(
+        (candidate) => candidate.tagName.toLowerCase() === tag,
+      );
+      const index = siblings.indexOf(node);
+      result.push({
+        tag,
+        index: siblings.length <= 1 || index < 0 ? undefined : index,
+      });
+    }
+
+    return {
+      nodes: result,
+    };
+  }
+
+  if (!(target instanceof Element)) return null;
+
+  const context = [];
+  let currentRoot = target.getRootNode() instanceof ShadowRoot ? target.getRootNode() : document;
+  const targetChain = buildChain(target);
+  const finalizedTarget = finalizePath(targetChain, currentRoot);
+  if (!finalizedTarget) return null;
+
+  while (currentRoot instanceof ShadowRoot) {
+    const host = currentRoot.host;
+    const hostRoot = host.getRootNode() instanceof ShadowRoot ? host.getRootNode() : document;
+    const hostChain = buildChain(host);
+    const finalizedHost = finalizePath(hostChain, hostRoot);
+    if (!finalizedHost) return null;
+    context.unshift({
+      kind: "shadow",
+      host: finalizedHost.nodes,
+    });
+    currentRoot = hostRoot;
+  }
+
+  return {
+    resolution: "deterministic",
+    context,
+    nodes: finalizedTarget.nodes,
+  };
+}`;
 function createAbpDomActionBridge(context) {
   return {
+    async buildReplayPath(locator) {
+      const { controller, document, backendNodeId } = await prepareLiveNodeContext(context, locator);
+      return withTemporaryExecutionResume(context, controller, async () => {
+        const raw = await callNodeValueFunction(controller, document, locator, backendNodeId, {
+          functionDeclaration: BUILD_LIVE_REPLAY_PATH_DECLARATION,
+          arguments: [{ value: LIVE_REPLAY_PATH_POLICY }, { value: BUILD_LIVE_REPLAY_PATH_SOURCE }]
+        });
+        return requireReplayPath(raw, locator);
+      });
+    },
     async inspectActionTarget(locator) {
       const { controller, document, backendNodeId } = await prepareLiveNodeContext(
         context,
@@ -3403,6 +3655,24 @@ async function callNodeFunctionWithNodeArgument(controller, document, locator, b
     await releaseObject(controller, objectId);
   }
 }
+async function callNodeValueFunction(controller, document, locator, backendNodeId, input) {
+  let objectId;
+  try {
+    objectId = await resolveNodeObjectId(controller, document, locator, backendNodeId);
+    const evaluated = await controller.cdp.send("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: input.functionDeclaration,
+      ...input.arguments === void 0 ? {} : { arguments: [...input.arguments] },
+      returnByValue: true,
+      awaitPromise: true
+    });
+    return evaluated.result?.value;
+  } catch (error) {
+    rethrowNodeLookupError2(document, locator, error);
+  } finally {
+    await releaseObject(controller, objectId);
+  }
+}
 async function resolveNodeObjectId(controller, document, locator, backendNodeId) {
   try {
     const resolved = await controller.cdp.send("DOM.resolveNode", {
@@ -3497,6 +3767,14 @@ function normalizePointerHitAssessment(value, canonicalTarget) {
     canonicalTarget
   };
 }
+function requireReplayPath(value, locator) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || value.resolution !== "deterministic") {
+    throw new Error(
+      `live DOM replay path builder returned an invalid result for ${locator.nodeRef}`
+    );
+  }
+  return value;
+}
 function rethrowNodeLookupError2(document, locator, error) {
   if (error instanceof Error && /No node with given id found|Could not find node with given id|Cannot find context/i.test(
     error.message
@@ -6525,6 +6803,6 @@ function resolveFallbackPageTarget(targets, tabMetadata) {
   return void 0;
 }
 
-export { AbpBrowserCoreEngine, createAbpBrowserCoreEngine };
+export { AbpBrowserCoreEngine, allocatePort, buildAbpLaunchCommand, createAbpBrowserCoreEngine, launchAbpProcess, resolveDefaultAbpBrowserExecutablePath, resolveDefaultAbpExecutablePath, resolveDefaultAbpWrapperExecutablePath };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map