maka/docs/computer-use-cursor-provenance.md

Computer Use cursor provenance and independent replacement

This document records the exact source boundary for Maka's agent-cursor overlay and the independent replacement completed for Apache Maka issue #3293. The historical record corrects the first revision of pull request #2676 without classifying the Computer Use implementation as a whole as derived from the inspected binary.

Current status

The current cursor no longer retains the glyph geometry, hotspot placement, motion values, close-enough thresholds, path-measurement constants, core score, or terminal-heading behavior transcribed from the proprietary binary described later in this document. Those inputs are historical only.

The replacement was derived before the contributor inspected the values it replaced. The complete public derivation is recorded at:

https://github.com/apache/maka/issues/3293#issuecomment-5371901326

The derivation used four Maka product requirements:

1. keep the agent cursor legible at 1x over arbitrary application content;
2. land the action hotspot before native click dispatch is released;
3. prefer the straightest valid route on long moves; and
4. settle position and heading without visible overshoot.

Independent replacement values

Glyph and action hotspot

The replacement is a rounded dart drawn inside a normalized unit square. Its tip is both the path start and the action hotspot. CursorEngine.pos remains the sole action coordinate, and rendering translates that coordinate directly to local canvas (0, 0) before drawing the tip.

• size = 20 CSS px;
• shadowBlur = 3 CSS px;
• maximum tip-to-painted-edge allowance and boundsMargin = 20 + 3 = 23 CSS px;
• start (0.00, 0.00);
• cubic controls (0.03, 0.23), (0.11, 0.51), end (0.20, 0.83);
• line (0.43, 0.63);
• cubic controls (0.49, 0.57), (0.57, 0.60), end (0.63, 0.69);
• line (0.80, 1.00);
• line (1.00, 0.89);
• cubic controls (0.86, 0.63), (0.69, 0.40), end (0.00, 0.00).

CURSOR_GLYPH retains its public tuple shape: each curve stores its endpoint first, followed by its two controls. The PiP SVG is the same path with the same local-origin hotspot. The status-item PNGs are deterministically rasterized from this geometry with Maka's existing blue gradient on a transparent background. Regenerate them from the repository root with node scripts/generate-cu-status-icons.mjs.

Motion configuration

CURSOR_MOTION retains the 30-field configuration shape. Its current values and independent rationale are:

Field	Replacement	Derivation
clickAngle	-π/4	Canonical diagonal resting direction
candidateCount	9	Odd symmetric grid with a guaranteed zero-arc candidate
boundsMargin	23	Glyph size plus shadow allowance
startHandle	1/3	Canonical straight cubic handle
endpointHandle	1/3	Same construction at arrival
arcSize	0.30	Avoidance candidates without encouraging desktop sweeps
arcFlow	0.50	Symmetric perpendicular displacement
straightPathDistanceThreshold	60	Three glyph widths
springResponseScaler	1/2400 s/px	Distance-scaled response in seconds per pixel
springResponseMin	0.18 s	Lower response bound
springResponseMax	0.72 s	Upper response bound
springDampingFraction	1.0	Critical damping; no position overshoot
scootDistanceThreshold	60 px	Three glyph widths
scootPositionResponse	0.16 s	Deformation follows main motion
scootPositionDampingFraction	1.0	No position bounce
scootPositionSettleVelocity	2 px/s	One tenth of the glyph size per second
scootAxisResponse	0.12 s	Axis responds faster than position
scootAxisDampingFraction	1.0	No axis overshoot
scootBaseRotationResponse	0.18 s	Matches the shortest main response
scootBaseRotationDampingFraction	1.0	No base-rotation bounce
scootStretchResponse	0.14 s	Subtle shape response
scootStretchDampingFraction	1.0	No stretch bounce
scootStretchMin	0.92	1 - 0.08, matching maximum Y squash
scootStretchPivotX	0.25	Keeps the leading quarter near the hotspot
scootStretchXAmount	0.16	Maximum 16% longitudinal stretch
scootSquashYAmount	0.08	Half the X deformation
scootRotationResponse	0.16 s	Tracks the deformation response
scootRotationDampingFraction	1.0	No rotational overshoot
scootRotationMax	π/8	22.5 degrees, half the resting diagonal
terminalTangentBlendStart	0.80	Final fifth blends into click heading

The position response is calculated as:

response = clamp(distanceInPixels * (1 / 2400 secondsPerPixel), 0.18, 0.72)

Path measurement and scoring

SCORE_SAMPLES = 33 means 33 points, including both endpoints, and 32 equal-length parameter intervals. The independent core measures are:

detour      = max(0, measuredLength / directDistance - 1)
angleEnergy = mean(deltaHeading²)
maxAngle    = max(abs(deltaHeading)) / π
totalTurn   = sum(abs(deltaHeading)) / π
outOfBounds = 0 or 1

For the degenerate chord, zero measured length has zero detour; positive measured length over a zero direct distance is rejected with infinite score.

The independent core score is:

8 * detour
+ 1.5 * angleEnergy
+ 2 * maxAngle
+ 0.5 * totalTurn
+ 1,000,000 * outOfBounds

These terms are dimensionless and positive. A valid straight path therefore wins when available, while leaving the viewport is a lexicographic rejection rather than a cosmetic preference. Maka's earlier raw path-length addition and backwards-arrival penalty remain around this core, as issue #3293 requires.

The independently derived scorer continues to evaluate Maka's existing single-segment cubic candidate family. It does not import any candidate generator from the historical artifact.

As a new Maka integration choice for this replacement, the nine-candidate budget is allocated by selection rather than a Cartesian product. This reconciles the independent count of nine with Maka's retained five-way departure fan. Fresh motion uses nine symmetric arc values at direct departure. Interrupted motion keeps all five DEPARTURE_FAN weights: five symmetric arcs (including zero) at direct departure, plus one zero-arc candidate at each of the other four departure weights. This allocation is an implementation choice around the independently derived odd symmetric budget, not part of that derivation.

Terminal heading

Fresh motion begins facing the path target. Over progress [0.80, 1.00], the engine computes the shortest signed angular difference from the path tangent to clickAngle and interpolates it with:

phase = clamp((progress - 0.80) / 0.20, 0, 1)
weight = phase² * (3 - 2 * phase)
heading = tangentAngle + shortestSignedDifference * weight

Wrapping the difference before interpolation prevents a long-way rotation across the -π/π boundary.

Close-enough gate and presentation deadline

The independent gate is:

progress = 0.99999
distance = 2 CSS px

Five-nines progress leaves at most one CSS pixel on a 100,000 CSS-pixel route, which is within the independent 2px distance gate. The deadline is not chosen separately from these values.

For the slowest critical spring, the engine replays its semi-implicit integration with:

response = 0.72 s
damping fraction = 1.0
step = 1 / 240 s
progress threshold = 0.99999

The threshold is reached at 1725ms. At the slowest supported presentation cadence of one frame per second, release is observable on the 2000ms frame. Adding 100ms of renderer/IPC scheduling margin gives:

cursorPresentationReadyDeadlineMs() = 2100 ms

The overlay seeds the engine clock at motion submission, so the first one-fps frame advances the first second. When a move interrupts another, the old path is first aligned to the same submission timestamp and the replacement is then seeded at that timestamp, preventing pre-replacement time from replaying into the new path.

The persistent transparent BrowserWindow disables Electron background throttling so its real requestAnimationFrame path does not enter a background-only one-fps phase drift while unfocused. Readiness is evaluated and reported only from that frame path after painting. Idle CPU behavior is unchanged because the renderer stops requesting frames once the engine settles.

The controller continues to source its ready fence from this function, so its fence cannot silently fall below the derived deadline. The result remains below the separate 5000ms dead-renderer backstop.

Historical binary-inspection record

Before issue #3293, Maka retained exact inputs recovered from this artifact:

• application: ~/.codex/computer-use/Codex Computer Use.app;
• executable: Contents/MacOS/SkyComputerUseService;
• bundle identifier: com.openai.sky.CUAService;
• signed build date: 2026-07-16;
• SHA-256: 44320516c4c400fb5459b203498c78e4af318b0096464f16c4445a47f2b8b8f4.

Pull request #1255 introduced binary-derived glyph, hotspot, and motion values. Pull request #1883 introduced binary-derived path-measurement and scorer values. Pull request #2676 documented that boundary. The proprietary artifact is not stored in this repository, and the recorded local path later contained a different signed build.

Those former inputs remain visible in published Git history and are described here only as historical provenance. They are not retained by current cursor behavior. Issue #3293 resolves the current-source gate by replacement, not by a legal determination about the former facts.

No OpenAI source code or executable bytes were added to this repository or its distribution.

MIT-licensed source lineage

The first Maka cursor renderer was a TypeScript adaptation of trycua/cua's MIT-licensed cursor-overlay, introduced in Maka commit 025d0c628a2162d0a7daf49e97d104c36a4431c6. The fixed upstream commit recorded by Maka was 8c921b2b3bf13494724ead4f0a814d80c56a7e8b.

Later work replaced most of that motion and glyph implementation. The MIT lineage remains relevant to the renderer's introduction and surrounding overlay design, but it is not the source of the independent values above.

Retained Maka-authored or Maka-adjusted behavior

Issue #3293 deliberately preserves the surrounding Maka work:

• the single-segment cubic candidate family in planCursorPath;
• MAX_DESIRED_ARC and DEPARTURE_FAN;
• the raw path-length cost and backwards-arrival score term;
• viewport widening and edge behavior;
• frame-clock ownership and low-frame-rate sub-stepping;
• target-window ordering, semantic element-center presentation, cancellation, completion, and presentation fences;
• Maka's brand palette, click pulse, shadow treatment, and host integration.

The result remains a mixed-lineage Maka implementation: an MIT-derived renderer foundation, Maka-authored product behavior, and a current cursor value set with a public independent derivation.