A letter typo on a digit is rejected by <input type=number>, so the
correcting Backspace deleted the previous real digit (1999 -> 999).
Digit neighbors are now digit-only in the Python, JS (Playwright +
Puppeteer) and .NET wrappers.
Layout can report a top edge of -1/64 px on an unscrolled page, which skipped
the pinned-at-top check and sent a pointless upward scroll burst before the
click. Allow 1px slack in Python, JS and .NET, with regression tests.
Also credit @Shub3am in README contributors (#554).
* fix(humanize): scroll the x axis in scroll-into-view (#521)
humanScrollIntoView only measured and scrolled the y axis. A target past
the right edge of a horizontally overflowing page counted as in view, so
no wheel events were sent, the click point landed offscreen and the
pointer check failed with "element is covered by <none>" after the full
timeout.
After the vertical pass, a horizontal pass now checks that the box fits
inside the viewport width and, if not, centres it with the same
humanized wheel burst on the x axis. It skips the scroll when the page
is already pinned at the needed horizontal boundary, mirroring the y
pinned check. Applied to Python (sync and async), JS Playwright,
Puppeteer and .NET.
.NET: IRawScrollPage.GetScrollStateAsync now also returns X and MaxX.
Fixes#521
* fix(humanize): handle RTL scrollX in the horizontal pinned check (#521)
In right-to-left documents Chrome's window.scrollX runs from 0 down to
-(scrollWidth - clientWidth). The x pass treated "scrollX <= 0" as pinned
at the left edge, so on an RTL page at its start a target in the left
overflow was never scrolled into view and the click failed with "covered
by <none>".
The scroll-state script now also reads the viewport direction (taken from
<body> when present, as Chrome does) and returns an RTL-aware minX and
maxX. Python, JS Playwright and .NET compare against those. The .NET
adapter shifts X and MaxX by minX so IRawScrollPage keeps its tuple shape
and X still runs 0..MaxX.
Puppeteer has no pinned check on the x axis and is unchanged.
* fix(humanize): skip the x pass for sub-pixel distances
A box wider than the viewport never passes the containment check, so
every action on it ran the x pass even when it was already centred: a
mouse move to the scroll area and a 0 or 1px wheel. Skip the pass when
the distance to centre is under 1px. Applied to Python (sync and async),
JS Playwright, Puppeteer and .NET.
* test(humanize): reword the set_content note on the #521 browser tests
The comment stated as fact that set_content never settles in
CloakBrowser. What I observed is narrower: it timed out in local runs of
these tests, so say that instead.
The download is signature/checksum-verified before extraction, so the
per-member path/symlink sanitization was redundant. Extract archives as-is
across all three wrappers (Python, JS, .NET), tar and zip.
- Python: filter="fully_trusted" (pins legacy behavior; 3.14 defaults to
"data"), plain zip extractall
- JS: drop the tar filter callback; inline the one-line extractTar
- .NET: TarFile/ZipFile.ExtractToDirectory; remove orphan ResolveSafeEntryPath
- Drop the obsolete traversal/symlink tests
Add a Mac fonts count to `cloakbrowser info` next to the existing Windows
font check, in the Python, JS, and .NET wrappers. Counts the macOS core
font set via fc-list on Linux and prints Mac fonts: n/20 with a conditional
nudge when incomplete. Tests added in all three wrappers.
The banner wrote '->' and em dashes straight to stderr. On a cp1252/strict
console (UK/EU-locale Windows) that raised UnicodeEncodeError and aborted the
binary-download path, blocking license apply and profile launch in the Manager.
Swap the banner glyphs to ASCII and route the writes through a swallow-all
helper so a cosmetic banner can never abort a launch. Same treatment in the JS
and .NET wrappers plus the Windows-font warning. Regression tests added across
all three (ASCII-only + cp1252-no-crash).
Increase the default GeoIP resolution timeout from 5 to 20 seconds across the Python, JavaScript, and .NET wrappers.
Fail the launch when requested GeoIP resolution times out, cannot load its database, cannot complete a lookup, or leaves timezone or locale unresolved. Explicit timezone and locale overrides remain valid without an egress-IP result.
Add parity coverage for the new timeout and failure behavior.
A supplied license key the server rejects, or one that cannot be validated
(server unreachable, no cache), now raises instead of silently downloading the
free binary. No-key (keyless) and valid-key (Pro) paths unchanged. Python, JS,
and .NET, with mirror tests in each.
Removing the Playwright fallback closed a main-world read leak but left every
get_by_* locator raising UnsupportedHumanizeSelectorError. Reimplement the four
cheap engines in the isolated-world resolver so those locators work again.
Selector engines (shared resolver, byte-identical in all three wrappers):
- internal:testid and internal:attr (placeholder/alt/title). The i flag is a
case-insensitive substring on the raw attribute value; test ids stay strict.
- internal:text. Exact compares the full normalized subtree text, unlike the
public text= engine which compares immediate fragments.
- internal:label, resolving aria-labelledby, then aria-label, then .labels.
- internal:role and >> chaining stay unsupported; the error now names what is
supported and the workaround.
Text parity fixes in __elementText, checked against playwright-core:
- drop a <br> to newline branch Playwright does not have
- concatenate shadow-root text into the host, which Playwright does
- give the public text= engine Playwright's self/selfAndChildren rule, since
contains() cannot see into a shadow root and kept the host as a match
Target identity: payloads carry a per-world generation (protocol v2). The world
is rebuilt on navigation and its id counter restarts, so an id alone could name
a different element. Generation is bounded to Int32, which the .NET wrapper
requires.
force=True now skips the pointer check entirely, matching Playwright, instead of
suppressing only the coverage rejection.
Also: drop dead _BOX_OP, _ACTIONABLE_OP and readSnapshot, and add a test
asserting the three hand-copied resolver literals stay identical and free of
characters that would terminate their host string literals.
Verified against Playwright's own locator resolution in a real browser:
20/20 engine parity, 7/7 text parity.
Derive actionable geometry from rendered text and visible descendants when an element has no box of its own. Preserve existing geometry behavior for normal elements and exclude hidden descendant content. Add Python, JavaScript, and .NET unit and browser regressions covering text, nested content, visibility, and humanized clicks.
Collect light-DOM matches before recursively merging open Shadow Root
matches, preserving Playwright order for broad selectors using first or nth.
Add resolver and real-browser coverage for mixed and nested Shadow Roots.
Resolve#512 by ignoring non-rendered document content during text
matching and selecting the same visible target as Playwright.
Improve text, structural, selector-list, and open shadow-root handling.
Align element state checks and forced-click behavior, and prevent pointer
dispatch when the original target is detached or replaced during mouse
movement.
Add sync, async, and real-browser regression coverage.
`cloakbrowser info` printed a bare seat count with no denominator, so a
customer could not tell whether they were at capacity (#513). It also
collapsed six distinct outcomes into one "unavailable": unreachable,
timeout, invalid key, inactive licence, rate limited, and the server
reporting the count as unknown while degraded.
Adds SessionSeats (active, limit, state, reason) and getSessionSeats to
all three wrappers; get_active_session_count keeps its signature and
delegates. The limit is read from the server, never derived from the plan
name, and falls back to the old bare count when absent.
Python, JS and .NET renderers verified byte-identical.
Humanized actions could fail with an element-not-attached error after a
navigation driven by a click or form submit, since the checks only refreshed
on goto. Now refresh on any main-frame navigation. Python, JS
Playwright/Puppeteer, and .NET. Regression from 0.5.6.
Forward caller-provided press delays through humanized page, frame, locator, element handle, and keyboard paths across Python, JavaScript, and .NET.
Use each automation library's native press operation for shortcut chords while retaining the existing humanized pre-press timing and focus behavior.
Python + JS wrappers. Add a stealth_dom / stealthDom module: reimplements the
common Playwright selector grammar (css, :has-text, text=, xpath=, trailing
>> nth=N) for direct DOM resolution in the isolated execution context, with a
fallback to the regular Playwright read for grammar it can't resolve. World
reads are wrapped so a world/CDP failure falls back rather than propagating out
of the humanized action.
ensure_actionable, ensure_stable, scroll geometry (_get_element_box + the
no_viewport window-size read), and check_pointer_events now read through it,
sync and async. Selector-based main-page actions (click/dblclick/hover/type/
fill/focus/press) are covered; ElementHandle and sub-frame paths unchanged.
JS routes Locator actions through frame methods, so main-frame locator clicks
now delegate to the humanized page methods (which use the shared helpers)
instead of the frame-scoped Playwright reads; sub-frames unchanged.
Tests: builders + parse, the rewired helpers' branching via a mock isolated
world, a Node-driven check of the shipped resolver JS selector semantics, and a
guard that main-frame locator clicks delegate to the humanized page path.
- humanize frames created after page load across Python and JavaScript\n- keep sync, async, Playwright, and Puppeteer paths idempotent\n- wrap .NET frame lifecycle event payloads without raw frame leaks\n- add cross-wrapper unit and browser regression coverage
Wire the existing launch()-time geoip resolver into the info/doctor command
across Python, JS, and .NET. With --proxy, info resolves the exit IP and the
timezone/locale a launch would apply (caching the GeoIP DB if absent) and prints
them in text and --json. Plain info is unchanged (no network) and now hints at
the flag. Adds diagnostics tests in all three suites.
A concurrent-session denial resolves after the CDP handshake, so the browser
exits with a live connection already established. The launch-failure path never
sees it and the user gets a bare TargetClosedError on their first call (#477).
The binary records the license exit code (76-79) to a per-launch file whose path
the wrapper passes via CLOAKBROWSER_LICENSE_STATUS_FILE. The wrapper reads it
when a guarded call throws and re-raises the correct CloakBrowserLicenseError.
Discrimination is on the file, not the error type, so a genuine crash is never
mislabelled. Fail-safe (no key or unwritable dir -> feature off) and
backward-compatible (old binaries never write the file).
Guarded surfaces: new_page/new_context, a persistent context's already-open
pages (goto + the wait family), and Puppeteer user-created contexts. Orphaned
denial files are swept at mint time; an observed code is cached in-process so a
concurrent second call can't miss it; the .NET reader parses as tolerantly as
Python/JS.
Implemented across Python, JavaScript (Playwright + Puppeteer), and .NET, with
unit tests. Reproduced end-to-end with a real over-cap denial.
cmd.exe defaults to cp850/cp1252, which carry no check mark or arrow.
Printing one raised UnicodeEncodeError and aborted the report at the
Launch line, so everything after it was lost — including on the success
path, once the launch probe stopped failing.
Marks now degrade to plain text per glyph when the console cannot
encode them. UTF-8 consoles (Linux, macOS, Windows Terminal) keep the
original output byte for byte.
.NET substitutes rather than throwing here (verified on the reference
box), so only the Python wrapper needed the change.
Chromium only handles --version on POSIX, so on Windows the switch is
ignored and a browser starts instead of printing. The 10s probe then
timed out and a healthy install was reported as broken, flashing a
window on screen each run.
Probe with --no-startup-window there: it exits immediately, opens no
window, and a broken binary still exits non-zero. No version is
reported on Windows, as nothing is printed. Linux and macOS unchanged.
Test uses a stub that hangs unless the flag is passed, mirroring the
real binary rather than a print-and-exit stub.
A license.key or cached Pro marker in the developer's cache dir resolved the
box as Pro, flipping version-gated defaults (headless no_viewport, inline proxy
auth) and failing 9 Python + 4 JS tests locally. Both suites now run against a
temp cache dir.
Add a preview release channel system to all wrappers (Python, JavaScript, .NET),
allowing users to opt into newer binary builds before they go stable.
- Python: preview/stable channel resolution in download, launch, CLI
(install, update, clear-cache), and license validation
- JavaScript: preview/stable channel in CLI, launch, license, and config
- .NET: preview/stable channel in CLI, license, diagnostics, and config
- All wrappers: channel fallback indicator, auto-update gate,
CLOAKBROWSER_RELEASE_CHANNEL env var support
- Harden channel resolution: reuse the resolution sidecar on offline lookups,
defensive marker/JSON parsing, atomic version-marker writes, a launch-time
preview-to-stable fallback notice, channel-aware info download URL, and
Python/JS/.NET parity for the fallback default
- Binary 150.0.7871.114.4 changelog (Linux x64 + arm64)
- Updated READMEs, CHANGELOG, and tests for all wrappers
cloakbrowser login gets a free key via GitHub sign-in (or saves a paid key); logout reverts. Launch banner and info are now tier-aware (keyless / free / pro). A free key drops any version pin so it always gets the latest build (server force-serves latest; a pinned manifest would fail checksum). Python, JS, and .NET kept in sync. README documents the free tier + commands.
A raw --fingerprint-timezone/--lang/--fingerprint-locale in args is now
promoted to an explicit value in maybe_resolve_geoip, so geoip only fills
the values the user did not set. Mirrors the timezone=/locale= param path.
Python, JS, and .NET, with tests.
zsh globs the unquoted bracket, so a user copy-pasting the printed
install hint hits a shell error. Quote it in both messages; update the
test that pinned the old string.
geoip.py used Path.rename which cannot overwrite on Windows, so a stale
DB never refreshed and every launch re-downloaded ~70 MB in a loop. No
lock meant concurrent launches each fired their own download.
- Python: os.replace + threading.Lock (initial + background paths)
- .NET: File.Move(overwrite) + SemaphoreSlim guard
- JS: shared in-flight promise (rename already overwrites)
- tests: overwrite + concurrent single-download coverage
pyproject: bump classifier to Production/Stable
A Pro license now gets a "Sessions: N seats in use" line, answering
"how many sessions do I have running?" without asking support.
Never cached (a cached count is a wrong count), skipped under --quick to
keep `info` network-free, and prints "unavailable" rather than a made-up
number when the count cannot be determined.
Python, JS and .NET.
The Pro binary exits with a distinct code per license failure; the wrappers ignored it, so a user got a bare "browser closed" error with no reason.
Add CloakBrowserLicenseError plus a launch-error parser that maps the exit code to a clear message, mirrored across the Python, JS, and .NET wrappers. Non-license failures pass through unchanged.
Route authenticated HTTP/HTTPS proxies through the browser's native proxy
authentication only on binaries that support it, resolved per platform and
binary version via a capability gate (sibling to the existing viewport and
window-geometry gates). Older binaries, including the free macOS and ARM
builds, fall back to the standard Playwright proxy path instead of emitting
credentials the binary cannot parse, so authenticated proxies keep working on
macOS and ARM instead of silently failing. Applied across the Python,
JavaScript, Puppeteer, and .NET wrappers.
With humanize=True, Locator/frame actions on an element inside an iframe
(frame.locator("#btn").click(), fill(), hover(), the frame.click(...)
equivalents) raised ElementNotAttachedError because the humanize layer
resolved every selector against the main frame. Route sub-frame locators
and frame-level actions through the owning frame's own document, keeping
humanized mouse motion inside the iframe; native fallback when the box
can't be read or the frame is detached. Python only (JS and .NET were
already frame-correct).
Adds mocked routing unit tests (sub-frame -> owning frame, main-frame ->
page, unpatched -> native), the human_click arg-order + _frame_fill
fallback guards, and @slow real-binary iframe integration tests.
Free-tier launch banner and 'cloakbrowser info' upgrade hint now advertise
the 7-day free Pro trial (Chromium 148) across Python, JS, and .NET; same
CTA added to both READMEs. Also surface binary verification failures verbatim
instead of falling back to a cached build (transient-only fallback).
info now shows the cached build that will launch AND the server's latest
Pro version on separate lines, so the two can no longer silently diverge
(a customer saw info report latest while launch ran a stale cache).
- Pro version resolution: unpinned launch prefers the server latest when it
is newer than or replaces a missing cached build, else stays on cache;
advances the version marker so info and later offline launches match.
- update command is license-aware: a valid Pro key updates the Pro binary,
everyone else updates free.
- Replace the fire-and-forget Pro background update thread with a foreground
rate-limited check (one network call/hour), honoring CLOAKBROWSER_AUTO_UPDATE=false.
- A valid Pro license never falls back to the free binary: get_effective_version
returns None when no Pro build is cached; resolution fails loudly instead.
- Tampering signal (BinaryVerificationError) surfaces verbatim on the unpinned
upgrade path — the cached-Pro fallback is only for transient download failures.
- get_effective_version(pro) requires the binary be executable, so info can't
report a build launch would reject.
- info --quick stays network-free (skips the server latest lookup); prints a
'not downloaded yet' line instead of 'None' when offline with no cache.
- Align the JS .last_update_check marker to seconds (Python/.NET parity).
- Mirror across Python, JS, and .NET wrappers; add update/CLI tests.
Windows font check now covers the full 8-font set (adds the two monospace
fonts) and reports a strict N/8 count; the launch-time warning fires on any
incomplete set, not just when none are present. Adds a separate Office-font
group (10 fonts) reported as an informational N/10 with no install nudge.
Ported across all three wrappers (Python, JS, .NET) to keep them in sync.
Follow-up fixes for the geoip-no-proxy and start-maximized commits:
- geoip: resolve the egress IP before the DB check so a DB-download failure
still yields the WebRTC exit IP — the proxy WebRTC spoof survives a DB hiccup
- geoip: skip the exit-IP echo call on no-proxy + explicit tz/locale (the WebRTC
IP would just be the real connection IP the site already sees — a no-op)
- launch_context: suppress auto --start-maximized when the caller set an explicit
viewport, matching JS across Python and .NET
- docker: poll for X readiness before starting openbox instead of a blind sleep
(avoids a silent window-manager startup race)
- refactor: extract the WebRTC exit-IP append into one helper per wrapper
- remove a dead isPrivateIp in the JS wrapper
- tests: fix stale no-proxy geoip assertions; add launch_context parity + .NET
geoip coverage
Python, JS and .NET wrappers kept in parity.
Default headed and headless launches to a maximized window (fills the
screen) on binaries at or above the same threshold as the headless
no-viewport default. Suppressed when the caller sets --window-size /
--window-position / --start-maximized or an explicit viewport; older
builds are unchanged. Version-gated via a dedicated helper sharing the
no-viewport threshold. Mirrored across Python, JS and .NET with parity tests.
The Docker image runs openbox so headed --start-maximized is honored
(bare Xvfb has no window manager; headless is unaffected).
When geoip=True and no proxy is set, resolve the machine's own public IP
directly (echo services, no proxy) and use it for timezone, locale, and the
WebRTC exit IP — same path as the proxied case. Previously geoip no-oped
without a proxy, leaving UTC + en-US in bare Docker/cloud launches.
Expand COUNTRY_LOCALE_MAP from 50 to 132 countries across all three wrappers
(Python, JS, .NET) so far more egress IPs resolve a locale.
Mirrored in cloakbrowser/, js/src/, and dotnet/. Tests added for the no-proxy
resolution path.
Headed launches already skip Playwright's emulated viewport (no_viewport)
because a fixed CDP viewport on a real window forces outerWidth < innerWidth,
a physically impossible geometry that's a bot tell. Headless historically kept
a fixed DEFAULT_VIEWPORT since there's no window chrome to make coherent
without emulation — but a newer Chromium build (>=148.0.7778.215.4) now
reports coherent dimensions in headless too, so it can drop the emulated
viewport the same way headed does.
Added binary_supports_headless_no_viewport() (mirrored in Python, JS, .NET) to
gate this per resolved binary version: local overrides with no declared
version stay on the old fixed-viewport path (unknown version = safe default),
while an explicit browser_version/CLOAKBROWSER_VERSION always wins so internal
builds can opt in. HEADLESS_NO_VIEWPORT_MIN_VERSION is currently set to a
version that hasn't shipped yet, so this is a no-op until that build is live —
behavior is byte-identical to today for every existing binary.
- Pass the resolved license key via environment (CLOAKBROWSER_LICENSE_KEY)
when launching the Chromium binary so the Pro binary can authenticate.
- Inject key when a custom user_env is provided with default file source:
Playwright replaces (not merges) the child env, which can drop HOME and
prevent the binary from finding ~/.cloakbrowser/license.key.
- Normalize user_env by filtering None/undefined values consistently across
Python, JS, and .NET wrappers.
- Add HomeDirOverride test seam to the .NET wrapper for cache path mocking.
info (plus a doctor alias) now reports the binary that will actually
launch for the resolved license instead of whatever is cached on disk:
it resolves and validates the license, shows the real tier, and on a
keyless or invalid key reports the free binary. Adds a launch test
(chrome --version) with a Linux missing-shared-library probe, a
Windows-font check (Linux only), GeoIP DB presence, and optional-dep
checks. --quick skips the launch test; --json emits machine output.
Python, JS, and .NET, with tests.
One-time, suppressible startup warning when spoofing Windows on a Linux host
with no Windows fonts detected (fc-list probe of the documented base set),
across Python, JS, and .NET. The first-launch banner now re-shows to free
users every 3 days; Pro users still see it once.
The version-check request (get_pro_latest_version) now sends the platform
tag so the server can return a per-OS LATEST pointer, letting us advance
one OS at a time. Mirrored across Python, JS, and .NET clients; older
clients send no header and keep tracking the global LATEST floor.
Pro/Free users can pin a specific Chromium version:
launch(browser_version='148.0.7778.215.2')
CLOAKBROWSER_VERSION=148.0.7778.215.2
- normalize_requested_version() validates version format (4-5 segs, no path traversal)
- Free path: downloads pinned version from public URL
- Pro path: routes pinned version through existing license validation API
- Pinning does NOT overwrite the 'latest' version marker
- JS: browserVersion option, normalizeRequestedVersion(), env support
- .NET: BrowserVersion option, NormalizeRequestedVersion(), env support
The macOS Pro build (darwin arm64 + Intel) is now served alongside Linux and
Windows, so a Pro license downloads the latest binary on macOS like every
other platform.
Reverts the v0.4.2 stopgap that, on macOS only, silently fell back to the free
binary when the Pro download returned 404 (there was no macOS Pro build yet). A
valid license now hard-fails on any Pro download error on every platform — no
silent downgrade — restoring the wrapper's stated invariant. Applied across the
Python, JS, and .NET wrappers; removes the now-unused DownloadHttpError type and
its tests.
README: macOS listed as available for Pro.
Add bin/fetch-widevine.py — a stdlib-only fetcher that pulls the Widevine CDM from Google's component server (arch-aware, sha256-verified, atomic, cached). The Docker entrypoint runs it when CLOAKBROWSER_FETCH_WIDEVINE is set (off by default), exporting CLOAKBROWSER_WIDEVINE_CDM so persistent profiles get a working CDM without a local Chrome to copy from. Fail-soft; skips when a CDM is already set or CLOAKBROWSER_WIDEVINE=0. Bare-metal Linux users can run the script directly. README: document the flag, drop the outdated storage-quota note.
Replace the same-origin checksum with a detached Ed25519 signature
(SHA256SUMS.sig) verified against a pinned public key before extraction,
closing #308: a compromised download mirror can no longer certify a
tampered binary. The signed manifest also binds the release version,
rejecting a forced downgrade to an older signed build.
Verification is mandatory and non-bypassable on the official download path;
custom CLOAKBROWSER_DOWNLOAD_URL mirrors keep the legacy skippable checksum.
Silent auto-update is preserved for everyone because only a constant public
key is pinned, not per-version hashes. Older installed wrappers are
unaffected — the version= line is ignored by their checksum parser.
Python uses cryptography; JS uses node:crypto. Adds tamper, downgrade, and
fail-closed tests in both languages.
Headed launches applied a fixed emulated viewport on top of the real
browser window, yielding outerWidth < innerWidth (an impossible window).
Default headed new_page()/new_context() to no_viewport so the page tracks
the real window; headless keeps a deterministic viewport. Covers Python
launch/launch_context/launch_persistent_context (+async) and the JS
Playwright/Puppeteer wrappers. Explicit viewport still honored.
CloakHQ