Lessons from rebuilding a haptics editor

The useful surprises were specific

Rebuilding Haptrix exposed problems that were easy to describe confidently and harder to verify: whether a Mac trackpad could play a custom pattern, how an AHAP resolved audio paths, and whether a valid-looking file retained its duration when Core Haptics read it.

These are lessons from the project’s documented implementation and checks. They are useful beyond an editor because any app loading haptic files has to cross the same boundaries between documentation, data and physical hardware.

A framework’s availability is not a hardware promise

Core Haptics exists on macOS, but that does not mean a Force Touch trackpad accepts arbitrary AHAP patterns. The trackpad has a small fixed feedback vocabulary. A supported game controller supplies a different output path through its own haptic engine. Trackpad feedback, controller haptics

Haptrix therefore distinguishes the document from the device that can reproduce it. A Mac can edit and visualise the pattern, while an iPhone can supply the tactile preview. The practical lesson is to verify the endpoint, not just whether an API imports successfully.

Write a capability table before designing the preview interface. Give unsupported output an honest explanation and a useful fallback. A successful “play” button press should not imply a sensation the device cannot produce.

Test the file the reader actually receives

Apple’s AHAP reference lists Duration, while its event-duration key and sample files use EventDuration. In the Learn examples check on macOS 27.0.1, replacing EventDuration with Duration caused the event’s duration to disappear on a Core Haptics parse-and-export round trip. AHAP reference, event duration key

That test is more useful than checking whether the JSON parses. It asks whether the receiving framework keeps the properties the author intended. The test also includes the deliberately wrong spelling as a negative control, so a later change in Apple’s behaviour is visible.

The lesson applies to tutorials too. Compile the code fences taken from the article, and parse the exact downloadable files. A separately maintained “equivalent” sample can pass while the reader’s copy is broken.

Repeated claims still need a source

Early rebuild documents repeated the claim that audio paths resolved relative to the pattern file. The project’s review found no supporting Apple documentation. The documented AHAP behaviour uses a path relative to the app bundle’s root; audio outside that bundle can be registered and referenced through a programmatically created event. AHAP audio paths, registering audio

The correction changed how the project described and handled bundles. It also produced a useful review rule: ask for the source when a statement first shapes a design. Four documents repeating the same assumption are still one assumption.

Share the rules that must agree

The native editor, browser preview and server all need to agree about the same pattern. If each independently implements timing and validation, a change can make one surface accept a file while another interprets it differently.

The rebuild puts those shared rules in a Rust core, exposed to the native app and the website, with common fixture vectors. That is an architectural choice for this project, not a requirement to write every haptics app in Rust. The useful principle is to identify which rules must agree and test them at their actual boundaries.

A preview still needs its assumptions stated. A picture of intensity is an explanation of authored data, not a measurement of force in a person’s hand. Avoid letting a convincing graph stand in for hardware testing.

Treat playback failure as a state

An engine may stop because of an interruption or reset. Audio resources and players may need rebuilding. If the application discards those errors, silence becomes indistinguishable from a valid quiet pattern. Engine lifecycle

Keep enough context to report which output was attempted and what failed. Recover when appropriate, but do not turn recovery into an excuse to replay an old action. An editor’s transport and an app’s one-shot confirmation have different expectations.

Shorten the path to a real device

The Simulator can check layout and navigation; it cannot tell you whether a cue feels right. Haptrix’s workflow keeps editing and iPhone preview close together so a change can be evaluated while its intention is still fresh. File-playback hardware requirements

For a new project, start with one small pattern, one supported output and a visible fallback. Confirm the complete path before building a large library. Designing haptics without writing code shows that loop, while AHAP files explained gives you small files to inspect and test.