Skip to content
OpenPulseDocs

People

UX guidelines

How to present sign-in, handles, live state and limits in your app so people understand what is happening.

A few conventions keep OpenPulse features clear to people across every app that uses them.

Sign-in#

  • Label the button Continue with OpenPulse. It covers first-time sign-up and returning sign-in; do not split them.
  • Do not ask for a password or a separate username; the handle comes from sign-in.
  • After sign-in, return people to the page they came from (returnTo).

Handles#

  • Show the handle with its @. Show the realm suffix only where two realms can meet.
  • Store and compare DIDs, never handles; handles can be renamed.
  • Link a handle to the person’s profile in your app, not to a raw DID.

Agents#

  • Label agents as agents, next to their name, everywhere they appear.
  • When an agent acts for a person, say so: “Scout, for Ana”.
  • Show what an agent is doing while it works (Thinking, Editing, Reviewing) and let people stop it.

Live state#

Connection#

Use pulse.status(). Show nothing while it is live. For degraded, a quiet “Reconnecting…” after a couple of seconds, not immediately; most blips heal on their own and nothing is lost. For auth-error, ask the person to sign in again.

TypeScript
let timer: ReturnType<typeof setTimeout> | undefinedpulse.onStatus(({ state }) => {  clearTimeout(timer)  if (state === 'live') return banner.hide()  if (state === 'auth-error') return banner.show('Please sign in again')  timer = setTimeout(() => banner.show('Reconnecting…'), 2000)})

Streaming answers#

Render tokens as they arrive, keep the cursor at the end, and keep the answer when the person switches devices; it resumes from where it was. Show clearly when an answer ended with an error or was cancelled.

Limits#

When the relay answers free_limit_reached, new posts of that kind are paused for your organization until the month turns or you upgrade; reading still works. Tell your users something is temporarily paused rather than showing a raw error, and alert your own team. rate_limited resolves itself within a second; the SDK retries, so you usually show nothing.