Volume III β freeact v0.3.1
A Practical Manual for the Domestication
of Semi-Sentient Web Browsers
Browsers are not tools. They are creatures β vast, semi-sentient rendering engines that evolved to display the Web. Each has its own temperament, nesting habits, and susceptibility to domestication. freeact is the art of taming them.
The most docile of the browser creatures. Native to colder climates. Exhibits natural resistance to anti-bot predators. When properly tamed, passes CloudFront checkpoints without raising suspicion. This is your primary mount.
Nesting: %LOCALAPPDATA%\Yandex\YandexBrowser\User Data
Call: browser.exe
Previously kept for diversity. Proved unreliable against CloudFront sentinels. All specimens released back into the wild. Five Yandex-only profiles remain in the stables.
The browser creature must first be roused from slumber. The daemon serves as its eternal perch β a spirit that keeps the creature alive between commands, eliminating the painful ritual of rebirth each time.
Summon the daemon spirit:
freeact daemon start β spoken once per sessionBind a creature to a name:
freeact --session mytask browser open DSYandex https://example.comObserve the creature's form:
freeact --session mytask state β reveals all visible appendagesAfter every interaction, the creature's form mutates. Indices shift. Elements vanish. New growths appear. Always observe (state) before touching (click/input). Never assume an index survives between observations.
Break this cycle at your peril. The creature will reject your touch if you skip observation.
| Poke | click 5 | Index from state output |
| Feed text | input 3 "hello" | Reacts to React, Vue, vanilla |
| Hover | hover 2 | Triggers dropdowns, tooltips |
| Press key | keys "Enter" | Enter, Tab, Escape... |
| Scroll | scroll down | up/down, --amount 1000 |
| Select | select 4 "Option" | Dropdown choice |
| Upload | upload 8 ./file.pdf | File input elements |
Each whisper is attempted 3 times with escalating force:
Attempt 1 β Playwright normal click
Attempt 2 β Force click (ignores overlays)
Attempt 3 β dispatchEvent('click') β JS el.click()
Inputs use nativeInputValueSetter for React compatibility. Exponential backoff: 0.3s β 0.6s β 1.2s.
| Soul-reading | get markdown | Full page as markdown (turndown.js, local) |
| Flesh | get html | Raw HTML, --selector for parts |
| Name | get title | Document title |
| Whisper | get text 7 | Visible text of element |
| Blood | get value 3 | Input current value |
| Portrait | screenshot | PNG capture, --full for full page |
| Mind-probe | eval "js code" | Arbitrary JavaScript execution |
Every fetch() and XMLHttpRequest is silently captured. No page.route() overhead β pure JS interception. View the creature's communication:
network requests β list all capturedLog stores up to max_network_entries (default 500). JSON responses auto-parsed. Text truncated at 10KB.
The creature wears a shroud woven from these illusions. Applied once per context, never duplicated:
| 1. | navigator.webdriver | deleted from prototype |
| 2. | navigator.plugins | Chrome PDF Plugin, PDF Viewer, Native Client |
| 3. | navigator.languages | ['en-US', 'en'] |
| 4. | navigator.platform | Win32 |
| 5. | hardwareConcurrency | 8 cores |
| 6. | deviceMemory | 8 GB |
| 7. | window.chrome.runtime | faked listeners |
| 8. | Permissions API | notification bypass |
| 9. | Canvas fingerprint | Β±0.05 noise per pixel (β€100K px) |
| 10. | WebGL vendor | Intel Inc. / Intel Iris |
| 11. | document.hidden | always false |
| 12. | visibilityState | always 'visible' |
| 13. | Notification API | requestPermission suppressed |
| 14. | chrome.runtime fallback | dual-check creation |
| 15. | Real browser profile | hardlinks, authentic cookies |
Some territories are guarded by the CloudFront Sentinel. It rejects headless creatures and Chromium impostors. The only known passage requires:
β Yandex Browser as mount
β Headed mode (visible window)
β Stealth shroud active
β Real browser profile with cookies
All Chrome/Edge/Cromium mounts have been retired. Five Yandex profiles remain.
For one-off missions where you need content without establishing a permanent bond. Launches a fresh creature, extracts, releases. No session baggage.
freeact stealth-extract https://site.com --content-type markdown -o page.md β quick, stateless, stealth-patchedWhen a site casts a CAPTCHA spell, the solver attempts counter-magic in this order:
1. Audio challenge β downloads MP3, transcribes via Google Speech or local Whisper
2. Image OCR β Tesseract / EasyOCR text extraction
3. reCAPTCHA v2 β human-like bezier mouse path + checkbox click
4. hCaptcha β iframe checkbox detection
5. Cloudflare Turnstile β behavioral simulation, 15s patience
Connect to your actual daily browser β the one with your real logins, cookies, and sessions. No copy, no new profile. You become a passenger in your own creature.
freeact setup --browser yandex β one-time: creates desktop shortcut with CDP
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
β CLI (cli.py) βββ human / AI agent commands β
β daemon (daemon.py :9341) βββ persistent spirit β
β β β
β ββββββ΄ββββββββββββββββββββββββββββββββββββββ β
β β _handlers.py βββ shared brain (16 ops) β β
β ββββββ¬ββββββββββββββββββββββββββββββββββββββ β
β β β
β ββββββ΄βββββ¬βββββββββββ¬βββββββββββ¬βββββββββββ β
β β state βinteract βextract β network β β
β β DOM treeβclick/typeβmarkdown β fetch/XHRβ β
β β wait βhover/keysβhtml/eval β capture β β
β βββββββββββ΄βββββββββββ΄βββββββββββ΄βββββββββββ β
β β β
β ββββββ΄ββββββββββββββββββββββββββββββββββββββ β
β β browser.py βββ CDP connection manager β β
β β stealth.py βββ 15 anti-detection spellsβ β
β β config.py βββ 5s cached configuration β β
β β session.py βββ 8h session persistence β β
β ββββββββββββββββββββββββββββββββββββββββββββ β
β β β
β ββββββ΄βββββ β
β β Yandex β βββ the tamed creature β
β β Browser β real profile, real cookies β
β βββββββββββ β
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
Stored at ~/.freeact/config.json. Cached in memory for 5 seconds between reads.
| default_browser | yandex | The Alpha mount |
| headless | false | Always visible (CloudFront passage) |
| stealth | true | Invisibility shroud active |
| timeout | 30000 | 30 seconds patience |
| max_network_entries | 500 | Thought capture capacity |
Thou shalt use no browser but Yandex. Chrome and Edge are false prophets that fall before CloudFront. The Alpha mount alone passes the sentinel.
Thou shalt keep the creature visible (headed=true). Invisible creatures (headless) are detected and slain by guardian spirits.
Thou shalt observe (state) before touching (click/input). The creature's form mutates after every interaction. Indices are ephemeral.
State β interact β wait stable β state. This cycle is sacred. Break it and the creature will reject thy commands.
Every command requires --session. The session binds thee to the creature. Sessions perish after 8 hours of neglect.
All command logic flows through _handlers.py. Daemon and CLI are but two faces of the same spirit. Duplicate not thy logic.
Copy not the creature's nest fully. Share its inodes through hardlinks. Only the mutable flesh need be duplicated.
Ruff must pass with zero complaints. Tests must show fourteen green marks. The code is sacred; keep it pure.
Load not thy markdown converter from distant CDNs. Bundle it within thy package. The creature needs no internet to process HTML.
All significant events must be recorded in ~/.freeact/freeact.log. The creature's life story is written there for post-mortem analysis.