feat: add writer-aware rendering

[seapagan]

Summary

This PR adds an explicit writer-aware rendering path to colored_text without changing existing Display and .to_string() behavior.

It introduces RenderTarget and StyledText::render(...) so callers can make ColorMode::Auto follow stdout, stderr, or a caller-supplied terminal capability. The existing formatting path remains stdout-based for compatibility.

The PR also updates rustdoc and README examples, removes the completed writer-aware item from TODO.md, and adds targeted tests for stdout/stderr/custom-target rendering behavior and regression coverage around the preserved Display semantics.

Notes

This intentionally does not redesign global color configuration or change the default rendering behavior. It is a focused additive API for callers that know their real output target.

Summary by CodeRabbit

Release Notes

• New Features

  • Added target-aware rendering capability allowing ColorMode::Auto to evaluate terminal capability based on the output destination (stdout, stderr, or explicit terminal setting).
  • Introduced new render() method enabling explicit control over colour rendering decisions for different output targets.

• Documentation

  • Updated documentation with examples demonstrating target-aware rendering behaviour and terminal detection across different outputs.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5660ccae-a743-4d78-9377-d6b92034f230

📥 Commits

Reviewing files that changed from the base of the PR and between 53a0b5a and c1058cc.

📒 Files selected for processing (6)

• README.md
• TODO.md
• src/config.rs
• src/lib.rs
• src/style.rs
• src/tests.rs

💤 Files with no reviewable changes (1)

• TODO.md

---

📝 Walkthrough

Walkthrough

This pull request introduces target-aware rendering capabilities to the coloured text library. A new RenderTarget enum enables rendering decisions to be based on specific output destinations (stdout, stderr, or explicit terminal mode), complemented by a new render() method on StyledText and refactored colour policy logic in the config module.

Changes

Cohort / File(s)	Summary
Documentation README.md, TODO.md	README expanded with feature documentation and example for target-aware rendering; TODO item about writer-aware API removed as resolved.
Configuration & Terminal Detection src/config.rs	Added public RenderTarget enum with variants for stdout, stderr, and explicit terminal state. Introduced should_colorize_for(target) function with target-specific terminal detection; existing should_colorize() now delegates to stdout target. Test infrastructure expanded with separate overrides for stdout and stderr terminal state.
Public API Exports src/lib.rs	RenderTarget enum re-exported alongside ColorMode and ColorizeConfig; crate documentation updated with note on using render(target) to direct ColorMode::Auto to non-stdout destinations.
Rendering Logic src/style.rs	Added public render(target: RenderTarget) method on StyledText returning target-aware rendered output. Introduced internal render_with_color_policy(bool) to centralise rendering logic. Updated Display implementation to delegate to centralised logic.
Tests src/tests.rs	Extended TestStateGuard to manage stderr terminal overrides. Added comprehensive tests for stderr rendering under RenderTarget::Stderr, ColorMode::Auto, and validation that Display output remains stdout-based in auto mode.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: modernize color composition and crate internals #5: Foundational PR establishing terminal-detection and colour-policy logic that this PR extends with target-aware rendering capabilities.

Poem

🐰 A render for each tint, from stdout to stderr's flight,
Now targets choose their colours—auto, always, never quite right!
The rabbit hops between destinations with glee,
Where each destination's destiny's plain to see. ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: add writer-aware rendering' directly and accurately describes the main change: introduction of target-aware rendering functionality via RenderTarget and StyledText::render() method.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/writer-aware-rendering

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}