frontrender

frontrender is a powerful headless browser tool built on Puppeteer, designed for AI agents and developers to simulate user-like interaction with JavaScript-heavy frontend pages.

It enables rendering, clicking, form filling, and structured web scraping using customizable selectors. Ideal for automating tasks or scraping dynamic sites.

✨ Features

• 🔍 Extracts visible text or specific elements
• 🖱 Simulates user clicks and form fills
• 📸 Captures page screenshots (returned as base64)
• 🧠 Maintains session state for multi-step navigation
• 🧰 Works with selectors like CSS, XPath, tag, aria, and more

📦 Installation

npm install frontrender

🧪 Example Usage

import renderTool from "frontrender";

const result = await renderTool.invoke({
  url: ["https://example.com"],
  action: "find",
  selectionType: "css",
  value: "h1",
  saveState: false,
});
console.log(result);


---

## 📘 API Reference

### `renderTool.invoke(input: RenderInput): Promise<RenderResult[]>`

### Input Schema

| Field           | Type                                                      | Required | Description                                                                  |
| --------------- | --------------------------------------------------------- | -------- | ---------------------------------------------------------------------------- |
| `url`           | `string[]`                                                | ✅        | URLs to navigate to                                                          |
| `action`        | `"click" \| "fill" \| "reload" \| "find" \| "skeleton"`   | ✅        | Action to perform                                                            |
| `selectionType` | `"css" \| "xpath" \| "text" \| "aria" \| "none" \| "tag"` | ✅        | Selector type to locate element                                              |
| `value`         | `string`                                                  | ✅        | The selector value or text (e.g., `".menu"`, `"a"`, or `"//div[@id='app']"`) |
| `elm`           | `string`                                                  | ❌        | (Optional) Additional selector information                                   |
| `cookies`       | `Cookie[]`                                                | ❌        | (Optional) Cookies to set before visiting the page                           |
| `saveState`     | `boolean`                                                 | ❌        | If true, stores browser session for reuse                                    |
| `stateId`       | `string`                                                  | ❌        | Use to resume a previous session                                             |

---

## 📤 Output Format

The response is a JSON array of objects with both text and screenshot:

```json
[
  {
    "type": "text",
    "text": "Extracted content here"
  },
  {
    "type": "image_url",
    "image_url": {
      "url": "data:image/png;base64,..."
    }
  }
]

Each page's screenshot is included in base64 format alongside the parsed content.

🧠 Example Use Cases

• LangChain agents doing multi-step form workflows
• Scraping menu data from dynamic restaurant websites
• Simulating a real user for bot testing or QA
• Navigating modals and tabs with intelligent clicking (coming soon)

🛠 Known Issues

• Modal-heavy or heavily JS-rendered pages may need improved interaction simulation
• Form fill sometimes struggles with deeply nested inputs
• click and fill actions on non-CSS selectors need edge-case testing

📜 License

MIT © 2025 Sebastian Hernandez-Tavares

💬 Author

Sebastian Hernandez-Tavares GitHub • Email

🧪 Dev Testing

You can run the built-in test:

// Uncomment to test
// testCode();

---

Let me know if you want me to:
- Convert this to a downloadable `.md` file
- Include badges (e.g. `npm version`, `license`)
- Create the final `package.json` with this README linked properly