V2 — Fighting-game shell tile

Out of V1 scope. Documented here because the route exists in apps/oshun/web/src/app/v2/page.tsx and ships with V1 builds. The route is covered by the broader Oshun PWA shell but is not in the V1 feature map.

Purpose#

The V2 fighting-game web surface running as a tile inside the shared Oshun shell, not as a standalone Next.js app. Renders the V2 stack ledger: shell-core clients, auth-feature counts, persistence contracts, developer-portal doc, retired standalone stack. Read-only — V2 product surfaces live under /v2/wiki, /v2/glossary, /v2/roadmap.

Entry points#

• Direct URL / bookmark — yes, anon
• Sub-nav "V2" item rendered by LSubNav on any V2 page
• Inbound link from /explore sub-nav (no card today)
• Linked from WALKTHROUGH/matrix/coverage.md "Out-of-V1 (excluded)" section

Layout regions#

page.tsx builds V2ShellTileModel from buildV2ShellTileModel() and mounts V2ShellSurface. Surface composes LWebShell with a top chrome (LCustomerNav active="explore" + LSubNav active="v2" with five tabs: Featured/Collections/V2/Wiki/Roadmap).

• Header: shell chrome — customer nav + V2 sub-nav
• Back link: <- Explore link at top
• Section head: kicker "V2" + title "Fighting game operations, inside the shell." + right chip "Shell-native"
• V2ShellTile: the canonical capability table (route, title, eyebrow, summary; serialized data-testid="v2-shell-tile")
• v2-shell-grid: 4 panels
  • Client surface — model.clients[] (@oshun/shell-core, @oshun/auth-client, @oshun/developer-portal, @oshun/persistence)
  • Shell map — model.shellEntryPoints[] (primary visibility from listConsumerShellEntryPoints) as links to canonical PWA routes
  • Persistence — first 6 of model.persistenceContracts[] (V1 object + enum contracts grouped by domain)
  • Developer portal — model.developerDoc (slug v2/shell-surface, section integrations, version)
  • Sophia knowledge — three links to /v2/wiki, /v2/glossary, /v2/roadmap (annotated @sophia/client)
• v2-shell-stack-note: retired standalone stack callout (Standalone Next.js, Sanity CMS, Contentful CMS) + route:/v2 code chip

States#

• Loading — server-rendered shell; static body, no client hydration gates
• Empty — N/A (model is deterministic; always populated)
• Populated — every panel renders rows from V2ShellTileModel; data-testid="v2-shell-surface" present
• Error (recoverable) — N/A; no fetch
• Offline — fully cacheable; SW should serve from cache
• Gated — N/A; anon-readable per PUBLIC_PATHS in proxy.ts
• Standalone PWA — renders cleanly without URL bar

Interactions#

Top chrome#

• Customer nav (LCustomerNav) — active="explore"; primary shell nav
• V2 sub-nav (LSubNav) — 5 items
  • Featured → /explore
  • Collections → /explore
  • V2 (current) → /v2
  • Wiki → /v2/wiki
  • Roadmap → /v2/roadmap

Back link#

• Explore (Link) — back to /explore

Shell map links#

• Shell entry-point links — N links rendered from model.shellEntryPoints; each links to its canonical PWA route (buildConsumerShellEntryPointHref(entry.id, 'web'))

Developer portal panel#

• Library surface (Link) — /library

Sophia knowledge panel#

• Wiki link → /v2/wiki
• Glossary link → /v2/glossary
• Roadmap link → /v2/roadmap

Data & contracts#

• Reads: buildV2ShellTileModel() (synchronous, in-process) → V2ShellTileModel
• Writes: none
• Realtime: none
• Caching: static; suitable for SSG/ISR
• Auth/role check: none — anon-readable

Cross-references#

• Sibling: v2-wiki.md, v2-glossary.md, v2-roadmap.md
• Component source: apps/oshun/web/src/components/v2/V2ShellSurface.tsx, apps/oshun/web/src/components/v2/V2ShellTile.tsx
• Model source: apps/oshun/web/src/v2/shell-tile.ts
• Scope: V2 is out of V1; see ../../matrix/coverage.md "Out-of-V1 (excluded)" section

Open questions / known gaps#

• No explicit V2-vs-V1 surface boundary documented in the user-facing UI; sub-nav implies V2 is a peer of Explore/Collections
• No outbound link from V2 surface back to the V1 customer hub other than shell-entry-point links
• Walkthrough is drafted from code-reading only — surface is forward-looking and may evolve before V2 launch