High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
Lite Engine
Deprecated: This document describes the legacy engine model (
chrome/lite/auto). The engine has been replaced by the browser provider model. Usebrowsers.defaultin your config with providers:chrome,cloak, orghost-chrome. See terminology for details. None of the code below exists at HEAD:internal/engine(Router, rules,LiteEngine), theserver.enginekey (now a config validation error) and theX-Engineheader were removed. The Gost-DOM static path now lives ininternal/browsers/ghostchrome/staticfetch, used by theghost-chromeprovider before it escalates to Chrome.
PinchTab includes a Lite Engine that performs DOM capture — navigate, snapshot, text extraction, click, and type — without requiring Chrome or Chromium. It is powered by Gost-DOM (v0.11.0, MIT), a headless browser written in pure Go.
Issue: #201
Why a Lite Engine?
Chrome is the default execution backend for PinchTab. A real browser session handles JavaScript rendering, bot-detection bypass, screenshots, and PDF generation. For many workloads — static sites, wikis, news articles, APIs — none of these are needed.
| Driver | Chrome | Lite |
|---|---|---|
| Memory per instance | ~200 MB | ~10 MB |
| Cold-start latency | 1–6 seconds | <100 ms |
| JavaScript rendering | yes | no |
| Screenshots / PDF | yes | no |
| No Chrome installation required | no | yes |
Lite wins at DOM-only workloads (3–4× faster navigate, 3× faster snapshot) and is the right choice for containers, CI pipelines, and edge environments where Chrome is not available.
Architecture
Engine Interface
All engines implement a common interface defined in internal/engine/engine.go:
type Engine interface {
Name() string
Navigate(ctx context.Context, url string) (*NavigateResult, error)
Snapshot(ctx context.Context, filter string) ([]SnapshotNode, error)
Text(ctx context.Context) (string, error)
Click(ctx context.Context, ref string) error
Type(ctx context.Context, ref, text string) error
Capabilities() []Capability
Close() error
}
The Chrome engine wraps the existing CDP/chromedp pipeline. LiteEngine in
internal/engine/lite.go implements the same interface using Gost-DOM.
Router (Strategy Pattern)
Request → Router → [Rule 1] → [Rule 2] → … → [Fallback Rule] → Engine
Router in internal/engine/router.go evaluates an ordered chain of RouteRule
implementations. The first rule that returns a non-Undecided verdict wins. Rules
are registered at startup and are hot-swappable via AddRule() / RemoveRule().
No handler, bridge, or config change is needed when adding new routing logic — only a
RouteRule implementation and a single router.AddRule(myRule) call.
Built-in Rules
| Rule | File | Behaviour |
|---|---|---|
CapabilityRule |
rules.go |
Routes screenshot, pdf, evaluate, cookies → Chrome |
ContentHintRule |
rules.go |
Routes URLs ending in .html/.htm/.xml/.txt/.md → Lite |
DefaultLiteRule |
rules.go |
Catch-all: all remaining DOM ops → Lite (used in lite mode) |
DefaultChromeRule |
rules.go |
Final fallback → Chrome (used in chrome and auto modes) |
Three Modes
| Mode | Behaviour |
|---|---|
chrome |
All requests go through Chrome. Backward-compatible default. |
lite |
DOM operations (navigate, snapshot, text, click, type) use Gost-DOM. Screenshot / PDF / evaluate / cookies fall through to Chrome (501 if Chrome is unavailable). |
auto |
Per-request routing via rules: capability and content-hint rules are evaluated first; unknown URLs fall back to Chrome. |
Request Flow (Lite Mode)
POST /navigate (server.engine=lite)
│
▼
handlers/navigation.go — HandleNavigate()
│
├─ useLite() == true
│ │
│ ▼
│ LiteEngine.Navigate(ctx, url)
│ ├─ HTTP GET url
│ ├─ Strip <script> tags (x/net/html tokenizer)
│ ├─ browser.NewWindowReader(reader) [Gost-DOM]
│ └─ return NavigateResult{TabID, URL, Title}
│
└─ w.Header().Set("X-Engine", "lite")
JSON {"tabId": "lp-1", "url": "…", "title": "…"}
Snapshot then traverses the Gost-DOM document tree and maps HTML semantics to accessibility roles (heading, link, button, textbox, …). Text walks the same tree and collapses whitespace runs.
Capability Boundaries
| Operation | Lite | Chrome |
|---|---|---|
| Navigate | ✅ (HTTP fetch + DOM parse) | ✅ |
| Snapshot | ✅ | ✅ |
| Text extraction | ✅ | ✅ |
| Click | ✅ (DOM event dispatch) | ✅ |
| Type | ✅ (DOM input events) | ✅ |
| Screenshot | ❌ → 501 Not Implemented |
✅ |
❌ → 501 Not Implemented |
✅ | |
| Evaluate (JS) | ❌ → 501 Not Implemented |
✅ |
| Cookies | ❌ → 501 Not Implemented |
✅ |
| JavaScript-rendered SPAs | ❌ | ✅ |
| Bot-detection bypass | ❌ | ✅ |
CapabilityRule ensures screenshot/pdf/evaluate/cookies are always routed to Chrome
even in lite mode.
Known Limitations
| Limitation | Detail |
|---|---|
<script> tags |
Gost-DOM panics on an un-initialized ScriptHost. Scripts are stripped before parse via x/net/html tokenizer. |
<a href> click |
Gost-DOM navigates on anchor click and may encounter scripts. Click() wraps execution in defer recover() and returns an error instead of panicking. |
CSS display:none |
Lite has no CSS engine so hidden elements still appear in the snapshot. |
| JavaScript-rendered content | Only the initial HTML is captured. SPAs (React, Next.js etc.) should use Chrome. |
| Sites that block HTTP bots | Stack Overflow and similar sites return 4xx/5xx to plain HTTP clients. Chrome bypasses this via a real browser session. |
Configuration
Set the engine in your config file:
{
"server": {
"engine": "lite"
}
}
The engine field is also forwarded to child bridge instances so every managed
instance in a multi-instance deployment uses the same mode.
Response Header
Responses served by the Lite engine include:
X-Engine: lite
This header is present on navigate, snapshot, and text responses when the lite
path was taken and is useful for observability and debugging.
Performance
Benchmark across 8 real-world websites (Navigate → Snapshot → Text pipeline, 7 sites where both engines completed successfully):
| Metric | Lite | Chrome | Speedup |
|---|---|---|---|
| Navigate total | 4,580 ms | 17,981 ms | 3.9× faster |
| Snapshot total | 1,739 ms | 5,155 ms | 3.0× faster |
| Text total | 925 ms | 500 ms | 0.5× (Chrome faster) |
| Grand total | 7,244 ms | 23,636 ms | 3.3× faster |
Chrome is faster at text extraction because it runs Mozilla Readability.js in-browser. Lite performs a raw DOM text walk which is slower for very large pages (e.g. Wikipedia CS: 687 ms vs 130 ms).
When to use each engine
| Workload | Recommendation |
|---|---|
| Static sites, wikis, news, blogs | Lite — 3–12× faster, no Chrome overhead |
| JavaScript-rendered SPAs | Chrome — Lite captures pre-JS HTML only |
| Sites that block HTTP clients | Chrome — real browser bypasses bot detection |
| Large-page snapshot / traversal | Lite — 3× faster snapshot |
| Text extraction on large articles | Chrome — Readability.js is more accurate |
| Screenshots, PDF, evaluate, cookies | Chrome — not supported in Lite |
Code Layout
| File | Purpose |
|---|---|
internal/engine/engine.go |
Engine interface, Capability constants, Mode enum, NavigateResult / SnapshotNode types |
internal/engine/lite.go |
LiteEngine — HTTP fetch, script stripping, Gost-DOM parse, role mapping |
internal/engine/router.go |
Router — ordered rule chain, AddRule / RemoveRule |
internal/engine/rules.go |
CapabilityRule, ContentHintRule, DefaultLiteRule, DefaultChromeRule |
internal/handlers/navigation.go |
useLite() fast path, X-Engine header |
internal/handlers/snapshot.go |
SnapshotNode → A11yNode conversion for lite path |
internal/handlers/text.go |
Lite text fast path |
cmd/pinchtab/cmd_bridge.go |
Resolves the engine mode string from CLI flag / config (resolveBridgeEngine) |
internal/server/bridge.go |
Wires the engine.Router (engine.NewRouter(mode, lite)) into the handler at startup |
internal/config/config_types.go |
RuntimeConfig.Engine / ServerConfig.Engine fields |
Dependency
| Package | Version | License | Purpose |
|---|---|---|---|
github.com/gost-dom/browser |
v0.11.0 | MIT | Headless browser: HTML parsing, DOM traversal, event dispatch |
github.com/gost-dom/css |
v0.1.0 | MIT | CSS selector evaluation |
golang.org/x/net |
existing | BSD-3 | HTML tokenizer used for script stripping |