human-movement-bench 0.1.2__tar.gz

human_movement_bench-0.1.2/CITATION.cff

@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+message: "If you use Human Movement, please cite this software."
+type: software
+title: Human Movement Benchmark
+version: 0.1.2
+date-released: 2026-11-06
+authors:
+  - family-names: Galal
+    given-names: Karim
+license: MIT
+abstract: "Windows-first personalized cursor trajectories and input timing for computer-use applications."

human_movement_bench-0.1.2/CONTRIBUTORS.md

@@ -0,0 +1,5 @@
+# Contributor
+
+Karim Galal is the sole contributor and maintainer of Human Movement.
+
+External libraries, datasets, research papers and engineering baselines retain their original ownership and attribution. They are references or dependencies, rather than contributors to this package.

human_movement_bench-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karim Galal
+
+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_movement_bench-0.1.2/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: human-movement-bench
+Version: 0.1.2
+Summary: Independent reproducible evaluation of timed human input traces
+Author: Karim Galal
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Dist: numpy>=2.1
+Requires-Dist: scipy>=1.14
+Requires-Dist: scikit-learn>=1.5
+Requires-Dist: joblib>=1.4
+Requires-Dist: pytweening==1.2.0 ; extra == 'baselines'
+Requires-Dist: selenium>=4.25 ; extra == 'baselines'
+Requires-Dist: pillow>=11 ; extra == 'datasets'
+Requires-Dist: pyarrow>=19 ; extra == 'datasets'
+Requires-Dist: torch>=2.6 ; extra == 'detectors'
+Maintainer: Karim Galal
+Requires-Python: >=3.12
+Provides-Extra: baselines
+Provides-Extra: datasets
+Provides-Extra: detectors
+Description-Content-Type: text/markdown
+
+# Human Movement Benchmark
+
+Independent evaluation of timed mouse, click, keyboard and scroll traces. Developed and maintained solely by Karim Galal.
+
+```sh
+pip install human-movement-bench
+human-movement-bench --help
+```
+
+Install `human-movement-bench[detectors]` to use the optional PyTorch detector. This evaluator does not import the movement generator. Headline scores require matched independent data, detector controls and successful functional checks; synthetic fixtures only validate the implementation.
+
+Licensed under MIT. See the included LICENSE file.

human_movement_bench-0.1.2/README.md

@@ -0,0 +1,12 @@
+# Human Movement Benchmark
+
+Independent evaluation of timed mouse, click, keyboard and scroll traces. Developed and maintained solely by Karim Galal.
+
+```sh
+pip install human-movement-bench
+human-movement-bench --help
+```
+
+Install `human-movement-bench[detectors]` to use the optional PyTorch detector. This evaluator does not import the movement generator. Headline scores require matched independent data, detector controls and successful functional checks; synthetic fixtures only validate the implementation.
+
+Licensed under MIT. See the included LICENSE file.

human_movement_bench-0.1.2/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "human-movement-bench"
+version = "0.1.2"
+readme = "README.md"
+description = "Independent reproducible evaluation of timed human input traces"
+requires-python = ">=3.12"
+dependencies = [
+    "numpy>=2.1",
+    "scipy>=1.14",
+    "scikit-learn>=1.5",
+    "joblib>=1.4",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "Karim Galal"
+
+[[project.maintainers]]
+name = "Karim Galal"
+
+[project.scripts]
+human-movement-bench = "human_movement_bench.cli:main"
+
+[project.optional-dependencies]
+detectors = ["torch>=2.6"]
+datasets = [
+    "pillow>=11",
+    "pyarrow>=19",
+]
+baselines = [
+    "pytweening==1.2.0",
+    "selenium>=4.25",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+source-include = [
+    "CITATION.cff",
+    "CONTRIBUTORS.md",
+]

human_movement_bench-0.1.2/pyproject.toml.orig

@@ -0,0 +1,32 @@
+[project]
+name = "human-movement-bench"
+version = "0.1.2"
+readme = "README.md"
+description = "Independent reproducible evaluation of timed human input traces"
+requires-python = ">=3.12"
+dependencies = ["numpy>=2.1", "scipy>=1.14", "scikit-learn>=1.5", "joblib>=1.4"]
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Karim Galal"}]
+maintainers = [{name = "Karim Galal"}]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+
+[project.scripts]
+human-movement-bench = "human_movement_bench.cli:main"
+
+[project.optional-dependencies]
+detectors = ["torch>=2.6"]
+datasets = ["pillow>=11", "pyarrow>=19"]
+baselines = ["pytweening==1.2.0", "selenium>=4.25"]
+
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+source-include = ["CITATION.cff", "CONTRIBUTORS.md"]

human_movement_bench-0.1.2/src/human_movement_bench/__init__.py

@@ -0,0 +1,4 @@
+"""Independent evaluator. Does not import human_movement internals."""
+
+__version__ = "0.1.2"
+BENCHMARK_VERSION = "hmbench-1"

human_movement_bench-0.1.2/src/human_movement_bench/assets/fixture.html

@@ -0,0 +1,27 @@
+<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Human Movement · Independent fixture</title>
+<style>body{font:16px/1.5 system-ui;background:#f4f3ed;color:#183b2b;max-width:1000px;margin:30px auto;padding:20px}h1{font-size:36px;font-weight:550}button{font:inherit;border:0;background:#285740;color:white;padding:12px 20px;border-radius:8px;cursor:pointer}header{display:flex;justify-content:space-between;align-items:center}#arena{height:420px;background:white;border:1px solid #d6dfd3;border-radius:12px;position:relative;overflow:hidden;margin:24px 0}.target{position:absolute;padding:0;border-radius:50%}.drop{position:absolute;right:50px;top:180px;width:120px;height:100px;border:2px dashed #285740;display:grid;place-items:center}.drag{position:absolute;left:50px;top:180px;width:50px;height:50px;background:#285740;border-radius:8px;touch-action:none}.corridor{position:absolute;left:50px;right:50px;top:165px;height:130px;background:#edf3e9}.pane{overflow:auto;height:100%;padding:20px}.card{height:150px;background:#f1f4ec;margin:12px;padding:20px}.goal{border:2px solid #285740}textarea{font:20px system-ui;width:90%;height:160px;padding:15px;margin:10px}#status{color:#60766a}#error{color:#a33}small{letter-spacing:1px}nav{display:flex;gap:12px;flex-wrap:wrap}.summary{padding:25px}#finish{background:#e1e7db;color:#183b2b}</style>
+<header><small>HMBENCH-1 · LOCAL FIXTURE</small><span id="label"></span></header><h1>Measure what actually arrives.</h1><p id="instructions">Capture pointing, clicks, a corridor drag, scrolling, and a known typing sample. These events belong to a separate benchmark session.</p>
+<nav><button id="start">Start session</button><button id="next" disabled>Next task</button><button id="finish" disabled>Finish & save</button></nav><section id="arena"><div class="summary"><h2>Ready when you are.</h2><p>Use identical display settings for every method. Browser and injection diagnostics are reported separately from behavioral similarity.</p></div></section><p id="status">Nothing is recording.</p><p id="error" role="alert"></p>
+<script>
+const config=__CONFIG__,arena=document.querySelector('#arena'),status=document.querySelector('#status');document.querySelector('#label').textContent=config.label+' · '+config.version;
+let active=false,mode=0,trial=0,events=[],start=0,chain=Promise.resolve(),presses=new Map(),id=0,untrusted=0,dragging=false,corridor=true;
+const names=['mouse','click','mouse','scroll','keyboard'],tasks=['pointing','click_hold','corridor_drag','scroll_card','fixed_text'];
+const prompt='Hello world — café, 中文, 🙂';
+function post(url,body){return fetch(url,{method:'POST',headers:{'Content-Type':'application/json','X-HM-Token':config.token},body:JSON.stringify(body)}).then(async r=>{let d=await r.json();if(!r.ok)throw Error(d.error);return d})}
+function emit(kind,extra={},event){if(!active)return;if(event&&!event.isTrusted)untrusted++;events.push({kind,t:(performance.now()-start)/1000,...extra})}
+function env(){return {platform:navigator.platform,dpr:devicePixelRatio,width:innerWidth,height:innerHeight,screenWidth:screen.width,screenHeight:screen.height}}
+function save(functional={}){if(!events.length)return;const payload={events,task_id:tasks[mode],modality:names[mode],functional,environment:env(),diagnostics:{webdriver:navigator.webdriver,untrusted_events:untrusted,userAgent:navigator.userAgent}};events=[];start=performance.now();untrusted=0;chain=chain.then(()=>post('/trace',payload)).then(r=>{status.textContent=r.saved+' traces saved locally.'}).catch(e=>document.querySelector('#error').textContent=e.message)}
+function layout(){const out={task:tasks[mode],prompt,viewport:env(),screenX,screenY};for(const name of ['.target','.drag','.drop','textarea','.goal']){const e=arena.querySelector(name);if(e){const r=e.getBoundingClientRect();out[name]={x:r.x,y:r.y,width:r.width,height:r.height}}}post('/layout',out).catch(()=>{})}
+function target(){const widths=[24,48,80],locations=[[.2,.3],[.8,.7],[.4,.7],[.75,.2]];const size=widths[trial%3],loc=locations[trial%4];arena.innerHTML='<button class="target" aria-label="Benchmark target">+</button>';const b=arena.firstChild;b.style.cssText=`width:${size}px;height:${size}px;left:${loc[0]*(arena.clientWidth-size)}px;top:${loc[1]*(arena.clientHeight-size)}px`;b.onclick=()=>{save(mode===0?{target_hit:true}:{});trial++;target()};layout()}
+function stage(){events=[];start=performance.now();trial=0;presses.clear();document.querySelector('#instructions').textContent=['Click varied targets several times, then choose Next task.','Click the target repeatedly at your normal pace.','Drag the green block through the pale corridor into the outlined box.','Scroll down to the outlined card and click it.','Type the displayed sample exactly, then click Finish & save.'][mode];if(mode<2)target();else if(mode===2){arena.innerHTML='<div class="corridor"></div><div class="drop">Release here</div><div class="drag" role="button" aria-label="Drag block"></div>';const d=arena.querySelector('.drag');corridor=true;d.onpointerdown=e=>{dragging=true;d.setPointerCapture(e.pointerId)};d.onpointermove=e=>{if(!dragging)return;const r=arena.getBoundingClientRect();const y=e.clientY-r.y;corridor&&=y>=165&&y<=295;d.style.left=(e.clientX-r.x-25)+'px';d.style.top=(y-25)+'px'};d.onpointerup=e=>{dragging=false;const r=arena.querySelector('.drop').getBoundingClientRect();save({drag_success:corridor&&e.clientX>=r.left&&e.clientX<r.right&&e.clientY>=r.top&&e.clientY<r.bottom});stage()};layout()}else if(mode===3){arena.innerHTML='<div class="pane"></div>';for(let i=0;i<12;i++){const c=document.createElement('div');c.className='card'+(i===7?' goal':'');c.textContent=i===7?'Click this card':'Card '+i;arena.firstChild.append(c);if(i===7)c.onclick=()=>{save({});stage()}}layout()}else{arena.innerHTML='<div class="summary"><p id="prompt"></p><textarea aria-label="Type the sample" spellcheck="false"></textarea></div>';arena.querySelector('#prompt').textContent=prompt;arena.querySelector('textarea').focus();layout()}}
+document.querySelector('#start').onclick=()=>{active=true;document.querySelector('#start').disabled=true;document.querySelector('#next').disabled=false;document.querySelector('#finish').disabled=false;status.textContent='Recording browser-delivered input.';stage()};
+document.querySelector('#next').onclick=()=>{if(mode===4){save({exact_text:arena.querySelector('textarea').value===prompt})}else events=[];mode=(mode+1)%5;stage()};
+document.querySelector('#finish').onclick=async()=>{save(mode===4?{exact_text:arena.querySelector('textarea').value===prompt}:{});active=false;await chain;document.querySelector('#next').disabled=true;document.querySelector('#finish').disabled=true;arena.innerHTML='<div class="summary"><h2>Session saved.</h2><p>The evaluator will check data sufficiency, independent controls, and task correctness before showing a score.</p></div>'};
+arena.addEventListener('pointermove',e=>emit('move',{x:e.clientX,y:e.clientY},e),true);
+for(const [name,kind] of [['pointerdown','button_down'],['pointerup','button_up']])arena.addEventListener(name,e=>emit(kind,{x:e.clientX,y:e.clientY,button:['left','middle','right'][e.button]||'other'},e),true);
+arena.addEventListener('wheel',e=>emit('scroll',{dx:e.deltaX,dy:e.deltaY},e),{capture:true,passive:true});
+arena.addEventListener('keydown',e=>{if(!presses.has(e.code))presses.set(e.code,++id);emit('key_down',{press_id:presses.get(e.code),repeat:e.repeat},e)},true);
+arena.addEventListener('keyup',e=>{emit('key_up',{press_id:presses.get(e.code)||0},e);presses.delete(e.code)},true);
+arena.addEventListener('pointerup',e=>{if(active&&mode===0&&e.button===0&&!e.target.closest('.target')){save({target_hit:false});trial++;target()}});window.addEventListener('resize',layout);
+</script></html>
+

human_movement_bench-0.1.2/src/human_movement_bench/baselines.py

@@ -0,0 +1,48 @@
+"""Frozen engineering controls; no SDK internal implementation is imported."""
+
+from __future__ import annotations
+
+import math
+import random
+
+BASELINE_VERSION = "engineering-1"
+EXTERNAL_REVISIONS = {
+    "humancursor": "39d33f387b953950ffc1035183c9609f7f87c2c8",
+    "human_mouse": "c5cb6db923d4ff2a410abb466691a9659d924f9a",
+}
+
+
+def trajectory(
+    method: str,
+    start: tuple,
+    goal: tuple,
+    *,
+    duration: float = 0.6,
+    seed: int = 17842,
+    samples: int = 75,
+) -> list[dict]:
+    if method not in {"linear", "bezier", "minimum_jerk"}:
+        raise ValueError("Choose a frozen built-in baseline")
+    if samples < 2 or not math.isfinite(duration) or duration <= 0:
+        raise ValueError("Positive duration and at least two samples required")
+    rng = random.Random(seed)
+    dx, dy = goal[0] - start[0], goal[1] - start[1]
+    bend = rng.uniform(-0.15, 0.15)
+    c1 = (start[0] + dx / 3 - dy * bend, start[1] + dy / 3 + dx * bend)
+    c2 = (start[0] + dx * 2 / 3 - dy * bend, start[1] + dy * 2 / 3 + dx * bend)
+    output = []
+    for i in range(samples):
+        s = i / (samples - 1)
+        u = 10 * s**3 - 15 * s**4 + 6 * s**5 if method == "minimum_jerk" else s
+        if method == "bezier":
+            x, y = [
+                (1 - u) ** 3 * start[j]
+                + 3 * (1 - u) ** 2 * u * c1[j]
+                + 3 * (1 - u) * u * u * c2[j]
+                + u**3 * goal[j]
+                for j in (0, 1)
+            ]
+        else:
+            x, y = start[0] + dx * u, start[1] + dy * u
+        output.append({"kind": "move", "t": duration * s, "x": x, "y": y})
+    return output

human_movement_bench-0.1.2/src/human_movement_bench/cli.py

@@ -0,0 +1,178 @@
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from .traces import assert_disjoint, digest, make_manifest, read_jsonl, write_jsonl
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="human-movement-bench")
+    sub = parser.add_subparsers(dest="command", required=True)
+    for name in ("validate", "split", "fit", "evaluate"):
+        p = sub.add_parser(name)
+        p.add_argument("input", type=Path)
+        p.add_argument("--personal", action="store_true")
+        if name in {"split", "fit", "evaluate"}:
+            p.add_argument("--output", type=Path, required=True)
+        if name == "evaluate":
+            p.add_argument("--detectors", type=Path, required=True)
+            p.add_argument("--candidate-version", required=True)
+            p.add_argument("--profile-hash", default="none")
+            p.add_argument("--model-hash", default="none")
+    serve = sub.add_parser("serve")
+    serve.add_argument("--output", type=Path, required=True)
+    serve.add_argument("--participant", required=True)
+    serve.add_argument("--session")
+    serve.add_argument(
+        "--label", choices=("human", "candidate", "control", "human_control"), default="human"
+    )
+    serve.add_argument("--split", default="final_test")
+    serve.add_argument("--candidate-version", default="manual")
+    serve.add_argument("--no-browser", action="store_true")
+    report = sub.add_parser("report")
+    report.add_argument("reports", nargs="+", type=Path)
+    report.add_argument("--output", required=True, type=Path)
+    delivery = sub.add_parser("delivery")
+    delivery.add_argument("input", type=Path)
+    delivery.add_argument("--output", type=Path, required=True)
+    baseline = sub.add_parser("baseline")
+    baseline.add_argument(
+        "method", choices=("linear", "bezier", "minimum_jerk", "humancursor", "human_mouse")
+    )
+    baseline.add_argument("--start", type=float, nargs=2, default=(100, 100))
+    baseline.add_argument("--goal", type=float, nargs=2, default=(900, 500))
+    baseline.add_argument("--duration", type=float, default=0.6)
+    baseline.add_argument("--checkout", type=Path)
+    baseline.add_argument("--seed", type=int, default=17842)
+    baseline.add_argument("--output", type=Path, required=True)
+    imp = sub.add_parser("import")
+    imp.add_argument("dataset", choices=("cmu", "sapimouse", "balabit"))
+    imp.add_argument("input", type=Path)
+    imp.add_argument("--output", type=Path, required=True)
+    imp.add_argument("--split", required=True)
+    imp.add_argument("--terms-note", required=True)
+    imp.add_argument("--participant")
+    imp.add_argument("--session")
+    imp.add_argument("--timestamp-scale", type=float)
+    imp.add_argument("--timestamp-column")
+    args = parser.parse_args(argv)
+    try:
+        if args.command in {"validate", "split", "fit", "evaluate"}:
+            traces = read_jsonl(args.input)
+            assert_disjoint(traces, personal=args.personal)
+            if args.command == "validate":
+                print(
+                    json.dumps(
+                        {
+                            "traces": len(traces),
+                            "sha256": digest(args.input),
+                            "leakage_check": "passed",
+                        }
+                    )
+                )
+            elif args.command == "split":
+                print(json.dumps(make_manifest(traces, args.output), indent=2))
+            elif args.command == "fit":
+                from .detectors import fit
+
+                print(json.dumps(fit(traces, args.output, personal=args.personal), indent=2))
+            else:
+                from .evaluation import evaluate
+
+                result = evaluate(
+                    traces,
+                    args.detectors,
+                    personal=args.personal,
+                    metadata={
+                        "dataset_sha256": digest(args.input),
+                        "candidate_version": args.candidate_version,
+                        "profile_sha256": args.profile_hash,
+                        "model_sha256": args.model_hash,
+                    },
+                )
+                args.output.write_text(json.dumps(result, indent=2), encoding="utf-8")
+                print(
+                    json.dumps(
+                        {"status": result["status"], "overall_score": result["overall_score"]}
+                    )
+                )
+        elif args.command == "serve":
+            from .website import Fixture
+
+            Fixture(
+                args.output,
+                participant=args.participant,
+                session=args.session,
+                label=args.label,
+                split=args.split,
+                candidate_version=args.candidate_version,
+            ).serve(open_browser=not args.no_browser)
+        elif args.command == "report":
+            from .report import render
+
+            render([json.loads(p.read_text()) for p in args.reports], args.output)
+        elif args.command == "delivery":
+            from .delivery import analyze_delivery
+
+            args.output.write_text(
+                json.dumps(analyze_delivery(json.loads(args.input.read_text())), indent=2),
+                encoding="utf-8",
+            )
+        elif args.command == "baseline":
+            from .baselines import BASELINE_VERSION, trajectory
+
+            if args.method in {"humancursor", "human_mouse"}:
+                if not args.checkout:
+                    parser.error("External baseline requires --checkout at its frozen revision")
+                request = {
+                    "method": args.method,
+                    "checkout": str(args.checkout),
+                    "start": args.start,
+                    "goal": args.goal,
+                    "seed": args.seed,
+                }
+                captured = subprocess.run(
+                    [sys.executable, "-m", "human_movement_bench.external"],
+                    input=json.dumps(request),
+                    text=True,
+                    capture_output=True,
+                    check=True,
+                    timeout=60,
+                )
+                result = json.loads(captured.stdout)
+            else:
+                result = {
+                    "method": args.method,
+                    "version": BASELINE_VERSION,
+                    "events": trajectory(
+                        args.method, args.start, args.goal, duration=args.duration, seed=args.seed
+                    ),
+                }
+            args.output.parent.mkdir(parents=True, exist_ok=True)
+            args.output.write_text(json.dumps(result, indent=2), encoding="utf-8")
+        elif args.command == "import":
+            from .datasets import cmu_csv, mouse_csv
+
+            if args.dataset == "cmu":
+                result = cmu_csv(args.input, split=args.split, terms_note=args.terms_note)
+            else:
+                if not args.participant or not args.session or not args.timestamp_scale:
+                    parser.error(
+                        "Mouse import requires participant, session, and explicit timestamp-scale"
+                    )
+                result = mouse_csv(
+                    args.input,
+                    dataset=args.dataset,
+                    participant=args.participant,
+                    session=args.session,
+                    split=args.split,
+                    timestamp_scale=args.timestamp_scale,
+                    timestamp_column=args.timestamp_column,
+                    terms_note=args.terms_note,
+                )
+            write_jsonl(args.output, result)
+            print(f"Imported {len(result)} traces")
+    except (ValueError, OSError) as exc:
+        parser.exit(1, f"{exc}\n")

human_movement_bench-0.1.2/src/human_movement_bench/datasets.py

@@ -0,0 +1,209 @@
+"""Local, explicit dataset adapters. Downloads and terms acceptance are not implicit."""
+
+from __future__ import annotations
+
+import csv
+import hashlib
+import json
+from pathlib import Path
+
+from .traces import digest, validate
+
+CATALOG = {
+    "webclick": {
+        "url": "https://huggingface.co/datasets/Hcompany/WebClick",
+        "cohort": "webclick",
+        "role": "layout fixtures only; no timed motion",
+        "terms": "Apache-2.0 dataset card; retain source attribution",
+    },
+    "sapimouse": {
+        "url": "https://github.com/margitantal68/sapimouse",
+        "cohort": "sapimouse",
+        "role": "mouse sessions",
+        "terms": "Repository Apache-2.0; verify separate raw-download terms before redistribution",
+    },
+    "balabit": {
+        "url": "https://github.com/balabit/Mouse-Dynamics-Challenge",
+        "cohort": "balabit",
+        "role": "remote desktop mouse sessions",
+        "terms": "Record source README terms; no blanket license inferred",
+    },
+    "derived_mouse_dynamics": {
+        "url": "https://data.mendeley.com/datasets/9rv9s3v2br/1",
+        "cohort": "balabit",
+        "role": "derived from Balabit; not an independent cohort",
+        "terms": "Verify version-specific data terms",
+    },
+    "cmu": {
+        "url": "https://www.cs.cmu.edu/~keystroke/",
+        "cohort": "cmu_fixed_text",
+        "role": "fixed-text timing only",
+        "terms": "Research dataset; cite Killourhy and Maxion DSN 2009; verify source terms",
+    },
+    "becaptcha": {
+        "url": "https://github.com/BiDAlab/BeCAPTCHA-Mouse",
+        "cohort": "becaptcha",
+        "role": "optional mouse trajectories",
+        "terms": "Institutional agreement required; no automatic access or redistribution",
+    },
+}
+
+
+def provenance(path, dataset, terms_note):
+    if not terms_note.strip():
+        raise ValueError("Record the permitted use/terms you verified for this dataset")
+    return {**CATALOG[dataset], "file_sha256": digest(path), "terms_note": terms_note}
+
+
+def webclick_box(box: list[float], width: int, height: int) -> dict:
+    """WebClick bbox is normalized [left, top, right, bottom], never a path."""
+    if len(box) != 4 or not all(isinstance(x, (float, int)) and 0 <= x <= 1 for x in box):
+        raise ValueError("WebClick bounding box must be finite normalized coordinates")
+    left, top, right, bottom = box
+    if right <= left or bottom <= top or width <= 0 or height <= 0:
+        raise ValueError("Empty, reversed, or invalid WebClick box")
+    return {
+        "x": left * width,
+        "y": top * height,
+        "width": (right - left) * width,
+        "height": (bottom - top) * height,
+    }
+
+
+def mouse_csv(
+    path: str | Path,
+    *,
+    dataset: str,
+    participant: str,
+    session: str,
+    split: str,
+    timestamp_scale: float,
+    terms_note: str,
+    timestamp_column: str | None = None,
+) -> list[dict]:
+    if dataset not in {"sapimouse", "balabit"} or timestamp_scale <= 0:
+        raise ValueError("Choose sapimouse/balabit and explicit seconds-per-timestamp-unit")
+    path = Path(path)
+    with path.open(encoding="utf-8-sig", newline="") as stream:
+        sample = stream.read(4096)
+        stream.seek(0)
+        dialect = csv.Sniffer().sniff(sample, delimiters=",;\t")
+        rows = [
+            {k.strip().lower(): v.strip() for k, v in r.items()}
+            for r in csv.DictReader(stream, dialect=dialect)
+        ]
+    events = []
+    column = timestamp_column or "client timestamp"
+    for row in rows:
+        state = row["state"].lower()
+        if state in {"move", "drag"}:
+            kind = "move"
+        elif state in {"pressed", "press", "down"}:
+            kind = "button_down"
+        elif state in {"released", "release", "up"}:
+            kind = "button_up"
+        else:
+            continue
+        event = {
+            "kind": kind,
+            "t": float(row[column]) * timestamp_scale,
+            "x": float(row["x"]),
+            "y": float(row["y"]),
+        }
+        if kind != "move":
+            event["button"] = row["button"].lower()
+        events.append(event)
+    if not events:
+        raise ValueError("No supported input events found")
+    origin = events[0]["t"]
+    for e in events:
+        e["t"] -= origin
+    source = digest(path)
+    chunks, chunk = [], []
+    for e in events:
+        chunk.append(e)
+        if e["kind"] == "button_up" and len(chunk) >= 5:
+            chunks.append(chunk)
+            chunk = []
+    if len(chunk) >= 5:
+        chunks.append(chunk)
+    output = []
+    for i, chunk in enumerate(chunks):
+        start = chunk[0]["t"]
+        chunk = [{**e, "t": e["t"] - start} for e in chunk]
+        output.append(
+            validate(
+                {
+                    "participant_id": participant,
+                    "session_id": session,
+                    "recording_id": f"{source}:{i}",
+                    "source_recording_id": source,
+                    "cohort": CATALOG[dataset]["cohort"],
+                    "condition": "remote_desktop" if dataset == "balabit" else "sapimouse_capture",
+                    "task_id": "unlabelled_pointing",
+                    "split": split,
+                    "label": "human",
+                    "modality": "mouse",
+                    "events": chunk,
+                    "provenance": provenance(path, dataset, terms_note),
+                }
+            )
+        )
+    return output
+
+
+def cmu_csv(path: str | Path, *, split: str, terms_note: str) -> list[dict]:
+    source = digest(path)
+    output = []
+    with Path(path).open(encoding="utf-8-sig", newline="") as stream:
+        for i, row in enumerate(csv.DictReader(stream)):
+            holds = [(k, float(v)) for k, v in row.items() if k.startswith("H.")]
+            down_to_down = [float(v) for k, v in row.items() if k.startswith("DD.")]
+            events, t = [], 0.0
+            for j, (_, hold) in enumerate(holds):
+                events.extend(
+                    [
+                        {"kind": "key_down", "press_id": j + 1, "t": t},
+                        {"kind": "key_up", "press_id": j + 1, "t": t + hold},
+                    ]
+                )
+                if j < len(down_to_down):
+                    t += down_to_down[j]
+            participant, session = row["subject"], row["sessionIndex"]
+            # Source grouping is per actual subject/session, not the consolidated CSV container.
+            recording = hashlib.sha256(f"{source}:{participant}:{session}".encode()).hexdigest()
+            output.append(
+                validate(
+                    {
+                        "participant_id": participant,
+                        "session_id": f"{participant}:{session}",
+                        "session_time": int(session),
+                        "recording_id": f"{recording}:{i}",
+                        "source_recording_id": recording,
+                        "cohort": "cmu_fixed_text",
+                        "condition": "cmu_fixed_password",
+                        "task_id": "cmu_fixed_text",
+                        "split": split,
+                        "label": "human",
+                        "modality": "keyboard",
+                        "events": sorted(events, key=lambda e: e["t"]),
+                        "provenance": provenance(path, "cmu", terms_note),
+                    }
+                )
+            )
+    return output
+
+
+def becaptcha_json(path, *, agreement_reference: str) -> list[dict]:
+    if not agreement_reference.strip():
+        raise ValueError("A verified institutional agreement reference is required")
+    # Deliberately accepts an institution's canonical export, not undocumented restricted formats.
+    rows = json.loads(Path(path).read_text())
+    for row in rows:
+        validate(row)
+        row["provenance"] = {
+            **CATALOG["becaptcha"],
+            "agreement_reference": agreement_reference,
+            "file_sha256": digest(path),
+        }
+    return rows