👾 Open Computer Use – Open-Source Alternative to Codex Computer Use
Swift accessibilityai-agentai-agentsclaude-codecodexcodex-computer-usecomputer-usecomputer-use-agentcross-platformcuadesktop-automationgemini-cligui-automationmacosmcpmodel-context-protocolopen-computer-useopen-computer-use-mcpopenai-codexopencode
Add cursor motion reconstruction assets
ifuryst4a46de3ea7c7
diff --git a/.gitignore b/.gitignoreindex 25b9f4d..960377f 100644--- a/.gitignore+++ b/.gitignore@@ -4,3 +4,5 @@.swiftpm/dist/artifacts/codex-dumps/+__pycache__/+*.pycdiff --git a/docs/exec-plans/active/20260419-official-cursor-motion-reconstruction.md b/docs/exec-plans/active/20260419-official-cursor-motion-reconstruction.mdnew file mode 100644index 0000000..e8e3d34--- /dev/null+++ b/docs/exec-plans/active/20260419-official-cursor-motion-reconstruction.md@@ -0,0 +1,76 @@+# 官方 cursor motion 重建脚本++## 目标++继续逆向官方 `Codex Computer Use.app` 的 cursor motion 实现,在不触碰现有 `StandaloneCursorLab` 的前提下,于 `scripts/` 下落一套独立的二进制分析与 demo 脚本,能够基于指定起终点输出候选路径、采样点和几何测量结果。++## 范围++- 包含:+ - 深挖 `SkyComputerUseService` 中与 `CursorMotionPath`、`CursorMotionPathMeasurement`、`BezierAnimation`、`SpringAnimation` 相关的函数级行为。+ - 在 `scripts/` 下实现独立的 Python 脚本,读取官方 bundled app,提取 motion 类型、常数和候选系数表。+ - 实现一版 binary-guided 的 path sampling / measurement / candidate generation demo,输出 JSON 坐标样本与测量数据。+ - 把新的函数级分析和脚本使用方式沉淀到 `docs/` 与 history。+- 不包含:+ - 不修改 `experiments/StandaloneCursorLab/`。+ - 不把这次脚本直接下沉到主 MCP runtime。+ - 不宣称已经 100% 还原闭源算法中所有 scoring / timing 细节。++## 背景++- 相关文档:+ - `docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-model.md`+ - `docs/references/codex-computer-use-reverse-engineering/software-cursor-overlay.md`+ - `docs/PLANS_GUIDE.md`+- 相关代码路径:+ - `scripts/`+ - `~/.codex/plugins/cache/openai-bundled/computer-use/1.0.750/Codex Computer Use.app`+- 已知约束:+ - 当前仓库已有另一条 session 在持续修改 `experiments/StandaloneCursorLab`,本任务应避免与之冲突。+ - 官方 bundle 为闭源二进制,当前主要依赖 `otool`、`llvm-objdump`、Swift metadata 和常量表恢复。+ - 这次 demo 优先做成纯脚本 / JSON 输出,不依赖 GUI。++## 风险++- 风险:把“直接从函数控制流确认的行为”和“根据系数表做的重建”混为一谈。+- 缓解方式:脚本、文档和输出里显式标注 `confirmed_from_binary` 与 `reconstructed`.++- 风险:路径生成虽然已经 lift 到字段级,但仍可能把调用前那层 runtime bounds 发现和真正的 timing 绑定误写成“已完全恢复”。+- 缓解方式:把 `0x10005fd98` 的候选几何、`0x10005fa84` 的 bounds 预处理、以及 duration / animation descriptor 三部分分开标注。++- 风险:动到现有实验目录或 Package target,和另一条 session 发生冲突。+- 缓解方式:所有新增代码仅放到新的 `scripts/` 子目录和对应文档。++## 里程碑++1. 函数级逆向收敛。+2. 独立脚本实现。+3. 验证、文档与收尾。++## 验证方式++- 命令:+ - `python3 scripts/cursor-motion-re/reconstruct_cursor_motion.py inspect`+ - `python3 scripts/cursor-motion-re/reconstruct_cursor_motion.py demo --start 100 120 --end 720 380 --bounds 0 0 1280 800 --pretty`+- 手工检查:+ - 对照脚本输出的类型字段、系数表和常量,确认与当前逆向结论一致。+ - 检查路径采样和 measurement 输出是否符合 `CursorMotionPath` / `CursorMotionPathMeasurement` 的函数级分析。+- 观测检查:+ - 确认脚本能在本机默认 bundled app 路径上直接工作。+ - 确认文档中把 exact lift 和 reconstruction 分开表述。++## 进度记录++- [x] 里程碑 1+- [x] 里程碑 2+- [x] 里程碑 3++## 决策记录++- 2026-04-19:这条线不继续改 `StandaloneCursorLab`,而是单独在 `scripts/` 下做纯脚本 demo,避免与另一条 session 冲突。+- 2026-04-19:优先实现已从二进制函数级确认的 path sampling 和 measurement,再在此基础上做 candidate generation reconstruction,而不是反过来直接猜整套参数模型。+- 2026-04-19:`0x100060da0` 已确认 score 公式为 `320 * excessLengthRatio + 140 * angleEnergy + 180 * maxAngle + 18 * totalTurn + 45 * outOfBounds`,并确认“优先选 in-bounds 再取最小 score”的策略;duration 仍保留为未完全恢复。+- 2026-04-19:`0x10005fd98` 已进一步 lift 到字段级,当前脚本能按 bundled binary 生成完整 `20` 条候选,包含两条 base candidate、两段 cubic 的 arched candidate、真实 `CursorMotionPath/Segment` 布局,以及 guide vector `(-0.6946583704589973, 0.7193398003386512)`;runtime bounds 发现与 timing 仍单独保留为未完全恢复。+- 2026-04-19:timing 侧已经确认到真实类型和初始化链:`ComputerUseCursor.CloseEnoughConfiguration(progressThreshold=1.0, distanceThreshold=0.01)`、`ComputerUseCursor.CursorNextInteractionTiming.closeEnough(...)`、`Animation.SpringParameters(response=1.4, dampingFraction=0.9)`、`Animation.AnimationDescriptor.spring(...)`、`Animation.SpringAnimation`、`Animation.VelocityVerletSimulation.Configuration(dt=1/240, idleVelocityThreshold=28800)`,并把 `ComputerUseCursor.Window` 的 animation 状态槽位对回 `cursorMotionProgressAnimation / cursorMotionNextInteractionTimingHandler / cursorMotionCompletionHandler / cursorMotionDidSatisfyNextInteractionTiming`。+- 2026-04-19:`0x100593cfc` / `0x100593f18` / `0x100593404` / `0x100594110` 已经把 `VelocityVerlet` 的 `stiffness`、`drag`、stale-time clamp 和单步更新顺序全部直译出来;当前剩余不确定点不再是数学公式本身,而是 wall-clock duration 的上层调度。+- 2026-04-19:`0x1005761bc` / `0x1005934b0` 已经把 `SpringAnimation` 的 frame update / finished predicate 拆开;能确认 hidden self `0x68 / 0x70` 两个 buffer、threshold-square gate、`0.01` float literal 广播和 exact-zero gate,但 `0x68 / 0x70` 对应 `_value / _targetValue` 仍按 inference 标注。diff --git a/docs/exec-plans/completed/20260419-overlay-official-cursor-motion-alignment.md b/docs/exec-plans/completed/20260419-overlay-official-cursor-motion-alignment.mdnew file mode 100644index 0000000..7c4e60f--- /dev/null+++ b/docs/exec-plans/completed/20260419-overlay-official-cursor-motion-alignment.md@@ -0,0 +1,70 @@+# 主线 overlay 对齐官方 cursor motion++## 目标++把主线 `packages/OpenComputerUseKit/Sources/OpenComputerUseKit/SoftwareCursorOverlay.swift` 的 cursor move 行为,从当前的近似单段 Bezier + 固定 duration easing,调整为更接近官方 `Codex Computer Use.app` 的两层模型:++- 官方 lift 的 `20` 条候选路径、measurement 和 score 选择。+- 官方 lift 的 `VelocityVerlet` progress 推进与 `closeEnough` 返回时机。++## 范围++- 包含:+ - 在主线 package 中新增独立的 Swift cursor motion 内核。+ - 把 overlay 的 path selection 切到官方 lift 的 `CursorMotionPath` / `Segment` / measurement / score。+ - 把 overlay 的 move timing 切到 binary-backed `VelocityVerlet` progress。+ - 保留当前仓库已有的 target-window 命中优先策略,但把它降为官方候选集合上的 tie-break,而不是继续使用旧的 7 条固定候选。+ - 补单元测试、history 和架构文档。+- 不包含:+ - 不修改 `experiments/StandaloneCursorLab/`。+ - 不把这次变更扩展到 pulse / fog / idle sway 的完整官方 choreography。+ - 不宣称已经恢复官方 `finished` gate 的全部字段语义命名。++## 背景++- 当前主线 overlay 用的是简化版单段 cubic + 固定时长 `easeInOut`。+- 官方 binary 这两天已经确认到:+ - `20` 条候选路径。+ - `CursorMotionPathMeasurement(length, angleChangeEnergy, maxAngleChange, totalTurn, staysInBounds)`。+ - score 公式与 in-bounds 优先策略。+ - `SpringAnimation -> VelocityVerletSimulation` 的 `response=1.4`、`dampingFraction=0.9`、`dt=1/240`、`stiffness` / `drag` 公式和单步更新顺序。+ - `CloseEnoughConfiguration(progressThreshold=1.0, distanceThreshold=0.01)`。++## 风险++- 风险:一口气把当前 overlay 的候选与 timing 都换掉,可能让“窗口命中优先”的现有行为退化。+- 缓解方式:保留现有 target-window hit-test,但把它放到官方候选池上做 tie-break。++- 风险:主线点击调用在 `moveCursor` 结束后立刻执行真实点击,如果直接等到 spring 数值完全静止,体验会变慢。+- 缓解方式:主线 `moveCursor` 对齐官方 `closeEnough` 语义,到达 `progress >= 1` 且 `abs(target - progress) <= 0.01` 时返回。++- 风险:reverse-engineering 里对 `0x1005934b0` 仍有字段命名级不确定性。+- 缓解方式:主线只引入已确认的 path / measurement / `VelocityVerlet` / close-enough 逻辑,不把未证实的 finished 命名伪装成 exact。++## 验证方式++- `swift test`+- 针对 path 模型补单元测试,至少覆盖:+ - `CursorMotionPath` 起终点与 straight fallback。+ - 官方候选数量为 `20`。+ - 参考样例的 best candidate 与逆向脚本一致。+ - spring progress 会在 close-enough gate 返回,并出现端点锁定。++## 进度记录++- [x] 抽出主线可复用 motion 内核+- [x] 切换 overlay 到官方候选 + spring progress+- [x] 文档、history、测试同步完成++## 决策记录++- 2026-04-19:主线 overlay 这次只吃进已 binary-confirmed 的几何与 timing 内核,不等待 `finished` predicate 剩余字段命名完全坐实。+- 2026-04-19:target-window 命中策略保留,但从“旧 7 候选的主选择器”改成“官方候选池之上的 tie-break”。+- 2026-04-19:主线 runtime 直接复用官方 `closeEnough` spring shape,但不把 `1.429166...` 当作真实 wall-clock move duration;实际耗时继续按当前仓库已验证的本地校准公式映射。++## 结果记录++- 已在 `packages/OpenComputerUseKit/Sources/OpenComputerUseKit/CursorMotionModel.swift` 新增主线可复用 motion 内核,包含 `CursorMotionPath`、candidate measurement/score、`VelocityVerlet` progress animator 和官方候选生成逻辑。+- 已在 `packages/OpenComputerUseKit/Sources/OpenComputerUseKit/SoftwareCursorOverlay.swift` 切换到官方候选池选路,并把 target-window 命中采样降级为 tie-break。+- 已在 `packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift` 补充候选数量、参考样例 best candidate 和 `closeEnoughTime` 回归测试。+- 已执行 `swift test`,当前通过。diff --git a/docs/exec-plans/completed/20260419-visual-cursor-pose-dynamics-refactor.md b/docs/exec-plans/completed/20260419-visual-cursor-pose-dynamics-refactor.mdnew file mode 100644index 0000000..7ad1665--- /dev/null+++ b/docs/exec-plans/completed/20260419-visual-cursor-pose-dynamics-refactor.md@@ -0,0 +1,77 @@+# 主线 visual cursor 姿态动力学重构++## 目标++把主线 `SoftwareCursorOverlay` 从“path sample 直接驱动 tip + tangent 直接驱动角度”的单层模型,重构成更接近官方结构的双层模型:路径层只负责给出 `currentInterpolatedOrigin` 风格的运动目标,真正显示出来的 tip/velocity/angle/fog 由独立的 visual dynamics 状态持续推进。++## 范围++- 包含:+ - 在 `OpenComputerUseKit` 中引入可复用的 visual cursor dynamics 内核。+ - 删除当前临时补丁式的 `terminal settle`,改成贯穿 move / pulse / idle 的统一 2D 状态。+ - 调整 `SoftwareCursorView` 的渲染输入,增加 velocity-driven 的姿态与 fog/offset 表现。+ - 补单元测试、架构文档和 history。+- 不包含:+ - 不修改 `experiments/StandaloneCursorLab/`。+ - 不宣称已经精确恢复官方 `FogCursorViewModel` 的全部字段公式。+ - 不把这次改动扩展到完整 host choreography 或加载态 token。++## 背景++- 相关文档:+ - `docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-model.md`+ - `docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-reconstruction.md`+ - `docs/references/codex-computer-use-reverse-engineering/software-cursor-overlay.md`+- 相关代码路径:+ - `packages/OpenComputerUseKit/Sources/OpenComputerUseKit/CursorMotionModel.swift`+ - `packages/OpenComputerUseKit/Sources/OpenComputerUseKit/SoftwareCursorOverlay.swift`+- 已知约束:+ - 另一条 session 仍在推进 `StandaloneCursorLab`,这次不能去碰实验 target。+ - `CursorMotionPath.sample(progress)` 的 endpoint clamp 已经 binary-confirmed。+ - `Style.velocityX / velocityY / angle`、`currentInterpolatedOrigin`、`FogCursorViewModel._velocityX / _velocityY / _angle`、`CursorView._animatedAngleOffsetDegrees` 这些状态存在,但还没有完整公式级 lift。++## 风险++- 风险:这次改动会碰 overlay 的核心更新循环,容易把 click/pulse/idle 串联关系打断。+- 缓解方式:把 visual dynamics 做成纯 Swift 内核,优先用单元测试覆盖“跟随、过冲、角度滞后、静止回稳”。++- 风险:如果 visual tip 的独立动力学参数过强,真实点击点和视觉 cursor 会偏太远。+- 缓解方式:约束 tip lag/fog offset 上限,把 click/pulse 期间的目标位置固定在真实点击点周围。++- 风险:当前 reverse-engineering 还没恢复官方所有 render anchor 公式。+- 缓解方式:这次只引入有明确证据支撑的状态分层,不伪装成 exact 复刻;未知部分保留为仓库内可调但有测试保护的近似实现。++## 里程碑++1. 确定主线要拆出来的 visual dynamics 状态与渲染输入。+2. 在 `OpenComputerUseKit` 中完成重构并替换 `terminal settle`。+3. 补测试、文档、history,并完成验证。++## 验证方式++- 命令:+ - `swift test`+- 手工检查:+ - move 结束后不再出现明显 endpoint-pivot 翻转。+ - 横向或斜向进入终点时,visible tip 能出现自然的小幅前冲/回弧。+ - pulse / idle 能继承同一套姿态状态,而不是重新归零。+- 观测检查:+ - 主线代码里不再依赖临时 `terminal settle` 补丁驱动收尾。++## 进度记录++- [x] 里程碑 1+- [x] 里程碑 2+- [x] 里程碑 3++## 决策记录++- 2026-04-19:这次不继续强化 endpoint 附近的特判补丁,而是直接切到“路径目标 + 独立 visual dynamics”双层模型,原因是当前问题已经来自状态分层缺失,不再是单条路径候选选择错误。+- 2026-04-19:主线 visual cursor 这次不伪装成 exact 复刻 `FogCursorViewModel` 公式,而是先把已经有二进制证据支撑的状态分层落到主 runtime:`currentInterpolatedOrigin` 风格目标点、独立 `velocity/angle`、以及 velocity-driven fog/body lag。++## 结果记录++- 已在 `OpenComputerUseKit` 中新增 `CursorVisualDynamicsConfiguration`、`CursorVisualDynamicsState`、`CursorVisualRenderState` 和 `CursorVisualDynamicsAnimator`,作为主线 overlay 的可复用 visual dynamics 内核。+- 已删除主线 overlay 的临时 `terminal settle` 路径,`move`、`pulse`、`idle` 现在统一改为持续推进同一套 2D visual dynamics 状态。+- 已把 `SoftwareCursorView` 的输入从单一 `rotation` 扩展到 `rotation + cursorBodyOffset + fogOffset + fogScale`,让速度滞后和 fog 能体现在主 runtime 画面上。+- 已补充 visual dynamics 的回归测试,并执行 `swift test` 通过。diff --git a/docs/histories/2026-04/20260419-1333-add-binary-guided-cursor-motion-re-demo.md b/docs/histories/2026-04/20260419-1333-add-binary-guided-cursor-motion-re-demo.mdnew file mode 100644index 0000000..7b4f71f--- /dev/null+++ b/docs/histories/2026-04/20260419-1333-add-binary-guided-cursor-motion-re-demo.md@@ -0,0 +1,36 @@+## [2026-04-19 13:33] | Task: 新增独立 cursor motion 逆向 demo++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `gpt-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 继续深挖官方 cursor motion,并在独立目录里做一个不和 `StandaloneCursorLab` 冲突的 demo,最好能指定起终点输出路线和速度相关采样。++### 🛠 Changes Overview+**Scope:** `scripts/cursor-motion-re/`、`docs/exec-plans/active/`、`docs/references/`、`docs/histories/`++**Key Actions:**+- **[新增独立执行计划]**: 在 `docs/exec-plans/active/` 下为这条逆向 + 脚本化 demo 线路单独建 plan,并显式声明不触碰 `StandaloneCursorLab`。+- **[实现脚本化逆向工具]**: 新增 `scripts/cursor-motion-re/`,用纯 Python 实现最小 Mach-O section 解析、Swift field metadata 恢复和官方 binary 中的常量 / 候选系数表提取。+- **[实现 binary-guided demo]**: 新增 CLI,支持 `inspect` 和 `demo` 两个子命令;`demo` 可对指定起终点生成候选路径、measurement 和采样点 JSON,并默认输出精简版 `candidate_summaries + chosen_candidate`。+- **[确认候选打分与选择]**: 把 `0x100060da0` 中的 score 公式和 “prefer in-bounds, then choose minimum score” 策略回填进脚本输出,不再沿用之前的猜测权重。+- **[继续 lift 候选几何]**: 把 `0x10005fd98` 里 `CursorMotionPath/Segment` 的真实字段布局、guide vector、两条 base candidate、`3 x 3 x 2` arched candidate 以及 `20` 条候选总数直接落到脚本里,不再停留在“缺第二条 base candidate”的状态。+- **[补齐 timing 实证]**: 从 Swift metadata、type descriptor 和函数链继续下钻,确认 `ComputerUseCursor.CloseEnoughConfiguration`、`CursorNextInteractionTiming`、`Animation.SpringParameters`、`AnimationDescriptor`、`Transaction`、`VelocityVerletSimulation.Configuration` 的真实字段关系,并把 cursor path animation 的 `response=1.4`、`dampingFraction=0.9`、`dt=1/240`、`idleVelocityThreshold=28800` 和 `ComputerUseCursor.Window` 的 animation 状态槽位写回脚本与文档。+- **[补平 VelocityVerlet 数学公式]**: 继续深挖 `0x100593cfc`、`0x100593f18`、`0x100593404`、`0x100594110`,把 `stiffness = min((2π / response)^2, 28800)`、`drag = 2 * dampingFraction * sqrt(stiffness)`、stale-time clamp,以及单步 `VelocityVerlet` 更新顺序全部落进独立脚本。+- **[恢复 SpringAnimation finished predicate]**: 继续拆 `0x1005761bc` / `0x1005934b0`,确认 frame update 会在推进 simulation 后跑 finished predicate,并记录 threshold-square gate、`0.01` float literal 广播、exact-zero 双向比较,以及“端点先锁住、finished 仍可能稍后才成立”的谨慎 inference。+- **[固化函数级分析]**: 新增 `software-cursor-motion-reconstruction.md`,把已确认的 `sample(progress)`、`CursorMotionPathMeasurement`、候选 score 公式和候选总量形状单独沉淀。+- **[同步目录导航]**: 更新 reverse-engineering README,把新的 reconstruction 文档纳入索引。++### 🧠 Design Intent (Why)+当前已有另一条 session 在持续推进 `StandaloneCursorLab`,直接继续改实验 target 风险太高。这次改成 `scripts/` 下的独立脚本,一方面能继续深挖闭源实现,另一方面也能把“已确认”和“仍在 reconstruction”的部分明确分层,便于后续逐步替换。++### 📁 Files Modified+- `docs/exec-plans/active/20260419-official-cursor-motion-reconstruction.md`+- `docs/references/codex-computer-use-reverse-engineering/README.md`+- `docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-reconstruction.md`+- `docs/histories/2026-04/20260419-1333-add-binary-guided-cursor-motion-re-demo.md`+- `scripts/cursor-motion-re/README.md`+- `scripts/cursor-motion-re/official_cursor_motion.py`+- `scripts/cursor-motion-re/reconstruct_cursor_motion.py`diff --git a/docs/histories/2026-04/20260419-2010-align-overlay-motion-with-official-model.md b/docs/histories/2026-04/20260419-2010-align-overlay-motion-with-official-model.mdnew file mode 100644index 0000000..91bcef0--- /dev/null+++ b/docs/histories/2026-04/20260419-2010-align-overlay-motion-with-official-model.md@@ -0,0 +1,31 @@+## [2026-04-19 20:10] | Task: 主线 overlay 对齐官方 cursor motion++### 🤖 Execution Context+* **Agent ID**: `codex`+* **Base Model**: `gpt-5`+* **Runtime**: `Codex CLI`++### 📥 User Query+> 基于已有的逆向分析,调整当前主实现,让 visual cursor 的路径和速度表现尽量接近官方效果。++### 🛠 Changes Overview+**Scope:** `packages/OpenComputerUseKit/`、`docs/exec-plans/`、`docs/ARCHITECTURE.md`、`docs/histories/`++**Key Actions:**+- **[新增主线 motion 内核]**: 在 `OpenComputerUseKit` 中新增独立 `CursorMotionModel.swift`,把已确认的 `CursorMotionPath`、`CursorMotionPathMeasurement`、`20` 条官方候选、score 选择和 `VelocityVerlet` spring progress 正式接入主线 package。+- **[替换 overlay move 实现]**: 把 `SoftwareCursorOverlay` 的移动逻辑从旧的单段 cubic + `easeInOut` 切到官方候选池 + spring progress;同时保留现有 target-window 命中策略,但仅作为官方候选集合上的 tie-break。+- **[重构 visual dynamics 层]**: 删除补丁式 `terminal settle`,把主线 overlay 改成“路径层给目标点、visual dynamics 持续推进 visible tip / angle / fog”的双层模型,并让 move / pulse / idle 共用同一套状态。+- **[补齐验证与文档]**: 新增主线单元测试覆盖候选总数、参考样例 best candidate、`closeEnoughTime`,以及 visual dynamics 的“目标停止后 visible tip 继续过冲、角度短暂保留惯性后回稳”行为,并同步更新架构文档与 execution plan 状态。+- **[修正 heading/offset 分层]**: 后续又根据二进制里 `SoftwareCursorStyle.angle` 和 `CursorView._animatedAngleOffsetDegrees` 的分层证据,修正了主线和 standalone lab 的姿态模型,不再把主 heading 跟随错误压成只剩小幅 wiggle。++### 🧠 Design Intent (Why)+这次不是继续做实验 demo,而是把已经 binary-confirmed 的几何与 spring 形状真正落到主 runtime 里,缩小和官方视觉行为的偏差。后续又发现主线差异已经不再主要来自路径候选,而是来自缺少独立的姿态/渲染状态层,所以实现从“末端特判补丁”进一步升级成“路径目标 + visual dynamics”双层模型。另一方面,官方 transaction-level 的真实时长映射还没完全恢复,所以最终 wall-clock duration 继续保留本地校准,避免把动画直接拉慢到失真。++### 📁 Files Modified+- `packages/OpenComputerUseKit/Sources/OpenComputerUseKit/CursorMotionModel.swift`+- `packages/OpenComputerUseKit/Sources/OpenComputerUseKit/SoftwareCursorOverlay.swift`+- `packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift`+- `docs/ARCHITECTURE.md`+- `docs/exec-plans/completed/20260419-overlay-official-cursor-motion-alignment.md`+- `docs/exec-plans/completed/20260419-visual-cursor-pose-dynamics-refactor.md`+- `docs/histories/2026-04/20260419-2010-align-overlay-motion-with-official-model.md`diff --git a/docs/references/codex-computer-use-reverse-engineering/README.md b/docs/references/codex-computer-use-reverse-engineering/README.mdindex 4b731b5..8190234 100644--- a/docs/references/codex-computer-use-reverse-engineering/README.md+++ b/docs/references/codex-computer-use-reverse-engineering/README.md@@ -19,7 +19,7 @@- `software-cursor-motion-model.md`- 结合视频样本、官方字符串和当前开源实现,对 cursor motion 参数模型的推断。- `software-cursor-motion-reconstruction.md`- - 继续下钻到函数级后,对 `CursorMotionPath.sample(progress)`、`CursorMotionPathMeasurement` 和候选路径枚举线索的重建说明。+ - 继续下钻到函数级后,对 `CursorMotionPath.sample(progress)`、`CursorMotionPathMeasurement`、`CursorMotionPath/Segment` 布局、20 条候选几何、score 公式、in-bounds 优先选择策略,以及 `SpringAnimation -> VelocityVerletSimulation` timing 链、finished predicate 和 endpoint-lock 观测的重建说明。- `permission-onboarding.md`- 对 Accessibility / Screen Recording 权限引导和 System Settings accessory window 的分析。- `assets/README.md`diff --git a/docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-reconstruction.md b/docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-reconstruction.mdnew file mode 100644index 0000000..92d39cb--- /dev/null+++ b/docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-reconstruction.md@@ -0,0 +1,518 @@+# Software Cursor Motion Reconstruction++这份文档比 `software-cursor-motion-model.md` 更窄,专门记录这次继续往函数级推进后,已经能直接从 `SkyComputerUseService` 控制流里确认下来的实现细节,以及哪些部分仍然只是 reconstruction。++## 结论概览++这次最有价值的 4 个结论是:++- `CursorMotionPath.sample(progress)` 已经基本能按函数级行为重建出来。+- `CursorMotionPathMeasurement` 的 5 个输出字段已经能对应到采样循环和角度累计逻辑。+- `CursorMotionPath` / `Segment` 的真实字段布局已经能和写字段指令一一对上。+- 候选路径筛选不再只是“可能有一组权重”的推测,现在已经能确认 score 公式、in-bounds 优先策略,以及 `20` 条候选的几何生成形状。++这轮继续往 timing 侧推进之后,又补上了 4 个可以直接落到二进制实体上的结论:++- cursor path animation 不是抽象的 easing 黑盒,而是 `Animation.SpringAnimation` 驱动的一条进度动画链。+- `closeEnough` 相关类型和字段关系已经能从 Swift metadata 直接对上。+- spring 路径内部确实会落到 `Animation.VelocityVerletSimulation.Configuration`,并且 `stiffness / drag`、`dt = 1/240`、`VelocityVerlet` 单步更新顺序现在都能直接写出来。+- `ComputerUseCursor.Window` 里承载 cursor animation 状态的几个槽位,已经能和主控制流中的写字段顺序对上。++## 已确认的函数级行为++### 1. `CursorMotionPath.sample(progress)` 是“按 segment 选段,再做 cubic 求值”++函数地址:`0x10005c1dc`++从控制流可以确认:++1. 输入 `progress` 会先被 clamp 到 `0...1`。+2. 根据 `segments.count` 把全局 `progress` 映射到具体 `segmentIndex` 和 segment 内局部 `t`。+3. 如果 `progress >= 1`,直接落到最后一段、局部 `t = 1`。+4. 每段都按标准 cubic Bezier 公式求点:+ - 起点+ - `control1`+ - `control2`+ - 终点+5. 函数末尾还会调用一个辅助函数,返回额外两维量,结合调用点看更像是 tangent / orientation 相关数据。++这说明官方 path sampling 这层不是黑盒 easing,而是标准分段 cubic。++### 2. `CursorMotionPathMeasurement` 是固定步数采样,不是解析闭式公式++函数地址:`0x100060ac0`++能直接确认的行为:++- 它会遍历 `segments`。+- 每段固定按 `24` 个采样点推进。+- 只在相邻点距离大于 `0.01` 时才把这一小段当成有效步长。+- 对每个有效步长:+ - 累加 `length`+ - 用 `atan2(dy, dx)` 算 heading+ - 对相邻 heading 做 `[-pi, pi]` unwrap+ - 累加角度变化平方+ - 记录最大绝对转角+ - 累加总绝对转角++从寄存器和最终写回顺序可以把 5 个字段对应出来:++- `length`+- `angleChangeEnergy`+- `maxAngleChange`+- `totalTurn`+- `staysInBounds`++### 3. `staysInBounds` 是 measurement 阶段顺手维护的布尔值++这部分不是独立后处理。++`0x100060ac0` 在采样循环里会持续维护一个布尔标记,只有当所有关键采样点都还满足边界约束时,这个字段才保持 `true`。++当前最保守的解释是:++- 如果调用方给了 bounds,measurement 会把采样点逐个做包含性校验。+- 实现里能看到固定的 `20.0` 边距参与判断,因此不是严格贴边的裸矩形判断。++## 新确认的候选选择逻辑++### 0. `CursorMotionPath` 和 `Segment` 的内存布局已经钉住++结合 Swift field metadata 和 `0x10005fd98` / `0x10005c1dc` 的写字段、读字段顺序,可以把这两个关键结构的布局对上:++- `CursorMotionPath`+ - `start`: `0x00`+ - `end`: `0x10`+ - `startControl`: `0x20`+ - `arc`: `0x30`+ - `arcIn`: `0x48`+ - `arcOut`: `0x60`+ - `endControl`: `0x78`+ - `segments`: `0x88`+- `Segment`+ - `end`: `0x00`+ - `control1`: `0x10`+ - `control2`: `0x20`++`0x10005c1dc` 里对 `Segment` 的读取顺序也能说明:++- segment 的起点不是单独存的。+- 第一段起点来自 `CursorMotionPath.start`。+- 后续段的起点来自上一段的 `Segment.end`。+- `Segment.end / control1 / control2` 都是 cubic 采样时直接参与公式的绝对点。++### 1. 候选总量不是 18,而是 20++函数地址:`0x10005fd98`++这次把候选生成函数继续拆平后,可以确认:++- 有两张系数表:+ - `tableA = [0.55, 0.8, 1.05]`+ - `tableB = [0.65, 1.0, 1.35]`+- 双层循环枚举 `3 x 3` 组组合。+- 每组组合会再走左右镜像两条分支。+- 在进入双层循环前,函数还会先构造两条 base candidate。++因此总候选量不是之前保守写法里的“18 条左右”,而是更接近:++- `2` 条 base candidate+- `3 x 3 x 2 = 18` 条镜像候选+- 合计 `20` 条++### 2. 候选生成已经能落到字段级几何,不只是 table 级猜测++仍然是 `0x10005fd98`。++现在能直接确认:++- 有一组 guide 相关系数会先经 `swift_once` 初始化到全局:+ - `(-0.6946583704589973, 0.7193398003386512)`+- 这组数值本身是 confirmed;但后续对照官方视频后,直接把它当成固定屏幕坐标 guide vector 会在部分象限下产生明显不符的扭曲回环。当前 reconstruction 更保守的做法是:把它当成 path-local basis 里的系数对,再投到世界坐标去生成 candidate 几何。这一层“local-basis projection”目前仍属于 reconstruction-level inference,不是已经由反汇编逐指令坐实的结论。+- path builder 会先构造两条 base candidate:+ - `base-full-guide`+ - `base-scaled-guide`+- 再围绕两张系数表构造 `18` 条两段 cubic 的 arched candidate。++能直接确认的主尺度包括:++- `distance * 0.41960295031576633`+- `distance * 0.9`+- `distance * 0.15`+- `distance * 0.2765523188064277`+- `distance * 0.5783555327868779`+- `clippedTravel * 0.65`++其中有一条之前写得过于粗糙的结论需要修正:++- `arcExtent` 仍然可以安全写成:++```text+arcExtent = clamp(distance * 0.5783555327868779, 38, 440)+```++- 但 `handleExtent` 不是简单的 `clamp(..., 50, 520)`,而是这版 bundled binary 里的分段逻辑:++```text+rawHandle = distance * 0.2765523188064277++if rawHandle < 50:+ handleExtent = 50+else if rawHandle < 640:+ handleExtent = rawHandle+else:+ handleExtent = 520+```++在这组 guide 系数原始存储满足 `x < 0, y > 0` 的前提下,base candidate 的 guide travel 也能从原始分支树化简成这组 piecewise:++```text+startExtent =+ 48 if distance * 0.41960295031576633 < 48+ distance * 0.41960295031576633 if distance * 0.41960295031576633 < 640+ 640 if distance * 0.15 < 640+ 640 otherwise++endExtent =+ 48 if distance * 0.41960295031576633 < 48+ distance * 0.9+ if distance * 0.41960295031576633 < 640+ 48 if distance * 0.15 < 640+ 640 otherwise+```++再叠加 bounds clipping 后,会得到:++- `fullStartControl = start + guide * startExtent`+- `fullEndControl = end - guide * endExtent`+- `scaledStartControl = start + guide * (startExtent * 0.65 after clipping)`+- `scaledEndControl = end - guide * (endExtent * 0.65 after clipping)`++镜像候选也已经能落成具体几何:++- 先用 midpoint、signed normal、`tableA` 和 `handleExtent` 算 arc anchor。+- 再用 `tableB`、`arcExtent` 和一条由 `(dx, arcExtent)` 归一化得到的 forward vector 算 `arcIn / arcOut`。+- 每条 arched candidate 是两段 cubic:+ - 第一段:`start -> arc`+ - 第二段:`arc -> end`++### 3. 评分公式已经可以直接写出来++函数地址:`0x100060da0`++这次最重要的推进,是把 candidate measurement 之后的 score 组合方式拆出来了。++对每条候选路径,函数会先算:++- `directDistance = max(distance(start, end), 1)`+- `excessLengthRatio = max(length / directDistance - 1, 0)`++然后 score 为:++```text+score =+ 320 * excessLengthRatio+ + 140 * angleChangeEnergy+ + 180 * maxAngleChange+ + 18 * totalTurn+ + (staysInBounds ? 0 : 45)+```++这说明官方筛选逻辑明确偏好:++- 不要比直线长太多+- 不要有太大的角度抖动+- 不要有单次过猛的转向+- 不要有累计转向过多+- 如果候选跑出 bounds,直接加固定 penalty++### 4. 选择策略是“先保 in-bounds,再比 score”++`0x100060da0` 在算完所有候选的 measurement 和 score 之后,不是直接对整批取最小值。++它会先做一遍过滤:++- 如果存在 `staysInBounds == true` 的候选,只在这批 in-bounds 候选里取最小 score。+- 只有当没有任何 in-bounds 候选时,才会回退到全体候选里取最小 score。++这点对外观很重要,因为它解释了为什么官方路径看上去既“俏皮”又不容易穿窗体 / 越界。++## 新确认的 timing / animation 链++### 1. `CloseEnoughConfiguration` / `CursorNextInteractionTiming` 已经能落到真实嵌套类型++Swift metadata 里已经能直接恢复出这组父子关系:++- `ComputerUseCursor.CloseEnoughConfiguration`+ - `progressThreshold`+ - `distanceThreshold`+- `ComputerUseCursor.CursorNextInteractionTiming`+ - `closeEnough`+ - `finished`++这说明之前看到的 `1.0` 和 `0.01` 不是散落常量,而是已经能映射到真实字段:++- `progressThreshold = 1.0`+- `distanceThreshold = 0.01`++从 `0x10005be24..0x10005be3c` 的写栈顺序看,这两项正是 cursor path animation 在组 `next interaction timing` 时使用的 close-enough 配置。++### 2. `AnimationDescriptor` / `SpringParameters` / `Transaction` 的真实字段也已经恢复++同样通过 `__swift5_types` + `__swift5_fieldmd`,已经能确认:++- `Animation.AnimationDescriptor`+ - `bezier`+ - `spring`+- `Animation.SpringParameters`+ - `response`+ - `dampingFraction`+- `Animation.Transaction`+ - `priority`+ - `delay`+ - `completion`+ - `id`+ - `driverSource`+ - `descriptor`++这里最关键的是:++- cursor path 主链里用到的 spring 常量已经能直接确认是+ - `response = 1.4`+ - `dampingFraction = 0.9`+- 二进制同时确实导入了+ - `SwiftUI.Animation.spring(response:dampingFraction:blendDuration:)`++因此“官方 cursor path animation 用的是 spring 而不是自定义 bezier duration”这点已经是 binary-backed 结论,不再只是字符串级猜测。++### 3. `SpringAnimation` 会继续落到 `VelocityVerletSimulation.Configuration`++新的关键链路是:++- `Animation.SpringAnimation` metadata accessor:`0x1005768c4`+- allocating wrapper:`0x100576790`+- designated init 主体:`0x10057652c`+- `Animation.VelocityVerletSimulation.Configuration` metadata accessor:`0x100591fd4`+- `Configuration` 初始化主链:`0x100592f20`+- config completion:`0x100593cfc`++这条链路说明:++- cursor path animation 的“速度”底层不是简单的定长采样。+- 它通过 spring 参数继续构造成 `VelocityVerletSimulation`。++而 `Animation.VelocityVerletSimulation.Configuration` 的字段已经能直接恢复为:++- `response`+- `stiffness`+- `drag`+- `dt`+- `idleVelocityThreshold`++目前能直接确认的数值和公式有:++- `dt = 1/240 = 0.004166666666666667`+- `idleVelocityThreshold = 28800.0`+- `0x100593cfc`+ - `stiffness = min(response > 0 ? (2π / response)^2 : +inf, 28800.0)`+- `0x100593f18`+ - `drag = 2 * dampingFraction * sqrt(stiffness)`+- `0x100593404`+ - 如果 `targetTime - time > 1.0`,先把 `time` 钳到 `targetTime - 1/60`+ - 然后按 `dt` 循环推进,直到 `time >= targetTime`+- `0x100594110`+ - `velocityHalf = velocity + force * (dt / 2)`+ - `current = current + velocityHalf * dt`+ - `force = stiffness * (target - current) + (-drag) * velocityHalf`+ - `velocity = velocityHalf + force * (dt / 2)`++因此现在已经可以明确写成:++- 这条链路是 binary-backed 的 `VelocityVerlet` 弹簧仿真,而不是模糊的“某种 spring-like easing”。+- `stiffness / drag` 这两个核心量已经不再停留在“存在但公式未抄平”的状态。++### 4. `SpringAnimation` 的 frame update / finished predicate 已经基本拆开++这里最关键的两个函数是:++- `0x1005761bc`+- `0x1005934b0`++`0x1005761bc` 现在已经能确认成这条控制链:++- 通过 `0x1005730bc` 从 hidden self 的 `0x68` 槽位拷一个 current-value-like buffer。+- 通过 `0x100573390` 从 hidden self 的 `0x70` 槽位拷一个 target-value-like buffer。+- 调 `0x100593404` 推进 spring simulation。+- 调 `0x1005934b0` 计算 finished predicate。+- finished 时走 optional `nil` 返回;未 finished 时走 optional `some(updatedValue)` 返回。++`0x1005934b0` 当前已经能确认两段 gate:++- 第一段 gate:+ - 从 hidden self 再取两个标量槽位。+ - 先做 `Swift.max(slotA, slotB)`。+ - 再把另一个阈值字段平方后比较。+ - 只有 `max(slotA, slotB) <= threshold^2` 才会继续往下跑。+- 第二段 gate:+ - 明确构造了一个 `0.01` float literal。+ - 用 `SIMDStorage` 把它广播成和 animatable value 同标量数的向量。+ - 后面会跑一串逐分量乘法、减法和类型转换。+ - 末尾不是用近似比较,而是把一个差值派生标量 `A` 做成:+ - `A > 0`+ - `0 > A`+ - 只有两边都不成立时,才算 finished。++需要明确区分 confirmed 与 inference:++- 已确认:+ - `0x1005761bc` 的 optional `nil / some(updatedValue)` 分支结构+ - `0x1005934b0` 的 threshold-square gate+ - `0.01` float literal 广播+ - 双向比较实现 exact-zero gate+- 仍然是 inference:+ - `0x68 / 0x70` 很可能就是 `InterpolatableAnimation._value / _targetValue`+ - `0x1005934b0` 里 metadata `+0x30` 取到的阈值字段,很可能就是 `idleVelocityThreshold`++### 5. 可见几何会先锁到终点,这点现在已经能从几段二进制证据拼起来++这里要把“confirmed”与“组合推断”分开写:++- 已确认:+ - `CursorMotionPath.sample(progress)` 会把 `progress` clamp 到 `0...1`+ - `SpringAnimation` 的 progress 由上面的 `VelocityVerlet` 链驱动+ - `0x1005761bc` 的 finished 返回是单独由 `0x1005934b0` 控的+- 因此可以谨慎推出:+ - 一旦 raw spring progress 首次 `>= 1.0`,可见几何位置就会被 clamp 到 path endpoint+ - 这件事可能早于 raw spring state 在数值上完全静止++这也是为什么新的独立 demo 里要同时输出:++- `raw_progress_first_ge_target_time`+- `first_endpoint_lock_time`+- `close_enough_first_time`++在当前样本里,通常能直接看到:++- raw progress 已经越过 `1.0`+- 几何点已经停在终点+- 但 raw spring velocity / force 仍然非零++这条“端点先锁住、finished 还未必立刻返回”的结论,目前仍然按 inference 标注,因为它依赖把 `sample(progress)` 的 clamp、`VelocityVerlet` 的原始状态、以及 `0x1005934b0` 的 finished gate 三块证据拼在一起。++### 6. `ComputerUseCursor.Window` 的 animation 状态槽位已经能对上主控制流写入++`ComputerUseCursor.Window` 的真实字段顺序现在也能恢复:++- `style`+- `appMonitor`+- `wantsToBeVisible`+- `cursorMotionProgressAnimation`+- `cursorMotionNextInteractionTimingHandler`+- `cursorMotionCompletionHandler`+- `cursorMotionDidSatisfyNextInteractionTiming`+- `currentInterpolatedOrigin`+- `useOverlayWindowLevel`+- `correspondingWindowID`++结合 `0x10005be94..0x10005bf18` 的一串连续写字段,可以把 cursor move 动画主链里这几个写入直接对应到:++- `cursorMotionProgressAnimation`+- `cursorMotionNextInteractionTimingHandler`+- `cursorMotionCompletionHandler`+- `cursorMotionDidSatisfyNextInteractionTiming`++这意味着顶层控制流已经不只是“某个匿名对象在写几个槽位”,而是可以对回真实 `ComputerUseCursor.Window` 内部状态。++### 7. `SpringParameters` 区域还有一个已确认的 piecewise remap helper++`0x1005879a4` 位于 `Animation.SpringParameters` 一侧,它会把第二个输入量做如下 piecewise 映射:++```text+if x <= -1:+ mapped = +inf+else if x < 0:+ mapped = 1 / (1 + x)+else if x == 0:+ mapped = 0+else:+ mapped = 1 - min(x, 1)+```++这说明 bundled binary 里确实存在一层 spring 参数规整逻辑,能够把一个 `[-1, 1]` 附近的量映射到阻尼相关参数。++需要强调的是:++- cursor path move 这条链路里当前已经直接确认使用的是 `response = 1.4`、`dampingFraction = 0.9`。+- 上面这个 remap helper 是同一套 animation 库里的另一条可复用 spring 参数路径,不代表 cursor move 主链一定先经过这个 remap。++## 仍在重建中的部分++### 1. 自动 bounds 发现还没有直接 lift 到脚本输入层++主 app 在调用 `0x10005fd98` 前,还会先走一次 `0x10005fa84`:++- 从运行时屏幕 / 区域列表里挑出同时覆盖起点和终点的 bounds。+- 如果找不到这样的单个 rect,再对候选 rect 做 union。++当前脚本为了保持独立、可重复,要求调用方直接传 `--bounds`,没有把这段 runtime screen discovery 接进来。++### 2. duration / 真正的时间速度还没有完全恢复++目前已经能稳定输出:++- path 采样点+- tangent+- `speed_units_per_progress`++但这里的“speed”仍然是几何速度,即:++- 相邻等 progress 采样点之间的距离++真正的时间速度还缺少一层:++- progress 随时间如何推进+- `BezierParameters.duration` / `AnimationDescriptor` / `CloseEnoughConfiguration` 在 cursor motion 主链路里的最终接法++也就是说,现在已经能比较可靠地回答“路线怎么走”,但对“这条路线多快走完”还没有到可以宣称 exact 的程度。++比上一版更进一步的是:++- spring family+- close-enough 阈值+- `response / dampingFraction`+- `VelocityVerletSimulation.Configuration` 的字段+- `stiffness / drag`+- `dt = 1/240`+- `0x1005761bc` / `0x1005934b0` 的 update + finished predicate 控制流++这些已经都能直接从二进制确认。++仍然没有完全 lift 完的,是:++- `Animation.Transaction` 在 cursor move 这条主链里的完整组装顺序+- `0x1005934b0` 第二段里几个泛型临时 buffer 的精确语义命名+- `0x68 / 0x70 -> _value / _targetValue` 的最终符号级证明+- 真实 wall-clock duration 如何从 spring 仿真和 transaction 调度一起体现到最终时间轴上++## 脚本化落点++这次为了避开 `StandaloneCursorLab`,在 `scripts/cursor-motion-re/` 下落了一套独立脚本:++- `reconstruct_cursor_motion.py inspect`+ - 读取官方 binary,输出已恢复的 motion 类型、字段、常量和候选系数表。+- `reconstruct_cursor_motion.py demo`+ - 输入起终点和可选 bounds,输出候选路径、measurement 和采样点。++脚本里明确区分两类实现:++- `confirmed_from_binary`+ - 分段 cubic path sampling+ - `CursorMotionPathMeasurement`+ - 候选系数表提取+ - 候选 score 公式+ - in-bounds 优先选择策略+- `reconstructed`+ - duration / timing model+ - 调用前的 runtime bounds 发现++这样后续继续深挖时,可以逐项把 reconstruction 替换成更准确的函数级实现,而不是整套推倒重来。diff --git a/scripts/cursor-motion-re/README.md b/scripts/cursor-motion-re/README.mdnew file mode 100644index 0000000..2444950--- /dev/null+++ b/scripts/cursor-motion-re/README.md@@ -0,0 +1,66 @@+# Cursor Motion RE Scripts++这个目录承载和官方 `Codex Computer Use.app` cursor motion 逆向相关的独立脚本,不依赖 `StandaloneCursorLab`,也不接入主运行时。++当前脚本优先做两件事:++- 从官方 bundled `SkyComputerUseService` 里提取 motion 相关的 Swift 类型、字段和常量。+- 基于已经从二进制直接确认的 `CursorMotionPath.sample(progress)`、`CursorMotionPathMeasurement`、`CursorMotionPath/Segment` 布局、`0x10005fd98` 候选几何,以及已经坐实的 `SpringAnimation -> VelocityVerletSimulation` timing 证据,输出一版 binary-lifted 的候选路径和分析结果。++## 文件++- `official_cursor_motion.py`+ - 逆向辅助模块,包含最小 Mach-O section 解析、Swift field metadata 恢复、常量表读取,以及独立的 path / measurement / candidate demo 实现。+- `reconstruct_cursor_motion.py`+ - CLI 入口。++## 用法++查看官方 binary 中恢复出的 motion 类型、字段、常量与候选系数表:++```bash+python3 scripts/cursor-motion-re/reconstruct_cursor_motion.py inspect+```++对给定起终点生成候选路径,并输出 JSON:++```bash+python3 scripts/cursor-motion-re/reconstruct_cursor_motion.py demo \+ --start 100 120 \+ --end 720 380 \+ --bounds 0 0 1280 800 \+ --samples 32 \+ --pretty+```++不带 `--bounds` 时,`stays_in_bounds` 会退化为 `true`,只计算几何量。++如需把所有候选的完整 path 和 sample 一次性打出来,再加:++```bash+python3 scripts/cursor-motion-re/reconstruct_cursor_motion.py demo \+ --start 100 120 \+ --end 720 380 \+ --bounds 0 0 1280 800 \+ --samples 32 \+ --include-all-candidates \+ --pretty+```++## 输出说明++- `inspect`:+ - 输出从官方 binary 中恢复出的 motion 相关类型和字段。+ - 输出当前版本 bundled app 中提取出的 data-section 常量、候选系数表,以及从反汇编直接确认的 scoring / layout / piecewise 几何常量。+ - 额外输出 binary-confirmed 的 timing 证据:`CloseEnoughConfiguration` / `CursorNextInteractionTiming` / `SpringParameters` / `AnimationDescriptor` / `Transaction` / `VelocityVerletSimulation.Configuration` 的字段关系,以及 cursor path animation 的 `response=1.4`、`dampingFraction=0.9`、`dt=1/240`、`idleVelocityThreshold=28800`。+ - `VelocityVerlet` 的 `stiffness` / `drag` 公式和单步 `VelocityVerlet` 更新顺序现在已经按二进制直译。+ - 还会附带 `0x1005761bc` / `0x1005934b0` 的 finish predicate 证据块,明确哪些是 confirmed control flow,哪些仍然只是字段命名推断。+- `demo`:+ - 默认输出 `candidate_summaries` 和 `chosen_candidate`,避免一次性打印全部候选采样点。+ - `--include-all-candidates` 会额外输出所有候选的完整控制点、measurement 和采样点。+ - `sample(progress)` 与 `measure_path()` 是从函数控制流直接 lift 出来的实现。+ - candidate score、in-bounds 优先策略、`CursorMotionPath/Segment` 布局,以及 `20` 条候选几何都已经按当前 bundled binary 直译。+ - 时间轴输出会额外标出 `raw_progress_first_ge_target_*`、`first_endpoint_lock_*` 和 `close_enough_first_*`,方便对照 spring progress、可见端点锁定和 close-enough 判定。+ - 当前仍未完全恢复的是 duration / wall-clock timing、`0x1005934b0` 第二段里几个泛型 buffer 的精确语义命名,以及调用前那层 runtime bounds 自动发现。+ - `first_endpoint_lock_*` 依赖一个已确认前提:`sample(progress)` 会 clamp 到 `0...1`;但它和 `SpringAnimation` finished optional-return 的最终联动,当前仍按“多段已确认证据拼接出的 inference”标注。+ - 当前输出的 `speed_units_per_progress` 是几何速度,不是带真实 duration 的时间速度;duration 仍在继续逆向。diff --git a/scripts/cursor-motion-re/official_cursor_motion.py b/scripts/cursor-motion-re/official_cursor_motion.pynew file mode 100644index 0000000..a513ced--- /dev/null+++ b/scripts/cursor-motion-re/official_cursor_motion.py@@ -0,0 +1,1364 @@+from __future__ import annotations++import argparse+import json+import math+import struct+from dataclasses import asdict, dataclass+from pathlib import Path+from typing import Iterable+++DEFAULT_APP_PATH = (+ Path.home()+ / ".codex/plugins/cache/openai-bundled/computer-use/1.0.750/Codex Computer Use.app/Contents/MacOS/SkyComputerUseService"+)++TEXT_BASE_VM = 0x100000000+++@dataclass(frozen=True)+class Section:+ segname: str+ sectname: str+ addr: int+ size: int+ offset: int+++class MachOBinary:+ LC_SEGMENT_64 = 0x19++ def __init__(self, path: Path):+ self.path = path+ self.data = path.read_bytes()+ self.sections = self._parse_sections()++ def _parse_sections(self) -> list[Section]:+ data = self.data+ magic = struct.unpack_from("<I", data, 0)[0]+ if magic != 0xFEEDFACF:+ raise ValueError(f"unsupported Mach-O magic: {magic:#x}")++ _, _, _, _, ncmds, _, _, _ = struct.unpack_from("<IiiIIIII", data, 0)+ offset = 32+ sections: list[Section] = []++ for _ in range(ncmds):+ cmd, cmdsize = struct.unpack_from("<II", data, offset)+ if cmd == self.LC_SEGMENT_64:+ segname_raw = struct.unpack_from("<16s", data, offset + 8)[0]+ segname = segname_raw.split(b"\x00", 1)[0].decode("ascii", "replace")+ nsects = struct.unpack_from("<I", data, offset + 64)[0]+ sect_offset = offset + 72+ for _ in range(nsects):+ sectname_raw, sec_segname_raw = struct.unpack_from("<16s16s", data, sect_offset)+ sectname = sectname_raw.split(b"\x00", 1)[0].decode("ascii", "replace")+ sec_segname = sec_segname_raw.split(b"\x00", 1)[0].decode("ascii", "replace")+ addr, size, fileoff = struct.unpack_from("<QQI", data, sect_offset + 32)+ sections.append(+ Section(+ segname=sec_segname or segname,+ sectname=sectname,+ addr=addr,+ size=size,+ offset=fileoff,+ )+ )+ sect_offset += 80+ offset += cmdsize++ return sections++ def section(self, segname: str, sectname: str) -> Section:+ for section in self.sections:+ if section.segname == segname and section.sectname == sectname:+ return section+ raise KeyError(f"missing section {segname},{sectname}")++ def vm_to_file_offset(self, vmaddr: int) -> int:+ for section in self.sections:+ if section.addr <= vmaddr < section.addr + section.size:+ return section.offset + (vmaddr - section.addr)+ raise KeyError(f"vmaddr {vmaddr:#x} not in any section")++ def read_c_string(self, vmaddr: int) -> str | None:+ try:+ file_offset = self.vm_to_file_offset(vmaddr)+ except KeyError:+ return None+ end = self.data.find(b"\x00", file_offset)+ if end == -1:+ return None+ raw = self.data[file_offset:end]+ try:+ return raw.decode("utf-8", "replace")+ except UnicodeDecodeError:+ return None++ def read_double(self, vmaddr: int) -> float:+ file_offset = self.vm_to_file_offset(vmaddr)+ return struct.unpack_from("<d", self.data, file_offset)[0]+++@dataclass(frozen=True)+class MotionTypeInfo:+ name: str+ kind: int+ fields: list[str]+++def extract_motion_type_fields(binary: MachOBinary) -> list[MotionTypeInfo]:+ reflstr = binary.section("__TEXT", "__swift5_reflstr")+ fieldmd = binary.section("__TEXT", "__swift5_fieldmd")+ types = binary.section("__TEXT", "__swift5_types")+ const_sections = [+ binary.section("__TEXT", "__const"),+ binary.section("__TEXT", "__constg_swiftt"),+ binary.section("__TEXT", "__swift5_typeref"),+ reflstr,+ fieldmd,+ types,+ ]++ def cstr(vmaddr: int) -> str | None:+ for section in const_sections:+ if section.addr <= vmaddr < section.addr + section.size:+ file_offset = section.offset + (vmaddr - section.addr)+ end = binary.data.find(b"\x00", file_offset)+ if end == -1:+ return None+ return binary.data[file_offset:end].decode("utf-8", "replace")+ return None++ field_map: dict[int, tuple[int, list[str]]] = {}+ pos = fieldmd.offset+ end = fieldmd.offset + fieldmd.size+ while pos < end:+ _, _, kind, record_size, field_count = struct.unpack_from("<iiHHI", binary.data, pos)+ desc_vm = fieldmd.addr + (pos - fieldmd.offset)+ field_pos = pos + 16+ fields: list[str] = []+ for _ in range(field_count):+ _, _, field_rel = struct.unpack_from("<Iii", binary.data, field_pos)+ field_name = None+ if field_rel:+ field_name = cstr((fieldmd.addr + (field_pos - fieldmd.offset)) + 8 + field_rel)+ fields.append(field_name or "<unknown>")+ field_pos += record_size+ field_map[desc_vm] = (kind, fields)+ pos = field_pos++ interesting: list[MotionTypeInfo] = []+ seen: set[tuple[str, int]] = set()+ for entry_off in range(0, types.size, 4):+ entry_vm = types.addr + entry_off+ rel = struct.unpack_from("<i", binary.data, types.offset + entry_off)[0]+ desc_vm = entry_vm + rel+ try:+ desc_file = binary.vm_to_file_offset(desc_vm)+ except KeyError:+ continue+ _, _, name_rel, _, field_rel = struct.unpack_from("<IIiii", binary.data, desc_file)+ name = None+ for base in (desc_vm + 8, desc_vm + 12, desc_vm):+ value = cstr(base + name_rel)+ if value and any(ch.isalpha() for ch in value):+ name = value+ break+ if not name:+ continue+ field_desc_vm = desc_vm + 16 + field_rel if field_rel else None+ if field_desc_vm not in field_map:+ continue+ kind, fields = field_map[field_desc_vm]+ needles = (+ "Cursor",+ "Bezier",+ "Spring",+ "Animation",+ "VelocityVerlet",+ "Configuration",+ "DisplayLink",+ "CloseEnough",+ )+ if not any(needle in name for needle in needles):+ continue+ key = (name, field_desc_vm)+ if key in seen:+ continue+ seen.add(key)+ interesting.append(MotionTypeInfo(name=name, kind=kind, fields=fields))++ return sorted(interesting, key=lambda item: item.name)+++EXTRACTED_DOUBLE_CONSTANTS = {+ "distance_scale_primary": 0x100865928,+ "direct_span_scale": 0x100865910,+ "side_bias_scale": 0x100865930,+ "distance_scale_secondary": 0x100865938,+ "distance_scale_tertiary": 0x100865940,+ "minimum_step_distance": 0x100865948,+ "pi": 0x100865950,+ "negative_two_pi": 0x100865958,+ "negative_pi": 0x100865960,+ "positive_two_pi": 0x100865968,+ "nearly_negative_one": 0x100865970,+ "epsilon_01": 0x100865978,+ "score_length_weight": 0x100860C10,+ "score_angle_energy_weight": 0x100860C18,+ "score_max_angle_weight": 0x100860C20,+ "score_total_turn_weight": 0x100860C28,+ "score_in_bounds_factor": 0x100860C30,+ "score_secondary_in_bounds_factor": 0x100860C38,+ "score_shape_weight_a": 0x100860C40,+ "score_shape_weight_b": 0x100860C48,+ "score_shape_anchor": 0x100860C50,+}+++def extract_named_constants(binary: MachOBinary) -> dict[str, float]:+ return {name: binary.read_double(vmaddr) for name, vmaddr in EXTRACTED_DOUBLE_CONSTANTS.items()}+++CONFIRMED_DISASSEMBLY_CONSTANTS = {+ "normalization_epsilon": 0.001,+ "candidate_handle_min": 50.0,+ "candidate_handle_max": 520.0,+ "candidate_arc_min": 38.0,+ "candidate_arc_max": 440.0,+ "score_out_of_bounds_penalty": 45.0,+ "score_excess_length_weight": 320.0,+ "score_angle_energy_weight": 140.0,+ "score_max_angle_weight": 180.0,+ "score_total_turn_weight": 18.0,+}++CONFIRMED_CURSOR_TIMING_CONSTANTS = {+ "close_enough_progress_threshold": 1.0,+ "close_enough_distance_threshold": 0.01,+ "cursor_path_spring_response": 1.4,+ "cursor_path_spring_damping_fraction": 0.9,+ "velocity_verlet_dt": 1.0 / 240.0,+ "velocity_verlet_idle_velocity_threshold": 28800.0,+}++CONFIRMED_TIMING_TYPE_RELATIONSHIPS = {+ "ComputerUseCursor.CloseEnoughConfiguration": {+ "kind": "struct",+ "fields": ["progressThreshold", "distanceThreshold"],+ },+ "ComputerUseCursor.CursorNextInteractionTiming": {+ "kind": "enum",+ "cases": ["closeEnough", "finished"],+ },+ "ComputerUseCursor.Window": {+ "kind": "class",+ "fields": [+ "style",+ "appMonitor",+ "wantsToBeVisible",+ "cursorMotionProgressAnimation",+ "cursorMotionNextInteractionTimingHandler",+ "cursorMotionCompletionHandler",+ "cursorMotionDidSatisfyNextInteractionTiming",+ "currentInterpolatedOrigin",+ "useOverlayWindowLevel",+ "correspondingWindowID",+ ],+ },+ "Animation.SpringParameters": {+ "kind": "struct",+ "fields": ["response", "dampingFraction"],+ },+ "Animation.AnimationDescriptor": {+ "kind": "enum",+ "cases": ["bezier", "spring"],+ },+ "Animation.Transaction": {+ "kind": "struct",+ "fields": ["priority", "delay", "completion", "id", "driverSource", "descriptor"],+ },+ "Animation.VelocityVerletSimulation.Configuration": {+ "kind": "struct",+ "fields": ["response", "stiffness", "drag", "dt", "idleVelocityThreshold"],+ },+}++CONFIRMED_TIMING_PIPELINE = {+ "window_animation_state_slots": {+ "field_order_matches_binary_slot_writes": True,+ "fields_written_in_cursor_path_animation_setup": [+ "cursorMotionProgressAnimation",+ "cursorMotionNextInteractionTimingHandler",+ "cursorMotionCompletionHandler",+ "cursorMotionDidSatisfyNextInteractionTiming",+ ],+ },+ "animation_stack": [+ "ComputerUseCursor.CloseEnoughConfiguration(progressThreshold=1.0, distanceThreshold=0.01)",+ "ComputerUseCursor.CursorNextInteractionTiming.closeEnough(...)",+ "Animation.SpringParameters(response=1.4, dampingFraction=0.9)",+ "Animation.AnimationDescriptor.spring(...)",+ "Animation.SpringAnimation",+ "Animation.VelocityVerletSimulation.Configuration",+ ],+ "binary_functions": {+ "close_enough_metadata_accessor": "0x10005ed78",+ "next_interaction_timing_metadata_accessor": "0x10005ed88",+ "spring_parameters_metadata_accessor": "0x100587990",+ "animation_descriptor_metadata_accessor": "0x100596470",+ "spring_animation_metadata_accessor": "0x1005768c4",+ "spring_animation_allocating_init_wrapper": "0x100576790",+ "spring_animation_designated_init": "0x10057652c",+ "spring_animation_frame_update": "0x1005761bc",+ "spring_animation_value_copy_helper": "0x1005730bc",+ "spring_animation_target_copy_helper": "0x100573390",+ "velocity_verlet_configuration_init": "0x100592f20",+ "velocity_verlet_configuration_completion": "0x100593cfc",+ "velocity_verlet_advance_to_time": "0x100593404",+ "velocity_verlet_advance_one_step": "0x100594110",+ "spring_animation_finished_predicate": "0x1005934b0",+ "transaction_metadata_accessor": "0x1005967fc",+ },+ "spring_parameter_normalization_helper": {+ "function": "0x1005879a4",+ "input_name_in_binary_not_recovered": True,+ "confirmed_piecewise_mapping": "if x <= -1 -> +inf; else if x < 0 -> 1 / (1 + x); else if x == 0 -> 0; else -> 1 - min(x, 1)",+ "note": "This helper lives in the Animation.SpringParameters area; the cursor path animation uses direct response/dampingFraction constants and does not need this remap.",+ },+ "velocity_verlet_completion_status": {+ "two_pi_constant_used": True,+ "stiffness_and_drag_fields_exist": True,+ "exact_numeric_formula_transcription_complete": True,+ },+ "velocity_verlet_exact_math": {+ "stiffness_formula": "stiffness = min(response > 0 ? (2π / response)^2 : +inf, 28800)",+ "drag_formula": "drag = 2 * dampingFraction * sqrt(stiffness)",+ "stale_time_clamp": "if targetTime - time > 1.0, set time = targetTime - 1/60 before stepping",+ "step_sequence": [+ "velocityHalf = velocity + force * (dt / 2)",+ "current = current + velocityHalf * dt",+ "force = stiffness * (target - current) + (-drag) * velocityHalf",+ "velocity = velocityHalf + force * (dt / 2)",+ ],+ },+ "spring_animation_update_and_finish": {+ "frame_update_function": "0x1005761bc",+ "confirmed_behavior": [+ "copy a current-value-like buffer from hidden self offset 0x68",+ "copy a target-value-like buffer from hidden self offset 0x70",+ "advance the spring simulation via 0x100593404",+ "run 0x1005934b0 as the finished predicate",+ "return optional nil when finished, otherwise return some(updatedValue)",+ ],+ "finish_predicate_function": "0x1005934b0",+ "finish_predicate_gates": {+ "threshold_square_gate": "load two hidden-self scalar slots, take Swift.max(slotA, slotB), and require max(slotA, slotB) <= threshold^2 to continue",+ "exact_zero_gate": "build a float literal 0.01, run SIMD scalar loops, then accept only when a difference-derived scalar A is neither > 0 nor < 0",+ },+ "field_mapping_notes": {+ "copy_helper_offsets": {+ "0x1005730bc": "reads hidden self offset 0x68",+ "0x100573390": "reads hidden self offset 0x70",+ },+ "threshold_field_inference": "the metadata field loaded via +0x30 in 0x1005934b0 is very likely idleVelocityThreshold; this is inferred from adjacent layout and threshold-squared usage, not a direct symbol name",+ "value_target_field_inference": "the 0x68/0x70 slots are very likely InterpolatableAnimation._value / _targetValue; this mapping is inferred from class field metadata plus offset adjacency, not directly named in the code",+ },+ },+ "shared_helper_reuse": {+ "system_settings_accessory_transition_geometry_style": {+ "spring_response": 0.72,+ "spring_damping_fraction": 1.0,+ "note": "This is a separate bundled-binary caller that reuses part of the same spring initialization chain.",+ }+ },+}+++def build_model_constants(binary: MachOBinary) -> dict[str, float]:+ model_constants = extract_named_constants(binary)+ model_constants.update(CONFIRMED_DISASSEMBLY_CONSTANTS)+ return model_constants+++def extract_candidate_tables(binary: MachOBinary) -> dict[str, list[float]]:+ table_a_vm = 0x10098B988+ table_b_vm = 0x10098B9C0+ table_a = [binary.read_double(table_a_vm + 0x20 + (index * 8)) for index in range(3)]+ table_b = [binary.read_double(table_b_vm + 0x20 + (index * 8)) for index in range(3)]+ return {"table_a": table_a, "table_b": table_b}+++@dataclass(frozen=True)+class Vec2:+ x: float+ y: float++ def __add__(self, other: "Vec2") -> "Vec2":+ return Vec2(self.x + other.x, self.y + other.y)++ def __sub__(self, other: "Vec2") -> "Vec2":+ return Vec2(self.x - other.x, self.y - other.y)++ def scale(self, factor: float) -> "Vec2":+ return Vec2(self.x * factor, self.y * factor)++ def length(self) -> float:+ return math.hypot(self.x, self.y)++ def normalized(self) -> "Vec2":+ length = self.length()+ if length <= 1e-9:+ return Vec2(1.0, 0.0)+ return Vec2(self.x / length, self.y / length)++ def perpendicular(self) -> "Vec2":+ return Vec2(-self.y, self.x)++ def to_list(self) -> list[float]:+ return [self.x, self.y]+++@dataclass(frozen=True)+class Bounds:+ min_x: float+ min_y: float+ max_x: float+ max_y: float++ def contains(self, point: Vec2, padding: float = 0.0) -> bool:+ return (+ (self.min_x - padding) <= point.x <= (self.max_x + padding)+ and (self.min_y - padding) <= point.y <= (self.max_y + padding)+ )+++@dataclass(frozen=True)+class CubicSegment:+ end: Vec2+ control1: Vec2+ control2: Vec2+++@dataclass(frozen=True)+class SamplePoint:+ progress: float+ point: Vec2+ tangent: Vec2+ speed_units_per_progress: float++ def to_dict(self) -> dict[str, object]:+ return {+ "progress": self.progress,+ "point": self.point.to_list(),+ "tangent": self.tangent.to_list(),+ "speed_units_per_progress": self.speed_units_per_progress,+ }+++@dataclass(frozen=True)+class CursorMotionMeasurement:+ length: float+ angle_change_energy: float+ max_angle_change: float+ total_turn: float+ stays_in_bounds: bool++ def to_dict(self) -> dict[str, object]:+ return asdict(self)+++@dataclass(frozen=True)+class CandidateScoreComponents:+ excess_length_ratio: float+ excess_length_cost: float+ angle_energy_cost: float+ max_angle_cost: float+ total_turn_cost: float+ out_of_bounds_cost: float+ total_score: float++ def to_dict(self) -> dict[str, float]:+ return asdict(self)+++@dataclass(frozen=True)+class ScalarSpringConfiguration:+ response: float+ damping_fraction: float+ stiffness: float+ drag: float+ dt: float+ close_enough_progress_threshold: float+ close_enough_distance_threshold: float+ idle_velocity_threshold: float++ def to_dict(self) -> dict[str, float]:+ return asdict(self)+++@dataclass(frozen=True)+class ScalarVelocityVerletState:+ time: float+ velocity: float+ force: float++ def to_dict(self) -> dict[str, float]:+ return asdict(self)+++@dataclass(frozen=True)+class TimedCursorSample:+ step: int+ time: float+ progress: float+ point: Vec2+ spring_velocity: float+ spring_force: float+ geometric_speed_units_per_second: float++ def to_dict(self) -> dict[str, object]:+ return {+ "step": self.step,+ "time": self.time,+ "progress": self.progress,+ "point": self.point.to_list(),+ "spring_velocity": self.spring_velocity,+ "spring_force": self.spring_force,+ "geometric_speed_units_per_second": self.geometric_speed_units_per_second,+ }+++@dataclass(frozen=True)+class CursorMotionPath:+ start: Vec2+ end: Vec2+ start_control: Vec2 | None = None+ arc: Vec2 | None = None+ arc_in: Vec2 | None = None+ arc_out: Vec2 | None = None+ end_control: Vec2 | None = None+ segments: tuple[CubicSegment, ...] = ()++ def sample(self, progress: float) -> tuple[Vec2, Vec2]:+ if not self.segments:+ return self.start, Vec2(1.0, 0.0)++ clamped = min(max(progress, 0.0), 1.0)+ segment_count = len(self.segments)+ if clamped >= 1.0:+ segment_index = segment_count - 1+ local_t = 1.0+ else:+ scaled = clamped * segment_count+ segment_index = min(int(scaled), segment_count - 1)+ local_t = scaled - segment_index++ segment = self.segments[segment_index]+ start = self.start if segment_index == 0 else self.segments[segment_index - 1].end+ point = _sample_cubic(start, segment.control1, segment.control2, segment.end, local_t)+ tangent = _sample_cubic_tangent(start, segment.control1, segment.control2, segment.end, local_t).normalized()+ return point, tangent++ def sample_points(self, count: int) -> list[SamplePoint]:+ samples: list[SamplePoint] = []+ previous_point: Vec2 | None = None+ for index in range(count):+ progress = index / max(count - 1, 1)+ point, tangent = self.sample(progress)+ speed = 0.0 if previous_point is None else (point - previous_point).length()+ samples.append(+ SamplePoint(+ progress=progress,+ point=point,+ tangent=tangent,+ speed_units_per_progress=speed,+ )+ )+ previous_point = point+ return samples++ def measure(self, bounds: Bounds | None, min_step_distance: float = 0.01, samples_per_segment: int = 24) -> CursorMotionMeasurement:+ total_length = 0.0+ angle_change_energy = 0.0+ max_angle_change = 0.0+ total_turn = 0.0+ stays_in_bounds = True+ previous_point = self.start+ previous_angle: float | None = None++ if bounds is not None:+ stays_in_bounds = bounds.contains(self.start, padding=20.0)++ total_steps = max(len(self.segments) * samples_per_segment, 1)+ for step in range(1, total_steps + 1):+ progress = step / total_steps+ point, _ = self.sample(progress)+ delta = point - previous_point+ step_length = delta.length()++ if bounds is not None and stays_in_bounds:+ stays_in_bounds = bounds.contains(point, padding=20.0)++ if step_length > min_step_distance:+ angle = math.atan2(delta.y, delta.x)+ total_length += step_length++ if previous_angle is not None:+ angle_delta = angle - previous_angle+ while angle_delta > math.pi:+ angle_delta -= math.tau+ while angle_delta < -math.pi:+ angle_delta += math.tau+ angle_change_energy += angle_delta * angle_delta+ absolute_delta = abs(angle_delta)+ max_angle_change = max(max_angle_change, absolute_delta)+ total_turn += absolute_delta++ previous_angle = angle+ previous_point = point++ return CursorMotionMeasurement(+ length=total_length,+ angle_change_energy=angle_change_energy,+ max_angle_change=max_angle_change,+ total_turn=total_turn,+ stays_in_bounds=stays_in_bounds,+ )+++@dataclass(frozen=True)+class CandidatePath:+ identifier: str+ kind: str+ side: int+ table_a_scale: float | None+ table_b_scale: float | None+ score: float+ score_components: CandidateScoreComponents+ measurement: CursorMotionMeasurement+ path: CursorMotionPath++ def summary_dict(self) -> dict[str, object]:+ return {+ "identifier": self.identifier,+ "kind": self.kind,+ "side": self.side,+ "table_a_scale": self.table_a_scale,+ "table_b_scale": self.table_b_scale,+ "score": self.score,+ "score_components": self.score_components.to_dict(),+ "measurement": self.measurement.to_dict(),+ }++ def to_dict(self, sample_count: int, include_samples: bool = True) -> dict[str, object]:+ return {+ "identifier": self.identifier,+ "kind": self.kind,+ "side": self.side,+ "table_a_scale": self.table_a_scale,+ "table_b_scale": self.table_b_scale,+ "score": self.score,+ "score_components": self.score_components.to_dict(),+ "measurement": self.measurement.to_dict(),+ "path": {+ "start": self.path.start.to_list(),+ "end": self.path.end.to_list(),+ "start_control": self.path.start_control.to_list() if self.path.start_control else None,+ "arc": self.path.arc.to_list() if self.path.arc else None,+ "arc_in": self.path.arc_in.to_list() if self.path.arc_in else None,+ "arc_out": self.path.arc_out.to_list() if self.path.arc_out else None,+ "end_control": self.path.end_control.to_list() if self.path.end_control else None,+ "segments": [+ {+ "end": segment.end.to_list(),+ "control1": segment.control1.to_list(),+ "control2": segment.control2.to_list(),+ }+ for segment in self.path.segments+ ],+ },+ "samples": [sample.to_dict() for sample in self.path.sample_points(sample_count)] if include_samples else [],+ }+++def _sample_cubic(start: Vec2, control1: Vec2, control2: Vec2, end: Vec2, t: float) -> Vec2:+ omt = 1.0 - t+ omt2 = omt * omt+ t2 = t * t+ return Vec2(+ x=(omt2 * omt * start.x)+ + (3.0 * omt2 * t * control1.x)+ + (3.0 * omt * t2 * control2.x)+ + (t2 * t * end.x),+ y=(omt2 * omt * start.y)+ + (3.0 * omt2 * t * control1.y)+ + (3.0 * omt * t2 * control2.y)+ + (t2 * t * end.y),+ )+++def _sample_cubic_tangent(start: Vec2, control1: Vec2, control2: Vec2, end: Vec2, t: float) -> Vec2:+ omt = 1.0 - t+ return Vec2(+ x=(3.0 * omt * omt * (control1.x - start.x))+ + (6.0 * omt * t * (control2.x - control1.x))+ + (3.0 * t * t * (end.x - control2.x)),+ y=(3.0 * omt * omt * (control1.y - start.y))+ + (6.0 * omt * t * (control2.y - control1.y))+ + (3.0 * t * t * (end.y - control2.y)),+ )+++def clamp(value: float, minimum: float, maximum: float) -> float:+ return max(minimum, min(maximum, value))+++def build_scalar_spring_configuration() -> ScalarSpringConfiguration:+ response = CONFIRMED_CURSOR_TIMING_CONSTANTS["cursor_path_spring_response"]+ damping_fraction = CONFIRMED_CURSOR_TIMING_CONSTANTS["cursor_path_spring_damping_fraction"]+ dt = CONFIRMED_CURSOR_TIMING_CONSTANTS["velocity_verlet_dt"]+ idle_velocity_threshold = CONFIRMED_CURSOR_TIMING_CONSTANTS["velocity_verlet_idle_velocity_threshold"]++ # 0x100593cfc computes stiffness from the scalar spring response with:+ # raw = (2π / response)^2 if response > 0, otherwise +inf+ raw_stiffness = math.inf if response <= 0.0 else (math.tau / response) ** 2+ stiffness = min(raw_stiffness, idle_velocity_threshold)++ # 0x100593f18 then computes drag from the already-clamped stiffness as+ # 2 * dampingFraction * sqrt(stiffness).+ drag = 2.0 * damping_fraction * math.sqrt(stiffness)++ return ScalarSpringConfiguration(+ response=response,+ damping_fraction=damping_fraction,+ stiffness=stiffness,+ drag=drag,+ dt=dt,+ close_enough_progress_threshold=CONFIRMED_CURSOR_TIMING_CONSTANTS["close_enough_progress_threshold"],+ close_enough_distance_threshold=CONFIRMED_CURSOR_TIMING_CONSTANTS["close_enough_distance_threshold"],+ idle_velocity_threshold=idle_velocity_threshold,+ )+++def advance_scalar_velocity_verlet(+ current: float,+ target: float,+ state: ScalarVelocityVerletState,+ config: ScalarSpringConfiguration,+) -> tuple[float, ScalarVelocityVerletState]:+ half_dt = config.dt * 0.5++ # 0x100594948..0x100594b04+ velocity_half = state.velocity + (state.force * half_dt)+ # 0x100594c4c..0x100594e8c+ current = current + (velocity_half * config.dt)+ # 0x100594ecc..0x1005954f4+ force = (config.stiffness * (target - current)) + ((-config.drag) * velocity_half)+ # 0x1005955f0..0x100595858+ velocity = velocity_half + (force * half_dt)++ return current, ScalarVelocityVerletState(+ time=state.time + config.dt,+ velocity=velocity,+ force=force,+ )+++def advance_scalar_velocity_verlet_to_time(+ current: float,+ target: float,+ state: ScalarVelocityVerletState,+ config: ScalarSpringConfiguration,+ target_time: float,+) -> tuple[float, ScalarVelocityVerletState]:+ # 0x100593404 limits excessively stale simulation time to targetTime - 1/60.+ if (target_time - state.time) > 1.0:+ state = ScalarVelocityVerletState(+ time=target_time - (1.0 / 60.0),+ velocity=state.velocity,+ force=state.force,+ )++ while state.time < target_time:+ current, state = advance_scalar_velocity_verlet(+ current=current,+ target=target,+ state=state,+ config=config,+ )++ return current, state+++def build_timed_cursor_timeline(+ path: CursorMotionPath,+ report_every_steps: int = 4,+ max_duration_seconds: float = 2.0,+) -> dict[str, object]:+ config = build_scalar_spring_configuration()+ current = 0.0+ target = 1.0+ state = ScalarVelocityVerletState(time=0.0, velocity=0.0, force=0.0)+ samples: list[TimedCursorSample] = []+ previous_point: Vec2 | None = None+ close_enough_first_time: float | None = None+ close_enough_first_step: int | None = None+ raw_progress_first_ge_target_time: float | None = None+ raw_progress_first_ge_target_step: int | None = None+ first_endpoint_lock_time: float | None = None+ first_endpoint_lock_step: int | None = None+ step_count = int(max_duration_seconds / config.dt)++ start_point, _ = path.sample(current)+ samples.append(+ TimedCursorSample(+ step=0,+ time=0.0,+ progress=current,+ point=start_point,+ spring_velocity=state.velocity,+ spring_force=state.force,+ geometric_speed_units_per_second=0.0,+ )+ )+ previous_point = start_point++ for step in range(1, step_count + 1):+ target_time = step * config.dt+ current, state = advance_scalar_velocity_verlet_to_time(+ current=current,+ target=target,+ state=state,+ config=config,+ target_time=target_time,+ )+ point, _ = path.sample(current)+ geometric_speed = 0.0 if previous_point is None else (point - previous_point).length() / config.dt+ previous_point = point++ if raw_progress_first_ge_target_time is None and current >= target:+ raw_progress_first_ge_target_time = state.time+ raw_progress_first_ge_target_step = step++ if first_endpoint_lock_time is None and current >= target and point == path.end:+ first_endpoint_lock_time = state.time+ first_endpoint_lock_step = step++ if (+ close_enough_first_time is None+ and current >= config.close_enough_progress_threshold+ and abs(target - current) <= config.close_enough_distance_threshold+ ):+ close_enough_first_time = state.time+ close_enough_first_step = step++ should_record = (step % report_every_steps) == 0 or step == step_count+ if should_record:+ samples.append(+ TimedCursorSample(+ step=step,+ time=state.time,+ progress=current,+ point=point,+ spring_velocity=state.velocity,+ spring_force=state.force,+ geometric_speed_units_per_second=geometric_speed,+ )+ )++ return {+ "spring_configuration": config.to_dict(),+ "simulation_state_at_end": state.to_dict(),+ "binary_confirmed_step_sequence": [+ "velocityHalf = velocity + force * (dt / 2)",+ "current = current + velocityHalf * dt",+ "force = stiffness * (target - current) + (-drag) * velocityHalf",+ "velocity = velocityHalf + force * (dt / 2)",+ ],+ "internal_step_hz": round(1.0 / config.dt),+ "reported_sample_hz": round(1.0 / (config.dt * report_every_steps)),+ "reported_sample_stride_steps": report_every_steps,+ "raw_progress_first_ge_target_time": raw_progress_first_ge_target_time,+ "raw_progress_first_ge_target_step": raw_progress_first_ge_target_step,+ "first_endpoint_lock_time": first_endpoint_lock_time,+ "first_endpoint_lock_step": first_endpoint_lock_step,+ "close_enough_first_time": close_enough_first_time,+ "close_enough_first_step": close_enough_first_step,+ "endpoint_lock_inference_note": "CursorMotionPath.sample(progress) is binary-confirmed to clamp progress into [0, 1], so the visible point becomes the exact path endpoint once raw spring progress first reaches 1.0. The linkage from that visible endpoint lock to SpringAnimation's finished optional-return path is still an inference from multiple confirmed pieces.",+ "samples": [sample.to_dict() for sample in samples],+ }+++def _binary_piecewise_primary_extents(distance: float, constants: dict[str, float], guide: Vec2) -> tuple[float, float]:+ if not (guide.x < 0.0 < guide.y):+ raise ValueError("the current binary lift assumes the bundled guide vector has negative x and positive y")++ primary = distance * constants["distance_scale_primary"]+ direct = distance * constants["direct_span_scale"]+ secondary = distance * 0.15+ low_cutoff = 48.0+ high_cutoff = 640.0++ # This is the sign-specialized lift of 0x10005fe84..0x10006013c for the+ # bundled guide vector (-0.6946, +0.7193). The binary's branch tree reduces+ # to four piecewise regions under that fixed sign pattern.+ if primary < low_cutoff:+ return low_cutoff, low_cutoff+ if primary < high_cutoff:+ return primary, direct+ if secondary < high_cutoff:+ return high_cutoff, low_cutoff+ return high_cutoff, high_cutoff+++def _binary_piecewise_handle_extent(distance: float, constants: dict[str, float]) -> float:+ raw = distance * constants["distance_scale_secondary"]+ if raw < 50.0:+ return 50.0+ if raw < 640.0:+ return raw+ return 520.0+++def _clip_positive_ray(origin: Vec2, direction: Vec2, bounds: Bounds | None) -> float:+ if bounds is None:+ return math.inf++ limit = math.inf+ if direction.x > 0.0:+ limit = min(limit, (bounds.max_x - origin.x) / direction.x)+ elif direction.x < 0.0:+ limit = min(limit, (bounds.min_x - origin.x) / direction.x)++ if direction.y > 0.0:+ limit = min(limit, (bounds.max_y - origin.y) / direction.y)+ elif direction.y < 0.0:+ limit = min(limit, (bounds.min_y - origin.y) / direction.y)++ return max(limit, 0.0)+++def _normalized_or_default(vector: Vec2, minimum_length: float, constants: dict[str, float]) -> Vec2:+ length = vector.length()+ if length < minimum_length or length < constants["normalization_epsilon"]:+ return Vec2(1.0, 0.0)+ return vector.scale(1.0 / length)+++class BinaryGuidedPathGenerator:+ def __init__(self, constants: dict[str, float], tables: dict[str, list[float]]):+ self.constants = constants+ self.tables = tables+ self.guide_local = Vec2(-0.6946583704589973, 0.7193398003386512)++ def build_candidates(self, start: Vec2, end: Vec2, bounds: Bounds | None) -> list[CandidatePath]:+ delta = end - start+ distance = max(delta.length(), self.constants["normalization_epsilon"])+ direction = delta.normalized()+ local_normal = direction.perpendicular()+ guide = direction.scale(self.guide_local.x) + local_normal.scale(self.guide_local.y)+ reverse_guide = guide.scale(-1.0)++ start_extent_pre, end_extent_pre = _binary_piecewise_primary_extents(+ distance=distance,+ constants=self.constants,+ guide=guide,+ )+ start_extent = min(start_extent_pre, _clip_positive_ray(start, guide, bounds))+ end_extent = min(end_extent_pre, _clip_positive_ray(end, reverse_guide, bounds))++ start_extent_scaled = min(+ max(start_extent * self.constants["side_bias_scale"], 0.0),+ _clip_positive_ray(start, guide, bounds),+ )+ end_extent_scaled = min(+ max(end_extent * self.constants["side_bias_scale"], 0.0),+ _clip_positive_ray(end, reverse_guide, bounds),+ )++ full_start_control = start + guide.scale(start_extent)+ full_end_control = end - guide.scale(end_extent)+ scaled_start_control = start + guide.scale(start_extent_scaled)+ scaled_end_control = end - guide.scale(end_extent_scaled)++ raw_handle_extent = _binary_piecewise_handle_extent(distance, self.constants)+ raw_arc_extent = clamp(+ distance * self.constants["distance_scale_tertiary"],+ self.constants["candidate_arc_min"],+ self.constants["candidate_arc_max"],+ )++ midpoint = Vec2((start.x + end.x) * 0.5, (start.y + end.y) * 0.5)+ signed_normal = local_normal+ cross = (guide.y * direction.x) - (guide.x * direction.y)+ if cross < 0.0:+ signed_normal = signed_normal.scale(-1.0)+ arc_anchor_bias = guide.scale(start_extent * self.constants["side_bias_scale"])+ forward_unit = _normalized_or_default(+ direction.scale(distance) + signed_normal.scale(raw_arc_extent),+ minimum_length=raw_handle_extent,+ constants=self.constants,+ )++ candidates: list[CandidatePath] = []+ candidates.append(+ self._make_candidate(+ identifier="base-full-guide",+ kind="base",+ side=0,+ table_a_scale=None,+ table_b_scale=None,+ path=CursorMotionPath(+ start=start,+ end=end,+ start_control=full_start_control,+ end_control=full_end_control,+ segments=(CubicSegment(end=end, control1=full_start_control, control2=full_end_control),),+ ),+ bounds=bounds,+ distance=distance,+ )+ )+ candidates.append(+ self._make_candidate(+ identifier="base-scaled-guide",+ kind="base",+ side=0,+ table_a_scale=None,+ table_b_scale=None,+ path=CursorMotionPath(+ start=start,+ end=end,+ start_control=scaled_start_control,+ end_control=scaled_end_control,+ segments=(CubicSegment(end=end, control1=scaled_start_control, control2=scaled_end_control),),+ ),+ bounds=bounds,+ distance=distance,+ )+ )++ for outer_scale in self.tables["table_a"]:+ anchor_offset = signed_normal.scale(raw_handle_extent * outer_scale)+ for inner_scale in self.tables["table_b"]:+ tangent_span = forward_unit.scale(raw_arc_extent * inner_scale)++ for side, anchor in (+ (1, midpoint + arc_anchor_bias + anchor_offset),+ (-1, midpoint + arc_anchor_bias - anchor_offset),+ ):+ arc_in = anchor - tangent_span+ arc_out = anchor + tangent_span+ path = CursorMotionPath(+ start=start,+ end=end,+ start_control=full_start_control,+ arc=anchor,+ arc_in=arc_in,+ arc_out=arc_out,+ end_control=full_end_control,+ segments=(+ CubicSegment(end=anchor, control1=full_start_control, control2=arc_in),+ CubicSegment(end=end, control1=arc_out, control2=full_end_control),+ ),+ )+ candidates.append(+ self._make_candidate(+ identifier=f"a{outer_scale:.2f}-b{inner_scale:.2f}-{'positive' if side > 0 else 'negative'}",+ kind="arched",+ side=side,+ table_a_scale=outer_scale,+ table_b_scale=inner_scale,+ path=path,+ bounds=bounds,+ distance=distance,+ )+ )++ return candidates++ def choose_candidate(self, candidates: list[CandidatePath]) -> tuple[CandidatePath | None, str]:+ if not candidates:+ return None, "empty"++ in_bounds_candidates = [candidate for candidate in candidates if candidate.measurement.stays_in_bounds]+ pool = in_bounds_candidates if in_bounds_candidates else candidates+ policy = "prefer_in_bounds_then_lowest_score" if in_bounds_candidates else "lowest_score"+ return min(pool, key=lambda item: item.score), policy++ def _score_candidate(+ self,+ distance: float,+ measurement: CursorMotionMeasurement,+ ) -> CandidateScoreComponents:+ excess_length_ratio = max((measurement.length / max(distance, 1.0)) - 1.0, 0.0)+ excess_length_cost = excess_length_ratio * self.constants["score_excess_length_weight"]+ angle_energy_cost = measurement.angle_change_energy * self.constants["score_angle_energy_weight"]+ max_angle_cost = measurement.max_angle_change * self.constants["score_max_angle_weight"]+ total_turn_cost = measurement.total_turn * self.constants["score_total_turn_weight"]+ out_of_bounds_cost = 0.0 if measurement.stays_in_bounds else self.constants["score_out_of_bounds_penalty"]+ total_score = (+ excess_length_cost+ + angle_energy_cost+ + max_angle_cost+ + total_turn_cost+ + out_of_bounds_cost+ )+ return CandidateScoreComponents(+ excess_length_ratio=excess_length_ratio,+ excess_length_cost=excess_length_cost,+ angle_energy_cost=angle_energy_cost,+ max_angle_cost=max_angle_cost,+ total_turn_cost=total_turn_cost,+ out_of_bounds_cost=out_of_bounds_cost,+ total_score=total_score,+ )++ def _make_candidate(+ self,+ identifier: str,+ kind: str,+ side: int,+ table_a_scale: float | None,+ table_b_scale: float | None,+ path: CursorMotionPath,+ bounds: Bounds | None,+ distance: float,+ ) -> CandidatePath:+ measurement = path.measure(+ bounds=bounds,+ min_step_distance=self.constants["minimum_step_distance"],+ )+ score_components = self._score_candidate(distance=distance, measurement=measurement)+ return CandidatePath(+ identifier=identifier,+ kind=kind,+ side=side,+ table_a_scale=table_a_scale,+ table_b_scale=table_b_scale,+ score=score_components.total_score,+ score_components=score_components,+ measurement=measurement,+ path=path,+ )+++def build_inspect_output(binary: MachOBinary) -> dict[str, object]:+ guide_vector = [-0.6946583704589973, 0.7193398003386512]+ return {+ "binary_path": str(binary.path),+ "motion_types": [asdict(item) for item in extract_motion_type_fields(binary)],+ "data_section_constants": extract_named_constants(binary),+ "confirmed_model_constants": CONFIRMED_DISASSEMBLY_CONSTANTS,+ "confirmed_timing_constants": CONFIRMED_CURSOR_TIMING_CONSTANTS,+ "candidate_tables": extract_candidate_tables(binary),+ "confirmed_from_binary": {+ "path_sample_function": "segment selection + cubic bezier evaluation",+ "measurement_function": "24 samples per segment + angle unwrap + in-bounds flag",+ "candidate_tables_shape": "3 x 3 coefficient tables with mirrored path variants",+ "candidate_count_shape": "2 base candidates + 3 x 3 x 2 mirrored candidates = 20",+ "guide_vector": guide_vector,+ "path_struct_layout": {+ "start": "offset 0x00",+ "end": "offset 0x10",+ "startControl": "offset 0x20",+ "arc": "offset 0x30",+ "arcIn": "offset 0x48",+ "arcOut": "offset 0x60",+ "endControl": "offset 0x78",+ "segments": "offset 0x88",+ },+ "segment_struct_layout": {+ "end": "offset 0x00",+ "control1": "offset 0x10",+ "control2": "offset 0x20",+ },+ "guide_extent_piecewise": {+ "start_extent": "48 if d*0.41960295031576633 < 48; d*0.41960295031576633 if d*0.41960295031576633 < 640; 640 if d*0.15 < 640; else 640",+ "end_extent": "48 if d*0.41960295031576633 < 48; d*0.9 if d*0.41960295031576633 < 640; 48 if d*0.15 < 640; else 640",+ },+ "handle_extent_piecewise": "50 if d*0.2765523188064277 < 50; d*0.2765523188064277 if d*0.2765523188064277 < 640; else 520",+ "arc_extent_piecewise": "clamp(d*0.5783555327868779, 38, 440)",+ "candidate_score_formula": "320 * max(length / max(directDistance, 1) - 1, 0) + 140 * angleEnergy + 180 * maxAngle + 18 * totalTurn + 45 * outOfBounds",+ "candidate_selection_policy": "prefer in-bounds candidates, otherwise fall back to all candidates, then choose the minimum score",+ "velocity_verlet_stiffness_formula": "stiffness = min(response > 0 ? (2π / response)^2 : +inf, 28800)",+ "velocity_verlet_drag_formula": "drag = 2 * dampingFraction * sqrt(stiffness)",+ "velocity_verlet_step_sequence": [+ "velocityHalf = velocity + force * (dt / 2)",+ "current = current + velocityHalf * dt",+ "force = stiffness * (target - current) + (-drag) * velocityHalf",+ "velocity = velocityHalf + force * (dt / 2)",+ ],+ "spring_animation_frame_update": {+ "function": "0x1005761bc",+ "behavior": "advance simulation, evaluate finished predicate, return optional nil on finish else some(updatedValue)",+ "value_copy_helper": "0x1005730bc reads hidden self offset 0x68",+ "target_copy_helper": "0x100573390 reads hidden self offset 0x70",+ },+ "spring_animation_finish_predicate": {+ "function": "0x1005934b0",+ "threshold_square_gate": "requires max(hiddenStateSlotA, hiddenStateSlotB) <= threshold^2 before continuing",+ "exact_zero_gate": "after a 0.01 float-literal broadcast and SIMD scalar loops, accepts only when a difference-derived scalar A is neither A > 0 nor 0 > A",+ "field_name_inference_notes": {+ "hidden_self_0x68_0x70": "very likely InterpolatableAnimation._value / _targetValue",+ "metadata_plus_0x30_threshold": "very likely idleVelocityThreshold",+ },+ },+ },+ "timing_from_binary": {+ "type_relationships": CONFIRMED_TIMING_TYPE_RELATIONSHIPS,+ "cursor_path_constants": CONFIRMED_CURSOR_TIMING_CONSTANTS,+ "pipeline": CONFIRMED_TIMING_PIPELINE,+ },+ }+++def build_demo_output(+ binary: MachOBinary,+ start: Vec2,+ end: Vec2,+ bounds: Bounds | None,+ sample_count: int,+ include_all_candidates: bool,+) -> dict[str, object]:+ constants = build_model_constants(binary)+ tables = extract_candidate_tables(binary)+ generator = BinaryGuidedPathGenerator(constants=constants, tables=tables)+ candidates = generator.build_candidates(start=start, end=end, bounds=bounds)+ chosen_candidate, selection_policy = generator.choose_candidate(candidates)+ ordered_candidates = sorted(candidates, key=lambda item: (not item.measurement.stays_in_bounds, item.score))+ timed_timeline = build_timed_cursor_timeline(chosen_candidate.path) if chosen_candidate else None+ return {+ "binary_path": str(binary.path),+ "input": {+ "start": start.to_list(),+ "end": end.to_list(),+ "bounds": asdict(bounds) if bounds else None,+ "sample_count": sample_count,+ },+ "confirmed_model_constants": CONFIRMED_DISASSEMBLY_CONSTANTS,+ "confirmed_timing_constants": CONFIRMED_CURSOR_TIMING_CONSTANTS,+ "confirmed_from_binary": {+ "sample_progress_logic": True,+ "measurement_logic": True,+ "candidate_coeff_tables": True,+ "candidate_geometry_lifted_from_disassembly": True,+ "candidate_score_formula": True,+ "candidate_selection_policy": True,+ "spring_animation_chain": True,+ "velocity_verlet_configuration_fields": True,+ "window_animation_state_slots": True,+ "velocity_verlet_step_sequence": True,+ "stiffness_formula": True,+ "drag_formula": True,+ "spring_animation_finished_predicate_control_flow": True,+ },+ "reconstructed_or_inferred": {+ "automatic_bounds_discovery_from_runtime": True,+ "wall_clock_duration_model": True,+ "spring_animation_value_target_field_names": True,+ "endpoint_lock_to_finished_predicate_linkage": True,+ },+ "timing_notes": {+ "duration_recovered_from_binary": False,+ "sample_speed_is_geometric": True,+ "sample_speed_definition": "distance between adjacent time-stepped path points divided by dt",+ "spring_response_and_damping_recovered": True,+ "velocity_verlet_dt_recovered": True,+ "velocity_verlet_idle_velocity_threshold_recovered": True,+ "spring_animation_finish_predicate_control_flow_recovered": True,+ },+ "timing_binary_evidence": {+ "type_relationships": CONFIRMED_TIMING_TYPE_RELATIONSHIPS,+ "pipeline": CONFIRMED_TIMING_PIPELINE,+ },+ "candidate_shape_notes": {+ "confirmed_binary_candidate_count": 20,+ "demo_candidate_count": len(candidates),+ "bounds_note": "the bundled app derives bounds from runtime screen regions before calling the path builder; this script expects bounds as direct input",+ },+ "selection_policy": selection_policy,+ "timed_cursor_demo": timed_timeline,+ "candidate_summaries": [candidate.summary_dict() for candidate in ordered_candidates],+ "chosen_candidate": chosen_candidate.to_dict(sample_count=sample_count) if chosen_candidate else None,+ "all_candidates": [candidate.to_dict(sample_count=sample_count) for candidate in ordered_candidates]+ if include_all_candidates+ else None,+ }+++def parse_vec2(values: Iterable[str]) -> Vec2:+ x_raw, y_raw = values+ return Vec2(float(x_raw), float(y_raw))+++def parse_bounds(values: Iterable[str]) -> Bounds:+ min_x, min_y, max_x, max_y = (float(item) for item in values)+ return Bounds(min_x=min_x, min_y=min_y, max_x=max_x, max_y=max_y)+++def build_parser() -> argparse.ArgumentParser:+ parser = argparse.ArgumentParser(description="Reverse-engineering helpers for official cursor motion.")+ parser.add_argument("--app", type=Path, default=DEFAULT_APP_PATH, help="Path to SkyComputerUseService binary.")+ parser.add_argument("--pretty", dest="pretty_global", action="store_true", help="Pretty-print JSON output.")++ subparsers = parser.add_subparsers(dest="command", required=True)++ inspect = subparsers.add_parser("inspect", help="Dump recovered motion types, constants, and coefficient tables.")+ inspect.add_argument("--pretty", dest="pretty_local", action="store_true", help="Pretty-print JSON output.")++ demo = subparsers.add_parser("demo", help="Generate binary-guided candidate cursor paths.")+ demo.add_argument("--pretty", dest="pretty_local", action="store_true", help="Pretty-print JSON output.")+ demo.add_argument("--start", nargs=2, metavar=("X", "Y"), required=True, help="Start position.")+ demo.add_argument("--end", nargs=2, metavar=("X", "Y"), required=True, help="End position.")+ demo.add_argument(+ "--bounds",+ nargs=4,+ metavar=("MIN_X", "MIN_Y", "MAX_X", "MAX_Y"),+ help="Optional bounds used for stays_in_bounds measurement.",+ )+ demo.add_argument("--samples", type=int, default=32, help="Number of sample points per candidate.")+ demo.add_argument(+ "--include-all-candidates",+ action="store_true",+ help="Include full path and sample output for every candidate instead of only the chosen candidate.",+ )++ return parser+++def main(argv: list[str] | None = None) -> int:+ parser = build_parser()+ args = parser.parse_args(argv)++ binary = MachOBinary(args.app)+ if args.command == "inspect":+ payload = build_inspect_output(binary)+ elif args.command == "demo":+ start = parse_vec2(args.start)+ end = parse_vec2(args.end)+ bounds = parse_bounds(args.bounds) if args.bounds else None+ payload = build_demo_output(+ binary,+ start=start,+ end=end,+ bounds=bounds,+ sample_count=args.samples,+ include_all_candidates=args.include_all_candidates,+ )+ else:+ raise AssertionError(f"unsupported command: {args.command}")++ pretty = args.pretty_global or getattr(args, "pretty_local", False)+ import sys++ json.dump(payload, fp=sys.stdout, ensure_ascii=True, indent=2 if pretty else None)+ sys.stdout.write("\n")+ return 0+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/scripts/cursor-motion-re/reconstruct_cursor_motion.py b/scripts/cursor-motion-re/reconstruct_cursor_motion.pynew file mode 100644index 0000000..c4f61f8--- /dev/null+++ b/scripts/cursor-motion-re/reconstruct_cursor_motion.py@@ -0,0 +1,7 @@+#!/usr/bin/env python3++from official_cursor_motion import main+++if __name__ == "__main__":+ raise SystemExit(main())