Script API
The script file
Section titled “The script file”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.
update(context)
Section titled “update(context)”function update(context) { return { name: value, ... };}- Required. A script without a global function named
updateshows The script has no update(context) function. - Synchronous. It must return an object, not a Promise.
asyncfunctions don’t work. - Called with one argument,
context.
Schedule
Section titled “Schedule”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.
context
Section titled “context”| 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.
Return value
Section titled “Return value”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.
Global state
Section titled “Global state”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.
console
Section titled “console”| 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.
Available JavaScript
Section titled “Available JavaScript”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.
Not available
Section titled “Not available”| 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 |
Limits
Section titled “Limits”| 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.
Errors
Section titled “Errors”| 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 |
