docs(ui): make docs snapshots authentic to the production SDK (#2676)

* docs(ui): pin platform and align emoji baseline in docs snapshots

Doc snapshots previously rendered differently depending on the host running
the tests (macOS dev machines vs Linux CI) because three platform reads were
unpinned: `CurrentPlatform.type`, `defaultTargetPlatform`, and
`Theme.of(context).platform`. Code paths conditional on any of these would
flip — most visibly the mic button visibility in `StreamMessageComposer`.

Introduce `docsGoldenTest`, a wrapper around alchemist's `goldenTest` that
pins all three platform reads to iOS:

- `CurrentPlatform.debugCurrentPlatformOverride` and
  `debugDefaultTargetPlatformOverride` are set inside the alchemist
  `pumpWidget` hook (i.e. inside the test body) and reset via
  `whilePerforming`'s cleanup callback — the latest hook before
  `_verifyInvariants` enforces that foundation debug vars are null.
- `Theme.of(context).platform` is pinned via `ThemeData.platform` on
  `docsScreenshotsTheme()`.

Also adopt the `GoldenComponentFactory` from #2649, wired automatically
into every snapshot through the same `pumpWidget` hook so no per-test
plumbing is needed. It overrides the `emoji` component builder to add an
8 px top padding, nudging emoji glyphs to align with surrounding text.

Goldens regenerated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): fall back to platform emoji fonts for inline glyphs

Roboto carries no emoji glyphs, so any inline emoji in plain Text widgets
(message bodies, etc.) would render as tofu. Add the emoji font families
loaded by `_loadEmojiFont` to the textTheme's fallback chain so Flutter
finds the glyph automatically.

Defensive change — no current snapshot has inline emoji in plain text;
goldens unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): render docs snapshots with real San Francisco on macOS

Pinning the platform to iOS makes Material's iOS typography request the
`CupertinoSystemDisplay` and `CupertinoSystemText` family aliases. On a
real device the platform resolves those to SF Pro automatically; the
Flutter test renderer has no such mapping, so until now we worked around
it by overriding everything to Roboto.

Register `/System/Library/Fonts/SFNS.ttf` under both alias family names
via `FontLoader` in `_loadAppleSystemFont`. With that in place we can
drop the `fontFamily: 'Roboto'` override on `ThemeData` and switch Stream's
`StreamTextTheme` to `CupertinoSystemText` — Material widgets, message
text, and headings all now render in authentic SF on macOS.

The loader is a no-op outside macOS. Linux CI doesn't have SFNS.ttf, but
its goldens use `obscureText: true` so every glyph is replaced with an
Ahem block regardless — no behavioral change there.

Goldens regenerated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): group host-font loaders behind a single entry point

`_loadEmojiFont` and `_loadAppleSystemFont` both register absolute-path
host system fonts that aren't in any asset manifest. Wrap them in a
single `_loadHostSystemFonts()` so `testExecutable` reads as two awaits
(asset-manifest fonts, then host fonts) instead of three.

Pure refactor — no behavior change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci(goldens): split update_goldens into SDK/docs targets with platform-aware runners

The single Linux job previously regenerated `goldens/ci/*.png` for every
alchemist-dependent package — which is what the SDK packages commit, but
not what `docs_screenshots` commits. Docs snapshots commit
`goldens/macos/*.png` (real-text variant rendered with SF on macOS); the
Linux runner can never produce them.

Split the workflow by adding a `workflow_dispatch.inputs.target` choice
(`sdk` | `docs`) that routes to one of two jobs:

- `update_sdk_goldens` on ubuntu-latest — runs the new
  `update:goldens:sdk` melos script, which skips `docs_*` packages.
  Auto-commits `packages/**/goldens/**/*.png`.
- `update_docs_goldens` on macos-latest — runs `update:goldens:docs`,
  scoped to `docs_*` and exporting `UPDATE_PLATFORM_GOLDENS=1`.
  Auto-commits `docs/**/goldens/macos/*.png`.

`UPDATE_PLATFORM_GOLDENS` is a carve-out in
`docs/docs_screenshots/test/flutter_test_config.dart`: by default the CI
variant gate (`isRunningInCi → CiGoldens only`) skips the platform
snapshots, which is correct for any other runner; setting the env var
flips PlatformGoldens back on so the macOS job actually regenerates the
files it's there for.

The macOS job stays manual-dispatch only and is opt-in via the choice
input — macOS runner minutes cost ~10x Linux on GitHub Actions, so
defaulting to `sdk` keeps routine regenerations cheap.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci(goldens): docs_screenshots emits only the platform variant

`.gitignore` for docs_screenshots commits only `goldens/macos/*.png` —
the CI/obscured variant exists transiently on disk but is never inspected
and never compared against anything in the repo. Generating it wastes
test time and obscures intent.

Simplify `docs/docs_screenshots/test/flutter_test_config.dart` to enable
only `PlatformGoldensConfig` regardless of the host. The
`UPDATE_PLATFORM_GOLDENS` env-var carve-out is no longer needed (the gate
it flipped is gone), so drop it from `update:goldens:docs` in melos.yaml.

Side effect: with PlatformGoldens always on, running docs_screenshots
tests on a Linux runner would compare against a nonexistent `goldens/linux/`
set and fail. Add `--ignore="docs_*"` to the `test:flutter` melos script
so the regular Linux CI pipeline skips them entirely — docs goldens are
regenerated and verified through the dedicated macOS `update_docs_goldens`
job instead.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: Update Docs Snapshots

* docs(ui): drop redundant theme-level emoji fontFamilyFallback

`DefaultStreamEmoji` carries its own `fontFamilyFallback` chain pointing
at the platform emoji fonts, and that's the path every emoji in the
current snapshot set takes. No test renders an inline emoji glyph
through a plain Text widget, so the theme-level fallback was defending a
case that doesn't exist.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): try multiple SF font paths in _loadAppleSystemFont

Mirrors the candidate-list pattern in `_loadEmojiFont`: walk a list of
absolute font paths and bail at the first one that exists. Catches
pre-Catalina macOS where the system font ships as `SFNSDisplay.ttf`
instead of the modern `SFNS.ttf`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): render user and channel avatars from design-system fixtures

Stream's `StreamAvatar` / `StreamNetworkImage` / `CachedNetworkImage`
chain doesn't fetch real network bytes in tests — and even if it tried,
`flutter_test`'s HttpClient short-circuits every request. Up until now
every `User(image: 'https://…')` rendered as the gradient-letter
placeholder, which makes the docs look like nothing's loading.

Intercept the chain at the `StreamComponentFactory.networkImage` hook:
`GoldenComponentFactory` now installs a builder that returns an
`Image.memory` backed by one of 18 portrait fixtures sourced directly
from Stream's Chat SDK Design System Figma (node 2867:55922, "User
Photo"). Files live in `test/fixtures/avatars/` and are named to match
the Figma component names (e.g. `amelia-moore.png`); add or replace one
by dropping a PNG there and listing its slug in `_avatarSlugs`.

URLs hash deterministically into the list, so the same
`User(image: 'https://docs.fixture/avatar/bob.png')` always resolves to
the same person across snapshots.

To make this actually fire across the suite:

- `setupMockChannel` stubs `channel.image` and the default member User's
  image to synthetic `https://docs.fixture/avatar/{id}.png` URLs. Every
  channel previously had `channel.image: null`, so the channel-avatar
  branch never even reached `StreamNetworkImage`.
- Sweep across `User(id: '…')` constructions in test files — same
  `image:` URL pattern derived from the id — so user avatars in poll,
  thread, message, and search snapshots route through the same fixture.
- `docsGoldenTest` default `pumpBeforeTest` is now alchemist's
  `precacheImages` (was `onlyPumpAndSettle`). Without that pump,
  `MemoryImage` decode races the frame and the avatar circle shows the
  default background color instead of the actual bytes.

Goldens regenerated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): use design-system sample users and member-derived channel avatars

Two related cleanups, both about making the snapshots reflect a real
chat in a real product.

**Sample users in one file.** Inline `User(id: 'user-2', name: 'Bob', …)`
constructions were scattered across nine test files with arbitrary IDs
that didn't match anything in the design system. Move all of them into
`test/src/sample_users.dart` as named constants (`ameliaMoore`,
`noahSmith`, …) corresponding to the 18 named users in Figma node
2867:55922. Tests now reference users by name; adding or replacing a
sample user is one constant + one fixture PNG.

**Channel avatars derive from members.** `setupMockChannel` previously
stubbed `channel.image` to a synthetic URL, so every channel snapshot
took the `channel.image` branch in `StreamChannelAvatar` and rendered a
single circle. Real chats almost never set `channel.image` on group
channels — the avatar is derived from the member set. Stub
`channel.image` back to `null`, default the member list to three sample
users so the channel-list snapshot shows the stacked group avatar from
`StreamUserAvatarGroup`. Distinct DM channels with two members render
the other member's avatar, matching production behavior.

Also along the way:

- `golden_network_image.dart` now resolves URLs by slug (extracted from
  the last path segment), with a hash-based fallback for dynamic URLs
  like `user-$messageId` that don't match a known slug. `User(image:
  'https://docs.fixture/avatar/amelia-moore.png')` now deterministically
  renders Amelia regardless of how the URL hashes.
- `asOwnUser(user)` helper on `sample_users.dart` for `currentUser`
  stubs.
- `user_list_view` snapshot iterates the full 18-user roster with a
  seeded `Random(42)` toggling online indicators — varied without being
  flaky.

Goldens regenerated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): vary default channel member count per channel id

Default channels all picked the same 3 members (Amelia, Charlotte,
Elena), so every channel-list row rendered the same stacked group
avatar. Switch the `setupMockChannel` fallback to a per-channel
deterministic pick: seed a `Random` off the channel id, choose between
2 and 6 sample users, shuffle them in. Each channel now gets a unique
group avatar (Engineering happens to land on 6 → triggers the "+4"
overflow chip from `StreamUserAvatarGroup`, exactly like a real busy
channel would).

Determinism comes from a stable djb2-ish content hash, not Dart's
process-randomized `String.hashCode` — so the same channel id always
picks the same member set across runs.

Goldens regenerated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): trim user_list_view back to 500h

The full 18-user roster overflows naturally — keeping the snapshot at
the prior 500 px height keeps it consistent with the surrounding
fixtures (channel previews, message lists) and avoids a one-off tall
golden in the docs grid.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): use sample users in message search results

`_makeSearchResult` previously built inline `User(id: 'user-$messageId',
…)` so the URL slug couldn't match any fixture and the avatar resolved
through the hash fallback — names ("Alice", "Bob", "Carol", "Dave")
ended up paired with arbitrary portraits. Pass a `User` directly so the
slug aligns with the photo, and use design-system constants (Amelia,
Noah, Charlotte, Liam) so the names match the rest of the docs.

Side benefit: the first row now reads "You in General" because
`ameliaMoore` is the current user — accurate to how
`StreamMessageSearchListView` renders the current user's own messages.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): centralize the signed-in identity as `ownUser`

A single [OwnUser] constant in `sample_users.dart` replaces the
per-file `final _currentUser = ameliaMoore;` / `final _user1 = …;`
aliases and the ad-hoc `asOwnUser(ameliaMoore)` calls scattered across
tests. Because `OwnUser` is-a `User`, the same constant drops into both
`currentUser` stubs and any place a `User` is expected (message authors,
member lists, etc.) — so "who is signed in" is decided in exactly one
place across every doc snapshot.

`asOwnUser` is kept for the rare case where a test needs to promote a
different sample user (e.g. variant tests).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): scope user_list_view back to 5 users

Match the original snapshot's row count so the diff against the prior
golden stays compact — the design-system roster is still demonstrated
elsewhere via avatars rendering with the new fixture set.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): align appbars, bottom nav, and slidable actions with the sample app

The chat-list, thread-list, and swipe-action snapshots were dressed in
generic Material chrome — `AppBar('Stream Chat')`, a fictional
`Chats / Mentions / Threads` bottom nav, a red "Delete" swipe-action.
Real Stream apps look nothing like that, so the docs misrepresented the
product.

Rework the chrome to match `sample_app`:

- **Channel list & slidable channel list** (`channel_preview_test.dart`)
  swap the generic `AppBar` for `StreamChannelListHeader(title:
  Text('Chats'))`. The leading slot resolves to the signed-in user's
  avatar (Amelia) via the existing `currentUser` stub.
- **Swipe channel reveal** (same file) shows
  `streamIcons.more` (surface bg) + `streamIcons.mute` (accent bg) — the
  exact actions `sample_app/lib/widgets/channel_list.dart` ships.
- **Thread list** (`thread_list_view_test.dart`) uses
  `StreamChannelListHeader(title: Text('Threads'))` and a four-tab
  bottom nav: `Chats` (`streamIcons.messageBubble` / `messageBubbleFill`),
  `Threads` (`streamIcons.thread` / `threadFill`, active),
  `Drafts` (`Icons.drafts_outlined` / `drafts_rounded`), and
  `Reminders` (`Icons.bookmark_outline_rounded` / `bookmark_rounded`).
  The Material icons mirror the sample's actual choices — Stream
  doesn't ship a Drafts or Reminders icon.
- **Poll creator AppBar** (`poll_test.dart`) replaces `Icons.close` and
  `Icons.send` with `streamIcons.xmark` and `streamIcons.send` —
  thinner, design-system shapes.

Goldens regenerated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): use StreamAppBar/StreamButton + wire the trailing slot on list headers

Two follow-ups now that we're using the SDK's header components:

- **Poll creator** swaps Material `AppBar` + `IconButton` for `StreamAppBar`
  + `StreamButton.icon`, the toolbar + button primitives the SDK ships
  for modal/dialog chrome. Circular icon buttons, hairline bottom
  divider, design-system padding — same shape any production app gets
  for free when using these widgets.
- **Channel list, slidable channel list, and thread list** add a trailing
  `StreamButton.icon(icon: Icon(icons.plus))` to `StreamChannelListHeader`.
  The docstring for `StreamChannelListHeader` calls this out as the
  canonical "new chat" affordance, and rendering it makes the header's
  three-slot shape (avatar leading / title / action trailing)
  immediately visible to readers.

Also revert `user_list_view_test.dart` to the explicit five-User array
style — keeps the original visual layout and drops the dart:math import.

Goldens regenerated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): StreamSheetHeader for poll creator + trailing slot on header demos

Two follow-on tweaks to make the header demos cover the full SDK API:

- Poll creator now uses `StreamSheetHeader` (the SDK's modal/dialog
  toolbar) instead of `StreamAppBar`. Visually similar but semantically
  matches what a sheet-launched poll creator actually renders in
  production. Skipped `automaticallyImplyLeading: true` because our
  test scaffold has no popable route — kept the explicit leading
  button.
- `channel_list_header_test.dart` now wires `trailing: StreamButton.icon(
  icon: Icon(context.streamIcons.plus))` on both snapshots. Combined
  with the existing leading (avatar) and `subtitle: Text('12 channels')`,
  the "custom subtitle" snapshot now demos every slot of
  `StreamChannelListHeader` in a single golden.

Goldens regenerated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): authenticate message actions modal + trim bottom nav to chat/threads

Two corrections that bring the docs closer to the production SDK:

- **Message widget actions** stopped reinventing the action list. The
  snapshot used to render Material `Icons.*` against hand-rolled
  placeholder action types — visually plausible but missing the SDK's
  canonical "Mark as Unread" and "Flag Message" entries, and unaware
  of channel capabilities. Switch to
  `StreamMessageActionsBuilder.buildActions(context: ..., message: ...,
  channel: ..., currentUser: ...)` so the modal renders exactly what a
  user sees on long-press: Stream icons, translated labels, capability-
  aware visibility. Channel mock gets the full capability set
  (`sendReply`, `pinMessage`, `quoteMessage`, `readEvents`,
  `update*Message`, `delete*Message`) so every default action surfaces.
- **Thread list bottom nav** trims `Chats / Threads / Drafts / Reminders`
  to just `Chats / Threads` (matches what `sample_app` actually shows
  by default; Drafts and Reminders are config-gated additions there).
  Theming wraps the `BottomNavigationBar` in a `DecoratedBox` with
  `backgroundElevation1` + `borderSubtle` top divider, sets `elevation:
  0`, `iconSize: 20`, `textPrimary`/`textTertiary` item colors, and
  `metadataEmphasis` label styles — copied verbatim from
  `sample_app/lib/pages/channel_list_page.dart`.

Goldens regenerated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): partition destructive actions, match SDK button styling, vary thread authorship

Four corrections to the SDK alignment:

- Message actions modal wraps the builder output in
  `StreamContextMenuAction.partitioned(...)` so the destructive **Delete
  Message** lands at the end with a separator above it — the canonical
  grouping the SDK exposes for that purpose.
- Poll creator's `StreamSheetHeader` buttons now use
  `StreamButton.icon(type: .outline, style: .secondary)` for the
  leading dismiss button (matching the SDK's auto-implied leading on
  sheet routes) and `type: .solid` for the trailing confirm — the
  pattern `sample_app/lib/widgets/add_members_sheet.dart` uses.
- `_makeThread` now takes a `parentAuthor` so the thread list renders
  mixed authorship — one thread started by the current user (rendered as
  "You: …"), the others by Charlotte and Noah. Previously every thread
  was authored by `ownUser`, which made the list look like a single-user
  digest.
- Thread list empty state drops the hand-rolled `Center(Column(...))`
  and lets `StreamThreadListView` render its default
  `StreamScrollViewEmptyWidget` (messageBubblesLarge icon + translated
  "Reply to a message to start a thread") — same widget production
  users see.

Goldens regenerated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): bump message_widget_actions constraint to fit the full action list

`partitioned` adds Flag and Mute on top of Reply/Thread/Mark/Copy/Edit/
Pin/Delete, so the previous 500 px constraint clipped the modal. 700 px
fits the full list with breathing room.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): fix avatar leading on slidable list header + trim actions modal height

Two cleanups:

- `slidable_channel_list` was stubbing `currentUser` *before* the
  `fakeChannel` calls, so each `setupMockChannel` invocation
  overwrote `client.state` with its own `MockClientState()` (whose
  default `currentUser` is `OwnUser(id: 'user-id')`, the "U"
  placeholder). Move the stub after the channels are created so it
  wins, matching the order `channel_list_view` already uses. The
  header now renders Amelia's avatar properly.
- `message_widget_actions` was at 700 px after adding the full action
  list — visibly too tall. Trim to 620 px so the modal fits with
  comfortable margin and no dead space below.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): drop ci/ goldens from version control, fix gitignore pattern

The previous `.gitignore` pattern `!**/goldens/macos/*` only un-ignored
macos files relative to a (missing) preceding ignore rule, so the `ci/`
subdirectory was being tracked alongside `macos/`. With
`flutter_test_config` already disabling `CiGoldensConfig.enabled`, the
`ci/` files were stale leftovers from before that change — committing
them was pure noise.

Switch the ignore to `**/test/**/goldens/**` (recursively ignore
everything under any goldens dir) with `!**/test/**/goldens/macos/**`
re-allowing the macos subtree. Delete the orphan `ci/` PNGs so the
docs only ship the platform variant.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): stub channel.memberCount so group headers show member counts

`StreamChannelInfo` (the default subtitle for `StreamChannelHeader`)
branches on `channel.memberCount`: > 2 → "N members, M online", else
the DM-style "Last online …". Our mock left `memberCount` un-stubbed,
so it resolved to null and every snapshot fell into the DM branch —
yielding a misleading "Last online a few seconds ago" for channels
that visibly have 3+ avatars stacked.

Stub `memberCount` (and `memberCountStream`) from the configured member
list in `setupMockChannel`. Group-channel snapshots now read "3 Members"
(or whatever the per-channel deterministic count is), matching what
users actually see.

`channel_list_header` snapshots were already correct — they use the
connection-state default title with no subtitle.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(ui): render slidable channel snapshots via real Slidable + drag gesture

The slidable snapshots were hand-rolled — Row+Stack+Transform.translate
faking a swiped state with hardcoded action icons. Replace with the
actual `flutter_slidable` setup the sample app uses
(`sample_app/lib/widgets/channel_list.dart`):
`Slidable` with `endActionPane: ActionPane(extentRatio: 0.4, motion:
BehindMotion(), children: [more, mute])`. For the multi-channel test
the wrap goes through `StreamChannelListView.itemBuilder` so every row
gets the same slidable.

`whilePerforming: (tester) async { await tester.drag(...); await
tester.pumpAndSettle(); }` actually performs the gesture before the
snapshot. The result is a real animated reveal instead of a fake
translation, which catches any drift in Slidable's API or our usage.

Adds `flutter_slidable: ^4.0.0` to docs_screenshots dev_dependencies.
Drops the now-unused mocktail import in this file.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: Update Docs Snapshots

* docs(ui): use checkmark icon for poll creator trailing, matching the SDK

`StreamPollCreatorSheet` (the production widget) wires its trailing
`StreamButton.icon` to `context.streamIcons.checkmark`, not `send`. Our
snapshot was showing a paper-plane icon which doesn't appear anywhere
in the real poll creation flow.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: Update Docs Snapshots

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: xsahil03x <25670178+xsahil03x@users.noreply.github.com>

Author: xsahil03x

.github/workflows/update_goldens.yml

@@ -1,9 +1,20 @@
 name: update_goldens
 
-on: workflow_dispatch
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Which goldens to update"
+        required: true
+        type: choice
+        default: sdk
+        options:
+          - sdk
+          - docs
 
 jobs:
-  update_goldens:
+  update_sdk_goldens:
+    if: inputs.target == 'sdk'
     runs-on: ubuntu-latest
     steps:
       - name: 📚 Checkout branch
@@ -24,14 +35,48 @@ jobs:
       - name: 🔧 Bootstrap Workspace
         run: melos bootstrap --verbose
 
-      - name: 🖼️ Update Goldens
+      - name: 🖼️ Update SDK Goldens
         continue-on-error: true
-        run: melos run update:goldens
+        run: melos run update:goldens:sdk
 
       - name: 📤 Commit Changes
         uses: stefanzweifel/git-auto-commit-action@v7
         with:
-          commit_message: "chore: Update Goldens"
-          file_pattern: "**/test/**/goldens/*.png"
+          commit_message: "chore: Update SDK Goldens"
+          file_pattern: "packages/**/test/**/goldens/**/*.png"
+          commit_user_name: "Stream SDK Bot"
+          commit_user_email: "60655709+Stream-SDK-Bot@users.noreply.github.com"
+
+  update_docs_goldens:
+    if: inputs.target == 'docs'
+    runs-on: macos-latest
+    steps:
+      - name: 📚 Checkout branch
+        uses: actions/checkout@v6
+        with:
+          ssh-key: ${{ secrets.BOT_SSH_PRIVATE_KEY }}
+
+      - name: 🐦 Install Flutter
+        uses: subosito/flutter-action@v2
+        with:
+          flutter-version: "3.x"
+          channel: stable
+          cache-key: flutter-:os:-:channel:-:version:-:arch:-:hash:-${{ hashFiles('**/pubspec.lock') }}
+
+      - name: 📦 Install Tools
+        run: flutter pub global activate melos
+
+      - name: 🔧 Bootstrap Workspace
+        run: melos bootstrap --verbose
+
+      - name: 🖼️ Update Docs Goldens
+        continue-on-error: true
+        run: melos run update:goldens:docs
+
+      - name: 📤 Commit Changes
+        uses: stefanzweifel/git-auto-commit-action@v7
+        with:
+          commit_message: "chore: Update Docs Snapshots"
+          file_pattern: "docs/**/test/**/goldens/macos/*.png"
           commit_user_name: "Stream SDK Bot"
           commit_user_email: "60655709+Stream-SDK-Bot@users.noreply.github.com"

docs/docs_screenshots/.fvmrc

@@ -0,0 +1,3 @@
+{
+  "flutter": "3.44.0"
+}

docs/docs_screenshots/.gitignore

@@ -1,2 +1,5 @@
-# docs_screenshots uses platform (macOS) goldens only
-!**/goldens/macos/*
+# docs_screenshots commits only the platform (macOS) goldens.
+# Ignore everything under `goldens/`, then un-ignore the macos subtree.
+**/test/**/goldens/**
+!**/test/**/goldens/macos/
+!**/test/**/goldens/macos/**

docs/docs_screenshots/pubspec.yaml

@@ -28,6 +28,7 @@ dependencies:
 dev_dependencies:
   alchemist: ^0.14.0
   device_preview: ^1.2.0
+  flutter_slidable: ^4.0.0
   flutter_test:
     sdk: flutter
   mocktail: ^1.0.5

docs/docs_screenshots/test/channel/channel_header_test.dart

@@ -1,4 +1,3 @@
-import 'package:alchemist/alchemist.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:stream_chat_flutter/stream_chat_flutter.dart';
@@ -29,7 +28,7 @@ Widget _buildChannelHeaderScaffold({
 void main() {
   TestWidgetsFlutterBinding.ensureInitialized();
 
-  goldenTest(
+  docsGoldenTest(
     'channel header default',
     fileName: 'channel_header',
     constraints: const BoxConstraints.tightFor(width: 375, height: 72),
@@ -57,7 +56,7 @@ void main() {
     },
   );
 
-  goldenTest(
+  docsGoldenTest(
     'channel header with custom title',
     fileName: 'channel_header_custom_title',
     constraints: const BoxConstraints.tightFor(width: 375, height: 72),

docs/docs_screenshots/test/channel/channel_list_header_test.dart

@@ -1,61 +1,72 @@
-import 'package:alchemist/alchemist.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:mocktail/mocktail.dart';
 import 'package:stream_chat_flutter/stream_chat_flutter.dart';
 
 import '../src/golden_theme.dart';
 import '../src/mocks.dart';
+import '../src/sample_users.dart';
 
 Widget _buildListHeaderScaffold({
   required MockClient client,
-  StreamChannelListHeader? header,
+  required PreferredSizeWidget Function(BuildContext) headerBuilder,
 }) {
   return MaterialApp(
     theme: docsScreenshotsTheme(),
     debugShowCheckedModeBanner: false,
     home: StreamChat(
       client: client,
       connectivityStream: Stream.value([ConnectivityResult.mobile]),
-      child: Scaffold(appBar: header),
+      child: Builder(
+        builder: (context) => Scaffold(appBar: headerBuilder(context)),
+      ),
     ),
   );
 }
 
 void main() {
   TestWidgetsFlutterBinding.ensureInitialized();
 
-  goldenTest(
+  docsGoldenTest(
     'channel list header default',
     fileName: 'channel_list_header',
     constraints: const BoxConstraints.tightFor(width: 375, height: 72),
     builder: () {
       final client = MockClient();
       final clientState = MockClientState();
       when(() => client.state).thenReturn(clientState);
-      when(() => clientState.currentUser).thenReturn(OwnUser(id: 'user-id', name: 'Alice'));
+      when(() => clientState.currentUser).thenReturn(ownUser);
 
       return _buildListHeaderScaffold(
         client: client,
-        header: const StreamChannelListHeader(),
+        headerBuilder: (context) => StreamChannelListHeader(
+          trailing: StreamButton.icon(
+            icon: Icon(context.streamIcons.plus),
+            onPressed: () {},
+          ),
+        ),
       );
     },
   );
 
-  goldenTest(
+  docsGoldenTest(
     'channel list header with custom subtitle',
     fileName: 'channel_list_header_custom_subtitle',
     constraints: const BoxConstraints.tightFor(width: 375, height: 72),
     builder: () {
       final client = MockClient();
       final clientState = MockClientState();
       when(() => client.state).thenReturn(clientState);
-      when(() => clientState.currentUser).thenReturn(OwnUser(id: 'user-id', name: 'Alice'));
+      when(() => clientState.currentUser).thenReturn(ownUser);
 
       return _buildListHeaderScaffold(
         client: client,
-        header: const StreamChannelListHeader(
-          subtitle: Text('12 channels'),
+        headerBuilder: (context) => StreamChannelListHeader(
+          subtitle: const Text('12 channels'),
+          trailing: StreamButton.icon(
+            icon: Icon(context.streamIcons.plus),
+            onPressed: () {},
+          ),
         ),
       );
     },