Skip to content

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

feat: add standalone cursor motion lab

ifuryst3296e3287bda
diff --git a/Package.swift b/Package.swift
index 2316014..af25dc2 100644
--- a/Package.swift
+++ b/Package.swift
@@ -24,6 +24,10 @@ let package = Package(
name: "OpenComputerUseSmokeSuite",
targets: ["OpenComputerUseSmokeSuite"]
),
+ .executable(
+ name: "StandaloneCursorLab",
+ targets: ["StandaloneCursorLab"]
+ ),
],
targets: [
.target(
@@ -45,6 +49,13 @@ let package = Package(
dependencies: ["OpenComputerUseKit"],
path: "apps/OpenComputerUseSmokeSuite/Sources/OpenComputerUseSmokeSuite"
),
+ .executableTarget(
+ name: "StandaloneCursorLab",
+ path: "experiments/StandaloneCursorLab/Sources/StandaloneCursorLab",
+ resources: [
+ .process("Resources"),
+ ]
+ ),
.testTarget(
name: "OpenComputerUseKitTests",
dependencies: ["OpenComputerUseKit"],
diff --git a/README.md b/README.md
index a093589..0d8f5f5 100644
--- a/README.md
+++ b/README.md
@@ -56,6 +56,16 @@ open-computer-use doctor
open-computer-use -h
```
+## Cursor Lab
+
+This repo also includes an experimental standalone cursor-motion demo for iterating on the Codex-style software cursor without coupling every experiment to the MCP server:
+
+```bash
+swift run StandaloneCursorLab
+```
+
+The lab lives in [`experiments/StandaloneCursorLab`](./experiments/StandaloneCursorLab) and currently exposes tunable `START HANDLE`, `END HANDLE`, `ARC SIZE`, `ARC FLOW`, and `SPRING` controls.
+
## License
[MIT](./LICENSE)
diff --git a/README.zh-CN.md b/README.zh-CN.md
index e7fa0db..4b28ce3 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -61,6 +61,16 @@ open-computer-use doctor
open-computer-use -h
```
+## Cursor Lab
+
+仓库里现在还带了一个独立的 cursor motion 实验 demo,用来脱离 MCP 主链路单独调软件鼠标的轨迹和手感:
+
+```bash
+swift run StandaloneCursorLab
+```
+
+这个实验目录在 [`experiments/StandaloneCursorLab`](./experiments/StandaloneCursorLab),当前已经提供 `START HANDLE`、`END HANDLE`、`ARC SIZE`、`ARC FLOW`、`SPRING` 这组可调参数。
+
## License
[MIT](./LICENSE)
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 0375993..7219caa 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -18,6 +18,8 @@
- 键鼠输入模拟
- software cursor overlay
- fixture test bridge
+- `experiments/StandaloneCursorLab`
+ 独立的 Swift cursor motion lab,用于试验 `Bezier + arc + spring` 参数模型、调参 UI 和独立渲染,不直接耦合主 MCP runtime。
- `scripts/`
仓库级自动化命令,包括 smoke test、`.app` 打包入口、npm 分发脚本,以及 `scripts/computer-use-cli/` 这个用于探测官方 bundled `computer-use` 的 Go helper。
- `docs/`
@@ -71,6 +73,12 @@
- 对 fixture 的 `get_app_state` 和少量测试专用动作,会通过 `FixtureBridge` 走显式 command 通道。
- 这个 bridge 只服务于仓库内 deterministic smoke path,不是面向真实第三方 app 的能力边界。
+### 5. Cursor Lab
+
+- `StandaloneCursorLab` 是一个单独的 SwiftUI demo target,可通过 `swift run StandaloneCursorLab` 本地启动。
+- 这条线优先验证 motion model 本身:参数层、路径层、spring/timing 模拟和 debug UI。
+- 当前它不接真实 tool call,也不回写主 `SoftwareCursorOverlay`,目的是把实验噪音与产品行为边界隔离开。
+
## 关键边界
- 开源版当前不复刻官方闭源实现里的 caller signing、私有 IPC、完整 overlay choreography 和 plugin 自安装逻辑。
@@ -82,6 +90,7 @@
## 主要验证路径
- 单元测试:`swift test`
+- cursor lab 构建:`swift build --product StandaloneCursorLab`
- 端到端 smoke:`./scripts/run-tool-smoke-tests.sh`
- app 打包:`./scripts/build-open-computer-use-app.sh debug`
- npm staging:`node ./scripts/npm/build-packages.mjs`
diff --git a/docs/exec-plans/active/20260418-standalone-cursor-lab.md b/docs/exec-plans/active/20260418-standalone-cursor-lab.md
new file mode 100644
index 0000000..548c969
--- /dev/null
+++ b/docs/exec-plans/active/20260418-standalone-cursor-lab.md
@@ -0,0 +1,68 @@
+# Standalone Cursor Lab
+
+## 目标
+
+在当前仓库内落一个与主 `OpenComputerUseKit` 解耦的独立目录,用 Swift 实现一版可调参的软件 cursor motion demo,用来逼近官方视频里的手感,并为后续单独开源做准备。
+
+## 范围
+
+- 包含:
+- 新建独立目录承载 cursor motion 实验,不直接污染主 MCP runtime。
+- 把 motion model 拆成参数层、路径层、时间模拟层、渲染层。
+- 做一个本地可运行的 demo,至少支持起点/终点、轨迹预览、参数滑杆和点击触发。
+- 把本轮逆向分析沉淀到 `docs/references/`。
+- 不包含:
+- 本轮不要求接入真实 `click` tool。
+- 本轮不要求完全复刻官方闭源素材。
+- 本轮不要求把 demo 立即发布成独立仓库。
+
+## 背景
+
+- 用户提供了 X 视频样本,明确出现 `START HANDLE`、`END HANDLE`、`ARC SIZE`、`ARC FLOW`、`SPRING` 调参项。
+- `SkyComputerUseService` 字符串已出现 `BezierParameters`、`SpringParameters`、`arcHeight`、`arcIn`、`arcOut`、`cursorMotionProgressAnimation` 等证据。
+- 当前仓库已有 `SoftwareCursorOverlay.swift`,但它更像产品内近似实现,不适合继续承载大量调参与实验 UI。
+
+## 风险
+
+- 风险:过早把实验代码下沉到主包,导致主线 overlay 行为反复波动。
+- 缓解方式:先放独立目录,稳定后再抽公共模块。
+- 风险:只凭视频调参,可能把“视觉像”误当成“结构对”。
+- 缓解方式:优先围绕已确认字段名建模,不做纯拍脑袋参数命名。
+- 风险:demo UI 和未来独立开源边界不清。
+- 缓解方式:第一阶段只做最小可运行 lab,避免提前引入和 MCP/tool 相关的耦合。
+
+## 里程碑
+
+1. 建立独立目录与 README,明确模块边界。
+2. 实现纯参数化路径生成与可视化。
+3. 补 spring/timing 模拟。
+4. 视效果再决定是否回灌主 overlay。
+
+## 验证方式
+
+- 能独立运行本地 demo。
+- 能通过 slider 实时改变轨迹几何和停驻手感。
+- 仓库文档能说明该目录与主产品代码的边界。
+
+## 进度记录
+
+- [x] 里程碑 1
+- [x] 里程碑 2
+- [x] 里程碑 3
+- [ ] 里程碑 4
+
+## 最新进展
+
+- 2026-04-18:已补齐点击任意位置触发候选路径预览,不再局限于 replay。
+- 2026-04-18:已修正 click capture 的坐标系和事件覆盖问题,底部区域不再因为额外矩形排除区而出现隐藏死区。
+- 2026-04-18:已把 `DEBUG` toggle 的开启态改成明显高亮,并把 controls 改成最小 overlay 布局,避免透明容器阻挡画布点击。
+- 2026-04-18:已把路径模型升级为“line direction + cursor heading”混合约束,并新增 `turn` / `brake` 候选族,选中的主路径开始具备更明显的先顺头部方向、再回咬目标的走势。
+- 2026-04-18:已把 timing 从 spring + `easeInOut` 改为 minimum-jerk bell-shaped profile,并移除位置层末端 overshoot;cursor 在运动中持续跟随切线朝向,到点阶段再平滑回正。
+- 2026-04-19:已为路径建立 curvature / heading-change 加权的 effort lookup,进度推进不再直接绑定 Bezier 参数 `t`,从而让高曲率转向段更慢、直线段更快。
+- 2026-04-19:已把 standalone lab 的 cursor 切到资源化 PNG asset,并改成 tip-anchor 驱动的命中点对齐;静止姿态与运动姿态共用一套 heading calibration,运动中持续朝向当前切线方向。
+
+## 决策记录
+
+- 2026-04-18:先把这项工作定义为 standalone lab,而不是继续直接堆进 `OpenComputerUseKit`.
+- 2026-04-18:参数命名优先采用视频 UI 与官方字符串的交集:`start/end handle`、`arc size/flow`、`spring`。
+- 2026-04-18:第一版 demo 先用独立 SwiftUI target + `CVDisplayLink` 驱动模拟,优先验证参数语义和轨迹手感,再考虑与主 overlay 合流。
diff --git a/docs/histories/2026-04/20260418-1430-standalone-cursor-lab.md b/docs/histories/2026-04/20260418-1430-standalone-cursor-lab.md
new file mode 100644
index 0000000..1f157be
--- /dev/null
+++ b/docs/histories/2026-04/20260418-1430-standalone-cursor-lab.md
@@ -0,0 +1,44 @@
+## [2026-04-18 14:30] | Task: 落独立 cursor motion lab
+
+### 🤖 Execution Context
+* **Agent ID**: `codex`
+* **Base Model**: `gpt-5`
+* **Runtime**: `Codex CLI`
+
+### 📥 User Query
+> 结合官方视频和已分析到的 cursor overlay 线索,在当前仓库里单独开一个目录,实现一版可独立开源的软件鼠标曲线,并继续推进分析与落地。
+
+### 🛠 Changes Overview
+**Scope:** `Package.swift`、`experiments/StandaloneCursorLab/`、`docs/`、`README`
+
+**Key Actions:**
+- **[新增独立 target]**: 把 `StandaloneCursorLab` 加入 Swift Package,可通过 `swift run StandaloneCursorLab` 单独运行。
+- **[实现 motion demo]**: 新增参数化 cursor motion model、Bezier 路径生成、spring/timing 模拟和 SwiftUI 调参界面。
+- **[补齐点击交互]**: 支持点击画布任意位置生成多条候选路径,并选中一路径驱动 cursor 动画。
+- **[收敛候选曲线与显示逻辑]**: 扩展为多组 descriptor 驱动的轨迹族,并让主路径在关闭 `DEBUG` 时继续可见。
+- **[修正点击坐标与死区]**: 统一 AppKit click-capture 和 SwiftUI 画布的坐标语义,去掉误导性的矩形事件排除区,避免底部区域出现“点了不动”的隐藏死区。
+- **[收敛 demo 控件状态]**: 把 `DEBUG` toggle 的开启态改为明确高亮,并让顶部 controls 只占自身区域,不再靠整层透明容器遮挡画布事件。
+- **[增强 turn/brake 手感]**: 把路径生成从“只看起终点连线”改成“线方向 + cursor 朝向”的混合约束,并新增 `turn` / `brake` family,让主路径更容易出现先顺头部方向、再掉头切入、末端带刹车回咬的走势。
+- **[重做 timing / rotation]**: 把进度推进从 spring + `easeInOut` 改成更接近人手 pointing 的 minimum-jerk bell-shaped timing;同时让 cursor 在运动过程中持续朝向切线方向,并在到点阶段平滑回归经典朝向。
+- **[移除末端多余位移]**: 删除位置层的 settle overshoot,保留连续移动和自然减速,不再在最后额外挪一下。
+- **[加入 curvature-aware timing]**: 为路径建立 weighted-effort lookup,把高曲率和大 heading-change 的片段映射为更慢的时间推进,让“起步掉头”和“末端收束”阶段获得更自然的速度分配,而不是直接用 Bezier 参数 `t` 均匀走完。
+- **[切到资源化 cursor asset]**: 把 standalone lab 的矢量箭头切换为 target 内置 PNG 资源,建立单独的 glyph calibration,并把静止姿态收敛到接近视频里的默认朝向。
+- **[改为 tip-anchor 命中对齐]**: 不再拿整张 cursor 图的中心做定位,而是把图像 tip 对齐到 motion sample point,避免更换为朝上型 asset 后重新出现点击坐标偏移。
+- **[收敛运动中朝向跟随]**: 把 motion simulator 的 rotation 统一为基于 glyph neutral heading 的绝对姿态,运动时持续追随曲线切线方向,结束时再平滑回到静止角度。
+- **[同步仓库知识]**: 补 motion model 逆向分析文档、active execution plan、架构说明、README 入口和 history。
+
+### 🧠 Design Intent (Why)
+主线 `SoftwareCursorOverlay` 更适合承载产品行为,不适合继续堆调参与实验 UI。这次把 cursor 曲线实验拆成独立 lab,是为了先稳定参数模型和视觉手感,再决定哪些部分适合回灌主 MCP 实现或单独开源。
+
+### 📁 Files Modified
+- `Package.swift`
+- `README.md`
+- `README.zh-CN.md`
+- `docs/ARCHITECTURE.md`
+- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
+- `docs/references/codex-computer-use-reverse-engineering/README.md`
+- `docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-model.md`
+- `experiments/StandaloneCursorLab/README.md`
+- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift`
+- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
+- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/StandaloneCursorLabApp.swift`
diff --git a/docs/histories/2026-04/20260419-1320-deepen-official-cursor-motion-analysis.md b/docs/histories/2026-04/20260419-1320-deepen-official-cursor-motion-analysis.md
new file mode 100644
index 0000000..3b562a4
--- /dev/null
+++ b/docs/histories/2026-04/20260419-1320-deepen-official-cursor-motion-analysis.md
@@ -0,0 +1,26 @@
+## [2026-04-19 13:20] | Task: 深挖官方 cursor motion 静态模型
+
+### 🤖 Execution Context
+* **Agent ID**: `codex`
+* **Base Model**: `gpt-5`
+* **Runtime**: `Codex CLI`
+
+### 📥 User Query
+> 继续分析官方 `Codex Computer Use.app`,重点看 `calculates natural and aesthetic motion paths` 相关算法,尽量从 app 里找到曲线和速度怎么计算。
+
+### 🛠 Changes Overview
+**Scope:** `docs/references/codex-computer-use-reverse-engineering/`、`docs/histories/`
+
+**Key Actions:**
+- **[补强静态分析证据]**: 对 `SkyComputerUseService` 的 `__swift5_types` / `__swift5_fieldmd` 做静态恢复,不再只依赖 `strings` 关键词。
+- **[确认 cursor path 类型]**: 文档新增 `ComputerUseCursor`、`Window`、`Style`、`CloseEnoughConfiguration`、`CursorNextInteractionTiming`、`CursorMotionPathMeasurement`、`Segment`、`CursorMotionPath` 的字段级证据。
+- **[确认 timing / spring 类型]**: 文档新增 `BezierAnimation`、`SpringAnimation`、`BezierFunction`、`BezierParameters`、`SpringParameters`、`VelocityVerletSimulation`、`Configuration`、`AnimationDescriptor` 的字段级证据。
+- **[修正旧推断]**: 把此前把 `ARC SIZE` 直接映射到 `arcHeight` 的说法降级,改为更保守地映射到 cursor path 的 `arc` / 控制点偏移。
+- **[明确 next-interaction gate]**: 基于 `CloseEnoughConfiguration(progressThreshold, distanceThreshold)` 和 `CursorNextInteractionTiming(closeEnough, finished)`,补充“动画未完全结束即可进入下一交互”的 timing 机制判断。
+
+### 🧠 Design Intent (Why)
+之前 motion model 文档主要停留在“看到哪些字符串,所以推测有哪些层”的阶段。这次把 Swift 元数据也解析出来,是为了把曲线与速度模型从概念推断推进到字段级证据,减少后续开源实现时把官方结构猜错的概率。
+
+### 📁 Files Modified
+- `docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-model.md`
+- `docs/histories/2026-04/20260419-1320-deepen-official-cursor-motion-analysis.md`
diff --git a/docs/references/codex-computer-use-reverse-engineering/README.md b/docs/references/codex-computer-use-reverse-engineering/README.md
index 0676d1c..4b731b5 100644
--- a/docs/references/codex-computer-use-reverse-engineering/README.md
+++ b/docs/references/codex-computer-use-reverse-engineering/README.md
@@ -16,6 +16,10 @@
- 2026-04-17 对 9 个公开 `computer-use` tools 的实测 request / response 样本。
- `software-cursor-overlay.md`
- 对黄色虚拟鼠标 overlay 的资源、字符串和运行时窗口证据分析。
+- `software-cursor-motion-model.md`
+ - 结合视频样本、官方字符串和当前开源实现,对 cursor motion 参数模型的推断。
+- `software-cursor-motion-reconstruction.md`
+ - 继续下钻到函数级后,对 `CursorMotionPath.sample(progress)`、`CursorMotionPathMeasurement` 和候选路径枚举线索的重建说明。
- `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-model.md b/docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-model.md
new file mode 100644
index 0000000..33248ed
--- /dev/null
+++ b/docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-model.md
@@ -0,0 +1,405 @@
+# Software Cursor Motion Model
+
+这个文档聚焦软件 cursor 的“运动模型”本身,不再只讨论 overlay window 是否存在,而是回答另一个更具体的问题:官方演示里那条自然、可调、带一点弹性的鼠标曲线,当前已经能从哪些证据反推出结构。
+
+结论先写在前面:结合视频、`SkyComputerUseService` 字符串,以及这次直接从 `__swift5_types` / `__swift5_fieldmd` 恢复出的类型和字段,可以比较有把握地判断官方不是只做了一条固定 cubic Bezier,而是做了一层独立的 motion engine,至少包含 3 层:
+
+- 一层路径几何模型:`CursorMotionPath` + `Segment`。
+- 一层逐帧动画/物理推进:`BezierAnimation` + `SpringAnimation` + `VelocityVerletSimulation`。
+- 一层“下一次交互何时允许开始”的 timing gate:`CloseEnoughConfiguration` + `CursorNextInteractionTiming`。
+
+## 已观察事实
+
+### 1. 视频里有显式的调参 UI
+
+用户提供的 X 视频里,左上角能稳定看到 5 个 slider:
+
+- `START HANDLE`
+- `END HANDLE`
+- `ARC SIZE`
+- `ARC FLOW`
+- `SPRING`
+
+右上角能看到 3 个 toggle:
+
+- `DEBUG`
+- `MAIL`
+- `CLICK`
+
+这说明至少在官方内部调试构建里,cursor motion 不是黑盒常量,而是一组可实时调的参数。
+
+### 2. `SkyComputerUseService` 里不仅有字符串,还有可恢复的 Swift motion 类型
+
+这次除了 `strings`,还额外做了两步:
+
+- 用 `otool -l` 确认 `__swift5_typeref`、`__swift5_reflstr`、`__swift5_fieldmd`、`__swift5_types` 这些 section 的位置。
+- 解析 `__swift5_types` 中的 type descriptor,再反查 `__swift5_fieldmd`,把 field descriptor 归回具体类型名。
+
+这样拿到的不再只是零散关键词,而是“哪个类型拥有哪些字段”的证据。
+
+#### Cursor 路径与状态相关类型
+
+从 `SkyComputerUseService` 静态恢复出的核心类型和字段如下:
+
+```text
+ComputerUseCursor
+ delegate
+ targetWindowID
+ isMoving
+ shouldFadeOut
+ window
+ correspondingApplicationPID
+ style
+ activityState
+
+Window
+ style
+ appMonitor
+ wantsToBeVisible
+ cursorMotionProgressAnimation
+ cursorMotionNextInteractionTimingHandler
+ cursorMotionCompletionHandler
+ cursorMotionDidSatisfyNextInteractionTiming
+ currentInterpolatedOrigin
+ useOverlayWindowLevel
+ correspondingWindowID
+
+Style
+ velocityX
+ velocityY
+ isPressed
+ activityState
+ isAttached
+ angle
+
+CloseEnoughConfiguration
+ progressThreshold
+ distanceThreshold
+
+CursorNextInteractionTiming
+ closeEnough
+ finished
+
+ActivityState
+ idle
+ loading
+ paused
+
+CursorMotionPathMeasurement
+ length
+ angleChangeEnergy
+ maxAngleChange
+ totalTurn
+ staysInBounds
+
+Segment
+ end
+ control1
+ control2
+
+CursorMotionPath
+ start
+ end
+ startControl
+ arc
+ arcIn
+ arcOut
+ endControl
+ segments
+```
+
+这批字段把几件事基本坐实了:
+
+- 官方 cursor path 不是一个写死的单段 cubic,而是一个 `CursorMotionPath`,里面显式保存 `segments`。
+- 每个 `Segment` 自己再带 `control1` / `control2` / `end`,说明底层仍是 cubic Bezier,但高层路径可以由多段组成。
+- path 旁边还有一份 `CursorMotionPathMeasurement`,字段不是只有长度,而是 `angleChangeEnergy`、`maxAngleChange`、`totalTurn` 和 `staysInBounds`。这强烈说明官方会对候选路径做几何质量评分,而不是简单取一条。
+- `CloseEnoughConfiguration(progressThreshold, distanceThreshold)` 加上 `CursorNextInteractionTiming(closeEnough, finished)`,说明官方明确建模了“动画还没完全结束,但已经够接近,可以允许下一次交互”的状态。
+
+#### 动画与速度推进相关类型
+
+`SkyComputerUseService` 同时还带着一套独立的动画模块:
+
+```text
+BezierAnimation
+ parameters
+
+Parameters
+ curve
+ duration
+
+InterpolatableAnimation
+ id
+ _value
+ _targetValue
+ eventHandler
+ state
+ _initialValue
+ startTime
+
+SpringAnimation
+ simulation
+
+BezierFunction
+ x1
+ x2
+ y1
+ y2
+ cx
+ cy
+ bx
+ by
+ ax
+ ay
+
+BezierParameters
+ curve
+ duration
+
+SpringParameters
+ response
+ dampingFraction
+
+VelocityVerletSimulation
+ configuration
+ time
+ velocity
+ force
+
+Configuration
+ response
+ stiffness
+ drag
+ dt
+ idleVelocityThreshold
+
+AnimationDescriptor
+ bezier
+ spring
+```
+
+这里最关键的不是名字本身,而是字段组合:
+
+- `BezierParameters(curve, duration)` 说明 time progression 确实有一层显式的 Bezier timing,而不是只靠系统默认 easing。
+- `BezierFunction(x1, x2, y1, y2, cx, cy, bx, by, ax, ay)` 说明这层 Bezier 不是抽象关键词,而是实际把 cubic 多项式系数预展开了。
+- `SpringParameters(response, dampingFraction)` 是用户可调或上层可配置的 spring 输入。
+- `VelocityVerletSimulation(configuration, time, velocity, force)` 和 `Configuration(response, stiffness, drag, dt, idleVelocityThreshold)` 则几乎可以确认底层不是一次性解析函数,而是 display-link 驱动的逐帧物理模拟。
+
+### 3. `Fog` / `wiggle` 也不是口头说法,而是独立 view model
+
+这次还能直接看到一组和“思考时轻微摇摆”“fog 光晕”对应的类型:
+
+```text
+FogCursorViewModel
+ _velocityX
+ _velocityY
+ _isPressed
+ _activityState
+ _isAttached
+ _angle
+
+CursorView
+ viewModel
+ cursorRadius
+ _animatedAngleOffsetDegrees
+ _loadingAnimationToken
+ fogRadius
+ cursorScaleAnchorPoint
+ fogScaleAnchorPoint
+```
+
+这说明:
+
+- 光标朝向确实是速度驱动的,不是纯位置插值。
+- “thinking wiggle” 至少在渲染层有专门的 `_animatedAngleOffsetDegrees` 和 `_loadingAnimationToken`。
+- fog 也不是简单阴影,而是单独建模了 `fogRadius` 和对应的 scale anchor。
+
+### 4. 当前开源仓库已有一版较简化的近似实现
+
+`packages/OpenComputerUseKit/Sources/OpenComputerUseKit/SoftwareCursorOverlay.swift` 当前已经具备:
+
+- 基于起终点生成多组 cubic Bezier 候选。
+- 按目标 `windowID` 做采样命中,筛掉明显飘出目标窗口的路径。
+- 路径切线驱动的 cursor 旋转。
+- click pulse 与 idle sway。
+
+但它还没有显式建模这些官方证据里已出现的参数:
+
+- `start handle`
+- `end handle`
+- path 分段与 turn-energy 评分
+- `arc flow`
+- `spring`
+
+也没有“带速度状态的 spring settle”和“下一交互 timing gate”。
+
+## 现在可以比较确定的结构判断
+
+下面这部分仍然带推断成分,但已经不是“纯猜”,而是基于上面的静态类型证据。
+
+### 1. 曲线怎么计算
+
+目前最合理的结构是:
+
+1. 先构造一个高层 `CursorMotionPath`。
+2. 这个 path 至少包含:
+ - `start`
+ - `end`
+ - `startControl`
+ - `endControl`
+ - `arc`
+ - `arcIn`
+ - `arcOut`
+ - `segments`
+3. 再把 path 展开成一组具体 `Segment`。
+4. 每个 `Segment` 再用 `control1` / `control2` / `end` 生成实际 cubic Bezier。
+5. 然后对整条 path 计算 `CursorMotionPathMeasurement`:
+ - `length`
+ - `angleChangeEnergy`
+ - `maxAngleChange`
+ - `totalTurn`
+ - `staysInBounds`
+6. 只有满足质量和 window 命中约束的路径,才会被接受并开播。
+
+这比“从起点到终点直接拉一条单段 cubic”要复杂得多,也更接近团队成员说的 `calculates natural and aesthetic motion paths`。
+
+### 2. 速度怎么推进
+
+从类型和字段看,速度推进大概率不是“沿 Bezier 参数 `t` 匀速跑”,而是:
+
+1. 用 `BezierAnimation` / `BezierParameters(curve, duration)` 控制一段基础进度。
+2. 在需要弹性和停驻手感的阶段,再叠 `SpringAnimation`。
+3. spring 本体通过 `VelocityVerletSimulation` 按帧迭代:
+ - 维护 `time`
+ - 维护当前 `velocity`
+ - 维护当前 `force`
+ - 按 `Configuration(response, stiffness, drag, dt, idleVelocityThreshold)` 推进
+4. `DisplayLinkAnimationDriver(displayLink)` 负责逐帧驱动。
+
+`VelocityVerletSimulation` 这个名字尤其关键,因为它已经把“用什么数值方法跑 spring”暴露出来了。就现有证据看,官方更像是在做逐帧积分,而不是单纯调用一个现成的 `CASpringAnimation` 然后交给系统黑盒求值。
+
+### 3. 什么时候允许下一次交互开始
+
+`CloseEnoughConfiguration(progressThreshold, distanceThreshold)` 和 `CursorNextInteractionTiming(closeEnough, finished)` 这组类型,说明官方把“动作已足够接近,可继续下一步”和“动作完全结束”明确区分开了。
+
+这意味着:
+
+- 视觉动画还没完全 settle 时,系统可能已经允许模型进入下一次 tool interaction。
+- 这个 gate 至少会同时看两件事:
+ - 已经跑过了多少进度 `progressThreshold`
+ - 离目标还剩多少距离 `distanceThreshold`
+
+这比“每次都傻等动画播完再继续”更贴近官方演示里那种连续、不断句的操作感。
+
+## 参数映射的修正判断
+
+和上一版文档相比,这里有一处重要修正。
+
+### `START HANDLE`
+
+现在看,最可能映射到 `CursorMotionPath.startControl`,以及最终分段 cubic 上的 `control1`。
+
+### `END HANDLE`
+
+现在看,最可能映射到 `CursorMotionPath.endControl`,以及最终分段 cubic 上的 `control2`。
+
+### `ARC SIZE`
+
+上一版把它直接映射到 `arcHeight`,这个判断现在要降级。
+
+新的证据显示:
+
+- cursor path 本体字段里确认到的是 `arc`、`arcIn`、`arcOut`。
+- `arcHeight` 目前只在 `SystemSettingsAccessoryTransitionGeometryStyle` 上被确认,不像 cursor path 本体字段。
+
+所以更保守的说法是:`ARC SIZE` 更可能先作用在 `CursorMotionPath.arc` 或分段控制点偏移量上,而不是已经能直接确认是某个叫 `arcHeight` 的 cursor 字段。
+
+### `ARC FLOW`
+
+这条判断比上一版更稳了,因为 `CursorMotionPath` 里确实存在 `arcIn` / `arcOut`:
+
+- `arcIn` 大概率控制起点侧进入主弧线的节奏。
+- `arcOut` 大概率控制终点侧回收至目标的节奏。
+- `ARC FLOW` 大概率是在这两个量之间做重分配。
+
+### `SPRING`
+
+这条也比上一版更具体了。现在可以把它落到一整套链路上:
+
+- 上层参数:`SpringParameters(response, dampingFraction)`
+- 运行时模拟:`VelocityVerletSimulation`
+- 模拟配置:`Configuration(response, stiffness, drag, dt, idleVelocityThreshold)`
+
+## 对独立实现的设计启发
+
+如果要在当前仓库里抽一个后续可独立开源的版本,建议不要再把所有逻辑继续塞进 `SoftwareCursorOverlay`,而是拆成 4 层:
+
+### 1. Motion Parameters
+
+纯值类型,不依赖 AppKit。
+
+建议至少包含:
+
+- `startHandle`
+- `endHandle`
+- `arcHeight`
+- `arcFlow`
+- `spring`
+
+### 2. Motion Path Builder
+
+输入起点、终点和参数,产出:
+
+- `CursorMotionPath`
+- `segments`
+- `control1`
+- `control2`
+- `measurement`
+- 切线
+
+这里单独负责几何,不负责时间。
+
+### 3. Motion Simulator
+
+在路径几何之上叠时间推进:
+
+- Bezier progress animation
+- spring simulation
+- velocity
+- force
+- next-interaction timing gate
+- completion timing
+
+### 4. Cursor Renderer / Demo Host
+
+最外层才接 AppKit / SwiftUI,负责:
+
+- overlay window
+- debug slider UI
+- target point 标注
+- click / mail / debug toggle
+
+## 对仓库落点的建议
+
+为了后续独立开源更干净,这块建议先作为单独目录推进,而不是直接和 MCP runtime 耦合:
+
+- 目录建议:`experiments/StandaloneCursorLab/`
+- 第一阶段先做一个纯本地 demo app,不接真实 tool call。
+- 等参数模型稳定后,再决定是否把其中的 `Motion Parameters` / `Path Builder` 下沉回 `packages/` 复用。
+
+这样可以避免两个问题:
+
+- 为了追官方手感,反复改动线上 `click` overlay。
+- demo/调参 UI 代码污染主产品边界。
+
+## 当前判断
+
+当前最合理的独立实现方向不是“继续微调现有候选 Bezier 权重”,而是:
+
+1. 先把 motion model 从 overlay 渲染里拆出来。
+2. 明确把 `handle`、`arc`、`spring`、`closeEnough timing` 建模成一等参数。
+3. 把 path builder 做成“多段 cubic + measurement”而不是单段模板曲线。
+4. 把 timing simulator 做成“Bezier progress + spring settle + velocity state”。
+5. 做一个带 slider/toggle 的本地 Swift demo。
+6. 用这个 demo 逼近视频里的轨迹和停驻手感。
+
+只有这样,后面这个目录才真的适合单独开源。
diff --git a/experiments/StandaloneCursorLab/README.md b/experiments/StandaloneCursorLab/README.md
new file mode 100644
index 0000000..b2b55db
--- /dev/null
+++ b/experiments/StandaloneCursorLab/README.md
@@ -0,0 +1,51 @@
+# Standalone Cursor Lab
+
+这个目录用于实现一个可独立演进、后续可单独开源的软件 cursor motion demo。
+
+当前目标不是替换仓库主线的 `SoftwareCursorOverlay`,而是先把“轨迹几何 + 时序弹性 + 调参 UI”从主产品代码里拆出来,做成一个更适合试验和对比的视频 lab。
+
+## 为什么单独放这里
+
+- 主线 `packages/OpenComputerUseKit/.../SoftwareCursorOverlay.swift` 已经承担产品行为,不适合继续塞大量实验代码。
+- 用户提供的视频和官方字符串都说明 cursor motion 有独立参数模型,适合先做一个 lab。
+- 这块后续可能单独开源,先在目录边界上收口更干净。
+
+## 计划中的模块
+
+- `Sources/MotionModel/`
+ - 参数定义,例如 `startHandle`、`endHandle`、`arcSize`、`arcFlow`、`spring`
+- `Sources/PathBuilder/`
+ - 根据起点、终点和参数生成可采样曲线
+- `Sources/Simulator/`
+ - 负责路径进度、spring settle、timing
+- `Sources/App/`
+ - 本地 demo UI、debug slider、toggle、目标点交互
+
+## 当前参考
+
+- `docs/references/codex-computer-use-reverse-engineering/software-cursor-overlay.md`
+- `docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-model.md`
+- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
+
+## 当前状态
+
+当前已经有一个可运行的 SwiftUI demo target:
+
+```bash
+swift run StandaloneCursorLab
+```
+
+现阶段支持:
+
+- 点击画布任意位置,先预览多条候选路径,再自动选一路径并驱动 cursor 过去。
+- 拖动起点和终点。
+- 实时调 `START HANDLE`、`END HANDLE`、`ARC SIZE`、`ARC FLOW`、`SPRING`。
+- 预览 Bezier 主路径、控制柄和 cursor 动画。
+- 使用 target 自带资源里的 cursor asset 渲染指针,并用 tip-anchor 而不是整张图中心来对齐点击点。
+- cursor 在运动过程中持续跟随当前切线方向,结束后再回到静止姿态。
+
+后续实现应优先保持:
+
+- 参数层不依赖 AppKit。
+- 几何层和时间层分离。
+- demo host 可以替换,但 motion model 可以单独复用。
diff --git a/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorGlyphCalibration.swift b/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorGlyphCalibration.swift
new file mode 100644
index 0000000..1f3869d
--- /dev/null
+++ b/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorGlyphCalibration.swift
@@ -0,0 +1,31 @@
+import AppKit
+import CoreGraphics
+
+enum CursorGlyphCalibration {
+ static let neutralHeading = -CGFloat.pi / 2
+ static let restingRotation = -26.5 * CGFloat.pi / 180
+}
+
+enum CursorGlyphArtwork {
+ static let layoutSize = CGSize(width: 72, height: 72)
+ static let imageSize = CGSize(width: 34, height: 34)
+ static let imageOrigin = CGPoint(
+ x: (layoutSize.width - imageSize.width) * 0.5,
+ y: 8
+ )
+ static let tipAnchor = CGPoint(
+ x: imageOrigin.x + (imageSize.width * 0.5),
+ y: imageOrigin.y + 1
+ )
+ static let contentOffset = CGSize(
+ width: (layoutSize.width * 0.5) - tipAnchor.x,
+ height: (layoutSize.height * 0.5) - tipAnchor.y
+ )
+
+ static let image: NSImage? = {
+ guard let url = Bundle.module.url(forResource: "StandaloneCursorPointer", withExtension: "png") else {
+ return nil
+ }
+ return NSImage(contentsOf: url)
+ }()
+}
diff --git a/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift b/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift
new file mode 100644
index 0000000..ccc470d
--- /dev/null
+++ b/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift
@@ -0,0 +1,607 @@
+import AppKit
+import QuartzCore
+import SwiftUI
+
+struct CursorLabRootView: View {
+ @State private var parameters = CursorMotionParameters.default
+ @State private var start = CGPoint(x: 220, y: 440)
+ @State private var end = CGPoint(x: 860, y: 260)
+ @State private var debugEnabled = true
+ @State private var mailEnabled = false
+ @State private var clickEnabled = true
+ @StateObject private var model = CursorLabViewModel()
+
+ var body: some View {
+ GeometryReader { proxy in
+ ZStack {
+ CursorLabBackground()
+
+ CursorLabCanvas(
+ start: $start,
+ end: $end,
+ debugEnabled: debugEnabled,
+ showClickPulse: clickEnabled,
+ model: model
+ )
+ .onAppear {
+ model.configure(start: start, end: end, parameters: parameters)
+ model.restart()
+ }
+ .onChange(of: proxy.size) { _, newSize in
+ clampPoints(to: newSize)
+ model.configure(start: start, end: end, parameters: parameters)
+ }
+ .onChange(of: start) { _, newValue in
+ model.updateStart(newValue)
+ }
+ .onChange(of: end) { _, newValue in
+ model.queueMove(to: newValue)
+ }
+ .onChange(of: parameters) { _, newValue in
+ model.updateParameters(newValue)
+ }
+ }
+ .overlay(alignment: .topLeading) {
+ controlPanel
+ .padding(24)
+ }
+ .overlay(alignment: .topTrailing) {
+ togglePanel
+ .padding(24)
+ }
+ }
+ }
+
+ private var controlPanel: some View {
+ VStack(alignment: .leading, spacing: 10) {
+ CursorSliderRow(title: "START HANDLE", value: $parameters.startHandle)
+ CursorSliderRow(title: "END HANDLE", value: $parameters.endHandle)
+ CursorSliderRow(title: "ARC SIZE", value: $parameters.arcSize)
+ CursorSliderRow(title: "ARC FLOW", value: $parameters.arcFlow, accent: Color(red: 0.92, green: 0.22, blue: 0.58))
+ CursorSliderRow(title: "SPRING", value: $parameters.spring)
+
+ Button("REPLAY") {
+ model.replayCurrentSelection()
+ }
+ .buttonStyle(CursorActionButtonStyle())
+ .padding(.top, 6)
+ }
+ }
+
+ private var togglePanel: some View {
+ VStack(alignment: .trailing, spacing: 12) {
+ CursorToggleRow(title: "DEBUG", isOn: $debugEnabled)
+ CursorToggleRow(title: "MAIL", isOn: $mailEnabled)
+ CursorToggleRow(title: "CLICK", isOn: $clickEnabled)
+ }
+ }
+
+ private func clampPoints(to size: CGSize) {
+ let inset: CGFloat = 80
+ start.x = min(max(start.x, inset), size.width - inset)
+ start.y = min(max(start.y, inset), size.height - inset)
+ end.x = min(max(end.x, inset), size.width - inset)
+ end.y = min(max(end.y, inset), size.height - inset)
+ }
+}
+
+@MainActor
+final class CursorLabViewModel: ObservableObject {
+ @Published private(set) var path = CursorMotionPathBuilder.makePath(
+ from: CGPoint(x: 220, y: 440),
+ to: CGPoint(x: 860, y: 260),
+ parameters: .default
+ )
+ @Published private(set) var candidates: [CursorMotionCandidate] = []
+ @Published private(set) var selectedCandidateID: String?
+ @Published private(set) var currentState = CursorMotionState(
+ point: CGPoint(x: 220, y: 440),
+ rotation: CursorGlyphCalibration.restingRotation,
+ trailProgress: 0,
+ isSettled: false
+ )
+ @Published private(set) var clickPulse: CGFloat = 0
+
+ private var simulator = CursorMotionSimulator(
+ start: CGPoint(x: 220, y: 440),
+ end: CGPoint(x: 860, y: 260),
+ parameters: .default
+ )
+ private var displayLink: CVDisplayLink?
+ private var lastTimestamp: CFTimeInterval?
+ private var previewRemaining: CGFloat = 0
+ private var queuedTarget: CGPoint?
+
+ func configure(start: CGPoint, end: CGPoint, parameters: CursorMotionParameters) {
+ simulator.reset(start: start, end: end, parameters: parameters)
+ path = simulator.path
+ candidates = CursorMotionPathBuilder.makeCandidatePaths(
+ from: start,
+ to: end,
+ parameters: parameters,
+ startRotation: currentState.rotation
+ )
+ selectedCandidateID = candidates.first?.id
+ currentState = CursorMotionState(point: start, rotation: CursorGlyphCalibration.restingRotation, trailProgress: 0, isSettled: false)
+ clickPulse = 0
+ }
+
+ func updateStart(_ value: CGPoint) {
+ simulator.reset(start: value)
+ path = simulator.path
+ candidates = CursorMotionPathBuilder.makeCandidatePaths(
+ from: value,
+ to: simulator.end,
+ parameters: simulator.parameters,
+ startRotation: currentState.rotation
+ )
+ selectedCandidateID = candidates.first?.id
+ currentState = CursorMotionState(point: value, rotation: currentState.rotation, trailProgress: 0, isSettled: false)
+ }
+
+ func queueMove(to value: CGPoint) {
+ queuedTarget = value
+ let origin = currentAnchorPoint
+ let startRotation = currentState.rotation
+ candidates = CursorMotionPathBuilder.makeCandidatePaths(
+ from: origin,
+ to: value,
+ parameters: simulator.parameters,
+ startRotation: startRotation
+ )
+ selectedCandidateID = candidates.first?.id
+ path = candidates.first?.path ?? CursorMotionPathBuilder.makePath(
+ from: origin,
+ to: value,
+ parameters: simulator.parameters,
+ startRotation: startRotation
+ )
+ currentState = CursorMotionState(point: origin, rotation: currentState.rotation, trailProgress: 0, isSettled: false)
+ clickPulse = 0
+ previewRemaining = 0.24
+ lastTimestamp = nil
+ ensureDisplayLink()
+ }
+
+ func updateParameters(_ value: CursorMotionParameters) {
+ simulator.reset(parameters: value)
+ if let queuedTarget {
+ queueMove(to: queuedTarget)
+ } else {
+ candidates = CursorMotionPathBuilder.makeCandidatePaths(
+ from: currentAnchorPoint,
+ to: simulator.end,
+ parameters: value,
+ startRotation: currentState.rotation
+ )
+ selectedCandidateID = candidates.first?.id
+ path = candidates.first?.path ?? simulator.path
+ currentState = CursorMotionState(point: currentAnchorPoint, rotation: currentState.rotation, trailProgress: 0, isSettled: false)
+ clickPulse = 0
+ }
+ }
+
+ func restart() {
+ replayCurrentSelection()
+ }
+
+ func replayCurrentSelection() {
+ let target = queuedTarget ?? simulator.end
+ queueMove(to: target)
+ }
+
+ private func ensureDisplayLink() {
+ guard displayLink == nil else {
+ return
+ }
+
+ var link: CVDisplayLink?
+ CVDisplayLinkCreateWithActiveCGDisplays(&link)
+ guard let link else {
+ return
+ }
+
+ let callback: CVDisplayLinkOutputCallback = { _, _, _, _, _, userInfo in
+ guard let userInfo else {
+ return kCVReturnSuccess
+ }
+
+ let viewModel = Unmanaged<CursorLabViewModel>.fromOpaque(userInfo).takeUnretainedValue()
+ Task { @MainActor in
+ viewModel.tick()
+ }
+ return kCVReturnSuccess
+ }
+
+ CVDisplayLinkSetOutputCallback(link, callback, Unmanaged.passUnretained(self).toOpaque())
+ displayLink = link
+ CVDisplayLinkStart(link)
+ }
+
+ private func stop() {
+ guard let displayLink else {
+ return
+ }
+ CVDisplayLinkStop(displayLink)
+ self.displayLink = nil
+ }
+
+ private func tick() {
+ let now = CACurrentMediaTime()
+ let dt = CGFloat(lastTimestamp.map { now - $0 } ?? (1.0 / 60.0))
+ lastTimestamp = now
+
+ if previewRemaining > 0 {
+ previewRemaining -= dt
+ if previewRemaining <= 0 {
+ startSelectedCandidateAnimation()
+ }
+ return
+ }
+
+ currentState = simulator.step(deltaTime: dt)
+ path = simulator.path
+
+ if currentState.trailProgress > 0.94 {
+ let pulseProgress = min(max((currentState.trailProgress - 0.94) / 0.06, 0), 1)
+ clickPulse = sin(pulseProgress * .pi)
+ } else {
+ clickPulse = 0
+ }
+
+ if currentState.isSettled {
+ stop()
+ }
+ }
+
+ private func startSelectedCandidateAnimation() {
+ guard let selectedPath = candidates.first(where: { $0.id == selectedCandidateID })?.path ?? candidates.first?.path else {
+ stop()
+ return
+ }
+
+ simulator.reset(path: selectedPath)
+ path = selectedPath
+ currentState = CursorMotionState(point: selectedPath.start, rotation: CursorGlyphCalibration.restingRotation, trailProgress: 0, isSettled: false)
+ }
+
+ private var currentAnchorPoint: CGPoint {
+ if previewRemaining > 0 {
+ return currentState.point
+ }
+ return currentState.isSettled ? simulator.end : currentState.point
+ }
+}
+
+private struct CursorLabCanvas: View {
+ @Binding var start: CGPoint
+ @Binding var end: CGPoint
+ let debugEnabled: Bool
+ let showClickPulse: Bool
+ @ObservedObject var model: CursorLabViewModel
+
+ var body: some View {
+ ZStack {
+ persistentPathLayer
+
+ if debugEnabled {
+ debugCandidateLayer
+ }
+
+ Circle()
+ .fill(Color.white.opacity(0.9))
+ .frame(width: 12, height: 12)
+ .overlay(Circle().stroke(Color.white.opacity(0.4), lineWidth: 8))
+ .position(start)
+ .allowsHitTesting(false)
+
+ Circle()
+ .fill(Color(red: 0.98, green: 0.45, blue: 0.68))
+ .frame(width: 14, height: 14)
+ .overlay(Circle().stroke(Color.white.opacity(0.35), lineWidth: 8))
+ .position(end)
+ .allowsHitTesting(false)
+
+ CursorGlyph(rotation: model.currentState.rotation, clickPulse: showClickPulse ? model.clickPulse : 0)
+ .position(model.currentState.point)
+ .shadow(color: Color.black.opacity(0.14), radius: 8, x: 0, y: 4)
+ .allowsHitTesting(false)
+
+ CanvasClickCapture { location in
+ end = location
+ }
+ }
+ }
+
+ private var persistentPathLayer: some View {
+ Canvas { context, _ in
+ let selectedPath = Path(model.path.cgPath)
+ context.stroke(
+ selectedPath,
+ with: .linearGradient(
+ Gradient(colors: [
+ Color.white.opacity(0.28),
+ Color(red: 0.98, green: 0.72, blue: 0.86).opacity(0.16),
+ ]),
+ startPoint: model.path.start,
+ endPoint: model.path.end
+ ),
+ style: StrokeStyle(lineWidth: 2.6, lineCap: .round, lineJoin: .round)
+ )
+
+ let livePath = trimmedPath(progress: model.currentState.trailProgress)
+ context.stroke(
+ livePath,
+ with: .linearGradient(
+ Gradient(colors: [
+ Color.white.opacity(0.88),
+ Color(red: 0.97, green: 0.38, blue: 0.65).opacity(0.95),
+ ]),
+ startPoint: model.path.start,
+ endPoint: model.path.end
+ ),
+ style: StrokeStyle(lineWidth: 5.2, lineCap: .round, lineJoin: .round)
+ )
+ }
+ .allowsHitTesting(false)
+ }
+
+ private var debugCandidateLayer: some View {
+ Canvas { context, _ in
+ for (index, candidate) in model.candidates.enumerated() where candidate.id != model.selectedCandidateID {
+ let path = Path(candidate.path.cgPath)
+ let strokeColor = Color.white.opacity(max(0.10, 0.22 - CGFloat(index) * 0.016))
+ context.stroke(
+ path,
+ with: .color(strokeColor),
+ style: StrokeStyle(lineWidth: 1.25, dash: [6, 8], dashPhase: CGFloat(index) * 2)
+ )
+ }
+
+ let handleStroke = StrokeStyle(lineWidth: 1.0, dash: [4, 6])
+ let handleColor = Color.white.opacity(0.22)
+ context.stroke(Path { path in
+ path.move(to: model.path.start)
+ path.addLine(to: model.path.control1)
+ path.move(to: model.path.end)
+ path.addLine(to: model.path.control2)
+ }, with: .color(handleColor), style: handleStroke)
+
+ for point in [model.path.control1, model.path.control2] {
+ let rect = CGRect(x: point.x - 4, y: point.y - 4, width: 8, height: 8)
+ context.fill(Path(ellipseIn: rect), with: .color(.white.opacity(0.55)))
+ }
+
+ if let selectedCandidate = model.candidates.first(where: { $0.id == model.selectedCandidateID }) {
+ let labelPoint = CGPoint(
+ x: selectedCandidate.path.point(at: 0.54).x + 18,
+ y: selectedCandidate.path.point(at: 0.54).y - 16
+ )
+ let text = Text("SELECTED")
+ .font(.system(size: 10, weight: .black, design: .rounded))
+ .foregroundColor(.white.opacity(0.82))
+ context.draw(text, at: labelPoint, anchor: .leading)
+ }
+ }
+ .allowsHitTesting(false)
+ }
+
+ private func trimmedPath(progress: CGFloat) -> Path {
+ Path(model.path.cgPath).trimmedPath(from: 0, to: max(0.001, min(progress, 1)))
+ }
+}
+
+private struct CanvasClickCapture: NSViewRepresentable {
+ let onTap: (CGPoint) -> Void
+
+ func makeNSView(context: Context) -> ClickCaptureView {
+ let view = ClickCaptureView()
+ view.onTap = onTap
+ return view
+ }
+
+ func updateNSView(_ nsView: ClickCaptureView, context: Context) {
+ nsView.onTap = onTap
+ }
+}
+
+private final class ClickCaptureView: NSView {
+ var onTap: ((CGPoint) -> Void)?
+
+ override var isFlipped: Bool {
+ true
+ }
+
+ override init(frame frameRect: NSRect) {
+ super.init(frame: frameRect)
+ wantsLayer = true
+ layer?.backgroundColor = NSColor.clear.cgColor
+ }
+
+ @available(*, unavailable)
+ required init?(coder: NSCoder) {
+ nil
+ }
+
+ override func acceptsFirstMouse(for event: NSEvent?) -> Bool {
+ true
+ }
+
+ override func mouseDown(with event: NSEvent) {
+ let location = convert(event.locationInWindow, from: nil)
+ onTap?(location)
+ }
+}
+
+private struct CursorGlyph: View {
+ let rotation: CGFloat
+ let clickPulse: CGFloat
+
+ var body: some View {
+ ZStack {
+ Ellipse()
+ .fill(Color.black.opacity(0.12))
+ .frame(width: 22 + clickPulse * 4, height: 6 + clickPulse * 1.4)
+ .offset(x: 0, y: 24)
+ .blur(radius: 1.6)
+
+ glyphBody
+
+ if clickPulse > 0.02 {
+ Circle()
+ .stroke(Color.white.opacity(0.26), lineWidth: 1)
+ .frame(width: 8 + clickPulse * 12, height: 8 + clickPulse * 12)
+ }
+ }
+ .frame(width: CursorGlyphArtwork.layoutSize.width, height: CursorGlyphArtwork.layoutSize.height)
+ .rotationEffect(.radians(rotation), anchor: .center)
+ .scaleEffect(x: 1 - clickPulse * 0.04, y: 1 + clickPulse * 0.03, anchor: .center)
+ }
+
+ @ViewBuilder
+ private var glyphBody: some View {
+ if let image = CursorGlyphArtwork.image {
+ Image(nsImage: image)
+ .resizable()
+ .interpolation(.high)
+ .antialiased(true)
+ .frame(width: CursorGlyphArtwork.imageSize.width, height: CursorGlyphArtwork.imageSize.height)
+ .offset(CursorGlyphArtwork.contentOffset)
+ } else {
+ CursorGlyphFallbackShape()
+ .fill(Color.black.opacity(0.92))
+ .frame(width: CursorGlyphArtwork.imageSize.width, height: CursorGlyphArtwork.imageSize.height)
+ .offset(CursorGlyphArtwork.contentOffset)
+ }
+ }
+}
+
+private struct CursorGlyphFallbackShape: Shape {
+ func path(in rect: CGRect) -> Path {
+ return Path { path in
+ path.move(to: CGPoint(x: rect.midX, y: rect.minY))
+ path.addQuadCurve(
+ to: CGPoint(x: rect.maxX, y: rect.maxY * 0.86),
+ control: CGPoint(x: rect.maxX * 0.92, y: rect.maxY * 0.28)
+ )
+ path.addQuadCurve(
+ to: CGPoint(x: rect.midX, y: rect.maxY * 0.62),
+ control: CGPoint(x: rect.maxX * 0.82, y: rect.maxY * 1.02)
+ )
+ path.addQuadCurve(
+ to: CGPoint(x: rect.minX, y: rect.maxY * 0.86),
+ control: CGPoint(x: rect.maxX * 0.18, y: rect.maxY * 1.02)
+ )
+ path.addQuadCurve(
+ to: CGPoint(x: rect.midX, y: rect.minY),
+ control: CGPoint(x: rect.maxX * 0.08, y: rect.maxY * 0.28)
+ )
+ path.closeSubpath()
+ }
+ }
+}
+
+private struct CursorSliderRow: View {
+ let title: String
+ @Binding var value: CGFloat
+ var accent: Color = Color(red: 0.94, green: 0.28, blue: 0.62)
+
+ var body: some View {
+ HStack(spacing: 10) {
+ Slider(value: Binding(
+ get: { Double(value) },
+ set: { value = CGFloat($0) }
+ ), in: 0...1)
+ .tint(accent)
+ .frame(width: 66)
+
+ Text(title)
+ .font(.system(size: 10, weight: .black, design: .rounded))
+ .foregroundStyle(Color.white.opacity(0.82))
+ .tracking(0.8)
+ .frame(width: 92, alignment: .leading)
+ }
+ }
+}
+
+private struct CursorToggleRow: View {
+ let title: String
+ @Binding var isOn: Bool
+ var accent: Color = Color(red: 0.92, green: 0.22, blue: 0.58)
+
+ var body: some View {
+ HStack(spacing: 10) {
+ Text(title)
+ .font(.system(size: 10, weight: .black, design: .rounded))
+ .foregroundStyle(Color.white.opacity(0.82))
+ .tracking(0.8)
+
+ Toggle("", isOn: $isOn)
+ .toggleStyle(CursorToggleStyle(accent: accent))
+ .labelsHidden()
+ }
+ }
+}
+
+private struct CursorToggleStyle: ToggleStyle {
+ let accent: Color
+
+ func makeBody(configuration: Configuration) -> some View {
+ RoundedRectangle(cornerRadius: 10)
+ .fill(configuration.isOn ? accent : Color.white.opacity(0.34))
+ .frame(width: 38, height: 20)
+ .overlay(alignment: configuration.isOn ? .trailing : .leading) {
+ Circle()
+ .fill(Color.white)
+ .frame(width: 15, height: 15)
+ .padding(2)
+ }
+ .contentShape(Rectangle())
+ .onTapGesture {
+ configuration.isOn.toggle()
+ }
+ }
+}
+
+private struct CursorActionButtonStyle: ButtonStyle {
+ func makeBody(configuration: Configuration) -> some View {
+ configuration.label
+ .font(.system(size: 11, weight: .bold, design: .rounded))
+ .padding(.horizontal, 10)
+ .padding(.vertical, 5)
+ .background(Color.white.opacity(configuration.isPressed ? 0.18 : 0.12))
+ .foregroundStyle(Color.white.opacity(0.88))
+ .clipShape(Capsule())
+ }
+}
+
+private struct CursorLabBackground: View {
+ var body: some View {
+ LinearGradient(
+ colors: [
+ Color(red: 0.96, green: 0.75, blue: 0.85),
+ Color(red: 0.92, green: 0.71, blue: 0.91),
+ Color(red: 0.97, green: 0.62, blue: 0.76),
+ Color(red: 0.44, green: 0.77, blue: 0.97),
+ ],
+ startPoint: .topLeading,
+ endPoint: .bottomTrailing
+ )
+ .overlay {
+ Canvas { context, size in
+ let blobs: [(CGPoint, CGSize, Color)] = [
+ (CGPoint(x: size.width * 0.18, y: size.height * 0.20), CGSize(width: 360, height: 620), Color.white.opacity(0.20)),
+ (CGPoint(x: size.width * 0.55, y: size.height * 0.58), CGSize(width: 420, height: 720), Color(red: 1, green: 0.72, blue: 0.82).opacity(0.22)),
+ (CGPoint(x: size.width * 0.82, y: size.height * 0.26), CGSize(width: 360, height: 520), Color(red: 0.52, green: 0.82, blue: 1).opacity(0.26)),
+ ]
+
+ for blob in blobs {
+ let rect = CGRect(origin: .zero, size: blob.1).offsetBy(dx: blob.0.x - blob.1.width / 2, dy: blob.0.y - blob.1.height / 2)
+ context.addFilter(.blur(radius: 48))
+ context.fill(Path(ellipseIn: rect), with: .color(blob.2))
+ }
+ }
+ }
+ .ignoresSafeArea()
+ }
+}
diff --git a/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift b/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift
new file mode 100644
index 0000000..b0c7e29
--- /dev/null
+++ b/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift
@@ -0,0 +1,873 @@
+import CoreGraphics
+import Foundation
+
+struct CursorMotionParameters: Equatable {
+ var startHandle: CGFloat = 0.29
+ var endHandle: CGFloat = 0.08
+ var arcSize: CGFloat = 0.06
+ var arcFlow: CGFloat = 0.64
+ var spring: CGFloat = 0.53
+
+ static let `default` = CursorMotionParameters()
+}
+
+struct CursorMotionCandidate: Identifiable, Equatable {
+ let id: String
+ let path: CursorMotionPath
+ let score: CGFloat
+ let family: String
+}
+
+struct CursorPathSample {
+ let point: CGPoint
+ let tangent: CGVector
+}
+
+struct CursorMotionPath: Equatable {
+ let start: CGPoint
+ let control1: CGPoint
+ let control2: CGPoint
+ let end: CGPoint
+ let arcHeight: CGFloat
+ let arcIn: CGFloat
+ let arcOut: CGFloat
+
+ func point(at t: CGFloat) -> CGPoint {
+ let omt = 1 - t
+ let omt2 = omt * omt
+ let t2 = t * t
+
+ return CGPoint(
+ x: (omt2 * omt * start.x)
+ + (3 * omt2 * t * control1.x)
+ + (3 * omt * t2 * control2.x)
+ + (t2 * t * end.x),
+ y: (omt2 * omt * start.y)
+ + (3 * omt2 * t * control1.y)
+ + (3 * omt * t2 * control2.y)
+ + (t2 * t * end.y)
+ )
+ }
+
+ func tangent(at t: CGFloat) -> CGVector {
+ let omt = 1 - t
+ return CGVector(
+ dx: (3 * omt * omt * (control1.x - start.x))
+ + (6 * omt * t * (control2.x - control1.x))
+ + (3 * t * t * (end.x - control2.x)),
+ dy: (3 * omt * omt * (control1.y - start.y))
+ + (6 * omt * t * (control2.y - control1.y))
+ + (3 * t * t * (end.y - control2.y))
+ )
+ }
+
+ func sample(at t: CGFloat) -> CursorPathSample {
+ CursorPathSample(point: point(at: t), tangent: tangent(at: max(0.001, min(t, 0.999))))
+ }
+
+ func secondDerivative(at t: CGFloat) -> CGVector {
+ let omt = 1 - t
+ return CGVector(
+ dx: (6 * omt * (control2.x - (2 * control1.x) + start.x))
+ + (6 * t * (end.x - (2 * control2.x) + control1.x)),
+ dy: (6 * omt * (control2.y - (2 * control1.y) + start.y))
+ + (6 * t * (end.y - (2 * control2.y) + control1.y))
+ )
+ }
+
+ func curvature(at t: CGFloat) -> CGFloat {
+ let derivative = tangent(at: t)
+ let second = secondDerivative(at: t)
+ let numerator = abs((derivative.dx * second.dy) - (derivative.dy * second.dx))
+ let denominator = pow(max((derivative.dx * derivative.dx) + (derivative.dy * derivative.dy), 0.001), 1.5)
+ return numerator / denominator
+ }
+
+ var cgPath: CGPath {
+ let path = CGMutablePath()
+ path.move(to: start)
+ path.addCurve(to: end, control1: control1, control2: control2)
+ return path
+ }
+}
+
+enum CursorMotionPathBuilder {
+ private static let baseCursorHeading = CursorGlyphCalibration.neutralHeading
+
+ static func makePath(
+ from start: CGPoint,
+ to end: CGPoint,
+ parameters: CursorMotionParameters,
+ startRotation: CGFloat = 0,
+ endRotation: CGFloat = CursorGlyphCalibration.restingRotation
+ ) -> CursorMotionPath {
+ let metrics = MotionMetrics(start: start, end: end)
+ let descriptor = descriptors(for: metrics).max { lhs, rhs in
+ score(descriptor: lhs, metrics: metrics, parameters: parameters) < score(descriptor: rhs, metrics: metrics, parameters: parameters)
+ } ?? descriptors(for: metrics)[0]
+ return makePath(
+ from: start,
+ to: end,
+ parameters: parameters,
+ descriptor: descriptor,
+ metrics: metrics,
+ startRotation: startRotation,
+ endRotation: endRotation
+ )
+ }
+
+ static func makeCandidatePaths(
+ from start: CGPoint,
+ to end: CGPoint,
+ parameters: CursorMotionParameters,
+ startRotation: CGFloat = 0,
+ endRotation: CGFloat = CursorGlyphCalibration.restingRotation
+ ) -> [CursorMotionCandidate] {
+ let metrics = MotionMetrics(start: start, end: end)
+ return descriptors(for: metrics).map { descriptor in
+ let path = makePath(
+ from: start,
+ to: end,
+ parameters: parameters,
+ descriptor: descriptor,
+ metrics: metrics,
+ startRotation: startRotation,
+ endRotation: endRotation
+ )
+ return CursorMotionCandidate(
+ id: descriptor.id,
+ path: path,
+ score: score(descriptor: descriptor, metrics: metrics, parameters: parameters),
+ family: descriptor.family
+ )
+ }
+ .sorted { lhs, rhs in
+ lhs.score > rhs.score
+ }
+ }
+
+ private static func makePath(
+ from start: CGPoint,
+ to end: CGPoint,
+ parameters: CursorMotionParameters,
+ descriptor: MotionDescriptor,
+ metrics: MotionMetrics,
+ startRotation: CGFloat,
+ endRotation: CGFloat
+ ) -> CursorMotionPath {
+ let distance = metrics.distance
+ let direction = metrics.direction
+ let normal = metrics.normal
+ let resolvedFlow = (parameters.arcFlow + descriptor.flowShift).clamped(to: 0...1)
+ let flowBias = (resolvedFlow - 0.5) * distance * 0.18
+
+ let baseStartReach = distance * (0.10 + parameters.startHandle * 0.56)
+ let baseEndReach = distance * (0.11 + parameters.endHandle * 0.62)
+ let distanceLift = 0.68 + (metrics.farFactor * 0.56)
+ let baseArcHeight = min(
+ max(distance * (0.10 + parameters.arcSize * 0.92) * descriptor.arcScale * distanceLift, 20),
+ distance * 0.96
+ )
+
+ let sideSign = descriptor.side
+ let arcVector = CGPoint(
+ x: normal.dx * baseArcHeight * sideSign,
+ y: normal.dy * baseArcHeight * sideSign
+ )
+
+ let startForward = headingVector(rotation: startRotation)
+ let endForward = headingVector(rotation: endRotation)
+ let startGuide = resolvedGuide(
+ line: direction,
+ forward: startForward,
+ normal: normal,
+ sideSign: sideSign,
+ lineWeight: descriptor.startLineWeight,
+ headingWeight: descriptor.startHeadingWeight,
+ normalBias: descriptor.startGuideNormalBias
+ )
+ let endGuide = resolvedGuide(
+ line: direction,
+ forward: endForward,
+ normal: normal,
+ sideSign: sideSign,
+ lineWeight: descriptor.endLineWeight,
+ headingWeight: descriptor.endHeadingWeight,
+ normalBias: descriptor.endGuideNormalBias
+ )
+
+ let startReach = max(baseStartReach * descriptor.startReachScale + flowBias * descriptor.startFlowWeight, 12)
+ let endReach = max(baseEndReach * descriptor.endReachScale - flowBias * descriptor.endFlowWeight, 12)
+ let control1Base = CGPoint(
+ x: start.x + startGuide.dx * startReach,
+ y: start.y + startGuide.dy * startReach
+ )
+ let control2Base = CGPoint(
+ x: end.x - endGuide.dx * endReach,
+ y: end.y - endGuide.dy * endReach
+ )
+
+ let control1 = CGPoint(
+ x: control1Base.x + arcVector.x * descriptor.startNormalScale,
+ y: control1Base.y + arcVector.y * descriptor.startNormalScale
+ )
+ let control2 = CGPoint(
+ x: control2Base.x + arcVector.x * descriptor.endNormalScale,
+ y: control2Base.y + arcVector.y * descriptor.endNormalScale
+ )
+
+ let resolvedArcHeight = baseArcHeight * max(
+ abs(descriptor.startNormalScale),
+ abs(descriptor.endNormalScale),
+ 0.12
+ )
+ let arcIn = abs(descriptor.startNormalScale).clamped(to: 0.12...1.28)
+ let arcOut = abs(descriptor.endNormalScale).clamped(to: 0.12...1.28)
+
+ return CursorMotionPath(start: start, control1: control1, control2: control2, end: end, arcHeight: resolvedArcHeight, arcIn: arcIn, arcOut: arcOut)
+ }
+
+ private static func score(descriptor: MotionDescriptor, metrics: MotionMetrics, parameters: CursorMotionParameters) -> CGFloat {
+ let sideAffinity = descriptor.side == preferredSide(for: metrics) ? 0.04 : -0.02
+ let flowEnergy = abs(parameters.arcFlow - 0.5) * 0.08
+ let handleEnergy = max(parameters.startHandle, parameters.endHandle) * 0.06
+
+ switch descriptor.family {
+ case "turn":
+ return 0.36 + (metrics.farFactor * 0.28) + (metrics.horizontalFactor * 0.18) + (metrics.diagonalFactor * 0.10) + handleEnergy + sideAffinity
+ case "brake":
+ return 0.35 + (metrics.farFactor * 0.20) + (metrics.horizontalFactor * 0.12) + (parameters.spring * 0.06) + flowEnergy
+ case "orbit":
+ return 0.28 + (metrics.horizontalFactor * 0.20) + (metrics.farFactor * 0.28) + sideAffinity + flowEnergy
+ case "ribbon":
+ return 0.24 + (metrics.diagonalFactor * 0.26) + (metrics.farFactor * 0.10) + flowEnergy
+ case "slingshot":
+ return 0.22 + (metrics.closeFactor * 0.10) + (metrics.diagonalFactor * 0.20) + (metrics.farFactor * 0.08) + sideAffinity
+ case "hook":
+ return 0.20 + (metrics.closeFactor * 0.22) + (metrics.verticalFactor * 0.18)
+ case "snap":
+ return 0.18 + (metrics.closeFactor * 0.26) + (metrics.horizontalFactor * 0.08)
+ case "direct":
+ return 0.14 + (metrics.closeFactor * 0.20) - (metrics.farFactor * 0.28)
+ default:
+ return 0.12
+ }
+ }
+
+ private static func descriptors(for metrics: MotionMetrics) -> [MotionDescriptor] {
+ let orbitScale = 0.84 + (metrics.farFactor * 0.34)
+ let tightScale = 0.58 + (metrics.closeFactor * 0.22)
+ let turnaroundScale = 0.92 + (metrics.farFactor * 0.34)
+ let brakingScale = 0.76 + (metrics.farFactor * 0.28)
+
+ return [
+ MotionDescriptor(
+ id: "turn-high",
+ family: "turn",
+ side: 1,
+ startReachScale: 1.30,
+ endReachScale: 1.34,
+ startLineWeight: -0.26,
+ endLineWeight: -0.10,
+ startHeadingWeight: 1.56,
+ endHeadingWeight: 1.34,
+ startNormalScale: 0.52,
+ endNormalScale: 0.02,
+ startGuideNormalBias: 0.36,
+ endGuideNormalBias: 0.24,
+ startFlowWeight: -0.34,
+ endFlowWeight: 0.26,
+ flowShift: -0.08,
+ arcScale: turnaroundScale
+ ),
+ MotionDescriptor(
+ id: "turn-low",
+ family: "turn",
+ side: -1,
+ startReachScale: 1.26,
+ endReachScale: 1.38,
+ startLineWeight: -0.30,
+ endLineWeight: -0.12,
+ startHeadingWeight: 1.52,
+ endHeadingWeight: 1.38,
+ startNormalScale: 0.50,
+ endNormalScale: 0.04,
+ startGuideNormalBias: 0.34,
+ endGuideNormalBias: 0.24,
+ startFlowWeight: -0.30,
+ endFlowWeight: 0.28,
+ flowShift: 0.08,
+ arcScale: turnaroundScale * 0.96
+ ),
+ MotionDescriptor(
+ id: "brake-high",
+ family: "brake",
+ side: 1,
+ startReachScale: 0.92,
+ endReachScale: 1.48,
+ startLineWeight: 0.52,
+ endLineWeight: -0.28,
+ startHeadingWeight: 0.68,
+ endHeadingWeight: 1.66,
+ startNormalScale: 0.20,
+ endNormalScale: 0.24,
+ startGuideNormalBias: 0.10,
+ endGuideNormalBias: 0.36,
+ startFlowWeight: 0.10,
+ endFlowWeight: 0.42,
+ flowShift: -0.04,
+ arcScale: brakingScale
+ ),
+ MotionDescriptor(
+ id: "brake-low",
+ family: "brake",
+ side: -1,
+ startReachScale: 0.96,
+ endReachScale: 1.52,
+ startLineWeight: 0.48,
+ endLineWeight: -0.32,
+ startHeadingWeight: 0.70,
+ endHeadingWeight: 1.72,
+ startNormalScale: 0.22,
+ endNormalScale: 0.28,
+ startGuideNormalBias: 0.12,
+ endGuideNormalBias: 0.38,
+ startFlowWeight: 0.12,
+ endFlowWeight: 0.44,
+ flowShift: 0.04,
+ arcScale: brakingScale * 0.94
+ ),
+ MotionDescriptor(
+ id: "orbit-high",
+ family: "orbit",
+ side: 1,
+ startReachScale: 0.92,
+ endReachScale: 1.02,
+ startLineWeight: 0.72,
+ endLineWeight: 0.82,
+ startHeadingWeight: 0.34,
+ endHeadingWeight: 0.24,
+ startNormalScale: 1.24,
+ endNormalScale: 1.08,
+ startGuideNormalBias: 0.18,
+ endGuideNormalBias: 0.08,
+ startFlowWeight: 0.40,
+ endFlowWeight: 0.18,
+ flowShift: -0.10,
+ arcScale: orbitScale
+ ),
+ MotionDescriptor(
+ id: "orbit-low",
+ family: "orbit",
+ side: -1,
+ startReachScale: 0.88,
+ endReachScale: 1.04,
+ startLineWeight: 0.68,
+ endLineWeight: 0.84,
+ startHeadingWeight: 0.30,
+ endHeadingWeight: 0.22,
+ startNormalScale: 1.18,
+ endNormalScale: 1.02,
+ startGuideNormalBias: 0.16,
+ endGuideNormalBias: 0.08,
+ startFlowWeight: 0.34,
+ endFlowWeight: 0.14,
+ flowShift: 0.10,
+ arcScale: orbitScale * 0.94
+ ),
+ MotionDescriptor(
+ id: "ribbon-high",
+ family: "ribbon",
+ side: 1,
+ startReachScale: 0.98,
+ endReachScale: 0.90,
+ startLineWeight: 0.74,
+ endLineWeight: 0.34,
+ startHeadingWeight: 0.28,
+ endHeadingWeight: 0.56,
+ startNormalScale: 0.78,
+ endNormalScale: -0.56,
+ startGuideNormalBias: 0.10,
+ endGuideNormalBias: -0.22,
+ startFlowWeight: 0.12,
+ endFlowWeight: -0.18,
+ flowShift: 0.06,
+ arcScale: 0.82 + (metrics.diagonalFactor * 0.24)
+ ),
+ MotionDescriptor(
+ id: "ribbon-low",
+ family: "ribbon",
+ side: -1,
+ startReachScale: 0.94,
+ endReachScale: 0.92,
+ startLineWeight: 0.70,
+ endLineWeight: 0.36,
+ startHeadingWeight: 0.28,
+ endHeadingWeight: 0.60,
+ startNormalScale: 0.74,
+ endNormalScale: -0.52,
+ startGuideNormalBias: 0.10,
+ endGuideNormalBias: -0.20,
+ startFlowWeight: 0.10,
+ endFlowWeight: -0.16,
+ flowShift: -0.06,
+ arcScale: 0.80 + (metrics.diagonalFactor * 0.22)
+ ),
+ MotionDescriptor(
+ id: "slingshot-high",
+ family: "slingshot",
+ side: 1,
+ startReachScale: 1.12,
+ endReachScale: 1.00,
+ startLineWeight: -0.24,
+ endLineWeight: 0.86,
+ startHeadingWeight: 1.00,
+ endHeadingWeight: 0.24,
+ startNormalScale: 0.48,
+ endNormalScale: 0.94,
+ startGuideNormalBias: 0.20,
+ endGuideNormalBias: 0.08,
+ startFlowWeight: -0.46,
+ endFlowWeight: 0.24,
+ flowShift: -0.12,
+ arcScale: 0.74 + (metrics.diagonalFactor * 0.18)
+ ),
+ MotionDescriptor(
+ id: "slingshot-low",
+ family: "slingshot",
+ side: -1,
+ startReachScale: 1.16,
+ endReachScale: 1.02,
+ startLineWeight: -0.28,
+ endLineWeight: 0.88,
+ startHeadingWeight: 1.04,
+ endHeadingWeight: 0.24,
+ startNormalScale: 0.44,
+ endNormalScale: 0.98,
+ startGuideNormalBias: 0.22,
+ endGuideNormalBias: 0.10,
+ startFlowWeight: -0.42,
+ endFlowWeight: 0.22,
+ flowShift: 0.12,
+ arcScale: 0.72 + (metrics.diagonalFactor * 0.18)
+ ),
+ MotionDescriptor(
+ id: "hook-upper",
+ family: "hook",
+ side: 1,
+ startReachScale: 0.90,
+ endReachScale: 0.76,
+ startLineWeight: -0.44,
+ endLineWeight: 0.30,
+ startHeadingWeight: 0.92,
+ endHeadingWeight: 0.18,
+ startNormalScale: -0.36,
+ endNormalScale: 0.30,
+ startGuideNormalBias: -0.20,
+ endGuideNormalBias: 0.16,
+ startFlowWeight: -0.52,
+ endFlowWeight: 0.18,
+ flowShift: -0.10,
+ arcScale: tightScale
+ ),
+ MotionDescriptor(
+ id: "hook-lower",
+ family: "hook",
+ side: -1,
+ startReachScale: 0.88,
+ endReachScale: 0.74,
+ startLineWeight: -0.40,
+ endLineWeight: 0.28,
+ startHeadingWeight: 0.88,
+ endHeadingWeight: 0.18,
+ startNormalScale: -0.34,
+ endNormalScale: 0.26,
+ startGuideNormalBias: -0.18,
+ endGuideNormalBias: 0.16,
+ startFlowWeight: -0.48,
+ endFlowWeight: 0.16,
+ flowShift: 0.10,
+ arcScale: tightScale * 0.96
+ ),
+ MotionDescriptor(
+ id: "snap",
+ family: "snap",
+ side: preferredSide(for: metrics),
+ startReachScale: 1.10,
+ endReachScale: 0.72,
+ startLineWeight: 1.08,
+ endLineWeight: -0.22,
+ startHeadingWeight: 0.22,
+ endHeadingWeight: 0.74,
+ startNormalScale: 0.20,
+ endNormalScale: -0.34,
+ startGuideNormalBias: 0.06,
+ endGuideNormalBias: -0.16,
+ startFlowWeight: 0.28,
+ endFlowWeight: -0.34,
+ flowShift: 0.04,
+ arcScale: 0.54 + (metrics.closeFactor * 0.20)
+ ),
+ MotionDescriptor(
+ id: "direct",
+ family: "direct",
+ side: preferredSide(for: metrics),
+ startReachScale: 0.94,
+ endReachScale: 0.94,
+ startLineWeight: 1.16,
+ endLineWeight: 1.06,
+ startHeadingWeight: 0.02,
+ endHeadingWeight: 0.02,
+ startNormalScale: 0.02,
+ endNormalScale: 0.02,
+ startGuideNormalBias: 0,
+ endGuideNormalBias: 0,
+ startFlowWeight: 0.06,
+ endFlowWeight: 0.06,
+ flowShift: 0,
+ arcScale: 0.20
+ ),
+ ]
+ }
+
+ private static func preferredSide(for metrics: MotionMetrics) -> CGFloat {
+ if abs(metrics.dy) > abs(metrics.dx) * 0.72 {
+ return metrics.dy > 0 ? -1 : 1
+ }
+ return metrics.dx >= 0 ? 1 : -1
+ }
+
+ private static func headingVector(rotation: CGFloat) -> CGVector {
+ let angle = baseCursorHeading + rotation
+ return CGVector(dx: cos(angle), dy: sin(angle))
+ }
+
+ private static func resolvedGuide(
+ line: CGVector,
+ forward: CGVector,
+ normal: CGVector,
+ sideSign: CGFloat,
+ lineWeight: CGFloat,
+ headingWeight: CGFloat,
+ normalBias: CGFloat
+ ) -> CGVector {
+ normalized(CGVector(
+ dx: (line.dx * lineWeight) + (forward.dx * headingWeight) + (normal.dx * normalBias * sideSign),
+ dy: (line.dy * lineWeight) + (forward.dy * headingWeight) + (normal.dy * normalBias * sideSign)
+ ))
+ }
+
+ private static func normalized(_ vector: CGVector) -> CGVector {
+ let length = max(hypot(vector.dx, vector.dy), 0.001)
+ return CGVector(dx: vector.dx / length, dy: vector.dy / length)
+ }
+
+ private struct MotionDescriptor {
+ let id: String
+ let family: String
+ let side: CGFloat
+ let startReachScale: CGFloat
+ let endReachScale: CGFloat
+ let startLineWeight: CGFloat
+ let endLineWeight: CGFloat
+ let startHeadingWeight: CGFloat
+ let endHeadingWeight: CGFloat
+ let startNormalScale: CGFloat
+ let endNormalScale: CGFloat
+ let startGuideNormalBias: CGFloat
+ let endGuideNormalBias: CGFloat
+ let startFlowWeight: CGFloat
+ let endFlowWeight: CGFloat
+ let flowShift: CGFloat
+ let arcScale: CGFloat
+ }
+
+ private struct MotionMetrics {
+ let start: CGPoint
+ let end: CGPoint
+ let dx: CGFloat
+ let dy: CGFloat
+ let distance: CGFloat
+ let direction: CGVector
+ let normal: CGVector
+ let horizontalFactor: CGFloat
+ let verticalFactor: CGFloat
+ let diagonalFactor: CGFloat
+ let closeFactor: CGFloat
+ let farFactor: CGFloat
+
+ init(start: CGPoint, end: CGPoint) {
+ self.start = start
+ self.end = end
+ dx = end.x - start.x
+ dy = end.y - start.y
+ distance = max(hypot(dx, dy), 1)
+ direction = normalized(CGVector(dx: dx, dy: dy))
+ normal = normalized(CGVector(dx: -direction.dy, dy: direction.dx))
+ horizontalFactor = abs(dx) / distance
+ verticalFactor = abs(dy) / distance
+ diagonalFactor = min(horizontalFactor, verticalFactor) * 2
+ closeFactor = (1 - (distance / 280)).clamped(to: 0...1)
+ farFactor = ((distance - 180) / 540).clamped(to: 0...1)
+ }
+ }
+}
+
+struct CursorSpringParameters: Equatable {
+ let durationScale: CGFloat
+ let headingResponse: CGFloat
+ let finishRelaxation: CGFloat
+
+ static func from(_ spring: CGFloat) -> CursorSpringParameters {
+ CursorSpringParameters(
+ durationScale: 1.08 - (spring * 0.26),
+ headingResponse: 0.18 + (spring * 0.38),
+ finishRelaxation: 0.10 + ((1 - spring) * 0.10)
+ )
+ }
+}
+
+struct CursorMotionState {
+ let point: CGPoint
+ let rotation: CGFloat
+ let trailProgress: CGFloat
+ let isSettled: Bool
+}
+
+private struct CursorMotionTimingLookup {
+ struct Sample {
+ let t: CGFloat
+ let weightedDistance: CGFloat
+ }
+
+ let samples: [Sample]
+ let pathLength: CGFloat
+ let weightedLength: CGFloat
+
+ static func build(for path: CursorMotionPath) -> CursorMotionTimingLookup {
+ let sampleCount = 120
+ var samples: [Sample] = [.init(t: 0, weightedDistance: 0)]
+ var previous = path.sample(at: 0)
+ var previousHeading = atan2(previous.tangent.dy, previous.tangent.dx)
+ var pathLength: CGFloat = 0
+ var weightedLength: CGFloat = 0
+
+ for index in 1...sampleCount {
+ let t = CGFloat(index) / CGFloat(sampleCount)
+ let current = path.sample(at: t)
+ let ds = hypot(current.point.x - previous.point.x, current.point.y - previous.point.y)
+ let heading = atan2(current.tangent.dy, current.tangent.dx)
+ let headingChange = abs(normalize(angle: heading - previousHeading))
+ let midpoint = (t + samples[index - 1].t) * 0.5
+ let curvature = path.curvature(at: midpoint)
+ let curvatureWeight = min(curvature * max(path.arcHeight, 48), 1.75)
+ let segmentProfile = edgeProfile(at: midpoint)
+ let effortMultiplier = 1
+ + (headingChange * 1.9)
+ + (curvatureWeight * 0.65)
+ + (segmentProfile * (0.08 + (headingChange * 0.45)))
+
+ pathLength += ds
+ weightedLength += ds * effortMultiplier
+ samples.append(.init(t: t, weightedDistance: weightedLength))
+
+ previous = current
+ previousHeading = heading
+ }
+
+ return CursorMotionTimingLookup(samples: samples, pathLength: pathLength, weightedLength: weightedLength)
+ }
+
+ func parameter(at progress: CGFloat) -> CGFloat {
+ guard weightedLength > 0, samples.count > 1 else {
+ return progress.clamped(to: 0...1)
+ }
+
+ let target = progress.clamped(to: 0...1) * weightedLength
+ var low = 0
+ var high = samples.count - 1
+
+ while low < high {
+ let mid = (low + high) / 2
+ if samples[mid].weightedDistance < target {
+ low = mid + 1
+ } else {
+ high = mid
+ }
+ }
+
+ let upperIndex = max(low, 1)
+ let upper = samples[upperIndex]
+ let lower = samples[upperIndex - 1]
+ let span = max(upper.weightedDistance - lower.weightedDistance, 0.001)
+ let localProgress = ((target - lower.weightedDistance) / span).clamped(to: 0...1)
+ return lower.t + ((upper.t - lower.t) * localProgress)
+ }
+
+ private static func edgeProfile(at t: CGFloat) -> CGFloat {
+ let startBias = exp(-pow((t - 0.08) / 0.16, 2))
+ let endBias = exp(-pow((t - 0.90) / 0.14, 2))
+ return max(startBias, endBias)
+ }
+
+ private static func normalize(angle: CGFloat) -> CGFloat {
+ var value = angle
+ while value > .pi {
+ value -= 2 * .pi
+ }
+ while value < -.pi {
+ value += 2 * .pi
+ }
+ return value
+ }
+}
+
+final class CursorMotionSimulator {
+ private(set) var parameters: CursorMotionParameters
+ private(set) var path: CursorMotionPath
+ private(set) var springParameters: CursorSpringParameters
+ private(set) var start: CGPoint
+ private(set) var end: CGPoint
+
+ private var timingLookup: CursorMotionTimingLookup
+ private var elapsedTime: CGFloat = 0
+ private var travelDuration: CGFloat = 0.42
+ private var displayedRotation: CGFloat = 0
+
+ init(start: CGPoint, end: CGPoint, parameters: CursorMotionParameters) {
+ self.parameters = parameters
+ self.start = start
+ self.end = end
+ self.path = CursorMotionPathBuilder.makePath(from: start, to: end, parameters: parameters)
+ self.springParameters = .from(parameters.spring)
+ self.timingLookup = CursorMotionTimingLookup.build(for: path)
+ self.travelDuration = Self.duration(for: timingLookup, spring: springParameters)
+ self.displayedRotation = CursorGlyphCalibration.restingRotation
+ }
+
+ func reset(start: CGPoint? = nil, end: CGPoint? = nil, parameters: CursorMotionParameters? = nil) {
+ if let parameters {
+ self.parameters = parameters
+ }
+ if let start {
+ self.start = start
+ }
+ if let end {
+ self.end = end
+ }
+
+ path = CursorMotionPathBuilder.makePath(from: self.start, to: self.end, parameters: self.parameters)
+ springParameters = .from(self.parameters.spring)
+ timingLookup = CursorMotionTimingLookup.build(for: path)
+ travelDuration = Self.duration(for: timingLookup, spring: springParameters)
+ elapsedTime = 0
+ displayedRotation = CursorGlyphCalibration.restingRotation
+ }
+
+ func reset(path: CursorMotionPath, parameters: CursorMotionParameters? = nil) {
+ if let parameters {
+ self.parameters = parameters
+ }
+ self.path = path
+ self.start = path.start
+ self.end = path.end
+ springParameters = .from(self.parameters.spring)
+ timingLookup = CursorMotionTimingLookup.build(for: path)
+ travelDuration = Self.duration(for: timingLookup, spring: springParameters)
+ elapsedTime = 0
+ displayedRotation = CursorGlyphCalibration.restingRotation
+ }
+
+ func step(deltaTime dt: CGFloat) -> CursorMotionState {
+ let clampedDelta = max(1.0 / 240.0, min(dt, 1.0 / 24.0))
+ elapsedTime += clampedDelta
+ let rawProgress = (elapsedTime / max(travelDuration, 0.001)).clamped(to: 0...1)
+ let effortProgress = minimumJerk(rawProgress)
+ let pathProgress = timingLookup.parameter(at: effortProgress)
+ let sample = path.sample(at: pathProgress)
+ let point = sample.point
+ let liveRotation = rotation(for: sample.tangent)
+ let releaseStart = 1 - (springParameters.finishRelaxation * 0.55)
+ let releaseBlend = smoothstep(
+ from: releaseStart.clamped(to: 0...0.98),
+ to: 1,
+ value: rawProgress
+ )
+ let targetRotation = blendAngle(
+ from: liveRotation,
+ to: CursorGlyphCalibration.restingRotation,
+ progress: releaseBlend
+ )
+ displayedRotation = interpolateAngle(
+ from: displayedRotation,
+ to: targetRotation,
+ maxStep: (0.12 + (springParameters.headingResponse * 0.74)) * (clampedDelta * 60)
+ )
+
+ return CursorMotionState(
+ point: point,
+ rotation: rawProgress >= 1 ? CursorGlyphCalibration.restingRotation : displayedRotation,
+ trailProgress: pathProgress,
+ isSettled: rawProgress >= 1
+ )
+ }
+
+ private func rotation(for tangent: CGVector) -> CGFloat {
+ guard tangent.dx != 0 || tangent.dy != 0 else {
+ return CursorGlyphCalibration.restingRotation
+ }
+ let heading = atan2(tangent.dy, tangent.dx)
+ return normalize(angle: heading - CursorGlyphCalibration.neutralHeading)
+ }
+
+ private func normalize(angle: CGFloat) -> CGFloat {
+ var value = angle
+ while value > .pi {
+ value -= 2 * .pi
+ }
+ while value < -.pi {
+ value += 2 * .pi
+ }
+ return value
+ }
+
+ private func minimumJerk(_ value: CGFloat) -> CGFloat {
+ let t = value.clamped(to: 0...1)
+ return (10 * pow(t, 3)) - (15 * pow(t, 4)) + (6 * pow(t, 5))
+ }
+
+ private func smoothstep(from start: CGFloat, to end: CGFloat, value: CGFloat) -> CGFloat {
+ guard end > start else {
+ return value >= end ? 1 : 0
+ }
+ let t = ((value - start) / (end - start)).clamped(to: 0...1)
+ return t * t * (3 - (2 * t))
+ }
+
+ private func interpolateAngle(from current: CGFloat, to target: CGFloat, maxStep: CGFloat) -> CGFloat {
+ let delta = normalize(angle: target - current)
+ guard abs(delta) > maxStep else {
+ return target
+ }
+ return normalize(angle: current + (delta.sign == .minus ? -maxStep : maxStep))
+ }
+
+ private func blendAngle(from start: CGFloat, to end: CGFloat, progress: CGFloat) -> CGFloat {
+ let clamped = progress.clamped(to: 0...1)
+ let delta = normalize(angle: end - start)
+ return normalize(angle: start + (delta * clamped))
+ }
+
+ private static func duration(for lookup: CursorMotionTimingLookup, spring: CursorSpringParameters) -> CGFloat {
+ let distance = max(lookup.pathLength, 1)
+ let distanceTerm = 0.18 + min(distance / 1320, 0.34)
+ let curvatureTerm = min(max((lookup.weightedLength / distance) - 1, 0), 1.4) * 0.16
+ return max((distanceTerm + curvatureTerm) * spring.durationScale, 0.22)
+ }
+}
+
+private extension CGFloat {
+ func clamped(to range: ClosedRange<CGFloat>) -> CGFloat {
+ Swift.min(Swift.max(self, range.lowerBound), range.upperBound)
+ }
+}
diff --git a/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/Resources/StandaloneCursorPointer.png b/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/Resources/StandaloneCursorPointer.png
new file mode 100644
index 0000000..626e1f0
Binary files /dev/null and b/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/Resources/StandaloneCursorPointer.png differ
diff --git a/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/StandaloneCursorLabApp.swift b/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/StandaloneCursorLabApp.swift
new file mode 100644
index 0000000..8d60e6e
--- /dev/null
+++ b/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/StandaloneCursorLabApp.swift
@@ -0,0 +1,58 @@
+import AppKit
+import SwiftUI
+
+@main
+enum StandaloneCursorLabMain {
+ static func main() {
+ let application = NSApplication.shared
+ application.setActivationPolicy(.regular)
+
+ let delegate = StandaloneCursorLabAppDelegate()
+ application.delegate = delegate
+ application.run()
+ }
+}
+
+@MainActor
+final class StandaloneCursorLabAppDelegate: NSObject, NSApplicationDelegate {
+ private var window: NSWindow?
+
+ func applicationDidFinishLaunching(_ notification: Notification) {
+ installMenu()
+
+ let window = NSWindow(
+ contentRect: NSRect(x: 0, y: 0, width: 1120, height: 760),
+ styleMask: [.titled, .closable, .miniaturizable, .resizable],
+ backing: .buffered,
+ defer: false
+ )
+ window.title = "Standalone Cursor Lab"
+ window.center()
+ window.isReleasedWhenClosed = false
+ window.minSize = NSSize(width: 1120, height: 760)
+ window.contentView = NSHostingView(rootView: CursorLabRootView())
+
+ self.window = window
+ window.orderFrontRegardless()
+ window.makeKeyAndOrderFront(nil)
+ window.level = .normal
+ NSRunningApplication.current.activate(options: [.activateAllWindows, .activateIgnoringOtherApps])
+ NSApp.activate(ignoringOtherApps: true)
+ }
+
+ func applicationShouldTerminateAfterLastWindowClosed(_ sender: NSApplication) -> Bool {
+ true
+ }
+
+ private func installMenu() {
+ let mainMenu = NSMenu()
+ let appMenuItem = NSMenuItem()
+ mainMenu.addItem(appMenuItem)
+
+ let appMenu = NSMenu()
+ appMenu.addItem(withTitle: "Quit Standalone Cursor Lab", action: #selector(NSApplication.terminate(_:)), keyEquivalent: "q")
+ appMenuItem.submenu = appMenu
+
+ NSApp.mainMenu = mainMenu
+ }
+}