[EvgeniiaVak]

Adds createWorkoutBuilder, which returns a WorkoutBuilder hybrid object wrapping HKWorkoutBuilder one-to-one, as discussed in #269. It saves workouts with events (pause/resume, laps, segments) and, on iOS 16+, workout activities. saveWorkoutSample and the other existing APIs are unchanged.

Closes #269
Closes #110

API

createWorkoutBuilder(configuration) on WorkoutsModule. The builder has one method per HKWorkoutBuilder call: beginCollection, add, addMetadata, addWorkoutEvents, addWorkoutActivity (resolves with the activity UUID), updateActivityEndDate, updateActivityMetadata, endCollection, finishWorkout (resolves with a WorkoutProxy, or undefined when HealthKit returns none), discardWorkout and elapsedTime. The builder's state is exposed as readonly properties.

Notes

• HKWorkoutEvent raises an Objective-C exception for invalid input (e.g. a pause with a duration). Core gains createWorkoutEventSafe, which creates the event in Objective-C, so the promise rejects instead of the app crashing.
• Builder calls run one at a time in JS call order. Calls that aren't awaited can't reach HealthKit out of order.
• Calls after finishWorkout or discardWorkout reject instead of hanging. HealthKit never calls their completion.

Testing

• New contract scenarios: pause round-trip, activities round-trip, error cases, call order. All contract scenarios pass on an iOS 26.2 simulator.
• Also tested in a production app through tarball builds: iOS 26.2 simulator and a real iPhone on iOS 18.7 (pauses, routes, activities, totals).
• On the iOS 26.2 simulator, about 1 in 5 builder workouts drops the sample whose start date equals the workout start, when that start has milliseconds, so totals come back missing or partial. This didn't reproduce on the real device in 30 workouts. The pause scenario logs the totals instead of asserting them for this reason.

[changeset-bot]

🦋 Changeset detected

Latest commit: 6ca3efe

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@kingstinct/react-native-healthkit	Minor
@react-native-healthkit/core	Minor
@react-native-healthkit/health-records	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR