import type { Metadata } from "next";
import { CodeBlock } from "@/components/ui/code-block";
import { DocPage } from "@/components/docs/doc-page";
import { A, Code, H2, H3, Li, P, Strong, Table, TBody, Td, Th, THead, Tr, Ul } from "@/components/docs/prose";
import { Callout, ComingSoon } from "@/components/docs/callout";
import { Endpoint } from "@/components/docs/endpoint";
import { ParamTable } from "@/components/docs/param-table";
import { CodeTabs } from "@/components/docs/code-tabs";
import { ResponseExample } from "@/components/docs/response-example";
import { fetchTabs } from "@/components/docs/snippets";

export const metadata: Metadata = {
  title: "Browser",
  description: "Managed browser rendering on POST /v1/fetch: browser, browser_fallback, wait_for, wait_ms, wait_until, javascript, block_resources and screenshot; how automatic escalation works, what is captured, limits and errors.",
};

const RENDERED = {
  request_id: "req_5d6e7f8g9h0i1j2k",
  success: true,
  status: 200,
  url: "https://app.example.com/dashboard",
  final_url: "https://app.example.com/dashboard?tab=results",
  content: null,
  content_type: "text/html; charset=utf-8",
  headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
  cookies: [
    { name: "session", value: "9f3a…", domain: "app.example.com", path: "/" },
    { name: "cf_clearance", value: "…", domain: ".example.com", path: "/" },
  ],
  text: "Results\nRef\tPrice\nA-1041\tCA$ 1,250\n…",
  page: { title: "Dashboard — Results", description: null, canonical: "https://app.example.com/dashboard", lang: "en", og: {}, links_count: 64 },
  screenshot: "iVBORw0KGgoAAAANSUhEUgAA…",
  metadata: {
    network: "residential",
    country: "CA",
    mode: "browser",
    attempts: 1,
    duration_ms: 4930,
    bytes: 612340,
    session: "sess_8f2k1m9d3p7q4r6s",
    cached: false,
    timing: { dns_ms: 17, proxy_connect_ms: 0, tls_ms: 0, origin_ms: 4480, processing_ms: 61, total_ms: 4930 },
  },
};

const ACTIONS: Array<[string, string, string]> = [
  ["goto", "{ url }", "Navigate to a URL and wait for the load event."],
  ["click", "{ selector }", "Click the first element matching a CSS selector."],
  ["type", "{ selector, text, delay? }", "Focus an element and type text, optionally with a per-key delay."],
  ["scroll", "{ selector? | y? }", "Scroll an element into view, or scroll the page by a number of pixels."],
  ["wait", "{ selector? | ms? }", "Wait for a selector to appear, or for a fixed duration."],
  ["evaluate", "{ script }", "Run JavaScript in the page and capture its return value."],
  ["screenshot", "{ full_page?, selector? }", "Capture a PNG of the viewport, the full page or one element."],
  ["extract", "{ schema }", "Return structured data from the rendered DOM (shares the Extraction schema format)."],
];

export default function BrowserPage() {
  return (
    <DocPage path="/docs/browser" eyebrow="Core API" title="Browser" description="Render JavaScript-heavy pages in a managed headless Chromium that inherits Fetcha's routing, geography and sessions. Available on every fetch with browser: true, and used automatically when a plain request is blocked by a JavaScript challenge." status="Stable">
      <Endpoint method="POST" path="/v1/fetch  { browser: true }" scope="fetch:execute" status="Live" />
      <P>
        Browser rendering is part of the fetch request, not a separate endpoint. The browser runs on Fetcha&apos;s infrastructure, connects through the <Strong>same proxy network, country and
        session</Strong> as a plain fetch, loads the page, waits for it to settle and returns the rendered DOM in the usual response document. No <Code>browser:use</Code> scope is needed (the scope
        name still exists for compatibility).
      </P>

      <H2>Rendered fetch</H2>
      <ParamTable
        rows={[
          { name: "browser", type: "boolean", default: "false", description: <>Render the page in the managed browser instead of fetching it over plain HTTP.</> },
          { name: "browser_fallback", type: "boolean", default: "true", description: <>Escalate to the browser automatically when an HTTP attempt is blocked by a JavaScript challenge or anti-bot page. Set <code>false</code> to never render.</> },
          { name: "wait_until", type: '"load" | "domcontentloaded" | "networkidle"', default: '"domcontentloaded"', description: <>Navigation event to wait for. <code>networkidle</code> waits until no network request has been made for 500 ms; use it for pages that fetch their data after load.</> },
          { name: "wait_for", type: "string (CSS selector)", constraints: "≤ 512 chars", description: <>Selector that must be present before capture, after <code>wait_until</code>. Fails with <code>BROWSER_TIMEOUT</code> if it never appears within the timeout.</> },
          { name: "wait_ms", type: "integer (ms)", constraints: "0–30,000", description: <>Extra settle time after the wait condition and selector. Useful for pages that animate content in.</> },
          { name: "javascript", type: "boolean", default: "true", description: <>Set <code>false</code> to render with scripting disabled (useful to bypass client-side redirects or paywalls that rely on JS).</> },
          { name: "block_resources", type: "boolean", default: "true", description: <>Skip images, fonts and media. Saves bandwidth and time; scripts, stylesheets and XHR still load.</> },
          { name: "screenshot", type: "boolean", default: "false", description: <>Return a PNG of the viewport in <code>screenshot</code> (base64).</> },
          { name: "device", type: '"desktop" | "mobile" | "tablet"', description: <><code>mobile</code> renders with an iPhone viewport and User-Agent; <code>desktop</code> (default) uses 1366 × 768.</> },
          { name: "locale", type: "string", description: <>Sets the browser language and <code>Accept-Language</code>, e.g. <code>{`"fr-CA"`}</code>.</> },
        ]}
      />
      <P>
        All other fetch fields apply unchanged: <Code>country</Code>, <Code>region</Code>, <Code>city</Code>, <Code>network</Code>, <Code>session</Code>, <Code>headers</Code>, <Code>cookies</Code>,{" "}
        <Code>format</Code>, <Code>links</Code>, <Code>timeout</Code>, <Code>retries</Code> and <Code>debug</Code>. <Code>method</Code> and <Code>body</Code> are ignored in the browser; navigation is always a{" "}
        <Code>GET</Code>.
      </P>

      <H3>Example</H3>
      <P>Render a dashboard behind a login, reusing the sticky session that holds the login cookies, wait for the results table, and return readable text plus a screenshot.</P>
      <CodeTabs
        tabs={fetchTabs(
          { url: "https://app.example.com/dashboard", browser: true, wait_for: "table.results", wait_ms: 500, country: "CA", session: "sess_8f2k1m9d3p7q4r6s", format: "text", screenshot: true },
          {
            javascript: `console.log(data.metadata.mode, data.page.title); // "browser" "Dashboard — Results"\nawait fs.promises.writeFile("dashboard.png", Buffer.from(data.screenshot, "base64"));`,
            python: `print(data["metadata"]["mode"], data["page"]["title"])\nopen("dashboard.png", "wb").write(base64.b64decode(data["screenshot"]))`,
          },
        )}
      />
      <ResponseExample status={200} title="200 OK · metadata.mode: browser" body={RENDERED} />

      <H2>What is captured</H2>
      <Ul>
        <Li>
          <Strong>DOM after settle.</Strong> <Code>content</Code> is the serialised document (<Code>document.documentElement.outerHTML</Code>) once <Code>wait_until</Code>, <Code>wait_for</Code> and{" "}
          <Code>wait_ms</Code> are satisfied. <Code>format: text</Code> and <Code>markdown</Code> convert this rendered DOM, so client-side content is included.
        </Li>
        <Li>
          <Strong>Final URL.</Strong> <Code>final_url</Code> reflects server redirects and client-side navigations (<Code>location.replace</Code>, meta refresh, framework routers) that happened before capture.
        </Li>
        <Li>
          <Strong>Status and headers of the main document.</Strong> <Code>status</Code> and <Code>headers</Code> come from the main navigation response, not from sub-resources. A page that loads but shows an
          error inside the app still reports the document&apos;s status.
        </Li>
        <Li>
          <Strong>Cookies.</Strong> <Code>cookies</Code> contains the browser&apos;s cookie jar for the site after rendering, including cookies set by JavaScript and challenge clearances. Replay them via the{" "}
          <Code>cookies</Code> field or keep the <Code>session</Code>.
        </Li>
        <Li>
          <Strong>Page metadata and links.</Strong> <Code>page</Code> (title, description, canonical, lang, Open Graph, link count) and, with <Code>links: true</Code>, <Code>links[]</Code> are extracted from the
          rendered DOM.
        </Li>
        <Li>
          <Strong>Optional screenshot.</Strong> A PNG of the viewport (1366 × 768 desktop, 390 × 844 mobile), base64-encoded in <Code>screenshot</Code>.
        </Li>
      </Ul>

      <H2>Captcha solving</H2>
      <P>
        Most JavaScript challenges clear on their own inside the real browser. When Cloudflare asks for an interactive Turnstile verification instead, Fetcha intercepts the widget parameters,
        obtains a token from a managed human-verification service (2captcha) and hands it to the page, adopting the user agent the token was issued for. This typically adds 10–40 seconds, so keep
        <Code>timeout</Code> generous (60 s or more) for hard targets. Set <Code>{`solve_captcha: false`}</Code> to opt out on a request. Attempts that needed a token report{" "}
        <Code>captcha_solved: true</Code> in <Code>metadata.debug.attempts[]</Code>.
      </P>

      <H2>Automatic escalation</H2>
      <P>
        You rarely need to set <Code>browser: true</Code> yourself. With the default <Code>browser_fallback: true</Code>, Fetcha starts every request over plain HTTP because it is faster and cheaper.
        When an attempt is classified as a JavaScript challenge or an anti-bot interstitial (Cloudflare challenge or Turnstile, DataDome, PerimeterX, Akamai, Kasada, Imperva, AWS WAF, Vercel attack
        mode, or a soft 200 challenge page), the router escalates: it re-plays the request in the browser through the same route, letting the challenge script run and the clearance cookie be set.
      </P>
      <Ul>
        <Li>
          Escalation counts as one attempt and shares the request&apos;s single <Code>timeout</Code> and <Code>retries</Code> budget.
        </Li>
        <Li>
          <Code>metadata.mode</Code> is <Code>browser</Code> when the final attempt was rendered. With <Code>debug: true</Code>, each attempt lists its <Code>mode</Code> and, for blocked ones, the{" "}
          <Code>block_reason</Code>.
        </Li>
        <Li>Plain 403/429 blocks without a JavaScript challenge are retried on a new IP or a premium route first; the browser is used when the block needs a script to be executed.</Li>
        <Li>
          Set <Code>browser_fallback: false</Code> for latency-sensitive calls where a blocked answer is acceptable, or when you handle challenges yourself.
        </Li>
      </Ul>
      <Callout variant="info" title="Learning">
        Escalations feed the per-domain profile like any other attempt. A site that consistently needs the browser will be rendered directly on later requests, saving the wasted HTTP attempt.
      </Callout>

      <H2>Limits and errors</H2>
      <Table dense>
        <THead>
          <Tr>
            <Th>Limit</Th>
            <Th>Value</Th>
          </Tr>
        </THead>
        <TBody>
          <Tr>
            <Td>Concurrent renders per organization</Td>
            <Td mono>8</Td>
          </Tr>
          <Tr>
            <Td>Render time</Td>
            <Td>
              Bounded by the request <Code>timeout</Code> (max 120 s), shared with any HTTP attempts made before escalation
            </Td>
          </Tr>
          <Tr>
            <Td>Viewport</Td>
            <Td mono>1366 × 768 desktop · 390 × 844 mobile</Td>
          </Tr>
          <Tr>
            <Td>Response size</Td>
            <Td>Same 20 MB cap as plain fetches, applied to the serialised DOM. Screenshots are not counted.</Td>
          </Tr>
        </TBody>
      </Table>
      <Table dense>
        <THead>
          <Tr>
            <Th>Situation</Th>
            <Th>Result</Th>
          </Tr>
        </THead>
        <TBody>
          <Tr>
            <Td>
              Page did not reach <Code>wait_until</Code>, <Code>wait_for</Code> never appeared, or the render exceeded the remaining <Code>timeout</Code>
            </Td>
            <Td mono>504 BROWSER_TIMEOUT</Td>
          </Tr>
          <Tr>
            <Td>Browser pool disabled or unavailable</Td>
            <Td mono>400 BROWSER_UNAVAILABLE</Td>
          </Tr>
          <Tr>
            <Td>More than 8 renders in flight for the organization</Td>
            <Td mono>429 CONCURRENCY_LIMIT</Td>
          </Tr>
          <Tr>
            <Td>Target blocked even in the browser, on every attempt</Td>
            <Td>
              <Code>200</Code> with <Code>success: false</Code> and the last page, like any block
            </Td>
          </Tr>
        </TBody>
      </Table>
      <P>
        Rendered requests are logged like any other request: the request log shows <Strong>mode</Strong> per attempt, and bandwidth is metered on the bytes the browser actually transferred (which is
        why <Code>block_resources</Code> is on by default).
      </P>

      <H2>Tips</H2>
      <Ul>
        <Li>
          Prefer <Code>wait_for</Code> over a large <Code>wait_ms</Code>: it returns as soon as the content exists and fails clearly when it never does.
        </Li>
        <Li>
          Use <Code>{`format: "markdown"`}</Code> or <Code>{`"text"`}</Code> with the browser to get the rendered content without shipping the framework&apos;s HTML.
        </Li>
        <Li>
          Combine with a <A href="/docs/sessions">session</A> for logged-in areas: the browser reuses the session&apos;s IP and the cookies you pass, and returns the updated jar.
        </Li>
        <Li>
          If the site exposes the JSON endpoint the page calls, fetching it directly with <Code>{`format: "json"`}</Code> is still faster than rendering. See <A href="/docs/examples">Examples</A>.
        </Li>
      </Ul>

      <H2>Coming soon: browser actions</H2>
      <ComingSoon title="POST /v1/browser is not yet available">
        Multi-step interactions (click, type, scroll, evaluate) in one browser context are planned. <Code>POST /v1/browser</Code> currently returns <Code>400 BROWSER_UNAVAILABLE</Code>. The design below
        is indicative; field names may change before launch. Follow the <A href="/changelog">changelog</A>.
      </ComingSoon>
      <Endpoint method="POST" path="/v1/browser" status="Coming soon" />
      <Table>
        <THead>
          <Tr>
            <Th>Action</Th>
            <Th>Parameters</Th>
            <Th>Description</Th>
          </Tr>
        </THead>
        <TBody>
          {ACTIONS.map(([name, params, desc]) => (
            <Tr key={name}>
              <Td mono>{name}</Td>
              <Td mono>{params}</Td>
              <Td>{desc}</Td>
            </Tr>
          ))}
        </TBody>
      </Table>
      <CodeBlock
        lang="json"
        title="Planned request"
        code={JSON.stringify(
          {
            url: "https://www.example.ca/login",
            country: "CA",
            session: "sess_8f2k1m9d3p7q4r6s",
            actions: [
              { type: "type", selector: "#email", text: "me@example.com" },
              { type: "type", selector: "#password", text: "•••••••" },
              { type: "click", selector: "button[type=submit]" },
              { type: "wait", selector: ".account-summary" },
              { type: "screenshot", full_page: false },
              { type: "extract", schema: { balance: "string", plan: "string" } },
            ],
          },
          null,
          2,
        )}
      />
    </DocPage>
  );
}