import 'dart:async'; import 'package:flutter/widgets.dart'; import '../../core/api_gateway.dart'; import 'first_run_walkthrough.dart'; import 'walkthrough_store.dart'; /// Reports whether the server has no pipelines, runs or chats yet. Returns null /// when any of the three lists cannot be read, so an unreadable server never /// triggers the walkthrough. Future serverHasNoWorkYet(ApiGateway? gateway) async { if (gateway == null) return null; try { final replies = await Future.wait(>[ gateway.call('list_pipelines', {'include_archived': true}), gateway.call('list_runs'), gateway.call('chat_sessions'), ]); final lists = [ replies[0]['pipelines'], replies[1]['runs'], replies[2]['chat_sessions'], ]; if (lists.any((list) => list is! List)) return null; return lists.every((list) => (list as List).isEmpty); } catch (_) { return null; } } /// Offers the walkthrough from the Pipelines page, which is the first screen a /// new user sees. It is offered when: /// /// * the device has not finished or skipped it yet (first launch, once); or /// * the device already has, and the connected server has no pipelines, runs /// or chats, and that server has not been offered it before. /// /// The server check needs a connected session. While disconnected it waits, and /// it runs again on each new connection until the server answers. A check that /// cannot read the server leaves the gate open to retry; a decided check (the /// walkthrough shown, or the server has work) ends it for this mount. /// /// Nothing is shown while the store cannot be read, because an unavailable /// store reports "seen". The check runs only while [enabled] (the Pipelines tab /// is the one showing). class FirstRunWalkthroughGate extends StatefulWidget { const FirstRunWalkthroughGate({ super.key, required this.child, required this.store, required this.enabled, required this.serverScope, required this.connection, required this.connected, this.gateway, }); final Widget child; final WalkthroughStore store; /// Whether the Pipelines page is the one showing. final bool enabled; /// The connected server's scope, recorded when the walkthrough is offered. final String serverScope; /// Notifies when the connection may have changed; the gate re-reads /// [connected] on each notification. final Listenable connection; /// Whether the server session is connected right now. final bool Function() connected; /// The connected server's gateway, used for the empty-server check. final ApiGateway? gateway; @override State createState() => _FirstRunWalkthroughGateState(); } class _FirstRunWalkthroughGateState extends State { /// The offer is decided for this mount: shown, or nothing left to offer. bool _decided = false; /// An offer is in flight. bool _running = false; /// A new connection arrived while an offer was in flight. bool _connectedAgain = false; late bool _wasConnected; @override void initState() { super.initState(); _wasConnected = widget.connected(); widget.connection.addListener(_onConnectionChanged); _scheduleIfEnabled(); } @override void didUpdateWidget(FirstRunWalkthroughGate oldWidget) { super.didUpdateWidget(oldWidget); if (oldWidget.connection != widget.connection) { oldWidget.connection.removeListener(_onConnectionChanged); widget.connection.addListener(_onConnectionChanged); } _scheduleIfEnabled(); } @override void dispose() { widget.connection.removeListener(_onConnectionChanged); super.dispose(); } /// Acts only on a disconnected-to-connected transition, so frequent session /// notifications while connected never repeat the server check. void _onConnectionChanged() { final connected = widget.connected(); final became = connected && !_wasConnected; _wasConnected = connected; if (!became || _decided) return; if (_running) { _connectedAgain = true; return; } _scheduleIfEnabled(); } void _scheduleIfEnabled() { if (_decided || _running || !widget.enabled) return; _running = true; // A connection can arrive between frames; the post-frame callback needs a // frame, so request one explicitly. WidgetsBinding.instance.addPostFrameCallback((_) { if (!_active) { // Pipelines is hidden (or the gate is gone): release the flag so a // later enable reschedules the offer through didUpdateWidget. _running = false; return; } unawaited(_runOffer()); }); WidgetsBinding.instance.ensureVisualUpdate(); } /// The gate may offer only while mounted and while the Pipelines page is the /// one showing. Checked after every await and before every show. bool get _active => mounted && widget.enabled; Future _runOffer() async { try { await _offer(); } finally { _running = false; final again = _connectedAgain; _connectedAgain = false; if (again && !_decided) _scheduleIfEnabled(); } } Future _offer() async { final seen = await widget.store.isSeen(); if (!_active) return; if (!seen) { _decided = true; await _showIfActive(); return; } if (await widget.store.wasOffered(widget.serverScope)) { if (!_active) return; _decided = true; return; } // Wait for a connection; the connection listener runs the check again. if (!widget.connected()) return; final empty = await serverHasNoWorkYet(widget.gateway); if (!_active) return; // Unreadable: stay open so the next connection retries the check. if (empty == null) return; _decided = true; if (!empty) return; await widget.store.markOffered(widget.serverScope); await _showIfActive(); } Future _showIfActive() async { if (!_active) return; await _show(); } Future _show() async { await showFirstRunWalkthrough(context, onClosed: widget.store.markSeen); } @override Widget build(BuildContext context) => widget.child; }