Feature: Vertical writing mode (tategaki) for Japanese / Traditional Chinese EPUBs

[oemaix]

Summary

CrossPoint already handles horizontal CJK reading well (per-character line breaking, basic kinsoku, ruby annotations, CJK fonts from SD). What's missing is vertical writing mode (縦書き / tategaki): characters top-to-bottom, columns flowing right-to-left. This is the default typesetting for most Japanese fiction and very common for Traditional Chinese books in Taiwan and Hong Kong. Stock firmware doesn't support it, and as far as I can tell none of the community forks do either.

I've done a feasibility analysis of the codebase and believe this is implementable in stages with acceptable effort and no runtime performance cost. I'd like to coordinate before starting, since it touches the section cache format and the reader core (Phase 1 territory), even though the feature itself is squarely Phase 2 ("complex script support where realistic on ESP32 hardware").

Scope fit

• SCOPE.md §5 explicitly asks for input on "Languages with poor stock and fork coverage: Especially those that need shaping, complex layout, or non-Latin font work that nobody is handling well today." Vertical CJK is exactly this.
• SCOPE.md In-Scope: "EPUB Rendering & Optimization" and "Typography & Legibility".
• Not a theme, not a network connector, not an app — none of the closed areas apply.
• Precedent: RTL (Arabic/Hebrew) and CJK-via-SD-fonts already landed as language-gap work.

What the codebase already has

• Per-character CJK segmentation: ParsedText splits CJK runs into single-codepoint tokens at break opportunities (cjkCharacterBreakByteOffsets, lib/Epub/Epub/ParsedText.cpp).
• Basic kinsoku: no-break-before 、。」！？ / no-break-after 「（ rules (ParsedText.cpp:65–155).
• Ruby support: <ruby>/<rt> parsing and rendering — horizontal only today.
• SD card CJK fonts: .cpfont on-demand glyph loading already solves the font-size problem.
• Rotated glyph rendering: GfxRenderer::drawTextRotated90CW (lib/GfxRenderer/GfxRenderer.cpp:2124) exists as a compile-time template path — currently used for UI labels only.

What's missing (the actual work)

1. A vertical layout path. Layout is hardwired horizontal: line breaking measures against viewport width, pages stack lines top-to-bottom (ChapterHtmlSlimParser::addLineToPage). Vertical mode needs columns broken against viewport height, placed right-to-left. Conceptually an axis swap, applied through line breaking, page assembly, justification, and ruby placement.
2. Cache format extension. TextBlock stores only a horizontal per-word position (wordXpos), and section.bin has no writing-mode field. Needs a format extension + SECTION_FILE_VERSION bump (existing invalidation logic handles migration).
3. Detection. Neither writing-mode / -epub-writing-mode (CSS parser) nor page-progression-direction (OPF spine) are parsed today. I propose starting with a manual per-book setting and adding auto-detection later.
4. Typographic details: upright CJK glyphs with rotated Latin runs, vertical punctuation forms (、。 position), ruby to the right of the column, optionally tate-chū-yoko. These can be delivered incrementally. Note that the vertical punctuation forms have their own Unicode codepoints (Vertical Forms, U+FE10–FE19), so this can reuse the same codepoint-remapping approach the project already uses for Arabic contextual shaping in lib/MiniBidi (do_shape()).

Proposed staging

Stage	Contents	Result
1	Vertical layout path + cache extension + manual setting	Readable tategaki: upright CJK, rotated Latin
2	Vertical punctuation forms, vertical ruby, RTL page progression	Daily-driver quality for Japanese novels
3	CSS/OPF auto-detection, tate-chū-yoko, fuller kinsoku table	Commercial-reader quality

I'd open Stage 1 as a focused PR first, targeting develop.

Performance / memory

Layout cost is paid once at section-build time and cached to section.bin — vertical layout is the same class of work as horizontal with axes swapped, so page turns stay as fast as today. Glyph rotation goes through the existing compile-time template (no per-pixel runtime cost). CJK glyphs already stream from SD via the existing ring buffer, so DRAM pressure doesn't change. This should work on the C3, not just the S3.

Design consideration: column direction as a parameter

Traditional Mongolian is also written vertically but with columns flowing left-to-right, and would additionally require contextual glyph shaping (cursive joining, like Arabic rotated 90° — but unlike Arabic, Unicode encodes no presentation forms for Mongolian, so the existing do_shape() approach doesn't transfer). I don't propose implementing Mongolian now — the shaping work is a separate, much larger problem — but I'd design the layout path with column direction as a parameter rather than hardcoding right-to-left, so the door stays open.

Questions for maintainers

1. Given Phase 1 is still in progress, is a Stage-1 PR acceptable now, or should this wait? (The cache-format touch is small and version-gated.)
2. Any preference on where the writing-mode flag lives — per-book setting vs. global reader setting?
3. Should the section cache store per-word Y positions (mirroring wordXpos), or a writing-mode flag in the header with axis interpretation at render time?

I can supply sample EPUBs (Japanese fiction with ruby, Traditional Chinese vertical layout) and test on real hardware. Happy to iterate on the approach before writing any code.

[Uri-Tauber]

You have this fork https://github.com/zrn-ns/crosspoint-jp which add vertical Japanese support.
Seems to be actively maintained.

Make sure it support your device variant before flashing.

[oemaix]

Thanks for the pointer — I've studied zrn-ns/crosspoint-jp in detail (though
it didn't release a firmware for my device, reTerminal Sticky). It's genuinely
good work: a parallel vertical layout path (columns right-to-left, per-word Y
positions + a verticalMode flag in the section cache header), upright CJK with
rotated Latin, tate-chū-yoko, vertical ruby, kinsoku-aware column breaking, and
OpenType vert glyph substitution via the .cpfont pipeline. It also validates the
approach I'd sketched — they made essentially the same architectural choices.

Having looked closely, though, I think this strengthens the case for bringing
vertical writing into CrossPoint core rather than deferring to the fork:

1. The fork is intentionally Japanese-only. Its README explicitly states it has
   removed Chinese and Korean support and directs Chinese users to the separate
   CJK fork — which in turn has no vertical writing. So the fork ecosystem leaves a
   real gap: vertical Traditional Chinese (Taiwan/HK), a very common publishing
   format, is served by nobody. That's a perfectly legitimate scope choice by
   zrn-ns, but it means SCOPE.md's "another fork already solves this well" test
   only passes for Japanese readers.
2. Device coverage. The fork's README says it's only verified on the X3 (X4
   unconfirmed), with no S3-class environments (X4Pro, Sticky, PaperMono) at all.
3. Divergence is growing. The fork sits ~550 commits behind upstream master
   (section cache v34 vs v45, no partial builds). Porting only gets more expensive
   the longer it waits.

My proposal: I'd reach out to @zrn-ns first — credit via Co-Authored-By at minimum,
direct involvement if they're interested — then port in stages against the current
cache format: (1) vertical layout path + manual setting, (2) vert glyph substitution + vertical
ruby + RTL page progression, (3) auto-detection (OPF
page-progression-direction, and actually wiring up CSS writing-mode, which the fork
parses but doesn't use). Each stage as a focused PR against develop, tested on C3
and S3 hardware, with vertical Traditional Chinese and Japanese sample books.

Would a port along these lines be welcome?