This plan implements the product requirements in the application specification, the top-level data model, the AI operations specification, the AI connection specification, the core Dictionary specification, and the initial Reading and Conversation module specifications.
- Vite, React, and TypeScript single-page application
- Static GitHub Pages deployment and installable PWA
- IndexedDB persistence through typed repositories
- Browser Web Workers and a durable local job queue for extraction and analysis
- Hash routing so deep links work without server rewrites
- Build-time discovered first-party module packages and language packs for the MVP
The core application owns the local workspace, library, learner profiles, learning items, progress evidence, review scheduling, AI operation boundary, and module SDK. Learning modules consume those services without placing module-specific behavior in the core. A new module contributes its manifest, navigation icon, routes, settings, jobs, storage migrations, and tests from its own package. The host discovers those contributions at build time, so adding a module requires no handwritten feature changes to the core.
The MVP is entirely client-side. Repositories, jobs, AI operations, identity, and synchronization use transport-independent interfaces so later server implementations can replace local adapters without rewriting modules.
- Scaffold the Vite React TypeScript PWA and establish formatting, linting, type-checking, and test commands.
- Add hash routing, GitHub Pages base-path handling, a web manifest, service worker, and automated Pages deployment.
- Add IndexedDB schema versioning, typed repositories, backup export/import, and local reset.
- Build a local-workspace application shell with onboarding, navigation, and error handling.
- Define the relational model for users, language profiles, content, learning items, variants, occurrences, evidence, reviews, and module state.
- Define typed contracts and registries for:
LearningModuleLanguagePackContentImporterAnalysisProviderReviewActivity
- Build a
defineLearningModuleSDK, manifest schema, module test harness, and module scaffold. - Build a non-navigable
defineLearningTechniquecontract and generated technique registry for reusable strategies such as diglot weave. - Generate the first-party module registry from module entry points during the build.
- Add one generic
/modules/[moduleId]/[[...path]]host route and derive top-level navigation from each module manifest. - Let modules contribute namespaced settings, jobs, migrations, commands, and event handlers without editing core feature code.
- Reject duplicate IDs, incompatible contract versions, undeclared capabilities, route conflicts, and invalid icons during the build.
- Add immutable interaction and evidence events with idempotency keys.
- Add versioning for documents, analyses, modules, and language packs.
- Define a curated AI operation registry with typed inputs, typed outputs, caller capabilities, usage policy, and audit metadata.
- Put transport behind the operation dispatcher: direct browser execution for the MVP and a future authenticated server-function transport.
- Implement a Mandarin pack with Simplified Chinese, pinyin with tone marks, word segmentation, and dictionary-backed sense validation.
- Implement a Japanese pack with kanji/kana, Hepburn romanization, morphological tokenization, and inflection-aware dictionary validation.
- Implement a Korean pack with Hangul, Revised Romanization, morphological tokenization, and lemma-aware dictionary validation.
- Add versioned golden corpora covering segmentation, alignment, romanization, punctuation, and overlapping phrases.
- Support pasted text,
.txt,.md, EPUB, and web-article URLs. - Normalize all formats into documents, sections, and semantic blocks with stable source offsets.
- Preserve originals or source URLs and create versioned derived content.
- Process imports in browser workers with queued, extracting, analyzing, ready, and failed states.
- Sanitize rendered content and document that URL import works only when the source permits browser CORS; provide paste or upload as fallback.
- Add a Settings form for an OpenAI-compatible API base URL, masked API key, and model.
- Persist the connection in IndexedDB with a warning that browser storage cannot securely protect a key from code running on the same origin.
- Implement HTTPS URL validation, browser-CORS diagnostics, and a synthetic connection test.
- Implement the browser OpenAI-compatible adapter behind the AI operation gateway so modules never access credentials or arbitrary provider requests.
- Implement initial operations for contextual text analysis, target-variant proposal, answer evaluation, and conversational turn generation.
- Generate context-aware source spans and target-language variants through schema-validated AI output.
- Validate generated forms, romanization, and senses through the active language pack and dictionary sources.
- Persist confidence, provenance, analysis version, and validation results.
- Keep ambiguous or unsupported candidates out of automatic weaving.
- Support user corrections and versioned reanalysis.
- Implement diglot weave as a reusable, non-navigable technique package.
- Add deterministic candidate ranking, daily introduction budgets, one-day overrides, explicit “learn this” actions, meaning-aware substitution, overlap rules, layered help, and evidence mappings.
- Prove the technique contract against module-neutral text fixtures.
- Implement the Reading module as a self-contained package according to its module specification and the shared module authoring contract.
- Register its top-level icon, route tree, settings, background jobs, migrations, and event handlers through its manifest.
- Consume diglot weave as the module's initial reading technique.
- Build the library, import, reader, reading-progress, text-settings, and offline-reading surfaces.
- Preserve chapter structure from EPUB, Markdown, and explicit text headings, with per-chapter analysis and navigation.
- Support context-aware English word selection with read aloud, one-occurrence replacement, and explicit addition to the ongoing weave.
- Reuse introduced items in all validated later occurrences, including lazily refreshed existing documents.
- Implement the Conversation module as a self-contained package with top-level navigation and routes.
- Build locally persisted chat threads and messages with streaming or progressive response status, retry, edit-and-resend, and deletion.
- Generate assistant turns through the curated
conversation.generateTurnAI operation. - Preserve canonical assistant text and apply the shared diglot weave technique as a versioned presentation plan.
- Use the same daily introduction budget, learning state, Dictionary, and evidence services as Reading.
- Expose only approved, bounded AI operations to the module.
- Implement matching, fill-in-the-blank, and constrained sentence-construction activities.
- Add scheduling that balances recognition and production.
- Derive internal confidence and the visible Learning, Familiar, and Mastered tiers from immutable evidence.
- Require evidence over time and across review modes before Mastered.
- Add the core Dictionary tab for searching and filtering the user's tracked learning items, inspecting variants and history, and changing tiers.
- Add manual tier changes, resets, progress summaries, due counts, and item history.
- Cache the application shell and explicitly opened or downloaded reading content.
- Persist interactions locally by immutable event ID.
- Keep imported and generated content available offline; AI calls and URL imports require connectivity.
- Complete onboarding, library, reader, review, progress, and settings flows.
- Complete local-data privacy, API-key warning, upload, CORS failure, and content-sanitization reviews.
- Add accessibility coverage for reader interactions and review activities.
- Add local diagnostics, job status, and AI usage summaries without retaining prompt content.
- Add backup import/export, local data deletion, schema recovery, and GitHub Pages deployment procedures.
- Platform foundation precedes persisted feature work.
- Core contracts and the domain model precede language packs, imports, analysis, the reader, and reviews.
- The module and technique SDKs, generated registries, and generic host route precede implementation of any learning module.
- The transport-independent AI operation gateway precedes any module AI calls.
- Language packs and normalized imports both precede AI-assisted analysis.
- Analysis and learner-item state precede the shared diglot weave technique.
- The diglot weave technique precedes Reading and Conversation integration.
- Stable module interactions and evidence precede final review scheduling and progress reporting.
- Future synchronization contracts are proven against immutable local interaction events.
- Hardening is continuous, followed by a focused pass over the complete end-to-end system.
The complete logical model and ownership rules are defined in the top-level data model.
- Workspace: local workspace identity, preferences, schema version, and future synchronization metadata.
- Learning: language profiles, learning items, target variants, user-item state, tier history, evidence events, review schedules, and attempts.
- Content: library items, source files or URLs, document revisions, sections, blocks, analysis jobs, occurrences, and corrections.
- Modularity: module manifests and versions, profile-module settings, language-pack versions, and typed module state.
- Operations: idempotent jobs, import failures, AI usage and cost metadata, and audit timestamps.
All private data is scoped to the local workspace ID. Repository constraints must protect span and state integrity. Browser jobs and event replay must be idempotent.
- Unit tests for tier transitions, evidence weighting, daily caps and overrides, candidate ranking, sense disambiguation, span overlap, display toggles, and idempotent replay.
- Golden language tests for Mandarin segmentation and pinyin, Japanese inflection and romanization, Korean morphology and romanization, punctuation, and mixed-script display.
- Contract tests for every language pack, importer, analysis provider, module, and review activity.
- Integration tests for all import formats, workspace isolation, job retries, corrections, versioning, backup restore, and schema migration.
- End-to-end tests for onboarding, import, first weave, reveals, “learn this,” cap overrides, later substitutions, all review types, tier movement, and offline replay.
- Accessibility checks for keyboard use, screen readers, focus, reduced motion, contrast, and non-color state cues.
Included:
- English source texts
- One target language per profile and text
- Mandarin, Japanese, and Korean language packs
- Local browser profiles and progress in IndexedDB
- A locally persisted OpenAI-compatible API URL, key, and model with an explicit browser-storage warning
- Curated, typed AI operations with a replaceable future server transport
- Paste, text/Markdown, EPUB, and URL imports
- Deliberate diglot weaving
- Reading and Conversation modules that share the diglot weave technique
- Three visible tiers for tracked items, with unintroduced candidates excluded from the user's learning set
- A core Dictionary tab for the user's tracked words, phrases, and constructions
- Matching, fill-in-the-blank, and sentence-construction reviews
- Installable PWA with limited offline reading
Deferred:
- Native mobile applications
- Arbitrary source languages
- Speech recognition and pronunciation grading
- Social and classroom features
- A community content marketplace
- Arbitrary third-party runtime plugins
- Full free-form essay grading
- Redistribution of imported copyrighted texts
The writing mockup now uses the approved monoline direction for five characters. This records the implementation handoff; it does not add a production activity or expand the MVP scope above.
- Treat external stroke data as versioned language-pack assets, not a live service or a dependency on a particular practice engine. Pin the upstream release/commit and retain original outlines, ordered medians, source hashes, attribution, and license. The prototype uses Hanzi Writer Data 2.0.1; its source and derived artwork retain the bundled ARPHIC PUBLIC LICENSE.
- Key artwork by character and language/script/locale variant. The same Unicode character does not guarantee the same regional form or stroke order.
- Separate the source snapshot, declarative reviewed stroke recipes, generic transformation logic, and generated output. Recipes select stroke bodies; shared rules handle line/curve fitting and conservative terminal correction. Do not embed per-character drawing coordinates in the exercise UI.
- Prefer a reproducible asset-preparation/build step that produces approved, normalized stroke paths and matching samples. Record source, recipe, transform, and style versions, coordinate bounds, reference width, stroke order, and review status in the generated artifact. The prototype's style uses a 100-unit box, width 5.5, and rounded caps/joins.
- Bulk transformation produces candidates, not automatic approval. Validate numeric geometry, bounds, stroke counts/order, turns, hooks, and sampling, then review representative glyphs and flagged exceptions. Publish only approved refined assets. Keep a clearly identified, supported original style or show an explicit unavailable state for missing artwork; never silently invent it. An invalid approved artifact is an error, not permission to substitute a different glyph. The prototype has five reviewed recipes, not a full font.
- Expose artwork through a typed, versioned language-pack asset contract consumed by the writing activity. Keep the renderer and tracing engine replaceable. If Hanzi Writer's engine is selected later, adapt the approved geometry to its data contract; using its engine must not silently restore its stock brush artwork or its original matching medians.
- Use the same approved paths for reference artwork, next-stroke guidance, demonstrations, completed strokes, and the geometry used for matching. Derive matching samples from those paths; never display corrected geometry while grading against uncorrected medians. Scale drawing input and SVG with the same aspect-preserving transform. Size guidance markers for short dots.
- Bundle or explicitly download and cache approved packs for offline use. Drawing/tracing must not require remote assets, an LLM, or a recognition service. Keep source-data licenses and modification notices accessible with the distributed assets; independently authored application code remains separate from the licensed artwork.
- Treat reference width as part of the artwork style because round-cap compensation changes endpoints. Display-size changes only scale the artifact. If configurable reference widths are supported, regenerate or select both artwork and matching geometry together under the same versioned style.
- Persist ordered learner strokes, character/locale and artwork version, phase/assistance, repetition, and attempt state through the normal local activity repositories. Resume against the same artifact; do not switch geometry halfway through an attempt after a pack update.
- In memory practice, reveal only the current stroke after two rejected attempts on that stroke. Keep later strokes hidden and return to unassisted input for the next stroke. Persist per-stroke misses and revealed assistance within the repetition; interruptions do not count. Undo restores the revisited hint state, while Clear and a fresh repetition reset it. Assisted strokes must remain distinguishable from unaided recall in recorded results.
- Keep tracing feedback distinct from handwriting recognition and writing-skill mastery. Record assistance and what was actually assessed; completing guided repetitions must not imply unsupported recognition or an all-skill mastery score.
Use shared geometry tests and visual golden cases for the approved glyphs, including straight/slanted strokes, small dots, vertical hooks, and compound turns. Cover correct/reversed/off-path input, pointer cancellation, undo/clear, all guidance phases and repetitions, navigation/resume, small screens and stylus/touch input, offline asset availability, missing/corrupt/version-changed packs, and provenance/license packaging. The browser-script prototype is a reference for the intended appearance and behavior, not the production asset pipeline or persistence layer.
| Risk | Mitigation |
|---|---|
| Incorrect one-to-one translation | Contextual spans, construction-level items, dictionary validation, confidence gates, and user corrections |
| Romanization becoming a crutch | Show it by default only while Learning, then keep it available on demand |
| Too many substitutions harming comprehension | Daily budgets, spacing rules, deterministic planning, and explicit overrides |
| AI inconsistency or cost | Versioned structured output, caching, validation, explicit failures, and provider budgets |
| Browser-stored API key exposure | IndexedDB instead of localStorage, prominent warning, strict CSP, dependency review, no logs or default exports, and an easy clear-key action |
| Opaque automatic mastery | Visible tiers, evidence history, conservative promotion, and manual overrides |
| Browser CORS restrictions | Connection diagnostics and paste/file fallback when an AI endpoint or article source disallows browser access |
| Local data loss | Versioned IndexedDB migrations plus explicit backup export/import |
| Import security or ownership issues | Sanitization, size limits, source attribution, and a private local library |