Skip to content

feat: multilingual mdBook editions with magic and real reader worlds - #3

Closed
tgrospic wants to merge 19 commits into
alux-network:masterfrom
tgrospic:npm-ws
Closed

tgrospic wants to merge 19 commits into
alux-network:masterfrom
tgrospic:npm-ws

Conversation

@tgrospic

Copy link
Copy Markdown
Member

Overview

An mdBook-first version of the reader from #2. mdBook defines the book, web/languages.ts defines the editions, and everything else is derived from those two, including the tests.

Editions. Every language is built by mdBook itself, selected through MDBOOK_* environment overrides of book.toml. A small preprocessor (web/localize.ts) swaps in chapter.<lang>.md translations, translates part titles and reports stale translations by source hash. All 11 editions share the same chapter paths. The build writes to a temporary directory and replaces book/html only when every edition succeeds.

Reader. The markup is in theme/index.hbs (mdBook's template plus the reader), the style in theme/reader.css, and one TypeScript module (web/reader.ts, bundled to /reader.js) binds it. It adds the gateway with the magic and real worlds, the paged two-column magic book with page turns across chapters and RTL, running heads and folio, text size, bookmarks, reading music, the welcome audio and the language picker. UI labels from #2 are in web/i18n.ts. Static files are in public/, including the images that were in src/assets/.

Toolchain. TypeScript and Vite, no Python. npm start serves on port 3478 and rebuilds the book on change; npm run build builds every edition, then the reader bundle and public/.

Tests. npm test runs the review's verification plan:

  • the built site against the pages, titles, parts, lang/dir, links and anchors that mdBook's own book JSON defines for each edition, with a negative test for each check
  • each translation keeps its English chapter's code, math, link targets, media and heading levels
  • two clean builds are byte-identical

CI runs npm ci, npm run check, npm run build and npm test before publishing.

AGENTS.md states the repository's rules, its authority order and its Design by Meaning reading, for people and coding agents.

Continuing the design (for the #2 author)

@shixi-11, the structure is in place; the visual design is yours to carry on from here. #2's look was reproduced closely but not pixel for pixel, so please compare and refine.

Where design work goes:

  • Markup: theme/index.hbs. The reader's elements are marked by id; if you rename one, rename it in web/reader.ts too.
  • Style: theme/reader.css. Colors are tokens on :root with a dark palette for the coal, navy and ayu themes. The worlds are html[data-world="magic"|"real"], the gateway is html[data-gateway], page turns are html[data-turn]. Prefix rules on the chapter with #content, since mdBook's #content main outranks class selectors.
  • Behavior: web/reader.ts. Its header lists every piece of state it keeps.
  • Art, fonts and audio: public/, linked root-absolute (/forest-gateway.webp).
  • Labels: English text in the template with data-i18n, or t('…') in reader.ts, then every language in web/i18n.ts.

How to work:

  1. npm install, then npm start and open http://localhost:3478. Template, CSS and source changes rebuild and reload.
  2. Check both worlds, a right-to-left edition (/ar/), a narrow window (under 900px) and a dark theme.
  3. Before pushing, stop npm start and run npm run check, npm run build and npm test.

Keep design changes in the template, CSS, reader and public/; the build and tests should not need to change. Please don't add a framework, a second list of languages or pages, or post-processing of the rendered HTML. AGENTS.md explains why.

Additional Notes

Copy link
Copy Markdown
Contributor

@tgrospic I've continued the reader work on your mdBook-native baseline: tgrospic#1. It targets your npm-ws branch and contains two signed commits, without replacing the build, chapter sources or edition model.

The follow-up restores the bronze branding and approved small chapter illustrations, improves day/night readability and mobile layout, and restores scroll reading plus remembered chapter progress and manual language. Folios explicitly show chapter-local progress. It also fixes focused-control keyboard handling, rapid page turns, navigation audio, and CJK matching through the existing native search index, including direct search links and browser history. A separate commit fixes Windows paths and CRLF handling in the existing checks; AGENTS.md and README.md describe the state boundaries.

npm run check, npm run build and all 292 project tests pass locally. Browser checks cover all 11 editions, desktop/mobile layouts, RTL, day/night and 4K/HiDPI; Chrome 156, Firefox 153 and WebKit 26.5 passed the focused interaction checks, including a deliberately delayed reader script for direct CJK searches. The stacked PR targets npm-ws, so the workflow restricted to PRs against master has not run for these new commits.

I only have Android hardware and no iPhone or iPad. This pass used browser simulation; physical iOS Safari and Android acceptance are still outstanding. Nothing has been merged or deployed.

Copy link
Copy Markdown
Contributor

@tgrospic, following your browser-coverage request, I've rebased the follow-up PR onto e8661ac. Current head is e539367.

The scenarios are now checked into web/test/browser.test.ts, run by npm test, with routes derived from expectedSite(). Playwright replaces Puppeteer as the sole browser driver to cover WebKit; the Node test runner and mdBook architecture remain unchanged. README.md and AGENTS.md describe installation, profile selection and handover.

The mobile scenarios exposed a touch-toolbar target moving between touchend and click, plus headings hidden behind that toolbar; both have focused fixes and regression tests. The previous Firefox CI failures came from fonts cancelled during document navigation. The monitor now distinguishes only those explicit navigation cancellations; missing-font 404 negative fixtures confirm real resource failures still fail.

  • PASS: strict types, production build and all 504 tests, locally and in current-head CI, with zero failed or skipped tests. This includes the existing content/link/translation/determinism checks and 212 browser scenarios.
  • PASS: desktop Chromium 151.0.7922.34, Firefox 153.0 and WebKit 26.5; Pixel 7/Chromium and iPhone 13/WebKit simulations. Search checks verify that returned links belong to the current query, including cache changes, history and delayed reader loading.
  • NOT TESTED: physical Android Chrome and iOS Safari. I only have Android hardware and no iPhone/iPad; the automated mobile profiles are simulations.

The publishing step was skipped. Nothing has been merged or deployed; ready for your review.

Copy link
Copy Markdown
Contributor

@tgrospic I've taken over your completed npm-ws integration in #4, as requested. It includes the merged follow-up and your latest UI/test refinements, with the existing commit authorship preserved. #4 is the consolidated successor to #2 and #3; neither earlier PR has been closed.

The additional commit only clarifies the README credits and preserves Tomislav Grospić in the book author configuration and handover rules. I retained your paged-only magic world and latest interface behavior. All 507 tests pass locally; the new upstream CI run is in progress. Physical Android Chrome and iOS Safari remain untested—the mobile checks use browser profiles.

@tgrospic

Copy link
Copy Markdown
Member Author

Closing, fulfilled its purpose.

@tgrospic tgrospic closed this Oct 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants