High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
package handlers
import (
"context"
"fmt"
"net/http"
"regexp"
"sort"
"strconv"
"strings"
"time"
"github.com/pinchtab/pinchtab/internal/assets"
"github.com/pinchtab/pinchtab/internal/bridge"
"github.com/pinchtab/pinchtab/internal/bridge/observe"
"github.com/pinchtab/pinchtab/internal/browserops"
"github.com/pinchtab/pinchtab/internal/browsers"
"github.com/pinchtab/pinchtab/internal/config"
"github.com/pinchtab/pinchtab/internal/httpx"
"github.com/pinchtab/pinchtab/internal/scrape"
"github.com/pinchtab/pinchtab/internal/selector"
"unicode/utf8"
)
// @Endpoint GET /text
// @Param mode string query Extraction mode: "" default Readability, "raw"/"full" whole-page innerText, "markdown" seaportal Markdown of the rendered page (falls back to raw text as "markdown_fallback" when the converter yields nothing); any other value is a 400 (optional)
func (h *Handlers) HandleText(w http.ResponseWriter, r *http.Request) {
tabID := r.URL.Query().Get("tabId")
effectiveCfg, textRoute, ok := h.resolveReadRouting(w, r, tabID, "text", browsers.ShapeRenderedRead)
if !ok {
return
}
if !h.ensureBrowserOrRespond(w, effectiveCfg) {
return
}
mode, modeErr := resolveTextMode(r.URL.Query().Get("mode"))
if modeErr != nil {
httpx.Error(w, 400, modeErr)
return
}
format := strings.ToLower(strings.TrimSpace(r.URL.Query().Get("format")))
maxChars := -1
if v := r.URL.Query().Get("maxChars"); v != "" {
if n, err := strconv.Atoi(v); err == nil && n > 0 {
maxChars = n
}
}
resolvedTabID, tCtx, cancel, ok := h.resolveReadContext(w, r, tabID, effectiveCfg.ActionTimeout)
if !ok {
return
}
defer h.armIdleLifecycle(resolvedTabID)
defer cancel()
targetFrameID := h.resolveTargetFrameID(r, resolvedTabID)
// Auto-wait: if the document is still loading, wait for readyState to
// reach at least "interactive" before extracting text. Prevents empty or
// partial results when text is called before the page finishes loading.
h.waitForReadyState(tCtx)
selectorParam := r.URL.Query().Get("selector")
refParam := r.URL.Query().Get("ref")
ghostRoute := textRoute != nil && textRoute.UsedBrowser == config.BrowserGhostChrome
for attempt := 0; attempt < 2; attempt++ {
var modalNodeID int64
var modalOpen bool
var err error
if !ghostRoute {
modalNodeID, modalOpen, err = bridge.TopmostModalNodeID(tCtx, targetFrameID)
if err != nil {
respondSelectorFailure(w, err)
return
}
}
var text string
var extraction textExtraction
if selectorParam != "" || refParam != "" {
text, err = h.extractElementText(tCtx, resolvedTabID, selectorParam, refParam, modalNodeID)
} else if modalOpen {
err = h.Bridge.CallFunctionOnNode(tCtx, modalNodeID,
`function() { return this.innerText || this.textContent || ''; }`, nil, &text)
extraction = textExtraction{Text: text, Mode: extractionRaw, RawLength: utf8.RuneCountInString(text), RawKnown: true}
} else {
extraction, err = h.extractDocumentText(tCtx, mode, targetFrameID)
}
stable := true
if !ghostRoute {
afterNodeID, afterOpen, scopeErr := bridge.TopmostModalNodeID(tCtx, targetFrameID)
if scopeErr != nil {
respondSelectorFailure(w, fmt.Errorf("recheck topmost dialog: %w", scopeErr))
return
}
stable = modalNodeID == afterNodeID && modalOpen == afterOpen
}
if !stable {
continue
}
if err != nil {
if selectorParam != "" || refParam != "" {
respondSelectorFailure(w, fmt.Errorf("element text extract: %w", err))
return
}
httpx.Error(w, http.StatusInternalServerError, err)
return
}
scopeInfo := h.frameDisclosureFor(tCtx, resolvedTabID, targetFrameID)
if selectorParam != "" || refParam != "" {
h.writeElementTextResponse(w, r, tCtx, text, scopeInfo)
} else {
h.writeTextResponse(w, r, tCtx, extraction, maxChars, format, textRoute, scopeInfo)
}
return
}
httpx.Error(w, http.StatusConflict, fmt.Errorf("topmost dialog changed twice during text extraction; retry after the page settles"))
}
// writeElementTextResponse writes an already scope-validated element read.
func (h *Handlers) writeElementTextResponse(w http.ResponseWriter, r *http.Request, tCtx context.Context, text string, scope *frameDisclosure) {
url, _ := h.Bridge.CurrentURL(tCtx)
title, _ := h.Bridge.CurrentTitle(tCtx)
h.recordResolvedURL(r, url)
httpx.JSON(w, 200, scope.attach(map[string]any{
"url": url,
"title": title,
"text": text,
}))
}
const rawTextScript = `document.body.innerText`
// textModes are the values ?mode= accepts, each mapped to the extraction it selects.
// "full" is an ALIAS of raw because that is what the CLI's --full already sends and
// what the word plainly reads as — the whole unfiltered page. It used to fall through
// to readability, so a caller who read the CLI help and wrote ?mode=full against the
// API got the filtered output while believing they had asked for innerText.
var textModes = map[string]string{
"": "",
"raw": "raw",
"full": "raw",
"markdown": "markdown",
}
// resolveTextMode maps a requested mode onto the extraction that runs, and REFUSES an
// unimplemented one. Silently extracting readability for a mode nobody implemented hands
// the caller something other than what they asked for with no signal, which is the same
// defect class as losing a field boundary.
func resolveTextMode(requested string) (string, error) {
normalized := strings.ToLower(strings.TrimSpace(requested))
mode, ok := textModes[normalized]
if !ok {
return "", fmt.Errorf("unknown text mode %q; accepted values are %s (omit mode for the default Readability extraction)", requested, strings.Join(namedTextModes(), ", "))
}
return mode, nil
}
// namedTextModes lists the modes a caller can spell, sorted so the refusal reads the
// same on every run rather than however the map happened to iterate.
func namedTextModes() []string {
named := make([]string, 0, len(textModes))
for mode := range textModes {
if mode != "" {
named = append(named, mode)
}
}
sort.Strings(named)
return named
}
// Extraction modes echoed to the caller: which extractor produced the text.
const (
extractionReadability = "readability"
extractionRaw = "raw"
extractionReadabilityFallback = "readability_fallback"
extractionMarkdown = "markdown"
extractionMarkdownFallback = "markdown_fallback"
)
// isMarkdownExtraction reports whether an extraction came from the markdown
// mode, so the writer serves text/markdown and truncates on line boundaries.
// The fallback is included: the caller asked for markdown, and raw text is
// still valid Markdown.
func isMarkdownExtraction(mode string) bool {
return mode == extractionMarkdown || mode == extractionMarkdownFallback
}
// Readability is an article heuristic; on a layout it does not recognise as an
// article (landing page, dashboard, docs index) it returns the single block it
// scored highest. Measured against document.body.innerText, a collapse retains
// ~3% of the page while healthy article extraction retains ~91%, so any ratio in
// the low tens of percent separates the two with wide margin on both sides.
const readabilityCoverageRatio = 0.25
// Under this many raw characters the ratio is noise — a short page legitimately
// extracts to a couple of lines — so no fallback fires below it.
const readabilityCoverageFloorChars = 400
// headerTextExtraction reports the extraction mode on the format=text path,
// which returns a bare body with nowhere to carry the signal.
const headerTextExtraction = "X-PT-Text-Extraction"
// textExtraction is the document text plus the story of how it was produced:
// the mode that actually ran and the length of the raw document it was measured
// against (RawKnown is false when the baseline extraction itself failed).
type textExtraction struct {
Text string
Mode string
RawLength int
RawKnown bool
Title string
Description string
}
// extractDocumentText reads the document's text (readability unless mode=="raw")
// across all reachable frames, or scoped to targetFrameID when set. Readability
// output that covers too little of the raw document is discarded in favour of
// the raw text, reported as extractionReadabilityFallback.
func (h *Handlers) extractDocumentText(tCtx context.Context, mode, targetFrameID string) (textExtraction, error) {
if mode == extractionMarkdown {
return h.extractDocumentMarkdown(tCtx, targetFrameID)
}
if mode == "raw" {
text, err := h.extractText(tCtx, rawTextScript, targetFrameID)
if err != nil {
return textExtraction{}, err
}
return textExtraction{Text: text, Mode: extractionRaw, RawLength: utf8.RuneCountInString(text), RawKnown: true}, nil
}
text, err := h.extractText(tCtx, assets.ReadabilityJS, targetFrameID)
if err != nil {
return textExtraction{}, err
}
raw, rawErr := h.extractText(tCtx, rawTextScript, targetFrameID)
if rawErr != nil {
return textExtraction{Text: text, Mode: extractionReadability}, nil
}
extractedLen, rawLen := utf8.RuneCountInString(text), utf8.RuneCountInString(raw)
if readabilityCollapsed(extractedLen, rawLen) {
return textExtraction{Text: raw, Mode: extractionReadabilityFallback, RawLength: rawLen, RawKnown: true}, nil
}
return textExtraction{Text: text, Mode: extractionReadability, RawLength: rawLen, RawKnown: true}, nil
}
// extractDocumentMarkdown converts the frame-scoped rendered document to
// Markdown through the shared seaportal helper, reusing the same HTML read the
// /html inspect path uses so the frame scope is honoured identically. An empty
// conversion falls back to the raw document text, echoed as markdown_fallback.
func (h *Handlers) extractDocumentMarkdown(tCtx context.Context, targetFrameID string) (textExtraction, error) {
payload, err := h.inspectDocument(tCtx, targetFrameID, inspectKindHTML)
if err != nil {
return textExtraction{}, err
}
md := scrape.ToMarkdown(payload.HTML, payload.URL)
if md.Markdown == "" {
raw, rawErr := h.extractText(tCtx, rawTextScript, targetFrameID)
if rawErr != nil {
return textExtraction{}, rawErr
}
return textExtraction{
Text: raw,
Mode: extractionMarkdownFallback,
RawLength: utf8.RuneCountInString(raw),
RawKnown: true,
Title: md.Title,
Description: md.Description,
}, nil
}
return textExtraction{
Text: md.Markdown,
Mode: extractionMarkdown,
Title: md.Title,
Description: md.Description,
}, nil
}
func readabilityCollapsed(extractedLen, rawLen int) bool {
return rawLen >= readabilityCoverageFloorChars && float64(extractedLen) < float64(rawLen)*readabilityCoverageRatio
}
// extractText runs one extraction script through the traversal the request
// selected: every reachable frame (joined), or the scoped frame's isolated world
// so the expression sees the iframe's `document`, not the parent's. Both sides of
// the coverage ratio go through here, so they are always built identically.
func (h *Handlers) extractText(tCtx context.Context, script, targetFrameID string) (string, error) {
if targetFrameID == "" {
return h.extractTextAllFrames(tCtx, script), nil
}
return h.evalTextInFrame(tCtx, script, targetFrameID)
}
// truncateChars cuts s to at most limit characters, reporting whether it cut.
// Slicing by byte splits multi-byte characters and the orphaned bytes reach the
// client as U+FFFD.
func truncateChars(s string, limit int) (string, bool) {
if limit < 0 || utf8.RuneCountInString(s) <= limit {
return s, false
}
count := 0
for offset := range s {
if count == limit {
return s[:offset], true
}
count++
}
return s, false
}
// truncateCharsLine cuts s to at most limit characters, keeping whole lines
// while they fit and then rune-cutting the first line that overruns. A cut never
// splits a Markdown table row or link: a table row (starts with '|') that does
// not fit is dropped whole, and a cut that would land inside a [..](..) link is
// pulled back to before the link. Reports whether it cut. This differs from
// truncateChars, which cuts at the exact rune regardless of line structure.
func truncateCharsLine(s string, limit int) (string, bool) {
if limit < 0 || utf8.RuneCountInString(s) <= limit {
return s, false
}
var b strings.Builder
count := 0
for i, line := range strings.Split(s, "\n") {
sep := 0
if i > 0 {
sep = 1 // the newline joining this line to the previous
}
lineLen := utf8.RuneCountInString(line)
if count+sep+lineLen <= limit {
if i > 0 {
b.WriteByte('\n')
}
b.WriteString(line)
count += sep + lineLen
continue
}
// This line overruns. Keep a rune-cut of it unless its shape forbids
// splitting, in which case the whole line is dropped.
budget := limit - count - sep
if budget > 0 && !strings.HasPrefix(line, "|") {
if partial, ok := cutLineForMarkdown(line, budget); ok {
if i > 0 {
b.WriteByte('\n')
}
b.WriteString(partial)
}
}
break
}
return b.String(), true
}
// markdownLinkRe matches a whole [text](url) link so a truncation can refuse to
// cut through one.
var markdownLinkRe = regexp.MustCompile(`\[[^\]]*\]\([^)]*\)`)
// cutLineForMarkdown returns the leading runes of line (at most budget) for use
// as the final partial line of a truncation. A cut that would fall inside a
// [..](..) link is pulled back to the link's start so no half-open link escapes,
// then trailing whitespace is trimmed. ok is false only when nothing survives —
// the line began with the link that the budget split.
func cutLineForMarkdown(line string, budget int) (string, bool) {
cut := len(line)
count := 0
for off := range line {
if count == budget {
cut = off
break
}
count++
}
for _, loc := range markdownLinkRe.FindAllStringIndex(line, -1) {
if loc[0] < cut && cut < loc[1] {
cut = loc[0]
break
}
}
partial := strings.TrimRight(line[:cut], " \t")
if partial == "" {
return "", false
}
return partial, true
}
// writeTextResponse truncates, IDPI-scans, and writes the document text as
// plain text (format text/plain) or the JSON envelope.
func (h *Handlers) writeTextResponse(w http.ResponseWriter, r *http.Request, tCtx context.Context, extraction textExtraction, maxChars int, format string, route *browserops.RouteMetadata, scope *frameDisclosure) {
text := extraction.Text
truncated := false
if maxChars > -1 {
if isMarkdownExtraction(extraction.Mode) {
text, truncated = truncateCharsLine(text, maxChars)
} else {
text, truncated = truncateChars(text, maxChars)
}
}
url, _ := h.Bridge.CurrentURL(tCtx)
title, _ := h.Bridge.CurrentTitle(tCtx)
if extraction.Title != "" {
title = extraction.Title
}
h.recordResolvedURL(r, url)
// IDPI: scan extracted text for injection patterns and optionally wrap.
result := h.ContentGuard.Scan(text, url)
if result.Blocked {
httpx.Error(w, http.StatusForbidden, fmt.Errorf("content blocked by IDPI scanner: %s%s", result.BlockReason, idpiScannerHint()))
return
}
result.SetHeaders(w)
text = result.Text
w.Header().Set(headerTextExtraction, extraction.Mode)
if format == "text" || format == "plain" {
contentType := "text/plain; charset=utf-8"
if isMarkdownExtraction(extraction.Mode) {
contentType = "text/markdown; charset=utf-8"
}
w.Header().Set("Content-Type", contentType)
w.WriteHeader(200)
_, _ = w.Write([]byte(text))
return
}
resp := scope.attach(map[string]any{
"url": url,
"title": title,
"text": text,
"truncated": truncated,
"route": route,
"extraction": extraction.Mode,
"textLength": utf8.RuneCountInString(text),
})
if extraction.RawKnown {
resp["rawLength"] = extraction.RawLength
}
if extraction.Description != "" {
resp["description"] = extraction.Description
}
if result.Warning != "" {
resp["idpiWarning"] = result.Warning
}
httpx.JSON(w, 200, resp)
}
// @Endpoint GET /tabs/{id}/text
// @Param mode string query Extraction mode: "" default Readability, "raw"/"full" whole-page innerText, "markdown" seaportal Markdown of the rendered page (falls back to raw text as "markdown_fallback" when the converter yields nothing); any other value is a 400 (optional)
func (h *Handlers) HandleTabText(w http.ResponseWriter, r *http.Request) {
h.withPathTabID(w, r, h.HandleText)
}
// extractTextAllFrames evaluates the text script in every reachable frame and
// concatenates the results. Cross-origin frames are silently skipped (the
// isolated-world creation fails, just like snap skips inaccessible frames).
func (h *Handlers) extractTextAllFrames(ctx context.Context, script string) string {
frameTree, err := observe.FetchFrameTree(ctx)
if err != nil {
// Fallback: top frame only.
var text string
_ = h.Bridge.Evaluate(ctx, script, &text, bridge.EvalOpts{})
return text
}
ids := observe.FrameIDs(frameTree)
if len(ids) == 0 {
var text string
_ = h.Bridge.Evaluate(ctx, script, &text, bridge.EvalOpts{})
return text
}
var parts []string
for _, id := range ids {
t, err := h.evalTextInFrame(ctx, script, id)
if err != nil || strings.TrimSpace(t) == "" {
continue
}
parts = append(parts, t)
}
if len(parts) == 0 {
var text string
_ = h.Bridge.Evaluate(ctx, script, &text, bridge.EvalOpts{})
return text
}
return strings.Join(parts, "\n\n")
}
// evalTextInFrame evaluates a text-extraction script in a specific frame's
// isolated world and returns the result string.
func (h *Handlers) evalTextInFrame(ctx context.Context, script, frameID string) (string, error) {
var text string
if err := h.Bridge.EvaluateInFrame(ctx, frameID, script, &text, bridge.EvalOpts{}); err != nil {
if frameID != "" {
return "", fmt.Errorf("text extract (frame %s): %w", frameID, err)
}
return "", fmt.Errorf("text extract: %w", err)
}
return text, nil
}
func (h *Handlers) extractElementText(ctx context.Context, tabID, selectorValue, ref string, scopeBackendNodeID int64) (string, error) {
var text string
if scopeBackendNodeID != 0 {
var sel selector.Selector
if ref != "" {
sel = selector.Parse("ref:" + ref)
} else {
sel = selector.Parse(selectorValue)
}
nodeID, err := bridge.ResolveUnifiedSelectorWithinNode(ctx, sel, h.Bridge.GetRefCache(tabID), scopeBackendNodeID)
if err != nil {
return "", err
}
if err := h.Bridge.CallFunctionOnNode(ctx, nodeID,
`function() { return this.innerText || this.textContent || ''; }`, nil, &text); err != nil {
return "", err
}
return text, nil
}
if ref != "" {
cache := h.Bridge.GetRefCache(tabID)
if cache == nil {
return "", fmt.Errorf("ref not found: %s (no snapshot cache): %w", ref, bridge.ErrSelectorNoMatch)
}
target, ok := cache.Lookup(ref)
if !ok {
return "", fmt.Errorf("ref not found: %s: %w", ref, bridge.ErrSelectorNoMatch)
}
nodeID := target.BackendNodeID
err := h.Bridge.CallFunctionOnNode(ctx, nodeID,
`function() { return this.innerText || this.textContent || ''; }`,
nil, &text)
if err != nil {
return "", err
}
return text, nil
}
var script string
switch {
case strings.HasPrefix(selectorValue, "xpath:"):
xpath := selectorValue[len("xpath:"):]
script = fmt.Sprintf(`(function(){var r=document.evaluate(%q,document,null,XPathResult.FIRST_ORDERED_NODE_TYPE,null);var n=r.singleNodeValue;return n?(n.innerText||n.textContent||''):null})()`, xpath)
case strings.HasPrefix(selectorValue, "//") || strings.HasPrefix(selectorValue, "(//"):
script = fmt.Sprintf(`(function(){var r=document.evaluate(%q,document,null,XPathResult.FIRST_ORDERED_NODE_TYPE,null);var n=r.singleNodeValue;return n?(n.innerText||n.textContent||''):null})()`, selectorValue)
case strings.HasPrefix(selectorValue, "text:"):
textVal := selectorValue[len("text:"):]
script = fmt.Sprintf(`(function(){var w=document.createTreeWalker(document.body,NodeFilter.SHOW_TEXT);while(w.nextNode()){if(w.currentNode.textContent.includes(%q))return w.currentNode.parentElement.innerText||w.currentNode.parentElement.textContent||''}return null})()`, textVal)
case strings.HasPrefix(selectorValue, "css:"):
css := selectorValue[len("css:"):]
script = fmt.Sprintf(`(function(){var n=document.querySelector(%q);return n?(n.innerText||n.textContent||''):null})()`, css)
default:
script = fmt.Sprintf(`(function(){var n=document.querySelector(%q);return n?(n.innerText||n.textContent||''):null})()`, selectorValue)
}
if err := h.Bridge.Evaluate(ctx, script, &text, bridge.EvalOpts{}); err != nil {
return "", err
}
if text == "" {
return "", fmt.Errorf("no element matches selector %q: %w", selectorValue, bridge.ErrSelectorNoMatch)
}
return text, nil
}
func (h *Handlers) waitForReadyState(ctx context.Context) {
wctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
// An eval error or a non-loading state both stop the wait, matching the
// original loop which returned (silently) on either condition.
_ = pollUntil(wctx, 100*time.Millisecond, func() (bool, error) {
var state string
if err := h.Bridge.Evaluate(wctx, `document.readyState`, &state, bridge.EvalOpts{}); err != nil {
return true, nil
}
return state != "loading", nil
})
}