Skip to content

👾 Open Computer Use – Open-Source Alternative to Codex Computer Use

Add cursor motion reconstruction assets

ifuryst4a46de3ea7c7
diff --git a/.gitignore b/.gitignore
index 25b9f4d..960377f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,5 @@
.swiftpm/
dist/
artifacts/codex-dumps/
+__pycache__/
+*.pyc
diff --git a/docs/exec-plans/active/20260419-official-cursor-motion-reconstruction.md b/docs/exec-plans/active/20260419-official-cursor-motion-reconstruction.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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())