Skip to content
AtsuraeDownload

Development sign-in

Only on a local server with DEV_AUTH. Enter any account name.

Script API

widget.json names the file:

"script": { "file": "script.js", "updateEvery": "minute" }

The file is plain JavaScript (no modules). It’s evaluated once when the widget loads, then Atsurae calls its update function on the schedule.

function update(context) {
return { name: value, ... };
}
  • Required. A script without a global function named update shows The script has no update(context) function.
  • Synchronous. It must return an object, not a Promise. async functions don’t work.
  • Called with one argument, context.
updateEvery Runs
"minute" (default) just after each minute begins
"second" every second
number every that many seconds (minimum 1)

Also: right after loading, and whenever the battery, the playing track or the weather changes. Not while the displays sleep. One run at a time; if a run is still going, the next is skipped.

Field Type Description
now Date The current date and time
options object of strings This placement’s option values, by key. Toggles are "true"/"false".
screen.width number Main display width, in points
screen.height number Main display height, in points
battery.present boolean Whether the Mac has a battery
battery.level number or null 0–1
battery.charging boolean
cpu.level number or null 0–1, all cores. null until the first sample.
memory.used number or null Bytes used (Activity Monitor’s Memory Used)
memory.total number Bytes installed
memory.level number or null used / total
track.title string The playing song, or ""
track.artist string Its artist, or ""
track.playing boolean Whether a song is playing
weather object or null null until weather loads or when it isn’t available
weather.temperature number In weather.unit
weather.feelsLike number
weather.high number Today’s high
weather.low number Today’s low
weather.unit string "°C" or "°F", following the Mac’s settings
weather.condition string e.g. "Partly Cloudy"
weather.humidity number 0–1
weather.location string The city name

context is a fresh copy on every call. Changing it has no effect.

A plain object (not an array). Each property becomes {script.<name>}:

Value Becomes
string itself
number written with up to 10 significant digits, e.g. 0.4375, 42, 1e+21
boolean "true" / "false"
null / undefined ""
array or object JSON

Any other result (nothing, a number, an array) shows update() must return an object, like { greeting: "Hi" }.

Values replace the previous run’s values entirely.

Top-level variables persist between calls while the widget is loaded. Everything resets when the widget’s files change, the widget is turned off, or Atsurae restarts.

Method Output
console.log(...) normal line
console.info(...) normal line
console.warn(...) normal line
console.error(...) red line

Arguments are joined with spaces; non-strings are written as JSON. The last 200 lines per widget are kept, shown in Problems & Console.

JavaScriptCore (the engine in Safari) with the full standard library: Object, Array, String, Number, Math, Date, JSON, RegExp, Map, Set, WeakMap, Symbol, Promise (but update must return synchronously), typed arrays, and Intl (DateTimeFormat, NumberFormat, RelativeTimeFormat, PluralRules, Collator, …) with time zone support.

Missing Why / instead
fetch, XMLHttpRequest, WebSocket no network access
require, import one self-contained file
setTimeout, setInterval use updateEvery
window, document, DOM widgets aren’t web pages
files, storage, localStorage no access to the Mac; use globals for state
Limit Value When exceeded
Time per run (including loading) 0.25 s stopped: The script took too long (over 0.25 seconds) and was stopped.
Console history 200 lines per widget oldest lines dropped

After any error, the script doesn’t run again until its widget’s files change.

Message Meaning
Script error: … An exception, with its message and line number
The script has no update(context) function. No global update
update() must return an object, like { greeting: "Hi" }. Wrong return value
The script took too long (over 0.25 seconds) and was stopped. Too slow, or an endless loop
The script “script.js” isn’t in the widget’s folder. file doesn’t exist
A widget with a script must be a folder (.atsuraewidget) with the script inside. The widget is a single .json file