@browserbasehq/orca 3.0.9-alpha-3 → 3.1.0-headers

package/dist/cjs/lib/v3/types/private/snapshot.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Options that control how hybrid snapshots and targeted scopes are captured.
+ */
+export type SnapshotOptions = {
+    /**
+     * Filter the snapshot to a specific element/subtree using a selector that can cross iframes.
+     * Supports XPath (prefixed with `xpath=` or starting with `/`) and CSS with iframe hops via `>>`.
+     */
+    focusSelector?: string;
+    /**
+     * Pierce shadow DOM when calling DOM.getDocument. Defaults to true to retain the
+     * existing behaviour.
+     */
+    pierceShadow?: boolean;
+    /**
+     * Toggle whether iframe subtrees are included in the merged snapshot. Defaults to true.
+     */
+    includeIframes?: boolean;
+    /**
+     * Optional feature flag that surfaces experimental traversal tweaks in the Accessibility layer.
+     */
+    experimental?: boolean;
+};
+/**
+ * Hybrid snapshot payload consumed by act/extract/observe handlers.
+ */
+export type HybridSnapshot = {
+    /** Merged outline across every frame. */
+    combinedTree: string;
+    /** EncodedId (frameOrdinal-backendNodeId) -> absolute XPath. */
+    combinedXpathMap: Record<string, string>;
+    /** EncodedId -> URL extracted from AX properties. */
+    combinedUrlMap: Record<string, string>;
+    /** Per-frame payloads expose the original relative data for debugging. */
+    perFrame?: PerFrameSnapshot[];
+};
+export type PerFrameSnapshot = {
+    frameId: string;
+    outline: string;
+    xpathMap: Record<string, string>;
+    urlMap: Record<string, string>;
+};
+/**
+ * Compact encoding of DOM data for an entire session. Shared between capture
+ * and focus helpers so DOM traversal can be unit tested in isolation.
+ */
+export type SessionDomIndex = {
+    rootBackend: number;
+    absByBe: Map<number, string>;
+    tagByBe: Map<number, string>;
+    scrollByBe: Map<number, boolean>;
+    docRootOf: Map<number, number>;
+    contentDocRootByIframe: Map<number, number>;
+};
+export type FrameDomMaps = {
+    tagNameMap: Record<string, string>;
+    xpathMap: Record<string, string>;
+    scrollableMap: Record<string, boolean>;
+    urlMap: Record<string, string>;
+};
+export type ResolvedLocation = {
+    frameId: string;
+    backendNodeId: number;
+    absoluteXPath: string;
+};
+export type ResolvedFocusFrame = {
+    targetFrameId: string;
+    tailXPath: string;
+    absPrefix: string;
+};
+export type ResolvedCssFocus = {
+    targetFrameId: string;
+    tailSelector: string;
+    absPrefix: string;
+};
+export type Axis = "child" | "desc";
+export type Step = {
+    axis: Axis;
+    raw: string;
+    name: string;
+};
+export type A11yNode = {
+    role: string;
+    name?: string;
+    description?: string;
+    value?: string | number | boolean;
+    nodeId: string;
+    backendDOMNodeId?: number;
+    parentId?: string;
+    childIds?: string[];
+    children?: A11yNode[];
+    encodedId?: string;
+};
+export type A11yOptions = {
+    focusSelector?: string;
+    experimental: boolean;
+    tagNameMap: Record<string, string>;
+    scrollableMap: Record<string, boolean>;
+    encode: (backendNodeId: number) => string;
+};
+export type AccessibilityTreeResult = {
+    outline: string;
+    urlMap: Record<string, string>;
+    scopeApplied: boolean;
+};
+export type FrameParentIndex = Map<string, string | null>;
+/**
+ * Shared frame metadata that every snapshot step needs.
+ * - `rootId`: stable identifier for the main frame so we can detect root prefixes.
+ * - `parentByFrame`: lookup table for iframe parentage (used by focus scoping and prefixing).
+ * - `frames`: DFS-ordered frame ids so merging walks parents before children.
+ */
+export type FrameContext = {
+    rootId: string;
+    parentByFrame: FrameParentIndex;
+    frames: string[];
+};

package/dist/cjs/lib/v3/types/private/snapshot.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=snapshot.js.map

package/dist/cjs/lib/v3/types/private/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/snapshot.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Options that control how hybrid snapshots and targeted scopes are captured.\n */\nexport type SnapshotOptions = {\n  /**\n   * Filter the snapshot to a specific element/subtree using a selector that can cross iframes.\n   * Supports XPath (prefixed with `xpath=` or starting with `/`) and CSS with iframe hops via `>>`.\n   */\n  focusSelector?: string;\n  /**\n   * Pierce shadow DOM when calling DOM.getDocument. Defaults to true to retain the\n   * existing behaviour.\n   */\n  pierceShadow?: boolean;\n  /**\n   * Toggle whether iframe subtrees are included in the merged snapshot. Defaults to true.\n   */\n  includeIframes?: boolean;\n  /**\n   * Optional feature flag that surfaces experimental traversal tweaks in the Accessibility layer.\n   */\n  experimental?: boolean;\n};\n\n/**\n * Hybrid snapshot payload consumed by act/extract/observe handlers.\n */\nexport type HybridSnapshot = {\n  /** Merged outline across every frame. */\n  combinedTree: string;\n  /** EncodedId (frameOrdinal-backendNodeId) -> absolute XPath. */\n  combinedXpathMap: Record<string, string>;\n  /** EncodedId -> URL extracted from AX properties. */\n  combinedUrlMap: Record<string, string>;\n  /** Per-frame payloads expose the original relative data for debugging. */\n  perFrame?: PerFrameSnapshot[];\n};\n\nexport type PerFrameSnapshot = {\n  frameId: string;\n  outline: string;\n  xpathMap: Record<string, string>;\n  urlMap: Record<string, string>;\n};\n\n/**\n * Compact encoding of DOM data for an entire session. Shared between capture\n * and focus helpers so DOM traversal can be unit tested in isolation.\n */\nexport type SessionDomIndex = {\n  rootBackend: number;\n  absByBe: Map<number, string>;\n  tagByBe: Map<number, string>;\n  scrollByBe: Map<number, boolean>;\n  docRootOf: Map<number, number>;\n  contentDocRootByIframe: Map<number, number>;\n};\n\nexport type FrameDomMaps = {\n  tagNameMap: Record<string, string>;\n  xpathMap: Record<string, string>;\n  scrollableMap: Record<string, boolean>;\n  urlMap: Record<string, string>;\n};\n\nexport type ResolvedLocation = {\n  frameId: string;\n  backendNodeId: number;\n  absoluteXPath: string;\n};\n\nexport type ResolvedFocusFrame = {\n  targetFrameId: string;\n  tailXPath: string;\n  absPrefix: string;\n};\n\nexport type ResolvedCssFocus = {\n  targetFrameId: string;\n  tailSelector: string;\n  absPrefix: string;\n};\n\nexport type Axis = \"child\" | \"desc\";\n\nexport type Step = {\n  axis: Axis;\n  raw: string;\n  name: string;\n};\n\nexport type A11yNode = {\n  role: string;\n  name?: string;\n  description?: string;\n  value?: string | number | boolean;\n  nodeId: string;\n  backendDOMNodeId?: number;\n  parentId?: string;\n  childIds?: string[];\n  children?: A11yNode[];\n  encodedId?: string;\n};\n\nexport type A11yOptions = {\n  focusSelector?: string;\n  experimental: boolean;\n  tagNameMap: Record<string, string>;\n  scrollableMap: Record<string, boolean>;\n  encode: (backendNodeId: number) => string;\n};\n\nexport type AccessibilityTreeResult = {\n  outline: string;\n  urlMap: Record<string, string>;\n  scopeApplied: boolean;\n};\n\nexport type FrameParentIndex = Map<string, string | null>;\n\n/**\n * Shared frame metadata that every snapshot step needs.\n * - `rootId`: stable identifier for the main frame so we can detect root prefixes.\n * - `parentByFrame`: lookup table for iframe parentage (used by focus scoping and prefixing).\n * - `frames`: DFS-ordered frame ids so merging walks parents before children.\n */\nexport type FrameContext = {\n  rootId: string;\n  parentByFrame: FrameParentIndex;\n  frames: string[];\n};\n"]}