Solel//dev docs

How it works

You don't need this page to use . It's for when you want to know what happens underneath, or to talk to the desktop without the SDK.

Saying hello

The desktop loads your app in a sandboxed frame. When you call ready():

  1. The SDK sends a hello to the frame's parent, the desktop, with postMessage: { protocol: 'solel.app', version: 1, type: 'hello' }.
  2. The desktop checks the message came from your app's frame, and for an app on its own https address, from that address.
  3. It answers with a welcome, { protocol, version, type: 'welcome', context }, carrying the AppContext and a MessagePort in event.ports[0].
  4. Everything after that goes over the port.

Because the conversation moves to the port, a page the frame goes to later can't pick it up. A new page says hello again and gets a new port, and anything the old page was recording stops.

Messages

Requests that expect an answer carry an id, and the desktop answers with { type: 'result', id, ok: true, value } or { type: 'result', id, ok: false, error }.

From your app to the desktop:

type What it does
title Sets the window's title, from title
notify Sends a notification, from note. Has an id
open-app Opens another app by its manifest id, app, at path
close Closes the window
record, record-stop Starts and stops recording. Both have an id; the result of record-stop holds the audio and its type
record-cancel Stops recording and throws it away
sols-device Reads, or with change changes, how Sols behave on this device. Has an id
sols-changed Says a Sol changed
key A desktop shortcut pressed inside the app, by its key code

From the desktop to your app:

type What it says
result The answer to a request
theme The person's theme changed
layout The layout changed
open Open this path, from a notification link or another app
sols-device How Sols behave on this device changed, for an app with sols.manage

Who checks what

  • The desktop checks the microphone and sols.manage grants itself before recording or touching how Sols behave. It still understands gens-device and gens-changed from apps built with an older SDK.
  • The core checks notify: the desktop sends the note to POST /api/apps/{install}/notify as the person signed in, and the core refuses it without the grant, or past the app's limit.
  • Shortcuts. Keys pressed in a frame never reach the desktop, so the SDK passes on Ctrl Alt shortcuts, such as Ctrl Alt W to close the window, as key messages. AltGr, which arrives as Ctrl Alt on Windows, is left alone.

Using the protocol yourself

@solel-io/sdk/protocol has the message types and the helpers the desktop itself uses: PROTOCOL, PROTOCOL_VERSION, hello(), welcome(context), isHello() and isWelcome(). Where the frame loads from, and what it may do, is in The app frame.