navigate_dom_path

Instructions

Implementation Reference

• src/tools/BrowserAIDOMTools.ts:609-652 (handler)

  Main handler function for the navigate_dom_path tool. Validates args, loads page data from DB, navigates the DOM path using the helper, and returns element information (tagName, textContent, attributes, children).

  async navigateDOMPath(args: any): Promise<any> {
    try {
      const validatedArgs = NavigateDOMPathSchema.parse(args);
      logger.info(`Navigating DOM path: ${validatedArgs.path} for page: ${validatedArgs.page_id}`);
  
      // Load page data from database
      const page = await this.pagesRepo.findById(validatedArgs.page_id);
      if (!page) {
        throw new Error(`Page with ID ${validatedArgs.page_id} not found`);
      }
  
      if (!page.domJsonContent) {
        throw new Error(`No DOM content available for page ${validatedArgs.page_id}`);
      }
  
      const domJson = page.domJsonContent;
  
      // Navigate to the specified path
      const targetElement = this.navigatePath(domJson, validatedArgs.path);
  
      const result = {
        page_id: validatedArgs.page_id,
        path: validatedArgs.path,
        element: {
          tagName: targetElement?.tagName,
          textContent: validatedArgs.extract_content ? targetElement?.textContent : undefined,
          attributes: targetElement?.attributes,
          children: validatedArgs.include_children ? targetElement?.children : undefined,
        },
        navigation_info: {
          element_type: targetElement?.tagName,
          has_children: targetElement?.children && Array.isArray(targetElement.children) && targetElement.children.length > 0,
          text_length: targetElement?.textContent?.length || 0,
          attribute_count: targetElement?.attributes ? Object.keys(targetElement.attributes).length : 0,
        }
      };
  
      return result;
  
    } catch (error) {
      logger.error("Error navigating DOM path:", error);
      throw new Error(`Failed to navigate DOM path: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/tools/BrowserAIDOMTools.ts:86-107 (helper)

  Private helper navigatePath that traverses a DOM JSON object following a parsed dot-notation path, resolving property names and array indices.

  private navigatePath(domJson: any, path: string): any {
    const segments = this.parsePath(path);
    let current = domJson;
  
    for (const segment of segments) {
      if (segment.type === 'property') {
        if (current && typeof current === 'object' && segment.name in current) {
          current = current[segment.name];
        } else {
          throw new Error(`Property '${segment.name}' not found at path: ${path}`);
        }
      } else if (segment.type === 'index') {
        if (Array.isArray(current) && segment.index < current.length) {
          current = current[segment.index];
        } else {
          throw new Error(`Index ${segment.index} out of bounds at path: ${path}`);
        }
      }
    }
  
    return current;
  }

• src/tools/BrowserAIDOMTools.ts:112-129 (helper)

  Private helper parsePath that splits a dot-notation path string into segments (property names and array indices like 'body.main.article[0]').

  private parsePath(path: string): Array<{ type: 'property' | 'index'; name?: string; index?: number }> {
    const segments: Array<{ type: 'property' | 'index'; name?: string; index?: number }> = [];
    const parts = path.split('.');
  
    for (const part of parts) {
      const arrayMatch = part.match(/^(.+)\[(\d+)\]$/);
      if (arrayMatch) {
        // Property with array index
        segments.push({ type: 'property', name: arrayMatch[1] });
        segments.push({ type: 'index', index: parseInt(arrayMatch[2]) });
      } else {
        // Simple property
        segments.push({ type: 'property', name: part });
      }
    }
  
    return segments;
  }

• src/tools/BrowserAIDOMTools.ts:19-24 (schema)

  Local Zod schema (NavigateDOMPathSchema) defining input parameters: page_id, path (dot notation), extract_content (default true), include_children (default false).

  const NavigateDOMPathSchema = z.object({
    page_id: z.string().describe("Unique identifier of the page to navigate"),
    path: z.string().describe("Dot notation path to navigate (e.g., 'body.main.article[0].paragraphs[2]')"),
    extract_content: z.boolean().default(true).describe("Whether to extract text content from the target element"),
    include_children: z.boolean().default(false).describe("Whether to include child elements in the response"),
  });

• src/tools/BrowserAIDOMTools.ts:789-794 (registration)

  Registration of the 'navigate_dom_path' tool in the getTools() method, mapping name, description, inputSchema, and handler (navigateDOMPath).

  {
    name: "navigate_dom_path", 
    description: "Navigate to specific elements in DOM JSON using dot notation paths (e.g., 'body.main.article[0].paragraphs[2]'). Extracts content and provides element information.",
    inputSchema: zodToJsonSchema(NavigateDOMPathSchema),
    handler: this.navigateDOMPath.bind(this)
  },