Character Game for a Daughter with ADHD Meets cj-tauri's Silent Failures and a Drift Bug
Used the Cangjie language cj-tauri framework to make a HarmonyOS similar-character game for my kid in five minutes
My daughter is ten, in fifth grade. She's been diagnosed with ADHD and reading difficulty, and it's hard for her to keep attention on one thing for long. The doctor said to do more character-discrimination training, so I wanted to make a small game: group the similar-looking Chinese characters from grades one to five, and have her find the one that's different in a pile of look-alikes. Using one weekend, I built a similar-character game for my ten-year-old daughter (using the Cangjie language's cj-tauri cross-platform development framework).
My plan was a document I wrote first: five gameplay modes, tiered character library, reward mechanics all laid out. The hard part was never the design, it was turning it into something runnable—especially since it had to run on a computer first, then move to a HarmonyOS tablet. That's where cj-tauri shines: with the same source code, a different build configuration can produce a HarmonyOS PC build. I developed on the computer first, then ran it on the device with the same result.
This post records the whole journey: the framework choice, the three pits I fell into, and how I ended up fixing a bug in the cj-tauri upstream framework and submitting a PR.

1. Selecting the framework: why cj-tauri
The plan document originally specified Vue 3 + Phaser + localStorage, pure H5. But I wanted it to be a real application on the tablet, not a browser page—the kid would switch away, and I'd have to enable Guided Access to lock the screen. Too much hassle.
cj-tauri fits the bill: Cangjie backend + system WebView frontend. Cangjie statically compiles an exe, and the frontend is the HTML/CSS/JS I know well. Crucially, one piece of business code produces both desktop and HarmonyOS artifacts—first run on Windows desktop, and when the HarmonyOS tablet is ready, recompile for the tablet.
hanzi-game/
├── cj-tauri.toml # single source of truth: app id / window / page entry / capability manifest
├── src/ # Cangjie backend (save commands)
├── assets/ui/ # frontend: index.src.html + css/ + js/
└── tools/build-ui.js # frontend inliner (more on why it's needed later)
2. First version failed: page loaded but zero styles and zero scripts
According to the skill docs, “if the page is more than one screen, split it into assets/ui/index.html”. So I obediently split it into index.html + css/style.css + js/app.js and a few other files, writing relative references normally:
<link rel="stylesheet" href="css/style.css">
<script src="js/app.js"></script>
Compilation succeeded, and the window came up. What I saw was this:
All text was there, but no styles—the five pages I hid with display:none (home, game, results, gallery, and parent dashboard) were all stacked on one screen. And the bridge log had no errors at all:
[cj-bridge] controller ready, loading page
[cj-bridge] NavigateToString -> hr=0x00000000 ← looked perfectly fine
[cj-bridge] html navigation requested
I thought it was a CSS mistake at first, and changed it twice before realizing: JS wasn't executing either—the grade list and gameplay cards on the home page were supposed to be rendered by JS, but they were all empty. That meant the entire js/ directory wasn't loading a single file.
Looking at the framework source, I understood: PageSource.Asset reads the HTML file as a string, and the Windows side calls NavigateToString—there's no real document source, so relative-path <link href> and <script src> cannot resolve.
I wrote the diagnosis into my pitfall log: NavigateToString -> hr=0x0 is the “success” line, don't be fooled; the real criterion is whether the page's self-check line comes out.
// after the page starts successfully, send a line back to Cangjie stderr
bridge.invoke('report', { line: 'boot ok · bridged=' + bridged + ' · groups=' + groups });
Only when the log shows [frontend] boot ok · bridged=true · groups=102 does that mean the page is truly alive.
Fix: keep source in separate files, inline at build time into a self-contained page
I didn't want to stuff all CSS/JS into a ten-thousand-line HTML file just to work around this. So I added a 30-line inliner: the source remains split across files, and running node tools/build-ui.js generates a self-contained index.html.
// tools/build-ui.js core is two regexes
html = html.replace(/[ \t]*<link\b[^>]*href="([^"]+)"[^>]*>/gi,
(m, href) => '<style>\n' + readAsset(href) + '\n</style>');
html = html.replace(/[ \t]*<script\b[^>]*src="([^"]+)"[^>]*><\/script>/gi,
(m, src) => '<script>\n' + readAsset(src) + '\n</script>');
// if there are still relative references after inlining, fail immediately, don't make the next run play detective
const leftover = html.match(/(?:src|href)="(?!https?:|data:|#)[^"]+"/g);
if (leftover) process.exit(1);
The result is a single 110 KB page. The same code runs like this:

This pitfall later became upstream issue #9: the framework internally knows this limitation (AGENTS.md mentions it once), but the user-facing skill and template don't say a word, so if you follow the docs you'll step right into it. I suggested three steps in the issue—check should warn on relative references, the skill should add a note, and eventually support it properly with SetVirtualHostNameToFolderMapping.
3. The game itself: 5 questions per round, five gameplay modes
I organized the character library into 102 groups covering grades one to five (13/14/22/31/22 groups), each with pinyin, compound words, radical, and a memory mnemonic:
['点画系列', '大下加点是太,大右加点是犬',
[['大', 'dà', '大小', '大'], ['太', 'tài', '太阳', '大'], ['犬', 'quǎn', '警犬', '犬']]],
The data structure is a compact one-line-per-group; changing the library doesn't require touching Cangjie code—after editing, node tools/build-ui.js takes effect. I also wrote a validation script to confirm every compound word really contains the character.
Five gameplay modes
| Game | What it trains | How to play |
|---|---|---|
| 👀 Keen Eyes | Whole-character shape recognition | Find the one that's different among a pile of identical characters (or the one matching the sample) |
| 🔤 Character-Character Pairing | Character ↔ word meaning | Left column characters, right column words, tap to connect |
| 🔍 Radical Detective | Radical attribution | Given a character, pick its radical from a set |
| 👂 Listen and Identify | Hearing → vision | Listen to the pronunciation and pick the character; if you can't hear it, it degrades to choosing by pinyin |
| ✍️ Word Formation Challenge | Semantic understanding | A word has a blank, pick the character that fits |

Difficulty is adaptive: correct answers add one distractor (up to six options), wrong answers take one away. Wrong answers don't punish—no star, but no deduction. If you miss the same question a third time, the memory mnemonic automatically shows:
Mnemonic: 日里一横是太阳,目里两横是眼睛 (In 日 a horizontal line is the sun, in 目 two lines are the eyes)
Rewards and the parent dashboard
Stars accumulate one by one; when enough are collected, the pet levels up (6 forms, from egg baby to the Chinese-character dragon). There are 7 badges; the earliest unlocked is “初出茅庐——完成第 1 局” (Take the first step—complete the first round), and you get it even if you answer 0 correctly:

Note the encouraging line—"Today these characters are a bit hard, but you finished anyway. Come back tomorrow and you'll be more familiar." Praising effort, not results was a hard requirement of the plan; all the copy follows it. When a wrong answer happens, it says "Look at the difference between these two characters", never "wrong" or "dumb".
The parent dashboard is separately password-protected (default 1234). Inside you can see session time, accuracy trend, and the character groups that are repeatedly missed automatically go into a "key review area":

The line chart is drawn with my own Canvas code, no third-party library—adding chart.js would mean accounting for offline package size, not worth it.
4. The Cangjie backend does exactly one thing: persist progress
The frontend could use localStorage, but that's not safe in the WebView (those pages have no real source; origin is opaque, sometimes throwing a direct SecurityError). The kid's stars and badges can't be lost, so I had the Cangjie side write to a file.
Four commands, all in src/storage.cj:
progress:load read save (returns JSON text, empty string for empty save)
progress:save overwrite (takes { data: "<JSON text>" })
progress:path returns save path (for parent backup)
app:about version and data directory
cj-tauri has a "three-way linkage" rule; miss one and the frontend can't use it:
// ① implementation + registration
public func build(): AppSpec {
return AppSpec()
.window(WindowConfig("形近字辨别训练", 1024, 720))
.wire({ app =>
app.register("progress:load", ProgressLoadCommand())
app.register("progress:save", ProgressSaveCommand())
// ...
})
}
// ② assets/capabilities/default.json allows it (otherwise frontend gets command not allowed)
{ "commands": ["progress:load", "progress:save", "progress:path", "app:about", "report"] }
// ③ frontend invoke
bridge.invoke('progress:save', { data: JSON.stringify(state) })
Only ①③ yields command not allowed, only ①② yields command not registered. I missed the manifest the first time, but the error message was clear.
The save file lands at %LOCALAPPDATA%\cj-hanzi-game\progress.json—the app's own directory, not the project directory, so changing working directory doesn't lose progress. Before writing, it validates whether the JSON is legal and refuses to write if not: "better to lose one save than corrupt the save file."
The frontend has a fallback: if the backend is unavailable, it falls back to localStorage and also writes a local cache on every save. If anything goes wrong, at least not everything is lost.
5. Two environment pitfalls that cost me half an hour each
Neither is the framework's fault, but both give no hint, so they're worth recording.
Pitfall A: cjpm silently exits 127 with a full PATH
$ cjpm -v
$ echo $?
127
Not a single character printed. After a lot of searching, it was PATH order: put Cangjie's bin, tools/bin, and runtime/lib/windows_x86_64_cjnative at the front of PATH and it works. Same binary, same arguments, different order—different result. No error for this kind of problem; only a controlled experiment finds it.
Pitfall B: missing WebView2Loader.dll, window flashes and closes
Compilation is fine, double-click the artifact, the bridge prints one line and destroys the window:
[cj-bridge] host thread started
[cj-bridge] WebView2Loader.dll not found: put it next to the exe or on PATH
[cj-bridge] host destroyed: 000001575fcd8780
And cj-tauri info will tell you the C bridge is built and cjc/stdx/cjpm all resolve fine—info all green doesn't mean it runs. Copy the framework's native/webview2/WebView2Loader.dll next to the exe and it's done.
I filed both of these in upstream issue #11, and also reported two more: cj-tauri check only returns a decimal code=3221225781 when a third-party comparison fails (I had to convert it myself to 0xC0000135 to recognize it as DLL-not-found), and cj-tauri create --help treats --help as a project name and creates a directory.
6. Conveniently fixed an upstream bug
While working on this game I ran cj-tauri check, and it said:
[cj-tauri] skeleton drift: targets/desktop/cjpm.toml differs from generator output (run cj-tauri sync desktop to regenerate)
Fine, I reran sync, then check—same message. Sync again, check again, still. This isn't "I broke something", it's self-contradictory.
Digging into cli/src/sync.cj, I saw three small problems stacked:
- When reading the business package
cjpm.toml'spath = "E:\\test\\a", it doesn't do TOML un-escaping, so\\is carried through, ending up asE://test//awritten into mytargets/; syncrenders from the business package declaration, butcheckusesresolveFrameworkRoot()to re-render and compares strings—two different sources, comparison never holds;toTomlPathonly replaces\with/, **doesn't merge duplicate separators**, so the old skeleton'sE://never matches.
The fix is only a three-line idea: restore escaping, use one common root getter, and normalize both sides before comparing.
// single entry point: both sync and check must go through it, otherwise you get "sync then immediately drift"
func resolveSkeletonFrameworkRoot(verbose: Bool): Option<String> {
match (readBizFrameworkPath()) {
case Some(p) =>
if (verbose) { eprintln("[cj-tauri] framework path from business package declaration: ${p}") }
return Some(p)
case None => return resolveFrameworkRoot()
}
}
// normalization preserves leading UNC `//`: that's a Windows shared path, don't merge it away
func toTomlPath(p: String): String {
let s = p.replace("\\", "/")
// ... merge duplicate separators ...
}
I also added 5 regression tests guarding two invariants: TOML escapes must be restored (unknown escapes must not be swallowed), and separators must be merged and idempotent.
I deliberately did an A/B during verification
cd cli && cjpm test came out with 10 tests, 2 red. My first reaction was "I broke it", but I didn't dare change the tests—I stashed my changes and ran again on the base commit:
Base commit (no changes): TOTAL 5, PASSED 3, FAILED 2 ← same two
With my changes: TOTAL 10, PASSED 8, FAILED 2 ← new 5 all pass, the reds are still those two
Conclusion clear: those two [links] cases were already red on the base commit; I didn't introduce them. When tests are red, do a controlled experiment first, don't rush to change the test to make it green—that masks the problem, not fixes it.
The fix became PR #25, and the documentation work (quick reference of 4 items + AGENTS.md §4 three items) became PR #24.
One thing I didn't fix: scripts/test.sh fails at link time on my machine because libstdx.crypto.x509.a is missing symbols like CertOpenSystemStoreA (the mingw link-options lack -lcrypt32, and the base commit had it too). I reported this honestly in the PR description, no stowaway changes—one PR does one thing, or reviewers will have a bad time.
7. Getting on the HarmonyOS tablet: install in thirty seconds
Desktop passing is only halftime. The real hurdle when the tablet arrives is signing—HarmonyOS real devices don't trust self-signed certificates; they only trust a profile matching both package name and device UDID.
I first ran an offline check:
[sign] package name: com.example.hanzi_game
[sign] device UDID: (not obtained)
[sign] reason: can't get device UDID (device not connected? run `hdc shell bm get --udid` to see)
The device is clearly connected. The truth is hdc is not on PATH (it lives in DevEco's toolchains directory). Adding that directory to PATH, the same command changes its story:
[sign] device UDID: 667BA4F7…DCE1443
[sign] reason: this machine has no material with this UDID and package name com.example.hanzi_game
[sign] next step: run `cj-tauri sign --login` + `sign --auto` to sign one for this package name now
This also went upstream (see link at the end), because its first conclusion leads people toward "is my cable broken?".
Following the prompt, self-signing: sign --login pops a browser, log in to AGC (token encrypted and stored, valid ~4 hours), then sign --auto --newKeys generates a key pair locally—private key never goes to the cloud, only the CSR is submitted for a certificate, and then the profile and encrypted password are written back to build-profile.json5. The whole thing takes a minute; cj-tauri's self-signing is even faster than clicking through DevEco's automation.
Then I hit an ordering pitfall
After changing styles and regenerating the page, I habitually ran cj-tauri sync ohos—it rewrote build-profile.json5 from the template, turning signingConfigs back into an empty array. Then packaging:
> hvigor Finished :entry:default@SignHap... after 2 ms ← suspiciously fast
[ohos] HAP = …/entry-default-unsigned.hap
[ohos] note: this is an unsigned package, cannot install to device.
Running sign --auto again (without --newKeys, intending to reuse existing materials), it finished at step ⑥ without printing step ⑦ "written back signingConfigs", and no error—because the p12 password was randomly generated last time and only existed then; it can't reconstruct the encrypted password needed for write-back, so it silently skips. You end up with a project that "signed successfully" but produces an unsigned package.
The fix is simple, but you have to know: order is sync → sign → build, don't sync after signing; if you really need to redo, use sign --auto --newKeys, which regenerates the password and writes it back.
Once installed, it worked on the first try:
hdc install -r entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.example.hanzi_game
What it looks like on a real HarmonyOS device
The same assets/ui/, on a 1840×2800 tablet in portrait (SLG-W10):

First install (the image above is after adjustments) looked off to me: .big-btn { margin-top: auto } on a 2800px tall screen pushed "Start Practice" to the very bottom, leaving a big gap in the middle, like the layout wasn't finished. So I added a media query for tall windows—group content centered, font sizes enlarged overall, and the character cards and option cards enlarged too (so the kid doesn't have to lean in):
@media (min-height: 900px) {
#view-home { justify-content: center; }
#view-home .big-btn { margin-top: 22px; }
.home-title { font-size: 40px; }
.target-char { font-size: 176px; }
.opt-card .opt-char { font-size: 104px; }
}
The game page on the HarmonyOS tablet:

At this point, one business codebase runs on both desktop and HarmonyOS—the 200 lines of Cangjie in src/ and the 10 frontend files in assets/ui/ are shared between the two, the only difference being two skeletons derived from cj-tauri.toml.
8. What it can do now, and next steps
Verified (with real-device screenshots and bridge logs):
- All five gameplay modes work; answer judgment, progress points, combos, and encouragement bubbles are correct;
- A round of 5 questions goes to a results page; stars are saved to the save file and badges unlock;
- The parent dashboard's password gate, statistics, line chart, and key review area all work;
- Save data is written via Cangjie commands; I checked the file contents;
- HarmonyOS tablet real device runs: signing, installation, launch, 1840×2800 portrait layout all verified.
What isn't verified, I also need to say clearly:
- Sound effects and voice reading—Web Audio synthesis + SpeechSynthesis, both desktop and tablet verified only that they don't throw errors or block gameplay; how it sounds is up to the kid's ears;
- Long-term use on the tablet (whether memory grows after half an hour, whether ArkWeb drops frames) not tested.
Next step is to wait for her to come home from school and try it, then connect the tablet:
export CANGJIE_STDX_OHOS=<HarmonyOS version stdx>/linux_ohos_aarch64_cjnative/dynamic/stdx
cd targets/ohos && npx cj-tauri build
cd targets/ohos && npx cj-tauri run --install # run cj-tauri sign first to check signing materials
To her, whether this game was written in Cangjie, whether there were pitfalls, or how many upstream bugs got fixed—none of that matters. The only thing she cares about is: did the pet she chose grow up today.
Link summary
- Game project:
E:/test/harmonyos/test/cj-game/hanzi-game - cj-tauri framework: https://atomgit.com/qq8864/cj-tauri
- Filed issues: #9 relative assets silently fail · #10 sync/check always drift · #11 silent diagnosis failures
- Filed PRs: #24 documentation hardening · #25 drift fix