Skip to content

๐Ÿ‘พ Open Computer Use โ€“ Open-Source Alternative to Codex Computer Use

69.9 KB
Raw Blame
from __future__ import annotations

import argparse
import json
import math
import struct
from dataclasses import asdict, dataclass
from pathlib import Path
from typing import Iterable


DEFAULT_APP_PATH = (
    Path.home()
    / ".codex/plugins/cache/openai-bundled/computer-use/1.0.750/Codex Computer Use.app/Contents/MacOS/SkyComputerUseService"
)

TEXT_BASE_VM = 0x100000000


@dataclass(frozen=True)
class Section:
    segname: str
    sectname: str
    addr: int
    size: int
    offset: int


class MachOBinary:
    LC_SEGMENT_64 = 0x19

    def __init__(self, path: Path):
        self.path = path
        self.data = path.read_bytes()
        self.sections = self._parse_sections()

    def _parse_sections(self) -> list[Section]:
        data = self.data
        magic = struct.unpack_from("<I", data, 0)[0]
        if magic != 0xFEEDFACF:
            raise ValueError(f"unsupported Mach-O magic: {magic:#x}")

        _, _, _, _, ncmds, _, _, _ = struct.unpack_from("<IiiIIIII", data, 0)
        offset = 32
        sections: list[Section] = []

        for _ in range(ncmds):
            cmd, cmdsize = struct.unpack_from("<II", data, offset)
            if cmd == self.LC_SEGMENT_64:
                segname_raw = struct.unpack_from("<16s", data, offset + 8)[0]
                segname = segname_raw.split(b"\x00", 1)[0].decode("ascii", "replace")
                nsects = struct.unpack_from("<I", data, offset + 64)[0]
                sect_offset = offset + 72
                for _ in range(nsects):
                    sectname_raw, sec_segname_raw = struct.unpack_from("<16s16s", data, sect_offset)
                    sectname = sectname_raw.split(b"\x00", 1)[0].decode("ascii", "replace")
                    sec_segname = sec_segname_raw.split(b"\x00", 1)[0].decode("ascii", "replace")
                    addr, size, fileoff = struct.unpack_from("<QQI", data, sect_offset + 32)
                    sections.append(
                        Section(
                            segname=sec_segname or segname,
                            sectname=sectname,
                            addr=addr,
                            size=size,
                            offset=fileoff,
                        )
                    )
                    sect_offset += 80
            offset += cmdsize

        return sections

    def section(self, segname: str, sectname: str) -> Section:
        for section in self.sections:
            if section.segname == segname and section.sectname == sectname:
                return section
        raise KeyError(f"missing section {segname},{sectname}")

    def vm_to_file_offset(self, vmaddr: int) -> int:
        for section in self.sections:
            if section.addr <= vmaddr < section.addr + section.size:
                return section.offset + (vmaddr - section.addr)
        raise KeyError(f"vmaddr {vmaddr:#x} not in any section")

    def read_c_string(self, vmaddr: int) -> str | None:
        try:
            file_offset = self.vm_to_file_offset(vmaddr)
        except KeyError:
            return None
        end = self.data.find(b"\x00", file_offset)
        if end == -1:
            return None
        raw = self.data[file_offset:end]
        try:
            return raw.decode("utf-8", "replace")
        except UnicodeDecodeError:
            return None

    def read_double(self, vmaddr: int) -> float:
        file_offset = self.vm_to_file_offset(vmaddr)
        return struct.unpack_from("<d", self.data, file_offset)[0]


@dataclass(frozen=True)
class MotionTypeInfo:
    name: str
    kind: int
    fields: list[str]


def extract_motion_type_fields(binary: MachOBinary) -> list[MotionTypeInfo]:
    reflstr = binary.section("__TEXT", "__swift5_reflstr")
    fieldmd = binary.section("__TEXT", "__swift5_fieldmd")
    types = binary.section("__TEXT", "__swift5_types")
    const_sections = [
        binary.section("__TEXT", "__const"),
        binary.section("__TEXT", "__constg_swiftt"),
        binary.section("__TEXT", "__swift5_typeref"),
        reflstr,
        fieldmd,
        types,
    ]

    def cstr(vmaddr: int) -> str | None:
        for section in const_sections:
            if section.addr <= vmaddr < section.addr + section.size:
                file_offset = section.offset + (vmaddr - section.addr)
                end = binary.data.find(b"\x00", file_offset)
                if end == -1:
                    return None
                return binary.data[file_offset:end].decode("utf-8", "replace")
        return None

    field_map: dict[int, tuple[int, list[str]]] = {}
    pos = fieldmd.offset
    end = fieldmd.offset + fieldmd.size
    while pos < end:
        _, _, kind, record_size, field_count = struct.unpack_from("<iiHHI", binary.data, pos)
        desc_vm = fieldmd.addr + (pos - fieldmd.offset)
        field_pos = pos + 16
        fields: list[str] = []
        for _ in range(field_count):
            _, _, field_rel = struct.unpack_from("<Iii", binary.data, field_pos)
            field_name = None
            if field_rel:
                field_name = cstr((fieldmd.addr + (field_pos - fieldmd.offset)) + 8 + field_rel)
            fields.append(field_name or "<unknown>")
            field_pos += record_size
        field_map[desc_vm] = (kind, fields)
        pos = field_pos

    interesting: list[MotionTypeInfo] = []
    seen: set[tuple[str, int]] = set()
    for entry_off in range(0, types.size, 4):
        entry_vm = types.addr + entry_off
        rel = struct.unpack_from("<i", binary.data, types.offset + entry_off)[0]
        desc_vm = entry_vm + rel
        try:
            desc_file = binary.vm_to_file_offset(desc_vm)
        except KeyError:
            continue
        _, _, name_rel, _, field_rel = struct.unpack_from("<IIiii", binary.data, desc_file)
        name = None
        for base in (desc_vm + 8, desc_vm + 12, desc_vm):
            value = cstr(base + name_rel)
            if value and any(ch.isalpha() for ch in value):
                name = value
                break
        if not name:
            continue
        field_desc_vm = desc_vm + 16 + field_rel if field_rel else None
        if field_desc_vm not in field_map:
            continue
        kind, fields = field_map[field_desc_vm]
        needles = (
            "Cursor",
            "Bezier",
            "Spring",
            "Animation",
            "VelocityVerlet",
            "Configuration",
            "DisplayLink",
            "CloseEnough",
        )
        if not any(needle in name for needle in needles):
            continue
        key = (name, field_desc_vm)
        if key in seen:
            continue
        seen.add(key)
        interesting.append(MotionTypeInfo(name=name, kind=kind, fields=fields))

    return sorted(interesting, key=lambda item: item.name)


EXTRACTED_DOUBLE_CONSTANTS = {
    "distance_scale_primary": 0x100865928,
    "direct_span_scale": 0x100865910,
    "side_bias_scale": 0x100865930,
    "distance_scale_secondary": 0x100865938,
    "distance_scale_tertiary": 0x100865940,
    "minimum_step_distance": 0x100865948,
    "pi": 0x100865950,
    "negative_two_pi": 0x100865958,
    "negative_pi": 0x100865960,
    "positive_two_pi": 0x100865968,
    "nearly_negative_one": 0x100865970,
    "epsilon_01": 0x100865978,
    "score_length_weight": 0x100860C10,
    "score_angle_energy_weight": 0x100860C18,
    "score_max_angle_weight": 0x100860C20,
    "score_total_turn_weight": 0x100860C28,
    "score_in_bounds_factor": 0x100860C30,
    "score_secondary_in_bounds_factor": 0x100860C38,
    "score_shape_weight_a": 0x100860C40,
    "score_shape_weight_b": 0x100860C48,
    "score_shape_anchor": 0x100860C50,
}


def extract_named_constants(binary: MachOBinary) -> dict[str, float]:
    return {name: binary.read_double(vmaddr) for name, vmaddr in EXTRACTED_DOUBLE_CONSTANTS.items()}


CONFIRMED_DISASSEMBLY_CONSTANTS = {
    "normalization_epsilon": 0.001,
    "candidate_handle_min": 50.0,
    "candidate_handle_max": 520.0,
    "candidate_arc_min": 38.0,
    "candidate_arc_max": 440.0,
    "score_out_of_bounds_penalty": 45.0,
    "score_excess_length_weight": 320.0,
    "score_angle_energy_weight": 140.0,
    "score_max_angle_weight": 180.0,
    "score_total_turn_weight": 18.0,
}

CONFIRMED_CURSOR_TIMING_CONSTANTS = {
    "close_enough_progress_threshold": 1.0,
    "close_enough_distance_threshold": 0.01,
    "cursor_path_spring_response": 1.4,
    "cursor_path_spring_damping_fraction": 0.9,
    "velocity_verlet_dt": 1.0 / 240.0,
    "velocity_verlet_idle_velocity_threshold": 28800.0,
}

CONFIRMED_TIMING_TYPE_RELATIONSHIPS = {
    "ComputerUseCursor.CloseEnoughConfiguration": {
        "kind": "struct",
        "fields": ["progressThreshold", "distanceThreshold"],
    },
    "ComputerUseCursor.CursorNextInteractionTiming": {
        "kind": "enum",
        "cases": ["closeEnough", "finished"],
    },
    "ComputerUseCursor.Window": {
        "kind": "class",
        "fields": [
            "style",
            "appMonitor",
            "wantsToBeVisible",
            "cursorMotionProgressAnimation",
            "cursorMotionNextInteractionTimingHandler",
            "cursorMotionCompletionHandler",
            "cursorMotionDidSatisfyNextInteractionTiming",
            "currentInterpolatedOrigin",
            "useOverlayWindowLevel",
            "correspondingWindowID",
        ],
    },
    "Animation.SpringParameters": {
        "kind": "struct",
        "fields": ["response", "dampingFraction"],
    },
    "Animation.AnimationDescriptor": {
        "kind": "enum",
        "cases": ["bezier", "spring"],
    },
    "Animation.Transaction": {
        "kind": "struct",
        "fields": ["priority", "delay", "completion", "id", "driverSource", "descriptor"],
    },
    "Animation.VelocityVerletSimulation.Configuration": {
        "kind": "struct",
        "fields": ["response", "stiffness", "drag", "dt", "idleVelocityThreshold"],
    },
}

CONFIRMED_TIMING_PIPELINE = {
    "window_animation_state_slots": {
        "field_order_matches_binary_slot_writes": True,
        "fields_written_in_cursor_path_animation_setup": [
            "cursorMotionProgressAnimation",
            "cursorMotionNextInteractionTimingHandler",
            "cursorMotionCompletionHandler",
            "cursorMotionDidSatisfyNextInteractionTiming",
        ],
    },
    "animation_stack": [
        "ComputerUseCursor.CloseEnoughConfiguration(progressThreshold=1.0, distanceThreshold=0.01)",
        "ComputerUseCursor.CursorNextInteractionTiming.closeEnough(...)",
        "Animation.SpringParameters(response=1.4, dampingFraction=0.9)",
        "Animation.AnimationDescriptor.spring(...)",
        "Animation.SpringAnimation",
        "Animation.VelocityVerletSimulation.Configuration",
    ],
    "binary_functions": {
        "close_enough_metadata_accessor": "0x10005ed78",
        "next_interaction_timing_metadata_accessor": "0x10005ed88",
        "spring_parameters_metadata_accessor": "0x100587990",
        "animation_descriptor_metadata_accessor": "0x100596470",
        "spring_animation_metadata_accessor": "0x1005768c4",
        "spring_animation_allocating_init_wrapper": "0x100576790",
        "spring_animation_designated_init": "0x10057652c",
        "spring_animation_frame_update": "0x1005761bc",
        "spring_animation_value_copy_helper": "0x1005730bc",
        "spring_animation_target_copy_helper": "0x100573390",
        "velocity_verlet_configuration_init": "0x100592f20",
        "velocity_verlet_configuration_completion": "0x100593cfc",
        "velocity_verlet_advance_to_time": "0x100593404",
        "velocity_verlet_advance_one_step": "0x100594110",
        "spring_animation_finished_predicate": "0x1005934b0",
        "transaction_metadata_accessor": "0x1005967fc",
    },
    "spring_parameter_normalization_helper": {
        "function": "0x1005879a4",
        "input_name_in_binary_not_recovered": True,
        "confirmed_piecewise_mapping": "if x <= -1 -> +inf; else if x < 0 -> 1 / (1 + x); else if x == 0 -> 0; else -> 1 - min(x, 1)",
        "note": "This helper lives in the Animation.SpringParameters area; the cursor path animation uses direct response/dampingFraction constants and does not need this remap.",
    },
    "velocity_verlet_completion_status": {
        "two_pi_constant_used": True,
        "stiffness_and_drag_fields_exist": True,
        "exact_numeric_formula_transcription_complete": True,
    },
    "velocity_verlet_exact_math": {
        "stiffness_formula": "stiffness = min(response > 0 ? (2ฯ€ / response)^2 : +inf, 28800)",
        "drag_formula": "drag = 2 * dampingFraction * sqrt(stiffness)",
        "stale_time_clamp": "if targetTime - time > 1.0, set time = targetTime - 1/60 before stepping",
        "step_sequence": [
            "velocityHalf = velocity + force * (dt / 2)",
            "current = current + velocityHalf * dt",
            "force = stiffness * (target - current) + (-drag) * velocityHalf",
            "velocity = velocityHalf + force * (dt / 2)",
        ],
    },
    "spring_animation_update_and_finish": {
        "frame_update_function": "0x1005761bc",
        "confirmed_behavior": [
            "copy a current-value-like buffer from hidden self offset 0x68",
            "copy a target-value-like buffer from hidden self offset 0x70",
            "advance the spring simulation via 0x100593404",
            "run 0x1005934b0 as the finished predicate",
            "return optional nil when finished, otherwise return some(updatedValue)",
        ],
        "finish_predicate_function": "0x1005934b0",
        "finish_predicate_gates": {
            "threshold_square_gate": "load two hidden-self scalar slots, take Swift.max(slotA, slotB), and require max(slotA, slotB) <= threshold^2 to continue",
            "exact_zero_gate": "build a float literal 0.01, run SIMD scalar loops, then accept only when a difference-derived scalar A is neither > 0 nor < 0",
        },
        "field_mapping_notes": {
            "copy_helper_offsets": {
                "0x1005730bc": "reads hidden self offset 0x68",
                "0x100573390": "reads hidden self offset 0x70",
            },
            "threshold_field_inference": "the metadata field loaded via +0x30 in 0x1005934b0 is very likely idleVelocityThreshold; this is inferred from adjacent layout and threshold-squared usage, not a direct symbol name",
            "value_target_field_inference": "the 0x68/0x70 slots are very likely InterpolatableAnimation._value / _targetValue; this mapping is inferred from class field metadata plus offset adjacency, not directly named in the code",
        },
    },
    "shared_helper_reuse": {
        "system_settings_accessory_transition_geometry_style": {
            "spring_response": 0.72,
            "spring_damping_fraction": 1.0,
            "note": "This is a separate bundled-binary caller that reuses part of the same spring initialization chain.",
        }
    },
}


def build_model_constants(binary: MachOBinary) -> dict[str, float]:
    model_constants = extract_named_constants(binary)
    model_constants.update(CONFIRMED_DISASSEMBLY_CONSTANTS)
    return model_constants


def extract_candidate_tables(binary: MachOBinary) -> dict[str, list[float]]:
    table_a_vm = 0x10098B988
    table_b_vm = 0x10098B9C0
    table_a = [binary.read_double(table_a_vm + 0x20 + (index * 8)) for index in range(3)]
    table_b = [binary.read_double(table_b_vm + 0x20 + (index * 8)) for index in range(3)]
    return {"table_a": table_a, "table_b": table_b}


@dataclass(frozen=True)
class Vec2:
    x: float
    y: float

    def __add__(self, other: "Vec2") -> "Vec2":
        return Vec2(self.x + other.x, self.y + other.y)

    def __sub__(self, other: "Vec2") -> "Vec2":
        return Vec2(self.x - other.x, self.y - other.y)

    def scale(self, factor: float) -> "Vec2":
        return Vec2(self.x * factor, self.y * factor)

    def length(self) -> float:
        return math.hypot(self.x, self.y)

    def normalized(self) -> "Vec2":
        length = self.length()
        if length <= 1e-9:
            return Vec2(1.0, 0.0)
        return Vec2(self.x / length, self.y / length)

    def perpendicular(self) -> "Vec2":
        return Vec2(-self.y, self.x)

    def to_list(self) -> list[float]:
        return [self.x, self.y]


@dataclass(frozen=True)
class Bounds:
    min_x: float
    min_y: float
    max_x: float
    max_y: float

    def contains(self, point: Vec2, padding: float = 0.0) -> bool:
        return (
            (self.min_x - padding) <= point.x <= (self.max_x + padding)
            and (self.min_y - padding) <= point.y <= (self.max_y + padding)
        )


@dataclass(frozen=True)
class CubicSegment:
    end: Vec2
    control1: Vec2
    control2: Vec2


@dataclass(frozen=True)
class SamplePoint:
    progress: float
    point: Vec2
    tangent: Vec2
    speed_units_per_progress: float

    def to_dict(self) -> dict[str, object]:
        return {
            "progress": self.progress,
            "point": self.point.to_list(),
            "tangent": self.tangent.to_list(),
            "speed_units_per_progress": self.speed_units_per_progress,
        }


@dataclass(frozen=True)
class CursorMotionMeasurement:
    length: float
    angle_change_energy: float
    max_angle_change: float
    total_turn: float
    stays_in_bounds: bool

    def to_dict(self) -> dict[str, object]:
        return asdict(self)


@dataclass(frozen=True)
class CandidateScoreComponents:
    excess_length_ratio: float
    excess_length_cost: float
    angle_energy_cost: float
    max_angle_cost: float
    total_turn_cost: float
    out_of_bounds_cost: float
    total_score: float

    def to_dict(self) -> dict[str, float]:
        return asdict(self)


@dataclass(frozen=True)
class ScalarSpringConfiguration:
    response: float
    damping_fraction: float
    stiffness: float
    drag: float
    dt: float
    close_enough_progress_threshold: float
    close_enough_distance_threshold: float
    idle_velocity_threshold: float

    def to_dict(self) -> dict[str, float]:
        return asdict(self)


@dataclass(frozen=True)
class ScalarVelocityVerletState:
    time: float
    velocity: float
    force: float

    def to_dict(self) -> dict[str, float]:
        return asdict(self)


@dataclass(frozen=True)
class TimedCursorSample:
    step: int
    time: float
    progress: float
    point: Vec2
    spring_velocity: float
    spring_force: float
    geometric_speed_units_per_second: float

    def to_dict(self) -> dict[str, object]:
        return {
            "step": self.step,
            "time": self.time,
            "progress": self.progress,
            "point": self.point.to_list(),
            "spring_velocity": self.spring_velocity,
            "spring_force": self.spring_force,
            "geometric_speed_units_per_second": self.geometric_speed_units_per_second,
        }


@dataclass(frozen=True)
class CursorMotionPath:
    start: Vec2
    end: Vec2
    start_control: Vec2 | None = None
    arc: Vec2 | None = None
    arc_in: Vec2 | None = None
    arc_out: Vec2 | None = None
    end_control: Vec2 | None = None
    segments: tuple[CubicSegment, ...] = ()

    def sample(self, progress: float) -> tuple[Vec2, Vec2]:
        if not self.segments:
            return self.start, Vec2(1.0, 0.0)

        clamped = min(max(progress, 0.0), 1.0)
        segment_count = len(self.segments)
        if clamped >= 1.0:
            segment_index = segment_count - 1
            local_t = 1.0
        else:
            scaled = clamped * segment_count
            segment_index = min(int(scaled), segment_count - 1)
            local_t = scaled - segment_index

        segment = self.segments[segment_index]
        start = self.start if segment_index == 0 else self.segments[segment_index - 1].end
        point = _sample_cubic(start, segment.control1, segment.control2, segment.end, local_t)
        tangent = _sample_cubic_tangent(start, segment.control1, segment.control2, segment.end, local_t).normalized()
        return point, tangent

    def sample_points(self, count: int) -> list[SamplePoint]:
        samples: list[SamplePoint] = []
        previous_point: Vec2 | None = None
        for index in range(count):
            progress = index / max(count - 1, 1)
            point, tangent = self.sample(progress)
            speed = 0.0 if previous_point is None else (point - previous_point).length()
            samples.append(
                SamplePoint(
                    progress=progress,
                    point=point,
                    tangent=tangent,
                    speed_units_per_progress=speed,
                )
            )
            previous_point = point
        return samples

    def measure(self, bounds: Bounds | None, min_step_distance: float = 0.01, samples_per_segment: int = 24) -> CursorMotionMeasurement:
        total_length = 0.0
        angle_change_energy = 0.0
        max_angle_change = 0.0
        total_turn = 0.0
        stays_in_bounds = True
        previous_point = self.start
        previous_angle: float | None = None

        if bounds is not None:
            stays_in_bounds = bounds.contains(self.start, padding=20.0)

        total_steps = max(len(self.segments) * samples_per_segment, 1)
        for step in range(1, total_steps + 1):
            progress = step / total_steps
            point, _ = self.sample(progress)
            delta = point - previous_point
            step_length = delta.length()

            if bounds is not None and stays_in_bounds:
                stays_in_bounds = bounds.contains(point, padding=20.0)

            if step_length > min_step_distance:
                angle = math.atan2(delta.y, delta.x)
                total_length += step_length

                if previous_angle is not None:
                    angle_delta = angle - previous_angle
                    while angle_delta > math.pi:
                        angle_delta -= math.tau
                    while angle_delta < -math.pi:
                        angle_delta += math.tau
                    angle_change_energy += angle_delta * angle_delta
                    absolute_delta = abs(angle_delta)
                    max_angle_change = max(max_angle_change, absolute_delta)
                    total_turn += absolute_delta

                previous_angle = angle
                previous_point = point

        return CursorMotionMeasurement(
            length=total_length,
            angle_change_energy=angle_change_energy,
            max_angle_change=max_angle_change,
            total_turn=total_turn,
            stays_in_bounds=stays_in_bounds,
        )


@dataclass(frozen=True)
class CandidatePath:
    identifier: str
    kind: str
    side: int
    table_a_scale: float | None
    table_b_scale: float | None
    score: float
    score_components: CandidateScoreComponents
    measurement: CursorMotionMeasurement
    path: CursorMotionPath

    def summary_dict(self) -> dict[str, object]:
        return {
            "identifier": self.identifier,
            "kind": self.kind,
            "side": self.side,
            "table_a_scale": self.table_a_scale,
            "table_b_scale": self.table_b_scale,
            "score": self.score,
            "score_components": self.score_components.to_dict(),
            "measurement": self.measurement.to_dict(),
        }

    def to_dict(self, sample_count: int, include_samples: bool = True) -> dict[str, object]:
        return {
            "identifier": self.identifier,
            "kind": self.kind,
            "side": self.side,
            "table_a_scale": self.table_a_scale,
            "table_b_scale": self.table_b_scale,
            "score": self.score,
            "score_components": self.score_components.to_dict(),
            "measurement": self.measurement.to_dict(),
            "path": {
                "start": self.path.start.to_list(),
                "end": self.path.end.to_list(),
                "start_control": self.path.start_control.to_list() if self.path.start_control else None,
                "arc": self.path.arc.to_list() if self.path.arc else None,
                "arc_in": self.path.arc_in.to_list() if self.path.arc_in else None,
                "arc_out": self.path.arc_out.to_list() if self.path.arc_out else None,
                "end_control": self.path.end_control.to_list() if self.path.end_control else None,
                "segments": [
                    {
                        "end": segment.end.to_list(),
                        "control1": segment.control1.to_list(),
                        "control2": segment.control2.to_list(),
                    }
                    for segment in self.path.segments
                ],
            },
            "samples": [sample.to_dict() for sample in self.path.sample_points(sample_count)] if include_samples else [],
        }


@dataclass(frozen=True)
class BinaryGuidedPathOverrides:
    start_extent_scale: float = 1.0
    end_extent_scale: float = 1.0
    arc_size_scale: float = 1.0
    arc_flow_scale: float = 1.0


def _sample_cubic(start: Vec2, control1: Vec2, control2: Vec2, end: Vec2, t: float) -> Vec2:
    omt = 1.0 - t
    omt2 = omt * omt
    t2 = t * t
    return Vec2(
        x=(omt2 * omt * start.x)
        + (3.0 * omt2 * t * control1.x)
        + (3.0 * omt * t2 * control2.x)
        + (t2 * t * end.x),
        y=(omt2 * omt * start.y)
        + (3.0 * omt2 * t * control1.y)
        + (3.0 * omt * t2 * control2.y)
        + (t2 * t * end.y),
    )


def _sample_cubic_tangent(start: Vec2, control1: Vec2, control2: Vec2, end: Vec2, t: float) -> Vec2:
    omt = 1.0 - t
    return Vec2(
        x=(3.0 * omt * omt * (control1.x - start.x))
        + (6.0 * omt * t * (control2.x - control1.x))
        + (3.0 * t * t * (end.x - control2.x)),
        y=(3.0 * omt * omt * (control1.y - start.y))
        + (6.0 * omt * t * (control2.y - control1.y))
        + (3.0 * t * t * (end.y - control2.y)),
    )


def clamp(value: float, minimum: float, maximum: float) -> float:
    return max(minimum, min(maximum, value))


def signed_angle(lhs: Vec2, rhs: Vec2) -> float:
    return math.atan2((lhs.x * rhs.y) - (lhs.y * rhs.x), (lhs.x * rhs.x) + (lhs.y * rhs.y))


def build_scalar_spring_configuration() -> ScalarSpringConfiguration:
    response = CONFIRMED_CURSOR_TIMING_CONSTANTS["cursor_path_spring_response"]
    damping_fraction = CONFIRMED_CURSOR_TIMING_CONSTANTS["cursor_path_spring_damping_fraction"]
    return build_scalar_spring_configuration_for(
        response=response,
        damping_fraction=damping_fraction,
    )


def build_scalar_spring_configuration_for(
    response: float,
    damping_fraction: float,
) -> ScalarSpringConfiguration:
    dt = CONFIRMED_CURSOR_TIMING_CONSTANTS["velocity_verlet_dt"]
    idle_velocity_threshold = CONFIRMED_CURSOR_TIMING_CONSTANTS["velocity_verlet_idle_velocity_threshold"]

    # 0x100593cfc computes stiffness from the scalar spring response with:
    # raw = (2ฯ€ / response)^2 if response > 0, otherwise +inf
    raw_stiffness = math.inf if response <= 0.0 else (math.tau / response) ** 2
    stiffness = min(raw_stiffness, idle_velocity_threshold)

    # 0x100593f18 then computes drag from the already-clamped stiffness as
    # 2 * dampingFraction * sqrt(stiffness).
    drag = 2.0 * damping_fraction * math.sqrt(stiffness)

    return ScalarSpringConfiguration(
        response=response,
        damping_fraction=damping_fraction,
        stiffness=stiffness,
        drag=drag,
        dt=dt,
        close_enough_progress_threshold=CONFIRMED_CURSOR_TIMING_CONSTANTS["close_enough_progress_threshold"],
        close_enough_distance_threshold=CONFIRMED_CURSOR_TIMING_CONSTANTS["close_enough_distance_threshold"],
        idle_velocity_threshold=idle_velocity_threshold,
    )


def advance_scalar_velocity_verlet(
    current: float,
    target: float,
    state: ScalarVelocityVerletState,
    config: ScalarSpringConfiguration,
) -> tuple[float, ScalarVelocityVerletState]:
    half_dt = config.dt * 0.5

    # 0x100594948..0x100594b04
    velocity_half = state.velocity + (state.force * half_dt)
    # 0x100594c4c..0x100594e8c
    current = current + (velocity_half * config.dt)
    # 0x100594ecc..0x1005954f4
    force = (config.stiffness * (target - current)) + ((-config.drag) * velocity_half)
    # 0x1005955f0..0x100595858
    velocity = velocity_half + (force * half_dt)

    return current, ScalarVelocityVerletState(
        time=state.time + config.dt,
        velocity=velocity,
        force=force,
    )


def advance_scalar_velocity_verlet_to_time(
    current: float,
    target: float,
    state: ScalarVelocityVerletState,
    config: ScalarSpringConfiguration,
    target_time: float,
) -> tuple[float, ScalarVelocityVerletState]:
    # 0x100593404 limits excessively stale simulation time to targetTime - 1/60.
    if (target_time - state.time) > 1.0:
        state = ScalarVelocityVerletState(
            time=target_time - (1.0 / 60.0),
            velocity=state.velocity,
            force=state.force,
        )

    while state.time < target_time:
        current, state = advance_scalar_velocity_verlet(
            current=current,
            target=target,
            state=state,
            config=config,
        )

    return current, state


def build_timed_cursor_timeline(
    path: CursorMotionPath,
    config: ScalarSpringConfiguration | None = None,
    report_every_steps: int = 4,
    max_duration_seconds: float = 2.0,
) -> dict[str, object]:
    config = config or build_scalar_spring_configuration()
    current = 0.0
    target = 1.0
    state = ScalarVelocityVerletState(time=0.0, velocity=0.0, force=0.0)
    samples: list[TimedCursorSample] = []
    previous_point: Vec2 | None = None
    close_enough_first_time: float | None = None
    close_enough_first_step: int | None = None
    raw_progress_first_ge_target_time: float | None = None
    raw_progress_first_ge_target_step: int | None = None
    first_endpoint_lock_time: float | None = None
    first_endpoint_lock_step: int | None = None
    step_count = int(max_duration_seconds / config.dt)

    start_point, _ = path.sample(current)
    samples.append(
        TimedCursorSample(
            step=0,
            time=0.0,
            progress=current,
            point=start_point,
            spring_velocity=state.velocity,
            spring_force=state.force,
            geometric_speed_units_per_second=0.0,
        )
    )
    previous_point = start_point

    for step in range(1, step_count + 1):
        target_time = step * config.dt
        current, state = advance_scalar_velocity_verlet_to_time(
            current=current,
            target=target,
            state=state,
            config=config,
            target_time=target_time,
        )
        point, _ = path.sample(current)
        geometric_speed = 0.0 if previous_point is None else (point - previous_point).length() / config.dt
        previous_point = point

        if raw_progress_first_ge_target_time is None and current >= target:
            raw_progress_first_ge_target_time = state.time
            raw_progress_first_ge_target_step = step

        if first_endpoint_lock_time is None and current >= target and point == path.end:
            first_endpoint_lock_time = state.time
            first_endpoint_lock_step = step

        if (
            close_enough_first_time is None
            and current >= config.close_enough_progress_threshold
            and abs(target - current) <= config.close_enough_distance_threshold
        ):
            close_enough_first_time = state.time
            close_enough_first_step = step

        should_record = (step % report_every_steps) == 0 or step == step_count
        if should_record:
            samples.append(
                TimedCursorSample(
                    step=step,
                    time=state.time,
                    progress=current,
                    point=point,
                    spring_velocity=state.velocity,
                    spring_force=state.force,
                    geometric_speed_units_per_second=geometric_speed,
                )
            )

    return {
        "spring_configuration": config.to_dict(),
        "simulation_state_at_end": state.to_dict(),
        "binary_confirmed_step_sequence": [
            "velocityHalf = velocity + force * (dt / 2)",
            "current = current + velocityHalf * dt",
            "force = stiffness * (target - current) + (-drag) * velocityHalf",
            "velocity = velocityHalf + force * (dt / 2)",
        ],
        "internal_step_hz": round(1.0 / config.dt),
        "reported_sample_hz": round(1.0 / (config.dt * report_every_steps)),
        "reported_sample_stride_steps": report_every_steps,
        "raw_progress_first_ge_target_time": raw_progress_first_ge_target_time,
        "raw_progress_first_ge_target_step": raw_progress_first_ge_target_step,
        "first_endpoint_lock_time": first_endpoint_lock_time,
        "first_endpoint_lock_step": first_endpoint_lock_step,
        "close_enough_first_time": close_enough_first_time,
        "close_enough_first_step": close_enough_first_step,
        "endpoint_lock_inference_note": "CursorMotionPath.sample(progress) is binary-confirmed to clamp progress into [0, 1], so the visible point becomes the exact path endpoint once raw spring progress first reaches 1.0. The linkage from that visible endpoint lock to SpringAnimation's finished optional-return path is still an inference from multiple confirmed pieces.",
        "samples": [sample.to_dict() for sample in samples],
    }


def _binary_piecewise_primary_extents(distance: float, constants: dict[str, float], guide: Vec2) -> tuple[float, float]:
    if not (guide.x < 0.0 < guide.y):
        raise ValueError("the current binary lift assumes the bundled guide vector has negative x and positive y")

    primary = distance * constants["distance_scale_primary"]
    direct = distance * constants["direct_span_scale"]
    secondary = distance * 0.15
    low_cutoff = 48.0
    high_cutoff = 640.0

    # This is the sign-specialized lift of 0x10005fe84..0x10006013c for the
    # bundled guide vector (-0.6946, +0.7193). The binary's branch tree reduces
    # to four piecewise regions under that fixed sign pattern.
    if primary < low_cutoff:
        return low_cutoff, low_cutoff
    if primary < high_cutoff:
        return primary, direct
    if secondary < high_cutoff:
        return high_cutoff, low_cutoff
    return high_cutoff, high_cutoff


def _binary_piecewise_handle_extent(distance: float, constants: dict[str, float]) -> float:
    raw = distance * constants["distance_scale_secondary"]
    if raw < 50.0:
        return 50.0
    if raw < 640.0:
        return raw
    return 520.0


def _clip_positive_ray(origin: Vec2, direction: Vec2, bounds: Bounds | None) -> float:
    if bounds is None:
        return math.inf

    limit = math.inf
    if direction.x > 0.0:
        limit = min(limit, (bounds.max_x - origin.x) / direction.x)
    elif direction.x < 0.0:
        limit = min(limit, (bounds.min_x - origin.x) / direction.x)

    if direction.y > 0.0:
        limit = min(limit, (bounds.max_y - origin.y) / direction.y)
    elif direction.y < 0.0:
        limit = min(limit, (bounds.min_y - origin.y) / direction.y)

    return max(limit, 0.0)


def _normalized_or_default(vector: Vec2, minimum_length: float, constants: dict[str, float]) -> Vec2:
    length = vector.length()
    if length < minimum_length or length < constants["normalization_epsilon"]:
        return Vec2(1.0, 0.0)
    return vector.scale(1.0 / length)


class BinaryGuidedPathGenerator:
    def __init__(self, constants: dict[str, float], tables: dict[str, list[float]]):
        self.constants = constants
        self.tables = tables
        self.guide_local = Vec2(-0.6946583704589973, 0.7193398003386512)

    def build_candidates(
        self,
        start: Vec2,
        end: Vec2,
        bounds: Bounds | None,
        overrides: BinaryGuidedPathOverrides | None = None,
    ) -> list[CandidatePath]:
        overrides = overrides or BinaryGuidedPathOverrides()
        delta = end - start
        distance = max(delta.length(), self.constants["normalization_epsilon"])
        direction = delta.normalized()
        local_normal = direction.perpendicular()
        guide = direction.scale(self.guide_local.x) + local_normal.scale(self.guide_local.y)
        reverse_guide = guide.scale(-1.0)

        start_extent_pre, end_extent_pre = _binary_piecewise_primary_extents(
            distance=distance,
            constants=self.constants,
            guide=guide,
        )
        start_extent = min(start_extent_pre * overrides.start_extent_scale, _clip_positive_ray(start, guide, bounds))
        end_extent = min(end_extent_pre * overrides.end_extent_scale, _clip_positive_ray(end, reverse_guide, bounds))

        start_extent_scaled = min(
            max(start_extent * self.constants["side_bias_scale"], 0.0),
            _clip_positive_ray(start, guide, bounds),
        )
        end_extent_scaled = min(
            max(end_extent * self.constants["side_bias_scale"], 0.0),
            _clip_positive_ray(end, reverse_guide, bounds),
        )

        full_start_control = start + guide.scale(start_extent)
        full_end_control = end - guide.scale(end_extent)
        scaled_start_control = start + guide.scale(start_extent_scaled)
        scaled_end_control = end - guide.scale(end_extent_scaled)

        raw_handle_extent = _binary_piecewise_handle_extent(distance, self.constants) * overrides.arc_size_scale
        raw_arc_extent = clamp(
            distance * self.constants["distance_scale_tertiary"] * overrides.arc_size_scale,
            self.constants["candidate_arc_min"],
            self.constants["candidate_arc_max"],
        )

        midpoint = Vec2((start.x + end.x) * 0.5, (start.y + end.y) * 0.5)
        signed_normal = local_normal
        cross = (guide.y * direction.x) - (guide.x * direction.y)
        if cross < 0.0:
            signed_normal = signed_normal.scale(-1.0)
        arc_anchor_bias = guide.scale(start_extent * self.constants["side_bias_scale"] * overrides.arc_flow_scale)
        forward_unit = _normalized_or_default(
            direction.scale(distance) + signed_normal.scale(raw_arc_extent),
            minimum_length=raw_handle_extent,
            constants=self.constants,
        )

        candidates: list[CandidatePath] = []
        candidates.append(
            self._make_candidate(
                identifier="base-full-guide",
                kind="base",
                side=0,
                table_a_scale=None,
                table_b_scale=None,
                path=CursorMotionPath(
                    start=start,
                    end=end,
                    start_control=full_start_control,
                    end_control=full_end_control,
                    segments=(CubicSegment(end=end, control1=full_start_control, control2=full_end_control),),
                ),
                bounds=bounds,
                distance=distance,
            )
        )
        candidates.append(
            self._make_candidate(
                identifier="base-scaled-guide",
                kind="base",
                side=0,
                table_a_scale=None,
                table_b_scale=None,
                path=CursorMotionPath(
                    start=start,
                    end=end,
                    start_control=scaled_start_control,
                    end_control=scaled_end_control,
                    segments=(CubicSegment(end=end, control1=scaled_start_control, control2=scaled_end_control),),
                ),
                bounds=bounds,
                distance=distance,
            )
        )

        for outer_scale in self.tables["table_a"]:
            anchor_offset = signed_normal.scale(raw_handle_extent * outer_scale)
            for inner_scale in self.tables["table_b"]:
                tangent_span = forward_unit.scale(raw_arc_extent * inner_scale)

                for side, anchor in (
                    (1, midpoint + arc_anchor_bias + anchor_offset),
                    (-1, midpoint + arc_anchor_bias - anchor_offset),
                ):
                    arc_in = anchor - tangent_span
                    arc_out = anchor + tangent_span
                    path = CursorMotionPath(
                        start=start,
                        end=end,
                        start_control=full_start_control,
                        arc=anchor,
                        arc_in=arc_in,
                        arc_out=arc_out,
                        end_control=full_end_control,
                        segments=(
                            CubicSegment(end=anchor, control1=full_start_control, control2=arc_in),
                            CubicSegment(end=end, control1=arc_out, control2=full_end_control),
                        ),
                    )
                    candidates.append(
                        self._make_candidate(
                            identifier=f"a{outer_scale:.2f}-b{inner_scale:.2f}-{'positive' if side > 0 else 'negative'}",
                            kind="arched",
                            side=side,
                            table_a_scale=outer_scale,
                            table_b_scale=inner_scale,
                            path=path,
                            bounds=bounds,
                            distance=distance,
                        )
                    )

        return candidates

    def choose_candidate(self, candidates: list[CandidatePath]) -> tuple[CandidatePath | None, str]:
        if not candidates:
            return None, "empty"

        in_bounds_candidates = [candidate for candidate in candidates if candidate.measurement.stays_in_bounds]
        pool = in_bounds_candidates if in_bounds_candidates else candidates
        policy = "prefer_in_bounds_then_lowest_score" if in_bounds_candidates else "lowest_score"
        return min(pool, key=lambda item: item.score), policy

    def _score_candidate(
        self,
        distance: float,
        measurement: CursorMotionMeasurement,
    ) -> CandidateScoreComponents:
        excess_length_ratio = max((measurement.length / max(distance, 1.0)) - 1.0, 0.0)
        excess_length_cost = excess_length_ratio * self.constants["score_excess_length_weight"]
        angle_energy_cost = measurement.angle_change_energy * self.constants["score_angle_energy_weight"]
        max_angle_cost = measurement.max_angle_change * self.constants["score_max_angle_weight"]
        total_turn_cost = measurement.total_turn * self.constants["score_total_turn_weight"]
        out_of_bounds_cost = 0.0 if measurement.stays_in_bounds else self.constants["score_out_of_bounds_penalty"]
        total_score = (
            excess_length_cost
            + angle_energy_cost
            + max_angle_cost
            + total_turn_cost
            + out_of_bounds_cost
        )
        return CandidateScoreComponents(
            excess_length_ratio=excess_length_ratio,
            excess_length_cost=excess_length_cost,
            angle_energy_cost=angle_energy_cost,
            max_angle_cost=max_angle_cost,
            total_turn_cost=total_turn_cost,
            out_of_bounds_cost=out_of_bounds_cost,
            total_score=total_score,
        )

    def _make_candidate(
        self,
        identifier: str,
        kind: str,
        side: int,
        table_a_scale: float | None,
        table_b_scale: float | None,
        path: CursorMotionPath,
        bounds: Bounds | None,
        distance: float,
    ) -> CandidatePath:
        measurement = path.measure(
            bounds=bounds,
            min_step_distance=self.constants["minimum_step_distance"],
        )
        score_components = self._score_candidate(distance=distance, measurement=measurement)
        return CandidatePath(
            identifier=identifier,
            kind=kind,
            side=side,
            table_a_scale=table_a_scale,
            table_b_scale=table_b_scale,
            score=score_components.total_score,
            score_components=score_components,
            measurement=measurement,
            path=path,
        )


def _derive_bundle_root(binary_path: Path) -> Path:
    if binary_path.parent.name == "MacOS" and binary_path.parent.parent.name == "Contents":
        return binary_path.parent.parent.parent
    return binary_path.parent


def scan_bundle_for_slider_labels(binary_path: Path) -> dict[str, object]:
    bundle_root = _derive_bundle_root(binary_path)
    exact_slider_phrases = [
        "START HANDLE",
        "END HANDLE",
        "ARC SIZE",
        "ARC FLOW",
    ]
    ambiguous_single_tokens = [
        "SPRING",
        "DEBUG",
        "MAIL",
        "CLICK",
    ]
    exact_findings = {label: False for label in exact_slider_phrases}
    ambiguous_findings = {label: False for label in ambiguous_single_tokens}
    files_scanned = 0

    for file_path in bundle_root.rglob("*"):
        if not file_path.is_file():
            continue
        files_scanned += 1
        try:
            payload = file_path.read_bytes().lower()
        except OSError:
            continue

        for label in exact_slider_phrases:
            if exact_findings[label]:
                continue
            if label.lower().encode("utf-8") in payload:
                exact_findings[label] = True

        for label in ambiguous_single_tokens:
            if ambiguous_findings[label]:
                continue
            if label.lower().encode("utf-8") in payload:
                ambiguous_findings[label] = True

    return {
        "bundle_root": str(bundle_root),
        "files_scanned": files_scanned,
        "exact_slider_phrases": exact_findings,
        "ambiguous_single_tokens": ambiguous_findings,
        "notes": {
            "exact_slider_phrase_scan": "used to check whether the shipping bundle still carries the specific slider UI labels from the video.",
            "ambiguous_single_token_scan": "single words like SPRING / DEBUG / MAIL / CLICK can appear for unrelated reasons in a release bundle, so these hits are not enough to claim the debug UI still ships.",
        },
    }


def summarize_path_shape(path: CursorMotionPath, sample_count: int = 128) -> dict[str, float | list[float]]:
    chord = path.end - path.start
    chord_length = chord.length()
    chord_direction = chord.normalized() if chord_length > 1e-9 else Vec2(1.0, 0.0)
    normal = chord_direction.perpendicular()

    max_signed_offset = 0.0
    apex_progress = 0.0
    for sample in path.sample_points(sample_count):
        offset_vector = sample.point - path.start
        signed_offset = (offset_vector.x * normal.x) + (offset_vector.y * normal.y)
        if abs(signed_offset) > abs(max_signed_offset):
            max_signed_offset = signed_offset
            apex_progress = sample.progress

    start_tangent = path.sample(0.04)[1]
    end_tangent = path.sample(0.96)[1]
    return {
        "chord_length": chord_length,
        "max_signed_offset_from_chord": max_signed_offset,
        "max_offset_from_chord": abs(max_signed_offset),
        "apex_progress": apex_progress,
        "start_heading_error_degrees": math.degrees(signed_angle(chord_direction, start_tangent)),
        "end_heading_error_degrees": math.degrees(signed_angle(chord_direction, end_tangent)),
    }


def summarize_candidate_geometry(candidate: CandidatePath, sample_count: int = 128) -> dict[str, object]:
    return {
        "identifier": candidate.identifier,
        "kind": candidate.kind,
        "side": candidate.side,
        "measurement": candidate.measurement.to_dict(),
        "shape_metrics": summarize_path_shape(candidate.path, sample_count=sample_count),
        "control_points": {
            "start_control": candidate.path.start_control.to_list() if candidate.path.start_control else None,
            "arc": candidate.path.arc.to_list() if candidate.path.arc else None,
            "arc_in": candidate.path.arc_in.to_list() if candidate.path.arc_in else None,
            "arc_out": candidate.path.arc_out.to_list() if candidate.path.arc_out else None,
            "end_control": candidate.path.end_control.to_list() if candidate.path.end_control else None,
        },
    }


def _find_best_arched_candidate(candidates: list[CandidatePath]) -> CandidatePath | None:
    arched = [candidate for candidate in candidates if candidate.kind == "arched"]
    if not arched:
        return None
    in_bounds = [candidate for candidate in arched if candidate.measurement.stays_in_bounds]
    pool = in_bounds if in_bounds else arched
    return min(pool, key=lambda item: item.score)


def _build_geometry_slider_variants(
    generator: BinaryGuidedPathGenerator,
    start: Vec2,
    end: Vec2,
    bounds: Bounds | None,
    sample_count: int,
    variant_overrides: list[tuple[str, BinaryGuidedPathOverrides]],
) -> list[dict[str, object]]:
    payload: list[dict[str, object]] = []
    for name, overrides in variant_overrides:
        candidates = generator.build_candidates(start=start, end=end, bounds=bounds, overrides=overrides)
        chosen_candidate, selection_policy = generator.choose_candidate(candidates)
        best_arched = _find_best_arched_candidate(candidates)
        payload.append(
            {
                "variant": name,
                "selection_policy": selection_policy,
                "chosen_candidate": summarize_candidate_geometry(chosen_candidate, sample_count=sample_count)
                if chosen_candidate
                else None,
                "best_arched_candidate": summarize_candidate_geometry(best_arched, sample_count=sample_count)
                if best_arched
                else None,
            }
        )
    return payload


def build_slider_study_output(
    binary: MachOBinary,
    start: Vec2,
    end: Vec2,
    bounds: Bounds | None,
    sample_count: int,
) -> dict[str, object]:
    constants = build_model_constants(binary)
    tables = extract_candidate_tables(binary)
    generator = BinaryGuidedPathGenerator(constants=constants, tables=tables)
    baseline_candidates = generator.build_candidates(start=start, end=end, bounds=bounds)
    baseline_choice, selection_policy = generator.choose_candidate(baseline_candidates)
    baseline_best_arched = _find_best_arched_candidate(baseline_candidates)

    if baseline_choice is None:
        raise ValueError("no baseline candidate produced for slider study")

    baseline_timeline = build_timed_cursor_timeline(path=baseline_choice.path)
    spring_response_baseline = CONFIRMED_CURSOR_TIMING_CONSTANTS["cursor_path_spring_response"]
    spring_damping_baseline = CONFIRMED_CURSOR_TIMING_CONSTANTS["cursor_path_spring_damping_fraction"]
    spring_variants = [
        (
            "response_minus_15pct",
            build_scalar_spring_configuration_for(
                response=spring_response_baseline * 0.85,
                damping_fraction=spring_damping_baseline,
            ),
        ),
        (
            "response_plus_15pct",
            build_scalar_spring_configuration_for(
                response=spring_response_baseline * 1.15,
                damping_fraction=spring_damping_baseline,
            ),
        ),
    ]
    spring_variant_payload = []
    for name, config in spring_variants:
        timeline = build_timed_cursor_timeline(path=baseline_choice.path, config=config)
        spring_variant_payload.append(
            {
                "variant": name,
                "spring_configuration": config.to_dict(),
                "timed_cursor_timeline": {
                    "first_endpoint_lock_time": timeline["first_endpoint_lock_time"],
                    "close_enough_first_time": timeline["close_enough_first_time"],
                    "raw_progress_first_ge_target_time": timeline["raw_progress_first_ge_target_time"],
                },
            }
        )

    return {
        "binary_path": str(binary.path),
        "input": {
            "start": start.to_list(),
            "end": end.to_list(),
            "bounds": asdict(bounds) if bounds else None,
            "sample_count": sample_count,
        },
        "shipping_bundle_label_evidence": scan_bundle_for_slider_labels(binary.path),
        "binary_confirmed_motion_terms": {
            "path_fields": ["startControl", "arc", "arcIn", "arcOut", "endControl"],
            "timing_fields": ["Animation.SpringParameters.response", "Animation.SpringParameters.dampingFraction"],
            "candidate_tables": extract_candidate_tables(binary),
            "fixed_geometry_constants": {
                "guide_vector": [-0.6946583704589973, 0.7193398003386512],
                "start_extent_piecewise": "48 / d*0.41960295031576633 / 640 depending on region",
                "end_extent_piecewise": "48 / d*0.9 / 640 depending on region",
                "handle_extent_piecewise": "50 / d*0.2765523188064277 / 520",
                "arc_extent_piecewise": "clamp(d*0.5783555327868779, 38, 440)",
                "arc_anchor_bias": "guide * (startExtent * 0.65)",
            },
            "spring_defaults": {
                "response": spring_response_baseline,
                "damping_fraction": spring_damping_baseline,
                "dt": CONFIRMED_CURSOR_TIMING_CONSTANTS["velocity_verlet_dt"],
            },
        },
        "baseline": {
            "selection_policy": selection_policy,
            "chosen_candidate": summarize_candidate_geometry(baseline_choice, sample_count=sample_count),
            "best_arched_candidate": summarize_candidate_geometry(baseline_best_arched, sample_count=sample_count)
            if baseline_best_arched
            else None,
            "timed_cursor_timeline": {
                "spring_configuration": baseline_timeline["spring_configuration"],
                "first_endpoint_lock_time": baseline_timeline["first_endpoint_lock_time"],
                "close_enough_first_time": baseline_timeline["close_enough_first_time"],
            },
        },
        "slider_mapping_analysis": {
            "start_handle": {
                "release_bundle_label_found": False,
                "mapping_confidence": "inferred_from_binary_fields",
                "affects_current_baseline_choice_directly": True,
                "binary_terms_touched": ["CursorMotionPath.startControl", "guide startExtent piecewise"],
                "effect_summary": "changes how far the launch-side control point projects along the guide direction, so it mainly changes the first third of the curve and the initial heading commitment.",
                "variants": _build_geometry_slider_variants(
                    generator=generator,
                    start=start,
                    end=end,
                    bounds=bounds,
                    sample_count=sample_count,
                    variant_overrides=[
                        ("start_extent_minus_25pct", BinaryGuidedPathOverrides(start_extent_scale=0.75)),
                        ("start_extent_plus_25pct", BinaryGuidedPathOverrides(start_extent_scale=1.25)),
                    ],
                ),
            },
            "end_handle": {
                "release_bundle_label_found": False,
                "mapping_confidence": "inferred_from_binary_fields",
                "affects_current_baseline_choice_directly": True,
                "binary_terms_touched": ["CursorMotionPath.endControl", "guide endExtent piecewise"],
                "effect_summary": "changes how far the arrival-side control point projects before the endpoint, so it mainly changes the terminal braking / hook-in segment and the final tangent alignment.",
                "variants": _build_geometry_slider_variants(
                    generator=generator,
                    start=start,
                    end=end,
                    bounds=bounds,
                    sample_count=sample_count,
                    variant_overrides=[
                        ("end_extent_minus_25pct", BinaryGuidedPathOverrides(end_extent_scale=0.75)),
                        ("end_extent_plus_25pct", BinaryGuidedPathOverrides(end_extent_scale=1.25)),
                    ],
                ),
            },
            "arc_size": {
                "release_bundle_label_found": False,
                "mapping_confidence": "inferred_from_binary_fields",
                "affects_current_baseline_choice_directly": baseline_choice.kind == "arched",
                "binary_terms_touched": ["handleExtent piecewise", "arcExtent piecewise", "table_a", "table_b"],
                "effect_summary": "changes how far the arched family pushes the apex off the chord and how wide the arc tangents open, so it mainly changes peak bowing, total turn, and path length.",
                "variants": _build_geometry_slider_variants(
                    generator=generator,
                    start=start,
                    end=end,
                    bounds=bounds,
                    sample_count=sample_count,
                    variant_overrides=[
                        ("arc_size_minus_30pct", BinaryGuidedPathOverrides(arc_size_scale=0.7)),
                        ("arc_size_plus_30pct", BinaryGuidedPathOverrides(arc_size_scale=1.3)),
                    ],
                ),
            },
            "arc_flow": {
                "release_bundle_label_found": False,
                "mapping_confidence": "inferred_from_binary_fields",
                "affects_current_baseline_choice_directly": baseline_choice.kind == "arched",
                "binary_terms_touched": ["arc_anchor_bias = guide * (startExtent * 0.65)"],
                "effect_summary": "the current lift has no dedicated flow field, but the fixed arc-anchor bias shifts the apex forward along the guide direction; perturbing it mainly moves where the curve reaches its widest bow, making the turn feel earlier or later.",
                "variants": _build_geometry_slider_variants(
                    generator=generator,
                    start=start,
                    end=end,
                    bounds=bounds,
                    sample_count=sample_count,
                    variant_overrides=[
                        ("arc_flow_minus_25pct", BinaryGuidedPathOverrides(arc_flow_scale=0.75)),
                        ("arc_flow_plus_25pct", BinaryGuidedPathOverrides(arc_flow_scale=1.25)),
                    ],
                ),
            },
            "spring": {
                "release_bundle_label_found": False,
                "mapping_confidence": "direct_binary_timing_fields_confirmed_but_one_dimensional_ui_mapping_unrecovered",
                "affects_current_baseline_choice_directly": True,
                "binary_terms_touched": ["Animation.SpringParameters.response", "Animation.SpringParameters.dampingFraction"],
                "effect_summary": "shipping cursor motion definitely uses SpringParameters(response=1.4, dampingFraction=0.9); varying response changes endpoint-lock timing and how quickly progress approaches 1.0, but the exact single-slider mapping used by the internal debug UI is still unrecovered.",
                "normalization_helper_note": CONFIRMED_TIMING_PIPELINE["spring_parameter_normalization_helper"],
                "variants": spring_variant_payload,
            },
        },
    }


def build_inspect_output(binary: MachOBinary) -> dict[str, object]:
    guide_vector = [-0.6946583704589973, 0.7193398003386512]
    return {
        "binary_path": str(binary.path),
        "motion_types": [asdict(item) for item in extract_motion_type_fields(binary)],
        "data_section_constants": extract_named_constants(binary),
        "confirmed_model_constants": CONFIRMED_DISASSEMBLY_CONSTANTS,
        "confirmed_timing_constants": CONFIRMED_CURSOR_TIMING_CONSTANTS,
        "candidate_tables": extract_candidate_tables(binary),
        "confirmed_from_binary": {
            "path_sample_function": "segment selection + cubic bezier evaluation",
            "measurement_function": "24 samples per segment + angle unwrap + in-bounds flag",
            "candidate_tables_shape": "3 x 3 coefficient tables with mirrored path variants",
            "candidate_count_shape": "2 base candidates + 3 x 3 x 2 mirrored candidates = 20",
            "guide_vector": guide_vector,
            "path_struct_layout": {
                "start": "offset 0x00",
                "end": "offset 0x10",
                "startControl": "offset 0x20",
                "arc": "offset 0x30",
                "arcIn": "offset 0x48",
                "arcOut": "offset 0x60",
                "endControl": "offset 0x78",
                "segments": "offset 0x88",
            },
            "segment_struct_layout": {
                "end": "offset 0x00",
                "control1": "offset 0x10",
                "control2": "offset 0x20",
            },
            "guide_extent_piecewise": {
                "start_extent": "48 if d*0.41960295031576633 < 48; d*0.41960295031576633 if d*0.41960295031576633 < 640; 640 if d*0.15 < 640; else 640",
                "end_extent": "48 if d*0.41960295031576633 < 48; d*0.9 if d*0.41960295031576633 < 640; 48 if d*0.15 < 640; else 640",
            },
            "handle_extent_piecewise": "50 if d*0.2765523188064277 < 50; d*0.2765523188064277 if d*0.2765523188064277 < 640; else 520",
            "arc_extent_piecewise": "clamp(d*0.5783555327868779, 38, 440)",
            "candidate_score_formula": "320 * max(length / max(directDistance, 1) - 1, 0) + 140 * angleEnergy + 180 * maxAngle + 18 * totalTurn + 45 * outOfBounds",
            "candidate_selection_policy": "prefer in-bounds candidates, otherwise fall back to all candidates, then choose the minimum score",
            "velocity_verlet_stiffness_formula": "stiffness = min(response > 0 ? (2ฯ€ / response)^2 : +inf, 28800)",
            "velocity_verlet_drag_formula": "drag = 2 * dampingFraction * sqrt(stiffness)",
            "velocity_verlet_step_sequence": [
                "velocityHalf = velocity + force * (dt / 2)",
                "current = current + velocityHalf * dt",
                "force = stiffness * (target - current) + (-drag) * velocityHalf",
                "velocity = velocityHalf + force * (dt / 2)",
            ],
            "spring_animation_frame_update": {
                "function": "0x1005761bc",
                "behavior": "advance simulation, evaluate finished predicate, return optional nil on finish else some(updatedValue)",
                "value_copy_helper": "0x1005730bc reads hidden self offset 0x68",
                "target_copy_helper": "0x100573390 reads hidden self offset 0x70",
            },
            "spring_animation_finish_predicate": {
                "function": "0x1005934b0",
                "threshold_square_gate": "requires max(hiddenStateSlotA, hiddenStateSlotB) <= threshold^2 before continuing",
                "exact_zero_gate": "after a 0.01 float-literal broadcast and SIMD scalar loops, accepts only when a difference-derived scalar A is neither A > 0 nor 0 > A",
                "field_name_inference_notes": {
                    "hidden_self_0x68_0x70": "very likely InterpolatableAnimation._value / _targetValue",
                    "metadata_plus_0x30_threshold": "very likely idleVelocityThreshold",
                },
            },
        },
        "timing_from_binary": {
            "type_relationships": CONFIRMED_TIMING_TYPE_RELATIONSHIPS,
            "cursor_path_constants": CONFIRMED_CURSOR_TIMING_CONSTANTS,
            "pipeline": CONFIRMED_TIMING_PIPELINE,
        },
    }


def build_demo_output(
    binary: MachOBinary,
    start: Vec2,
    end: Vec2,
    bounds: Bounds | None,
    sample_count: int,
    include_all_candidates: bool,
) -> dict[str, object]:
    constants = build_model_constants(binary)
    tables = extract_candidate_tables(binary)
    generator = BinaryGuidedPathGenerator(constants=constants, tables=tables)
    candidates = generator.build_candidates(start=start, end=end, bounds=bounds)
    chosen_candidate, selection_policy = generator.choose_candidate(candidates)
    ordered_candidates = sorted(candidates, key=lambda item: (not item.measurement.stays_in_bounds, item.score))
    timed_timeline = build_timed_cursor_timeline(chosen_candidate.path) if chosen_candidate else None
    return {
        "binary_path": str(binary.path),
        "input": {
            "start": start.to_list(),
            "end": end.to_list(),
            "bounds": asdict(bounds) if bounds else None,
            "sample_count": sample_count,
        },
        "confirmed_model_constants": CONFIRMED_DISASSEMBLY_CONSTANTS,
        "confirmed_timing_constants": CONFIRMED_CURSOR_TIMING_CONSTANTS,
        "confirmed_from_binary": {
            "sample_progress_logic": True,
            "measurement_logic": True,
            "candidate_coeff_tables": True,
            "candidate_geometry_lifted_from_disassembly": True,
            "candidate_score_formula": True,
            "candidate_selection_policy": True,
            "spring_animation_chain": True,
            "velocity_verlet_configuration_fields": True,
            "window_animation_state_slots": True,
            "velocity_verlet_step_sequence": True,
            "stiffness_formula": True,
            "drag_formula": True,
            "spring_animation_finished_predicate_control_flow": True,
        },
        "reconstructed_or_inferred": {
            "automatic_bounds_discovery_from_runtime": True,
            "wall_clock_duration_model": True,
            "spring_animation_value_target_field_names": True,
            "endpoint_lock_to_finished_predicate_linkage": True,
        },
        "timing_notes": {
            "duration_recovered_from_binary": False,
            "sample_speed_is_geometric": True,
            "sample_speed_definition": "distance between adjacent time-stepped path points divided by dt",
            "spring_response_and_damping_recovered": True,
            "velocity_verlet_dt_recovered": True,
            "velocity_verlet_idle_velocity_threshold_recovered": True,
            "spring_animation_finish_predicate_control_flow_recovered": True,
        },
        "timing_binary_evidence": {
            "type_relationships": CONFIRMED_TIMING_TYPE_RELATIONSHIPS,
            "pipeline": CONFIRMED_TIMING_PIPELINE,
        },
        "candidate_shape_notes": {
            "confirmed_binary_candidate_count": 20,
            "demo_candidate_count": len(candidates),
            "bounds_note": "the bundled app derives bounds from runtime screen regions before calling the path builder; this script expects bounds as direct input",
        },
        "selection_policy": selection_policy,
        "timed_cursor_demo": timed_timeline,
        "candidate_summaries": [candidate.summary_dict() for candidate in ordered_candidates],
        "chosen_candidate": chosen_candidate.to_dict(sample_count=sample_count) if chosen_candidate else None,
        "all_candidates": [candidate.to_dict(sample_count=sample_count) for candidate in ordered_candidates]
        if include_all_candidates
        else None,
    }


def parse_vec2(values: Iterable[str]) -> Vec2:
    x_raw, y_raw = values
    return Vec2(float(x_raw), float(y_raw))


def parse_bounds(values: Iterable[str]) -> Bounds:
    min_x, min_y, max_x, max_y = (float(item) for item in values)
    return Bounds(min_x=min_x, min_y=min_y, max_x=max_x, max_y=max_y)


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description="Reverse-engineering helpers for official cursor motion.")
    parser.add_argument("--app", type=Path, default=DEFAULT_APP_PATH, help="Path to SkyComputerUseService binary.")
    parser.add_argument("--pretty", dest="pretty_global", action="store_true", help="Pretty-print JSON output.")

    subparsers = parser.add_subparsers(dest="command", required=True)

    inspect = subparsers.add_parser("inspect", help="Dump recovered motion types, constants, and coefficient tables.")
    inspect.add_argument("--pretty", dest="pretty_local", action="store_true", help="Pretty-print JSON output.")

    demo = subparsers.add_parser("demo", help="Generate binary-guided candidate cursor paths.")
    demo.add_argument("--pretty", dest="pretty_local", action="store_true", help="Pretty-print JSON output.")
    demo.add_argument("--start", nargs=2, metavar=("X", "Y"), required=True, help="Start position.")
    demo.add_argument("--end", nargs=2, metavar=("X", "Y"), required=True, help="End position.")
    demo.add_argument(
        "--bounds",
        nargs=4,
        metavar=("MIN_X", "MIN_Y", "MAX_X", "MAX_Y"),
        help="Optional bounds used for stays_in_bounds measurement.",
    )
    demo.add_argument("--samples", type=int, default=32, help="Number of sample points per candidate.")
    demo.add_argument(
        "--include-all-candidates",
        action="store_true",
        help="Include full path and sample output for every candidate instead of only the chosen candidate.",
    )

    slider_study = subparsers.add_parser(
        "slider-study",
        help="Study how slider-like parameter hypotheses map onto binary-confirmed geometry and spring terms.",
    )
    slider_study.add_argument("--pretty", dest="pretty_local", action="store_true", help="Pretty-print JSON output.")
    slider_study.add_argument("--start", nargs=2, metavar=("X", "Y"), required=True, help="Start position.")
    slider_study.add_argument("--end", nargs=2, metavar=("X", "Y"), required=True, help="End position.")
    slider_study.add_argument(
        "--bounds",
        nargs=4,
        metavar=("MIN_X", "MIN_Y", "MAX_X", "MAX_Y"),
        help="Optional bounds used for stays_in_bounds measurement.",
    )
    slider_study.add_argument("--samples", type=int, default=96, help="Number of sample points used for geometry summaries.")

    return parser


def main(argv: list[str] | None = None) -> int:
    parser = build_parser()
    args = parser.parse_args(argv)

    binary = MachOBinary(args.app)
    if args.command == "inspect":
        payload = build_inspect_output(binary)
    elif args.command == "demo":
        start = parse_vec2(args.start)
        end = parse_vec2(args.end)
        bounds = parse_bounds(args.bounds) if args.bounds else None
        payload = build_demo_output(
            binary,
            start=start,
            end=end,
            bounds=bounds,
            sample_count=args.samples,
            include_all_candidates=args.include_all_candidates,
        )
    elif args.command == "slider-study":
        start = parse_vec2(args.start)
        end = parse_vec2(args.end)
        bounds = parse_bounds(args.bounds) if args.bounds else None
        payload = build_slider_study_output(
            binary,
            start=start,
            end=end,
            bounds=bounds,
            sample_count=args.samples,
        )
    else:
        raise AssertionError(f"unsupported command: {args.command}")

    pretty = args.pretty_global or getattr(args, "pretty_local", False)
    import sys

    json.dump(payload, fp=sys.stdout, ensure_ascii=True, indent=2 if pretty else None)
    sys.stdout.write("\n")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())