fix(surveys): show a survey once PosthogObserver has a context

[turnipdabeets]

💡 Motivation and Context

Surveys are rendered in Dart and need the BuildContext that PosthogObserver picks up on navigation. If a survey arrived while there was no context (before the first route, or after Posthog().close() cleared it), we logged and dropped it. The native SDK still held it as its active survey, so no other survey could show until the app restarted.

Telling native the survey was closed is not an option: it marks the survey seen and sends survey dismissed for a survey nobody saw.

Now SurveyService.showSurvey waits for the observer's next context and shows the survey then. hideSurvey() cancels the wait, and a newer survey replaces the waiting one. Nothing is sent to native while waiting. posthog-android's own survey UI does the same when it has no activity to present on.

If PosthogObserver is never installed the survey still never shows, as before; the debug log now says so.

Note for #627 (popup delay): it touches the same lines of showSurvey, so whichever lands second needs a small rebase.

💚 How did you test it?

• New widget tests in survey_wait_for_context_test.dart: survey arrives before the app has a context, context cleared then next navigation, hidden while waiting, replaced while waiting. Full suite passes (735 tests); analyze and format are clean.
• On an iOS 27.2 simulator and an Android emulator, against the real native SDKs with a local capture proxy: with the context cleared, a triggered survey did not show and sent no events; after pushing a route it showed within about 0.5s and sent survey shown; after closing it, a second survey showed normally.
• Not tested: a web build, go_router / didReplace, and a real close() then setup() (the context was cleared directly).

📝 Checklist

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

If releasing new changes

• Ran pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

• Written with Claude Code while reviewing feat(surveys): honor surveyPopupDelaySeconds before showing #627, where an on-device run showed the dropped survey leaves the native SDK blocked.
• Considered adding a native "could not render" signal that releases the survey without marking it seen. Rejected: it needs new public API in posthog-ios and posthog-android for a case Dart can handle alone.
• The sdk-specs surveys spec says missing render targets "log and return without emitting interaction events". This still logs and emits nothing, but waits for a target instead of returning.
• An independent review pass found nothing blocking; it led to the extra context-cleared test.

🤖 Generated with Claude Code

[github-actions]

posthog-flutter Compliance Report

Date: 2026-10-01 14:33:49 UTC
Duration: 96336ms

✅ All Tests Passed!

45/45 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	122ms
Format Validation.Event Has Uuid	✅	110ms
Format Validation.Event Has Lib Properties	✅	109ms
Format Validation.Distinct Id Is String	✅	107ms
Format Validation.Token Is Present	✅	108ms
Format Validation.Custom Properties Preserved	✅	109ms
Format Validation.Event Has Timestamp	✅	109ms
Retry Behavior.Retries On 503	✅	5317ms
Retry Behavior.Does Not Retry On 400	✅	2112ms
Retry Behavior.Does Not Retry On 401	✅	2111ms
Retry Behavior.Respects Retry After Header	✅	8114ms
Retry Behavior.Implements Backoff	✅	15432ms
Retry Behavior.Retries On 500	✅	5218ms
Retry Behavior.Retries On 502	✅	5217ms
Retry Behavior.Retries On 504	✅	5217ms
Retry Behavior.Max Retries Respected	✅	15430ms
Deduplication.Generates Unique Uuids	✅	115ms
Deduplication.Preserves Uuid On Retry	✅	5214ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10313ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5220ms
Deduplication.No Duplicate Events In Batch	✅	115ms
Deduplication.Different Events Have Different Uuids	✅	110ms
Compression.Sends Gzip When Enabled	✅	110ms
Batch Format.Uses Proper Batch Structure	✅	107ms
Batch Format.Flush With No Events Sends Nothing	✅	105ms
Batch Format.Multiple Events Batched Together	✅	113ms
Error Handling.Does Not Retry On 403	✅	2109ms
Error Handling.Does Not Retry On 413	✅	2112ms
Error Handling.Retries On 408	✅	5219ms

Feature_Flags Tests

✅ 16/16 tests passed

View Details

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

[lucasheriques]

LGTM. I traced both native bridges: hideSurveys cancels the wait, and a new renderSurvey replaces it. One optional simplification inline.