📝 document library logger facade types

docs/api/index.md

@@ -241,6 +241,7 @@ BitLogger API navigation.
 
 ## Application and library facades
 
+- [library-logger.md](./library-logger.md)
 - [library-logger-new.md](./library-logger-new.md)
 - [logger-to-library-logger.md](./logger-to-library-logger.md)
 - [library-logger-to-logger.md](./library-logger-to-logger.md)
@@ -259,6 +260,7 @@ BitLogger API navigation.
 - [build-library-logger.md](./build-library-logger.md)
 - [parse-and-build-library-logger.md](./parse-and-build-library-logger.md)
 - [default-library-logger.md](./default-library-logger.md)
+- [library-async-logger.md](./library-async-logger.md)
 - [async-logger-to-library-async-logger.md](./async-logger-to-library-async-logger.md)
 - [library-async-logger-to-async-logger.md](./library-async-logger-to-async-logger.md)
 - [library-async-logger-new.md](./library-async-logger-new.md)

docs/api/library-async-logger.md

@@ -0,0 +1,76 @@
+---
+name: library-async-logger
+group: api
+category: facade
+update-time: 20260613
+description: Public library-facing async logger facade type used to expose a narrower surface than AsyncLogger.
+key-word:
+    - library
+    - async
+    - facade
+    - public
+---
+
+## Library-async-logger
+
+`LibraryAsyncLogger[S]` is the public library-facing async logger facade type. It wraps `AsyncLogger[S]` and keeps queue-backed async logging behavior while intentionally exposing a narrower public surface for package boundaries.
+
+### Interface
+
+```moonbit
+pub struct LibraryAsyncLogger[S] {
+  inner : AsyncLogger[S]
+}
+```
+
+#### output
+
+- `LibraryAsyncLogger[S]` - Public library-oriented async logger wrapper over a concrete sink type `S`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a public facade struct, not a type alias.
+- The wrapped sink type `S` is preserved, so sink-specific typing remains available through the facade type parameter.
+- The facade keeps common library-safe async operations such as `new(...)`, `with_target(...)`, `child(...)`, `bind(...)`, `is_enabled(...)`, `run()`, `shutdown()`, and the main async write methods.
+- Call `to_async_logger()` when later code must recover the full underlying `AsyncLogger[S]` surface.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Narrower Public Async Logger Type
+
+When a package should expose async logging capability without publishing the full `AsyncLogger[S]` API:
+```moonbit
+let logger : LibraryAsyncLogger[@bitlogger.ConsoleSink] = LibraryAsyncLogger::new(
+  @bitlogger.console_sink(),
+  target="lib.async",
+)
+```
+
+In this example, the package boundary exposes the library async facade instead of the full async logger type.
+
+#### When Need To Recover The Full Async Logger Later
+
+When a library-facing async facade should later be adapted back into the ordinary async logger surface:
+```moonbit
+let full = logger.to_async_logger()
+ignore(full.pending_count())
+```
+
+In this example, the facade can be unwrapped when broader async lifecycle or state operations are needed internally.
+
+### Error Case
+
+e.g.:
+- `LibraryAsyncLogger[S]` itself does not have a runtime failure mode.
+
+- Runtime behavior still depends on the wrapped sink `S` and async runtime support, so sink-specific or target-specific limitations remain unchanged behind the facade.
+
+### Notes
+
+1. Use `LibraryAsyncLogger::new(...)`, `build_library_async_logger(...)`, or `parse_and_build_library_async_logger(...)` when you need a value of this type.
+
+2. Use `AsyncLogger[S]` directly when exposing the full async lifecycle and state surface is acceptable.

docs/api/library-logger.md

@@ -0,0 +1,73 @@
+---
+name: library-logger
+group: api
+category: facade
+update-time: 20260613
+description: Public library-facing sync logger facade type used to expose a narrower surface than Logger.
+key-word:
+    - library
+    - logger
+    - facade
+    - public
+---
+
+## Library-logger
+
+`LibraryLogger[S]` is the public library-facing sync logger facade type. It wraps `Logger[S]` and keeps standard logging behavior while intentionally exposing a narrower public surface for package boundaries.
+
+### Interface
+
+```moonbit
+pub struct LibraryLogger[S] {
+  inner : Logger[S]
+}
+```
+
+#### output
+
+- `LibraryLogger[S]` - Public library-oriented sync logger wrapper over a concrete sink type `S`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a public facade struct, not a type alias.
+- The wrapped sink type `S` is preserved, so sink-specific typing remains available through the facade type parameter.
+- The facade keeps common library-safe operations such as `new(...)`, `with_target(...)`, `child(...)`, `bind(...)`, `is_enabled(...)`, and the main write methods.
+- Call `to_logger()` when later code must recover the full underlying `Logger[S]` surface.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Narrower Public Sync Logger Type
+
+When a package should expose logging capability without publishing the full `Logger[S]` API:
+```moonbit
+let logger : LibraryLogger[ConsoleSink] = LibraryLogger::new(console_sink(), target="lib")
+```
+
+In this example, the package boundary exposes the library facade instead of the full logger type.
+
+#### When Need To Recover The Full Logger Later
+
+When a library-facing facade should later be adapted back into the ordinary sync logger surface:
+```moonbit
+let full = logger.to_logger()
+full.info("started")
+```
+
+In this example, the facade can be unwrapped when broader logger operations are needed internally.
+
+### Error Case
+
+e.g.:
+- `LibraryLogger[S]` itself does not have a runtime failure mode.
+
+- Runtime behavior still depends on the wrapped sink `S`, so any sink-specific limitations remain unchanged behind the facade.
+
+### Notes
+
+1. Use `LibraryLogger::new(...)`, `build_library_logger(...)`, or `parse_and_build_library_logger(...)` when you need a value of this type.
+
+2. Use `Logger[S]` directly when exposing the full sync composition surface is acceptable.