2 files changed, 346 insertions, 38 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d22e644..ba91bbb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,305 @@
 
 The implementation for the original Moonscript language 0.5.0 can be found in the `0.5.0` branch of Yuescript. The Moonscript with fixes and new features is in the main branch of Yuescript. Here are the changelogs for each Yuescript version.
 
+## v0.33.x
+
+### Added Features
+
+* Expanded documentation deliverables with an all-in-one documentation output.
+* Improved `break` feature set by supporting multiple break values (extends the `break with value` work introduced in `v0.28.x`).
+* Further improved reserved-comment preservation behavior for table/class blocks (parser, AST and code generation), with dedicated test coverage.
+
+### Fixed Issues
+
+* Fixed formatter issues and improved formatting stability.
+* Fixed comma placement/insertion issues when line-number comments are enabled (including class-member cases, issue #240).
+* Fixed more comment-preserving code paths and issue #245.
+* Improved documentation site rendering/highlighting and updated documentation content/assets.
+
+## v0.32.x
+
+### Added Features
+
+* Added `;` as a statement separator.
+  ```moonscript
+  a = 1; b = 2; result = a + b
+  ```
+* Migrated the documentation site to VitePress and added/expanded localized docs (including German and Portuguese-Brazil).
+* Added substantial compiler test coverage (including large regression/spec batches).
+
+### Fixed Issues
+
+* Fixed `import global` related issues after the `v0.31.x` syntax addition.
+* Fixed global-variable lint behavior.
+* Improved cross-platform build support (LuaJIT, MSVC/Windows, CMake, rockspec updates).
+* Added Lua 5.5 support in CMake configuration and fixed CI/build workflow issues.
+* Fixed issue #227 and multiple documentation/site regressions.
+
+## v0.31.x
+
+### Added Features
+
+* Added const attributes.
+  ```moonscript
+  const a = 123
+  const {:x, :y} = point
+  ```
+* Added `import global` syntax.
+  ```moonscript
+  import global
+  print "hello"
+  math.random 10
+  ```
+* These are the primary language-level additions in `v0.31.x` (with follow-up fixes landing in `v0.32.x`).
+
+### Fixed Issues
+
+* Fixed global import ordering.
+* Fixed a crash issue in `v0.31.1`.
+* Updated Windows workflow/build-related integration.
+
+## v0.30.x
+
+### Added Features
+
+* Added named vararg support.
+  ```moonscript
+  f = (...t) ->
+    for i = 1, t.n
+      print t[i]
+  ```
+* Improved syntax error messages with more contextual details (not syntax-changing, but a meaningful compiler UX improvement).
+
+### Fixed Issues
+
+* Fixed empty-line-as-block parsing issue.
+* Fixed formatter crash and other formatting-related issues.
+* Refactored `FnArgsDef` rules and fixed issue #224.
+* Updated reserved-comments behavior/functionality.
+
+## v0.29.x
+
+### Added Features
+
+* Introduced/iterated new syntax around `try` flow, including `try!` / `try?` related changes.
+  ```moonscript
+  a, b, c = try? func!
+  a = (try? func!) ?? "default"
+  
+  f try?
+    print 123
+    func!
+  catch e
+    print e
+    e
+  ```
+* Added more reversed-index support for slice expressions and later fixed reversed-index edge cases.
+  ```moonscript
+  tab = [1, 2, 3, 4, 5]
+  print tab[#], tab[#-1]
+  ```
+* Added function argument destructuring.
+  ```moonscript
+  f = ({:x, :y}) -> x + y
+  print f x: 1, y: 2
+  ```
+* Added YAML multiline string support and macro argument checking.
+  ```moonscript
+  config = |
+    database:
+      host: localhost
+      port: 5432
+  ```
+
+### Fixed Issues
+
+* Fixed a crash in `yue.to_ast()` and additional reference/crash issues.
+* Stopped linting explicitly defined global variables.
+* Fixed issue #222 and #223.
+* Improved platform/build compatibility: Windows x64, Lua 5.1, Termux, WASM/build pipeline issues.
+* Renamed builtin JSON library to `cojson`, included a minimal JSON lib in the compiler tool, and removed `codecvt` usage for C++26 compatibility.
+
+## v0.28.x
+
+### Added Features
+
+* Allowed backcall without parentheses.
+  ```moonscript
+  results = do
+    data <- readAsync "data.txt"
+    process data
+  ```
+* Added global `const` declaration support, including declaration without initializer.
+  ```moonscript
+  import global
+  global const Flag = 1
+  global const math, table
+  ```
+* Added `break with value` syntax.
+  ```moonscript
+  x, y = for i = 1, 10
+    if i > 5
+      break i, i * 2
+  ```
+* Added `-` for implicit object.
+  ```moonscript
+  items =
+    - "a"
+    - "b"
+    - "c"
+  ```
+
+### Fixed Issues
+
+* Added/expanded related tests/docs and table-matching support around the new syntax behaviors.
+
+## v0.27.x
+
+### Added Features
+
+* Adjusted macro behavior by aligning Lua inserter macro behavior with common Yue macro behavior (semantic behavior alignment rather than new syntax).
+
+### Fixed Issues
+
+* Fixed issues #194, #195, #198, #201, #204, #206 and #209.
+* Updated `efsw` and fixed build-related issues.
+* Added/updated tests and documentation examples.
+
+## v0.26.x
+
+### Added Features
+
+* Added WASM distribution support for ESM/CommonJS modules and TypeScript integration (#176).
+
+### Fixed Issues
+
+* Fixed WASM build issues and updated WASM build pipeline.
+* Fixed issues #174, #175, #177, #178, #183, #185 and #188.
+* Fixed MoonScript issue #459.
+* Fixed build flags and related release/build issues; refreshed specs/docs/readme.
+
+## v0.25.x
+
+### Added Features
+
+* This series mainly improves semantic correctness and code generation consistency.
+
+### Fixed Issues
+
+* Fixed multi-value assignment evaluation order (including more edge cases in `v0.25.1`).
+* Disallowed some semantically incorrect syntax to improve code consistency.
+* Removed redundant/useless `do` blocks in generated code (`with` and related cases).
+* Fixed indentation/missed-indent issue and a few additional regressions.
+
+## v0.24.x
+
+### Added Features
+
+* Added reusable macro environment support.
+* Added builtin macros `$to_ast()` and `$is_ast()`.
+* Added `yue.is_ast()`.
+  ```moonscript
+  import "yue"
+  formated = yue.format code, 0, true
+  ```
+
+### Fixed Issues
+
+* Fixed macro function line-number handling.
+* Fixed Lua 5.1 build.
+* Fixed Lua stack size insufficiency issue.
+
+## v0.23.x
+
+### Added Features
+
+* Added macros-generating-macros feature (`v0.23.9`), expanding macro metaprogramming capability.
+  ```moonscript
+  macro Enum = (...) ->
+    items = {...}
+    itemSet = {item, true for item in *items}
+    (item) ->
+      error "got \"#{item}\", expecting one of #{table.concat items, ', '}" unless itemSet[item]
+      "\"#{item}\""
+  
+  macro BodyType = $Enum(
+    Static
+    Dynamic
+    Kinematic
+  )
+  
+  print "Valid enum type:", $BodyType Static
+  ```
+* Most other `v0.23.x` changes focus on try-catch/code-generation correctness rather than new syntax forms.
+* Added more tests/spec cases and documentation updates (including object literal docs in README, #165).
+
+### Fixed Issues
+
+* Fixed multiple try-catch syntax ambiguity/corner cases and removed redundant generated `do` blocks.
+* Fixed spread expression list issue in up-value functions.
+* Prevented extra anonymous function generation from `const`/`close` declarations.
+* Fixed nil-coalescing/anonymous-function movement issue and anonymous-function argument ordering.
+* Fixed a for-each key variable const-marking issue and traceback rewrite/codegen checks.
+
+## v0.22.x
+
+### Added Features
+
+* Added default return declaration for function literals.
+  ```moonscript
+  findValue = (items): "not found" ->
+    for item in *items
+      if item.name == "target"
+        return item.name
+  ```
+* Added option to stop implicit returns on the root (#164).
+* `v0.22.x` also adjusts `for`-loop const behavior to align with Lua 5.5 changes, then refines the rule in `v0.22.1` (only index/key variable is const).
+
+### Fixed Issues
+
+* Fixed undeclared specifier in `yue_compiler.cpp` (#163).
+* Removed an unnecessary const declaration.
+* Corrected/refined `for`-loop const default behavior introduced in `v0.22.0`.
+
+## v0.21.x
+
+### Added Features
+
+* Changed the if-assignment syntax to prevent error-prone cases (syntax/grammar behavior change).
+  ```moonscript
+  if user := obj\find_user "valid"
+    print user.name
+  elseif other := obj\find_user "fallback"
+    print other.name
+  ```
+* Added `yue.format()` and fixed `yue` AST-to-code conversion related functionality.
+  ```moonscript
+  import "yue"
+  formated = yue.format code, 0, true
+  ```
+
+### Fixed Issues
+
+* Fixed issues #157 and #158 (including a web compiler issue).
+* Fixed invalid formatting/formation cases and in-expression formatting issues.
+* Fixed more invalid in-expression use cases.
+* Fixed const list destructuring, empty-check/empty-block-at-EOF cases, and crash/format edge cases.
+* Fixed `luaminify` related issue and updated Lua 5.4 integration/tooling.
+
+## v0.20.x (after v0.20.2)
+
+### Added Features
+
+* This interval mainly contains follow-up fixes for newly introduced `v0.20.2` features (chaining conditions, list/switch matching, import handling) plus release pipeline improvements.
+
+### Fixed Issues
+
+* Fixed table-matching syntax in `switch` statements with list tables.
+* Fixed a missing condition-chaining case.
+* Fixed a crash case for `import` statements.
+* Made function-call argument behavior consistent with table-list behavior.
+* Improved release/build pipeline setup (CI workflows, LuaRocks upload, docs code checks, test workflow setup).
+
 ## v0.20.2
 
 ### Added Features
diff --git a/README.md b/README.md
index 73fadf7..caff885 100644
--- a/README.md
+++ b/README.md
@@ -1,55 +1,58 @@
 # YueScript
 
-<img src="doc/docs/.vitepress/public/image/yuescript.png" width="300" height="300" alt="logo"/>
+<img src="doc/docs/.vitepress/public/image/yuescript.png" width="300" height="300" alt="YueScript logo"/>
 
 [![IppClub](https://img.shields.io/badge/IppClub-Certified-11A7E2?logo=data%3Aimage%2Fsvg%2Bxml%3Bcharset%3Dutf-8%3Bbase64%2CPHN2ZyB2aWV3Qm94PSIwIDAgMjg4IDI3NCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWw6c3BhY2U9InByZXNlcnZlIiBzdHlsZT0iZmlsbC1ydWxlOmV2ZW5vZGQ7Y2xpcC1ydWxlOmV2ZW5vZGQ7c3Ryb2tlLWxpbmVqb2luOnJvdW5kO3N0cm9rZS1taXRlcmxpbWl0OjIiPjxwYXRoIGQ9Im0xNDYgMzEgNzIgNTVWMzFoLTcyWiIgc3R5bGU9ImZpbGw6I2Y2YTgwNjtmaWxsLXJ1bGU6bm9uemVybyIvPjxwYXRoIGQ9Im0xNjkgODYtMjMtNTUgNzIgNTVoLTQ5WiIgc3R5bGU9ImZpbGw6I2VmN2EwMDtmaWxsLXJ1bGU6bm9uemVybyIvPjxwYXRoIGQ9Ik0yNiAzMXY1NWg4MEw4MSAzMUgyNloiIHN0eWxlPSJmaWxsOiMwN2ExN2M7ZmlsbC1ydWxlOm5vbnplcm8iLz48cGF0aCBkPSJNMTA4IDkydjExMmwzMS00OC0zMS02NFoiIHN0eWxlPSJmaWxsOiNkZTAwNWQ7ZmlsbC1ydWxlOm5vbnplcm8iLz48cGF0aCBkPSJNMCAyNzR2LTUyaDk3bC0zMyA1MkgwWiIgc3R5bGU9ImZpbGw6I2Y2YTgwNjtmaWxsLXJ1bGU6bm9uemVybyIvPjxwYXRoIGQ9Im03NyAyNzQgNjctMTA3djEwN0g3N1oiIHN0eWxlPSJmaWxsOiNkZjI0MzM7ZmlsbC1ydWxlOm5vbnplcm8iLz48cGF0aCBkPSJNMTUyIDI3NGgyOWwtMjktNTN2NTNaIiBzdHlsZT0iZmlsbDojMzM0ODVkO2ZpbGwtcnVsZTpub256ZXJvIi8%2BPHBhdGggZD0iTTE5MSAyNzRoNzl2LTUySDE2N2wyNCA1MloiIHN0eWxlPSJmaWxsOiM0ZTI3NWE7ZmlsbC1ydWxlOm5vbnplcm8iLz48cGF0aCBkPSJNMjg4IDEwMGgtMTdWODVoLTEzdjE1aC0xN3YxM2gxN3YxNmgxM3YtMTZoMTd2LTEzWiIgc3R5bGU9ImZpbGw6I2M1MTgxZjtmaWxsLXJ1bGU6bm9uemVybyIvPjxwYXRoIGQ9Im0yNiA4NiA1Ni01NUgyNnY1NVoiIHN0eWxlPSJmaWxsOiMzMzQ4NWQ7ZmlsbC1ydWxlOm5vbnplcm8iLz48cGF0aCBkPSJNOTMgMzFoNDJsLTMwIDI5LTEyLTI5WiIgc3R5bGU9ImZpbGw6IzExYTdlMjtmaWxsLXJ1bGU6bm9uemVybyIvPjxwYXRoIGQ9Ik0xNTggMTc2Vjg2bC0zNCAxNCAzNCA3NloiIHN0eWxlPSJmaWxsOiMwMDU5OGU7ZmlsbC1ydWxlOm5vbnplcm8iLz48cGF0aCBkPSJtMTA2IDU5IDQxLTEtMTItMjgtMjkgMjlaIiBzdHlsZT0iZmlsbDojMDU3Y2I3O2ZpbGwtcnVsZTpub256ZXJvIi8%2BPHBhdGggZD0ibTEyNCAxMDAgMjItNDEgMTIgMjctMzQgMTRaIiBzdHlsZT0iZmlsbDojNGUyNzVhO2ZpbGwtcnVsZTpub256ZXJvIi8%2BPHBhdGggZD0ibTEwNiA2MCA0MS0xLTIzIDQxLTE4LTQwWiIgc3R5bGU9ImZpbGw6IzdiMTI4NTtmaWxsLXJ1bGU6bm9uemVybyIvPjxwYXRoIGQ9Im0xMDggMjA0IDMxLTQ4aC0zMXY0OFoiIHN0eWxlPSJmaWxsOiNiYTAwNzc7ZmlsbC1ydWxlOm5vbnplcm8iLz48cGF0aCBkPSJtNjUgMjc0IDMzLTUySDBsNjUgNTJaIiBzdHlsZT0iZmlsbDojZWY3YTAwO2ZpbGwtcnVsZTpub256ZXJvIi8%2BPHBhdGggZD0iTTc3IDI3NGg2N2wtNDAtNDUtMjcgNDVaIiBzdHlsZT0iZmlsbDojYTgxZTI0O2ZpbGwtcnVsZTpub256ZXJvIi8%2BPHBhdGggZD0iTTE2NyAyMjJoNThsLTM0IDUyLTI0LTUyWiIgc3R5bGU9ImZpbGw6IzExYTdlMjtmaWxsLXJ1bGU6bm9uemVybyIvPjxwYXRoIGQ9Im0yNzAgMjc0LTQ0LTUyLTM1IDUyaDc5WiIgc3R5bGU9ImZpbGw6IzA1N2NiNztmaWxsLXJ1bGU6bm9uemVybyIvPjxwYXRoIGQ9Ik0yNzUgNTVoLTU3VjBoMjV2MzFoMzJ2MjRaIiBzdHlsZT0iZmlsbDojZGUwMDVkO2ZpbGwtcnVsZTpub256ZXJvIi8%2BPHBhdGggZD0iTTE4NSAzMWg1N3Y1NWgtMjVWNTVoLTMyVjMxWiIgc3R5bGU9ImZpbGw6I2M1MTgxZjtmaWxsLXJ1bGU6bm9uemVybyIvPjwvc3ZnPg%3D%3D&labelColor=fff)](https://ippclub.org) [![Ubuntu](https://github.com/pigpigyyy/Yuescript/actions/workflows/ubuntu.yml/badge.svg)](https://github.com/pigpigyyy/Yuescript/actions/workflows/ubuntu.yml) [![Windows](https://github.com/pigpigyyy/Yuescript/actions/workflows/windows.yml/badge.svg)](https://github.com/pigpigyyy/Yuescript/actions/workflows/windows.yml) [![macOS](https://github.com/pigpigyyy/Yuescript/actions/workflows/macos.yml/badge.svg)](https://github.com/pigpigyyy/Yuescript/actions/workflows/macos.yml) [![Discord Badge](https://img.shields.io/discord/844031511208001577?color=5865F2&label=Discord&logo=discord&logoColor=white&style=flat-square)](https://discord.gg/cRJ2VAm2NV)
 
-YueScript is a MoonScript dialect. It is derived from [MoonScript language](https://github.com/leafo/moonscript) 0.5.0 and continuously adopting new features to be more up to date.
+YueScript is a MoonScript dialect that compiles to Lua. It is derived from [MoonScript](https://github.com/leafo/moonscript) `0.5.0` and continues to adopt new features to stay up to date.
 
-MoonScript is a language that compiles to Lua. Since original MoonScript has been used to write web framework [lapis](https://github.com/leafo/lapis) and run a few business web sites like [itch.io](https://itch.io) and [streak.club](https://streak.club) with some large code bases. The original language is getting too hard to adopt new features for those may break the stablility for existing applications.
+## Quick Links
 
-So YueScript is a new code base for pushing the language to go forward and being a playground to try introducing new language syntax or programing paradigms to make MoonScript language more expressive and productive.
+- Website: <https://yuescript.org>
+- Documentation: <https://yuescript.org/doc>
+- Changelog: [`CHANGELOG.md`](./CHANGELOG.md)
+- Discord: <https://discord.gg/cRJ2VAm2NV>
 
-Yue (月) is the name of moon in Chinese and it's pronounced as [jyɛ].
+## Overview
 
+MoonScript has been used to build real-world projects such as [Lapis](https://github.com/leafo/lapis), [itch.io](https://itch.io), and [streak.club](https://streak.club). As the original implementation became harder to evolve without risking compatibility, YueScript was created as a modernized code base for pushing the language forward.
 
+YueScript is both a production-ready compiler and a playground for exploring new syntax and programming paradigms that make MoonScript-style development more expressive and productive.
+
+Yue (月) is the Chinese word for moon and is pronounced [jyɛ].
 
 ## About Dora SSR
 
 YueScript is being developed and maintained alongside the open-source game engine [Dora SSR](https://github.com/ippclub/Dora-SSR). It has been used to create engine tools, game demos and prototypes, validating its capabilities in real-world scenarios while enhancing the Dora SSR development experience.
 
-
-
 ## Features
 
-* Based on modified [parserlib](https://github.com/axilmar/parserlib) library from Achilleas Margaritis with some performance enhancement. **lpeg** library is no longer needed.
-* Written in C++17.
-* Support most of the features from MoonScript language. Generate Lua codes in the same way like the original compiler.
-* Reserve line numbers from source file in the compiled Lua codes to help debugging.
-* More features like macro, existential operator, pipe operator, Javascript-like export syntax and etc.
-* See other details in the [changelog](./CHANGELOG.md). Find document [here](http://yuescript.org).
-
-
+- Based on a modified [parserlib](https://github.com/axilmar/parserlib) with performance enhancements. `lpeg` is no longer required.
+- Written in C++17.
+- Supports most MoonScript features and generates Lua code in a style compatible with the original compiler.
+- Preserves source line numbers in generated Lua to improve debugging.
+- Adds features like macros, existential operator, pipe operator, JavaScript-like export syntax, and more.
+- See [`CHANGELOG.md`](./CHANGELOG.md) for more details.
 
-## Installation & Usage
+## Installation
 
-* **Lua Module**
+### Lua Module
 
-&emsp;&emsp;Build `yue.so` file with
+Build `yue.so` with:
 
 ```sh
 > make shared LUAI=/usr/local/include/lua LUAL=/usr/local/lib/lua
 ```
 
-&emsp;&emsp;Then get the binary file from path `bin/shared/yue.so`.
+Then get the binary file from `bin/shared/yue.so`.
 
-&emsp;&emsp;Or you can install [luarocks](https://luarocks.org), a package manager for Lua modules. Then install it as a Lua module with
+Or install via [LuaRocks](https://luarocks.org):
 
 ```sh
 > luarocks install yuescript
 ```
 
-&emsp;&emsp;Then require the YueScript module in Lua:
+Then require the YueScript module in Lua:
 
 ```lua
 require("yue")("main") -- require `main.yue`
@@ -65,26 +68,27 @@ f!
 })
 ```
 
+### Binary Tool (CLI)
 
+Clone this repo, then build and install executable with:
 
-* **Binary Tool**
-
-&emsp;&emsp;Clone this repo, then build and install executable with:
 ```sh
 > make install
 ```
 
-&emsp;&emsp;Build YueScript tool without macro feature:
+Build YueScript tool without macro feature:
+
 ```sh
 > make install NO_MACRO=true
 ```
 
-&emsp;&emsp;Build YueScript tool without built-in Lua binary:
+Build YueScript tool without built-in Lua binary:
+
 ```sh
 > make install NO_LUA=true
 ```
 
-&emsp;&emsp;Use YueScript tool with:
+Use YueScript tool with:
 
 ```sh
 > yue -h
@@ -131,24 +135,29 @@ Options:
    in a single line to start/stop multi-line mode
 ```
 
-Use cases:
+### Common Usage
 
-* Recursively compile every YueScript file with extension `.yue` under current path:  `yue .`
-* Compile and save results to a target path:  `yue -t /target/path/ .`
-* Compile and reserve debug info:  `yue -l .`
-* Compile and generate minified codes:  `yue -m .`
-* Execute raw codes:  `yue -e 'print 123'`
-* Execute a YueScript file:  `yue -e main.yue`
+- Recursively compile every YueScript file with extension `.yue` under current path: `yue .`
+- Compile and save results to a target path: `yue -t /target/path/ .`
+- Compile and reserve debug info: `yue -l .`
+- Compile and generate minified codes: `yue -m .`
+- Execute raw codes: `yue -e 'print 123'`
+- Execute a YueScript file: `yue -e main.yue`
 
+## Mascot (Xiaoyu / 小玉)
 
+<img src="doc/docs/.vitepress/public/image/mascot/electrichearts_20260211A_yuescript_xiaoyu.png" width="420" alt="Xiaoyu, the YueScript mascot"/>
 
-## Editor Support
+Xiaoyu (小玉) is YueScript's official mascot, a cyber rabbit often seen perched on a crescent moon and coding on a laptop.
 
-* [Vim](https://github.com/pigpigyyy/YueScript-vim)
-* [ZeroBraneStudio](https://github.com/pkulchenko/ZeroBraneStudio/issues/1134) (Syntax highlighting)
-* [Visual Studio Code](https://github.com/pigpigyyy/yuescript-vscode)
+- English page: [here](https://yuescript.org/doc/extras/mascot.html)
+- Artwork by [Tyson Tan](https://tysontan.com)
 
+## Editor Support
 
+- [Vim](https://github.com/pigpigyyy/YueScript-vim)
+- [ZeroBraneStudio](https://github.com/pkulchenko/ZeroBraneStudio/issues/1134) (Syntax highlighting)
+- [Visual Studio Code](https://github.com/pigpigyyy/yuescript-vscode)
 
 ## License