feat: add FlowConfirmation, the approval card, and its message part

[divyanshub024]

Summary

Adds FlowConfirmation, roadmap item 19: the approval card for gated actions.

• The Figma frame's pending state: a 16px asterisk in the warning accent beside the title, the host-written request, and right-aligned Reject (outlined) and Approve (filled) buttons on the raised surface. Every color and text style maps to theme tokens; metrics are per-component spec constants with padding/borderRadius overrides.
• Approved and rejected settle the card: the accent flips to success or error and the buttons collapse into one non-interactive row of the same footprint, so the card's height holds. The widget is stateless; a tap reports intent and the host re-renders with the new status.
• FlowConfirmationPart joins the sealed part model and renders the card in a turn. The decision reports through FlowThread.onConfirmationRespond with the message, the part, and the decision; approveLabel/rejectLabel/approvedLabel/rejectedLabel thread like the error card's strings. The package ships no strings.
• FlowConfirmationStyle joins the component styles with a FlowTheme.confirmationStyle default. The three state accents recolor a state's marks (asterisk, settled glyph, settled wash) with one override.
• The thinking indicator's private asterisk painter moves to lib/src/utils/flow_asterisk_painter.dart (internal, not exported) so both marks stay one drawing; behavior unchanged.
• Docs page, playground stage (Pending / Approved / Rejected / In a thread), README row, _redirects line, and changelog entry included.

Reviewer notes:

• The buttons are private (_ConfirmationButton), like the error card's retry pill, until the design system's Button lands and absorbs them.
• A button renders only when both its label and callback are set; a pending card with neither pair is a read-only notice, for chrome staged before the request is answerable.
• Only the pending state has a Figma frame; approved and rejected are derived from tokens (the settled row's fill is the accent at the status containers' 6%, so the default equals successContainer/errorContainer).
• One deliberate departure from the frame: the title and the settled label read in the ink ramp (onSurfaceVariant, onSurface), not the accent. In the light preset the accents on the card measure 2.47:1 (warning), 3.53:1 (success on its wash) and 4.45:1 (error), all under WCAG AA for text; the ink pairings measure 8.6:1 and 17:1. The accent still carries the state on the asterisk, the settled glyph and the wash.

Screenshots

New component, so no before column.

Pending, light	Pending, dark	Approved	Rejected	In a thread

How this was verified

• Playground confirmation stage: all four variants, light and dark. Tapping Approve or Reject settles the live card and the thread card in place; the card's height does not move across states and the thread does not scroll-jump.
• Headless screenshots of the embeds (?embed=confirmation&variant=...&theme=...) compared against the Figma frame at 480 wide.
• WCAG contrast computed for every text pairing in both presets from the token values.
• /playground/thinking-indicator checked after the painter extraction; the mark is unchanged.
• flutter analyze clean at the root and in example/ and playground/; dart format . applied.

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

Low Risk
Additive UI API and optional thread callbacks; no auth, networking, or breaking changes to existing message rendering paths.

Overview
Ships FlowConfirmation, an approval card for gated actions: pending shows host-localized title, message (live region), and optional approve/reject buttons; approved/rejected collapse actions into a fixed-height settled row with success/error accents. The widget is stateless—taps report intent and the host re-renders with FlowConfirmationStatus.

Adds FlowConfirmationPart to the message part model and wires it through FlowMessage / FlowThread via onConfirmationRespond(message, part, approved) plus thread-level button labels, mirroring the error-card pattern. FlowConfirmationStyle and FlowTheme.confirmationStyle support theming; public exports and docs/playground/changelog/README/roadmap mark Confirmation as shipped.

Refactors the thinking indicator’s asterisk into shared internal FlowAsteriskPainter (behavior unchanged).

^{Reviewed by Cursor Bugbot for commit 748579d. 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 cb21256. Configure here.}