← Selected work

A project by Jason Maitland / Learn & explore

Kaiyan · 开眼

Keep the language inside the story.

A Chinese–English reading product built around two directions of learning: read, listen, explore a word, save it in context and come back to the text.

In practiceThe public reader keeps pinyin attached to its Chinese text across desktop and mobile, so pronunciation stays with the passage being read.

Public web appPrivate sourceActive development
Explore the product
Kaiyan reading Rainy Evening with a contextual definition for evening and story audio controls.View full size ↗
In the project

A word stays attached to its sentence. Rainy Evening brings pinyin, meaning and prepared listening into one reading view.

About this image

Public interface · signed-out visitor · 7 September 2026
Revision: Image 87fd95e9e2f7

The problem

Language tools often scatter reading, pronunciation, lookup and review across separate experiences. The interruption makes it harder to stay with a story—and harder to remember why a saved word mattered.

What I built

A web-led bilingual reader with contextual vocabulary, offline lookup, listening, review, whole-book import and durable reading positions, alongside a native client direction.

The interesting part

The reader has to keep text, pronunciation, saved meaning and personal progress attached to the same source even as layout, devices and optional audio services change.

My contribution
Project creator responsible for the reading experience, language support and continuity of private learner state.
Evidence
Public reader captures and dated desktop/mobile checks of book recovery, account conflicts and paired-pinyin layout.
Access
Private source; public web reader. Personal reading material and learner state are private.
My decisions & how it was built
What I own
I shape the reading, lookup and review loop, and connect source text, saved vocabulary and private progress so a learner can leave and return.
A decision I made
I kept whole-book text separate from learner-state sync, allowing progress to travel without silently uploading a private manuscript.
What it builds on
Authored annotations and licensed offline dictionaries supply core language help. Browser storage holds book records, and separate local speech services supply optional audio; Kaiyan connects these around stable source locations.

01 / The work

Keep the learner in the story.

Two learning directions, one continuous habit.

Kaiyan is shaped around a household problem: an English-speaking learner reading Chinese and a Chinese-speaking learner reading English. Each direction has its own library, progress and review history, while interface language remains a separate choice.

The loop is deliberately small. Find something worth reading, reveal the support needed, save a useful word, review it in its sentence and return to the story. Optional features have to make that loop easier rather than replace it.

A word keeps its place in the sentence.

Tapping a word opens meaning, pronunciation and alternatives beside its source context. Authored annotations take priority; licensed offline dictionary data supplies deterministic fallback. A missing entry is shown as missing instead of being replaced with a plausible invented definition.

Saved vocabulary retains its reading and source anchor. Pronunciation can depend on the occurrence, so audio reuse follows context and pronunciation identity rather than only the written word. A review card can lead back to the passage that made the word useful.

A whole book needs a different data model.

A novel cannot be treated as a very large lesson object. Kaiyan separates Book, Chapter and Block records, keeps source bodies in a local book store and renders a bounded window of text. Reading positions use stable block identities and Unicode-scalar offsets, so line wrapping does not become a fragile bookmark.

Imports have a preview, provenance and validation before they enter the library. Whole-book text is kept outside the compact learner-state sync document. Signing in can carry progress without silently uploading the manuscript. Re-import, offline return and recovery are part of the reading journey.

Readable support has to survive a narrow screen.

A pronunciation line that looks tidy on desktop can detach from its Chinese characters on a phone. The September readability work made Chinese text and pinyin inseparable vertical pairs across readings, context cards, vocabulary and review. Source selection and speech offsets stay anchored to the original text.

Listening controls needed the same restraint. Unused audio controls scroll away; starting playback brings a compact transport into view. Expanding it respects the measured header instead of covering the passage. These changes came from inspecting the actual reader, including long context cards and small screens.

An unavailable service must not erase the learner.

First-user preparation found problems around failed initial sync, stale clients and content startup. The follow-up protects existing state when a load fails, carries deletions through conflicts and preserves legitimate review events from more than one device. Private offline access is an explicit choice, and sign-out removes its private local state.

The application and durable data now run on owned local hardware, with the public edge acting as transport. Optional Studio speech also has a local service boundary. The deterministic reader remains useful without treating a model as the authority for word meanings.

The next test is a learner’s first week.

The 28 September release record includes public desktop and mobile reading, paired pinyin, cached narration playback and account conflict recovery. Its content audit checked 186 catalogue bodies. A small optional starting-point check offers provisional reading and listening guidance; it is not a certified language assessment.

The next evidence is human: an actual first session, listening to the prepared narration, using the intended device and returning the next day. The existing screenshots show an earlier signed-out reader state; the latest paired-pinyin changes are described here but are not pictured.

How it connects

Return to the sentence.

Reading, help and repetition work best when they remain connected.

  1. 01

    Read & listen

    Choose a public passage and use its prepared narration.

  2. 02

    Notice a word

    Open meaning and pronunciation in the context of the sentence.

  3. 03

    Come back

    Resume the reading from Today; saved words have their own review path.

The captures use a signed-out visitor and device-local progress. No private account or personal library is shown.
Diagram source

Verified workflow diagram · reviewed 7 September 2026
Source revision: 955cedd1dd0a

03 / Choices & trade-offs

The decisions that shaped it.

01

Make core language help deterministic

Authored context and licensed offline dictionaries supply meanings and pronunciation. Optional model-generated help can enrich a passage without becoming its dictionary.

02

Separate source text from learner state

Whole-book bodies, annotations, progress and derived audio have different lifecycles. Keeping them separate makes private imports, bounded reading and recovery manageable.

03

Reuse contracts across native clients

Stable identifiers, source anchors, content schemas and behaviour fixtures are shared. Native platforms can use their own storage, speech and accessibility tools instead of inheriting one view hierarchy.

04 / Iteration

What changed along the way.

  1. Reading loop

    Connect lookup to review

    Structured bilingual passages, contextual saves and separate learning directions formed the initial daily-use experience.

  2. Whole books

    Keep long-form reading bounded

    Portable source contracts, local imports, chapter windows and stable anchors extended the product beyond short lessons.

  3. First-user preparation

    Refine what happens after a failure or a return

    Account recovery, cautious placement guidance, compact listening controls and paired pinyin addressed the real first-session journey.

05 / Under the hood

For the curious.

Architecture, implementation and the details behind the interface.

Stable source locations

Book → Chapter → Block records use explicit source anchors. Unicode-scalar offsets keep selection and saved context consistent between browser and native implementations.

Local reading and optional speech

IndexedDB holds browser book records; the offline shell and pinned lexicon support return visits. Prepared Studio audio is cached behind a separate local service and reused by exact context.

Continuity without silent loss

Versioned learner state, guarded hydration and conflict handling protect reading progress. Review histories are merged as events so one device does not discard another device’s study.

06 / Current state

Where it stands.

What exists today

The web reader is available. Native clients are being developed separately; the next learner review will test the reading and listening experience on their actual device.

Where I’m taking it

  • Complete the first learner’s reading, lookup, listening, saving and review journey on the device they will actually use, then check the next-day return.
  • Listen to the exact starter narration for pronunciation and teaching quality.
  • Extend native parity, private-library ownership and backup workflows through the same portable contracts.

Another thread to follow

Calidaw

A music studio humans and agents can play together.

Continuum

The system behind everything I build.

Have something like Kaiyan · 开眼 in mind?