fix(replay): warn when PostHogWidget mounts before setup

[marandaneto]

💡 Motivation and Context

Fixes #571.

When PostHogWidget mounts before Posthog().setup(), it silently skips replay initialization and listener registration. Later setup or recording commands cannot start capture for that widget instance.

This adds a warning that explains the required setup order and the option to remount the widget after setup. Because replay intent is unknown before setup, the message makes this advice conditional and says it can be ignored when replay is not intended. The warning is not emitted on web, where replay uses posthog-js. Replay initialization behavior is unchanged.

💚 How did you test it?

• The new regression test failed before the fix because no warning was emitted, then passed after the fix. It also verifies that rebuilding does not repeat the warning.
• All 343 VM tests passed with flutter test --no-pub --reporter expanded.
• All 6 Chrome tests passed for posthog_widget_test.dart and posthog_widget_web_test.dart. These cover warning suppression on web and after setup with replay enabled or disabled.
• dart analyze ., formatting checks, and git diff --check passed.
• The updated message assertion failed against the original unconditional wording and passed after the review feedback change.
• Autoreview of commit 9301682 against origin/main reported no actionable findings.

No emulator run was needed for this Dart-only logging change. Widget tests exercise the affected mount path with a mocked native channel.

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed. No documentation changes were needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Added a patch changeset file manually, equivalent to pnpm changeset.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Pi investigated the issue and implemented the change in a dedicated worktree using Git, GitHub CLI, Flutter tests, Dart analysis, and the isolated autoreview helper. The session transcript is not published.

The change follows the issue's request for a diagnostic rather than adding support for late setup. Remounting after setup restores capture within the same app launch. Review feedback prompted conditional wording because mounting the widget does not prove that replay is intended. Human review is required.

[greptile-apps]

_{Reviews (1): Last reviewed commit: "fix(replay): warn when PostHogWidget mou..." | Re-trigger Greptile}

[github-actions]

posthog-flutter Compliance Report

Date: 2026-09-11 10:29:51 UTC
Duration: 96856ms

✅ All Tests Passed!

45/45 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	146ms
Format Validation.Event Has Uuid	✅	120ms
Format Validation.Event Has Lib Properties	✅	117ms
Format Validation.Distinct Id Is String	✅	116ms
Format Validation.Token Is Present	✅	116ms
Format Validation.Custom Properties Preserved	✅	117ms
Format Validation.Event Has Timestamp	✅	117ms
Retry Behavior.Retries On 503	✅	5333ms
Retry Behavior.Does Not Retry On 400	✅	2119ms
Retry Behavior.Does Not Retry On 401	✅	2118ms
Retry Behavior.Respects Retry After Header	✅	8126ms
Retry Behavior.Implements Backoff	✅	15446ms
Retry Behavior.Retries On 500	✅	5226ms
Retry Behavior.Retries On 502	✅	5227ms
Retry Behavior.Retries On 504	✅	5226ms
Retry Behavior.Max Retries Respected	✅	15437ms
Deduplication.Generates Unique Uuids	✅	124ms
Deduplication.Preserves Uuid On Retry	✅	5224ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10335ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5230ms
Deduplication.No Duplicate Events In Batch	✅	124ms
Deduplication.Different Events Have Different Uuids	✅	117ms
Compression.Sends Gzip When Enabled	✅	115ms
Batch Format.Uses Proper Batch Structure	✅	113ms
Batch Format.Flush With No Events Sends Nothing	✅	108ms
Batch Format.Multiple Events Batched Together	✅	124ms
Error Handling.Does Not Retry On 403	✅	2117ms
Error Handling.Does Not Retry On 413	✅	2117ms
Error Handling.Retries On 408	✅	5224ms

Feature_Flags Tests

✅ 16/16 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	13ms
Request Payload.Flags Request Uses V2 Query Param	✅	10ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	10ms
Request Payload.Flags Request Omits Authorization Header	✅	9ms
Request Payload.Token In Flags Body Matches Init	✅	10ms
Request Payload.Groups Round Trip	✅	9ms
Request Payload.Groups Default To Empty Object	✅	10ms
Request Payload.Person Properties Distinct Id Auto Populated When Caller Omits It	✅	9ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	10ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	9ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	10ms
Request Lifecycle.No Flags Request On Init Alone	✅	4ms
Request Lifecycle.No Flags Request On Normal Capture	✅	113ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	16ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	10ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	115ms