first-run-ux: welcome modal + first-run gate (PR-B of #1101)

[RebelTechPro]

Summary

• Second of two PRs against First-run UX: welcome flow, empty states, tutorial-persona auto-invite (post-#336) #1101. PR-B is the user-facing welcome flow that consumes the foundations introduced in PR-A.
• ⚠️ Stacked on top of first-run-ux: foundations + empty states (PR-A of #1101) #1107 (PR-A). Until PR-A merges, this PR's diff will show both PR-A's commits and PR-B's commits. Once PR-A merges to main, GitHub auto-rebases and the diff here reduces to just the welcome-modal-specific commits.
• New widget widgets/onboarding/WelcomeModalWidget.ts — two-panel welcome flow using PR-A's <modal-widget>.
• First-run gate in MainWidget — opens the modal when currentUser.hasOnboarded is falsy, persists true on completion.
• Seed extension — Helper AI now joins the General room so the modal's "Helper is in General" copy matches reality.

Decisions (from the #1101 planning thread)

Question	Decision
Gate scope	Per-user (cross-device) — flag on UserEntity (PR-A)
Featured persona	Helper AI only — single, always-available local persona
API-key step	Skipped — local inference is good enough out-of-box per #336
Modal copy	I drafted, ready for your edits — strings live in WelcomeModalWidget.renderStep()

What changed

WelcomeModalWidget.ts (new, 178 lines)

• Two panels wrapped in <modal-widget>:
  1. Intro — "Continuum is a shared workspace where you collaborate with humans and AI personas side-by-side..."
  2. Hand-off — "Helper AI is already in your General room. It runs locally on your machine — no API keys, no cloud round-trips."
• Step indicator dots, Back / Next / Got-it buttons.
• Dismissing the modal (Escape / backdrop / X) is treated the same as "completed" — the user has seen the intro, no reason to nag next session.
• Fires welcome-complete event for the parent to react to.

MainWidget gate

• Adds @reactive() private _showWelcome state.
• onFirstRender: after URL routing and other setup, checks this.currentUser?.hasOnboarded. Falsy → opens the modal. currentUser is loaded by ReactiveWidget.connectedCallback() before onFirstRender runs, so this is race-free.
• onWelcomeComplete: closes the modal, calls data/update on users collection with { hasOnboarded: true }, mutates the in-memory entity so a hot re-render doesn't reopen it. Persist failure is logged, not surfaced — worst case the modal shows again next session.

Seed extension

• scripts/seed-continuum.ts:335 — SYSTEM_ROOM_UNIQUE_IDS extended from ['settings', 'help', 'theme', 'canvas'] to ['general', 'settings', 'help', 'theme', 'canvas'].
• This constant is referenced from both the fresh-seed path (line ~588) and the existing-rooms path (line ~530), so the change applies in both flows — fresh installs and re-seeds of existing databases both put Helper AI into General.
• Why this matters: without it, the welcome modal's hand-off ("Helper is in General") doesn't match reality for a fresh install. Now it does.

Test plan

• npm run build:ts → green (verified locally on top of PR-A)
• Fresh seed (npm run data:reseed): Helper AI appears in members list of General.
• Fresh user opens app → welcome modal appears within ~1s of MainWidget mount, focus lands inside the modal, Escape works.
• Step 1 → Next → Step 2 (step dots track, Back works).
• Got-it on step 2 → modal closes, data/update fires, users row has hasOnboarded: true.
• Reload page → modal does NOT reappear.
• Click "Helper AI" in General → mention works; send a message → Helper responds (validates the "say hi" copy).
• Escape on first panel → modal closes AND hasOnboarded persists (dismissal = completed).
• Screen reader pass: modal title announced, body announced, focus trap holds, focus restored to invoker on close.
• Theme spot-check across base / cyberpunk / light — modal honors theme variables.

⚠️ Not visually validated by me — TS compile is the only local check.

Copy policy

The text in WelcomeModalWidget.renderStep() is intentionally short and meant to be revised. Edit the strings directly; no separate i18n table yet. Tone target was warm-brief-system-confident-not-salesy.

Closes

Closes #1101 when both this and #1107 merge. (Tracker stays open until both are in.)

[joelteply]

Substantive review (claude tab #2 / claude-tab-2, picked up via continuum#1126 intake card). Reviewed #1107 first; this picks up the PR-B incremental delta.

What this PR adds (over #1107)

• WelcomeModalWidget — two-panel intro consuming <modal-widget> from PR-A
• MainWidget gate — opens modal when currentUser.hasOnboarded is falsy, persists true on completion
• Seed extension — Helper AI now auto-added to General room

What I verified

• Seed extension applies in both paths. I checked scripts/seed-continuum.ts:

  • Line 614 (existing-rooms path) iterates SYSTEM_ROOM_UNIQUE_IDS and adds Helper to any room missing them — adding 'general' here covers existing installs.
  • Line 671 (fresh-seed path) does the same for newly-created rooms — covers npm run data:reseed.
    Both paths affected, as your PR description claims. ✓

• Helper not double-added. The pre-existing General-room handling (line 752 area) only added a welcome message, not Helper membership. So adding 'general' to SYSTEM_ROOM_UNIQUE_IDS doesn't duplicate any earlier add. ✓

• MainWidget.onFirstRender ordering. Per the comment, currentUser is loaded by ReactiveWidget.connectedCallback() BEFORE onFirstRender runs — so this.currentUser?.hasOnboarded is reliable here. If that ever stops being true (refactor of base widget), the modal would silently skip for first-run users. Worth a comment-anchor on ReactiveWidget.connectedCallback so the load-order invariant doesn't drift.

• In-memory mutation after async persist (user.hasOnboarded = true; after the await). Defensive against hot re-renders that re-check currentUser.hasOnboarded before the next page load. Good. ✓

• Persist failure is logged not surfaced. Right call — worst case modal shows again next session, which is recoverable. ✓

Issues worth fixing before un-drafting

1. role="presentation" + aria-label="Welcome progress" on the step-indicator div (WelcomeModalWidget.renderFooter) are contradictory. role="presentation" tells assistive tech to ignore the element ENTIRELY — aria-label won't be announced because the element is "presentational." Pick one:

   • Drop role="presentation" if you want the label announced (dots are decorative, the label says what they mean).
   • Drop aria-label if you genuinely want AT to ignore the dots (and rely on the step text + buttons to convey progress).
   • Or: <div role="status" aria-live="polite" aria-label="Step ${step+1} of ${totalSteps}"> if you want each step-change announced.

2. WelcomeModalWidget.complete() sets this.open = false internally, but this.open is also bound from the parent via ?open=${this._showWelcome}. On the next parent render, the parent's value wins. So the internal mutation is dead state — harmless but confusing. Either remove this.open = false (rely solely on the event-driven parent close), or document that the internal flag is only for the rare case the modal is used standalone.

Things to consider (not blocking)

3. backend: 'server' hardcoded in the data/update call. Most Commands.execute('data/update', ...) invocations in the codebase don't pass backend explicitly (it auto-routes). Worth checking whether explicit 'server' is required here, or if you can drop it for consistency with other call sites.

4. Modal copy mentions "head into Settings to plug in cloud providers like Anthropic, OpenAI, or others." Worth a quick check that Settings UI for API key entry actually exists in this state of the codebase — if not, the copy promises something that isn't there and a user clicking "Settings" gets confused. If it's planned-but-not-yet-built, soften to "When you want richer responses, cloud providers can be added later" or similar.

5. requestAnimationFrame focus inside ModalWidget.updated() — if open rapidly toggles (false→true→false), multiple rAFs queue and try to focus a no-longer-open dialog. The focusFirstElement would no-op because querySelector finds nothing, but it's worth a if (!this.open) return; guard inside the rAF callback. Tiny edge case.

6. onModalClose treats Escape/backdrop/X all as "completed" — this is the right UX call (don't nag), but the test plan should explicitly check that hasOnboarded persists on Escape-dismiss, not just on Got-it. Add a [ ] checkbox: "Escape on first panel → hasOnboarded is written to DB."

Test plan additions

Your [ ] list is good. Suggested additions before un-drafting:

• Both seed paths: npm run data:reseed on a clean DB, and re-running it on an existing DB → Helper appears in General members in BOTH cases.
• Persist on dismissal: Escape → reload page → modal does NOT reappear.
• Failed persist scenario: kill the server mid-Got it click → confirm warning logged, confirm modal re-appears next session.
• Step indicator a11y: with role/aria-label fixed per nit Feature: CLI Implementation with Testing #1, verify screen reader announces step changes.

Recommendation

LGTM to land after fixing nit #1 (role=presentation + aria-label conflict). The architecture is right (per-user flag, race-free gate, dismissal=completed), the seed change is correctly placed in both code paths, and the modal-widget reuse is clean.

The PR-A/PR-B split paid off here — this review was 30 minutes instead of 2 hours because the foundation was already validated.

Thanks for the careful gate ordering and the in-memory mutation safety net. New-contributor work that gets the lifecycle details right is the rare kind.

[joelteply]

Review (claude-tab-1) — REQUEST CHANGES (stale-branch regression of #1100)

This branch is stale relative to canary. The diff against current canary shows it reverts the XSS hardening shipped in #1100 (chat XSS hardening — DOM-returning adapter render path):

-      this.renderAdapterContentInto(contentDiv, adapter, message);
+      contentDiv.innerHTML = contentHtml;   // ← re-introduces innerHTML XSS surface

Plus deletes the renderAdapterContentInto private method that was the seam for that hardening.

This is the same root cause I documented in detail on #1107 — see #1107 (review) latest review for the full breakdown including the a11y phase-2 regression in #1108 specifically.

Fix

Rebase this branch onto current origin/canary and resolve the conflict in ChatWidget.ts so the new work in this PR sits ON TOP of the kept renderAdapterContentInto path, not in place of it.

After rebase, this PR's actual changes will likely be much smaller and easier to evaluate on their own merits. As-is the diff is dominated by accidental reverts.

The PR's intentional changes look fine; this is purely a substrate hygiene issue. Sorry for the late catch — these PRs sat unreviewed too long. The substrate's stale-PR signal (airc#608 / #609) would have flagged it earlier.