Skip to content

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

Refine StandaloneCursorLab tuning controls and timing

Leoddc2299a18d9
diff --git a/docs/exec-plans/active/20260418-standalone-cursor-lab.md b/docs/exec-plans/active/20260418-standalone-cursor-lab.md
index bf9c26b..9cda754 100644
--- a/docs/exec-plans/active/20260418-standalone-cursor-lab.md
+++ b/docs/exec-plans/active/20260418-standalone-cursor-lab.md
@@ -67,6 +67,10 @@
- 2026-04-19:继续对照官方视频后,确认 lab 主线不能直接拿 raw reverse-engineered `20` candidates 当 chooser;当前已改成 heading-driven 选路,把当前可见朝向和最终 resting pose 一起参与选路,主路径重新收敛到“需要掉头时走单侧 C 形,不需要掉头时近直线”的分布。
- 2026-04-20:在对照 `scripts/render-synthesized-software-cursor.swift` 与用户截图后,确认共享 glyph renderer 的亮白 asset 风格并不对;当前已把 lab 改成优先显示仓库里的官方 `252x252` runtime baseline 图,fallback 才走脚本同款 procedural pointer/fog,同时把 idle 从 XY 漂移收紧为中心固定的小幅摆角。
- 2026-04-20:继续按用户反馈收紧姿态后,lab 现在把“内部 heading”与“可见箭头角度”分离;选路仍可参考当前 heading,但屏幕上看到的箭头不再像车头一样沿切线持续转向,只在转弯时轻微 lean。
+- 2026-04-20:按用户反馈把左上角 5 个 slider 恢复回来,并重新接到 heading-driven 路径几何与 progress spring;当前 slider 明确只作为本地调参入口,不宣称是已完全确认的官方字段映射。
+- 2026-04-20:继续按用户反馈把左上角控件区裁成纯 slider,并把 slider label / panel accent 收回当前中性灰紫主色系;不再保留 `REPLAY` / `RESET` 按钮和额外 metrics 文案,避免信息噪音和低对比白字。
+- 2026-04-20:修正窗口 resize 时的状态重置 bug;`proxy.size` 变化现在只更新 canvas bounds,不再重新走 `configure + snap(to: start)`,因此调整窗口大小不会把 cursor 强行拉回起始点。
+- 2026-04-20:基于 `Codex Computer Use.app` 的新一轮 timing 逆向,确认默认 move 的 wall-clock endpoint-lock 是固定的 `343 / 240 = 1.4291667s`;lab 现已移除距离驱动的 travel-duration 压缩,默认档直接按官方 spring timeline 走,`SPRING` slider 只再改变 spring 本身的 response / damping 与对应时长。
## 决策记录
@@ -76,3 +80,4 @@
- 2026-04-19:在拿到更完整的 binary-backed 路径与视觉层实现后,lab 改为直接演示 recovered 结构,不再把未经确认的 slider 语义继续当成主实现。
- 2026-04-19:对 `swift_once` 恢复出的 guide 系数,当前默认采用“常量已确认、世界坐标解释不成立、局部基底投影更贴近官方视频”的实现策略;后续如果拿到更强的二进制级证据,再继续下沉这层解释。
- 2026-04-19:raw binary lift 的 `20` candidate pool 保留在 `StandaloneCursor` 这条分析线;`StandaloneCursorLab` 和主 runtime overlay 则统一切到 heading-driven 主线,实现上优先保证“朝向约束 + 单侧转弯”这个更贴近官方视频的结构行为。
+- 2026-04-20:恢复 slider UI 时,继续把“调参入口”和“binary-confirmed 结构”分开表述;lab 可以暴露 `start/end handle`、`arc size/flow`、`spring` 这些测试旋钮,但文档和代码都不把它们说成官方一一字段对照。
diff --git a/docs/histories/2026-04/20260418-1430-standalone-cursor-lab.md b/docs/histories/2026-04/20260418-1430-standalone-cursor-lab.md
index b5d3f8e..24de98d 100644
--- a/docs/histories/2026-04/20260418-1430-standalone-cursor-lab.md
+++ b/docs/histories/2026-04/20260418-1430-standalone-cursor-lab.md
@@ -107,3 +107,57 @@
### 📁 Additional Files Modified
- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
- `experiments/StandaloneCursorLab/README.md`
+
+### 🔁 Follow-up (2026-04-20, restore slider tuning surface)
+**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+
+**Key Actions:**
+- **[恢复左上角 slider 面板]**: 把用户指出被删掉的 `START HANDLE`、`END HANDLE`、`ARC SIZE`、`ARC FLOW`、`SPRING` 五个滑块重新加回 `StandaloneCursorLab` 左上角,并保留 `REPLAY` / candidate metrics 作为辅助观察面板。
+- **[重新接回参数语义]**: `CursorMotionParameters` 不再只是空壳默认值;现在这些 slider 会直接驱动 heading-driven path builder 的 start/end handle、arc size/flow,以及 progress spring 配置和 travel duration。
+- **[补自定义滑块样式]**: 用更接近用户截图的细轨道 + 白色圆形 thumb 实现本地调参控件,避免直接退回系统默认控件风格。
+- **[同步文档边界]**: `StandaloneCursorLab` README 和 active execution plan 都改成显式说明“slider 是本地调参入口,不等于已 binary-confirmed 的官方字段映射”。
+
+### 📁 Additional Files Modified
+- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift`
+- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
+- `experiments/StandaloneCursorLab/README.md`
+- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
+
+### 🔁 Follow-up (2026-04-20, align default move speed with official endpoint-lock timing)
+**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+
+**Key Actions:**
+- **[移除距离驱动时长压缩]**: `StandaloneCursorLab` 的默认 move 不再用本地经验公式根据路径长度压缩 wall-clock 时长,避免中长距离移动明显快于官方。
+- **[默认档对齐官方 1.429s timeline]**: 基于最新逆向确认的 `343 / 240 = 1.4291667s` endpoint-lock 时间,把默认 `response=1.4 / damping=0.9` 档位直接对齐到官方 spring timeline。
+- **[保留 spring slider 但收紧语义]**: `SPRING` slider 继续只改变 progress spring 的 response / damping 与对应 settle 时间,不再叠加独立的 distance-based duration fudge factor。
+- **[同步文档口径]**: README 和 active plan 现在都明确写出默认档的官方 endpoint-lock 时长,避免继续把 move 速度表述成不稳定的本地校准结果。
+
+### 📁 Additional Files Modified
+- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift`
+- `experiments/StandaloneCursorLab/README.md`
+- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
+
+### 🔁 Follow-up (2026-04-20, simplify slider panel styling)
+**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+
+**Key Actions:**
+- **[移除左上角多余文案]**: 把 slider 面板里的 `REPLAY`、`RESET`、heading-driven 标题和 candidate metrics 全部移除,只保留 5 个调参 slider。
+- **[收回当前色系]**: 面板文字从低对比的白色改回深色,slider accent 也从偏粉高亮切回当前 lab 的中性灰紫主色系。
+- **[同步说明文档]**: README 和 active plan 不再把左上角 panel 描述成带 `REPLAY` 的观察面板,而是明确为纯 slider 调参入口。
+
+### 📁 Additional Files Modified
+- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
+- `experiments/StandaloneCursorLab/README.md`
+- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
+
+### 🔁 Follow-up (2026-04-20, preserve cursor state on resize)
+**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+
+**Key Actions:**
+- **[修正 resize 回跳]**: 窗口尺寸变化时不再重新调用 `configure(...)+snap(to: start)`;现在只更新 canvas bounds,避免 cursor 因为 resize 被强制拉回起始点。
+- **[移除错误的 resize clamp]**: 左上角 slider 面板和 canvas 的 resize 流程不再顺手重写 `start/end` 坐标,避免窗口变化意外改写当前会话状态。
+- **[同步记录]**: active plan 补充这次 resize bugfix,明确“调窗口大小不应改变当前 cursor 位置”已经收口。
+
+### 📁 Additional Files Modified
+- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
+- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
diff --git a/experiments/StandaloneCursorLab/README.md b/experiments/StandaloneCursorLab/README.md
index b821a84..d86c04e 100644
--- a/experiments/StandaloneCursorLab/README.md
+++ b/experiments/StandaloneCursorLab/README.md
@@ -17,7 +17,7 @@
- 官方风格 `VelocityVerlet` spring progress
- 独立 visual dynamics,用 visible tip/velocity/angle/fog 来驱动姿态
- `Sources/CursorLabRootView.swift`
- - 本地 demo UI、候选路径 overlay、`REPLAY` 与点击交互
+ - 本地 demo UI、slider 调参面板、候选路径 overlay 与点击交互
- `Sources/SynthesizedCursorGlyphView.swift`
- 参考 `scripts/render-synthesized-software-cursor.swift` 的 baseline/procedural cursor renderer
@@ -38,11 +38,12 @@ swift run StandaloneCursorLab
现阶段支持:
- 点击画布任意位置,先预览当前 heading-driven candidate 族,再自动选一路径并驱动 cursor 过去。
-- `REPLAY` 会从固定起点重新跑同一条选中路径,便于反复观察收尾曲线和姿态变化。
+- 左上角保留 `START HANDLE`、`END HANDLE`、`ARC SIZE`、`ARC FLOW`、`SPRING` 5 个 slider,面板本身不再附带 `REPLAY` / `RESET` 按钮或额外指标文案,便于直接对照当前轨迹和画面观感。
- debug overlay 会显示控制点、arc handle 和当前选中的 candidate id / score。
- 关闭 `DEBUG` 后不会展示任何轨迹线或目标点,只保留 cursor 本体,便于单独观察最终运动观感。
- lab 主线不再直接复用 raw binary lift 的 `20` 条 candidate + score;当前改为 reverse-engineering 约束下的 heading-driven chooser,把起始朝向和最终 resting pose 一起喂给路径选择器,让默认曲线更稳定收敛到单侧 C 形或近直线。
- 主路径进度不再用 speculative `easeInOut` 或 terminal settle;现在直接复用官方风格 spring progress。
+- 默认档的 wall-clock move 时长现在直接对齐 reverse-engineered 官方 endpoint-lock 时间 `343 / 240 = 1.4291667s`;不再额外按路径距离压缩时长。
- 可见 cursor 不再直接贴在 path sample 上,而是经过独立 visual dynamics 状态,再输出 `rotation + cursorBodyOffset + fogOffset + fogScale`。
- 候选路径现在显式约束“先顺车头方向掉头,再沿主轴推进,再按 resting pose 收尾”;因此大多数跨向移动会呈现单侧 C 形,需要直接切入时才会退化为近直线,而不会再出现两侧乱甩的 S 形扭曲。
- 箭头的可见角度不再像“车头”一样持续指向移动方向;当前会保留更接近默认 cursor 的静止姿态,只在转弯时给一点轻微 lean,并在停住后继续做原地小摆角。
@@ -52,6 +53,8 @@ swift run StandaloneCursorLab
后续实现应优先保持:
- 不要再把未验证的 slider 参数语义伪装成“官方实现”。
+- slider 可以作为本地调参入口保留,但要明确它们是 heading-driven lab 的测试旋钮,不是已经 binary-confirmed 的一一字段映射。
+- `SPRING` slider 可以改变 spring 本身的 response / damping 与对应 settle 时间,但默认档应继续保持官方 `1.4291667s` endpoint-lock 节奏。
- 路径层、progress 层和 visible pose 层继续保持分离。
- 没有真实 target window 的场景里,要明确区分 `StandaloneCursor` 的 raw reverse-engineered pool 和 `StandaloneCursorLab` 的 heading-driven 主线实现。
- demo host 可以替换,但 motion model 和 visual dynamics 应保持可单独复用。
diff --git a/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift b/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift
index c853a1f..5d9f514 100644
--- a/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift
+++ b/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift
@@ -8,11 +8,14 @@ private enum CursorLabPalette {
static let mainSoft = Color(red: 0.95, green: 0.95, blue: 0.97)
static let mainMuted = Color(red: 0.82, green: 0.81, blue: 0.85)
static let mainStrong = Color(red: 0.63, green: 0.62, blue: 0.68)
+ static let accent = Color(red: 0.58, green: 0.57, blue: 0.65)
+ static let accentSoft = Color(red: 0.77, green: 0.76, blue: 0.82)
}
struct CursorLabRootView: View {
@State private var start = CGPoint(x: 220, y: 440)
@State private var end = CGPoint(x: 860, y: 260)
+ @State private var motionParameters = CursorMotionParameters.default
@State private var debugEnabled = true
@State private var mailEnabled = false
@State private var clickEnabled = true
@@ -31,12 +34,16 @@ struct CursorLabRootView: View {
model: model
)
.onAppear {
- model.configure(start: start, end: end, canvasSize: proxy.size)
+ model.configure(
+ start: start,
+ end: end,
+ canvasSize: proxy.size,
+ parameters: motionParameters
+ )
model.replay(from: start, to: end)
}
.onChange(of: proxy.size) { _, newSize in
- clampPoints(to: newSize)
- model.configure(start: start, end: end, canvasSize: newSize)
+ model.updateCanvasSize(newSize)
}
.onChange(of: start) { _, newValue in
model.updateStart(newValue)
@@ -44,6 +51,9 @@ struct CursorLabRootView: View {
.onChange(of: end) { _, newValue in
model.queueMove(to: newValue)
}
+ .onChange(of: motionParameters) { _, newValue in
+ model.updateParameters(newValue, start: start, end: end)
+ }
}
.overlay(alignment: .topLeading) {
controlPanel
@@ -57,27 +67,31 @@ struct CursorLabRootView: View {
}
private var controlPanel: some View {
- VStack(alignment: .leading, spacing: 10) {
- Text("HEADING-DRIVEN MOTION")
- .font(.system(size: 10, weight: .black, design: .rounded))
- .foregroundStyle(CursorLabPalette.ink.opacity(0.82))
- .tracking(0.8)
-
- Text(model.selectionLabel)
- .font(.system(size: 10, weight: .bold, design: .rounded))
- .foregroundStyle(CursorLabPalette.ink.opacity(0.68))
- .tracking(0.6)
-
- Text(model.selectionMetricsLabel)
- .font(.system(size: 10, weight: .medium, design: .rounded))
- .foregroundStyle(CursorLabPalette.ink.opacity(0.52))
-
- Button("REPLAY") {
- model.replay(from: start, to: end)
- }
- .buttonStyle(CursorActionButtonStyle())
- .padding(.top, 6)
+ VStack(alignment: .leading, spacing: 12) {
+ CursorParameterSliderRow(
+ title: "START HANDLE",
+ value: $motionParameters.startHandle
+ )
+ CursorParameterSliderRow(
+ title: "END HANDLE",
+ value: $motionParameters.endHandle
+ )
+ CursorParameterSliderRow(
+ title: "ARC SIZE",
+ value: $motionParameters.arcSize
+ )
+ CursorParameterSliderRow(
+ title: "ARC FLOW",
+ value: $motionParameters.arcFlow
+ )
+ CursorParameterSliderRow(
+ title: "SPRING",
+ value: $motionParameters.spring
+ )
}
+ .padding(.horizontal, 16)
+ .padding(.vertical, 14)
+ .background(CursorPanelBackground())
}
private var togglePanel: some View {
@@ -88,13 +102,6 @@ struct CursorLabRootView: View {
}
}
- 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
@@ -128,6 +135,7 @@ final class CursorLabViewModel: ObservableObject {
private var previewRemaining: CGFloat = 0
private var queuedTarget = CGPoint(x: 860, y: 260)
private var canvasBounds = CGRect(x: 0, y: 0, width: 1080, height: 720)
+ private var motionParameters = CursorMotionParameters.default
var selectionLabel: String {
guard let selectedCandidate else {
@@ -156,7 +164,14 @@ final class CursorLabViewModel: ObservableObject {
candidates.first(where: { $0.id == selectedCandidateID }) ?? candidates.first
}
- func configure(start: CGPoint, end: CGPoint, canvasSize: CGSize) {
+ func configure(
+ start: CGPoint,
+ end: CGPoint,
+ canvasSize: CGSize,
+ parameters: CursorMotionParameters
+ ) {
+ motionParameters = parameters
+ simulator.updateParameters(parameters)
queuedTarget = end
canvasBounds = CGRect(origin: .zero, size: canvasSize)
let selection = bestSelection(
@@ -174,6 +189,29 @@ final class CursorLabViewModel: ObservableObject {
ensureDisplayLink()
}
+ func updateCanvasSize(_ canvasSize: CGSize) {
+ canvasBounds = CGRect(origin: .zero, size: canvasSize)
+ }
+
+ func updateParameters(_ parameters: CursorMotionParameters, start: CGPoint, end: CGPoint) {
+ motionParameters = parameters
+ simulator.updateParameters(parameters)
+ queuedTarget = end
+
+ let selection = bestSelection(
+ from: start,
+ to: end,
+ startRotation: CursorGlyphCalibration.restingRotation
+ )
+ candidates = selection.candidates
+ selectedCandidateID = selection.selected.id
+ path = selection.selected.path
+ currentState = simulator.snap(to: currentState.point, path: selection.selected.path)
+ clickPulse = 0
+ previewRemaining = 0
+ lastTimestamp = nil
+ }
+
func updateStart(_ value: CGPoint) {
let selection = bestSelection(
from: value,
@@ -285,6 +323,7 @@ final class CursorLabViewModel: ObservableObject {
start: start,
end: end,
bounds: selectionBounds,
+ parameters: motionParameters,
startForward: headingVector(rotation: startRotation),
endForward: headingVector(rotation: CursorGlyphCalibration.restingRotation)
)
@@ -579,6 +618,106 @@ private struct SynthesizedCursorGlyphRepresentable: NSViewRepresentable {
}
}
+private struct CursorParameterSliderRow: View {
+ let title: String
+ @Binding var value: CGFloat
+
+ var body: some View {
+ HStack(spacing: 16) {
+ CursorParameterSlider(value: $value)
+ .frame(width: 142, height: 24)
+
+ VStack(alignment: .leading, spacing: 2) {
+ Text(title)
+ .font(.system(size: 10, weight: .black, design: .rounded))
+ .foregroundStyle(CursorLabPalette.ink.opacity(0.82))
+ .tracking(0.8)
+
+ Text(String(format: "%.2f", Double(value)))
+ .font(.system(size: 9, weight: .semibold, design: .monospaced))
+ .foregroundStyle(CursorLabPalette.mainStrong.opacity(0.90))
+ }
+ .frame(width: 110, alignment: .leading)
+ }
+ }
+}
+
+private struct CursorParameterSlider: View {
+ @Binding var value: CGFloat
+ let range: ClosedRange<CGFloat>
+
+ init(value: Binding<CGFloat>, range: ClosedRange<CGFloat> = 0...1) {
+ _value = value
+ self.range = range
+ }
+
+ var body: some View {
+ GeometryReader { proxy in
+ let width = max(proxy.size.width, 1)
+ let normalized = ((value - range.lowerBound) / (range.upperBound - range.lowerBound)).clamped(to: 0...1)
+ let knobCenterX = normalized * width
+
+ ZStack(alignment: .leading) {
+ Capsule()
+ .fill(CursorLabPalette.ink.opacity(0.12))
+ .frame(height: 5)
+
+ Capsule()
+ .fill(
+ LinearGradient(
+ colors: [CursorLabPalette.accent, CursorLabPalette.accentSoft],
+ startPoint: .leading,
+ endPoint: .trailing
+ )
+ )
+ .frame(width: max(knobCenterX, 8), height: 5)
+
+ Circle()
+ .fill(CursorLabPalette.mainSoft)
+ .frame(width: 24, height: 24)
+ .overlay {
+ Circle()
+ .stroke(Color.white.opacity(0.64), lineWidth: 1)
+ }
+ .shadow(color: CursorLabPalette.ink.opacity(0.12), radius: 8, y: 3)
+ .offset(x: knobCenterX - 12)
+ }
+ .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .leading)
+ .contentShape(Rectangle())
+ .gesture(
+ DragGesture(minimumDistance: 0)
+ .onChanged { gesture in
+ let clampedX = gesture.location.x.clamped(to: 0...width)
+ let progress = clampedX / width
+ value = (range.lowerBound + ((range.upperBound - range.lowerBound) * progress))
+ .clamped(to: range)
+ }
+ )
+ }
+ }
+}
+
+private struct CursorPanelBackground: View {
+ var body: some View {
+ RoundedRectangle(cornerRadius: 26, style: .continuous)
+ .fill(
+ LinearGradient(
+ colors: [
+ CursorLabPalette.mainSoft.opacity(0.82),
+ CursorLabPalette.main.opacity(0.72),
+ ],
+ startPoint: .topLeading,
+ endPoint: .bottomTrailing
+ )
+ )
+ .overlay {
+ RoundedRectangle(cornerRadius: 26, style: .continuous)
+ .stroke(Color.white.opacity(0.30), lineWidth: 1)
+ }
+ .shadow(color: CursorLabPalette.ink.opacity(0.10), radius: 20, y: 8)
+ }
+}
+
private struct CursorToggleRow: View {
let title: String
@Binding var isOn: Bool
@@ -618,18 +757,6 @@ private struct CursorToggleStyle: ToggleStyle {
}
}
-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(CursorLabPalette.ink.opacity(configuration.isPressed ? 0.16 : 0.10))
- .foregroundStyle(CursorLabPalette.ink.opacity(0.88))
- .clipShape(Capsule())
- }
-}
-
private struct CursorLabBackground: View {
var body: some View {
LinearGradient(
diff --git a/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift b/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift
index 82721f8..6afb1c6 100644
--- a/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift
+++ b/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift
@@ -2,7 +2,49 @@ import CoreGraphics
import Foundation
struct CursorMotionParameters: Equatable {
- static let `default` = CursorMotionParameters()
+ var startHandle: CGFloat
+ var endHandle: CGFloat
+ var arcSize: CGFloat
+ var arcFlow: CGFloat
+ var spring: CGFloat
+
+ static let `default` = CursorMotionParameters(
+ startHandle: 0.29,
+ endHandle: 0.08,
+ arcSize: 0.06,
+ arcFlow: 0.64,
+ spring: 0.5
+ )
+
+ init(
+ startHandle: CGFloat = 0.29,
+ endHandle: CGFloat = 0.08,
+ arcSize: CGFloat = 0.06,
+ arcFlow: CGFloat = 0.64,
+ spring: CGFloat = 0.5
+ ) {
+ self.startHandle = startHandle.clamped(to: 0...1)
+ self.endHandle = endHandle.clamped(to: 0...1)
+ self.arcSize = arcSize.clamped(to: 0...1)
+ self.arcFlow = arcFlow.clamped(to: 0...1)
+ self.spring = spring.clamped(to: 0...1)
+ }
+
+ var progressSpringConfiguration: CursorMotionSpringConfiguration {
+ CursorMotionSpringConfiguration(
+ response: 0.96 + (0.88 * spring),
+ dampingFraction: 0.98 - (0.16 * spring)
+ )
+ }
+
+ func calibratedTravelDuration(
+ distance _: CGFloat,
+ measurement _: CursorMotionMeasurement
+ ) -> CGFloat {
+ // The official move timing is driven by the spring reaching endpoint lock,
+ // not by an extra distance-based wall-clock scaling layer.
+ CursorMotionProgressAnimator.closeEnoughTime(configuration: progressSpringConfiguration)
+ }
}
struct CursorMotionSegment: Equatable {
@@ -227,26 +269,32 @@ struct CursorMotionSpringConfiguration: Equatable {
let closeEnoughDistanceThreshold: CGFloat
let idleVelocityThreshold: CGFloat
- static let official: CursorMotionSpringConfiguration = {
- let response: CGFloat = 1.4
- let dampingFraction: CGFloat = 0.9
- let dt: CGFloat = 1.0 / 240.0
- let idleVelocityThreshold: CGFloat = 28_800
+ init(
+ response: CGFloat,
+ dampingFraction: CGFloat,
+ dt: CGFloat = 1.0 / 240.0,
+ closeEnoughProgressThreshold: CGFloat = 1,
+ closeEnoughDistanceThreshold: CGFloat = 0.01,
+ idleVelocityThreshold: CGFloat = 28_800
+ ) {
let rawStiffness = response > 0 ? pow((2 * .pi) / response, 2) : .infinity
let stiffness = min(rawStiffness, idleVelocityThreshold)
let drag = 2 * dampingFraction * sqrt(stiffness)
- return CursorMotionSpringConfiguration(
- response: response,
- dampingFraction: dampingFraction,
- stiffness: stiffness,
- drag: drag,
- dt: dt,
- closeEnoughProgressThreshold: 1,
- closeEnoughDistanceThreshold: 0.01,
- idleVelocityThreshold: idleVelocityThreshold
- )
- }()
+ self.response = response
+ self.dampingFraction = dampingFraction
+ self.stiffness = stiffness
+ self.drag = drag
+ self.dt = dt
+ self.closeEnoughProgressThreshold = closeEnoughProgressThreshold
+ self.closeEnoughDistanceThreshold = closeEnoughDistanceThreshold
+ self.idleVelocityThreshold = idleVelocityThreshold
+ }
+
+ static let official = CursorMotionSpringConfiguration(
+ response: 1.4,
+ dampingFraction: 0.9
+ )
}
struct CursorMotionSpringState: Equatable {
@@ -256,6 +304,8 @@ struct CursorMotionSpringState: Equatable {
}
enum CursorMotionProgressAnimator {
+ private static let officialEndpointLockTime: CGFloat = 343.0 / 240.0
+
static func advance(
current: CGFloat,
target: CGFloat = 1,
@@ -316,6 +366,10 @@ enum CursorMotionProgressAnimator {
static func closeEnoughTime(
configuration: CursorMotionSpringConfiguration = .official
) -> CGFloat {
+ if configuration == .official {
+ return officialEndpointLockTime
+ }
+
var current: CGFloat = 0
var state = CursorMotionSpringState()
var step = 0
@@ -505,14 +559,6 @@ enum OfficialCursorMotionModel {
}
}
- static func calibratedTravelDuration(distance: CGFloat, measurement: CursorMotionMeasurement) -> CGFloat {
- let weightedRatio = max((measurement.length / max(distance, 1)) - 1, 0)
- let distanceTerm = 0.18 + min(distance / 1300, 0.35)
- let curvatureTerm = min(weightedRatio, 1.5) * 0.18
- let settleTerm = min(weightedRatio, 1.0) * 0.04
- return max(distanceTerm + curvatureTerm + settleTerm, 0.23)
- }
-
private static func makeCandidate(
id: String,
kind: CursorMotionKind,
@@ -607,16 +653,13 @@ enum OfficialCursorMotionModel {
}
enum HeadingDrivenCursorMotionModel {
- private static let defaultStartHandle: CGFloat = 0.29
- private static let defaultEndHandle: CGFloat = 0.08
- private static let defaultArcSize: CGFloat = 0.06
- private static let defaultArcFlow: CGFloat = 0.64
private static let normalizationEpsilon: CGFloat = 0.001
static func makeCandidates(
start: CGPoint,
end: CGPoint,
bounds: CGRect?,
+ parameters: CursorMotionParameters,
startForward: CGVector,
endForward: CGVector
) -> [CursorMotionCandidate] {
@@ -641,6 +684,7 @@ enum HeadingDrivenCursorMotionModel {
to: end,
metrics: metrics,
descriptor: descriptor,
+ parameters: parameters,
startForward: resolvedStartForward,
endForward: resolvedEndForward
)
@@ -673,29 +717,26 @@ enum HeadingDrivenCursorMotionModel {
}
}
- static func calibratedTravelDuration(distance: CGFloat, measurement: CursorMotionMeasurement) -> CGFloat {
- OfficialCursorMotionModel.calibratedTravelDuration(distance: distance, measurement: measurement)
- }
-
private static func makePath(
from start: CGPoint,
to end: CGPoint,
metrics: MotionMetrics,
descriptor: MotionDescriptor,
+ parameters: CursorMotionParameters,
startForward: CGVector,
endForward: CGVector
) -> CursorMotionPath {
let distance = metrics.distance
let direction = metrics.direction
let normal = metrics.normal
- let resolvedFlow = (defaultArcFlow + descriptor.flowShift).clamped(to: 0...1)
+ let resolvedFlow = (parameters.arcFlow + descriptor.flowShift).clamped(to: 0...1)
let flowBias = (resolvedFlow - 0.5) * distance * 0.18
- let baseStartReach = distance * (0.10 + defaultStartHandle * 0.56)
- let baseEndReach = distance * (0.11 + defaultEndHandle * 0.62)
+ 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 + defaultArcSize * 0.92) * descriptor.arcScale * distanceLift, 20),
+ max(distance * (0.10 + parameters.arcSize * 0.92) * descriptor.arcScale * distanceLift, 20),
distance * 0.96
)
@@ -1455,6 +1496,8 @@ final class CursorMotionSimulator {
private var phase: CursorMotionPhase
private var progress: CGFloat
private var progressSpringState: CursorMotionSpringState
+ private var progressSpringConfiguration: CursorMotionSpringConfiguration
+ private var progressCloseEnoughTime: CGFloat
private var moveElapsed: CGFloat
private var travelDuration: CGFloat
private var visualState: CursorVisualDynamicsState
@@ -1462,6 +1505,7 @@ final class CursorMotionSimulator {
private var idlePhase: CGFloat
init(start: CGPoint, end: CGPoint, parameters: CursorMotionParameters) {
+ let progressSpringConfiguration = parameters.progressSpringConfiguration
self.parameters = parameters
path = CursorMotionPath(start: start, end: end)
self.start = start
@@ -1470,8 +1514,12 @@ final class CursorMotionSimulator {
phase = .idle(restingTipPosition: start)
progress = 1
progressSpringState = CursorMotionSpringState()
+ self.progressSpringConfiguration = progressSpringConfiguration
+ progressCloseEnoughTime = CursorMotionProgressAnimator.closeEnoughTime(
+ configuration: progressSpringConfiguration
+ )
moveElapsed = 0
- travelDuration = OfficialCursorMotionModel.calibratedTravelDuration(
+ travelDuration = parameters.calibratedTravelDuration(
distance: distanceBetween(start, end),
measurement: measurement
)
@@ -1480,6 +1528,14 @@ final class CursorMotionSimulator {
idlePhase = 0
}
+ func updateParameters(_ parameters: CursorMotionParameters) {
+ self.parameters = parameters
+ progressSpringConfiguration = parameters.progressSpringConfiguration
+ progressCloseEnoughTime = CursorMotionProgressAnimator.closeEnoughTime(
+ configuration: progressSpringConfiguration
+ )
+ }
+
@discardableResult
func snap(to point: CGPoint, path newPath: CursorMotionPath? = nil) -> CursorMotionState {
if let newPath {
@@ -1508,7 +1564,7 @@ final class CursorMotionSimulator {
progressSpringState = CursorMotionSpringState()
moveElapsed = 0
idlePhase = 0
- travelDuration = OfficialCursorMotionModel.calibratedTravelDuration(
+ travelDuration = parameters.calibratedTravelDuration(
distance: distanceBetween(path.start, path.end),
measurement: measurement
)
@@ -1527,16 +1583,21 @@ final class CursorMotionSimulator {
case .moving:
moveElapsed += clampedDelta
let normalizedElapsed = (moveElapsed / max(travelDuration, 0.001)).clamped(to: 0...1)
- let springTime = normalizedElapsed * OfficialCursorMotionModel.closeEnoughTime
+ let springTime = normalizedElapsed * progressCloseEnoughTime
(progress, progressSpringState) = CursorMotionProgressAnimator.advance(
current: progress,
state: progressSpringState,
+ configuration: progressSpringConfiguration,
to: springTime
)
let sample = path.sample(at: progress)
let renderState = advanceVisualDynamics(toward: sample.point)
- let finished = normalizedElapsed >= 1 || CursorMotionProgressAnimator.isCloseEnough(progress: progress)
+ let finished = normalizedElapsed >= 1
+ || CursorMotionProgressAnimator.isCloseEnough(
+ progress: progress,
+ configuration: progressSpringConfiguration
+ )
if finished {
progress = 1