Skip to content

Commit e8eabdc

Browse files
klopez4212Terp
andcommitted
Streamline onboarding recovery and automatic backup
Apply Matt's onboarding feedback: automatic Builderlab backup with retry, direct restore completion, existing-profile preservation, and forward-only completion after admission. Refine onboarding copy and document the flows. Co-authored-by: Terp <5856f6900e8e0a4e0ea1f4f8d2ee33e4753d2119bc122f94ecafc660b46c0511@buzz.block.builderlab.xyz> Signed-off-by: klopez4212 <[email protected]>
1 parent e1d9a16 commit e8eabdc

16 files changed

Lines changed: 441 additions & 440 deletions

‎docs/buzz-help.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,20 +18,22 @@ the interface unless an available tool actually supports that action.
1818
## Identity and getting connected
1919

2020
- Buzz uses a key-based identity. On first launch, the welcome screen offers
21-
**Sign in with email**. **Other options** reveals a **Community URL** field
21+
**Sign in with Builderlab**. **Other options** reveals a **Community URL** field
2222
for an address or invite link; desktop does not offer QR scanning.
2323
With no communities yet, **Join** advances through full-page access and profile
24-
steps. **Back** returns to the entered link. An invite-code field appears for
24+
steps. Before joining, **Back** returns to the entered link; after admission,
25+
profile setup continues forward. An invite-code field appears for
2526
a supplied invite or denied access on a community that enforces membership;
2627
community policy links open separately.
2728
On Mac, the welcome entrance plays once per app storage profile; Reduce Motion
2829
skips it, and pressing a key finishes it immediately.
2930
The key-import field masks your key. Use the eye inside the field to reveal
3031
or hide it. Check the signed-in email before creating a key.
3132
Setup then creates a new key or takes an existing private key, and may link
32-
it to the signed-in account. **Back it up** explicitly enables online backup;
33-
**Not now** continues with automatic backup disabled. A name is required to
34-
finish joining a community; an avatar is optional. A returning account may restore
33+
it to the signed-in account. Builderlab setup backs the key up automatically;
34+
if backup fails, retry to complete setup. Independent-community key imports
35+
without Builderlab sign-in do not upload a backup. Existing community profiles
36+
are preserved and skip setup. A new profile needs a name; an avatar is optional. A returning account may restore
3537
its backed-up key where the build and account allow it. If the older Buzz app
3638
was used on this computer, a **Continue with your Buzz identity?** dialog
3739
brings that identity over without signing in; **Not now** keeps the welcome

‎docs/communities.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -471,3 +471,9 @@ while keeping the local name unchanged. No remote membership, profile, or policy
471471
acceptance is created by this fixture. Live validation with an authorized identity can restore existing profiles and
472472
read selected communities without posting test messages. The fixture itself is
473473
not evidence of live access; see [manual fixture setup](contributing.md#manual-browser-fixtures).
474+
475+
First-run profile setup preserves an existing relay profile, including one without
476+
a display name, and skips editing it. When restoring multiple saved communities
477+
without a requested destination, Buzz prefers one with an existing profile. After
478+
admission, new-profile setup offers Continue without a Back action: returning to
479+
selection would not undo the membership already granted by the community.

‎docs/identity.md‎

Lines changed: 35 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Native macOS, Windows and Linux without the live development broker open on a
44
welcome screen when no human key exists on this device: **Buzz** — "Your people,
5-
your agents, your projects — all in one place." — with **Sign in with email**
5+
your agents, your projects — all in one place." — with **Sign in with Builderlab**
66
(the label the Buzz mobile client uses; first-run copy never names the sign-in
77
provider) and a live **Community URL** field with **Continue** beside it (the
88
same field and normalisation as Join a community below). Sign in runs the
@@ -17,7 +17,7 @@ heading unless the page focuses a field itself, and **Back** returns focus to
1717
the choice that opened the page.
1818

1919
Federated-identity builds (`BUZZ_BUILD_FEDERATED_IDENTITY_CONFIG`) do not yet
20-
support this flow. **Sign in with email** runs under the bundled Builderlab
20+
support this flow. **Sign in with Builderlab** runs under the bundled Builderlab
2121
plugin's own network grant, which an FI build does not have (its Builderlab
2222
calls go through the native FI session; #1461), so sign-in fails with
2323
*Couldn’t sign in* after the browser step. FI builds need their own first-run
@@ -45,7 +45,7 @@ another Builderlab deployment, and every community in a build whose
4545
`BUZZ_BUILDERLAB_URL` is another origin or empty, pauses on **Connect to
4646
{host}**: nothing a relay publishes names its sign-in portal, so the user
4747
chooses. The page says only that Buzz relies on a key for the user's identity; its choices are
48-
**Sign in with email**, which signs in at `BUZZ_BUILDERLAB_URL` and
48+
**Sign in with Builderlab**, which signs in at `BUZZ_BUILDERLAB_URL` and
4949
continues exactly as the welcome screen's own button does (the landing shows
5050
the sign-in pending with the address held; the key it creates is linked to that
5151
account and backed up there), and setup then lands on **Join Community** for
@@ -85,30 +85,30 @@ where the backup step can run (see
8585
[automatic backup](#automatic-backup-and-optional-recovery)); kgoose answers
8686
`404` wherever backups are not configured. Not sent, a `404` or any failure
8787
leaves the lookup unavailable rather than empty, and never fails setup: it only
88-
decides whether Welcome back offers a restore and whether an import needs the
89-
backup offer.
88+
decides whether Welcome back offers a restore and whether an import needs
89+
automatic backup.
9090

9191
**Not linked** pauses on **Get started with Buzz**. **Create my key** creates
9292
and links a key; **Use an existing key** opens **Enter your private key**. **Use a different
9393
account** signs out the first-run session and returns to the welcome screen.
9494
The browser may retain its portal session. This choice page shows the signed-in
9595
email so the account can be checked before linking a key.
9696

97-
Creation does not authorize backup. After creating and linking, Buzz asks
98-
**Back up your key?**, with the disclosure that Block can restore the encrypted
99-
copy, including anywhere else the key is used. **Back it up** enables automatic
100-
backup and waits for the uploader. **Not now** persists automatic backup as off
101-
when the build supports backup, then continues. A failed upload can also be
102-
skipped with automatic backup disabled. First run never reveals a newly created
103-
key; Settings → Identity can reveal it later.
97+
Builderlab setup automatically backs up the created key after linking it to the
98+
signed-in account and waits for the uploader. The create/import screens disclose
99+
this behavior. A failed backup stays in setup with **Try again**, preserving the
100+
key on this device; it cannot be bypassed by disabling backup. If the session
101+
has expired, retry signs in again and must return to the original account before
102+
uploading. A canceled sign-in or different account leaves setup and the key intact. First run never
103+
reveals a newly created key; Settings → Identity can reveal it later.
104104

105105
**Enter your private key** accepts a plain-text `nsec1…` key or a text file up to 1 KiB.
106106
The input stays masked until **Reveal private key** is selected using the eye
107107
inside the field; **Hide private key** masks it again. The public identity preview uses npub. NIP-49 encrypted backups are not supported;
108108
invalid input stays on the form. **I lost my key** sits under the input. **Back**
109-
discards the draft. A successful account-backed import links the key and offers
110-
backup unless that key already has a backup. An import without Builderlab
111-
sign-in skips linking and backup. Importing alone never authorizes an upload.
109+
discards the draft. A successful account-backed import links the key and automatically backs it up
110+
unless that key already has a backup. An import without Builderlab
111+
sign-in skips linking and backup. Importing without a Builderlab account never uploads the key.
112112

113113
**Linked** pauses on **Welcome back**: the account is already linked to a Buzz
114114
identity — the key on the user's other device — shown as the full npub under
@@ -125,13 +125,15 @@ stack, **Use a different account** is the same exit as on Get started with Buzz:
125125
signs the session out and returns to the welcome screen without importing,
126126
restoring or replacing the linked key. The imported
127127
key is already the account's, so nothing is linked. Unless the lookup already
128-
lists it, a successful import then pauses on **Back up your key?** as on a new
129-
account; a listed key continues without the offer.
128+
lists it, a successful import automatically backs up the key as on a new
129+
account; a listed key continues without another upload.
130130

131131
**Restore your key** opens native recovery in a separate browser sign-in.
132132
Only the account’s linked key can be installed. While waiting, **Cancel** cancels
133133
the attempt; during installation, navigation is disabled. A successful install
134-
continues without a backup offer. Failure shows **Couldn’t restore your key**,
134+
continues directly to community restoration and the next required step, without
135+
another Welcome back confirmation. One status screen shows **Restoring your key…**
136+
throughout recovery, with a browser sign-in hint while waiting. Failure shows **Couldn’t restore your key**,
135137
with **Enter my private key**, **I lost my key**, optional **Try again**, then Back.
136138
Retry is available for transient errors and partially retrieved backups, but not
137139
for unavailable/refused recovery, a complete empty result or complete mismatch.
@@ -143,7 +145,7 @@ signed-in device or a usable backup. Starting over replaces the linked key;
143145
old messages and profiles are not deleted, but access does not carry over.
144146
Owned community hostnames appear only when present; a failed lookup still shows
145147
its error. **Go back** returns to the prior screen. **Start over with a new key**
146-
creates a key, unlinks the old key, links the new one, then offers optional backup.
148+
creates a key, unlinks the old key, links the new one, then automatically backs it up.
147149
The old key stays linked until the new one is on the device,
148150
and binding never overwrites, so the unlink comes after creation and before
149151
the link. The unlink checks the bound key first: it sends nothing more when
@@ -169,20 +171,13 @@ which stays on the error and is logged in development builds. Once a key is on
169171
the device, the page also says what is undone: *Your key is saved on this
170172
device, but it isn’t linked to your account or backed up yet.* when
171173
the unlink or link failed (a key that isn't linked can't be backed up),
172-
otherwise *Your key is saved on this device, but it isn’t backed up yet.* A
173-
failure that may clear offers **Try again** (primary), which repeats the failed
174-
step and the rest of the lane, never creating a second key: for the account
175-
check, unlink or link, no answer, too many requests (HTTP 429) or a server
176-
error (HTTP 5xx), and for the link also a link request that expired, was
177-
already used or could not be found, since Try again asks for a new one; for a
178-
backup, Builderlab being unreachable or slow to confirm. A lapsed sign-in is
179-
never retried, since Try again would send the same sign-in. A failed unlink or
180-
link with a key on the device blocks: nothing links the key later, so the page
181-
offers only **Try again**, whatever the failure, and no way past it. A failed
182-
backup also offers **Continue without backup**, which writes nothing and skips
183-
the remaining steps for the end of the lane below (Finding communities on a
184-
linked account, then the restore); a later sign-in runs the backup again.
185-
Before a key exists, the page offers **Back** to the welcome screen instead.
174+
otherwise *Your key is saved on this device, but setup isn’t complete yet.
175+
Retry to continue.* **Try again** repeats the failed step and the rest of the
176+
lane without creating another key. An expired backup session prompts sign-in
177+
again and verifies the original account subject before uploading. Canceled or
178+
wrong-account sign-in leaves setup and the key intact. Unsupported backup builds
179+
show configuration guidance. Failed linking and backup cannot be bypassed.
180+
Before a key exists, the page also offers **Back** to the welcome screen.
186181

187182
Within one first-run session the Join page exits only through a join or a
188183
restored community; there is no skip. That holds only while the app stays
@@ -518,12 +513,12 @@ hands the sign-in back, whatever the outcome; an earlier pass's result never
518513
answers it. A pass that stops to wait for consent, a session or a key binding
519514
fails the step, since nothing would wake it again before first run ends. The
520515
failed page names the reason without any service response. The automatic choice
521-
stays on after a failure, Continue without backup included, so a later
516+
stays on after a failure, so a later
522517
Builderlab sign-in may still finish the backup the user asked for. The step
523518
hands a sign-in over only when this build's uploader can back up to Builderlab.
524519
Anywhere else (a build without backup configured) the step fails at once as
525-
*Key backup isn’t available in this version of Buzz.* without saving the
526-
choice, and the user continues without backup.
520+
*Couldn’t back up your key. This build needs Builderlab backup support to finish setup.* without saving
521+
the choice. First-run failures offer retry and preserve the saved key.
527522

528523
When secure storage confirms absence, native recovery commands support explicit
529524
browser sign-in. The session and recovered keys remain native; the renderer sees
@@ -783,9 +778,10 @@ The native identity service exposes `getBackupChoice()` and
783778
`setBackupChoice(pubkey, automatic)`. These APIs expose public metadata and do not
784779
change identity readiness. Reading a choice does not contact a server; saving
785780
automatic backup wakes the existing native uploader if a session is connected.
786-
First run's backup consent is **Back it up**, after creating, replacing or
787-
importing a key. Creating or linking the key does not authorize an upload.
788-
**Not now** persists automatic backup as disabled when backup is available.
781+
Builderlab first run discloses automatic backup before creating, replacing or
782+
importing a key, then enables it after linking. There is no separate backup-choice
783+
screen or failure bypass. Independent imports without Builderlab sign-in do not
784+
enable backup. Settings retains control over future automatic uploads.
789785

790786
The choice is bound to the current public key and trusted build-configured backup
791787
service and namespace. Missing or mismatched metadata returns no choice;

‎src/features/identity/BackupOffer.tsx‎

Lines changed: 0 additions & 46 deletions
This file was deleted.

‎src/features/identity/ConnectChoice.tsx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import { Button } from "../../shared/design-system/ui/Button";
77
* it hosts signs in at once), before any sign-in: the relay cannot sign the
88
* user in, but Buzz still needs a key. Connect runs the build portal's sign-in
99
* exactly as the landing's button does (the key it creates is linked to that
10-
* account, with backup offered separately); the import brings a key with no account to
10+
* account, with automatic backup); the import brings a key with no account to
1111
* link it to. Either way setup ends on Join Community for the found address.
1212
*/
1313
export function ConnectChoice({
@@ -18,7 +18,7 @@ export function ConnectChoice({
1818
}: {
1919
/** The found community's host, as the find page shows it. */
2020
host: string;
21-
/** Sign in at the build portal and continue as the landing’s Sign in with email does. */
21+
/** Sign in at the build portal and continue as the landing’s Sign in with Builderlab does. */
2222
onConnect: () => void;
2323
/** The user already has a key: open the import page. */
2424
onImport: () => void;
@@ -54,7 +54,7 @@ export function ConnectChoice({
5454
</div>
5555
<div className="flex flex-col gap-2">
5656
<Button variant="prominent" size="lg" onClick={onConnect}>
57-
Sign in with email
57+
Sign in with Builderlab
5858
</Button>
5959
<Button size="lg" data-return-focus="import" onClick={onImport}>
6060
Use an existing key

‎src/features/identity/KeyChoice.tsx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,15 @@ import { Button } from "../../shared/design-system/ui/Button";
22
import styles from "./IdentitySetup.module.css";
33
import { OnboardingScreen } from "./OnboardingScreen";
44

5-
/** Create and link a key, or import one, before choosing optional backup. */
5+
/** Create and link a key, or import one, with automatic Builderlab backup. */
66
export function KeyChoice({
77
email,
88
onCreate,
99
onImport,
1010
onSwitchAccount,
1111
}: {
1212
email?: string | undefined;
13-
/** Create the key, link it to the account, then offer optional backup. */
13+
/** Create the key, link it to the account, then back it up. */
1414
onCreate: () => void;
1515
/** The user already has a key: open the import page. */
1616
onImport: () => void;
@@ -31,8 +31,8 @@ export function KeyChoice({
3131
Get started with Buzz
3232
</h1>
3333
<p className="text-body text-subtle">
34-
We’ll create a private key that represents you in Buzz. You can also
35-
use it in other compatible apps.
34+
We’ll create a private key that represents you in Buzz. Your key is
35+
backed up to your Builderlab account automatically.
3636
</p>
3737
{email && (
3838
<p className="break-words text-body-sm text-subtle">

‎src/features/identity/KeyImport.tsx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,12 +26,14 @@ import { SetupProgress } from "./SetupProgress";
2626
*/
2727
export function KeyImport({
2828
expectedPubkey,
29+
automaticBackup = false,
2930
onBack,
3031
onLost,
3132
onImport,
3233
}: {
3334
/** The hex key linked to the signed-in account, when the lane has one. */
3435
expectedPubkey?: string | undefined;
36+
automaticBackup?: boolean;
3537
onBack: () => void;
3638
onLost?: (() => void) | undefined;
3739
/** Rejects with the native refusal, shown under the field. */
@@ -125,6 +127,13 @@ export function KeyImport({
125127
Paste your private key to sign in to Buzz. You can also select
126128
or drop a text file with your key.
127129
</p>
130+
{automaticBackup && (
131+
<p className="text-body-sm text-subtle">
132+
Your key will be backed up to your Builderlab account
133+
automatically. Block can use that copy to restore this key,
134+
including anywhere else you use it.
135+
</p>
136+
)}
128137
<div className={styles.importForm}>
129138
<Field
130139
label="Private key (nsec)"

‎src/features/identity/KeyLost.tsx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import type { OwnedCommunity } from "./builderlab-account";
33
import { WireframePanel } from "./Wireframe";
44

55
/** Recovery guidance and consequences before replacing a linked key.
6-
* Backup is offered separately after the replacement has been linked. */
6+
* The replacement is automatically backed up after linking. */
77
export function KeyLost({
88
owned,
99
onBack,
@@ -31,7 +31,8 @@ export function KeyLost({
3131
<p className="mt-2 text-body text-subtle">
3232
Starting over replaces the key linked to your Builderlab account. Your
3333
profile, messages, and community access won’t carry over. Your old
34-
content won’t be deleted.
34+
content won’t be deleted. The new key will be backed up to your
35+
Builderlab account automatically.
3536
</p>
3637
</div>
3738
{(owned === undefined || owned.length > 0) && (

0 commit comments

Comments
 (0)