Repository navigation
Conversation
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
I like the new design with Magic world. It also shows that good specification can provide multiple implementations like here different UI interpretations. To support this direction I suggest some reorganization of web project. It's standard JS tooling which can better integrate with mdbook that can provide structured data for SPA app. mdbook is like simple compiler or Below is the prompt for AI. Architecture refactor requested: TypeScript + Vite + mdBook JSON The new reader looks promising, but the implementation is becoming unnecessarily complex, particularly We should not reimplement mdBook's content processing in JavaScript. mdBook already owns the book structure, chapter ordering, Markdown preprocessing, links, and extensions. Please refactor the 1. Single source of truthUse mdBook's JSON renderer output as the input to the website build.
Note: mdBook JSON contains chapter Markdown, not rendered HTML. Use a Markdown renderer only for the remaining rendering step. Do not duplicate preprocessing or assume the JSON provides a Markdown AST. 2. TypeScript + ViteConvert the Suggested minimal structure: This is a guideline, not a requirement to create extra abstractions or files. 3. Separate content from presentationThe architecture should be: Both reading experiences must consume the same content model. Neither should know how mdBook or Markdown source files are organized. Language variants must preserve the same structural chapter identity, heading anchors, code, equations, and source links. 4. Eliminate duplicated logicReplace or simplify
Keep genuine reader-specific behavior, such as video clip presentation, syntax highlighting, navigation, and book pagination, in small, focused modules. Use mdBook-compatible rendering and anchor rules rather than inventing another Markdown dialect. Where mdBook JSON does not supply the required representation, make that transformation explicit and test it. 5. Build pipelineProvide simple commands: pnpm dev
pnpm build
pnpm preview
pnpm test
Keep GitHub Pages deployment straightforward. No server runtime. 6. Preserve behaviorDo not redesign the UI as part of this refactor. Preserve the existing languages, two reading modes, audio, search, bookmarks, pagination, math, admonitions, artwork, routes, and responsive behavior. Add focused tests for chapter hierarchy, links, heading anchors, translation alignment, and preservation of code and mathematical expressions. Main principle: mdBook defines the book. TypeScript defines a minimal typed reader model. Vite builds the UI. Presentation must not become another book compiler. Please implement the refactor, not just propose an architecture. Favor a small, readable, dependency-light project over framework complexity. |
|
Thanks, @tgrospic. Implemented the refactor in this PR.
Validation: build and strict type checks pass, with 33 unit/integration tests; 1,881 page-number/code checks across all 28 chapters, eleven languages and three widths; 264 reader interaction checks; and 739 sharing checks. The previous reader's 77 code blocks, 95 equations and four video addresses are preserved. The original source book and publishing workflow are unchanged. The implementation and setup details are in web/README.md. Ready for another review. |
|
Fixed an intermittent blank-book regression in 6ae6444. When image decoding was still pending, navigating to another chapter and resizing could leave an old reader's resize callback alive. It queried the shared app for Reproduced the missing book element before the fix; the identical delayed-image/navigation/resize sequence now retains the new chapter in both development and the production preview. Build/type checks and all 37 unit/integration tests pass, including four new ownership regressions. Another 60 browser checks pass with normal animations across English, Chinese and Arabic, light/dark themes and 390/1600px widths, covering rapid turns, font changes, anchor jumps and browser history. |
There was a problem hiding this comment.
Please resize these big images to needed size. Git repo behaves much better with smaller files and it's optimized for text. So images should be used carefully.
There was a problem hiding this comment.
Thanks, @tgrospic. Addressed in 2e54da9.
- Removed 13 unused PNG masters from the tracked public tree after preserving identical originals separately. The current
public/artdirectory is now 3.04 MB instead of 29.09 MB. - Resized the runtime marks to 256×239, the ribbon to 256×704 and the crab to 512×512. The night mark is now 30,408 bytes instead of 199,680; these four runtime assets together dropped from 962,870 to 165,900 bytes.
- Checked the actual rendered sizes at 3840×2160/DPR 1 and 1920×1080/DPR 2 in both themes. Small artwork retains enough resolution for its display size, with complete subjects, proportions and transparency. The forest, standing wizard and full-width textures retain their native dimensions; no upscaled artwork is being described as native 4K.
The unused PNGs were not page requests, so their removal primarily reduces the checkout/static artifact; the runtime reductions also reduce image transfer. Earlier binary blobs remain in Git history, which I have not rewritten. Asset sizing and maintenance notes are in web/ARTWORK.md.
|
Follow-up in 2e54da9 also fixes the blank paper shown during refresh and initial pagination. The current chapter now appears as readable sheets before image/font preparation and whole-book counting finish. Reflow keeps the existing content, and a noninteractive visual copy bridges PageFlip's first paint without duplicate anchors or active embedded players. Fonts and images prepare concurrently; decoded images are reused between chapters, and scroll mode no longer preloads every book illustration. The page-number audit also caught lazy illustrations measuring differently before their intrinsic size was available. Their reserved dimensions and display boxes are now stable, so cached chapter offsets match the rendered pages. Validation: production build/strict type checks and 39 unit/integration tests pass; 1,881 numbering/code checks across all 28 chapters, eleven languages and three widths; 72 delayed-image/font cold-load, reload and reflow checks; 12 pagination-state checks; 48 artwork checks; and 20 checks at 4K viewport/high-density display sizes. The frame-by-frame checks found no empty book frame. In the local production preview, readable content appeared at about 0.73s cold and 0.25s on reload, while complete pagination continued in the background. Public-network timings have not been measured. The image-sizing changes are detailed in the reply to your inline review. The source book and publishing workflow are unchanged. |
|
@tgrospic, added a site-identity follow-up in 0ac51cc. The tab icon now uses the verified official ALUX mark in warm gold on a forest-green badge, with no miniature bronze texture. The self-contained SVG is under 10 KB, with PNG/ICO fallbacks and a touch icon; a new favicon URL avoids the previous cached icon. Browser titles, app names and Open Graph site names now have Chinese and English treatments: the two Chinese editions use their Chinese name, and all other language editions use “ALUX Programming.” Chapter titles, body translations, descriptions and existing language-specific covers remain localized. Static routes, runtime navigation and the sharing preview agree. Production build, strict type checks and all 40 tests pass. Another 678 static/live branding checks pass across all eleven languages and both readers, including a language switch, preview site names and served icon variants. The icon was also inspected at 16/32px, on light/dark surfaces and at DPR 2. The source book and deployment workflow are unchanged. Earlier updates in this PR: navigation and blank-book lifecycle fix, refresh/loading and page-number corrections, and image sizing and high-density display checks. |
Cache search text per localized book and update only search results. Index canonical translation blocks with nested-content invalidation, and reuse preview sheets when layout counts are already settled. Preserve output, page numbering and animation behavior.
|
@tgrospic, a focused reader-performance follow-up is now in 87442d8.
In an interleaved local Chrome test with 4× CPU slowdown, median search-handler time changed from 12.7→4.7ms (English), 14.7→4.3ms (Chinese) and 16.5→4.6ms (Arabic), with 60 measured inputs per version/language after warm-up. A second, noisier batch confirmed the direction. These measure local CPU work; English startup improvement was inconclusive, so I am not claiming a general network-loading speedup. Validation: production build, strict types and all 44 tests pass; 280 translated chapters are exactly equal to the prior implementation; all 300 search-result/URL comparisons match. Also reran 1,881 page-number/code checks, 529 search interactions, 72 delayed-load/reload checks, 12 pagination-state checks and 60 normal-animation lifecycle checks. Three desktop/mobile/RTL search screenshot comparisons are pixel-identical. The maintenance notes document cache invalidation and the settled-layout requirement. |
|
@tgrospic, the maintenance-guide follow-up is in 8d1397b.
An audit of all 737 generated HTML pages found that the current titles already follow these rules. This commit documents the existing behavior; it does not change the reader UI, book content or deployment workflow. The root |
|
@tgrospic Browser-icon polish is now in Validation: the production build and strict TypeScript checks passed; all 737 generated pages reference the updated icon. I checked 16px and 32px rendering on light and dark backgrounds. CI is green: https://github.com/alux-network/alux-programming/actions/runs/40014693966. |
Refactor multilingual content: Markdown translations as first-class mdBook sourcesThe TypeScript and mdBook JSON integration are much better now. However, translation is still implemented through a complex HTML-token alignment system and runtime DOM manipulation. We should simplify the architecture rather than continue extending this machinery. Goal: every language should have real Markdown source files, processed by mdBook before rendering. The frontend should only consume already-localized book data. Please implement the following refactor. 1. Translation sources:
|
|
@tgrospic, implemented the source-localization and Solid refactor from your review. The main change is in
Validation: the web build and 32 Node tests pass; the production-build Chromium regression passes 318 assertions across 99 language/viewport/route combinations, including book/scroll switching, search, bookmarks, language/world continuity and slow-asset first paint. Migrated visible prose and protected technical content match the prior editions; one existing Japanese heading-list metadata artifact is documented and corrected without changing its visible heading or canonical ID. The unchanged original mdBook/linkcheck PR workflow is green for Migration evidence and review resolutions and the root/web Agent guides now describe the source layout and handover boundaries. Ready for your review. |
|
The architecture looks much better now. The mdBook pipeline, Markdown translations, typed content model, and SolidJS integration address my main concerns. I don't think another major refactor is needed. Let's focus on measurable merge criteria. 1. Pagination and lifecycle
2. Translation correctness
3. Reproducible builds
4. Browser acceptance testsTest both Magic and Real readers on:
Verify at least:
5. CI and performance
Merge decisionRequired before merge:
Can be follow-up PRs:
Please report each acceptance criterion as PASS / FAIL / NOT TESTED, with test commands and browser versions where applicable. No more architectural rewrites. Fix blockers, document remaining limitations, and merge when the required criteria pass. |
|
@tgrospic, the measurable-acceptance follow-up is pushed in
Reproduction: Acceptance ledger and limitations, root No merge, auto-merge or production deployment was performed. |
|
@shixi-11 thank you for the acceptance work. You answered every criterion with evidence, and the only open gate is physical-device testing, which was never in your hands. I said no more architectural rewrites, and I'm going back on that now. This is not because #2 failed the criteria. While reviewing, I tried how small the same reader could be on plain mdBook: no SolidJS, no separate content model and no client-side routing. mdBook builds every language edition itself ( Where #3 stands against the same criteria:
Two places where your work would move #3 forward the most:
You can continue here by rebasing this PR on top of #3, or open a new PR against #3's branch, whichever is easier for you. |
|
Superseded by: |
Result
Adds an eleven-language ALUX Programming reading site with a forest entrance, a paginated magic book and a quiet document reader. Both worlds retain direct chapter entry, full contents, search, bookmarks, shared reading preferences, on-demand pagination with explicitly labelled chapter progress and reliable cached whole-book numbering, book/scroll modes, bounded video clips, welcome audio and reading music.
Content and application architecture
SUMMARY.mdremain authoritative. The 280 approved translated chapters now live beside them aschapter.<lang>.md; missing translations fall back to English.content/<lang>.jsonmodels serve both readers, search and static routes. The browser loads only requested editions. Canonical chapter paths, heading IDs, reading storage and four legacy heading aliases are preserved.Original English Markdown,
book.toml, the mdBook theme and the GitHub Pages workflow remain unchanged. No merge or production deployment is included.Validation and handover
pnpm --dir web buildand strict TypeScript pass; 36 Node unit/integration tests pass.pnpm --dir web test:browserpasses 318 assertions, including 99 language/viewport/route combinations across all eleven languages at 320/768/1440px, both worlds and contents, plus interaction regressions.The existing GitHub Pages workflow is unchanged. A separate reader workflow now runs frozen installation, compiler lint/strict types, builds/tests, generated-route/resource audits, full-output repeatability and browser acceptance. Publishing still runs only on pushes to
master; this PR does not deploy production. Latest CI status is reported in the PR checks rather than inferred from local tests.The acceptance follow-up fixes current-chapter-only measurement, PageFlip resource cleanup, cancelled navigation/clipboard work, Windows mdBook support probes, mobile View Transition timing and duplicate embedded players in animation snapshots. English-source fingerprints provide non-blocking translation freshness warnings. Chromium, Firefox, Android-profile Chromium and iPhone-profile WebKit pass local automation, including native audio playback-clock/pause checks. These mobile profiles are simulations. The owner has Android but no iPhone/iPad; physical Android Chrome and iOS Safari remain NOT TESTED.
See measurable acceptance and remaining device limits for PASS/FAIL/NOT TESTED evidence, versions, commands, repeatability and the baseline comparison.
See the migration and review record, web maintenance instructions and local build/browser-test instructions. The reader and social preview pages remain under
web/previews/.