---
path: /welcome/download
surface: customer
domain: onboarding-public
auth: anon
source: apps/oshun/web/src/app/welcome/download/page.tsx
status: walked
last_walked: >-
  2026-06-28 automated install-contract walk (Playwright Chromium against real
  dev infra) — validated `/welcome/download` platform links, auth handoff links,
  install trigger buttons, browser guide cards, preview image assets, read-only
  deep links, footer navigation, mobile SmartAppBanner, `beforeinstallprompt`
  activation, and standalone installed guidance. Evidence:
  `apps/oshun/web/e2e/welcome-download-install.spec.ts`.

  2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data
  (2xx), console/page-errors, expected content, screenshot verified; live
  screen-reader, touch, offline, and telemetry-delivery checks pending a manual
  AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md
---

# Welcome · Install / Download

## Purpose

Platform-specific install guidance. Surfaces iOS App Store, Google Play, and PWA
install flows; documents per-browser install steps; previews the installed
workspace; lists deep-link URI schemes for the six domains.

## Entry points

- Marketing CTA "Install OSHUN" (from `/welcome`, `/welcome/domains`)
- Footer "Download" link
- Companion-bridge rail on `/` (signed-in shell) → `/welcome/download`
- SmartAppBanner "Open in app" → routes through this page on tap if no app
  installed
- Direct URL / bookmark — yes (anon)

## Layout regions

`page.tsx` is a server component using the shared `welcomePage` CSS register.
Pulls store URLs and domain list copy from `@/lib/mobile-store-links`. Composes
`<SmartAppBanner />` plus sectioned content; mounts `<PwaInstallPrompt />` at
the bottom and `<PwaInstallTriggerButton />` inline.

- **SmartAppBanner**: mobile install nudge
- **welcomeHero**: eyebrow "Install OSHUN", h1 "Bring the six-domain workspace
  onto every device", subtitle + two CTA buttons ("Create your account" / "Sign
  in on the web")
- **Download options grid** (`.welcomeFeatureGrid`, three cards from
  `PLATFORMS`):
  - **iOS** — link to `OSHUN_APP_STORE_URL` (external, `target="_blank"`,
    `rel="noopener noreferrer"`)
  - **Android** — link to `OSHUN_PLAY_STORE_URL` (external)
  - **Web (PWA)** — `PwaInstallTriggerButton` (in-page install)
- **Browser install guidance** (`#web-install`, `data-download-web-install`):
  - h2 "Install the browser version with the right path for your device"
  - Three guide cards (`BROWSER_INSTALL_GUIDES`, each with
    `data-download-install-step`): Desktop Chrome/Edge, Android Chrome,
    iPhone/iPad Safari — each with subtitle + ordered step list
  - Callout card (`data-download-install-callout`): "Use the live install prompt
    when it appears" + `PwaInstallTriggerButton`
- **Installed-workspace previews** (`welcomePreviewGrid`,
  `data-download-preview-grid`):
  - Four `<figure>` cards (`PREVIEW_FRAMES`): Home workspace (desktop), Activity
    continuity (desktop), Mobile home, Mobile explore — each `<Image>`
    lazy-loaded with explicit width/height and caption
- **Deep links**: six `<code>` cards listing `oshun://` URIs (tara, veritas,
  nyx, arete, nisaba, metis)
- **Why install** features grid (`FEATURES`): four cards — Standalone shell,
  Route continuity, Quick actions (uses `OSHUN_CUSTOMER_DOMAIN_LIST_COPY` from
  `mobile-store-links`), Cross-device sync
- **welcomeFooterCta** "Already have the app?": signin + signup buttons
- **welcomeFooter**: brand + nav (Home, Dashboard, Download), copyright
- **`<PwaInstallPrompt />`**: in-app install banner (lifecycle-managed client
  component)

## States

- [x] **Loading** — N/A; static server component; no route-local fetch or
      skeleton exists in `page.tsx`.
- [x] **Default desktop** — full grid; install prompt button visible. Covered by
      `welcome-download-install.spec.ts`.
- [x] **Mobile (`SmartAppBanner` showing)** — iOS SmartAppBanner renders while
      iOS, Android, and Web (PWA) cards remain visible. Covered by
      `welcome-download-install.spec.ts`.
- [x] **PWA install available (Chrome/Edge)** — `PwaInstallTriggerButton` /
      `PwaInstallPrompt` becomes active when `beforeinstallprompt` fires.
      Covered by `welcome-download-install.spec.ts`.
- [x] **PWA install unavailable / dismissed** — before the browser event, static
      trigger buttons are enabled but dispatch a no-op and no prompt renders;
      dismissal cooldown is covered by `pwa-install-update-offline.spec.ts`.
- [x] **Already installed (PWA)** — standalone display mode renders installed
      guidance and suppresses the available prompt; static education controls
      remain visible. Covered by `welcome-download-install.spec.ts`.
- [x] **Reduced motion** — `<Image>` is static; no autoplay; the shared E2E
      fixture runs with reduced motion while asserting this route.
- [ ] **Offline** — SW-cached HTML; external store links still navigate
- [x] **Standalone PWA launch into this page** — renders installed guidance with
      four post-install tips and leaves static education visible. Covered by
      `welcome-download-install.spec.ts`.

## Interactions

### Hero CTAs

- [x] **"Create your account"** (link, primary) →
      `buildPublicAuthEntryPath({ mode: 'signup', entrySource: 'welcome-download' })`.
      Covered by `welcome-download-install.spec.ts`.
- [x] **"Sign in on the web"** (link, secondary) →
      `buildPublicAuthEntryPath({ mode: 'signin', redirectPath: '/', entrySource: 'welcome-download' })`.
      Covered by `welcome-download-install.spec.ts`.

### Platform cards (`PLATFORMS`)

- [x] **iOS "App Store" link** (anchor, `external`, `target="_blank"`,
      `rel="noopener noreferrer"`) → `OSHUN_APP_STORE_URL`. Covered by
      `welcome-download-install.spec.ts`.
- [x] **Android "Google Play" link** (anchor, external) →
      `OSHUN_PLAY_STORE_URL`. Covered by `welcome-download-install.spec.ts`.
- [x] **Web (PWA) "Install from this browser"** (`PwaInstallTriggerButton`) —
      triggers the deferred `beforeinstallprompt` when available
  - Unavailable state: no prompt renders before the browser event.
  - Standalone state: installed guidance renders while static education controls
    remain visible.
  - Note copy: "Chrome and Edge can show a direct prompt. Safari on iPhone and
    iPad uses Share > Add to Home Screen."
  - Covered by `welcome-download-install.spec.ts`.

### Browser install guides

- [x] **Three guide cards** (article, `data-download-install-step={id}`) —
      non-interactive; visual reference with ordered steps. Covered by
      `welcome-download-install.spec.ts`.

### Install callout

- [x] **"Install from this browser" CTA** (PwaInstallTriggerButton) — second
      instance of the install trigger inside the callout. Covered by
      `welcome-download-install.spec.ts`.

### Preview grid

- [x] **Four `<figure>`s** (`data-download-preview-card={title}`) — lazy-loaded
      screenshots; `<Image>` from `next/image` with explicit `sizes`; each
      referenced `/screenshots/*.png` asset returns PNG bytes. Covered by
      `welcome-download-install.spec.ts`.

### Deep link cards

- [x] **Six `<code>` cards** — read-only (no click handler); document the
      `oshun://` scheme. Covered by `welcome-download-install.spec.ts`.

### Footer CTAs / nav

- [x] **"Sign in to the shell"** → signin redirect `/`. Covered by
      `welcome-download-install.spec.ts`.
- [x] **"Create a new account"** → signup. Covered by
      `welcome-download-install.spec.ts`.
- [x] **Footer "Home" / "Dashboard" / "Download" links**. Covered by
      `welcome-download-install.spec.ts`.

### `<PwaInstallPrompt />`

- [x] **In-app install banner** — appears when `beforeinstallprompt` fires;
      callout trigger reaches installed guidance; dismissible cooldown is
      covered by `pwa-install-update-offline.spec.ts`.

## Data & contracts

- **Reads**:
  - `OSHUN_APP_STORE_URL`, `OSHUN_PLAY_STORE_URL`,
    `OSHUN_CUSTOMER_DOMAIN_LIST_COPY` from `@/lib/mobile-store-links`
  - `buildPublicAuthEntryPath` from `@/lib/public-entry`
- **Writes**: none from `page.tsx`; install dismissal state managed by
  `PwaInstallPrompt`
- **Realtime**: none
- **Caching**: SSR static; SW cache; lazy-loaded screenshots
- **Auth**: anon (in middleware `PUBLIC_PREFIXES`)

## Cross-references

- Shell PWA behavior:
  [`shell/03-pwa-behavior.md`](../../shell/03-pwa-behavior.md)
- Journey:
  [`../../journeys/install-as-pwa.md`](../../journeys/install-as-pwa.md)
- Sibling public surfaces: [`welcome.md`](./welcome.md),
  [`welcome-domains.md`](./welcome-domains.md), [`landing.md`](./landing.md)
- Component sources:
  - `apps/oshun/web/src/components/PwaInstallPrompt.tsx`
  - `apps/oshun/web/src/components/PwaInstallTriggerButton.tsx`
  - `apps/oshun/web/src/components/SmartAppBanner.tsx`
  - `apps/oshun/web/src/lib/mobile-store-links.ts`
- E2E evidence:
  - `apps/oshun/web/e2e/welcome-download-install.spec.ts`
  - `apps/oshun/web/e2e/pwa-install-update-offline.spec.ts`

## Open questions / known gaps

- [ ] Native Safari cannot emit `beforeinstallprompt`; Chromium automation
      verifies the iOS SmartAppBanner and Safari copy, but a manual/device pass
      is still needed for true Safari install affordance behavior.
- [ ] Confirm `OSHUN_APP_STORE_URL` and `OSHUN_PLAY_STORE_URL` point at live
      store listings vs placeholder
- [ ] Deep-link cards display verified read-only `oshun://` schemes; installed
      native app registration for those schemes remains unverified on
      iOS/Android.