From e342149a09bb3e6fad195e003704e44704c48f64 Mon Sep 17 00:00:00 2001 From: Manjunath Paparaju Date: Wed, 18 Nov 2026 19:24:52 +0530 Subject: [PATCH] Turn the first-run launcher into a three-step welcome Replace the single dense welcome card with three short steps: an introduction to the modes, where to start (Space Missions, Environmental or Explore manually, Explore selected by default), then quick tips (the place tip points at the search bar) and links. Next and Back keep the selection, and only Enter God mode runs a mission; double clicks, Enter repeats and clicks during a step change cannot launch one. Skip and ESC close the card for the session, as before. Drop the Live Contacts tile and the old voice tip. Space Missions switches on its layer, which opens its own panel, so no first-run choice enters a Context mode or opens the Context panel any more, and that path is gone. The last step links to the repository and Halfpixel's channels, each opening in a new tab without opener or referrer. Its GEV Stories card closes the welcome and opens the in-app Stories Explore view; the Stories announcement stays hidden, and unseen, until the card has closed and Stories has loaded. The dim layer behind the card is a click-through tint with no blur. Update the 13 catalogs, CURRENT-STATE, the first-run QA harness and its mutations, and the scripts that dismissed the old card. Add a changelog fragment. Co-authored-by: Sameh Khamis --- changelog.d/4-three-step-onboarding.md | 5 + docs/CURRENT-STATE.md | 49 +- scripts/qa-firstrun-mutations.mjs | 41 +- scripts/qa-firstrun.mjs | 136 +- scripts/qa-floor-hold.mjs | 2 +- scripts/qa-street-level.mjs | 3 - src/firstRunCopy.js | 18 +- src/firstRunExperience.js | 74 +- src/firstRunExperience.test.mjs | 262 ++-- src/firstRunLauncherView.test.mjs | 242 +++- src/i18n/locales/ar.json | 41 +- src/i18n/locales/de.json | 41 +- src/i18n/locales/es.json | 41 +- src/i18n/locales/fr.json | 41 +- src/i18n/locales/he.json | 41 +- src/i18n/locales/it.json | 41 +- src/i18n/locales/ja.json | 41 +- src/i18n/locales/pt.json | 41 +- src/i18n/locales/ru.json | 41 +- src/i18n/locales/sv.json | 41 +- src/i18n/locales/uk.json | 41 +- src/i18n/locales/zh-CN.json | 41 +- src/i18n/locales/zh-Hant.json | 41 +- src/ui/stores/firstRun.js | 4 +- src/ui/styles/first-run.css | 1648 ++++++++++++++++++++++-- src/ui/styles/rtl.css | 10 +- src/ui/views/WelcomeView.vue | 295 ++++- 27 files changed, 2807 insertions(+), 515 deletions(-) create mode 100644 changelog.d/4-three-step-onboarding.md diff --git a/changelog.d/4-three-step-onboarding.md b/changelog.d/4-three-step-onboarding.md new file mode 100644 index 0000000000..ecf505719b --- /dev/null +++ b/changelog.d/4-three-step-onboarding.md @@ -0,0 +1,5 @@ +- Replace the first-run launcher with a three-step welcome: an introduction to + the modes, where to start (Space Missions, Environmental or Explore + manually), then quick tips and links. The Live Contacts starting choice is + gone. GEV Stories opens in the app from the last step, and a light tint (no + blur) sits over the globe while the card is up (manjunath22466, #4). diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 64207f325a..237a5258db 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -4106,10 +4106,31 @@ which embeds the MAP_KEY. points to restrictions, quota, or connectivity. These hints do not expose keys. > **2026-08-23 — first-run mission launcher** (`src/firstRunExperience.js`, -> `#first-run-launcher`, styles at the tail of `style.css`). After startup -> settles, a fresh session gets one card offering **Live Contacts · Space -> Missions · Environmental · Explore manually**. No layer and no optional API -> call happens until a tile is clicked. The right-hand DISPLAY rail +> `#first-run-launcher`, styles in `src/ui/styles/first-run.css`). After startup +> settles, a fresh session gets three steps: mode introduction, a starting +> mission, then quick tips and links. God mode is available; Analyst is +> marked coming soon. **Space Missions · Environmental · Explore +> manually** are the starting choices, with Explore selected by default; Live +> Contacts is no longer offered as a starting mission (its Context tab is +> unchanged). The footer status line stays empty until a mission reports +> progress or an error; the old voice tip is gone. While the card is up, a +> click-through backdrop tints the globe behind it (`.first-run-backdrop`, a +> 28% dark tint with no blur); it never takes input, so the card stays +> non-modal. The last step links out to the GitHub repository and +> Halfpixel's channels (YouTube, X, Instagram, LinkedIn, bilawal.ai, +> halfpixel.ai); each opens in a new tab with `rel="noopener noreferrer"`, and +> the addresses live in `FIRST_RUN_LINKS` (`src/firstRunCopy.js`). The GEV +> Stories card's BROWSE STORIES button closes the card (a session dismissal, +> like Skip) and opens the in-app Stories Explore view, keeping the Stories +> announcement hidden while Stories loads. Next and Back preserve that selection without starting +> a mission. Only **Enter God mode** runs it; Back is inert while it is loading. +> Step changes focus the main action, announce the new heading separately from +> mission progress, and refresh the scrolling affordance after the transition. Repeated Enter keys, +> double-clicks and activation during a step transition cannot launch a mission. +> No layer and no optional API call happens until the final action is clicked. +> The Stories announcement waits, from startup until onboarding closes, without +> marking it seen. +> The right-hand DISPLAY rail > (`pp-toggles`) now starts **collapsed** on a first run rather than expanded — > a stored collapse state still wins, as before. > @@ -4157,26 +4178,28 @@ which embeds the MAP_KEY. > `localStorage['gev:first-run-mission:v1'] === 'suppressed'`, written **only** > by the "Don't show this again" checkbox → the per-session > `sessionStorage['gev:first-run-mission-session:v1'] === 'dismissed'`, written -> by **every** close path (mission, Explore, ESC, the footer dismiss button). So +> by **every** close path (a mission or Explore from ENTER GOD MODE, ESC, the +> header Skip button, BROWSE STORIES). So > it returns each fresh browser session until the visitor ticks the box; clearing > storage un-ticks it, which is accepted. Both stores fail open — an unreadable > store still shows the launcher rather than silently swallowing first launch. > -> **The footer dismiss button is the keyboardless ESC.** Phones and tablets have -> no ESC key, so the footer hint is a `data-first-run-dismiss` button that calls +> **The header Skip button is the keyboardless ESC.** Phones and tablets have +> no ESC key, so the header action is a `data-first-run-dismiss` button that calls > the same `dismiss()` as ESC. It stays visible at every width (phones used to -> hide it, leaving a mission as the only way out) and reads DISMISS on a -> `(hover: none) and (pointer: coarse)` screen, "ESC to dismiss" otherwise. Its -> 44px touch target is a `::before` outside the layout, so the footer row keeps +> hide it, leaving a mission as the only way out) and reads SKIP on a +> `(hover: none) and (pointer: coarse)` screen, "SKIP · ESC" otherwise. Its +> 44px touch target is a `::before` outside the layout, so the header row keeps > its one-line height. > > **What a mission may persist (do not "simplify" this).** Layer enablement is > durable in this app (`gev:layer-state:v2`, written by > `LayerStateCoordinator._commitExplicit` only for origin `user`/`voice`/`tool`). > A mission enables **its own** layers at `origin: 'user'` — durable, exactly as -> clicking those rows is, because picking the mission _is_ that choice. The two -> Context missions also expand the Context panel, as the visible tabs do; the -> globe missions open no panel. Everything else is off limits: detection +> clicking those rows is, because picking the mission _is_ that choice. Space +> Missions switches on its layer, which opens its own Space Missions panel; no +> mission enters a Context mode or opens the Context panel, and the globe +> missions open no panel. Everything else is off limits: detection > mode/density, `gev:detection-allocation:v1`, 3D models, feather, and above all > `_detectionUserOverridden` — setting that flag means "the operator hand-edited > detection" and would silently disable the CRT/NVG/FLIR auto-preset contract for diff --git a/scripts/qa-firstrun-mutations.mjs b/scripts/qa-firstrun-mutations.mjs index 91e303885a..2c622598fd 100644 --- a/scripts/qa-firstrun-mutations.mjs +++ b/scripts/qa-firstrun-mutations.mjs @@ -276,21 +276,21 @@ const MUTATIONS = [ }, { defect: 'the tile stops promising the fires it actually turns on', - file: 'html', + file: 'module', from: " 'Live earthquakes and active fires, from USGS and NASA',", to: " 'Live earthquakes worldwide, straight from USGS',", }, { - defect: 'the owner-authored first-run line is quietly rewritten', + defect: 'the maintainer-authored first-run line is quietly rewritten', file: 'html', from: 'It feels like a forbidden cockpit—then you realize the sources are public and the data is real.', - to: "It feels like a forbidden cockpit. It isn't — every feed is public, and every contact is live.", + to: 'A live 3D globe of public data. Pick a view to begin.', }, { defect: 'the ledgered global-chip defect loses its pointer to the real fix', file: 'module', - from: ' // means a KEY REQUIRED terminal state in src/loadingFeedback.js, a state', - to: ' // (note removed)', + from: ' // ends KEY REQUIRED (src/loadingFeedback.js), and the quakes half of the', + to: ' // ends KEY REQUIRED, and the quakes half of the', }, { defect: 'the globe missions never pull the camera out', @@ -314,7 +314,7 @@ const MUTATIONS = [ defect: 'Explore manually quietly runs a mission instead of nothing', file: 'module', from: "if (mission.kind === 'none') return { ok: true, choice };", - to: "if (mission.kind === 'none') return { ok: true, choice, ran: await setContextMode('contacts') };", + to: "if (mission.kind === 'none') return { ok: true, choice, ran: await setLayerEnabled('rocket-launches') };", }, { defect: 'an unknown choice is treated as a success', @@ -348,15 +348,14 @@ const MUTATIONS = [ { defect: 'a mission persists a 3D-models choice nobody made', file: 'module', - from: ' const result = await styleManager.setContextMode(mode);', - to: ' styleManager._setModels3dEnabled?.(true);\n const result = await styleManager.setContextMode(mode);', + from: " setLayerEnabled: (layerId) =>\n dataManager.setEnabled(layerId, true, { origin: 'user' }),", + to: " setLayerEnabled: (layerId) => {\n styleManager._setModels3dEnabled?.(true);\n return dataManager.setEnabled(layerId, true, { origin: 'user' });\n },", }, { - defect: - 'the Context panel is left collapsed, hiding the mode that just started', + defect: 'a mission writes panel chrome nobody chose', file: 'module', - from: " styleManager.setPanelCollapsed?.('global-context-panel', false, {\n explicit: true,\n });", - to: ' // panel reveal removed', + from: ' flyToGlobe: () => styleManager.resetToGlobeView(),', + to: " flyToGlobe: () => {\n styleManager.setPanelCollapsed?.('global-context-panel', false, { explicit: true });\n return styleManager.resetToGlobeView();\n },", }, { defect: @@ -371,8 +370,8 @@ const MUTATIONS = [ defect: 'disabling the focused tile drops the keyboard to mid-flight', file: 'html', - from: ':aria-disabled="launcher?.busy ?? undefined" @click="controls?.choose(\'contacts\')"', - to: ':disabled="launcher?.busy === \'true\'" @click="controls?.choose(\'contacts\')"', + from: ':aria-disabled="String(settling || launcher?.busy === \'true\')" @click="onPrimary"', + to: ':disabled="launcher?.busy === \'true\'" @click="onPrimary"', }, { defect: 'Tab escapes into an app the visitor has not seen yet', @@ -421,8 +420,8 @@ const MUTATIONS = [ defect: 'the card loses its viewport cap and clips on a short landscape phone', file: 'css', - from: ' max-height: calc(100dvh - 1.5rem);', - to: ' /* cap removed */', + from: ' body.mobile-shell #first-run-launcher {\n bottom: 5.8rem;\n max-height: calc(100vh - 6.55rem);\n max-height: calc(100dvh - 6.55rem);\n }', + to: ' body.mobile-shell #first-run-launcher {\n bottom: 5.8rem;\n /* cap removed */\n }', }, { defect: @@ -437,7 +436,7 @@ const MUTATIONS = [ // those instead and prove nothing about this feature. defect: "the launcher's reduced-motion opt-out is dropped", file: 'css', - from: ' #first-run-launcher,\n .first-run-choices button,\n .first-run-arrow {\n transition: none;\n }\n /* Scrolling a tile into view must not animate either. */\n .first-run-choices {\n scroll-behavior: auto;\n }', + from: ' #first-run-launcher,\n .first-run-backdrop,\n .first-run-back,\n .first-run-missions button,\n .first-run-link-card,\n .first-run-link-button,\n .first-run-enter {\n transition: none;\n }\n /* Scrolling a tile into view must not animate either. */\n .first-run-choices {\n scroll-behavior: auto;\n }', to: ' .first-run-nothing {\n transition: none;\n }', }, @@ -445,14 +444,14 @@ const MUTATIONS = [ { defect: 'a mission tile is dropped from the menu', file: 'html', - from: '