v0.2.4

v0.2.4 — Desktop window icon and Vietnamese docs

Bug Fixes

• Desktop window/taskbar icon stays the default Flet icon (LAI-B-004 follow-up). Flet 0.21.x's bundled Flutter client did not wire windowIcon into the Page control, so page.window.icon and every Python-side workaround were silently ignored at runtime. Bumped flet to 0.23.2 in requirements.txt so page.window.icon reaches the native window, and the bundled lexora-ai-icon.ico now replaces the default Flet icon in the Windows title bar, taskbar, and Alt+Tab thumbnail in dev (python run_ui.py --no-browser) without needing a flet pack build.
• Branding code duplication. Centralised the desktop chrome wiring in new src/lexora/ui/desktop_branding.py::apply_desktop_branding. run_ui.py and src/lexora/ui/main.py now call the shared helper, eliminating two divergent copies of the icon-resolution logic.

Documentation

• Vietnamese README (README.vi.md). New top-level Vietnamese guide for Windows installation (ZIP and MSI from GitHub Releases, SmartScreen guidance, post-install steps, source build) with a Settings screenshot in Vietnamese.
• Vietnamese provider/API key guide (docs/cau-hinh-api-key.vi.md). Translated, step-by-step Vietnamese version of docs/provider-api-key-guide.md covering OpenAI, Azure OpenAI, Azure AI Foundry, Gemini, Anthropic, and Qwen, plus a combined .env template and quick CLI validation snippets.
• Cross-links. Added pointers from the English README.md and docs/provider-api-key-guide.md to the Vietnamese counterparts.

Internal

• Spec/docs comment cleanup. Reworded the onefile vs onedir rationale in packaging/windows/lexora_ai.spec and docs/windows-build-and-packaging.md to attribute the failure mode to PyInstaller onefile + Python 3.12 on Windows rather than to a specific Flet minor version.

Downloads

• LexoraAI-windows-amd64.zip — portable Windows ZIP, run LexoraAI.exe after extracting.
• LexoraAI-windows-amd64.msi — per-machine WiX installer for Windows.
• LexoraAI-macos-arm64.zip — macOS Apple Silicon .app bundle.

Verification

• The desktop title bar / Windows taskbar should now show the Lexora "L" icon instead of the default Flet "F".
• See README.vi.md and docs/cau-hinh-api-key.vi.md for the new Vietnamese guides.

Full changelog entry: CHANGELOG.md.

Full Changelog: v0.2.3...v0.2.4

v0.2.3

Lexora AI v0.2.3

Patch release focused on the Windows MSI shortcut regression introduced during ICE cleanup, plus README documentation for the Translation Context parameters (Tone / Domain / Instruction) shipped in v0.2.2.

No translation pipeline behavior changes. Safe upgrade from v0.2.2.

---

Highlights

• Windows MSI shortcuts land in the correct All Users locations again — fixes a regression where the Start Menu folder could be created at D:\Lexora Labs\Lexora AI\ (or whichever drive the MSI was launched from) instead of %ProgramData%\Microsoft\Windows\Start Menu\Programs\Lexora AI\.
• README now documents the v0.2.2 Context surface for both UI and CLI (Tone, Domain, Custom instruction), including allowed values, the ~8 KB instruction cap, and the run-report fields.
• WiX build pipeline is more reliable: a new wix-patch-harvested.ps1 step gives the launcher a stable File id so non-advertised shortcuts can target it via [#LexoraAILauncherExe], and light.exe -sval is the documented trade-off for ICE38/43/57 vs. shortcut visibility on per-machine installs.

---

Bug Fixes

MSI: shortcut placement regression guard (LAI-B-013)

During the ICE38/ICE43/ICE57 cleanup, packaging/windows/Product.wxs was temporarily switched to CommonProgramsFolder / CommonDesktopFolder. With InstallScope="perMachine" and the MSI launched from a non-system drive (e.g. D:\), Windows Installer resolved those ids to the install-media drive root, so shortcuts were created at:

D:\Lexora Labs\Lexora AI\Lexora AI.lnk

instead of the expected All Users Start Menu folder.

Fix: restored ProgramMenuFolder / DesktopFolder (auto-redirected to the All Users / Common locations because ALLUSERS=1 is implicit under InstallScope="perMachine") and added an explicit regression-guard comment so the next ICE cleanup does not regress this again. Documented in docs/windows-build-and-packaging.md §7.2.

MSI: link/compile errors during this patch cycle

Reauthored shortcut components to compile cleanly with WiX 3 after several attempts that hit:

• LGHT0094 — unresolved Directory:CommonProgramsFolder / Directory:CommonDesktopFolder (standard folder ids must be declared under TARGETDIR).
• CNDL0035 — Shortcut/@Target cannot coexist with Advertise="yes".
• CNDL0004 — Shortcut does not accept KeyPath.
• LGHT0204 — ICE38 / ICE43 / ICE57 on HKLM KeyPath under Common* shortcut folders.

Final, working authoring on main:

• Advertise="no" shortcut with Target="[#LexoraAILauncherExe]".
• New packaging/windows/wix-patch-harvested.ps1 runs after heat.exe and renames the harvested LexoraAI.exe File row to the stable id LexoraAILauncherExe so the [#…] reference resolves.
• HKLM RegistryValue KeyPath on each shortcut component (HKCU was tried but caused per-machine shortcuts to silently disappear).
• light.exe -sval skips ICE — an intentional, documented trade-off, since the pure-ICE-clean alternatives broke real installs.

---

Documentation

README

• New Context section under "Translate tab — per-job configuration" describing the Tone, Domain, and Custom instruction controls, their allowed values, the ~8,000-character instruction cap, the EN/VI label policy, the Legal/Medical disclaimer, and the run-report fields (tone, domain, instruction_length, instruction_hash).
• New CLI Context flags section in Usage (quick reference) with example commands for --tone, --domain, --instruction, and --instruction-file, including allowed enum values.
• Roadmap updated:
  • The old "Translation context, instructions, and glossary" bullet is replaced by saved presets / per-project defaults (LAI-T-060, deferred post-v1) and a working glossary path item (only the glossary part is still pending).
  • Usage / UI bullet now mentions the Context card and notes that re-runs inherit Tone/Domain/Instruction.

Internal docs

• docs/windows-build-and-packaging.md §7.2 expanded with the regression note, the -sval rationale, and the manual light command updated to include the patch script.
• docs/todo-list.md row for LAI-B-013 records the 2026-05-05 regression and re-fix.

---

CI / Build pipeline

• .github/workflows/desktop-release.yml — runs wix-patch-harvested.ps1 after heat.exe; calls light.exe -sval.
• packaging/windows/build-local.ps1 — same patch step; light runs with -sval locally too, so the local build mirrors CI.
• packaging/windows/wix-patch-harvested.ps1 — new, idempotent post-heat patch.
• packaging/windows/Product.wxs — final shortcut authoring described above.

No changes to:

• macOS flet pack step.
• Translation engine, CLI surface, UI runtime behavior.
• Cache fingerprinting.

---

Commits in this release

• cff3bde fix(packaging): restore ProgramMenuFolder shortcut placement; ICE skip with -sval
• ee0753a docs(readme): translation context params (Tone, Domain, Instruction) for UI and CLI
• 5ebf559 chore(release): v0.2.3 changelog (WiX shortcut regression fix + README context docs)

---

Upgrade notes

If you previously installed a build that wrote shortcuts to D:\Lexora Labs\Lexora AI\ (or any non-system drive):

1. Uninstall the previous MSI:

   msiexec /x LexoraAI-windows-amd64.msi /l*v uninstall.log

2. Manually delete any leftover Lexora Labs\Lexora AI\ folder on the wrong drive (Windows Installer does not own that location).

3. Install v0.2.3 and confirm the shortcut appears at:

   %ProgramData%\Microsoft\Windows\Start Menu\Programs\Lexora AI\Lexora AI.lnk
   

   If the optional Desktop shortcut feature is enabled, also at %PUBLIC%\Desktop\Lexora AI.lnk.

If v0.2.2 worked correctly for you, this is an in-place upgrade (MajorUpgrade) — install over the previous version.

---

Assets

Asset	Description
LexoraAI-windows-amd64.msi	Per-machine WiX installer (Program Files; All Users shortcuts).
LexoraAI-windows-amd64.zip	Portable Windows build — extract and run LexoraAI.exe.
LexoraAI-macos-arm64.zip	Apple Silicon macOS app (drag into /Applications).

See CHANGELOG.md for the full version history.

v0.2.2

Bug Fixes

• MSI shortcuts (LAI-B-013): Windows installer now creates Start Menu and optional Desktop shortcuts under the correct all-users locations (ProgramMenuFolder / DesktopFolder) regardless of which drive the MSI is run from. Previously, CommonProgramsFolder resolved to the install media drive (e.g. D:\) instead of %ProgramData%, so shortcuts were silently dropped.
• MSI writable output paths (LAI-B-012): Default translate output now writes to user_data_dir()/library (e.g. %LOCALAPPDATA%\Lexora Labs\Lexora AI\library) instead of a path relative to the Program Files install directory. Relative path overrides supplied via the UI are also remapped to the writable location; a safe fallback is used when the target directory cannot be created.
• UI cache path normalization (LAI-B-014): Settings UI coerces legacy relative cache paths (e.g. .lexora/translation_cache.jsonl) to the user-writable default under user_data_dir(), preventing WinError 5 access-denied errors after MSI installation.
• EPUB CSS preservation (LAI-B-003): Translated EPUB chapters now retain the original <head> content (stylesheet links, meta tags, charset declarations) merged with the translated <body> and localized <title>, so output formatting and styling match the source book.

Features and Improvements

• Structured EPUB batch on by default: --structured-epub-batch is now the default translation mode for EPUB files. Opt out with --no-structured-epub-batch. The Translator.translate_file API defaults are aligned with the CLI.
• Startup loading overlay: Desktop app shows a localized splash screen while the jobs database and screens initialize, preventing a blank-window appearance on first launch or relaunch.
• Async session handler: main and attach_lexora_shell are now fully async with await bootstrap instead of page.run_task, eliminating cross-thread races that could leave the splash stuck.
• SQLite connection timeout: jobs.sqlite3 opens with timeout=30.0 to reduce contention when a second app instance briefly holds the database lock.

CI

• Windows: MSI_PRODUCT_VERSION is now derived from the GitHub release tag (WiX four-part n.n.n.n format).
• macOS: --product-version is passed to flet pack from the tag-derived semver.
• Manual release trigger: The desktop release workflow now accepts a workflow_dispatch with a version input (e.g. v0.2.2) that creates and pushes the release tag, then builds and publishes the GitHub release automatically.

Tests

• tests/test_translate_output_paths.py — output path resolution under MSI-style environments.
• tests/test_ui_cache_path_normalization.py — legacy cache path coercion in the Settings UI.

v0.2.1.1

What's changed

• Windows packaging/installer hardening: PyInstaller onedir build + WiX MSI flow + committed packaging spec + local packaging script/doc.
• Settings UX fixes: long endpoint values remain visible/editable, KEY fields reveal correctly, and provider delete now requires confirmation.
• Runtime path safety: app data (jobs/secrets/cache) now resolves to user-writable directories instead of install directories.
• EPUB output preservation: original XHTML <head> (including CSS links) is restored after translation, with whitespace fixes around inline tags (<a>, <em>, <code>).

Validation

• Desktop release workflow for v0.2.1.1 completed with successful Windows and macOS packaging jobs.

Follow-up

• CLI wrapper simplification remains planned (LAI-T-052).

v0.1.1

What's Changed

• Init the project Add Lexora AI - AI-powered eBook translation tool by @binhthanhng in #2
• Feature UI v1 by @binhthanhng in #6
• Add centralized theme system with dark/light/system support; remove duplicated Colors classes by @Copilot in #7
• Use branding ico for app icons by @binhthanhng in #8
• feat(cache): add cache scope, clear-cache option, and compatibility filtering by @binhthanhng in #10
• feat(logging): finalize tasks 13-15 with tokenized file naming, sink routing, and test coverage by @binhthanhng in #11
• fix(epub): sanitize output rendering, add provider key guide, and block EPUB tracking by @binhthanhng in #12
• fix(bug-01): finalize EPUB sanitization and remove deprecation warning sources by @binhthanhng in #14
• feat(logging): close review gaps for UI and structured events by @binhthanhng in #15
• docs(planning): split todo list into active and done sections by @binhthanhng in #16
• feat(track-a): harden canonical CLI runtime and run contract by @binhthanhng in #18
• EPUB structured JSON batch translation (OpenAI, Azure Foundry, Gemini) by @binhthanhng in #21
• feat(ui): continue translate UX and shell refinements by @binhthanhng in #22
• feat(ui): finalize jobs lifecycle UX and onboarding docs by @binhthanhng in #23
• feat(ui): finalize language switch polish and translation wording by @binhthanhng in #24
• feat(ui-db): persist jobs lifecycle to local SQLite (LAI-T-046) by @binhthanhng in #25
• fix(ui): resolve Azure Foundry deployment model mismatch in Flet by @binhthanhng in #26
• feat(ui): finalize provider settings UX and close approved tasks by @binhthanhng in #27
• Feat/UI default library output naming by @binhthanhng in #28

New Contributors

• @Copilot made their first contribution in #7

Full Changelog: https://github.com/Lexora-Labs/lexora-ai/commits/v0.1.1