Prepare 0.4.1 release documentation

README.md

@@ -14,6 +14,15 @@
 
 BitLogger 是一个使用 MoonBit 编写的结构化日志库
 
+## 🧭 后端兼容
+
+| 模块 / 能力 | native / llvm | js / wasm / wasm-gc |
+| --- | --- | --- |
+| `bitlogger` 主包 | 支持 | 支持 |
+| `file_sink(...)` | 支持 | 不支持, `native_files_supported()` 返回 `false` |
+| `bitlogger_async` | 支持原生 worker 语义 | 支持兼容实现 |
+| `examples/async_basic` | 支持 | 受 `async fn main` 入口限制, 当前不提供 |
+
 ## ❇️ 特点
 
 - 🧩 基础能力: 支持 level, formatter, sink, context field 和全局 logger.
@@ -355,8 +364,17 @@ match logger.file_runtime_state() {
 - 建议使用 `shutdown()` 停止 worker. 默认模式下, 它会先等待队列清空, 再关闭 queue, 最后等待 worker 退出
 - 提供基础生命周期观测: `is_closed()`, `is_running()`, `has_failed()`, `last_error()`
 - async worker 支持 `max_batch` 批量消费, 以及 `flush=Never|Batch|Shutdown` 的基础 flush 策略
+- 提供 `async_runtime_mode()` / `async_runtime_mode_label(...)` / `async_runtime_supports_background_worker()` 用于探测当前后端是原生 worker 还是兼容实现
+- 提供 `async_runtime_state_to_json(...)` / `stringify_async_runtime_state(...)`, 便于在启动日志或诊断输出里直接暴露当前 async runtime 模式
 - 示例见 [examples/async_basic/main.mbt](/E:/repo/MooLiteyukiBot/examples/async_basic/main.mbt:1)
-- 仅支持 `native/llvm` backend, 与同步 core 分开维护
+- `bitlogger_async` 现在支持多端编译: `native/llvm` 保留后台 worker 语义, `js` / `wasm` / `wasm-gc` 提供兼容实现
+- 由于 `moonbitlang/async` 的 `async fn main` 入口当前仍有限制, `examples/async_basic` 示例仍保持 `native` target
+
+启动时诊断示例:
+
+```moonbit
+println(stringify_async_runtime_state(async_runtime_state(), pretty=true))
+```
 
 ### Async Config
 

docs/README-en.md

@@ -6,6 +6,15 @@ BitLogger is a structured logging library written in MoonBit.
 
 BitLogger currently provides:
 
+## Backend Compatibility
+
+| Module / capability | native / llvm | js / wasm / wasm-gc |
+| --- | --- | --- |
+| `bitlogger` core package | Supported | Supported |
+| `file_sink(...)` | Supported | Not available, `native_files_supported()` returns `false` |
+| `bitlogger_async` | Native worker semantics | Compatibility implementation |
+| `examples/async_basic` | Supported | Not shipped currently because `async fn main` entry support is still limited |
+
 - log levels: `Trace`, `Debug`, `Info`, `Warn`, `Error`
 - structured key-value fields
 - plain console output
@@ -331,8 +340,17 @@ match logger.file_runtime_state() {
 - `shutdown()` is now the recommended way to stop the async worker. By default it waits for the queue to drain, closes the queue, and then waits for the worker to exit.
 - Basic lifecycle observability is also available through `is_closed()`, `is_running()`, `has_failed()`, and `last_error()`.
 - The async worker now supports batched queue draining via `max_batch` and basic flush policies through `flush=Never|Batch|Shutdown`.
+- `async_runtime_mode()`, `async_runtime_mode_label(...)`, and `async_runtime_supports_background_worker()` expose whether the current backend is using the native worker path or the compatibility implementation.
+- `async_runtime_state_to_json(...)` and `stringify_async_runtime_state(...)` make it easy to include the current async runtime mode in startup diagnostics or health output.
 - The recommended startup pattern is shown in [examples/async_basic/main.mbt](/E:/repo/MooLiteyukiBot/examples/async_basic/main.mbt:1).
-- This layer currently targets `native/llvm` only and remains isolated from the synchronous logger core.
+- `bitlogger_async` now compiles across multiple targets: `native/llvm` keeps the background worker semantics, while `js` / `wasm` / `wasm-gc` use a compatibility implementation.
+- Because `moonbitlang/async` still limits `async fn main` entry support, the `examples/async_basic` executable remains `native`-only for now.
+
+Startup diagnostic example:
+
+```moonbit
+println(stringify_async_runtime_state(async_runtime_state(), pretty=true))
+```
 
 ### Async Config
 

docs/changes/0.4.0.md

@@ -3,7 +3,6 @@
 version 0.4.0
 
 ### Feature
-
 - feat: add `ColorMode = Never | Auto | Always` for text formatter color control
 - feat: add ANSI level, target, timestamp, and field rendering to `format_text(...)`
 - feat: add `color_mode` to `TextFormatter` and `TextFormatterConfig`
@@ -22,7 +21,6 @@ version 0.4.0
 - feat: add `ColorSupport = Basic | TrueColor` and support `sink.text_formatter.color_support` so hex / RGB styles can downgrade to basic ANSI colors
 
 ### Test
-
 - test: cover ANSI text formatter rendering in `Always` mode
 - test: cover `Auto` mode fallback behavior when `NO_COLOR` is present
 - test: cover config parsing and serialization for `color_mode`
@@ -43,7 +41,6 @@ version 0.4.0
 - docs: add runtime and JSON examples for toggling style markup parsing
 
 ### Notes
-
 - `Auto` currently uses a conservative rule: if `NO_COLOR` exists, ANSI is disabled; otherwise ANSI is enabled
 - inline style markup supports both short close `</>` and named closing tags like `</red>`
 - unknown or invalid inline tags currently fall back to plain text and do not raise formatter errors

docs/changes/0.4.1.md

@@ -0,0 +1,19 @@
+## BitLogger Update Changes
+
+version 0.4.1
+
+### Feature
+
+- feat: make `bitlogger_async` compile on `js` / `wasm` / `wasm-gc` via a compatibility backend instead of abort-only stubs
+- feat: add `async_runtime_mode()` and related helpers so callers can explicitly detect native-worker vs compatibility async behavior
+- feat: add `AsyncRuntimeState` JSON/stringify helpers for exposing async runtime mode in diagnostics
+
+### Test
+
+- test: cover async logger compatibility backend queue drain behavior and keep async config roundtrip available on non-native targets
+- test: cover async runtime capability helper consistency across backend-specific implementations
+
+### Notes
+
+- `bitlogger_async` now provides a compatibility implementation on non-native targets; the standalone async example remains `native`-only because `async fn main` entry support is still toolchain-limited
+- `examples/async_basic` now prints the current async runtime state at startup so downstream projects have a minimal diagnostic pattern to copy

examples/async_basic/main.mbt

@@ -1,4 +1,6 @@
 async fn main {
+  println(@lib_async.stringify_async_runtime_state(@lib_async.async_runtime_state(), pretty=true))
+
   let raw = "{\"logger\":{\"min_level\":\"info\",\"target\":\"async.demo\",\"timestamp\":true,\"sink\":{\"kind\":\"text_console\",\"text_formatter\":{\"show_timestamp\":false,\"separator\":\" | \"}}},\"async_config\":{\"max_pending\":2,\"overflow\":\"DropOldest\",\"max_batch\":4,\"linger_ms\":5,\"flush\":\"Batch\"}}"
   let config = @lib_async.parse_async_logger_build_config_text(raw) catch {
     err => {

moon.mod.json

@@ -1,6 +1,6 @@
 {
   "name": "Nanaloveyuki/BitLogger",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "deps": {
     "maria/json_parser": "0.1.1",
     "moonbitlang/async": "0.18.1"