hua-wen-reader-ui

The reader surface for Hua Wen Reader — a kang-components UI that reads Chinese news articles classified by HSK level, with per-article simplified versions and tap-for-phonics vocabulary.

It is built once and mounted in two places:

• a standalone Hua Wen Reader app (its own thin shell), and
• as an opt-in add-on inside xunzi.

Tracked by xunzi epic #552 (children #553–#558).

Architecture

• Layer 1 — primitives: kang-components (shared, domain-free).
• Layer 2 — this package (a "surface"): views + typed API client + local logic, exposing a Mount that takes a host-injected context (identity?, theme/spring, navigate, host).
• Layer 3 — shells: the standalone app and xunzi each provide their own navigation; this surface never owns the shell.

Data-plane split: the Go backend serves anonymous public content only; per-user state (read / saved / vocab-seen) lives in Gun, keyed on the shared identity when mounted inside xunzi. No auth is added to the Go API.

Backend API (consumed as-is; GET-only, anonymous, CORS *)

| Endpoint | Returns | |---|---| | GET /api/articles | paginated list; filters hsk_level (1–9), source_id, topic (10 fixed), sort_by/sort_dir | | GET /api/articles/{id} | { article, simplified_versions[] } | | GET /api/sources | RSS sources | | GET /api/search?q= | up to 50 articles | | GET /api/stats | counts incl. articles_by_hsk_level |

JSONB shapes (pinned Phase 0 — the Go models pass these through opaquely)

vocabulary_json and definitions_json are VocabularyEntry[] | null:

interface VocabularyEntry { word: string; pinyin: string; meaning: string; hsk_level?: number }

Article.vocabulary_json is parsed defensively (parseVocabulary) because the original column was not guaranteed to be an array. character_set is simplified | traditional (verify against GET /api/sources on the live instance during Phase 1). Topics: 政治 / 经济 / 科技 / 文化 / 科学 / 体育 / 健康 / 国际 / 社会 / 其他.

Phonics

Per-word pinyin ships in the data; the original frontend's ChineseText.tsx + lib/phonetics (longest-match tokenization, tap tooltips, pinyin→zhuyin + tone sandhi) is the reference implementation to port. When mounted in xunzi, the phonetic-system and tone-sandhi controls bind to xunzi's phonic / useSandhiTones preferences via the host context.

Develop

npm install
npm run dev      # Vite dev server; proxies /api → VITE_API_TARGET (default http://localhost:8080)
npm test         # vitest
npm run build    # tsc -b && vite build

Node ≥ 20 for the toolchain (matching the xunzi ecosystem).

Status

Phase 0 scaffold: toolchain (Vite + React 18 + styled-components + TanStack Query

• React Router) + pinned API types + a proving test. kang-components is added in Phase 1 (#554) with the first views that consume it.