Deliver editable worksheets, accessible reading, and validated publications

[byoungd]

Problem and outcome

This change turns the bilingual reading site and offline book into a more complete reader workflow. It repairs legacy routes, metadata, dark-mode and responsive reading, keyboard and screen-reader behavior, content integrity, private assets, build reproducibility, and CI release gates. It also fixes genuine EPUB and PDF publication defects and adds generated whole-worksheet downloads so readers can preserve a complete editable record.

Cross-session examples now keep their goal, initial baseline, capacity, boundaries, evidence locations, and next task. The site explains that a file path is not evidence an AI has read that file. The EPUB has no website-only copy controls or invalid Vue attributes, and PDF preformatted text wraps within measured page bounds without shrinking the type.

The Toolkit Overview now starts with a four-line action and a complete walkthrough link, so a first-time reader can begin without scanning every worksheet route. This responds to the repository's real reader feedback about tools being difficult to use and is mirrored in both languages and offline editions.

The bilingual home page now also exposes a concrete speaking plan for readers who ask how to improve oral English: unscripted baseline, unfamiliar follow-ups, listener retelling, interaction repair, and a fourteen-day transfer check.

The homepage also states the project boundary plainly: this is an open bilingual manuscript and static reading/publication project, while the repository source supports corrections, content checks, and builds. Reader feedback decisions and the boundary of unverified third-party medical-English recommendations are recorded in QUALITY_ROADMAP.md.

The reader field note now asks for time to first saved action and non-sensitive conditions, making later reader evidence more comparable without collecting identity or private project data. The dependency tree also pins smol-toml@1.8.0 through an npm override after CI surfaced its high-severity DoS advisory.

Evidence or official sources

• Sharp security advisory
• EPUBCheck 5.3.0, fixed release archive SHA256, and Maven Central verification produce 0 errors and 0 warnings for both current editions.
• VitePress stable/next channels, Node support schedule, WCAG 2.2, and ARIA dialog/combobox guidance were checked on 2026-09-10.
• QUALITY_ROADMAP.md records evidence already obtained and the real-reader, device, assistive-technology, and reader-compatibility work that remains.

Chinese and English pages

All 78 page pairs retain their manuscript task and evidence structure. Forty-two generated editable Markdown downloads are available across both languages. No generated download is compiled as a public page or indexed as duplicate prose.

Privacy and licensing impact

Private-asset and clipboard regressions use temporary synthetic fixtures or browser mocks; no credentials are read or added. Worksheet downloads include source/CC BY-NC provenance. Existing content and code licenses remain applicable.

Editorial gates

This combines site/tooling and bounded bilingual example corrections. Dynamic source dates remain explicit. The project targets WCAG 2.2 AA and reports automated/keyboard evidence; it does not claim full WCAG conformance. EPUB accessibility metadata is descriptive and does not claim that every illustration has complete descriptions.

Verification

• npm run check: passed, including 58 Node tests, 6 PDF layout tests, 177 Markdown content checks, format checks, EPUB synchronization, and PDF semantic/hash validation.
• npm run sync:content: passed; 42 worksheet downloads and both publication editions regenerated deterministically.
• npm run docs:build: passed within existing search, theme, framework, and image budgets.
• PLAYWRIGHT_CHANNEL=chrome npm run test:smoke -- --workers=3: 554 desktop/mobile tests passed against a fresh production build and preview; the local run uses system Chrome, while Linux CI uses Playwright 1.63.0 with its managed Chromium 153.
• npm audit --audit-level=high: zero findings; git diff --check and all workflow YAML/Bash checks passed.
• python -m pip_audit -r requirements-pdf.txt: no known vulnerabilities; the pinned audit tool is part of CI and Pages validation.
• EPUBCheck 5.3.0: both current EPUBs 0 fatals / 0 errors / 0 warnings; offline 320px reading traversed 130 XHTML files with no missing images or horizontal overflow.
• PDF: six layout tests including full published bilingual code-boundary scans passed; affected Chinese pages 267, 269, 285 were rendered and visually checked for clipping.
• Performance baseline: fresh Chromium contexts under Fast 3G/Slow 3G measured first paint, DOMContentLoaded, load, transfer size, and resource count across four representative routes; results and limitations are recorded in QUALITY_ROADMAP.md. The current bottleneck is pre-rendered HTML transfer, while the local search index remains lazy.
• READER_RESEARCH.md defines a privacy-first, repeatable protocol for future first-use and delayed-return observations; it keeps real reader evidence separate from synthetic examples and automated test claims.
• Remote CI passed remote commit 4e823cc17ff4b7aaf343c7ba515b387172e8e758: both validate and smoke succeeded on Linux, including all 554 browser tests with Playwright-managed Chromium. The local worktree is clean; GitHub API was used only because Git smart HTTP was temporarily unavailable.

This branch is pushed as a draft PR for review. It does not merge or deploy automatically.