I've had my fair share of App Store rejections in the past:

• ⌘ rcmd was rejected for usage of private APIs
• GammaDimmer was rejected for having a link to 🌕 Lunar (my app for controlling monitors that would never get accepted on the App Store)

But I wasn't prepared to be rejected because my app is "not good enough" for the App Store.

4.2.2 - Design - Minimum Functionality

I tried to launch a simple, no-frills iOS app for party-goers and music festivals in 🇷🇴 Romania.

The backend would be a simple Google Sheet which my brother would update daily with curated underground parties and the usual festivals.

My brother is not a programmer, so entering data had to be as low tech as possible.

So ok, I did a basic SwiftUI implementation where I fetch the .csv of the sheet, massage that data into a grid of events, and add the following useful iOS features:

• Add to Calendar button (which uses EventKit to fill in the URL, Location, End Date fields automatically, and adds the necessary reminder alerts)
• Get directions button (which gives you a Google Maps link to the exact coordinates of the event. Super useful as some events are in forests or places where the address is not enough)
• Buy tickets button (which should always point you to the correct website to get tickets from)

All of the above are only possible because my brother spends hours of his time every day to look for event location, coordinates, ticket website, FB/IG/Official website links. Info which is not readily available on a single internet webpage.

Then I created a simple website at subsol.one and sent the app to App Store review.

After a full day of waiting, I got the most stupid rejection I ever read:

Guideline 4.2.2 - Design - Minimum Functionality

We noticed that your app only includes links, images, or content aggregated from the Internet with limited or no native iOS functionality. Although this content may be curated from the web specifically for your users, since it does not sufficiently differ from a mobile web browsing experience, it is not appropriate for the App Store.

Next Steps

We encourage you to review your app concept and work towards creating an app that offers customers an engaging and lasting experience that also meets the App Store’s high expectations for quality and functionality.

So the app does not sufficiently differ from a mobile web browsing experience. Ok. Fair enough.

Second try

I thought the app is useful enough as it is for now.

Considering that the iOS App Store still can't get rid of so many scam apps which are even used for extortion and blackmail, I really didn't understand how this was an acceptable reason for a rejection.

The app is simple, fast, does what it says without any BS unneeded complexity. I thought subsequent features would be added based on what the users would ask for.

But sure, let's add some premature iOS native features for Apple:

• Push Notifications: so you can know instantly when new parties are found
• User Location: used for sorting by how close the events are to you, and for notifying only on events near you
• Share button: for sharing Universal Links to events with other people

Still, after even more agonising days of waiting, the same rejection came along.

Third try

I added more iOS features, because why not:

• Events on the map: to visually assess where each event is happening in the country
  • This was surprisingly easy to do in SwiftUI, I was amazed myself
• Homescreen widgets: utterly useless, but can't get more iOS-y and less webapp-y than this, right?

Another day of Waiting for review and, as before, another rejection with the same generic message. This time I had to ask, what the heck did they want from me?

I sent the following message to the App Store reviewers:

What exactly do you need for this app to be accepted? I have people asking for it, it's already done and these rejections are keeping them from using the app.

It already uses the following native iOS functionalities:

• Push Notifications on new events (this is not possible on the web in iOS)
• Getting user location using CoreLocation and sorting events by how close they are
• Uses the above two functions for notifying only on new parties within 30km of the user location (again, not possible to do such a thing in a web app)
• Shows the events on the native iOS MapKit UI
• Uses a custom URL scheme (subsol:) and Universal Links for easy sharing of parties
• Has homescreen widgets for viewing the latest events
• Allows the user to add the event to calendar with most fields already filled in (event location, when it ends, useful URLs etc.)

And all I got was another generic response:

Hello,

Thank you for your response. We encourage you to consider ways to make your app stand out.

We understand that it can be difficult to determine what the best experience is to offer your users.

While there isn’t one set answer that works for every app, the following iOS development videos offer great information for helping understand how your app can provide a great user experience: – Essential Design Principles – Design Tips for Great Games

You may also want to review the Human Interface Guidelines available on Apple Developer.

Best regards,

App Store Review

Now what?

I considered using some more device sensors to justify the app being an app.

I even did a parallax animation (because I thought it looked cool and it uses the accelerometer) and added one of those Taptic Engine button-like vibrations on clicking on the event image.

Parallax animation -- Twitter

But I think they just don't like the idea of the app, and no matter what I add to it, they won't accept it.

Update: 26 Aug 2022 at 19:30

Uhm.. something just happened

About a week after this article started spinning around the internet, I was quietly working on a chat feature for this app when something odd happened.

I got an email from App Store Connect that the app is now In Review. Without me submitting anything more than what was already there from the third try.

10 minutes later, the app was accepted and is now there for anyone to download on the App Store.

So, not sure what happened, I can only guess that someone from the review board might have stumbled upon this article.

If that is the case, thank you kind reviewer! You made my day, and my little brother's as well.

I forgot to mention in the first part of the article that the whole idea started so that my brother can have a basic income while he's going to art college, starting this autumn. The main reason why this is an app and not a website is because in-app purchases are easier to work with than payments on the internet (no need for creating a user account, payment data is usually already available etc.).

So yeah, we're finally one step further towards that goal. Just one more thing to figure out: who would pay for such a thing?

I develop 🌕 Lunar, a macOS app for getting intelligent adaptive brightness on external monitors and controlling every aspect of your monitor using DDC and other obscure protocols.

I get tons of email about Lunar, especially after it became my full time “job” in 2021. A lot of those emails complain about Lunar bugs, but sometimes, after a good multi day chase, I conclude it’s actually a monitor bug and the user has to kind of.. deal with it.

”Buy another monitor” is never a good response, so I try to help and provide a workaround whenever I can.

But anyway, here’s a small collection of those bugs.

Dual monitors swapped positions

You know how people get two identical monitors and place them side by side for a neat ultrawide-like look.

Well a lot of those people experience a very annoying behavior: After standby or restart, the monitors get swapped by the OS, so moving the cursor to the left monitor will actually appear on the right monitor, and vice-versa.

If the monitors also had some of the settings different, like resolution or color profile, those also get swapped.

This doesn’t happen for Apple vendored monitors like the Pro Display XDR in the above image, and you’ll see why in a minute.

How monitor settings are stored

Whenever you arrange monitors, the system has to store those coordinates persistently and restore them when the monitor reconnects. In standby, the monitor is actually disconnected and disappears from the I/O Registry, so on system wake, it reconnects and the OS has to rearrange based on the stored settings.

To store something persistently, you need to have a way of identifying that monitor precisely. So the OS computes an UUID from whatever it can find inside the data provided by the monitor.

That data is called the EDID structure and it contains things like vendor ID, week/year of manufacture, serial number etc.

Why does this happen?

The problem comes from vendors who flash the same exact firmware with the same EDID to multiple monitors in the same batch.

Serial number is emphasized above especially because by definition it should be a unique number that increments with each monitor. Well it doesn’t. And it has nothing to do with the serial number you see on the back of the monitor or the box or wherever it’s placed.

So if you have the bad luck to buy two identical monitors, from the same batch, with the same EDID, then the OS will compute the same UUID for both.

That means that on reconnection, the monitors will look identical from the OS side, so the stored settings will have to be assigned randomly for each monitor. That will sometimes, not always, but deterministically when it's most annoying, cause the swapping bug.

And there’s nothing you can do to fix it.

Workaround

The simplest solution is present in Lunar's Shortcuts (available without a Pro license):

• Swap Monitors to fix arrangement on setups with 2 monitors
• Fix Monitor Arrangement for setups with 3 or more monitors

For people that don't want to use Lunar, I wrote a simple CLI for swapping monitors here:

mac-utils/SwapMonitors.swift · GitHub

Installation

• You can either install it from the Terminal:

export BINDIR=/usr/local/bin
export BINURL="https://github.com/alin23/mac-utils/raw/main/bin/SwapMonitors"

mkdir -p "$BINDIR" && \
  curl "$BINURL" > "$BINDIR/SwapMonitors" && \
  chmod +x "$BINDIR/SwapMonitors"

• Or use a Shortcut that does that automatically

The shortcut also provides a way to bind a hotkey, or run it from the menu bar.

Usage

• Just run it and let the algorithm find the monitors that should be swapped: (either press the hotkey you assigned to the Shortcut, or run it from the command line)

⌁ ❯ SwapMonitors

Swapping Dell U2719D (2) [ID: 17] with Dell U2719D (1) [ID: 18]

External Display 1: x=4872.0 y=0.0 width=2560.0 height=1440.0
	Moving to: x=1800.0 y=0.0

External Display 2: x=1800.0 y=0.0 width=3072.0 height=1620.0
	Moving to: x=4872.0 y=0.0

• Or pass the IDs of the monitors to swap as arguments

⌁ ❯ SwapMonitors print-ids
IDs of monitors in order of appearance from left to right: [17, 19, 18]
Names of monitors in order of appearance from left to right: ["Dell U2719D (2)", "LG Ultrafine", "Dell U2719D (1)"]

⌁ ❯ SwapMonitors 17 18

Swapping Dell U2719D (2) [ID: 17] with Dell U2719D (1) [ID: 18]

External Display 1: x=1800.0 y=0.0 width=2560.0 height=1440.0
	Moving to: x=4360.0 y=0.0

External Display 2: x=4360.0 y=0.0 width=3072.0 height=1620.0
	Moving to: x=1800.0 y=0.0

Monochrome HDR

While developing external monitor support for XDR Brightness, I needed a way to test it.

And since I don't have a 600nits+ monitor, I reached out to my friend István Tóth, the developer of BetterDisplay (and also a previous Lunar user who became a MonitorControl maintainer by porting Lunar's M1 DDC code to MonitorControl, long story).

When István turned on XDR Brightness on his Lenovo Creator Extreme, it was suddenly stripped of all color and everything became grayscale on it.

Other Lunar users also mentioned this issue on other specific monitor models, even before XDR Brightness was a thing. I thought I had an idea then on what could cause this, but this new data point dismantled my previous theory.

Some causes I can think of:

• The macOS ICC profile for that monitor computes a 0 chroma value in specific Gamma table configurations
• The monitor internal color profile/preset is reverted to some default value on receiving a DDC command that's not handled correctly
• The grayscale filter of macOS is enabled somehow? ¯\_(ツ)_/¯

In the end, I have no idea what causes the problem, I simply disabled XDR for external monitors by default in Lunar, and made it opt-in.

Blacking out

This is the bug that causes the most angry and panicky emails I get.

On receiving specific DDC commands, some monitors simply go black and stop responding to any user input.

Reconnecting the video cable doesn't do anything, the power button doesn't work, from the user perspective it looks like Lunar just bricked their monitors.

The fix is simple: unplug the power cable, and plug it back again

What's happening?

I have an idea.

Firmware bugs

Since Lunar doesn't do anything unusual (it just sends standard DDC commands for setting brightness and contrast), I assume the bug is in the DDC handler code inside the monitor controller firmware.

It's possible that either a specific series of bytes, or a burst of DDC messages, causes the firmware to crash, and maybe even enter in a tight loop since it doesn't seem to restart itself.

I keep an extensive FAQ with possible monitor features and settings that can break DDC and even cause this bug in specific setups: FAQ - The brightness or volume doesn't change

Long cables

On rare occasions, the issue was actually being caused by a too long Thunderbolt cable.

Most people don't know that there's no such thing as a 6 meter Thunderbolt cable, not without built-in signal amplifiers or fiber optics and expensive converter chips.

So, expectedly, when using the data channel for DDC for longer than a few milliseconds, the video signal will drop completely, or revert to a much lower resolution and refresh rate.

Custom color profiles

In other cases, the issue was a custom color profile, and the problem was actually caused by a macOS bug.

One Lunar user was an astronomer, and had a self-made observatory at home. He created a color profile that pushed most colors towards dark red, to keep his natural night vision when working.

But when Lunar adjusted the Gamma tables, the macOS color formula was sometimes reaching a point where every color computed to rgb(0, 0, 0).

The Lunar adjustments were completely normal and well within the documented range, and I found no way to predict on what values would the system reach that point.

I had to add a periodic timer that checks if the macOS color curve gets to 0, and reset all color adjustments, then forcefully disable that functionality for the user and let him know about it.

Switching input just blinks the screen

The DDC protocol (or more exactly the Monitor Control Command Set (MCCS) specification), defines a command for switching monitor inputs.

So you might have:

• a MacBook on the Thunderbolt input of your monitor
• a PlayStation on the HDMI1 input
• a Raspberry Pi on HDMI2

And to switch between those, you can fiddle with the monitor buttons, or you can do that with handy keyboard shortcuts through DDC.

Because KVMs are expensive, I implemented that functionality in Lunar for people that don't really need the "keyboard switching" part of a KVM, but mostly the "video switching" part.

So, where's the bug?

The thing is, some monitors lie about this functionality.

Even if the monitor reports that the VCP code 0x60 for Input Select is implemented, when any input value is sent, the monitor just blinks. By that I mean it goes black for a second, then returns to the previous image.

There's no software fix for these monitors.

Mute command doesn't do anything

Kind of in the same vein as with the input switching bug above, the DDC Mute command just doesn't do anything on some monitors.

The odd thing is that the monitors do have a mute switch in their OSD, but it's not controllable by the VCP code 0x8D for Audio Mute.

Instead, on some monitors, it seems that setting the volume to some non-standard value like 255 (or -1 if we flip from unsigned to signed integers), might affect the volume setting. On most monitors though, it doesn't do anything at all.

That's another workaround that got its own section in Lunar's settings because of how often it's encountered.

Lunar Lite

This was my first attempt at publishing on the App Store. I started earning money on my 🌕 Lunar Pro app for controlling native monitor brightness in May 2021. But after a few months I noticed some people were asking for a cheaper and more basic alternative to Lunar, that can also be installed from the App Store.

So I built Lunar Lite, an app that was supposed to dim monitor brightness by altering the Gamma curve to make the colors appear darker, and submitted it to the App Store on Nov 8, 2021 at 5:46 PM.

After about 2 hours and 30 minutes, on Nov 8, 2021 at 8:11 PM, I got a rejection.

There were two functionalities that the App Store review board rejected:

• Using a private macOS API to control the native brightness of the built-in MacBook/iMac display (DisplayServicesSetBrightness)
  • The reason given by the reviewer was that private APIs are not guaranteed to remain available and can break in subtle ways
  • There's no other way to get this functionality so controlling native brightness had to be left out
• Showing a menu item that linked to my other app, Lunar Pro, with a description that said: For more advanced features and native brightness control, check out Lunar Pro
  • The reason given was that I'm not allowed to link to other methods of payment for the app, even though I was linking to a completely different app

I appealed this, stating that my case falls under 3.2 Other Business Model Issues - 3.2.1 Acceptable:

3.2.1 Acceptable

(i) Displaying your own apps for purchase or promotion within your app, provided the app is not merely a catalog of your apps.

The appeal was rejected with the same generic message, so I just removed the menu item just to get it accepted.

This affected my business because of multiple reasons:

• Some people will hear about Lunar Pro from a friend, and go searching for it on the App Store, not knowing that advanced apps can only be distributed outside the App Store
  • Those people downloaded Lunar Lite thinking it would control the native brightness, and then would leave a bad review when they noticed it only did software dimming, even if the description clearly stated that limitation
• I wanted to give a 30% discount on Lunar Pro licenses for those Lunar Lite users that found that they needed more features after buying the App Store app
  • But that wasn't possible because I was forbidden from adding a coupon code link to Lunar Pro inside the app

Eventually I phased out Lunar Lite because bad reviews kept appearing from users that thought they were getting a good deal on the full-featured Lunar Pro app, and the App Store provides no way of handling those reviews.

All I could do was reply to those reviews with clarifications, but not a single user replied back or changed their review in any way.

Lunar Lite v1 timeline

rcmd

My second app for the App Store was a much simpler idea: an instant app switching method called rcmd that uses the Right Command key + the first letter of the app name

The execution of the idea was not so simple though because the App Store sandbox doesn't allow the usual way of listening to key events to differentiate between Left and Right ⌘ Command. I wrote at length on that here: Why aren't the most useful Mac apps on the App Store?

I submitted the first version of rcmd on Nov 18, 2021 at 1:37 PM and after 2 hours 26 min at Nov 19, 2021 at 4:03 PM the app was rejected.

The reason was the usage of yet another private API that I needed for opening Exposé on the windows of a single app.

Exposé preview

The rejection email

That wasn't such a big deal though, it was a useful functionality but I could live without it. I removed the feature and got the app accepted on my second attempt.

Because of App Store sandbox limitations, there was no way to switch to specific windows of an app (like for example, focus a specific PDF opened in Preview) so I got some bad reviews from people that expected that feature to be present.

Again, the App Store was completely unhelpful in getting rid of those reviews, even if they were clearly irrelevant because the user did not read the description before buying.

I tried both replying and reporting the reviews to App Store but nothing changed.

This was a paid app and planned to continue developing it and make a sizeable income on it, but people were reluctant to buying it without trying it first.

The missing support for free trials for one-time purchase apps on the App Store had the biggest impact on the business side. There is some support but it's awkward to both implement and present to users.

“Free trial” not allowed anymore

Date Submitted: 24 October 2021 at 20:28

Apparently my Free trial available on lowtechguys.com/rcmd line is not allowed anymore in the Promotional text section.

It has been there for the last few months, already approved by other reviewers.

But when I tried to release v2.3.0 with updates for Stage Manager on macOS Ventura, the app was rejected on the basis that the trial line is not app metadata.

Guideline 2.3 - Performance - Accurate Metadata

We noticed that your app's metadata includes the following information, which is not relevant to the app's content and functionality:

Free trial is available on the official website at lowtechguys.com/rcmd

I tried explaining that it is the only way to let people know that the app can be tried for free but was further rejected. Resubmitting the app got the same rejection.

In the end I removed the line just to push the update to users. I will remove rcmd from the App Store in the near future and publish it independently on my website.

rcmd v1 timeline

Copyright Infringement on cover artwork

Date Submitted: 2 October 2024

The video I'm using to demo how rcmd works with Stage Manager, shows how I switch to a Music stage where I have Spotify in the foreground. And because I've got FKJ's VINCENT album in that window with the cover artwork obviously showing, I'm apparently at risk of copyright infringement.

The reviewer helpfully included a very low-res screenshot of where I'm doing that:

I removed that video as I didn't have time to edit it and resubmitted.

Another rejection came in as my other main video also switched to Spotify for a second and showed some cover artworks.

I didn't have that original video anymore, and Apple offers no way of downloading the video from App Store Connect.. whatever, deleted the video and resubmitted with only screenshots. I'll get out of the App Store soon anyway, I'm sick of this.

Volum

My third attempt, and my first foray into multiplatform development (both iOS and macOS) was Volum, an app for controlling DIY smart home devices, that don't have an app or a visual way to control them.

It started as a volume control app for Yamaha AV Receivers, because I wanted to be able to press volume keys to control the sound from my Mac, instead of reaching for the AV receiver volume knob.

The first version of the app was rejected on legal matters, stating that I was not allowed to mention Yamaha's brand and products. So I removed mentions to Yamaha from the descriptions and screenshots, and advertised the app as a generic smart home control app.

I didn't see much hope in making money from this app, as it fills a very narrow niche, so this didn't impact my business.

Volum v1 timeline

Sub Sol

This was the most frustrating experience I had with the App Store review board, because I had no idea what they were asking from me.

Besides the fact that iOS apps take a lot longer to get reviewed (measured in days as opposed to hours for macOS apps), the reason for the rejection felt plain stupid: the app was too simple, and not worthy of being on the App Store.

I wrote some notes on my blog about the experience, which quickly became viral after publishing the link on Hacker News: App Store doesn't accept "too simple" apps — Alin Panaitiu

In the article you can find my 3 attempts at fixing issues and resubmitting the app, along with my appeal that changed nothing.

The app was my way of helping my brother earn a basic income until he gets to go on his first year of college in autumn.

The idea was that he would curate this list of underground parties and festivals instead of scrubbing dishes or working in retail for the summer. I needed the app on the App Store so I could monetise it easily.

The target audience wouldn't pay for such a thing on the web. It's a lot less friction to authorise a $1 app purchase with your face than inputting your credit card details on a web form, and I needed that convenience.

After a few days of the article being shared all over the internet, suddenly the app was changed to In Review without me doing anything, and accepted, just like that.

But it was already too late. The summer had passed, festivals were ending, there were less and less parties, and the idea of making money from this was fading. The college admission process and finding rent was also taking all my brother's remaining time by now so we made the app free for the moment. We'll try again next year.

Sub Sol v1 timeline

I’ve been unemployed since May 2021, and occupied my time by mostly working on macOS apps for my small app studio: The low-tech guys.

That may sound ideal for some, but it’s actually a very frustrating type of work most of the time. And to vent that frustration, somehow, I started writing.

I’m not really sure how it happened. One day, I just found myself morphing my hastily written findings into a short story, until it started looking like something I would want to read.

Copper and Hugo

I first started writing on this blog I called Copper, which existed there as a placeholder since when I created my personal website using Hugo.

At the time, I wanted to share my PCB reverse engineering efforts, hence the name Copper. Nothing came out of that though.

I liked how fast Hugo is at hot reloading, and how the basics for writing a blog are builtin: a fast and complete Markdown renderer, RSS, a sitemap, categories, series, tags etc.

But it took me a while to bend it to my idea of a blog.

I started with the Blogophonic theme (which I most likely didn't need) that uses the Tachyons CSS framework (yet another thing to learn), and had to work my way through shortcodes, templates, archetypes, obscure CSS classes, page layouts, YAML frontmatter.. it felt like a burden.

When all you need is to get that yarn ball of sentences out of your head, onto a page where eyes can make some sense out of it, meddling with the innards of a site generator is the last thing you want to start with.

After seeing how well received that first article was, I wrote a few more, mostly to share what I had learned in those last few months of research. But it was getting tiring to do all the git and hugo dance just to write some words.

NotePlan

I found this super useful note taking app called NotePlan when I first subscribed to Setapp, and been using it ever since because of its good looking markdown themes, per-day notes and calendar integration.

I was already using NotePlan for tasks and ideas, so I also started writing those articles in NotePlan first before moving them to Hugo for refinement. That’s because I could more easily see how the markdown will look like when it’s rendered.

Also because I love writing in the NotePlan iPad app with the Apple Pencil, but not exactly in the way most would imagine.

I had some shorter pages written in NotePlan on various findings that I didn’t move in Hugo because I felt that the blog should be destined for long form articles based on deeper research.

I knew NotePlan has a Publish with iCloud button and used that for sharing rendered Markdown pages a few times. I thought, why not use that for a notes page where I can share every little tidbit instantly?

I created notes.alinpanaitiu.com, which at first was just an HTML file where I manually added links to my notes published from NotePlan.

While testing, I quickly realized something I was sure would not scale: on every browser visit, the published page was using CloudKit.js to fetch the markdown text of my note from a database and render it to HTML.

I know that this is what allowed me to see my NotePlan changes rendered on the web without delays. But it felt slow, wasteful, and I would probably run into some CloudKit rate limits sooner or later.

Caddy

I have a Caddy server running on Hetzner, where I manage all my domains, reverse proxies and static file servers from a single Caddyfile.

Somehow I stumbled upon the fact that it also renders markdown and Go templates out of the box. That was a nice coincidence!

Since NotePlan stores the notes as plain .md files in a single local folder, I autorsync-ed that folder to my server and quickly configured Caddy to render the files on the notes.alinpanaitiu.com domain.

 notes.alinpanaitiu.com {
    root * /static/notes/

    file_server
    templates {
        mime text/html text/plain text/xml
    }

    encode zstd gzip

    try_files {path} /index.html?path={path}
}

Unexpectedly, even though it's a rare event in the web dev world, the thing just worked!

The pages looked crude without styling, but I was now able to write beautiful markdown in NotePlan and have it instantly available as a fast and ugly public web page.

I ported the style from my blog as a single CSS file with no framework (turns out you don’t really need that nowadays, huh), wrote an index.html, a sitemap.xml and an rss.xml using simple Go templating ❴❴ stuff ❵❵ for the dynamic bits, called it Zinc (because Copper was already taken), and published it to the world!

The first thing there were my notes on how App Store reviewers rejected my first iOS app multiple times: App Store doesn’t accept “too simple” apps. The piece became viral quickly, helped get the app accepted, and also got my name mentioned in a Wired article. To keep the surprises coming, an old friend noticed my name in that article and decided to contact me, creating a nice opportunity to reunite.

I like trains 🚂

I don't own a car and never plan to. My wife and I, we're the weird ones amongst our friends and relatives because of that. We never went to driving school, we like walking a lot, and we get sick after 5 minutes in a car. Nowadays we get sick even faster because of the obnoxious, vomit inducing, smelly "air fresheners" that are EVERYWHERE. How do those people breathe all day??

Out of necessity, we've grown accustomed to take the train wherever possible, and even started to like the conditions:

• large leg space
• a table between the seats for the laptop
• sockets for charging electronics
• no tight turns, mostly going slowly in a straight line
• long, boring rides because Romania's rail infrastructure has been neglected for the last 40 years, and trains have to limit their speed to 30km/h on most segments
  • not exactly a fan of this.

You can even sleep in those things if you don't mind the claustrophobic beds.

And because we travel a lot and I don’t want to haul my 2kg of Apple Silicon in laptop form every time, I wanted to make sure I can write and publish these notes from my overpowered iPhone.

NotePlan is already on my iPhone, iPad and MacBook and it syncs flawlessly everywhere, so writing the articles is a solved problem.

For publishing, I went with a semi-automated solution based on Syncthing, my favorite peer-to-peer file sync software, since I already had it running on the Hetzner server where Caddy is running.

I installed Möbius Sync, a Syncthing client for iOS, and tried pointing it to the notes folder. But because each iOS app runs in its own sandbox, Möbius couldn't see NotePlan's files.

I had to create a separate notes folder that Möbius could see, then made a Shortcut to copy files from NotePlan's folder to Möbius's folder in a single tap. That turned out to be an even better solution because I could now edit notes without confusing readers with pages that end abruptly in the mi... ddle of the sentence.

Details

I kinda like this solution for now. It gives me the feeling that I own it and that I know how all the moving parts interact.

I can also write when I’m offline and get things synced later, even when I get just the thinnest trickle of internet bandwidth.

Now I wonder if a ready to use service like this already exists and I didn’t know what to look for.

My key points seem to be:

• A native app that works offline, syncs on all devices, and looks clean
• A way to bring my own custom domain
• Markdown with syntax highlighting
• Custom CSS support
• RSS
• Sitemap file
• Opengraph, Twitter etc. meta tags generator
• Lean HTML, no unnecessary JS
• Templating (although it can be omitted if sensible defaults are in place)
• Media files that I can just drag and drop in the editor

That last point still needs a bit of manual work right now. NotePlan supports dragging images and have them rendered inline without issues. It even places the image files in a [note title]_attachments folder right beside the [note title].md file which allows relative links to work even after moving the folder around.

Optimizing images is important to me and I’m glad I found out about imgproxy. I have it running on my server and I replace every <img src=""> with a <picture> equivalent that resize images on the fly and converts them to either AVIF or WEBP based on what the client supports.

Moving pictures are a pain though.

I never use GIFs because of their size inefficiency and bad quality. So I convert everything to highly efficient videos, then upload them to a separate static file server (because Mobius Sync has a 20MB limit on the free plan).

But I have to use ffmpeg on my laptop for that, and the videos don’t get rendered in NotePlan (although that’s not that big of a deal). I should probably automate that on my server somehow.

I like autoplay muted loop videos, but I wish they were loaded lazily when the scroll position reached the part of the page where the video is. I’ll probably have to add some JS for that in the future, or move to play on click mode.

It feels odd that we have to go through all of this just to get some colorful text, some images and videos on a public web page owned by the author.

What I have now is a bit fragile, but it’s still a joy to use. It’s simply convenient and always available on all my devices.

I don’t have to use a laggy web editor that generates a bloated web page, or a command line that’s severely limited and hard to type in a mobile environment.

I hop on a noisy train in the dark, watch the sun rise from behind mountains still covered by Romania’s old trees, and start laying my thoughts on this virtual paper that’s always here in my pocket.

Someone, somewhere, will read them.

I've been sitting on publishing these notes for a while, because I don't want to diminish the work of the talented people that engineered SwiftUI and plowed through years of AppKit and UIKit code to get to this state.

But I'd like to draw attention to some performance limitations, in the hope that a SwiftUI engineer might see this and understand pain points that might not be so obvious from their side.

Grila

I built a calendar app for macOS. There are many calendar apps out there, but this one is mine, and I wanted it to fit two very specific use cases:

• keyboard-oriented UI and navigation
• always one key-press away

This is the How?, an idea of the behaviour that the calendar should have when it's done - but the Why? is a bit of a longer story.

In October 2022, my little brother started college, and moving from the countryside to a big city meant large costs of living that my parents weren't prepared for. I wanted to support him somehow.

To support himself, he currently has to work 12 hours a day, 5 days a week (including weekends) at a coffee shop. He barely sees the college building.

I thought I could build a low effort, low maintenance, affordable but still useful app, from which all the proceeds will go towards funding his costs. I actually tried that in the summer but the App Store rejections rendered my efforts useless.

So sifting through my noted app ideas, I thought a keyboard-driven macOS calendar would be the simplest to build, especially with the newest SwiftUI additions.

After all it's just a grid of numbers that doesn't even need to be clickable, how hard could it be? (I'm saying that a lot, aren't I?..)

The SwiftUI convenience

After a week of long days stretching into the night, I had this thing working that I called Grila (Romanian word for "grid")

In 7 days I had 3 different views (year, month and 3-months), light and dark mode support, customisable color schemes, keyboard navigation and help hints to make it discoverable, and best of all: ✨ ANIMATIONS! ✨

These damn animations man.. they're so fluid and springy and easy to use in SwiftUI, that it lures you into adding them everywhere.

The grid

I started with the only obvious grid element for laying out the weeks as rows of days: LazyHGrid

LazyHGrid(rows: (1...7).map { _ in GridItem(.fixed(30)) }) {
    ForEach(days) { day in
        DayView(day: day)
    }
}

And it was obviously wrong for my use case...

This container is lazy so it takes more time get the view rendered because SwiftUI has to check if each row is visible before rendering it.

Since there was no other grid element, I had to write my own using HStacks inside VStacks. This took longer than I expected because I had to compute how many weeks a month has and on what column it starts and ends. As usual, fixing an edge case brings with it three more.

But after this hiccup, almost everything that followed felt surprisingly easy to build.

The (over)views

For example I wanted to be able to switch between a full year view and month views, which also meant the window had to be resized to fit each view. As soon as I had my separate views, this was all I had to do in my main view:

enum GridZoom {
    case month
    case multiMonth
    case year
}

struct MainView: View {
    @State var zoom: GridZoom

    var body: some View {
        switch zoom {
            case .month:
                MonthView().fixedSize()
            case .multiMonth:
                MultiMonthView().fixedSize()
            case .year:
                YearView().fixedSize()
        }
    }
}

The .fixedSize() modifier would resize the window automatically, and simply setting the zoom property would render the appropriate view.

Color schemes

I also wanted to have configurable color schemes because not everyone likes the same colors as I do, and because sometimes I get bored of the chosen colors myself.

With 3 sliders for hue, saturation and contrast, and a few built-in SwiftUI modifiers, I had created the easiest way to adjust the color palette:

struct ColorPreferencesView: View {
    @AppStorage("hue") var hue = 30.0
    @AppStorage("saturation") var saturation = 1.0
    @AppStorage("contrast") var contrast = 1.0

    var body: some View {
        Slider(value: $hue, in: 0.0 ... 359.0, label: { Text("Hue") })
        Slider(value: $saturation, in: 0.0 ... 2.0, label: { Text("Saturation") })
        Slider(value: $contrast, in: 0.0 ... 2.0, label: { Text("Contrast") })
    }
}

struct ContentView: View {
    @AppStorage("hue") var hue = 30.0
    @AppStorage("saturation") var saturation = 1.0
    @AppStorage("contrast") var contrast = 1.0

    var body: some View {
        MainView()
            .hueRotation(.degrees(hue))
            .saturation(saturation)
            .contrast(contrast)
    }
}

Keyboard-oriented UI

Reacting to keyboard events is still something I do outside of SwiftUI when I need single-key shortcuts (e.g. / instead of ⌘/).

That's easily done by using a local event monitor:

NSEvent.addLocalMonitorForEvents(matching: .keyDown) { event in
    switch event.keyCode {
        case kVK_ANSI_Slash:
            let showHelp = UserDefaults.standard.bool(forKey: "showHelp")
            UserDefaults.standard.set(!showHelp, forKey: "showHelp")
        // case NUMBERS:
        //     changeDay()
        // case LETTERS:
        //     changeMonth()
        default:
            return event
    }

    return nil
}

struct ContentView: View {
    @AppStorage("showHelp") var showHelp = false

    var body: some View {
        MainView()

        if showHelp {
            HelpHints()
        }
    }
}

Performance pitfalls

I never create apps just for other people, I have to have a need for that app myself so that I understand both the problem and the solution. Also solutions usually need to evolve with the world and the constant technology changes, otherwise the app becomes obsolete fast.

I also never release apps as soon as they're done. I use them myself for weeks, so I can notice all the creaks and rattles in real world usage before getting them in the hands of people.

So after that week of building, exactly in the first day after, a friend calls to tell me they'd like to visit from another city in about a month. When's the best time?

Nice, exactly what I made Grila for! No more need to launch Alfred or Spotlight, type "calendar", hit enter, look bedazzled at the "Week view? what the heck is this for?", figure out how to switch to the month view, oh wait, I have to constantly switch between November and December.. "maybe the year view is better?" nope, no events are visible there.

Now I just press Right Option+\ and have both November and December and events in my face instantly!

Well not really.

It took about two seconds and a cringing janky animation to get Grila rendered on the screen. Every key press made me slow down my thinking because there was a 1 second latency until the action changed something in the UI. It made me feel like I went back to 2008 on my Core 2 Duo PC running Windows Vista.

What was different? This time I had Low Power Mode active on my M1 Max MacBook.

Even with LPM, this CPU is still incredibly fast. If Grila struggles so much on it, I can't even imagine how bad it would behave on older Intel Macs.

Instruments for investigation

macOS has a powerful troubleshooting utility for apps called Instruments.

Attaching its Time Profiler to Grila showed that the heaviest stack trace was in some SwiftUI graph updating code. Look at this thing!

Click on it, I dare you.

Yes, that's how much I understood from it as well.

Since the stack trace is of no use, I tried the SwiftUI profiling template from Instruments.

What looks unusual is the huge number of updates on my custom views. Some updates also take 5ms or more which when called on the main thread, will block any UI rendering and animations.

Maybe I was sloppy and too liberal with my view states, I should improve on this.

Optimisations (and wacky workarounds)

The slowest thing was the year view. Because it had to render more than 365 views, each small change was excruciatingly slow.

I lowered the number of views by consolidating each month's day views into a single, carefully aligned text string.

So this:

struct WeekRow: View {
    @State var week: Int

    var body: some View {
        ForEach(days(week)) { day in
            Text(day)
        }
    }
}

struct YearMonth: View {
    var body: some View {
        VStack {
            WeekRow(week: 1)
            WeekRow(week: 2)
            WeekRow(week: 3)
            WeekRow(week: 4)
            WeekRow(week: 5)
        }
    }
}

Became this:

struct YearMonth: View {
    var body: some View {
        Text(generateMonthText())
            .font(.body.monospaced())
            // Using the `monospaced` font makes
            // aligning text columns much easier
    }
}

Year view was now much faster, but partly neutered as I had no way of showing events or other types of information under each day. Oh well, that doesn't mean much anyway if I can't even make this app usable.

The 3-months view had no obvious low hanging fruit. The View Properties Updates profiler showed that there were a ton of updates causing the body of the view to be called many times, but it was impossible to figure out what mattered.

Somehow in my tireless internet sleuthing, I stumbled upon a SwiftUI private function that prints the changes which caused a body update: Self._printChanges()

So I could now insert that line into my DayView and work my way up to the MultiMonthView until I figured out what changes are unnecessary.

States and Bindings

The words that you'll stumble upon the most in SwiftUI are @State and @Binding, which are property wrappers for defining local state and two-way bindings.

You see, there's this thing that happens a lot when creating SwiftUI views with deeper hierarchies:

• You create BigContainingView with @State var someProp
• Inside you call SmallView(prop: someProp)
• You change someProp outside
• Why isn't SmallView updating?
• You add @Binding var prop into SmallView
  • and call it using SmallView(prop: $someProp) (notice the added $)
• Ah nice, the view is now updating

Because of this issue, I had created a shortcut for passing one-way bindings, and because of this shortcut, my list continued with:

• Performance issues..
• Why is SmallView NOW CONSTANTLY UPDATING?

In the following example, I needed a way to highlight the selected day, but passing selected as @State wouldn't propagate through the view graph. So I made it a binding, which caused all the DayViews to update when selecting another day (instead of just the two days that actually changed):

extension Binding {
    static func oneway(getter: @escaping () -> Value) -> Binding {
        Binding(get: getter, set: { _ in })
    }
}

struct DayView: View {
    @State var date: Date
    @Binding var selected: Bool

    ...
}

struct MonthView: View {
    @State var selectedDate: Date

    var body: some View {
        ForEach(dates) { date in
            DayView(date: date, selected: .oneway { date == selectedDate })
        }
    }
}

----------------------------------

// Logs from Self._printChanges()

DayView: _selected changed.
DayView: _selected changed.
DayView: _selected changed.
// ... repeated 77 times

The solution I found for this was to turn the Binding back into a State and manually add an .id() to the DayView that factors in the selected property.

That way, the graph algorithm will compare the new id with the old one, and if selected is different, the view will get redrawn.

struct MonthView: View {
    @State var selectedDate: Date

    var body: some View {
        ForEach(dates) { date in
            let isSelected = date == selectedDate

            DayView(date: date, selected: isSelected)
                .id("\(date)-\(isSelected)")
        }
    }
}

This change alone decreased the number of unnecessary view updates to 1/4 of what it was when I started debugging.

ObservableObject

Another pattern I tend to overuse is having a global object with @Published properties that I can change from AppDelegate and have their changes seen by SwiftUI views.

class SomeGlobalObject: ObservableObject {
    @Published var fooDayView = true
    @Published var barHintView = false
}

let GLOBAL = SomeGlobalObject()


struct DayView: View {
    @ObservedObject var global = GLOBAL

    // ... uses fooDayView somewhere
}

struct HintView: View {
    @ObservedObject var global = GLOBAL

    // ... uses barHintView somewhere
}


// somewhere in AppDelegate

barHintView.toggle()

----------------------------------

// Logs from Self._printChanges()

DayView: _global changed.
DayView: _global changed.
DayView: _global changed.
...
HintView: _global changed.

DayView doesn't use the changed property, so all those updates could have been skipped entirely. In this case, I had to get over my tendency to not repeat myself, and just pass the properties as parameters.

There are other ways to fix this, each with its own quirks:

• Store those properties in UserDefaults
  • This makes them persistent on disk which might not be desirable
• Define multiple, more specific global objects with less properties
  • It becomes hard to remember which object had which property
• Pass the values as EnvironmentValues
  • This needs even more boilerplate
  • Helpful if the property is needed deep in the view hierarchy

Here's the EnvironmentValues alternative as an example:

struct SelectedDateKey: EnvironmentKey {
    static let defaultValue = Date()
}

extension EnvironmentValues {
    var selectedDate: Date {
        get { self[SelectedDateKey.self] }
        set { self[SelectedDateKey.self] = newValue }
    }
}

extension View {
    func selectedDate(_ selectedDate: Date) -> some View {
        environment(\.selectedDate, selectedDate)
    }
}

struct ContentView: View {
    var body: some View {
        MainView()
            .selectedDate(globalSelectedDate)
    }
}

struct SomeViewDeepDownInTheGraph: View {
    @Environment(\.selectedDate) var selectedDate

    var body: some View {
        Text(selectedDate.formatted())
    }
}

Animations

When they’re done correctly, animations can convey information that would otherwise be missing. Like where an element was moved after a layout change, or how a view was resized when more elements appeared inside it.

SwiftUI makes this specific case easy to implement using .matchedGeometryEffect:

struct ContentView: View {
    @Namespace var namespace

    var body: some View {
        HStack {
            if showHelp {
                PinWindowButton(showHint: true)
                    .matchedGeometryEffect(id: "pinWindowButton", in: namespace)

                Spacer()
                HelpHints()
            } else {
                PinWindowButton(showHint: false)
                    .matchedGeometryEffect(id: "pinWindowButton", in: namespace)
            }
        }

        MainView()
    }
}

Animations don’t always have to be practical though. They can be added solely for their whimsical effect.

I myself love it when I’m mesmerized by an user interface that appears organic and closer to real life movement. Those interfaces feel much more personal.

Springs in SwiftUI can create that appearance without having to tune any parameter:

Button("Toggle Help Hints") {
    withAnimation(.spring()) {
        showHelp.toggle()
    }
}

// Toggling showHelp will move the PinWindowButton and change its size
//
// SwiftUI will compute the difference between the old and new layout,
// and animate that difference using the `.spring` animation

But a lot of the time, animations are overused and can’t even be turned off.

I remember the first time I used a MacBook trackpad in 2015, swiping with three fingers to move through Spaces. It felt magical.

Less than one year later, the same animation was driving me nuts because I was switching spaces so often, that the animation was slowing me down. There’s no way to disable that animation from the system, you can only reduce it to a crossfade.

Yabai can actually disable it by altering the system window manager code in memory, but that requires disabling SIP (which I can’t do anymore because I need some iOS apps on my Mac which only work with SIP enabled).

I have since settled on using a single Space with my rcmd app for instant app switching.

I wanted to improve this experience though, so I made animations completely configurable in Grila.

Because they’re computationally expensive, I disabled them by default in Low Power Mode, or when Reduce Motion is enabled in Accessibility settings.

// in AppDelegate
reduceMotionObserver = NotificationCenter.default
    .publisher(for: NSWorkspace.accessibilityDisplayOptionsDidChangeNotification)
    .sink { _ in reduceMotion = NSWorkspace.shared.accessibilityDisplayShouldReduceMotion }

lowPowerModeObserver = NotificationCenter.default
    .publisher(for: .NSProcessInfoPowerStateDidChange)
    .sink { _ in lowPowerMode = ProcessInfo.processInfo.isLowPowerModeEnabled }


// in SwiftUI
withAnimation((reduceMotion || lowPowerMode) ? .linear(duration: 0) : .spring()) {
    actionProducingLayoutChange()
}

I also gave the user the choice to enable them back, disable them completely and even change their speed and springiness.

Is it fast yet?

Two months later, after exhausting all the optimization possibilities, the app finally felt usable. It was plenty fast for the actions that were most often used so I finally released it.

But it could be better.

I’m not entirely sure if there’s still a lot of performance left on the table for the SwiftUI engineers, but it kinda looks that way from my side. There are some places where the framework seems to be doing a lot of unnecessary work.

Taking the 3-months view for example, it renders 11 rows of days, of which only half change when going to the next month. But I’m still seeing all 11 x 7 views being scrapped and rendered from scratch.

In the AppKit world I would have had the day views as class instead of struct, and I could have updated their day number and weekday in place. It wouldn’t be easy, but it’s an optimization that would have made all the difference.

The year view is an even more dramatic example, where the 365 day views are made up of only 31 stylised text views, cloned and placed on different coordinates. Those 31 views can even be drawn beforehand and cached forever. I found no way of letting SwiftUI know about this fact, and have it used for optimization.

Is there hope?

Obviously, I have no idea of the underlying architecture of SwiftUI, so what I'm saying might not even be possible. Or, when implemented, it would open up a can of edge cases and causing bugs that would be even worse than not having it in the first place. Or maybe my specific use case is caused by my own inability to use SwiftUI properly.

Maybe I'm just not holding it right.

But sooner or later, other app devs will try the same things I tried. The chaos of this world guarantees it.

And it's not a big deal, people could have lived without yet another calendar app. I could do other things to help my brother. The sun would still shine the next day (until it implodes 5 billion years in the future).

But ever since leaving the AppKit and UIKit world, I felt that these Apple engineers have created a magical tool. I felt like going from hammering a piece of metal to a CNC precision cutter. I'm using less force, moving much faster, and things end up even closer to how I wanted them to look.

In the last 3 years, I had the feeling that the ultimate goal for SwiftUI is to reach feature parity with the other established system UI frameworks, and we're incredibly close to that.

My hope is that after this, those Apple engineers will realise what a great thing they created, and continue honing it until we'll no longer have the need to compare the new with the old.

EDIT: A simple way to speed this up

Two years later, I finally found the largest culprit of the slowness, and wrote about it here: How I made my SwiftUI calendar app 3x faster

There's this thing called Launchpad on macOS which shows you all the apps on your Mac in an iOS like manner.

You may already have it in the Dock, but you can also launch it as any other app. There's even a nifty trackpad gesture for it where you pinch with thumb and three fingers.

When holding Option, it wiggles the app icons and shows an X button for apps installed from Mac App Store (MAS for short). Clicking on that button removes the app, along with its preferences and other files it created.

But hold on, why is Lunar having an X button in the first video though? Could it be that..

No no, it's not on the App Store, it would never have a chance in hell getting accepted there given the plethora of private APIs that it uses.

Turns out, there's a simple way to have that button show up for non-MAS apps as well.

mkdir /Applications/Lunar.app/Contents/_MASReceipt
touch /Applications/Lunar.app/Contents/_MASReceipt/receipt

Having an empty MAS receipt tricks the system to think the app was installed from App Store.

So what happens when I click that symbol now?

> fsevent_watch -F /

215781385   0x00020200=[removed]    /Applications/Lunar.app
215781406   0x00020200=[removed]    /Users/alin/Library/Application Support/Lunar
215781409   0x00010200=[removed]    /Users/alin/Library/Preferences/fyi.lunar.Lunar.plist

Well, looks like we got a working uninstaller with a good user experience for free.

For people looking for ways to remove files from apps that are already uninstalled, I'll leave below some possible methods:

Brew

If a Homebrew Formulae exists for that app, you can run the following terminal command to remove app files left behind:

brew uninstall --cask --force --zap

This works because most app developers will declare the paths that can be safely deleted inside the formula. One can view that using the brew cat <app-name> command.

Cleaner apps

1. FindAnyFile can look for files belonging to a specific app, even if it was uninstalled
2. AppCleaner can uninstall apps and delete its files at the same time

Using Lunar's CLI

If you are already using Lunar, I added a simple command-line action in v6 that can do that on both Apple Silicon and Intel.

# Install CLI if not already installed
/Applications/Lunar.app/Contents/MacOS/Lunar install-cli

# Read and decode EDID from all monitors
lunar edid

# Read and decode EDID from a specific monitor
lunar edid dell

You'll get a nice human readable structure like this:

LG Ultra HD [ID 5]
    edid-decode (hex):

    00 ff ff ff ff ff ff 00 1e 6d 09 5b b9 ca 04 00
    08 1b 01 04 b5 3c 22 78 9e 30 35 a7 55 4e a3 26
    0f 50 54 21 08 00 71 40 81 80 81 c0 a9 c0 d1 c0
    81 00 01 01 01 01 4d d0 00 a0 f0 70 3e 80 30 20
    65 0c 58 54 21 00 00 1a 28 68 00 a0 f0 70 3e 80
    08 90 65 0c 58 54 21 00 00 1a 00 00 00 fd 00 38
    3d 1e 87 38 00 0a 20 20 20 20 20 20 00 00 00 fc
    00 4c 47 20 55 6c 74 72 61 20 48 44 0a 20 01 11

    02 03 11 71 44 90 04 03 01 23 09 07 07 83 01 00
    00 02 3a 80 18 71 38 2d 40 58 2c 45 00 58 54 21
    00 00 1e 56 5e 00 a0 a0 a0 29 50 30 20 35 00 58
    54 21 00 00 1a 00 00 00 00 00 00 00 00 00 00 00
    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 c8

    ----------------

    Block 0, Base EDID:
     EDID Structure Version & Revision: 1.4
     Vendor & Product Identification:
       Manufacturer: GSM
       Model: 23305
       Serial Number: 314041
       Made in: week 8 of 2017
     Basic Display Parameters & Features:
       Digital display
       Bits per primary color channel: 10
       DisplayPort interface
       Maximum image size: 60 cm x 34 cm
       Gamma: 2.20
       DPMS levels: Standby
       Supported color formats: RGB 4:4:4, YCrCb 4:4:4, YCrCb 4:2:2
       Default (sRGB) color space is primary color space
       First detailed timing includes the native pixel format and preferred refresh rate
     Color Characteristics:
       Red  : 0.6523, 0.3349
       Green: 0.3046, 0.6367
       Blue : 0.1484, 0.0615
       White: 0.3134, 0.3291
     Established Timings I & II:
       DMT 0x04:   640x480    59.940476 Hz   4:3     31.469 kHz     25.175000 MHz
       DMT 0x09:   800x600    60.316541 Hz   4:3     37.879 kHz     40.000000 MHz
       DMT 0x10:  1024x768    60.003840 Hz   4:3     48.363 kHz     65.000000 MHz
     Standard Timings:
       GTF     :  1152x864    60.000000 Hz   4:3     53.700 kHz     81.624000 MHz
       DMT 0x23:  1280x1024   60.019740 Hz   5:4     63.981 kHz    108.000000 MHz
       DMT 0x55:  1280x720    60.000000 Hz  16:9     45.000 kHz     74.250000 MHz
       DMT 0x53:  1600x900    60.000000 Hz  16:9     60.000 kHz    108.000000 MHz (RB)
       DMT 0x52:  1920x1080   60.000000 Hz  16:9     67.500 kHz    148.500000 MHz
       DMT 0x1c:  1280x800    59.810326 Hz  16:10    49.702 kHz     83.500000 MHz
     Detailed Timing Descriptors:
       DTD 1:  3840x2160   59.996625 Hz  16:9    133.312 kHz    533.250000 MHz (600 mm x 340 mm)
                    Hfront   48 Hsync  32 Hback   80 Hpol P
                    Vfront   54 Vsync   5 Vback    3 Vpol N
       DTD 2:  3840x2160   30.000000 Hz  16:9     66.660 kHz    266.640000 MHz (600 mm x 340 mm)
                    Hfront    8 Hsync 144 Hback    8 Hpol P
                    Vfront   54 Vsync   5 Vback    3 Vpol N
       Display Range Limits:
         Monitor ranges (GTF): 56-61 Hz V, 30-135 kHz H, max dotclock 560 MHz
       Display Product Name: 'LG Ultra HD'
     Extension blocks: 1
    Checksum: 0x11

    ----------------

    Block 1, CTA-861 Extension Block:
     Revision: 3
     Basic audio support
     Supports YCbCr 4:4:4
     Supports YCbCr 4:2:2
     Native detailed modes: 1
     Video Data Block:
       VIC  16:  1920x1080   60.000000 Hz  16:9     67.500 kHz    148.500000 MHz (native)
       VIC   4:  1280x720    60.000000 Hz  16:9     45.000 kHz     74.250000 MHz
       VIC   3:   720x480    59.940060 Hz  16:9     31.469 kHz     27.000000 MHz
       VIC   1:   640x480    59.940476 Hz   4:3     31.469 kHz     25.175000 MHz
     Audio Data Block:
       Linear PCM:
         Max channels: 2
         Supported sample rates (kHz): 48 44.1 32
         Supported sample sizes (bits): 24 20 16
     Speaker Allocation Data Block:
       FL/FR - Front Left/Right
     Detailed Timing Descriptors:
       DTD 3:  1920x1080   60.000000 Hz  16:9     67.500 kHz    148.500000 MHz (600 mm x 340 mm)
                    Hfront   88 Hsync  44 Hback  148 Hpol P
                    Vfront    4 Vsync   5 Vback   36 Vpol P
       DTD 4:  2560x1440   59.950550 Hz  16:9     88.787 kHz    241.500000 MHz (600 mm x 340 mm)
                    Hfront   48 Hsync  32 Hback   80 Hpol P
                    Vfront    3 Vsync   5 Vback   33 Vpol N
    Checksum: 0xc8  Unused space in Extension Block: 74 bytes

I only coded the logic for reading the EDID using DDC. The actual decoding part is done using an embedded universal binary of edid-decode.

Coding it from scratch

Here I'll lay out how EDID data can be read from a monitor using DDC. We'll continue to use edid-decode for decoding it.

If you want to skip compiling edid-decode, you can find it for download here: github.com/alin23/Lunar - bin/edid-decode

Apple Silicon

Communicating over DDC is different for each Mac architecture.

On Apple Silicon, macOS provides us with a handy private function inside IOKit:

IOReturn IOAVServiceCopyEDID(IOAVServiceRef service, CFDataRef* edidData)

For each connected monitor, there will be a DCPAVServiceProxy present in the hardware tree. From that proxy we can construct an IOAVService instance and call IOAVServiceCopyEDID on.

DCP stands for Display CoProcessor, a separate chip with its own firmware, that handles display communication without loading the CPU.

Read more in Asahi Linux Progress Report: August 2021 - Reverse Engineering DCP

We'll do the following steps:

• iterate on each DCPAVServiceProxy
• check its Location property to see if it's External
  • This skips the built-in screen of the MacBook or iMac
• create an IOAVService from the proxy
• call IOAVServiceCopyEDID on the IOAVService

edid.m

@import Foundation;
@import IOKit;

typedef CFTypeRef IOAVServiceRef;
extern IOAVServiceRef IOAVServiceCreateWithService(CFAllocatorRef allocator, io_service_t service);
extern IOReturn IOAVServiceCopyEDID(IOAVServiceRef service, CFDataRef* edidData);

int main(int argc, char** argv) {
    io_iterator_t iterator;
    kern_return_t result = IOServiceGetMatchingServices(kIOMasterPortDefault, IOServiceMatching("DCPAVServiceProxy"), &iterator);
    if (result != KERN_SUCCESS) return 1;

    io_service_t service;
    while ((service = IOIteratorNext(iterator)) != IO_OBJECT_NULL) {
        CFStringRef location = IORegistryEntrySearchCFProperty(service, kIOServicePlane, CFSTR("Location"), kCFAllocatorDefault, kIORegistryIterateRecursively);
        if (location == NULL || CFStringCompare(CFSTR("External"), location, 0) != 0) continue;

        IOAVServiceRef avService = IOAVServiceCreateWithService(kCFAllocatorDefault, service);
        if (avService == NULL) continue;

        CFDataRef edidData = NULL;
        IOReturn edidResult = IOAVServiceCopyEDID(avService, &edidData);
        if (edidResult != kIOReturnSuccess || edidData == NULL) continue;

        NSData* nsEdidData = [NSData dataWithBytes:CFDataGetBytePtr(edidData) length:CFDataGetLength(edidData)];
        UInt8 *bytes = nsEdidData.bytes;

        for (int i = 0; i < nsEdidData.length; i++)
            printf("%02X ", bytes[i]);
        printf("\n");
    }
    return 0;
}

We can then compile and run it using the following commands:

clang -fmodules -o edid edid.m

./edid | while read line; do
    echo $line | edid-decode
done

Intel

On Intel Macs, we don't have the convenience of IOAVServiceCopyEDID so we need to craft the I²C request ourselves and send it to the monitor.

Based on the DDC/CI specifications, the request will need to be sent to address 0x50.

But because IOKit needs the least-significant byte (LSB) for other things, we need to use the 0xA0 address which is 0x50 << 1.

We'll do the following steps:

• iterate over NSScreen.screens
• get the internal macOS display ID
• get the monitor framebuffer using CGSServiceForDisplayNumber
• send an IOI2CRequest to the first interface that responds to IOI2CInterfaceOpen

edid.m

@import Cocoa;
@import IOKit.i2c;

extern void CGSServiceForDisplayNumber(CGDirectDisplayID display, io_service_t* service);

bool FramebufferI2CRequest(io_service_t framebuffer, IOI2CRequest* request) {
    IOItemCount busCount;
    if (IOFBGetI2CInterfaceCount(framebuffer, &busCount) != KERN_SUCCESS) return false;

    IOOptionBits bus = 0;
    while (bus < busCount) {
        io_service_t interface;
        if (IOFBCopyI2CInterfaceForBus(framebuffer, bus++, &interface) != KERN_SUCCESS) continue;

        IOI2CConnectRef connect;
        if (IOI2CInterfaceOpen(interface, kNilOptions, &connect) != KERN_SUCCESS) continue;

        if (IOI2CSendRequest(connect, kNilOptions, request) == KERN_SUCCESS) {
            IOI2CInterfaceClose(connect, kNilOptions);
            return true;
        }
    }
    return false;
}

int main(int argc, char** argv) {
    for (NSScreen* screen in NSScreen.screens) {
        CGDirectDisplayID displayID = [[screen.deviceDescription objectForKey:@"NSScreenNumber"] unsignedIntValue];
        if (CGDisplayIsBuiltin(displayID)) continue;

        io_service_t framebuffer = 0;
        CGSServiceForDisplayNumber(displayID, &framebuffer);
        if (framebuffer == 0) return 1;

        IOI2CRequest request = {};
        UInt8 data[256] = {};

        request.sendAddress = 0xA0;
        request.sendTransactionType = kIOI2CSimpleTransactionType;
        request.sendBuffer = (vm_address_t)data;
        request.sendBytes = 0x01;

        data[0] = 0x00;
        request.replyAddress = 0xA1;
        request.replyTransactionType = kIOI2CSimpleTransactionType;
        request.replyBuffer = (vm_address_t)data;
        request.replyBytes = sizeof(data);

        if (!FramebufferI2CRequest(framebuffer, &request)) return 1;

        for (int i = 0; i < 256; ++i) {
            printf("%02X ", data[i]);
        }
        printf("\n");
        return 0;
    }
}

Again, we can read and decode the EDID using the following command:

clang -fmodules -o edid edid.m

./edid | while read line; do
    echo $line | edid-decode
done

Writing EDID to monitors

Not exactly the topic of this note, but wanted to write down my findings for posterity.

Reading the EDID binary from a monitor, editing it and then writing it back to the monitor memory is something that one would rarely need to do.

But there is this annoying practice of monitor vendors that annoys the hell out of a large number of people and it's only fixable by editing EDIDs: they write the same serial number for all their monitors in a batch.

This leads to monitors getting swapped around in a multi monitor setup, and people having to re-arrange them on every reconnection. That's because from the OS side, all monitors look identical and there's no way to know which was left and which was right after they reconnect.

Technically, simply changing one byte of the EDID serial number should fix this. This is how I would do it:

• read the EDID from the monitor
• assign a random byte to EDID[12] (serial number is stored as a 32bit number on bytes 12-16)
• write the EDID back to monitor memory through I²C

And here's the code that should do that:

@import Foundation;
@import IOKit;

typedef CFTypeRef IOAVServiceRef;
extern IOAVServiceRef IOAVServiceCreateWithService(CFAllocatorRef allocator, io_service_t service);
extern IOReturn IOAVServiceCopyEDID(IOAVServiceRef service, CFDataRef* edidData);
extern IOReturn IOAVServiceWriteI2C(IOAVServiceRef service, uint32_t chipAddress, uint32_t dataAddress, void* inputBuffer, uint32_t inputBufferSize);

void edid_decode(NSData *nsEdidData) {
    NSTask* task = [[NSTask alloc] init];
    [task setLaunchPath:@"/usr/local/bin/edid-decode"];
    [task setArguments:@[@"-"]];

    NSPipe* inputPipe = [NSPipe pipe];
    [task setStandardInput:inputPipe];

    [task launch];

    [[inputPipe fileHandleForWriting] writeData:nsEdidData];
    [[inputPipe fileHandleForWriting] closeFile];

    [task waitUntilExit];
}

int main(int argc, char** argv) {
    io_iterator_t iterator;
    kern_return_t result = IOServiceGetMatchingServices(kIOMasterPortDefault, IOServiceMatching("DCPAVServiceProxy"), &iterator);
    if (result != KERN_SUCCESS) return 1;

    io_service_t service;
    while ((service = IOIteratorNext(iterator)) != IO_OBJECT_NULL) {
        CFStringRef location = IORegistryEntrySearchCFProperty(service, kIOServicePlane, CFSTR("Location"), kCFAllocatorDefault, kIORegistryIterateRecursively);
        if (location == NULL || CFStringCompare(CFSTR("External"), location, 0) != 0) continue;

        IOAVServiceRef avService = IOAVServiceCreateWithService(kCFAllocatorDefault, service);
        if (avService == NULL) continue;

        CFDataRef edidData = NULL;
        IOReturn edidResult = IOAVServiceCopyEDID(avService, &edidData);
        if (edidResult != kIOReturnSuccess || edidData == NULL) continue;

        NSMutableData* nsEdidData = [NSMutableData dataWithBytes:CFDataGetBytePtr(edidData) length:CFDataGetLength(edidData)];
        UInt8 *bytes = nsEdidData.mutableBytes;

        printf("Old EDID:\n");
        edid_decode(nsEdidData);

        bytes[12] = arc4random_uniform(256); // Set first serial number byte to a random value
        UInt8 checksum = 0;
        for (int i = 0; i < 127; i++) checksum += bytes[i];
        bytes[127] = 256 - checksum; // Recompute checksum

        printf("\n\nNew EDID:\n");
        edid_decode(nsEdidData);

        char input[10];
        printf("\n\nDo you want to write the new EDID to the monitor? (y/n): ");
        fgets(input, 10, stdin);

        if (strcmp(input, "y\n") != 0) continue;

        printf("\n\nWriting new EDID: ");
        IOReturn err = IOAVServiceWriteI2C(avService, 0x50, 0, bytes, nsEdidData.length);
        if (err) {
            printf("error %s\n", mach_error_string(err));
            return 1;
        }
        printf("OK\n");
    }
    return 0;
}

Provided you have the edid-decode binary in /usr/local/bin/, the code can be run with:

clang -fmodules -o edid-rewrite edid-rewrite.m && ./edid-rewrite

Why it's not a good solution

The problem is that most monitors have write-protected EEPROMs and the write operation will just fail or discard the data.

I tested this on my LG 27UD88-W 4K monitor, and on an older 55" LG TV and neither accepted the EDID rewrite.

Some monitors might have a service menu which has an option for enabling EDID writes, some might only accept the write on a specific port like HDMI1, but most will just ignore the operation.

A bit of background.

When macOS Monterey was announced, Apple added an orange dot indicator that appears on top of everything whenever the microphone is in use.

This has made a lot of people very angry and been widely regarded as a bad move.

Kidding, it was quite a nice privacy addition actually. We could finally see in realtime when an app used the microphone, and what app that is.

But this wasn't something that everyone wanted.

For example, when projecting live visuals on a large screen, you might want to make the screen background black to give the impression of floating effects. That vibrant colored dot in the corner breaks that illusion.

It can also be a distraction for a specific group of people struggling with attention deficit.

Oh, and it also appears in screen recordings, which annoys me as well whenever I want to demo something.

First solution

After news got out, Sydney San Martin posted a command-line implementation in a HackerNews thread called undot which could grab the dot and move it off screen, since it was just a normal window.

And I decided to make an easy to use app for it called YellowDot (in my eyes, it looks yellow ¯\_(ツ)_/¯)

macOS 12.2

Apple took note of this, saw it as a vulnerability, and promptly updated their code to disable this method of hiding the dot.

Indeed, it is a vulnerability. Any app with Accessibility and Microphone Permissions could record audio without your knowledge.

The problem was that there was no way for the user to opt out of this.

A Privacy Indicator toggle that asks for password or biometric authentication could solve this problem for people that want a Mac to be a tool that should work for them as they want.

Second solution

Tyshawn Cormier, another developer annoyed by this, came up with a different solution a few days after macOS 12.2 was released: RecordingIndicatorUtility.

It needed disabling System Integrity Protection (SIP) because it injected code inside the WindowServer and ControlCenter processes. There, it had access to methods that handled the drawing of this privacy indicator, and it could just set its opacity to 0 to hide it.

Quite a clever solution, but a bit too convoluted and apparently risky for most people.

Anyway, with no better idea in hand, I updated the YellowDot page to point people to Tyshawn's app and proceeded to forget about it.

Still no real solution...

After a while I noticed something odd in my Plausible Analytics dashboard:

Even if the app was no longer working, and I wasn't making any noise about it, it was still the second most accessed page on The low-tech guys.

And most traffic was coming from Google. People were constantly looking for a way to hide this dot.

I couldn't stop thinking that maybe there is a way to do this with SIP enabled.

What the dot?

So if it was no longer a simple window, how was this dot drawn on the screen?

Was it drawn on the GPU using Metal? Was it pixels pushed directly into the framebuffer?

No, it was still a damn window.

// WindowInfo.swift
import Foundation
import Cocoa

let info = CGWindowListCopyWindowInfo(.optionOnScreenOnly, kCGNullWindowID)
print(info as! [[String: AnyObject]])



❯ swift WindowInfo.swift

[
    "kCGWindowName": StatusIndicator,
    "kCGWindowOwnerName": Window Server
    "kCGWindowBounds": {
        Height = 16; Width = 8;
        X = 1953; Y = 16;
    },
    "kCGWindowOwnerPID": 403,
    "kCGWindowNumber": 713,
    "kCGWindowMemoryUsage": 2288,
    "kCGWindowStoreType": 1,
    "kCGWindowAlpha": 1,
    "kCGWindowSharingState": 1,
    "kCGWindowLayer": 0,
    "kCGWindowIsOnscreen": 1,
]

But this time, it was a special kind of window. Accessibility APIs could no longer find it, and thus there was no way to move the window around.

Looking for the "StatusIndicator" string inside SkyLight.framework points us to:

int system_status_indicator_get_window(PKGSystemStatusIndicator_t*) {
    // ...
    _WSWindowSetProperty(r20, @"kCGSWindowTitle", @"StatusIndicator");
    // ...
}

Looks like the window is created with an internal method called WSWindowCreate. This creates the window but doesn’t insert it in the CGSLocalWindows hashmap.

This prevents user facing APIs from seeing the window, as they do a CGSWindowGetMapped to fetch the window object, which looks inside that hashmap.

I was wondering if we could call these methods directly. They’re not exported so we can’t link them in Swift, but we can call them directly by address.

system_status_indicator_set_shape looks interesting, it expects a CGRect, a CGPoint and a double. These are most likely the draw region, the origin and the size of the dot.

Let’s see if we can move the dot offscreen by altering the x coordinate. I’m intercepting the method call using Frida and setting the d0 register to 9999999.

Because structures like CGRect are passed by value, d0 corresponds to the first double field of the first non-pointer argument: that is the x coordinate of the drawing region

yellowdot.js

const symbols = Module.enumerateSymbols('SkyLight')
function addr(symname) {
  return ptr(symbols.find((sym) => sym.name == symname).address)
}

const system_status_indicator_set_shape = new NativeFunction(
  addr('_ZL33system_status_indicator_set_shapeP26PKGSystemStatusIndicator_t6CGRect7CGPointd'),
  'int', ['pointer', ['double', 'double', 'double', 'double'], ['double', 'double'], 'double']
)

Interceptor.attach(system_status_indicator_set_shape, {
  onEnter: function (args) {
    console.log(
      `system_status_indicator_set_shape(${args[0]}, rx: ${this.context.d0}, ry: ${this.context.d1}, rw: ${this.context.d2}, rh: ${this.context.d3}, x: ${this.context.d4}, y: ${this.context.d5}, size: ${this.context.d6})`
    )

	// Move the dot offscreen
    this.context.d0 = 9999999
  },
})

Load the script, attach to WindowServer and start an audio recording:

> sudo frida --load yellowdot.js WindowServer

// Dot in ControlCenter icon
system_status_indicator_set_shape(0x600002f28540, rx: 1953, ry: 16, rw: 8, rh: 16, x: 1957, y: 24, size: 3)

// Dot in Full Screen
system_status_indicator_set_shape(0x600002f28540, rx: 0, ry: 0, rw: 0, rh: 0, x: 2010, y: 16, size: 4)

Ok looks promising.

To call the function we would need a pointer to a PKGSystemStatusIndicator struct which we don’t know the layout of. I asked ChatGPT about it and came up with a good enough answer:

Now, how would one call a function by address? Isn’t Address space layout randomization a problem here?

The dyld cache (where SkyLight resides) gets loaded at a random address at startup, but thankfully that stays the same until restart.

We can use _dyld_get_image_vmaddr_slide to get the base memory address of a specific module, then add to that the address of the symbol that we got from disassembling SkyLight.

Then we cast that address to a function using unsafeBitCast and just call it with the right parameters.

yellowdot.swift

import Cocoa
import Foundation
import MachO

func getDotWindowID() -> CGWindowID? {
    let info = CGWindowListCopyWindowInfo(.optionOnScreenOnly, kCGNullWindowID)
    guard let windows = info as? [[String: AnyObject]],
          let window = windows.first(where: { ($0["kCGWindowName"] as? String) == "StatusIndicator" })
    else {
        return nil
    }

    return window["kCGWindowNumber"] as? CGWindowID
}

struct PKGSystemStatusIndicator {
    var windowID: CGWindowID
    var field_78: UInt32
    var field_unk1: UnsafeMutablePointer<UInt64>?
    var field_unk2: UnsafeMutablePointer<Any>?
}

guard let id = getDotWindowID() else {
    exit(1)
}
var pkg = PKGSystemStatusIndicator(windowID: id, field_78: 0, field_unk1: nil, field_unk2: nil)


let libraryName = "/System/Library/PrivateFrameworks/SkyLight.framework/Versions/A/SkyLight"
var slide: Int = 0

let imageCount = _dyld_image_count()
let skyLightIndex = (0 ..< imageCount).first { index in
    _dyld_get_image_name(index) == libraryName
}
guard let skyLightIndex, _dyld_get_image_vmaddr_slide(skyLightIndex) != 0 else {
    print("The \(libraryName) library is not loaded in the dyld cache")
    exit(1)
}

let slide = _dyld_get_image_vmaddr_slide(skyLightIndex)
print("The slide of the \(libraryName) library is 0x\(String(slide, radix: 16))")

typealias SystemStatusIndicatorSetShapeFunction = @convention(c) (UnsafeMutableRawPointer?, CGRect, CGPoint, Double) -> Void
let systemStatusIndicatorSetShape = unsafeBitCast(0x18514d130 + slide, to: SystemStatusIndicatorSetShapeFunction.self)

systemStatusIndicatorSetShape(&pkg, .zero, CGPoint(x: 999999, y: 16), 4)

> swift yellowdot.swift

The slide of the /System/Library/PrivateFrameworks/SkyLight.framework/Versions/A/SkyLight library is 0x1c98c000
fish: Job 1, 'sudo ./yellowdot' terminated by signal SIGSEGV (Address boundary error)

Hmm ok, it’s not so easy.

Debugging this with lldb drops us into WSWindowCreate where we are trying to load something from the 0x0 address. We reach that address because the internal SkyLight code expects to find a data structure filled with windows at a specific address in memory.

Obviously, we don’t have such a thing, that data only exists inside the WindowServer process and we have no access to it.

systemstatusd

The “call by address” idea doesn’t work. But something else jumped out to me when I was trying to find a rogue LaunchDaemon.

/System/Library/LaunchDaemons/com.apple.systemstatusd.plist

This seems to run some kind of server for handling these indicators. What happens if we just disable it?

❯ sudo launchctl bootout system/com.apple.systemstatusd

That worked! Starting an audio recording no longer shows the dot!

It even stops showing the newly added blue location dot when I open the Weather app. Not exactly what I wanted.

But does it work with SIP enabled?

❯ sudo launchctl bootout system/com.apple.systemstatusd
Boot-out failed: 150: Operation not permitted while System Integrity Protection is engaged

❯ sudo killall systemstatusd
killall: warning: kill -term 448: Operation not permitted

❯ sudo rm /System/Library/LaunchDaemons/com.apple.systemstatusd.plist
override rw-r--r-- root/wheel restricted,compressed for /System/Library/LaunchDaemons/com.apple.systemstatusd.plist? y
rm: /System/Library/LaunchDaemons/com.apple.systemstatusd.plist: Operation not permitted

Nope, they thought of everything.

Looks like with SIP enabled, these software rendered colored dots are just as effective as the green hardware-wired webcam LED.

Without a 0-day exploit, an attacker has no way of recording audio or location without you noticing it. But it also means you are stuck with this dot on your screen even when you fully trust the software.

The only solution is still disabling SIP, and using RecordingIndicatorUtility. Looks like Tyshawn just replaced the code injection method with toggling this systemstatusd server instead, so it is more likely to survive macOS updates.

NOTE: This is not a tutorial. If you don't understand this article in detail, please don't attempt to do what's written in it.

On MacBook laptops with a notch, the area above the notch is reserved for the menu bar for most applications. That is good for normal window usage, as the menubar no longer takes precious vertical space that could be used for the content.

Going fullscreen though, only makes that area black (so as to hide the notch) but apps will still render below the notch, leaving about 100k pixels useless.

So here are some instructions on how to fullscreen a window above the notch in the most hackish way possible.

By the way, if you prefer that old MacBook without a notch design, my Lunar app can disable the notch by applying a hidden resolution.

Old-style fullscreen

Every macOS window is actually a NSWindow, and that class has a toggleFullScreen() method.

But what that does is move the window to its own special Mission Control Space and render it fullscreen below the notch. Not what I want.

There's a thing called old-style fullscreen which some apps support natively (Sublime Text, kitty, IINA etc.).

Instead of calling toggleFullScreen(), this method does the following:

• makes the window borderless
• sets up the app to auto-hide the menubar and dock
• sets the window frame equal to the screen frame

Here's how IINA does it for example: iina/MainWindowController.swift · iina/iina · GitHub

The problem is that, while apps can change their own windows as they please, there's no way for an app to change those attributes on windows of other apps.

Injecting code

Using Frida we can inject and run code inside the context of any running process.

We first need to disable SIP though, as code injection is restricted by default for obvious security reasons.

Below we define our Frida script, which we can save in ~/Documents/OverNotch.js for later usage.

OverNotch.js

var NSApplicationPresentationAutoHideMenuBar = 1 << 2
var NSApplicationPresentationAutoHideDock = 1 << 0
var NSWindowStyleMaskBorderless = 0
var NSApplicationPresentationDefault = 0

global.app = ObjC.classes.NSApplication.sharedApplication()

global.arrayFromNSArray = (nsArray) => {
    var jsArray = []
    var count = nsArray.count()
    for (var i = 0; i < count; i++) {
        jsArray[i] = nsArray.objectAtIndex_(i)
    }
    return jsArray
}

global.mainWindow = () => {
    if (global.app.mainWindow()) { return global.app.mainWindow() }
    if (global.app.keyWindow()) { return global.app.keyWindow() }

    var windows = arrayFromNSArray(global.app.windows())
    var index = Math.min(...windows.map((w) => w.orderedIndex()))
    return windows.find((w) => w.orderedIndex() == index)
}

global.w = mainWindow()

global.toggleFullScreen = (windowNum) => {
    if (!windowNum) { windowNum = global.w.windowNumber() }

    var dict = ObjC.classes.NSThread.mainThread().threadDictionary()
    if (dict.valueForKey_(windowNum.toString())) {
        stopFullScreen(windowNum)
    } else {
        makeFullScreen(windowNum)
    }
}

global.stopFullScreen = (windowNum) => {
    Interceptor.revert(app.setPresentationOptions_.implementation)
    ObjC.schedule(ObjC.mainQueue, () => {
        global.app.setPresentationOptions_(NSApplicationPresentationDefault)
    })

    var window = windowNum ? global.app.windowWithWindowNumber_(windowNum) : global.w
    if (!window) {
        return console.log('Window not found')
    }

    ObjC.schedule(ObjC.mainQueue, () => {
        var key = window.windowNumber().toString()
        var dict = ObjC.classes.NSThread.mainThread().threadDictionary()
        if (dict.valueForKey_(key)) {
            window.setStyleMask_(dict.valueForKey_(key).unsignedLongLongValue())
            dict.removeObjectForKey_(key)
        }

        window.setFrameUsingName_(key)
        window.setIsMovable_(true)

        Interceptor.revert(app.setPresentationOptions_.implementation)
    })
}

global.makeFullScreen = (windowNum) => {
    var window = windowNum ? global.app.windowWithWindowNumber_(windowNum) : global.w
    if (!window) {
        return console.log('Window not found')
    }

    ObjC.schedule(ObjC.mainQueue, () => {
        var key = window.windowNumber().toString()
        var dict = ObjC.classes.NSThread.mainThread().threadDictionary()
        var value = ObjC.classes.NSNumber.numberWithUnsignedLongLong_(window.styleMask())
        dict.setValue_forKey_(value, key)
        window.saveFrameUsingName_(key)

        global.app.setPresentationOptions_(NSApplicationPresentationAutoHideDock | NSApplicationPresentationAutoHideMenuBar)
        window.setStyleMask_(NSWindowStyleMaskBorderless)
        window.setFrame_display_(window.screen().frame(), true)
        window.setIsMovable_(false)

        Interceptor.replace(app.setPresentationOptions_.implementation, new NativeCallback((mask) => {}))
    })
}

Then as a test, have a Safari window open, and run the following to make it fullscreen:

sudo frida -q -l ~/Documents/OverNotch.js -e "toggleFullScreen()" Safari

Note that this doesn't work with all windows, and some apps will crash when their window styleMask is changed.

Hotkey

I prefer to bind fn - a to fullscreen the current window using skhd.

I would usually bind rcmd - a as it's a bit easier to press, but since I surrendered the ⌘ Right Command key to my rcmd app switcher, I'm using fn for these system-wide hotkeys.

Here's what I added in ~/.skhdrc to do that:

fn - a  : sudo frida -q -l ~/Documents/OverNotch.js -e "toggleFullScreen()" $(osascript -e 'tell application "System Events" to get unix id of first application process whose frontmost is true')

Why would you need such a thing?

I personally wanted it for having Windows 11 look as natively as possible through Parallels Desktop. I still need it from time to time for hardware that only provides a Windows configuration program.

You can also use it to get an immersive view of specific webpages. Here's NightDrive for example:

Or maybe have a more focused zen-mode on note taking apps. Here's NotePlan in my case:

SIP disabled? How about no?

Frida and other debuggers like lldb and gdb use the task_for_pid API for attaching to a running process.

That doesn't necessarily need SIP being disabled. For task_for_pid to succeed on a process, that process needs to meet one of the following requirements:

• be unsigned
• be signed without Hardened Runtime
• include the com.apple.security.get-task-allow entitlement

Fortunately, we can alter the signature of any non-system app without disabling SIP.

Unfortunately that's not very straightforward because we need to ensure that we sign all the additional bundles inside the app, and we need to take care of not removing existing entitlements.

Because I'm using fish shell, here's how I approach this task:

function resign-bundle -a bundle
    # Dump existing entitlements as a PLIST
    codesign -d --entitlements - --xml "$bundle" >/tmp/entitlements.xml
    if not test -s /tmp/entitlements.xml
        # Sign without Hardened Runtime
        codesign -fs $CODESIGN_CERT "$bundle"
        return
    end

    # Add `get-task-allow` to the entitlements to allow debuggers
    /usr/libexec/PlistBuddy -c "Add :com.apple.security.get-task-allow bool true" /tmp/entitlements.xml
    # Sign with Hardened Runtime and `get-task-allow`
    codesign -fs $CODESIGN_CERT -o runtime --timestamp --entitlements /tmp/entitlements.xml "$bundle"
end

function resign-app -a app
    # Backup existing app
    mkdir -p ~/.cache/resign-app-backups/
    if not test -d "~/.cache/resign-app-backups/$(basename "$app")"
        rsync -avz "$app" ~/.cache/resign-app-backups/
    end

    # Resign bundles inside the app
    fd -uu '\.(app|framework|dylib|xpc|appex)$' "$app" -j 1 -x fish -c 'resign-bundle {}'

    # Resign the app itself
    resign-bundle "$app"
end

Testing this on RealVNC Viewer:

> resign-app "/Applications/VNC Viewer.app"

Executable=/Applications/VNC Viewer.app/Contents/MacOS/vncviewer
/Applications/VNC Viewer.app: replacing existing signature

I also tried testing this on VirtualBuddy but because it has a required entitlement (com.apple.vm.networking) and an embedded provisioning profile tied to the developer certificate, this got too complicated to warrant the effort.

System apps also can't work with this approach because some of them live in immutable volumes called Cryptexes. For example here's where Safari can be found on macOS Ventura:

# Safari lives at /System/Volumes/Preboot/Cryptexes/App/System/Applications/Safari.app

> codesign --remove-signature '/System/Volumes/Preboot/Cryptexes/App/System/Applications/Safari.app'
/System/Volumes/Preboot/Cryptexes/App/System/Applications/Safari.app: internal error in Code Signing subsystem

This is a collection of keyboard and trackpad workflows that I accumulated over the last 7 years of using a MacBook.

Here are some important abbreviations I am using in this article:

Key Sequences

In 6 years of using BetterTouchTool I had no idea this feature existed.

It can map any sequence of keys (even modifiers) to any action.

Sequence: individual keys pressed one after the other, not key combos that you press at the same time

In the below video, I map rcmd then lcmd to the macOS zoom hotkey: ⌘ ⌥ 8

I only have 2 key sequences at the moment:

• rcmd then lcmd → Picture-in-Picture Zoom
• lcmd then rcmd → Superkey Seek

Superkey is the Pro version of Hyperkey, the app that maps CapsLock to the hyper key, made by Ryan Hanson (developer of the popular window management app Rectangle).

The below video is a demonstration of how I use it to quickly find and click on things that I know they're somewhere on the screen, but I would be too slow to notice-point-and-click with my eyes and trackpad.

I'm pressing lcmd then rcmd, typing fip then pressing Enter which clicks on the browser tab with fipple in its title.

You can even hold modifiers while pressing Enter to do the same action that clicking with that modifier would do. In my browser's case I can:

• ^ Enter to right click the tab and show the context menu (for muting or pinning the tab, etc)
• ⌘ Enter to close the tab without trying to click on the tiny X

Double Tap

Raycast added the possibility of mapping a double tap modifier combo to summon it.

I personally mapped ⌥ ⌥ and I like it because it doesn't clash with any other keys while being unique enough to remember.

One thing I noticed though is that it is faster and easier to press lalt then ralt to register a double tap, instead of actually pressing one Option key twice. The reverse direction (right then left) works as well.

One could also use BTT's Key Sequences to map arbitrary double or even triple taps to any action.

For example here I mapped ^ ^ to BTT's GPT action and I use it to convert some ObjC code to Swift:

the ⌘ C and ⌘ V in the video are synthesised by BTT, I'm not copy-pasting anything

One-key app switching

When using more than 3 apps, it becomes annoying to Command Tab Tab Tab... all of the time.

I'd like to switch to exactly the app I need, with a single keypress. Previously I did this by manually assigning rcmd + letter to my most used apps, using Karabiner or BTT.

I finally wrote the rcmd app to do the assigning automatically for me, while also adding nice features like show/hide app by pressing the same letter twice, or launch app if not already running etc.

As a bonus, I was able to implement focusing and opening specific projects, documents or windows of an app using the same method.

I have many projects in my code editor and frequently need to switch between them. And when opening up such a project, I also need to open a terminal tab and cd to the directory of that project.

For some of those I also need to open a specific Sketch or Pixelmator file which contains the graphics of the app or website. And of course, if it's a website, I also need to open the damn webpage in my browser to see how it looks while I develop it.

ლ(╹◡╹ლ)

That's too much work. And way too many things to remember.

And I don't always need all of them at once, I want to be able to open things selectively, so a script that does it all isn't a good choice for me

So I dedicated the ralt key for opening and switching between these projects.

Configuring rcmd to do the window focusing thingie is a bit convoluted because of the App Store sandbox limitations, but if you have many projects to switch between, it's worth it.

To give you the basics on how to do this:

• Install Hammerspoon and the window switching script from rcmd's Switcher menu
• Manually open the project you want to assign (e.g. open a folder in VSCode)
• Press ralt = (or the key before backspace) to show the assignment menu
• Press K and then press the letter you want to bind to that project
• Tell rcmd how it can open that window (usually you'd choose Open a file)

if the ralt hotkeys don't do anything after first installing the script, you might need to restart rcmd and Hammerspoon

Fn key

It always seemed weird to me how we have this Fn key which only interacts with the function row of keys, backspace and arrows and just takes up keyboard space for the rest of the time.

So of course, after running out of keys to bind, I looked for ways to use that key.

I know BTT and Karabiner can use it, but I prefer skhd for its simplicity. I decided to use it mostly for running scripts, and doing window management with yabai.

Starting with skhd is really simple:

• brew install skhd
• brew services start skhd
• Give it the required permissions
• Start adding your hotkeys inside ~/.skhdrc

Simply editing and saving the skhdrc file will hot reload the changes. Much faster than clicking around in the BTT UI.

Here are some interesting hotkeys I use with skhd:

# Edit skhd config
fn + k : code $HOME/.skhdrc

# Easy to use Sleep hotkey
fn - q : pmset sleepnow

# Turn on lights to warm colors
fn - w : shortcuts run "Warm Blend"

# Connect or disconnect Sidecar
fn - s : $HOME/.local/bin/lunar toggle-connection sidecar

# Search selected text on Google
fn - g : skhd -k 'cmd - c'; open "https://www.google.ro/search?q=$(pbpaste)"
# Upload selected file and copy URL to clipboard
fn - f : skhd -k 'cmd + alt - c'; \
       terminal-notifier -title "Uploading file" -message "$(pbpaste)" -ignoreDnD; \
       curl --upload-file "$(pbpaste)" "https://transfer.sh/$(basename $(pbpaste))" | pbcopy; \
       terminal-notifier -title "File uploaded" -message "$(pbpaste)" -ignoreDnD


# --- Things that need SIP disabled ---
()
# Decrease window opacity (more transparent) -- "0x1B" => "minus (-)"
fn - 0x1B : yabai -m window --opacity $(bc -e "$(yabai -m query --windows --window | jq -r '."opacity"') - 0.05")
# Increase window opacity (less transparent) -- "0x18" => "plus (=)",
fn - 0x18 : yabai -m window --opacity $(bc -e "$(yabai -m query --windows --window | jq -r '."opacity"') + 0.05")

# Toggle Picture-in-Picture for the current window
fn - p : yabai -m window --toggle pip

Text expansions

Everyone has these snippets of text that they type often: email address, phone number, specific emojis, URLs etc.

I use Raycast's Snippets feature to quickly type these things by assigning mnemonics to them.

I also map typos I frequently do to their correct words. Examples:

• oyu -> you
• improt -> import
• stirng -> string

Adding a snippet in Raycast is as simple as copying some text, then opening its clipboard manager and pressing ⌘ S.

Here's how I have it configured in case you want to replicate my setup exactly:

Trackpad gestures

I've been working on MacBooks exclusively for the last 6 years, and the Trackpad has always been right there at the center.

It's such a good input device, with multitouch, Force Touch and great OS support. It would be a shame to neglect it.

I'm using BTT to configure all kinds of gestures for it, the below video shows some of my most used ones:

(contains sound)

Remembering key bindings

How do you keep all this in mind??

I get that question often. And the truth is it's becoming harder and harder.

I cope by dedicating modifiers to sets of actions and by always looking at the places where these key bindings are configured when I need them.

Very often I forget where a hotkey was defined.

FuzzyKey

About a year ago, I started writing FuzzyKey, a fuzzy search Spotlight-like UI for all types of hotkeys. There are multiple apps doing similar things, but I wanted to take things further.

The defining features would have been:

• Parsers and ingesters for user defined hotkeys in most common apps
  • (e.g. keeping an always up-to-date database of hotkeys from skhdrc, keybindings.json etc.)
  • this could be extensible by users who want to write their own parsers
• Really good fuzzy search that surfaces the keys most likely to be forgotten
• Easily edit a key binding without having to remember where it's defined

After a few months, me and 2 friends wrote the parser architecture, the key bindings change watchers, a bit of UI, a bit of CLI, and the following parsers:

• Shells: Bash, ZSH, Fish
• Browsers: Chrome (for extension hotkeys)
• Terminals: iTerm, Kitty
• Code Editors: Sublime Text, VSCode, XCode, JetBrains
• Menubar (basically what CheatSheet does)
• skhd

But there was so much more work to do, and some parsers were already getting compatibility issues from app updates, that we paused working on it.

I gained a lot more experience in macOS app dev, so I'm hoping to revisit this idea soon.

I'm also secretly hoping to start crafting wood flutes and composing music so that I don't have a need for remembering any hotkeys anymore.

Here's my first Romanian Kaval ^_^

I have a few websites that I need to use often on my iPhone. I want to have them as PWA (Progressive Web Apps) so I can use them as if they were native apps.

This helps by making those sites readily available in the App Switcher, on the home screen and in Spotlight Search. It also gives me a bit more screen real estate by hiding the browser UI.

Websites can be installed as PWA if they provide a manifest in the form of:

<link rel="manifest" href="manifest.json">

This manifest file contains metadata about the app, like the name, icons, theme color, etc.

The websites I use don't provide this manifest file, so I found a way to add it myself.

I use a Safari extension called Modificator to add the manifest file to the HTML and a simple API that I cooked for generating arbitrary manifest files.

The API supports almost all the manifest properties and can be used as such:

curl 'https://api.lowtechguys.com/manif?name=Sentry'

{
    "name": "Sentry",
    "short_name": "Sentry",
    "display": "standalone",
    "orientation": "portrait"
}

Sentry

Here I'll demonstrate adding a Sentry error reporting dashboard as an app on the home screen.

In the Modificator app, I needed to add a JS modificator as such:

document.head.innerHTML += "<link rel=manifest href=https://api.lowtechguys.com/manif?name=Sentry>"

Looks like the Modificator app doesn't properly escape single quotes so I needed to make sure I don't use them at all.

Then I went on the Sentry website, adjusted the zoom to 75% to allow more content to be visible, pressed the Share button at the bottom and tapped Add to Home Screen.

The app looks like this on the home screen:

And this is how it looks on an iPhone 12 mini:

A more complex example

In the case of Sentry, we were helped by the fact that the site defines a good quality icon and a theme color in its head

<link rel="apple-touch-icon" href="https://s1.sentry-cdn.com/_static/c1d4f32cdd3bcf7e5d26c2cbf4f29f2f/sentry/images/logos/apple-touch-icon.png">
<meta name="theme-color" content="#2f1937">

We would need to add a few more parameters to the API call for websites that don't have those properties defined.

As an example, I'll add the FAQ website of my adaptive brightness app, Lunar. I have to reference it often when responding to support emails.

The modificator JS will be the following:

document.head.innerHTML += "<meta name=mobile-web-app-capable content=yes>" +
    "<link rel=manifest href=https://api.lowtechguys.com/manif?name=Lunar+FAQ&start_url=https%3A%2F%2Flunar.fyi%2Ffaq&icon=https%3A%2F%2Ffiles.lunar.fyi%2Flunar-icon-maskable.png>"

Here's what we're doing this time, exemplified with a curl command:

curl -G 'https://api.lowtechguys.com/manif' \
    --data-urlencode name='Lunar FAQ' \
    --data-urlencode color=#161125 \
    --data-urlencode icon=https://files.lunar.fyi/lunar-icon-maskable.png

{
    "name": "Lunar FAQ",
    "short_name": "Lunar FAQ",
    "display": "standalone",
    "orientation": "portrait",
    "icons": [
        {
            "src": "https://files.lunar.fyi/lunar-icon-maskable.png",
            "purpose": "any maskable"
        }
    ],
    "theme_color": "#161125",
    "background_color": "#161125"
}

Showcase

Caveats

The method doesn't work on websites with a more restrictive Content Security Policy because the manifest has to be fetched from an external host (api.lowtechguys.com in this case).

If the CSP is sent as a header, there's nothing you can do in JS to make that policy less restrictive.

For example, I wanted to add the Marginalia search engine on the home screen in this manner, but because of its default-src https://*.marginalia.nu policy, this doesn't work.

I was determined enough to do this, so I used Proxyman to alter the Marginalia CSP header, just enough to trick Safari into allowing the manifest URL. After adding the app on the home screen, it keeps working without any CSP alteration needed.

Statusbar

By default, the status bar will take the color of the theme-color meta value.

If that doesn't exist, the status bar will be black with white text, which doesn't look too immersive on most apps.

You can make the status bar transparent so that it takes the background of the website using the following meta element:

<meta name=apple-mobile-web-app-status-bar-style content=black-translucent>

Note that if the website background is light, you'll still have white text in the status bar, which will be hard to read.

Normally apps crash because of bugs introduced by the developer, but in my experience, there are cases where crashes can be out of the developer’s control.

For example the app might work with hardware closely, and the expectations the system has on that hardware are not met when a power or connection cord is yanked out (or if there’s any electromagnetic interference caused by your IKEA chair)

Or maybe the app works with a network shared disk which disconnects abruptly in the middle of busy I/O, or a rogue driver changes the hardware tree while the app is traversing it, or God forbid, there is a kernel bug.

In all those cases, the crash is just a nuisance for the end user as they now have to relaunch the app. The crash report is also of no use to the developer, and mostly serves as a time consuming confusion.

After we reach a certain confidence in the app stability, we can explore some ways to have the app restart automatically when the inevitable crash happens.

The launchd way

com.example.MyApp.restartOnCrash.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>KeepAlive</key>
        <dict>
            <key>Crashed</key>
            <true/>
        </dict>

        <key>Label</key>
        <string>com.example.MyApp.restartOnCrash</string>

        <key>ProgramArguments</key>
        <array>
            <string>/usr/bin/open</string>
            <string>-W</string>
            <string>/Applications/MyApp.app</string>
        </array>
    </dict>
</plist>