📝 document formatter model aliases

docs/api/index.md

@@ -65,9 +65,12 @@ BitLogger API navigation.
 - [color-mode.md](./color-mode.md)
 - [color-support.md](./color-support.md)
 - [style-markup-mode.md](./style-markup-mode.md)
+- [text-style-type.md](./text-style-type.md)
 - [text-style.md](./text-style.md)
+- [style-tag-registry-type.md](./style-tag-registry-type.md)
 - [style-tag-registry.md](./style-tag-registry.md)
 - [default-style-tag-registry.md](./default-style-tag-registry.md)
+- [text-formatter-type.md](./text-formatter-type.md)
 - [text-formatter.md](./text-formatter.md)
 - [text-formatter-config.md](./text-formatter-config.md)
 - [default-text-formatter-config.md](./default-text-formatter-config.md)

docs/api/style-tag-registry-type.md

@@ -0,0 +1,71 @@
+---
+name: style-tag-registry-type
+group: api
+category: formatter
+update-time: 20260613
+description: Public style-tag registry alias used for formatter tag lookup and customization.
+key-word:
+    - style
+    - registry
+    - alias
+    - public
+---
+
+## Style-tag-registry-type
+
+`StyleTagRegistry` is the public registry type used to map style-tag names to `TextStyle` values. It is a direct alias to the registry model used by local formatter tag sets, global tag customization, and default tag helpers.
+
+### Interface
+
+```moonbit
+pub type StyleTagRegistry = @utils.StyleTagRegistry
+```
+
+#### output
+
+- `StyleTagRegistry` - Public style-tag registry value containing named `TextStyle` entries.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a formatter instance.
+- The current registry model stores named `TextStyle` entries internally.
+- `style_tag_registry()` creates an empty value of this type.
+- `default_style_tag_registry()`, `global_style_tag_registry()`, and formatter methods such as `with_style_tags(...)` all operate on this same public registry type.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Registry For Local Formatter Tags
+
+When style tags should be assembled before they are attached to a formatter:
+```moonbit
+let tags : StyleTagRegistry = style_tag_registry()
+  .set_tag("accent", fg=Some("#4cc9f0"), bold=true)
+```
+
+In this example, the registry remains a standalone typed value until a formatter uses it.
+
+#### When Need To Pass A Registry Through Shared Setup Code
+
+When application boot code should return or store a reusable tag set:
+```moonbit
+let tags = default_style_tag_registry()
+```
+
+In this example, the alias makes it explicit that the value is the registry itself rather than one formatter.
+
+### Error Case
+
+e.g.:
+- `StyleTagRegistry` itself does not have a runtime failure mode.
+
+- Unknown tag lookups simply produce no matching style instead of raising an error.
+
+### Notes
+
+1. Use `style_tag_registry()` or `default_style_tag_registry()` when you need a value of this type in code.
+
+2. Attach this registry to a `TextFormatter` when tag lookup should affect actual rendered output.

docs/api/text-formatter-type.md

@@ -0,0 +1,71 @@
+---
+name: text-formatter-type
+group: api
+category: formatter
+update-time: 20260613
+description: Public text-formatter alias used for structured text rendering configuration and reuse.
+key-word:
+    - formatter
+    - text
+    - alias
+    - public
+---
+
+## Text-formatter-type
+
+`TextFormatter` is the public reusable formatter type used for readable text log rendering. It is a direct alias to the formatter model used by text sinks, formatter customization helpers, and direct `format_text(...)` calls.
+
+### Interface
+
+```moonbit
+pub type TextFormatter = @utils.TextFormatter
+```
+
+#### output
+
+- `TextFormatter` - Public text-rendering value containing timestamp, level, target, field, template, color, markup, and style-tag settings.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a sink or logger by itself.
+- The current fields are `show_timestamp`, `show_level`, `show_target`, `show_fields`, `separator`, `field_separator`, `template`, `color_mode`, `color_support`, `style_markup`, `target_style_markup`, `fields_style_markup`, and `style_tags`.
+- `text_formatter(...)` constructs this type as the main runtime entry point.
+- The same value type is consumed by `format_text(...)`, `text_console_sink(...)`, and config-to-runtime bridges such as `TextFormatterConfig::to_formatter()`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Reusable Formatter Value
+
+When one formatter should be created once and shared across multiple sinks or formatting calls:
+```moonbit
+let formatter : TextFormatter = text_formatter(show_timestamp=false, template="[{level}] {message}")
+```
+
+In this example, the formatter remains a reusable typed value instead of being tied to one output path.
+
+#### When Need Direct Formatting Without Building A Logger
+
+When code should format a record through a previously prepared formatter:
+```moonbit
+let formatter = text_formatter(color_mode=ColorMode::Always)
+println(format_text(Record::new(Level::Info, "started"), formatter=formatter))
+```
+
+In this example, the formatter type is used directly as a rendering dependency.
+
+### Error Case
+
+e.g.:
+- `TextFormatter` itself does not have a runtime failure mode.
+
+- Unknown style tags or unsupported visible styling fall back to plain text behavior instead of raising formatter-construction errors.
+
+### Notes
+
+1. Use `text_formatter(...)` when you need a value of this type in code.
+
+2. Use `TextFormatterConfig` when the same rendering policy should be stored or transported as config data first.

docs/api/text-style-type.md

@@ -0,0 +1,70 @@
+---
+name: text-style-type
+group: api
+category: formatter
+update-time: 20260613
+description: Public text-style alias used for formatter tag definitions and config-driven style values.
+key-word:
+    - style
+    - formatter
+    - alias
+    - public
+---
+
+## Text-style-type
+
+`TextStyle` is the public value type used to describe foreground color, background color, and emphasis flags for formatter styling. It is a direct alias to the style model used by tag registries, formatter config maps, and inline-style resolution.
+
+### Interface
+
+```moonbit
+pub type TextStyle = @utils.TextStyle
+```
+
+#### output
+
+- `TextStyle` - Public style value containing `fg`, `bg`, `bold`, `dim`, `italic`, and `underline`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a formatter instance or registry.
+- The current fields are `fg : String?`, `bg : String?`, `bold : Bool`, `dim : Bool`, `italic : Bool`, and `underline : Bool`.
+- `text_style(...)` constructs this type as the normal handwritten entry point.
+- The same value type is stored in `StyleTagRegistry` entries and in `TextFormatterConfig` style-tag maps.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Style Value For Reuse
+
+When one style should be defined once and reused across tag registrations or config assembly:
+```moonbit
+let accent : TextStyle = text_style(fg=Some("#4cc9f0"), bold=true)
+```
+
+In this example, the style stays as structured data instead of being tied to one formatter immediately.
+
+#### When Need To Pass A Style Through Formatter Configuration
+
+When style values should be assembled first and attached later:
+```moonbit
+let warning = text_style(fg=Some("yellow"), bold=true)
+```
+
+In this example, the alias makes it explicit that the value can travel through config or registry code unchanged.
+
+### Error Case
+
+e.g.:
+- `TextStyle` itself does not have a runtime failure mode.
+
+- A style value can still produce no visible ANSI effect if the chosen formatter disables color or style markup.
+
+### Notes
+
+1. Use `text_style(...)` when you need a value of this type in code.
+
+2. Use `StyleTagRegistry` when named reusable style lookup is needed instead of one standalone style value.