jdZddlmZddlZddlZddlmZddlmZgdZ dZ dZ d Z d Z d Zd ZdXdZdYdZedGddZdZdZd[d!Zd\d$Zd]d)Zd^d_d-Zd`d0ZedGd1d2ZedGd3d4ZedGd5d6Zdad;Zdbd>Zdcd@ZdddAZdedFZ dfdIZ!dgdKZ"dddLdhdSZ#GdTdUZ$didWZ%dS)jaCursor motion planning - per-session mouse trajectories, in pure Python. Why this lives here and not in the engine ----------------------------------------- The trajectory the cursor follows between two points is a *shape*, and a shape built out of hardcoded constants is an invariant: it is byte-for-byte the same curve family for every movement, of every session, of every install of this package. Anything that can be measured once can then be recognised forever, and worse, it links every account a single user runs. So every number that decides what a path looks like is drawn from the session seed instead of being written in the source: the arm geometry, the number of control knots, the easing, the duration law, the sampling interval, the tremor and its anisotropy, how often a movement overshoots and how often two events land on the same device pixel. Two seeds therefore produce measurably different *families* of paths, not just different samples from one family. The same seed reproduces byte-identical paths, because seed-reproducibility is a documented property of this package and callers rely on it (``InvisiblePlaywright(seed=42)``). Design notes worth keeping -------------------------- * **Noise is zero-mean.** Tremor is drawn from ``gauss(0, sigma)``. A non-zero mean puts a systematic drift on every waypoint of every path ever produced, which is both a bug and a signature. * **Noise is genuinely two-dimensional.** Tremor has an *along-travel* and an *across-travel* component with independent draws and their own scales, so the displacement covariance of a movement has two non-negligible eigenvalues. A tremor applied on a single direction is rank-1: every displacement in the movement is parallel to one vector, which is a one-line test to detect. It also leaves a whole screen axis noiseless whenever the movement happens to be horizontal or vertical, and an exactly noiseless axis lies on an analytic curve that can be solved from a handful of samples and used to predict the rest of the stream. * **Every interior waypoint is displaced.** Not a random subset: a subset means a knowable fraction of the emitted points sit *exactly* on the underlying analytic curve, which is the same break in a slower form. * **The speed profile is bell-shaped and drawn per movement.** Speed is zero at both ends, peaks somewhere near the middle, and the peak position is random per movement inside a per-seed sub-range. A single fixed easing is an invariant even when the positions differ; an easing that starts at maximum speed also implies infinite initial acceleration, which no hand does. * **Duration follows a Fitts-style law**, so a long movement takes longer than a short one. A constant duration makes implied speed scale with distance, which is backwards. * **Aiming overshoots, sometimes.** A ballistic reach lands past its target and is pulled back by a corrective submovement. A generator whose axial progress is monotone in 100.000% of its paths is as recognisable as one that always drifts the same way: "exactly zero, always" is a signature too. The overshoot here is bounded and its rate is per-seed. * **Two consecutive events may share a device pixel.** Reported coordinates are integers, so a pointer crawling through the slow ends of a movement really does repeat one. A duplicate rate of exactly zero on every path is, again, an exact invariant. The rate is per-seed and bounded, and never becomes the long run of identical tail events that a fixed ease-out produces. * **The per-seed difference lives in the SHAPE.** Fine timing does not survive dispatch (a scheduler quantises short sleeps), so a generator whose sessions differ only in tempo differs in nothing observable. The arm geometry below - a per-seed pivot direction that decides which way a stroke bows, given its direction on screen - is what makes two seeds trace visibly different curves between the same two points. The module is pure: no Playwright, no network, no filesystem, no clock. Every property it claims is verifiable with arithmetic alone - which is exactly what lets ``tests/test_motion.py`` check its statistics without launching a browser. ) annotationsN) bisect_left) dataclass) MotionStyleWaypoint CursorMotionstyle_for_seed MIN_STEPS MAX_STEPSMIN_DURATION_MSMAX_DURATION_MSSAMPLE_FLOOR_MSD@g@@ @g& .>seedinttagstrreturncdt|dzz }|dD]}||z}|dzdz}|dzS)zFNV-1a mix -> independent PRNG streams per logical bucket from one seed. Same convention used elsewhere in the package for deriving sub-streams; kept local so this module stays importable on its own with nothing but stdlib. l%#Ds_ lzutf-8li)rencode)rrhchs MC:\Projects\Historical\venv\Lib\site-packages\invisible_playwright/_motion.py_mixrisZ c$ii*<<=Ajj!!55 R  "4 4 z>vfloatlohic&||kr|n ||kr|n|SN)rr!r"s r_clampr&vs R22AFFbb2rT)frozenceZdZUdZded<ded<ded<ded<ded <ded <ded <ded <ded <ded<ded<ded<ded<ded<ded<ded<ded<ded<ded<ded<ded<ded<ded<ded<ded<ded<ded<ded <ded!<ded"<ded#<ded$<ded%<ded&<ded'<ded(<ded)<d*S)+ra'The shape parameters of one session. All of it is drawn from the seed. Every field below replaces something that used to be a literal. The ranges are picked so that two installs are very unlikely to share a shape, while every single sample still reads as a hand moving a mouse. rknotsztuple[float, ...] knot_baser knot_wobblebow_basebow_frac bow_abs_px bow_knee_px pivot_anglepivot_strengthbow_bias bow_cap_px short_move_px target_w_px fitts_a_ms fitts_b_ms dur_jitterstep_ms step_jitter ease_a_lo ease_a_hi ease_r_lo ease_r_hitremor_across_px tremor_anisotremor_full_pxtremor_burst_ptremor_burst_mult tremor_shape overshoot_povershoot_fracovershoot_cap_pxovershoot_min_px over_start_lo over_start_hi over_shape dup_keep_p dup_run_maxN__name__ __module__ __qualname____doc____annotations__r%rrrr}sJJJ!    OOOOOONNN    rrc btjt|d}|dd|dd|ddf}|dd|dd|ddf}|d d }t ||d d zd }||kr|dz}|dd}t ||ddzd}|dd}t ||ddzd} t ddid|ddd|d|ddd|d|dd d!|d"d#d$|d%d&d'|d(d)tjzd*|dd+d,|d-d.d/|d0d1d2|d0d&d3|d4d5d6|d&d7d8|d&d9d:|d;d<d=|d>d?d@|d;d.dA|dB|dC|dD|dE|dFdGdH|d.dIdJ|dKd7dL|dMddN|dOdPdQ|d dRdS|dTddU|dVdWdX|d?dYdZ|d[d\d]|d^| d_|d`dRda|d;dbdc|ddS)ez:Draw one session's shape parameters from the session seed.z motion:stylegQ?gRQ?gףp= ?g)\(?g?g333333?gffffffg333333?g@g333333?gffffff?g @g?g(\?g333333?g?g?g?gQ?gp= ף?r)r*r+g{Gz?gQ?r,r-gMb?g/$?r.?g@r/g>@gV@r0g@r1Q?r2gffffffֿffffff?r3rg[@r4r5g<@gL@r6gg@r7gd@r8g?gQ?r9rg2@r:r;r<r=r>r?g{Gz?g(\?r@gffffff?rAgQ@rBg?rCg?gffffff@rDg?rEgQ?rFg{Gz?{Gz?rGgF@rHg$@gA@rIrJrKg?rL皙?rMr%) randomRandomruniformminrrandintmathpi) rrr*r,a_loa_hir_lor_hiover_loover_his rr r s d40011A $ $ $I $ % %H 99T4 D taiid+++T 2 2D t||d{ 99T4 D taiid+++T 2 2Diid##G'AIIdD111488G & & & ii1ooo& )& IIdD)))&  &  5%((( &  99S#&&& & IIdD)))& IIc3=111& yyt,,,& 5$'''& 99T5)))& iid+++& IIdD)))& 99T5)))& 99T5)))&  99T4(((!& " #t$$$#& $IIdD)))%& &$'& ($)& *$+& ,$-& .4.../& 0YYtT***1& 2yyu---3& 4yyt,,,5& 6))C---7& 8YYtT***9& :IIdD)));& <yy...=& >4...?& @4...A& BgC& DgE& F99T4(((G& H99T4(((I& JIIaOOOK& &rctrllist[tuple[float, float]]ttuple[float, float]c|tdkr?fdttdz Dtdk?dS)z>De Casteljau. Degree is 2..4 here, so the O(n^2) form is free.rUcg|]f}|d|dzd|dz zz|d|dzd|dz zzfgS)rrUr%).0iptsrms r z!_bezier_point..Gs   Aq SQZ]SVAY6!;;Aq SQZ]SVAY6!;;    rr)lenrange)rkrmrss `@r _bezier_pointrwCsu C c((Q,,     3s88a<((     c((Q,, q6Mrntuple[list[float], list[float]]c ffdtD}fd|D}dg}tdD]o}||dtj||d||dz dz ||d||dz dz zp||fS)zISample the curve uniformly in t and return (t values, cumulative length).c g|] }|dz z  SrUr%rqrrrxs rrtz_arc_table..U! ( ( (!!q1u+ ( ( (rc0g|]}t|Sr%)rw)rqrmrks rrtz_arc_table..Vs# . . .a=q ! ! . . .rrXrUr)rvappendrbhypot)rkrxtsrscumrrs`` r _arc_tablerQs ) ( ( (uQxx ( ( (B . . . .2 . . .C %C 1a[[__ 3r7TZAq CAJqM(A3q6!9sSTWXSXzZ[}C\]]]^^^^ s7Nrr list[float]rscj|d}|tkrdSt|d|}t||}|dkr|dS|t|kr|dS||||dz z }|tkrdn|||dz z |z }||dz ||||dz z |zzS)zBInvert the arc-length table: linear interpolation between samples.rrXrrU)_EPSr&rru)rrrtotaljspanfs r _t_at_arclenr]s GE }}sq#uACAAvv!u CHH}}"v q6CAJ Dt||!c!a%j.D!8A a!e911q5 )Q. ..rAabc fdtD}fd|D}dg}tdD]J}||dd||||dz zz||||dz z zzK|dtkrfdtDSfd|D}d |d<|S) aCumulative (normalised) distance profile for a Beta-shaped speed density. Speed density v(t) = t^(a-1) * (1-t)^(b-1) with a, b > 1: zero at both ends, single interior peak at (a-1)/(a+b-2). Integrating gives a monotone S(t) with S(0)=0 and S(1)=1 exactly. c g|] }|dz z  Sr|r%r}s rrtz"_profile_table..tr~rc8g|]}|dz zd|z dz zzS)rWr%)rqrmrrs rrtz"_profile_table..us3 D D DAQ1s7^qa#g 6 7 D D DrrXrUrg?c g|] }|dz z  Sr|r%r}s rrtz"_profile_table..{s!...QU ...rcg|]}|z Sr%r%)rqcrs rrtz"_profile_table..|s " " "1u9 " " "rrW)rvrr) rrrxrdensrrroutrs ``` @r_profile_tablerms ) ( ( (uQxx ( ( (B D D D D D D D DD %C 1a[[RR 3r7SDGd1q5k$9:bebQi>OPPQQQQ GE }}....U1XX.... " " " "c " " "CCG Jrtableuc|dkrdS|dkrdS|t|dz z}t|}|t|dz kr|dS||||dz||z ||z zzS)z2Interpolate the cumulative profile at u in [0, 1].rXrWrUr)rur)rrxrrs r _profile_atrsCxxsCxxs SZZ!^A AACJJNRy 8uQU|eAh.1q59 99rc<eZdZUdZded<ded<ded<ded<dS)raOne synthetic mousemove. ``dt_ms`` is how long to wait *before* dispatching this point (0 for the first); ``t_ms`` is the same schedule expressed as elapsed time from the start of the movement, for callers that prefer to correct their own drift. r rydt_mst_msNrNr%rrrrs@ HHH HHHLLLKKKKKrrceZdZUdZded<ded<ded<ded<ded<ded<ded <ded <ded <eddZddZdS)_Axisa'The straight line from start to end, and the frame built on it. Every stage below places points as "so far along the travel, so far to the side of it", so the unit tangent and normal are computed once here rather than being threaded through six signatures as four loose floats. r from_xfrom_yto_xto_ydistuxuynxnyr'_Axis'c ||z ||z }}tj||}||z ||z } }|t|t|t|t|||| | | Sr$)rbrr ) clsrrrrdxdyrrrs rbetweenz _Axis.betweensxv Bz"b!!dBIBs5==%--teDkkR"b** *ralongacrossrncv|j|j|zz|j|zz|j|j|zz|j|zzfSr$)rrrrrr)selfrrs ratz_Axis.atsF dgo-&0@@ dgo-&0@@B BrN) rr rr rr rr rr)rr rr rrn)rOrPrQrRrS classmethodrrr%rrrrsMMMMMMKKKKKKKKK III III III III***[*BBBBBBrrcTeZdZUdZdZded<dZded<dZded<dZded<d d Z d S) _OvershootabA reach that lands past its target and is pulled back. A hump added to the position, mostly along the travel: it rises after ``u0``, peaks past the target, and returns to zero at u = 1, so the endpoint stays exact while the axial coordinate genuinely goes backwards on the way in. ``amp == 0`` means this movement did not overshoot. rXr ampperprWu0shaperrc|jdks ||jkrdStjtj||jz zd|jz z |jzS)aHow much of the hump applies at fraction ``u``; 0 outside it. The WEIGHT, not the displacement. The caller multiplies in the same grouping the original expression used - see the note in ``_control_polygon`` about float multiplication not being associative; returning ``amp * w`` here and multiplying by the unit vector there regroups it and shifts the result in the last bit. rXrW)rrrbsinrcr)rrs r weight_atz_Overshoot.weight_atsM 8s??a47ll3x1tw;/3=ABBdjPPrN)rr rr ) rOrPrQrRrrSrrrrr%rrrrs|CDBOOOOE Q Q Q Q Q Qrrrng random.Randomaxisstc~tjj|jztjj|jzz }j|jzj|jz|jj zz z}|jj krdnj }tfdt|D}|j|jfg}t!|D]\}} j|} |j|z| zdjz jdz| zzz} t+| j j} ||j|j|jz| zz|j| zz|j|j|jz| zz|j| zzf||j|jf|S)aKnots near their per-seed axial positions, displaced across the travel. How far, and on which side, is mostly decided by the session's arm geometry: a stroke swinging about a joint at ``pivot_angle`` bows away from that joint, so the same two endpoints give one session a left-hand arc and another a right-hand one. That is deterministic given the direction of travel, which is exactly why it separates sessions instead of averaging out over movements. rUc3K|]<}tj|djzddV=dS)rXr[rYN)r&r*gaussr+)rqrrrs r z#_control_polygon..s^  r|A3!?!??tLLrrW)rbcosr0rrrr-rr.r/r4r)sortedrvrr enumerater,r1rr2r&r3rrrrr) rrrswing amp_scalen_knotsaxialrkrrmagrs ` ` r_control_polygonrshr~&&048BN3K3Kdg3UU VEty(=49, BN0JKLI9r///aaRXG w  E[$+ & 'D%  MM1k!n   % +R&&#))BK*E*EEK L S2=."-88 T[47TY#6#::TWs]J[47TY#6#::TWs]JL M M M MKKDI&''' Krtarget_w float | Nonec2|r|dkrt|n|j}tj|j|z dz}|j|j|zztj|d|j z}t|ttS)aFitts, fed the WIDTH of the thing being hit. The generator cannot derive that width from two points. Until 2026-07-26 it always used the per-seed default, so a stroke to a 20 px control and one to a 200 px control took the same time - the law was implemented and then fed a constant. The planner knows the box; passing it is giving the model a fact, not taking over its pacing. rrWrX) r r5rblog2rr6r7exprr8r&r r )rrrrwbitsdurations r_movement_durationrs$H1 h".A 9TY]S( ) )D   44 #r}%%9'9''H (O_ = ==rrctt|jz }ttt t |}fdt|D}t|}dg}d}|D]"}||z }| ||z|z #||d<t|dkr|S|dg} |ddD]+} | | dz tkr| | ,t| dkr(|| dz tkr| | || S)aWhen each sample is taken, never closer together than a device can report. PHYSICAL FLOOR. The increments are log-normal with no lower bound, so the tail lands under any real sampling interval: measured 2026-07-26, 8.64% of emitted gaps were below 8 ms and the smallest was 3.52 ms, i.e. 284 Hz, while the per-seed nominal interval was a sane 9.7-17.9 ms. A mouse reports at 125 Hz (8 ms) and the browser coalesces on top of that, so a gap under that is not fast sampling - it is a rate no device produces, and it is measurable on the wire without any statistics. DROPPED, not compressed. Squeezing the gap back up would move every later point and change the movement's duration; dropping the offending sample keeps the schedule and the endpoint exactly as drawn. Same choice the dispatcher makes for the time cap: fewer events, never faster ones. cjg|]/}tjdj0S)rX)rbrrr:)rq_rrs rrtz!_sample_times..8s3 M M MDHSYYsBN33 4 4 M M MrrXrrrrU) rroundr9maxr r`r rvsumrrurpop) rrrn_stepsincs total_inctimesaccrkepttms ` ` r _sample_timesr#sW"%2:-..//G)SG4455G N M M M MeGnn M M MDD I EE C 11 q X^i/0000E"I 5zzQ !H:DAbDk R=O + + KKOOO 4yy1}}DH,>>  KK Krc |j|jks||jkrt St |j|jztj| ddzd|j }t ||| ddz| |j |j |jS)NrXrZr\)rrrr)rrHr]rErr&rFrbrrrGr_rIrJrK)rrrrs r_draw_overshootrPs y2&&&#**,,".*H*H|| "TY.#))C:N:N1O1OOb) + +C #3!5!55R%5r7GHHM + + ++rrprofover list[tuple[float, float, float]]c tdtdt|jdz dz}t ||\}}|d} g} t |dz } t |D]\} } | dkr#| |j|j df/| | kr#| |j |j | fX| |z }t|t||t||| z\}}||}|rP||j|jz|z|j|jz|zzz }||j|jz|z|j|jz|zzz }| ||| f| S) zWalk the curve by ARC LENGTH, not by parameter. Sampling a Bezier at even parameter steps clusters points where the curve is tightly wound; the velocity profile is only a velocity profile if the distance covered follows it. g@rrUrrX)rr`rrrrurrrrrrrwrrrrrrrrr)rkrrrrrn_arcrrlengthrawlastrrrrpxpyrs r _sample_curver\s CSS11A566 7 7Eu%%GB WF,.C u::>D5!!!!2 66 JJ T[#6 7 7 7  99 JJ 49b1 2 2 2  Mt\"c2=dA2F2F2O&Q&QRRB NN1    C $'DH$q(47TY+>+BB BB $'DH$q(47TY+>+BB BB BB<    JrrNonectdtj|j|jz }|j|z}||jz}tdt|dz D]}||\} } } tj tj | |z z|j z} | d|} | d|}| |jkrB| | d||jzz } || d||jzz }| | z} || z}| |j| zz|j|zz| |j| zz|j|zz| f||<dS)aMTwo independent components on every interior waypoint, in place. LAST among the drawing stages, deliberately: `with_jitter=False` skips only this, so both runs share an rng stream up to here and can be differenced point by point. That is how the zero-mean property and the tremor covariance are measured at all. rWrUrXN)r`rbsqrtrrAr?r@rvrurrcrDrr]rBrCrrrr)rrrrrgain across_pxalong_pxrrrrrra_offc_offs r _apply_tremorr}sl sDIdi"*;;<< = =D#d*I2?*H 1c#hhl # # > >V B HTWX . / /2? B #x(( #y)) ::<<"+ + + SYYsHr/C$CDD DE SYYsI0D$DEE EE    tw&58tw&58">A > >rlist[Waypoint]c &g}g}d}d}t|D]\}\}} } t|t| f} |t|dz k} |rx| |dkrl|dz }||jkr||jks>| s{|||r |djnd}d}nd}|t|| | |z | || | }|S)azBounded runs of repeated device pixels. Keeping a repeat sometimes is the point (see the module docstring); what must not happen is the long run of identical tail events a fixed ease-out produces, so a run is cut at ``dup_run_max``. The final waypoint always carries the exact endpoint, whether it repeats a pixel or replaces the point that would have. rXrrUr) rrrurMr]rLrrrr) rrrrkeysprev_trunrrrrrkeyrs r_collapse_duplicate_pixelsr s%C"$D F C$S>>))cjjllR].J.J  ),5R#C 8BBK44555 C Jr) with_jitterrrrrrr boolctj||z ||z tks@t|t|krMt|t|kr-t t |t |ddgSt ||||}t|||} t||||} t|| |} | |j |j } t| | | |j|jz} t#|||}t%| | | || |}|rt'||||| t)|||S)aqBuild one path, as a pipeline of the stages above. ``rng`` supplies every per-movement draw, and the stage order is the draw order - see the note above the stages before reordering anything. ``with_jitter=False`` returns the same path with the tremor switched off and nothing else changed: same control polygon, same schedule, same overshoot. rX)rbrrrrr rrrrrr_r;r<rr=r>rrrr )rrrrrrr rrrkrrease_arrrs r_planrsT, 4&=$-00477f t,,v%++1M1MteDkk3<<== ==t 4 4D Cr * *D!#tR::H #x , ,E [[r| 4 4F &&3;;r|R\+R+R"R S SD 3b ) )D eXtT4 @ @C4c3b(333 %c3 3 33rceZdZdZdZdddd Zedd ZeddZeddZ d dZ dddd!dZ dS)"raZPer-session cursor path generator. ``CursorMotion(seed)`` fixes the session's shape family; each call to :meth:`path` draws one movement from it. The n-th movement of a given seed is always the same path, and each movement has its own independent PRNG stream, so inserting or removing a movement does not perturb the others. )_seed_style_countN)stylerrrMotionStyle | Nonerrcvt||_||nt|j|_d|_dS)Nr)rrr rr)rrrs r__init__zCursorMotion.__init__s4YY $0eenTZ6P6P  rc|jSr$)rrs rrzCursorMotion.seeds zrrc|jSr$)rrs rrzCursorMotion.styles {rc|jS)z8How many movements have been generated on this instance.rrs rcountzCursorMotion.counts {rcd|_dS)z?Rewind the movement counter (a fresh page/context starts over).rNrrs rresetzCursorMotion.resets  r)indexrrr rrrr" int | Nonerrrc ||j}|xjdz c_tjt|jdt |z}t ||||||j|S)zWaypoints from (from_x, from_y) to (to_x, to_y), inclusive of both. Pass ``index`` to address a specific movement of the session without advancing the counter (used by the tests; also handy for replay). NrUzmotion:move:%d)r)rr]r^rrrrr)rrrrrr"rrs rpathzCursorMotion.pathso =KE KK1 KKmD-=E -JKKLLS&&$dk&((( (r)rrrrrr)rr)rr)rr)rr rr rr rr r"r#rrrr) rOrPrQrR __slots__rpropertyrrrr!r%r%rrrrs.IAE XXX!!%((((((((rrr%c$|r |djndS)z2Wall time the whole movement is scheduled to take.rrX)r)r%s rtotal_msr)s )48==c)r)rrrrrr)rr r!r r"r rr )rrrr)rkrlrmr rrn)rkrlrxrrry)rrrrrr rr )r)rr rr rxrrr)rrrr rr )rrrrrrrrl) rrrrrrrrrr )rrrr rrrr)rrrrrrrr)rkrlrrrr rrrrrrrr) rrrrrrrrrr rr)rrrrrrrr)rrrr rr rr rr rrr rrrrr)r%rrr )&rR __future__rrbr]bisectr dataclassesr__all__r r r r rrrr&rr rwrrrrrrrrrrrrrr rrr)r%rrr.s\@@D#""""" !!!!!!   "         3333 $uuuuuuuupGGGGZ         / / / / ( : : : :  $         $BBBBBBBB@ $QQQQQQQQJ%%%%P>>>>(****Z + + + +B>>>>4!!!!X!&4&4&4&4&4&4R5(5(5(5(5(5(5(5(p******r