API Reference

All functions are available under the global Gurasuraisu object.

Notifications & Dialogs

These functions allow your app to display messages to the user using Polygol's native UI.

Gurasuraisu.showPopup(message)

Shows a simple, non-blocking "toast" notification at the bottom of the screen that disappears automatically.

• message (string, required): The text to display.

Example:

Gurasuraisu.showPopup('Your settings have been saved.');

Gurasuraisu.showNotification(message, [options])

Shows a more prominent notification that also appears in the notification shade.

• message (string, required): The main text of the notification.

• options (object, optional): Configuration for the notification.

  • icon (string): The name of a Material Symbols icon to display.

  • buttonText (string): Text for an action button.

  • buttonAction: Note: This is handled internally by Polygol and cannot be a callback from the Gurapp.

Example:

Gurasuraisu.showNotification('Update complete!', { icon: 'check_circle' });

Gurasuraisu.showAlert(message, [title])

Displays a modal alert dialog that the user must dismiss.

• message (string, required): The body text of the alert.

• title (string, optional): The title of the alert dialog. Defaults to 'Alert'.

Example:

Gurasuraisu.showAlert('Please fill in all required fields.', 'Input Error');

async Gurasuraisu.showConfirm(message, [title])

Displays a modal confirmation dialog with "Yes" and "No" buttons. This function returns a Promise.

• Returns: A Promise that resolves to true if the user clicks "Yes", and false if they click "No" or close the dialog.

Example:

async function deleteItem() {
    const confirmed = await Gurasuraisu.showConfirm('Are you sure you want to delete this file?');
    if (confirmed) {
        // ... proceed with deletion
        Gurasuraisu.showPopup('File deleted.');
    }
}

async Gurasuraisu.showPrompt(message, [title], [defaultValue])

Displays a modal dialog with a text input field. This function returns a Promise.

• Returns: A Promise that resolves to the string value entered by the user, or null if the user cancels.

Example:

async function renameFile() {
    const newName = await Gurasuraisu.showPrompt('Enter a new name for the file:', 'Rename', 'MyDocument.txt');
    if (newName !== null) {
        // ... proceed with renaming logic
        console.log('New file name:', newName);
    }
}

App & Window Management

Gurasuraisu.minimize()

Requests Polygol to minimize the current Gurapp.

Gurasuraisu.openApp(url)

Requests Polygol to open another installed Gurapp.

• url (string, required): The root-relative URL of the app to open (e.g., /chronos/index.html).

Gurasuraisu.blackout()

Turns the screen black (enters sleep/privacy mode).

Live Activities

Live Activities are persistent notifications that can display real-time information from your app.

Gurasuraisu.liveActivity.start(options)

Starts a new Live Activity.

• options (object, required):

  • activityId (string): A unique ID for this activity within your app.

  • url (string): The URL of the HTML page for the activity's content.

  • homescreen (boolean, optional): If true, allows the activity to push a summary to the homescreen widget. Defaults to false.

  • height (string, optional): The desired height of the activity in the notification shade (e.g., '120px').

Example:

Gurasuraisu.liveActivity.start({
    activityId: 'stopwatch-123',
    url: '/stopwatch/activity.html',
    homescreen: true,
    height: '80px'
});

Gurasuraisu.liveActivity.update(activityId, data)

Pushes new data to a running Live Activity's iframe. The iframe should have a 'message' event listener to receive it.

• activityId (string, required): The ID of the activity to update.

• data (object, required): The data payload to send.

In the main app:

Gurasuraisu.liveActivity.update('stopwatch-123', { time: '01:23.45' });

In activity.html:

window.addEventListener('message', (event) => {
    if (event.data.type === 'live-activity-update') {
        document.getElementById('timer').textContent = event.data.time;
    }
});

Gurasuraisu.liveActivity.pushHomescreenUpdate(data)

(For use inside an activity iframe only). Pushes a summary to the homescreen widget if homescreen: true was set.

• data (object, required):

  • icon (string): A Material Symbols icon name.

  • text (string): The text to display.

In activity.html:

Gurasuraisu.liveActivity.pushHomescreenUpdate({
    icon: 'timer',
    text: '1:23'
});

Gurasuraisu.liveActivity.stop(activityId)

Stops and removes a Live Activity.

Gurasuraisu.liveActivity.isActive(activityId)

Checks locally if an activity with the given ID was started by the current app instance. Returns true or false.

Media Playback

Integrate your media app with Polygol's system-wide media controls.

Gurasuraisu.registerMediaSession(metadata, [supportedActions])

Registers a new media session, showing the media widget in the Polygol UI.

• metadata (object, required):

  • title (string)

  • artist (string)

  • artwork (array): An array of objects, e.g., [{ src: 'url/to/image.png' }].

• supportedActions (array, optional): A string array of actions your app supports. Valid actions are: 'playPause', 'next', 'prev'. Defaults to ['playPause'].

Gurasuraisu.updatePlaybackState(state)

Updates the playback state (e.g., playing/paused) in the media widget.

• state (object, required):

  • playbackState (string): Must be either 'playing' or 'paused'.

  • metadata (object, optional): New metadata object if the track has changed.

Gurasuraisu.updateMediaProgress(progressState)

Updates the progress bar in the media widget.

• progressState (object, required):

  • currentTime (number): The current playback time in seconds.

  • duration (number): The total duration of the track in seconds.

Gurasuraisu.onMediaControl(actions)

Listens for media control commands sent from Polygol (e.g., when the user taps the play button in the control center).

• actions (object, required): An object where keys are action names and values are callback functions.

Example:

const audio = document.querySelector('audio');

Gurasuraisu.onMediaControl({
    playPause: () => {
        if (audio.paused) {
            audio.play();
        } else {
            audio.pause();
        }
    },
    next: () => {
        playNextTrack();
    },
    prev: () => {
        playPreviousTrack();
    }
});

Gurasuraisu.clearMediaSession()

Clears the current media session for your app and hides the widget (if your app was the active one).

Widgets

Register widgets that users can add to their homescreen.

Gurasuraisu.registerWidget(widgetData)

Registers a widget with Polygol. This should be called once when your app loads for each widget it provides.

• widgetData (object, required): An object describing the widget.

  • appName (string): The name of your app.

  • widgetId (string): A unique ID for the widget within your app (e.g., 'weather-forecast').

  • title (string): A user-friendly title (e.g., '5-Day Forecast').

  • url (string): The URL of the widget's content page.

  • defaultSize (array): The default [width, height] in grid units (e.g., [2, 1]).

  • openUrl (string, optional): The URL to open when the widget is tapped. Defaults to your app's main URL.

File Handling

Gurasuraisu.downloadFile(filename, dataUrl)

Asks Polygol to trigger a file download for the user.

• filename (string, required): The desired name of the file (e.g., 'backup.json').

• dataUrl (string, required): The content of the file encoded as a Data URL.

Privileged Functions

The following functions require special permissions and are generally only available to system apps like the "App Store" or "Terminal". Calling them from a standard Gurapp will have no effect.

• Gurasuraisu.installApp(appObject)

• Gurasuraisu.deleteApp(appObject)

• Gurasuraisu.requestInstalledApps()

• Gurasuraisu.getLocalStorageItem(key)

• Gurasuraisu.setLocalStorageItem(key, value)

• Gurasuraisu.setSettingValue(key, value)

• And all list..., remove..., clear... functions related to localStorage and IndexedDB.