Build

Lifecycle

What happens between the shell creating a frame and your app's first paint, and how the connection ends.

Connect, then render, then ready

TypeScript
1import { os } from '@doan-labs/duo-sdk'
2
3await os.connect() // hello → welcome → ack; resolves with os.view, os.owner, os.session filled
4createRoot(document.body).render(<App />)
5requestAnimationFrame(() => os.ready()) // after the first frame painted

connect() posts hello to the shell with the protocol version, the SDK version and the single-use nonce the frame received as window.name, retrying every second. The shell answers welcome with the view, the session and a transferred MessagePort, or refused when the SDK version is incompatible, the protocol is wrong or the frame is blocked. Every later message rides the port.

Call connect() once, before rendering. Calling it again returns the same promise. ready() tells the shell the first frame is on glass so it can drop its launch cover; until then the person sees your icon.

What welcome carries

os.viewThe display this document is on. See Displays and the fold.
os.owner{ epoch } when this view is the designated owner of effects, otherwise null.
os.session.argThe argument another app or a link opened you with, if any. os.session.onArg fires when it changes.
os.session.migration{ from } when the owner should migrate data written by an earlier version.
os.storage.limitsThe limits below.

Requests and errors

Every SDK method is a request over the port with an id. Requests are answered in order, and a mutation is acknowledged only after the shell's database transaction completed. A request that gets no answer in five seconds is retried once with the same id, so the shell can deduplicate; if that also times out the promise rejects with E_TIMEOUT. A timeout does not prove a write failed: read back before writing again.

Failures reject with PlatformError, whose code is one of:

CodeMeaning
E_ARGSBad key, oversized value, too many requests in flight.
E_QUOTAStorage or command quota exhausted.
E_RATERate limit; back off.
E_DENIEDA permission the manifest does not declare.
E_STALEAn owner-only call from a view that is no longer the owner.
E_TIMEOUTNo answer after the retry.
E_CLOSED, E_GONEThe view was revoked or the app removed.
E_PROTOCOLMalformed traffic; the shell closes the view.
E_STORAGEThe database failed.

Limits

Key128 bytes, printable characters
Value256 KiB, strings only
Keys per app4096
Persistent storage5 MiB per app
Session storage64 KiB per session
Command payload16 KiB; 32 commands waiting
Requests in flight64; 200 per second sustained, 400 burst
Message envelope300 KiB

Ending

The shell sends bye with a reason (closed, uninstalled, updating, error, revoked) and closes the port. Pending promises reject with E_CLOSED. There is no hook to run code afterwards: anything that must survive lives in storage before it happens. A frame that throws an uncaught error reports it to the shell; Escape pressed inside the frame is forwarded and takes the person home.

Edit this page on GitHub