feat: error state with retry

[divyanshub024]

Summary

Roadmap row 20. Adds FlowErrorState, the failure card: error glyph, host-written title and message, and a labelled retry pill. Adds FlowErrorPart to the message model and threads onRetry, errorTitle, retryLabel through FlowMessage and FlowThread.

Breaking (pre-1.0): a failed assistant turn no longer recolors its content into the errorContainer bubble. Delivered parts keep their normal ink and the turn closes with the card. A turn with status: error and no FlowErrorPart still renders a default card, so status-only hosts keep a visible failure state. The user bubble's error treatment is unchanged.

Notes for review:

• Anatomy follows the pre-rewrite FlowErrorBubble and FlowRetryButton, translated to the new tokens. First consumer of the error color role.
• FlowErrorPart(message, retryable) mirrors the block stac_ai already emits; FlowThread.onRetry(message) matches its retry loop. retryable: false hides the pill even when retry is wired.
• Card metrics and the 40% hairline are placeholders until the Figma file has a frame for this component.
• Shares CHANGELOG, roadmap rows, and flow_message.dart lines with feat: code block with built-in syntax highlighting #12. Whichever merges second resolves trivial conflicts.

Screenshots

Before	After
Whole turn recolored into the errorContainer bubble; no message, no retry

How this was verified

Playground Error State stage on Chrome (web), both themes. Card and Minimal variants render the full and message-only anatomies. Failed turn shows a reply that died mid-sentence: partial text keeps normal ink, card sits at the part gap, Retry removes the card and resumes the streaming reveal to completion. Docs site builds clean.

Checklist

• flutter analyze lib and flutter analyze in example/ and playground/ are clean
• dart format . applied
• Exercised in the playground — with a stage demo added or updated if this is a new component or variant
• No new entries under dependencies: in pubspec.yaml (Flutter SDK and flutter.dev packages only)
• Nothing model-facing — no prompts, schemas, or provider/network calls
• New public API is exported from lib/flow_ui.dart and documented in docs/ and the README table
• CHANGELOG.md updated for user-facing changes, with breaking changes called out
• PR title follows conventional commits (feat:, fix:, refactor:, docs:, chore:)

---

Note

Medium Risk
Public API and a breaking change to how failed assistant turns render; hosts that relied on the errorContainer bubble will see a different layout and need to wire retry/copy.

Overview
Ships FlowErrorState: a failure card (glyph, host-written title/message, optional retry pill) plus FlowErrorPart. onRetry, errorTitle, and retryLabel are threaded through FlowMessage and FlowThread. Retry is host-owned; retryable: false hides the pill.

Breaking: a failed assistant turn no longer recolors its content into an errorContainer bubble. Delivered parts keep normal ink and the turn closes with the card (a default one if there is no FlowErrorPart). User-bubble error treatment is unchanged. Docs, changelog, and a playground demo cover standalone, minimal, and in-thread retry.

^{Reviewed by Cursor Bugbot for commit 69fcda5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d23a6b0. Configure here.}