init (the init promise)

The init promise of the Dashlet handle: the single point at which the dashlet knows which environment it is in and what the host told it about selection, session, and user.

1. Signature

readonly init: Promise<InitContext>;

It is created when the dashlet is installed and never changes. It resolves to the normalized InitContext in every environment — the environment only changes how the promise settles, not what it settles to.

2. Guarantees

  • Resolves exactly once. The state machine settles from detecting a single time; later init events (dashboard switch-back, rich-client callbacks) are re-emitted through onInit/onUpdate, not through the promise.

  • Never rejects. There is no reject path on the promise — the standalone degraded state is an observable fallback, not an error (Standalone operation).

  • Bounded. It cannot hang: the detection cap (detectionTimeoutMs, default 5000 ms) settles it as standalone, and a safety-net timeout (`detectionTimeoutMs + 250 ms) wraps the detection itself.

3. How it settles per environment

Environment Settle event source of the settled emission

webclient

The first onInit accepted by origin validation (the host-declared client type rich_client routes it to the rich-client settle instead)

webclientEvent

rich client

Either the bridge read (self-initialization when window.osClient appears) or the first osDashletInit host callback — whichever comes first

richClientSelfInit or richClientCallback

standalone

The detection cap elapsed with no bridge and no accepted event — or the dashlet was destroyed while still detecting (destroy settles it as standalone first)

standalone

The settle fires all onInit listeners with the same context and the corresponding InitSource; the promise resolution happens exactly on the first settle.

4. Examples

const dashlet = installDashletGlobal({});

dashlet.init.then((ctx) => {
    // ctx: InitContext — identical shape in all three environments
    console.log(ctx.environment); // 'webclient' | 'richClient' | 'standalone'
    render(ctx);
});

// or
const ctx = await dashlet.init;

See Quickstart for the full minimal dashlet.