human-input-kit 0.2.1__tar.gz

human_input_kit-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and dev deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          playwright install chromium
+
+      - name: Ruff
+        run: ruff check .
+
+      - name: Pytest
+        run: pytest

human_input_kit-0.2.1/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package and dev deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          playwright install chromium
+
+      - name: Ruff
+        run: ruff check .
+
+      - name: Pytest
+        run: pytest
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build
+        run: python -m build
+
+      - name: Twine check
+        run: twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

human_input_kit-0.2.1/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+.env

human_input_kit-0.2.1/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## v0.2.1 — 2026-06-11
+
+### Changed
+
+- PyPI README: SEO subtitle, warmup playbook (cadence vs fingerprint), contextual affiliate note
+- Fixed Install code fence typo in README
+- `pyproject.toml`: search keywords (`human-like-mouse`, `playwright-warmup`, `bot-detection`)
+- `--show-deal`: contextual folder-scale warmup copy with affiliate disclosure
+- FAQ: +4 SEO questions (human scroll, warmup script, N-profile MLX, affiliate opt-in)
+
+## v0.2.0 — 2026-06-11
+
+### Added
+
+- `examples/mlx_warmup_demo.py` — MLX Launcher warmup pseudocode with TODO markers; cdp-connect-kit peer pattern
+- README: MLX single-profile warmup vs production N-profile warmup via automation-farm-runner
+- Optional `[mlx]` extra marker (no added dependencies)
+
+- Deterministic mode: global `--seed 42` on CLI (default 42) for reproducible demos/tests
+- `human_input_kit.sync_` — Playwright **sync** API (`move_mouse_along`, `human_type`, etc.)
+- `human_input_kit.async_` — Playwright **async** API module (re-exports async helpers)
+- Gesture JSON schema validation before `replay` (CLI fails fast with clear errors)
+- `examples/demo_warmup.py` with `--seed`, `--url`, `--headed` CLI args
+- Bezier benchmark test (100 points, loose <50ms CI ceiling; target <10ms)
+- README demo GIF placeholder path `docs/assets/demo.gif`
+- GitHub Actions CI (Python 3.10–3.12)
+
+### Changed
+
+- Top-level `human_input_kit` exports sync Playwright helpers by default
+- `load_recording(..., validate=True)` validates schema before parsing
+
+## v0.1.0 — 2026-06-01
+
+- Initial release: Bezier paths, scroll/typing/idle helpers, record/replay CLI

human_input_kit-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 human-input-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

human_input_kit-0.2.1/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: human-input-kit
+Version: 0.2.1
+Summary: Human-like Playwright mouse, scroll, and typing — Bezier warmup with deterministic seeds. CLI: human-input.
+Project-URL: Homepage, https://github.com/human-input-kit/human-input-kit
+Project-URL: Documentation, https://github.com/human-input-kit/human-input-kit#readme
+Project-URL: Repository, https://github.com/human-input-kit/human-input-kit
+Project-URL: Issues, https://github.com/human-input-kit/human-input-kit/issues
+Author: human-input-kit contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: behavior-replay,bezier-curve,bot-cadence,bot-detection,gesture-recording,human-behavior,human-like-mouse,idle-jitter,interaction-polish,mouse-movement,multilogin-warmup,playwright-input,playwright-scroll,playwright-warmup,scroll-simulation,typing-simulation,warmup-script
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: playwright>=1.40
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: mlx
+Description-Content-Type: text/markdown
+
+# human-input-kit
+
+**Human-like Playwright mouse & scroll** — Bezier paths, typing delays, and warmup recipes with deterministic seeds.
+
+[![PyPI version](https://img.shields.io/pypi/v/human-input-kit.svg)](https://pypi.org/project/human-input-kit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/human-input-kit.svg)](https://pypi.org/project/human-input-kit/)
+[![License: MIT](https://img.shields.io/pypi/l/human-input-kit.svg)](https://pypi.org/project/human-input-kit/)
+
+```bash
+pip install human-input-kit
+human-input --help
+```
+
+CLI: **`human-input`** · Python **3.10+** · optional **`[mlx]`** for Launcher helpers
+
+Human-like **mouse**, **scroll**, and **typing** helpers for Playwright — Bezier paths, variable delays, idle jitter, and gesture record/replay.
+
+## Problem
+
+Raw `page.click()` and `page.keyboard.type()` bursts look mechanical. Warmup workflows need curved mouse paths, uneven scroll cadence, and typing pauses. Teams reinvent these snippets in every scraper.
+
+`human-input-kit` packages the primitives and a small CLI for demo, record, and replay flows.
+
+## Install
+
+```bash
+pip install human-input-kit
+playwright install chromium
+```
+
+Development:
+
+```bash
+pip install human-input-kit[dev]
+```
+
+![Warmup demo](docs/assets/demo.gif)
+
+> Placeholder: add a screen recording at `docs/assets/demo.gif` (not shipped in the wheel).
+
+## Quick start
+
+```bash
+# Reproducible motion (default seed 42)
+human-input --seed 42 demo-scroll --url https://news.ycombinator.com
+human-input record --duration 30 -o gestures.json
+human-input replay gestures.json   # validates gesture JSON schema first
+
+# Runnable warmup example
+python examples/demo_warmup.py --seed 42
+
+# Documented recipes (deterministic with --seed)
+python recipes/scroll_news.py --seed 42
+python recipes/youtube_idle.py --seed 42 --seconds 30 --headed
+```
+
+**Sync Playwright API** (default package exports):
+
+```python
+from human_input_kit import (
+    bezier_mouse_path,
+    human_type,
+    idle_jitter,
+    move_mouse_along,
+    random_scroll,
+    seed_rng,
+)
+
+seed_rng(42)
+path = bezier_mouse_path((100, 100), (500, 300))
+move_mouse_along(page, path)          # sync Page
+random_scroll(page, bursts=4)
+idle_jitter(page)
+human_type(page, "input[name='q']", "playwright warmup")
+```
+
+**Async Playwright API** (`human_input_kit.async_`):
+
+```python
+from human_input_kit import seed_rng
+from human_input_kit import async_ as human_async
+
+seed_rng(42)
+path = human_async.bezier_mouse_path((100, 100), (500, 300))
+await human_async.move_mouse_along(page, path)
+await human_async.random_scroll(page, bursts=4)
+```
+
+See `examples/demo_warmup.py` for a full async script.
+
+### Recipes
+
+Copy-paste scripts in [`recipes/`](recipes/) for common warmup patterns. Each accepts `--seed` so demo motion is reproducible in CI and screen recordings.
+
+| Recipe | Command | Behavior |
+|--------|---------|----------|
+| News scroll | `python recipes/scroll_news.py --seed 42` | Bezier drift → scroll bursts → idle jitter on a news feed |
+| YouTube idle | `python recipes/youtube_idle.py --seed 42 --headed` | Idle micro-moves + rare scroll on `youtube.com` |
+
+Options: `--url`, `--headed` (both); `--bursts` (scroll_news); `--seconds` (youtube_idle).
+
+## MLX warmup (single profile)
+
+`human-input-kit` does **not** bundle MLX or Launcher clients. For one-off MLX profile warmup, follow the **cdp-connect-kit** peer pattern:
+
+```bash
+pip install human-input-kit
+pip install cdp-connect-kit[mlx]   # peer dependency — not required by human-input-kit
+playwright install chromium
+
+export MLX_TOKEN=your_bearer_token
+export MLX_FOLDER_ID=your-folder-uuid
+
+# Pseudocode demo with TODO markers for Launcher start/stop:
+python examples/mlx_warmup_demo.py --profile-id PROFILE_UUID
+
+# Or warmup an already-started profile (CDP_URL from Launcher):
+CDP_URL=http://127.0.0.1:55513 python examples/mlx_warmup_demo.py --profile-id PROFILE_UUID
+```
+
+`examples/mlx_warmup_demo.py` documents: Launcher start → `connect_over_cdp` → Bezier scroll/jitter warmup → Launcher stop. Set `HUMAN_INPUT_KIT_MLX_DEMO=1` after installing `cdp-connect-kit[mlx]` to enable the live Launcher calls.
+
+Optional marker extra (installs nothing): `pip install human-input-kit[mlx]`
+
+## CLI
+
+| Command | Description |
+|---------|-------------|
+| `human-input demo-scroll --url URL` | Scroll + idle jitter demo |
+| `human-input record --duration SEC -o FILE` | Record gestures JSON |
+| `human-input replay FILE` | Replay saved gestures (schema-validated) |
+| `human-input --seed N` | Global RNG seed on all subcommands (default `42`) |
+
+## API
+
+| Module | Use with |
+|--------|----------|
+| `human_input_kit` | Playwright **sync** `Page` |
+| `human_input_kit.async_` | Playwright **async** `Page` |
+| `human_input_kit.bezier` | Path math only (`bezier_mouse_path`) |
+
+| Function | Description |
+|----------|-------------|
+| `bezier_mouse_path(start, end, steps=25)` | Cubic Bezier point list (sync, fast) |
+| `move_mouse_along(page, path)` | Animate mouse along path |
+| `human_type(page, selector, text)` | Variable per-char typing delays |
+| `random_scroll(page, bursts=3)` | Random wheel bursts with pauses |
+| `idle_jitter(page, moves=4)` | Small idle hand movements |
+| `seed_rng(n)` | Deterministic variance for tests/demos |
+| `load_recording(path, validate=True)` | Load gestures JSON with schema check |
+
+### Gesture format
+
+```json
+{
+  "version": 1,
+  "url": "https://news.ycombinator.com",
+  "events": [
+    {"type": "move", "t": 0.0, "x": 120, "y": 80},
+    {"type": "scroll", "t": 1.2, "dy": 320}
+  ]
+}
+```
+
+## Behavioral mimicry vs profile isolation
+
+Human-like mouse paths and scroll timing can reduce **obvious automation cadence**, but behavioral mimicry alone is **necessary and insufficient** for production multi-account workflows.
+
+Detection stacks also correlate:
+
+- Browser fingerprint consistency (UA, WebGL, Client Hints)
+- IP / proxy reputation
+- Cookie and storage isolation
+- TLS and network signals
+
+Use `human-input-kit` for **warmup and interaction polish** inside an already-isolated profile (dedicated browser profile, proxy, and storage boundary). Pair with [fingerprint-coherence](https://pypi.org/project/fingerprint-coherence/) and [playwright-cdp-probe](https://pypi.org/project/playwright-cdp-probe/) for profile-level QA.
+
+## When mechanical clicks still get flagged (playbook)
+
+Behavior polish helps **cadence** — not fingerprint or IP. Typical order of operations:
+
+| Signal still failing | Tool | Action |
+|----------------------|------|--------|
+| Teleport mouse / constant intervals | `human-input-kit` | Bezier paths, `--seed` for reproducible demos |
+| UA / screen / timezone mismatch | [fingerprint-coherence](https://pypi.org/project/fingerprint-coherence/) | Audit profile before warmup |
+| `navigator.webdriver` / headless leaks | [playwright-cdp-probe](https://pypi.org/project/playwright-cdp-probe/) | Compare vanilla vs Launcher CDP |
+| One profile ok, N profiles not | `automation-farm-runner` | `farm-runner mlx-pool` + warmup script reading `CDP_URL` |
+
+**Warmup pipeline (single profile):**
+
+```bash
+export MLX_TOKEN=... MLX_FOLDER_ID=...
+# cdp-connect-kit starts profile → CDP_URL
+CDP_URL=http://127.0.0.1:PORT python examples/mlx_warmup_demo.py --profile-id UUID
+human-input --seed 42 demo-scroll --url https://news.ycombinator.com
+cdp-probe mlx --profile-id UUID --url https://example.com
+```
+
+**Warmup at scale:** farm job imports `human_input_kit`, reads `CDP_URL` / `PROFILE_ID` from env — gestures stay in this package; queueing stays in `farm-runner`.
+
+## Limitations
+
+- **Playwright only** — APIs expect a Playwright `Page`.
+- **Record mode** captures DOM events + scripted warmup; not a full OS-level input recorder.
+- **Not undetectable** — reduces mechanical patterns; does not spoof fingerprints or network identity.
+- **Headless motion** — some sites behave differently in headless Chromium.
+
+## Production
+
+For **many profiles** (folder pool, cron, concurrency), use **`farm-runner`** (`automation-farm-runner`) with a warmup script that imports `human_input_kit` and reads `CDP_URL` / `PROFILE_ID`. This package is the gesture library; the farm runner owns MLX pool lifecycle.
+
+**Partner note (affiliate):** Human-like input pays off **inside** isolated Multilogin X profiles (proxy + fingerprint already matched) — not on leaky vanilla Chromium. If folder-scale warmup is your bottleneck, eligible new browser purchases may accept code **`SAAS50`** at [multilogin.com](https://multilogin.com/?ref=SAAS50) — verify terms before checkout. Demos and recipes work without MLX. Full disclosure: [docs/AFFILIATE.md](docs/AFFILIATE.md). Coupon details only via `human-input --show-deal` (never printed by default).
+
+**FAQ:** [docs/FAQ.md](docs/FAQ.md) — human-like mouse movement, Playwright scroll warmup, bot detection cadence.
+
+
+
+
+
+## Related tools (on PyPI)
+
+| Package | CLI | Role |
+|---------|-----|------|
+| [playwright-cdp-probe](https://pypi.org/project/playwright-cdp-probe/) | `cdp-probe` | CDP / WebDriver exposure score |
+| [cookie-jar-bridge](https://pypi.org/project/cookie-jar-bridge/) | `cookie-bridge` | Netscape ↔ Playwright cookies |
+| [proxy-lane-checker](https://pypi.org/project/proxy-lane-checker/) | `proxy-lane` | Proxy TCP / HTTP / geo / DNSBL |
+| [fingerprint-coherence](https://pypi.org/project/fingerprint-coherence/) | `fp-coherence` | UA / screen / timezone lint |
+
+**Toolkit pipeline:** `proxy-lane check` → `fp-coherence audit` → automate → `cdp-probe run` → `cookie-bridge validate`
+
+## License
+
+MIT
+
+---
+
+**Production antidetect:** [Multilogin X](https://multilogin.com/?ref=SAAS50) · Code `SAAS50` (-50% browser) · `MIN50` (-50% cloud phone)  
+More scripts: [@Multilogin_Scripts_Bot](https://t.me/Multilogin_Scripts_Bot) · [Coupons](https://anti-detect.github.io/)

human_input_kit-0.2.1/README.md

@@ -0,0 +1,238 @@
+# human-input-kit
+
+**Human-like Playwright mouse & scroll** — Bezier paths, typing delays, and warmup recipes with deterministic seeds.
+
+[![PyPI version](https://img.shields.io/pypi/v/human-input-kit.svg)](https://pypi.org/project/human-input-kit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/human-input-kit.svg)](https://pypi.org/project/human-input-kit/)
+[![License: MIT](https://img.shields.io/pypi/l/human-input-kit.svg)](https://pypi.org/project/human-input-kit/)
+
+```bash
+pip install human-input-kit
+human-input --help
+```
+
+CLI: **`human-input`** · Python **3.10+** · optional **`[mlx]`** for Launcher helpers
+
+Human-like **mouse**, **scroll**, and **typing** helpers for Playwright — Bezier paths, variable delays, idle jitter, and gesture record/replay.
+
+## Problem
+
+Raw `page.click()` and `page.keyboard.type()` bursts look mechanical. Warmup workflows need curved mouse paths, uneven scroll cadence, and typing pauses. Teams reinvent these snippets in every scraper.
+
+`human-input-kit` packages the primitives and a small CLI for demo, record, and replay flows.
+
+## Install
+
+```bash
+pip install human-input-kit
+playwright install chromium
+```
+
+Development:
+
+```bash
+pip install human-input-kit[dev]
+```
+
+![Warmup demo](docs/assets/demo.gif)
+
+> Placeholder: add a screen recording at `docs/assets/demo.gif` (not shipped in the wheel).
+
+## Quick start
+
+```bash
+# Reproducible motion (default seed 42)
+human-input --seed 42 demo-scroll --url https://news.ycombinator.com
+human-input record --duration 30 -o gestures.json
+human-input replay gestures.json   # validates gesture JSON schema first
+
+# Runnable warmup example
+python examples/demo_warmup.py --seed 42
+
+# Documented recipes (deterministic with --seed)
+python recipes/scroll_news.py --seed 42
+python recipes/youtube_idle.py --seed 42 --seconds 30 --headed
+```
+
+**Sync Playwright API** (default package exports):
+
+```python
+from human_input_kit import (
+    bezier_mouse_path,
+    human_type,
+    idle_jitter,
+    move_mouse_along,
+    random_scroll,
+    seed_rng,
+)
+
+seed_rng(42)
+path = bezier_mouse_path((100, 100), (500, 300))
+move_mouse_along(page, path)          # sync Page
+random_scroll(page, bursts=4)
+idle_jitter(page)
+human_type(page, "input[name='q']", "playwright warmup")
+```
+
+**Async Playwright API** (`human_input_kit.async_`):
+
+```python
+from human_input_kit import seed_rng
+from human_input_kit import async_ as human_async
+
+seed_rng(42)
+path = human_async.bezier_mouse_path((100, 100), (500, 300))
+await human_async.move_mouse_along(page, path)
+await human_async.random_scroll(page, bursts=4)
+```
+
+See `examples/demo_warmup.py` for a full async script.
+
+### Recipes
+
+Copy-paste scripts in [`recipes/`](recipes/) for common warmup patterns. Each accepts `--seed` so demo motion is reproducible in CI and screen recordings.
+
+| Recipe | Command | Behavior |
+|--------|---------|----------|
+| News scroll | `python recipes/scroll_news.py --seed 42` | Bezier drift → scroll bursts → idle jitter on a news feed |
+| YouTube idle | `python recipes/youtube_idle.py --seed 42 --headed` | Idle micro-moves + rare scroll on `youtube.com` |
+
+Options: `--url`, `--headed` (both); `--bursts` (scroll_news); `--seconds` (youtube_idle).
+
+## MLX warmup (single profile)
+
+`human-input-kit` does **not** bundle MLX or Launcher clients. For one-off MLX profile warmup, follow the **cdp-connect-kit** peer pattern:
+
+```bash
+pip install human-input-kit
+pip install cdp-connect-kit[mlx]   # peer dependency — not required by human-input-kit
+playwright install chromium
+
+export MLX_TOKEN=your_bearer_token
+export MLX_FOLDER_ID=your-folder-uuid
+
+# Pseudocode demo with TODO markers for Launcher start/stop:
+python examples/mlx_warmup_demo.py --profile-id PROFILE_UUID
+
+# Or warmup an already-started profile (CDP_URL from Launcher):
+CDP_URL=http://127.0.0.1:55513 python examples/mlx_warmup_demo.py --profile-id PROFILE_UUID
+```
+
+`examples/mlx_warmup_demo.py` documents: Launcher start → `connect_over_cdp` → Bezier scroll/jitter warmup → Launcher stop. Set `HUMAN_INPUT_KIT_MLX_DEMO=1` after installing `cdp-connect-kit[mlx]` to enable the live Launcher calls.
+
+Optional marker extra (installs nothing): `pip install human-input-kit[mlx]`
+
+## CLI
+
+| Command | Description |
+|---------|-------------|
+| `human-input demo-scroll --url URL` | Scroll + idle jitter demo |
+| `human-input record --duration SEC -o FILE` | Record gestures JSON |
+| `human-input replay FILE` | Replay saved gestures (schema-validated) |
+| `human-input --seed N` | Global RNG seed on all subcommands (default `42`) |
+
+## API
+
+| Module | Use with |
+|--------|----------|
+| `human_input_kit` | Playwright **sync** `Page` |
+| `human_input_kit.async_` | Playwright **async** `Page` |
+| `human_input_kit.bezier` | Path math only (`bezier_mouse_path`) |
+
+| Function | Description |
+|----------|-------------|
+| `bezier_mouse_path(start, end, steps=25)` | Cubic Bezier point list (sync, fast) |
+| `move_mouse_along(page, path)` | Animate mouse along path |
+| `human_type(page, selector, text)` | Variable per-char typing delays |
+| `random_scroll(page, bursts=3)` | Random wheel bursts with pauses |
+| `idle_jitter(page, moves=4)` | Small idle hand movements |
+| `seed_rng(n)` | Deterministic variance for tests/demos |
+| `load_recording(path, validate=True)` | Load gestures JSON with schema check |
+
+### Gesture format
+
+```json
+{
+  "version": 1,
+  "url": "https://news.ycombinator.com",
+  "events": [
+    {"type": "move", "t": 0.0, "x": 120, "y": 80},
+    {"type": "scroll", "t": 1.2, "dy": 320}
+  ]
+}
+```
+
+## Behavioral mimicry vs profile isolation
+
+Human-like mouse paths and scroll timing can reduce **obvious automation cadence**, but behavioral mimicry alone is **necessary and insufficient** for production multi-account workflows.
+
+Detection stacks also correlate:
+
+- Browser fingerprint consistency (UA, WebGL, Client Hints)
+- IP / proxy reputation
+- Cookie and storage isolation
+- TLS and network signals
+
+Use `human-input-kit` for **warmup and interaction polish** inside an already-isolated profile (dedicated browser profile, proxy, and storage boundary). Pair with [fingerprint-coherence](https://pypi.org/project/fingerprint-coherence/) and [playwright-cdp-probe](https://pypi.org/project/playwright-cdp-probe/) for profile-level QA.
+
+## When mechanical clicks still get flagged (playbook)
+
+Behavior polish helps **cadence** — not fingerprint or IP. Typical order of operations:
+
+| Signal still failing | Tool | Action |
+|----------------------|------|--------|
+| Teleport mouse / constant intervals | `human-input-kit` | Bezier paths, `--seed` for reproducible demos |
+| UA / screen / timezone mismatch | [fingerprint-coherence](https://pypi.org/project/fingerprint-coherence/) | Audit profile before warmup |
+| `navigator.webdriver` / headless leaks | [playwright-cdp-probe](https://pypi.org/project/playwright-cdp-probe/) | Compare vanilla vs Launcher CDP |
+| One profile ok, N profiles not | `automation-farm-runner` | `farm-runner mlx-pool` + warmup script reading `CDP_URL` |
+
+**Warmup pipeline (single profile):**
+
+```bash
+export MLX_TOKEN=... MLX_FOLDER_ID=...
+# cdp-connect-kit starts profile → CDP_URL
+CDP_URL=http://127.0.0.1:PORT python examples/mlx_warmup_demo.py --profile-id UUID
+human-input --seed 42 demo-scroll --url https://news.ycombinator.com
+cdp-probe mlx --profile-id UUID --url https://example.com
+```
+
+**Warmup at scale:** farm job imports `human_input_kit`, reads `CDP_URL` / `PROFILE_ID` from env — gestures stay in this package; queueing stays in `farm-runner`.
+
+## Limitations
+
+- **Playwright only** — APIs expect a Playwright `Page`.
+- **Record mode** captures DOM events + scripted warmup; not a full OS-level input recorder.
+- **Not undetectable** — reduces mechanical patterns; does not spoof fingerprints or network identity.
+- **Headless motion** — some sites behave differently in headless Chromium.
+
+## Production
+
+For **many profiles** (folder pool, cron, concurrency), use **`farm-runner`** (`automation-farm-runner`) with a warmup script that imports `human_input_kit` and reads `CDP_URL` / `PROFILE_ID`. This package is the gesture library; the farm runner owns MLX pool lifecycle.
+
+**Partner note (affiliate):** Human-like input pays off **inside** isolated Multilogin X profiles (proxy + fingerprint already matched) — not on leaky vanilla Chromium. If folder-scale warmup is your bottleneck, eligible new browser purchases may accept code **`SAAS50`** at [multilogin.com](https://multilogin.com/?ref=SAAS50) — verify terms before checkout. Demos and recipes work without MLX. Full disclosure: [docs/AFFILIATE.md](docs/AFFILIATE.md). Coupon details only via `human-input --show-deal` (never printed by default).
+
+**FAQ:** [docs/FAQ.md](docs/FAQ.md) — human-like mouse movement, Playwright scroll warmup, bot detection cadence.
+
+
+
+
+
+## Related tools (on PyPI)
+
+| Package | CLI | Role |
+|---------|-----|------|
+| [playwright-cdp-probe](https://pypi.org/project/playwright-cdp-probe/) | `cdp-probe` | CDP / WebDriver exposure score |
+| [cookie-jar-bridge](https://pypi.org/project/cookie-jar-bridge/) | `cookie-bridge` | Netscape ↔ Playwright cookies |
+| [proxy-lane-checker](https://pypi.org/project/proxy-lane-checker/) | `proxy-lane` | Proxy TCP / HTTP / geo / DNSBL |
+| [fingerprint-coherence](https://pypi.org/project/fingerprint-coherence/) | `fp-coherence` | UA / screen / timezone lint |
+
+**Toolkit pipeline:** `proxy-lane check` → `fp-coherence audit` → automate → `cdp-probe run` → `cookie-bridge validate`
+
+## License
+
+MIT
+
+---
+
+**Production antidetect:** [Multilogin X](https://multilogin.com/?ref=SAAS50) · Code `SAAS50` (-50% browser) · `MIN50` (-50% cloud phone)  
+More scripts: [@Multilogin_Scripts_Bot](https://t.me/Multilogin_Scripts_Bot) · [Coupons](https://anti-detect.github.io/)