feat: add FlowToast, the floating notice, and showFlowToast

[divyanshub024]

Summary

Adds the toast from the Flow UI Figma frames: a floating notice with a glyph, one wrapping line and a close cross on a frosted card.

• FlowToast: the card. Host-supplied glyph, one line that wraps, a close cross; surfaceBright at 80% under the firm hairline on a 12px corner, the theme's shadow at a 24 blur, labelMediumEmphasised in ink. The glyph and the cross centre on the first line; the cross disc is pinned from outside the row, so the card keeps the design's height whether the line wraps or not.
• showFlowToast and FlowToastHandle: float the card in the nearest Overlay with no setup. 358 wide, 24 in from the top end corner from 600px; full width inside 16 below that. Stacked as a deck: newest in front, older cards peeking out above it, three at most. Hover fans the deck out and pauses every clock; under assistive navigation it stays fanned out with no auto-dismiss. 4s dwell, duration: null stays. The handle dismisses early or awaits closed.
• Placement distances absorb the display's own insets rather than adding to them (a notch pushes the card only as far as it exceeds the 24), the chat view's rule for its bottom edge.
• FlowToastStyle with a FlowTheme.toastStyle slot. The failure form is iconColor: colors.error; no tone enum, the host owns the glyph.
• The 3px frost is painted by the layer behind the fading card, not inside it: a BackdropFilter under an Opacity samples the fade's own layer, not the page (the preview's rule).
• Playground stage with Neutral, Error, Sticky, Stacked and Card variants. The live variants fill the stage inside an Overlay.wrap, so toasts land at the pane's top end corner on the web canvas and at the top of the screen in the phone frame. The stage now reports its floating variant pills to stage-filling demos as a 56px top inset so top-anchored chrome lands under them; this also insets the attachments Drop variant's chat surface.
• Docs page, README row, changelog, roadmap and theming entries. The example shows a toast for a copied message instead of a Material snackbar.

Reviewer notes:

• Keyboard focus never reaches the cross: the overlay sits outside every route's focus scope. Hosts bind Escape to handle.dismiss(); documented on the page.
• Toast sits under Surfaces as item 29 in the roadmap tables, to avoid renumbering.

Screenshots

Before	After
No toast; the example raised a Material SnackBar('Copied')	Light web canvas, light stacked with the frost over the trigger, dark phone frame, and the card alone: images attached in the chat thread, dragged in here

How this was verified

• flutter analyze lib, flutter analyze in example/ and playground/; dart format ..
• Playground on an iPad simulator build (real fonts, real frames): every variant, light and dark, web canvas and phone frame. The frost visibly blurs the trigger under a stack.
• Lifecycle in a throwaway widget test, deleted afterwards so test/ stays empty: 4s dismissal, hover pause, cross and handle, eviction past three, dismiss before mount, overlay teardown under live toasts, reduced motion, accessible navigation, wide and compact placement, RTL.
• Docs page renders at /components/toast, in the sidebar after Confirmation.

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
• Any new entry under dependencies: in pubspec.yaml is flutter.dev-published, forces no configuration on hosts that never use the feature, and is argued in this PR
• 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
New overlay lifecycle (~800 lines) affects global UI stacking, timers, and accessibility behavior; integration risk is moderate but localized to optional toast calls rather than core chat paths.

Overview
Adds Toast as a shipped surface: a frosted floating notice with host icon, wrapping message, and dismiss control, plus showFlowToast to mount it in the nearest Overlay with no host wiring.

FlowToast is the card-only widget (live region, optional dismiss). showFlowToast owns placement (wide vs compact), a three-deep stacked deck with hover fan-out and paused timers, default 4s auto-dismiss (duration: null for sticky work), FlowToastHandle for early dismiss/closed, and a 3px page blur drawn behind the fade (not inside the card). FlowToastStyle and FlowTheme.toastStyle follow the existing component-style pattern.

The example app swaps the copy SnackBar for a toast. Docs, changelog, roadmap, and README list the API; the playground adds toast variants and bumps top inset for stage-filling demos so toasts sit under variant pills.

^{Reviewed by Cursor Bugbot for commit 1f05090. 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 dd093f9. Configure here.}