Performance and battery
Atsurae is built to run all day, often on battery. Widgets were designed to cost almost nothing, and yours will too if you follow a few rules.
How widgets are drawn
Section titled “How widgets are drawn”Widgets aren’t web pages. Each element becomes a macOS Core Animation layer: text layers, image layers and shape layers in one transparent window. macOS keeps them on screen without Atsurae doing anything. Atsurae touches a layer only when its content changes.
What that means in practice:
- A clock that shows minutes redraws once a minute.
- Text that never changes is drawn once.
- There’s no animation loop. Nothing runs between updates.
We measured Atsurae with its window closed, playing a 4K video wallpaper:
| Widgets on | Memory | CPU |
|---|---|---|
| none | ~29 MB | ~2.3% (the video) |
| Day, Date and Time | ~34 MB | no measurable change |
| Greeting and World Clock (both scripted), plus Now Playing Bar | ~37 MB | ~2.6–2.8% |
What costs more
Section titled “What costs more”| Thing | Cost | Advice |
|---|---|---|
| Showing seconds | A redraw every second | Show seconds only if they matter |
updateEvery: "second" |
A script run every second | Use "minute" or a number of seconds when you can |
| A script at all | A few MB for the JavaScript engine, shared by all scripted widgets, plus a little per widget | Use tokens when they can do the job |
| Large images | Memory for the decoded image | Atsurae scales images to their drawn size, but keep files reasonable |
| Many elements | One layer each | Dozens are fine; hundreds aren’t needed |
| CPU and memory tokens | A sample every 5 seconds | Fine; it’s a cheap system call |
Weather refreshes every 30 minutes and only while a widget shows it.
Script rules of thumb
Section titled “Script rules of thumb”- Do the least work per run. Compute what changed; don’t rebuild large tables every time.
- Keep state in globals if it’s expensive to compute. Globals persist between runs until the widget’s files change.
- Don’t loop to wait. There are no timers; use
updateEvery. - Stay well under the time limit. Each run gets 0.25 seconds. A typical
updatetakes well under a millisecond.
Scripts run on a background thread, so even a slow script never makes the desktop or the app stutter.
When widgets are off
Section titled “When widgets are off”With no widget turned on, Atsurae has no widget window, runs no scripts, and starts no data sources. Watching your widgets folder for changes costs nothing until a file changes.
