Write Puppeteer Code with JavaScript Only

How User Scripts Work

SOCIALBROWSER is made available automatically inside trusted Social Browser User Scripts. Targets can be CSS selectors or real DOM elements:

Copyawait SOCIALBROWSER.page.click("#save");
await SOCIALBROWSER.page.click(document.querySelector("#save"));

Keep scripts scoped to the intended profile, workspace, and page. Review scripts before trusting them, and test changes on a low-risk page first.

Quick Start

Wait for the form, guard the result, enter placeholder data, submit it, and wait for a success state:

Copyconst page = SOCIALBROWSER.page;

const email = await page.waitForSelector("#email", {
  visible: true,
  timeout: 10000,
});

if (!email) return null;

await page.type("#email", "name@example.com", { clear: true });
await page.type("#password", "secure-password", { clear: true });
await page.click('button[type="submit"]');

return await page.waitForSelector(".dashboard, .success-message", {
  visible: true,
  timeout: 15000,
});

Core Page Actions

These helpers operate on a selector or DOM element. Options vary by action; use the options supported by the current Social Browser build.

Human-Like Visible Actions

Humanized behavior is enabled by default for the relevant visible actions. Typing uses varying delays between characters; spaces and punctuation can add a short pause; and the visible black cursor follows a curved path with acceleration and deceleration. click, hover, and focus can move to the target before acting.

These are visible interaction effects, not a guarantee of human detection outcomes. They do not bypass CAPTCHA, access controls, or website policies, and they do not guarantee that a website will treat automation as human activity.

Copyconst page = SOCIALBROWSER.page;

await page.type("#message", "Hello! I would like more information.", {
  clear: true,
});

await page.cursor.move("#send-button");
await page.cursor.click("#send-button");
await page.scrollHuman(0, 700);

Advanced timing

Copyawait SOCIALBROWSER.page.type("#search", "Social Browser", {
  clear: true,
  delayMin: 45,
  delayMax: 130,
  pauseChance: 0.15,
});

await SOCIALBROWSER.page.cursor.move("#search-button", {
  durationMin: 300,
  durationMax: 900,
});

Fast mode

Copyawait SOCIALBROWSER.page.type("#search", "fast mode", {
  clear: true,
  human: false,
});

await SOCIALBROWSER.page.click("#search-button", { human: false });

Mouse, Keyboard, Cursor, and Touch APIs

Use the lower-level device helpers when a selector-based page action is not the right fit:

Useful combinations

Copy// Menu hover
await page.hover("#account-menu");
await page.waitForSelector("#account-menu .dropdown", { visible: true });

// Keyboard search
await page.focus("#search");
await page.keyboard.type("Social Browser");
await page.keyboard.press("Enter");

// Coordinate click and visible cursor control
await page.mouse.click(420, 280);
await page.cursor.show();
await page.cursor.move("#next");
await page.cursor.click("#next");

Finding and Waiting for Elements

Use selectors, evaluation helpers, and waits to keep a script synchronized with the current page:

Extract result-card titles

Copyconst titles = await page.$$eval(".result-card", (cards) =>
  cards.map((card) => card.querySelector("h2")?.textContent?.trim()).filter(Boolean)
);

return titles;

Shadow DOM lookup

Copyconst button = await page.findDeep("site-shell", "button.save");
if (button && await page.isEnabled(button)) {
  await page.click(button);
}

Wait for a loading overlay to disappear

Copyawait page.waitForSelector(".loading-overlay", { visible: true });
await page.waitForGone(".loading-overlay", { timeout: 15000 });

Locator API

The Puppeteer-inspired locator helper keeps a target together while you wait, hover, click, fill, focus, or retrieve its element handle.

Copyconst submit = SOCIALBROWSER.page.locator('button[type="submit"]');

await submit.wait({ visible: true });
await submit.hover();
await submit.click();

Locators also support fill(), focus(), and elementHandle():

Copyconst search = page.locator("#search");
await search.fill("Social Browser");
await search.focus();
const handle = await search.elementHandle();

Run Real Puppeteer Code When You Need It

SOCIALBROWSER.page.runPuppeteer() is intended for trusted Social Browser User Scripts. It runs trusted, real Puppeteer code in the Main Process against the exact current Social Browser workspace/tab.

Copyconst result = await SOCIALBROWSER.page.runPuppeteer(
  async (browser, page, args) => {
    await page.screenshot({ path: args.path });

    return {
      title: await page.title(),
      url: page.url(),
    };
  },
  { path: "C:/temp/social-browser-page.png" },
);

console.log(result);

Inside the callback, you can read the title and URL, evaluate DOM code, or take a screenshot:

Copyconst details = await SOCIALBROWSER.page.runPuppeteer(async (browser, page) => ({
  title: await page.title(),
  url: page.url(),
  heading: await page.$eval("h1", (node) => node.textContent.trim()),
}));

console.log(details);

For a simple serializable Puppeteer method call, page.puppeteer("title") can be used:

Copyconst title = await SOCIALBROWSER.page.puppeteer("title");
console.log(title);

Methods that require unsupported Chrome DevTools Protocol domains may not be available in every embedded browser build.

Complete Example: Search and Collect Results

This example waits for the search field, types naturally, uses the visible cursor, waits for results, reads result-card titles, and returns an array while guarding against missing elements.

Copyconst page = SOCIALBROWSER.page;
const search = await page.waitForSelector("#site-search", {
  visible: true,
  timeout: 10000,
});

if (!search) return [];

await page.type("#site-search", "Social Browser", { clear: true });
const searchButton = await page.waitForSelector("#search-button", {
  visible: true,
  timeout: 5000,
});

if (!searchButton) return [];

await page.cursor.move("#search-button");
await page.cursor.click("#search-button");

const results = await page.waitForSelector(".result-card", {
  visible: true,
  timeout: 15000,
});

if (!results) return [];

return (await page.$$eval(".result-card", (cards) =>
  cards.map((card) => card.querySelector("h2")?.textContent?.trim()).filter(Boolean)
)) || [];

Complete Example: Login Form

Use placeholder credentials while developing. Do not hard-code real passwords in shared User Scripts.

Copyconst page = SOCIALBROWSER.page;
const form = await page.waitForSelector("form#login", {
  visible: true,
  timeout: 10000,
});

if (!form) return null;

await page.type("#email", "name@example.com", { clear: true });
await page.type("#password", "placeholder-password", { clear: true });

const submit = await page.waitForSelector('button[type="submit"]', {
  visible: true,
  timeout: 5000,
});

if (!submit) return null;

await page.click(submit);

return await page.waitForSelector(".dashboard, .login-error", {
  visible: true,
  timeout: 15000,
});

Use only accounts and pages you are authorized to operate, and follow the terms and policies of the websites you use. Social Browser does not guarantee access, account status, CAPTCHA results, or human-like treatment by a third-party website.