V1 Web PWA · Surface walkthrough

V2 — Combat Glossary (Sophia-backed)

A per-surface walkthrough of the V1 Web PWA customer surface: layout, states, interactions, data, and cross-references.

walked
8sections2 minread
Markdown source
On this page

Context. surface customer · domain v2-knowledge · route /v2/glossary · auth anon · source apps/oshun/web/src/app/v2/glossary/page.tsx

Last walked. 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

Out of V1 scope. Documented for completeness; route exists under apps/oshun/web/src/app/v2/glossary/page.tsx.

Purpose#

Searchable fighting-game language reference: frame advantage, meaty, rollback, hitstop, hitlag, kara cancel, OS, shimmy, frame trap, ukemi, and community slang. Same V2KnowledgeSurface component as /v2/wiki and /v2/roadmap; differs only by the 'glossary' surface-id passed to buildV2KnowledgeSurfaceModel.

Entry points#

  • Sub-nav "Glossary" item from any V2 page
  • "Sophia knowledge → Glossary" panel link on /v2
  • Direct URL / bookmark — yes, anon
  • Inbound link from tutorials / commentator surfaces (when V2 ships)

Layout regions#

page.tsx is an async server component: const model = await buildV2KnowledgeSurfaceModel('glossary'); renders <V2KnowledgeSurface model={...} />. Identical layout to /v2/wiki.

  • Header: LWebShell chrome — customer nav + V2 sub-nav (active="glossary")
  • Section head: kicker "Sophia RAG / terminology", title "Combat glossary"
  • Coverage strip: 3 metrics (answer citations / source documents / average confidence)
  • RAG answer panel: composed glossary answer with citation chips
  • Entries panel: term entries with body, metrics, citations
  • Citations rail: per-citation cards (label / title / source / section / confidence / excerpt)

States#

  • Loading — server-rendered
  • Empty — N/A
  • Populated — glossary entries from buildV2KnowledgeSurfaceModel('glossary')
  • Error — N/A in current local impl
  • Offline — cacheable
  • Gated — N/A, anon
  • Standalone PWA — clean render

Interactions#

Top chrome#

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

Citation chips#

  • Citation chip — anchor to matching citation card in the rail
    • Keyboard: tab-focusable; enter activates
    • Screen reader: announces label + linked title

Entries#

  • Per-entry citation chips — same anchor behavior

Data & contracts#

  • Reads: buildV2KnowledgeSurfaceModel('glossary') → V2KnowledgeSurfaceModel
  • Writes: none
  • Realtime: none
  • Caching: static (local corpus); SWR/ISR when swapped to real @sophia/client target
  • Auth/role check: anon

Cross-references#

Open questions / known gaps#

  • Same local-Sophia swap concern as /v2/wiki
  • No alphabetical jump-list or quick search field within the glossary
  • No bookmark / pin per term