feat(orbit): proactive returning-user greeting (§9.3)

[Hackshaven]

What

Phase 7 §9.3 of docs/WEB_CATALOG_FEATURES_PLAN.md — proactive Orbit greeting for returning visitors.

When someone reopens the catalog after a gap of more than 24 h, Orbit proactively opens the chat panel and streams a short, warm "welcome back" turn. The greeting is steered by a local-only returning-user context block:

• how long since the last visit (whole days),
• titles of datasets added since their last visit (capped at 5),
• titles they recently viewed (capped at 3, resolved to current catalog titles).

Orbit opens with one short paragraph and offers one or two concrete next steps (a new dataset, returning to something they viewed, or a tour) rather than dumping a list.

How

Layer	Change
docentContext.ts	New ReturningUserContext interface + buildReturningUserBlock() pure string builder; optional returningUserBlock threaded into buildSystemPrompt (prepended after the role intro, turn-0 only). Lines with no data are omitted.
docentService.ts	triggerOpeningTurn() — once-per-session latch (resetOpeningTurnForTests() for tests), skips entirely when the LLM is unconfigured (a canned local-engine greeting would feel off), delegates to processMessage so the greeting reuses the full streaming + discovery-tool + <<LOAD:>>→chip path. New optional returningUserBlock param on processMessage.
chatUI.ts	playReturningGreeting() opens the panel, streams the turn, and attaches a one-time "Orbit remembers locally" disclosure footnote (gated by sos-orbit-greeting-disclosed.v1). Self-gates on: callbacks present, not already streaming, no existing user turn, LLM configured.
main.ts	maybeGreetReturningVisitor() gates on catalog mode + getLastSession() existing + a >24 h gap, then hands local visit memory to the UI. Fire-and-forget.
types/index.ts	ChatMessage.disclosureFootnote?: boolean.
chat.css / en.json	Footnote styling + two i18n strings (chat.greeting.disclosure, chat.greeting.disclosure.link).

Privacy

All inputs are local-only (visit memory from §9.2). Nothing new is sent server-side except the resulting prompt block to the LLM the user has already configured for chat. No new telemetry events. A one-time, dismissible-by-reading disclosure footnote explains the local memory and links to the privacy surface.

Incidental fix

restoreSession() left the module-level messages array stale when sessionStorage was empty — it now resets to []. This is correct production behavior (re-init shouldn't resurrect a prior conversation) and makes the chat tests order-independent.

Testing

• npm run test — 3840 passing / 1 skipped (new: buildReturningUserBlock + system-prompt inclusion in docentContext.test.ts; triggerOpeningTurn latch/skip/injection in docentService.test.ts; playReturningGreeting stream/footnote/empty-drop in chatUI.test.ts).
• npm run type-check (incl. check:i18n-strings) — clean.
• npm run check:locales — artifacts up to date.
• npm run build — clean.

[Copilot]

Pull request overview

Implements Phase 7 §9.3 “proactive returning-user greeting” for Orbit chat: when a visitor returns after a >24h gap in catalog mode, the chat panel auto-opens and streams an LLM-generated welcome-back message steered by a local-only returning-visitor context block, with a one-time privacy disclosure footnote.

Changes:

• Add a ReturningUserContext + buildReturningUserBlock() and thread an optional returningUserBlock into the system prompt (turn-0 only).
• Add triggerOpeningTurn() in docentService (once-per-session latch; skips when LLM unconfigured) and playReturningGreeting() in chatUI (auto-open, stream, one-time disclosure).
• Add UI + i18n + styling for the disclosure footnote, plus a session-restore fix to reset stale messages when sessionStorage is empty.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/ui/chatUI.ts	Adds proactive greeting streaming + one-time disclosure footnote; fixes restoreSession() stale messages when storage is empty.
src/ui/chatUI.test.ts	Adds tests for greeting streaming, disclosure gating, and empty-stream placeholder drop.
src/types/index.ts	Extends ChatMessage with disclosureFootnote?: boolean.
src/styles/chat.css	Styles the disclosure footnote as muted, small text.
src/services/docentService.ts	Adds triggerOpeningTurn() and threads returningUserBlock through processMessage → buildSystemPrompt.
src/services/docentService.test.ts	Adds coverage for opening-turn latch, skip when unconfigured, and prompt injection.
src/services/docentContext.ts	Adds ReturningUserContext, buildReturningUserBlock(), and optional returning-user block inclusion in system prompt.
src/services/docentContext.test.ts	Adds tests for returning-user block construction and conditional system-prompt inclusion.
src/main.ts	Adds maybeGreetReturningVisitor() gating (>24h gap, catalog mode) and passes local visit context to UI.
locales/en.json	Adds disclosure footnote strings.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.