02

Bối cảnh

Đây là prototype nghiên cứu và proof of integration, không phải viewer hoàn chỉnh hay bản sao chính thức của game. Core tests chỉ dùng fixture tự viết và không yêu cầu asset có bản quyền.

This is a research prototype and proof of integration, not a finished viewer or an official game replica. Core tests use hand-written fixtures and require no copyrighted game assets.

03

Ràng buộc

• Parser chỉ hỗ trợ subset AFF được tài liệu hóa; unsupported input phải trả diagnostics có cấu trúc.
• Domain, timing và renderer logic phải nằm trong Rust thay vì được viết lại trong TypeScript.
• Browser boundary dùng contract JSON có version để giảm coupling và làm lỗi tích hợp dễ quan sát.

04

Vai trò của tôi

Thiết kế workspace Rust, domain model, parser subset, timing map, renderer scene, WASM DTO boundary và browser vertical slice.

Designed the Rust workspace, domain model, AFF-subset parser, timing map, renderer scene, WASM DTO boundary, and browser vertical slice.

05

Kiến trúc

• crates/core định nghĩa chart domain types độc lập với browser.
• crates/parser tạo chart hoặc structured diagnostics từ AFF fixture.
• crates/timing xây timing context và playback snapshot; crates/renderer tạo scene IR và deterministic SVG.
• crates/wasm xuất versioned JSON envelope cho apps/web gọi từ React/Vite.

06

Quyết định kỹ thuật

• Không viết lại parser/timing/renderer trong TypeScript để giữ một nguồn sự thật cho correctness.
• Dùng SVG debug preview xác định được trước khi tối ưu visual fidelity hoặc animation.
• Dùng legal fixtures tự viết để tách nghiên cứu kỹ thuật khỏi dữ liệu game có bản quyền.

07

Kiểm thử và validation

• cargo test --workspace kiểm tra các Rust crates.
• pnpm check chạy format, clippy, Rust tests, WASM build, frontend type check, unit tests và production build.
• CI thực thi Rust fmt/clippy/tests, WASM package build, frontend tests và production build trên clean runner.

08

Observability

• Browser hiển thị structured diagnostics và primitive counts để kiểm tra kết quả parser/renderer thay vì chỉ trả màn hình trống.

09

Bảo mật

• Core fixtures không chứa chart hoặc asset được trích xuất từ game; browser prototype không có account, backend hoặc dữ liệu người dùng.

10

Failure modes

• AFF ngoài subset, malformed input, WASM contract mismatch hoặc frontend build không tương thích.
• SVG hiện là debug renderer và không đại diện cho official scroll physics.

11

Kết quả hiện có

• Vertical slice hiện có thể load fixture hợp lệ, parse bằng WASM, trả diagnostics, chọn playback time, dựng Rust scene và render SVG cùng các primitive counts.
• Chưa công bố benchmark performance, replay, audio sync, analytics UI hay offline cache.

12

Bài học

• Contract có version và deterministic fixtures giúp tách lỗi parser, timing, rendering và browser integration rõ hơn.

13

Bước tiếp theo

• Cải thiện ergonomics cho fixture selection, malformed examples và render controls trước khi mở rộng analytics hoặc replay.