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#

• Loading — N/A; static server component; no route-local fetch or skeleton exists in page.tsx.
• Default desktop — full grid; install prompt button visible. Covered by welcome-download-install.spec.ts.
• Mobile (SmartAppBanner showing) — iOS SmartAppBanner renders while iOS, Android, and Web (PWA) cards remain visible. Covered by welcome-download-install.spec.ts.
• PWA install available (Chrome/Edge) — PwaInstallTriggerButton / PwaInstallPrompt becomes active when beforeinstallprompt fires. Covered by welcome-download-install.spec.ts.
• 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.
• 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.
• 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
• 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#

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

Platform cards (PLATFORMS)#

• iOS "App Store" link (anchor, external, target="_blank", rel="noopener noreferrer") → OSHUN_APP_STORE_URL. Covered by welcome-download-install.spec.ts.
• Android "Google Play" link (anchor, external) → OSHUN_PLAY_STORE_URL. Covered by welcome-download-install.spec.ts.
• 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#

• 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#

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

Preview grid#

• 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#

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

Footer CTAs / nav#

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

<PwaInstallPrompt />#

• 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
• Journey: ../../journeys/install-as-pwa.md
• Sibling public surfaces: welcome.md, welcome-domains.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.