Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

31.2 KB
Raw Blame
import 'dart:async';
import 'dart:io';

import 'package:harness/shared/theme/app_icons.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

import '../bootstrap/environment_provisioner.dart';
import '../shared/theme/app_theme.dart' as grid;
import '../shared/widgets/command_row.dart';
import '../state/app_state.dart';
import '../theme/app_theme.dart';

/// First-run setup. Launch probes stay read-only; a plan that installs
/// entirely in-app then runs unasked and this screen shows its progress. Only a
/// plan that needs a password in Terminal (Linux apt) waits on the review's
/// install action.
class EnvironmentSetupScreen extends StatefulWidget {
  final AppNotifier notifier;

  const EnvironmentSetupScreen({super.key, required this.notifier});

  @override
  State<EnvironmentSetupScreen> createState() => _EnvironmentSetupScreenState();
}

class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
  String? _copied;
  String? _copyError;
  var _copyRevision = 0;
  Timer? _copyTimer;
  final _scroll = ScrollController();
  final _primaryFocus = FocusNode(debugLabel: 'Setup action');
  final _bodyFocus = FocusNode(
    debugLabel: 'Setup details',
    skipTraversal: true,
  );
  final _manualFocus = FocusNode(debugLabel: 'Switch setup method');
  EnvironmentSetupPhase? _lastPhase;
  bool _actionWasAvailable = false;
  bool _detailsOpen = false;

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addPostFrameCallback((_) {
      if (mounted) widget.notifier.productMeasurement.setupShown();
    });
  }

  @override
  void dispose() {
    widget.notifier.productMeasurement.setupHidden();
    _copyTimer?.cancel();
    _scroll.dispose();
    _primaryFocus.dispose();
    _bodyFocus.dispose();
    _manualFocus.dispose();
    super.dispose();
  }

  Future<void> _copy(String value) async {
    final revision = ++_copyRevision;
    _copyTimer?.cancel();
    try {
      await Clipboard.setData(ClipboardData(text: value));
      if (!mounted || revision != _copyRevision) return;
      setState(() {
        _copied = value;
        _copyError = null;
      });
      _copyTimer = Timer(const Duration(milliseconds: 1400), () {
        if (mounted && revision == _copyRevision) {
          setState(() => _copied = null);
        }
      });
    } catch (_) {
      if (!mounted || revision != _copyRevision) return;
      setState(() {
        _copied = null;
        _copyError =
            'Could not copy. Select the text to copy it, or try again.';
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    grid.AppTheme.watch(context);
    final state = widget.notifier.environmentReadiness;
    final phaseChanged = _lastPhase != state.phase;
    final actionAvailable =
        !widget.notifier.environmentSetupInFlight &&
        const {
          EnvironmentSetupPhase.review,
          EnvironmentSetupPhase.chooseMethod,
          EnvironmentSetupPhase.failed,
          EnvironmentSetupPhase.waitingForTerminal,
          EnvironmentSetupPhase.ready,
        }.contains(state.phase);
    if (phaseChanged || (actionAvailable && !_actionWasAvailable)) {
      WidgetsBinding.instance.addPostFrameCallback((_) {
        if (!mounted || ModalRoute.of(context)?.isCurrent == false) return;
        if (widget.notifier.environmentReadiness.phase != state.phase) return;
        if (phaseChanged && _scroll.hasClients) _scroll.jumpTo(0);
        // A new next step should be usable with Enter. Keep an explicit choice
        // to read/copy details or change methods when asynchronous updates land.
        if (actionAvailable &&
            !widget.notifier.environmentSetupInFlight &&
            !_bodyFocus.hasFocus &&
            !_manualFocus.hasFocus) {
          _primaryFocus.requestFocus();
        }
      });
    }
    _lastPhase = state.phase;
    _actionWasAvailable = actionAvailable;
    final compact = MediaQuery.sizeOf(context).height < 640;
    return Scaffold(
      backgroundColor: AppColors.background,
      body: SafeArea(
        child: Padding(
          padding: EdgeInsets.all(compact ? 16 : 24),
          child: Center(
            child: ConstrainedBox(
              constraints: const BoxConstraints(maxWidth: 640),
              child: Material(
                color: AppColors.sidebar,
                clipBehavior: Clip.antiAlias,
                shape: RoundedRectangleBorder(
                  borderRadius: BorderRadius.circular(14),
                  side: BorderSide(color: AppColors.border),
                ),
                child: Column(
                  mainAxisSize: MainAxisSize.min,
                  children: [
                    Flexible(
                      child: SingleChildScrollView(
                        controller: _scroll,
                        padding: EdgeInsets.all(compact ? 20 : 28),
                        child: Focus(
                          focusNode: _bodyFocus,
                          child: _body(state),
                        ),
                      ),
                    ),
                    _footer(state),
                  ],
                ),
              ),
            ),
          ),
        ),
      ),
    );
  }

  Widget _body(EnvironmentReadiness state) => switch (state.phase) {
    EnvironmentSetupPhase.preflight => _preflight(state),
    EnvironmentSetupPhase.review ||
    EnvironmentSetupPhase.chooseMethod => _choose(state),
    EnvironmentSetupPhase.installing ||
    EnvironmentSetupPhase.waitingForTerminal ||
    EnvironmentSetupPhase.verifying => _installing(state),
    EnvironmentSetupPhase.failed => _failure(state),
    EnvironmentSetupPhase.ready => _ready(state),
  };

  Widget _heading(String eyebrow, String title, String lead) => Column(
    crossAxisAlignment: CrossAxisAlignment.start,
    children: [
      Text(
        eyebrow,
        style: grid.AppType.caption(
          color: AppColors.accent,
          fontWeight: FontWeight.w600,
        ),
      ),
      const SizedBox(height: 6),
      Text(
        title,
        style: grid.AppType.title(
          fontWeight: FontWeight.w600,
          color: AppColors.text,
        ),
      ),
      const SizedBox(height: 6),
      Text(
        lead,
        style: grid.AppType.body(color: AppColors.textSoft, height: 1.55),
      ),
      const SizedBox(height: 16),
    ],
  );
  Widget _preflight(EnvironmentReadiness state) => Column(
    crossAxisAlignment: CrossAxisAlignment.start,
    children: [
      _heading(
        'Getting started',
        'Checking this computer',
        'Checking the tools Harness needs to run your agents.',
      ),
      _checkList(state, checking: true),
    ],
  );

  Widget _choose(EnvironmentReadiness state) {
    final mode = state.mode ?? EnvironmentSetupMode.automatic;
    final items = state.plan;
    final count = items.length;
    final countLabel = '$count ${count == 1 ? 'tool' : 'tools'}';
    final needsTerminal = items.any((item) => item.requiresTerminal);
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        _heading(
          'Getting started',
          'Get this computer ready',
          count == 0
              ? 'Your tools are ready. Verify them to continue.'
              : count == 1
              ? 'Install this tool, then start your first harness.'
              : 'Install these $countLabel, then start your first harness.',
        ),
        Row(
          children: [
            const Expanded(
              child: Text(
                'Required tools',
                style: TextStyle(fontWeight: FontWeight.w500),
              ),
            ),
            TextButton(
              style: TextButton.styleFrom(foregroundColor: AppColors.textSoft),
              onPressed: () => widget.notifier.selectEnvironmentSetupMode(
                mode == EnvironmentSetupMode.automatic
                    ? EnvironmentSetupMode.manual
                    : EnvironmentSetupMode.automatic,
              ),
              child: Text(
                mode == EnvironmentSetupMode.automatic
                    ? 'Manual setup'
                    : 'Use automatic setup',
              ),
            ),
          ],
        ),
        const SizedBox(height: 8),
        if (mode == EnvironmentSetupMode.automatic) ...[
          if (needsTerminal) ...[
            _notice(
              AppIcons.terminal,
              'Admin prompts stay in Terminal',
              'Complete any installation prompts there, then return to Harness.',
            ),
            const SizedBox(height: 16),
          ],
          _planList(items),
        ] else
          _manualList(items),
      ],
    );
  }

  Widget _installing(EnvironmentReadiness state) => Column(
    crossAxisAlignment: CrossAxisAlignment.start,
    children: [
      _heading(
        'Getting started',
        state.phase == EnvironmentSetupPhase.waitingForTerminal
            ? 'Finish setup in Terminal'
            : state.phase == EnvironmentSetupPhase.verifying
            ? 'Running final verification'
            : 'Preparing this computer',
        state.message ?? 'Installing only the missing required tools.',
      ),
      if (state.phase == EnvironmentSetupPhase.waitingForTerminal)
        _notice(
          AppIcons.lock,
          'Harness cannot see your password',
          'Finish the prompts in Terminal, then return here. Harness checks progress automatically.',
        ),
      const SizedBox(height: 18),
      _checkList(state, checking: true),
      _logs(state),
    ],
  );

  Widget _failure(EnvironmentReadiness state) {
    final failure = state.failure;
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        _heading(
          'Setup needs attention',
          failure?.title ?? 'Environment setup failed',
          failure?.detail ?? state.message ?? 'Review the full error below.',
        ),
        _checkList(state),
        if (failure?.command != null) ...[
          const SizedBox(height: 16),
          CommandRow(
            command: failure!.command!,
            copied: _copied == failure.command,
            onCopy: () => _copy(failure.command!),
          ),
        ],
        _logs(state),
      ],
    );
  }

  Widget _ready(EnvironmentReadiness state) => Column(
    crossAxisAlignment: CrossAxisAlignment.start,
    children: [
      _heading(
        'Setup complete',
        'This computer is ready',
        'Every required command passed. Continue to your workspace.',
      ),
      _checkList(state),
    ],
  );

  Widget _checkList(
    EnvironmentReadiness state, {
    bool checking = false,
  }) => EnvironmentCheckList(readiness: state, checking: checking);

  Widget _planList(List<EnvironmentPlanItem> items) {
    if (items.isEmpty) {
      return _notice(
        AppIcons.circleCheck,
        'Nothing left to install',
        'Every dependency is ready. Continue to final verification.',
      );
    }
    final stacked = grid.appTextScaleOf(context) > 1.25;
    return _Panel(
      child: Column(
        children: [
          for (var index = 0; index < items.length; index++)
            ListTile(
              dense: true,
              leading: CircleAvatar(
                radius: 14,
                backgroundColor: AppColors.hover,
                foregroundColor: AppColors.text,
                child: Text('${index + 1}', style: grid.AppType.monoLabel()),
              ),
              title: Text(items[index].title, style: grid.AppType.label()),
              subtitle: stacked
                  ? Text(
                      items[index].detail,
                      style: grid.AppType.body(color: AppColors.textSoft),
                    )
                  : null,
              trailing: stacked
                  ? null
                  : ConstrainedBox(
                      constraints: const BoxConstraints(maxWidth: 280),
                      child: Text(
                        items[index].detail,
                        maxLines: 2,
                        overflow: TextOverflow.ellipsis,
                        textAlign: TextAlign.end,
                        style: grid.AppType.body(color: AppColors.textSoft),
                      ),
                    ),
            ),
        ],
      ),
    );
  }

  Widget _manualList(List<EnvironmentPlanItem> items) => Column(
    children: [
      if (items.isEmpty)
        _notice(
          AppIcons.circleCheck,
          'Nothing left to install',
          'Every dependency is ready. Continue to final verification.',
        ),
      for (var index = 0; index < items.length; index++)
        Padding(
          padding: const EdgeInsets.only(bottom: 10),
          child: _Panel(
            padding: const EdgeInsets.all(14),
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text(
                  '${index + 1} · ${items[index].title}',
                  style: grid.AppType.heading(
                    fontWeight: FontWeight.w600,
                    color: AppColors.text,
                  ),
                ),
                const SizedBox(height: 9),
                CommandRow(
                  command: items[index].command,
                  copied: _copied == items[index].command,
                  onCopy: () => _copy(items[index].command),
                ),
              ],
            ),
          ),
        ),
    ],
  );

  Widget _logs(EnvironmentReadiness state) {
    if (state.output.isEmpty) return const SizedBox.shrink();
    final diagnostics = state.output.join('\n');
    return Container(
      width: double.infinity,
      margin: const EdgeInsets.only(top: 18),
      decoration: BoxDecoration(
        color: AppColors.background,
        border: Border.all(color: AppColors.border),
        borderRadius: BorderRadius.circular(10),
      ),
      child: ExpansionTile(
        initiallyExpanded: _detailsOpen,
        maintainState: true,
        expandedCrossAxisAlignment: CrossAxisAlignment.stretch,
        expansionAnimationStyle: AnimationStyle.noAnimation,
        onExpansionChanged: (open) => setState(() => _detailsOpen = open),
        title: Row(
          children: [
            Expanded(
              child: Text(
                'Setup details',
                style: grid.AppType.label(
                  fontWeight: FontWeight.w600,
                  color: AppColors.text,
                ),
              ),
            ),
            TextButton.icon(
              onPressed: () => _copy(diagnostics),
              icon: const Icon(AppIcons.copy, size: 14),
              label: Text(
                _copied == diagnostics ? 'Copied' : 'Copy diagnostics',
              ),
            ),
          ],
        ),
        children: [
          Divider(height: 1, color: AppColors.border),
          ConstrainedBox(
            constraints: const BoxConstraints(maxHeight: 210),
            child: SingleChildScrollView(
              reverse: true,
              padding: const EdgeInsets.all(14),
              child: SelectableText(
                diagnostics,
                style: grid.AppType.monoLabel(
                  fontWeight: FontWeight.w400,
                  height: 1.55,
                  color: AppColors.textSoft,
                ),
              ),
            ),
          ),
        ],
      ),
    );
  }

  Widget _notice(IconData icon, String title, String detail) {
    final tone = AppColors.accent;
    return Container(
      padding: const EdgeInsets.all(14),
      decoration: BoxDecoration(
        color: tone.withValues(alpha: 0.07),
        border: Border.all(color: tone.withValues(alpha: 0.35)),
        borderRadius: BorderRadius.circular(10),
      ),
      child: Row(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Icon(icon, size: 18, color: tone),
          const SizedBox(width: 11),
          Expanded(
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text(
                  title,
                  style: grid.AppType.label(fontWeight: FontWeight.w600),
                ),
                const SizedBox(height: 4),
                Text(
                  detail,
                  style: grid.AppType.body(
                    color: AppColors.textSoft,
                    height: 1.45,
                  ),
                ),
              ],
            ),
          ),
        ],
      ),
    );
  }

  Widget _footer(EnvironmentReadiness state) {
    final busy = widget.notifier.environmentSetupInFlight;
    final mode = state.mode ?? EnvironmentSetupMode.automatic;
    final missingCount = state.plan.length;
    final manual = mode == EnvironmentSetupMode.manual;
    String? label;
    VoidCallback? action;
    IconData? icon;
    switch (state.phase) {
      case EnvironmentSetupPhase.review || EnvironmentSetupPhase.chooseMethod:
        label = manual
            ? 'Check again'
            : missingCount == 0
            ? 'Verify and continue'
            : 'Install $missingCount ${missingCount == 1 ? 'tool' : 'tools'}';
        icon = manual ? AppIcons.refreshCw : AppIcons.download;
        action = manual
            ? widget.notifier.retryEnvironmentSetup
            : widget.notifier.startEnvironmentSetup;
      case EnvironmentSetupPhase.failed:
        label = 'Retry';
        action = manual || !widget.notifier.environmentInstallRequested
            ? widget.notifier.retryEnvironmentSetup
            : widget.notifier.startEnvironmentSetup;
      case EnvironmentSetupPhase.ready:
        label = 'Continue';
        action = widget.notifier.continueAfterEnvironmentSetup;
      case EnvironmentSetupPhase.waitingForTerminal:
        label = 'Recheck now';
        icon = AppIcons.refreshCw;
        action = () => widget.notifier.recheckEnvironmentStep(
          state.steps[EnvironmentStep.clipboard] ==
                  EnvironmentStepStatus.needsTerminal
              ? EnvironmentStep.clipboard
              : EnvironmentStep.tmux,
        );
      default:
        break;
    }
    final actions = Wrap(
      alignment: WrapAlignment.end,
      crossAxisAlignment: WrapCrossAlignment.center,
      spacing: 8,
      runSpacing: 8,
      children: [
        if (state.phase == EnvironmentSetupPhase.failed && !manual)
          TextButton(
            focusNode: _manualFocus,
            onPressed: busy
                ? null
                : () {
                    widget.notifier.selectEnvironmentSetupMode(
                      EnvironmentSetupMode.manual,
                    );
                    widget.notifier.showEnvironmentMethodChoice();
                  },
            child: const Text('Switch to Manual'),
          ),
        if (label != null)
          FilledButton.icon(
            focusNode: _primaryFocus,
            autofocus: true,
            onPressed: busy ? null : action,
            icon: icon == null ? null : Icon(icon, size: 16),
            label: Text(label),
          )
        else if (busy)
          const SizedBox(
            width: 18,
            height: 18,
            child: CircularProgressIndicator(strokeWidth: 2),
          ),
      ],
    );
    final next = Semantics(
      liveRegion: _copyError != null,
      child: Text(
        _copyError ?? 'Next: start your first harness.',
        style: grid.AppType.body(
          color: _copyError == null
              ? AppColors.textSoft
              : Theme.of(context).colorScheme.error,
        ),
      ),
    );
    return Container(
      padding: const EdgeInsets.symmetric(horizontal: 24, vertical: 16),
      decoration: BoxDecoration(
        color: AppColors.sidebar,
        border: Border(top: BorderSide(color: AppColors.border)),
      ),
      child: LayoutBuilder(
        builder: (context, constraints) {
          if (constraints.maxWidth < 600 ||
              grid.appTextScaleOf(context) > 1.25) {
            return Column(
              mainAxisSize: MainAxisSize.min,
              crossAxisAlignment: CrossAxisAlignment.stretch,
              children: [next, const SizedBox(height: 12), actions],
            );
          }
          return Row(
            children: [
              Expanded(child: next),
              const SizedBox(width: 12),
              actions,
            ],
          );
        },
      ),
    );
  }
}

class _Panel extends StatelessWidget {
  final Widget child;
  final EdgeInsetsGeometry padding;
  const _Panel({required this.child, this.padding = EdgeInsets.zero});

  @override
  Widget build(BuildContext context) {
    return Container(
      width: double.infinity,
      padding: padding,
      clipBehavior: Clip.antiAlias,
      decoration: BoxDecoration(
        color: AppColors.surface,
        border: Border.all(color: AppColors.border),
        borderRadius: BorderRadius.circular(11),
      ),
      child: child,
    );
  }
}

class _CheckSectionLabel extends StatelessWidget {
  final String label;
  const _CheckSectionLabel(this.label);

  @override
  Widget build(BuildContext context) {
    grid.AppTheme.watch(context);
    return Container(
      width: double.infinity,
      padding: const EdgeInsets.fromLTRB(16, 11, 16, 8),
      decoration: BoxDecoration(
        color: AppColors.background.withValues(alpha: 0.28),
        border: Border(bottom: BorderSide(color: AppColors.border)),
      ),
      child: Text(
        label,
        style: grid.AppType.label(
          color: AppColors.textSoft,
          fontWeight: FontWeight.w600,
        ),
      ),
    );
  }
}

class _CheckRow extends StatelessWidget {
  final String label;
  final String detail;
  final EnvironmentStepStatus? status;
  final bool checking;
  const _CheckRow({
    required this.label,
    required this.detail,
    required this.status,
    this.checking = false,
  });

  @override
  Widget build(BuildContext context) {
    grid.AppTheme.watch(context);
    final color = switch (status) {
      EnvironmentStepStatus.ready => AppColors.success,
      EnvironmentStepStatus.failed => Theme.of(context).colorScheme.error,
      EnvironmentStepStatus.needsTerminal => AppColors.warning,
      EnvironmentStepStatus.running => AppColors.accent,
      EnvironmentStepStatus.notApplicable => AppColors.textSoft,
      _ => AppColors.textSoft,
    };
    return Container(
      padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 14),
      decoration: BoxDecoration(
        border: Border(bottom: BorderSide(color: AppColors.border)),
      ),
      child: Row(
        children: [
          if (checking || status == EnvironmentStepStatus.running)
            SizedBox(
              width: 16,
              height: 16,
              child: CircularProgressIndicator(strokeWidth: 2, color: color),
            )
          else
            Icon(
              status == EnvironmentStepStatus.ready
                  ? AppIcons.circleCheck
                  : status == EnvironmentStepStatus.failed
                  ? AppIcons.circleX
                  : status == EnvironmentStepStatus.notApplicable
                  ? AppIcons.circleMinus
                  : AppIcons.circle,
              size: 17,
              color: color,
            ),
          const SizedBox(width: 12),
          Expanded(
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text(label, style: grid.AppType.label()),
                const SizedBox(height: 3),
                Text(
                  detail,
                  style: grid.AppType.body(color: AppColors.textSoft),
                ),
              ],
            ),
          ),
          Text(switch (status) {
            EnvironmentStepStatus.ready => 'Ready',
            EnvironmentStepStatus.failed => 'Missing',
            EnvironmentStepStatus.needsTerminal => 'Terminal',
            EnvironmentStepStatus.running => 'Working',
            EnvironmentStepStatus.notApplicable => 'Not applicable',
            _ => checking ? 'Checking' : 'Required',
          }, style: grid.AppType.label(color: color)),
        ],
      ),
    );
  }
}

/// One row per command Harness runs — never one per way of obtaining it.
/// What obtaining a missing one takes is the row's detail, read off the
/// plan the provisioner computed.
///
/// Shared by [EnvironmentSetupScreen] and the setup tour's Details
/// ([EnvironmentSetupDetails]), so both list the same steps the same way.
class EnvironmentCheckList extends StatelessWidget {
  const EnvironmentCheckList({
    super.key,
    required this.readiness,
    this.checking = false,
    this.isWindows,
  });

  final EnvironmentReadiness readiness;

  /// The terminal step is B's terminal host on Windows. Null means this host.
  final bool? isWindows;

  /// Pre-flight rows show a spinner instead of a status.
  final bool checking;

  @override
  Widget build(BuildContext context) {
    grid.AppTheme.watch(context);
    final windows = isWindows ?? Platform.isWindows;
    final state = readiness;
    final probing = checking && state.phase == EnvironmentSetupPhase.preflight;
    return _Panel(
      child: Column(
        children: [
          const _CheckSectionLabel('Host dependencies'),
          _CheckRow(
            label: windows ? 'Terminal host' : 'tmux terminal backend',
            detail: windows ? _terminalHostDetail(state) : _tmuxDetail(state),
            status: state.steps[EnvironmentStep.tmux],
            checking: probing,
          ),
          if (Platform.isLinux)
            _CheckRow(
              label: 'Native image clipboard',
              detail: _linuxClipboardDetail,
              status: state.steps[EnvironmentStep.clipboard],
              checking: probing,
            ),
          const _CheckSectionLabel('Harness components'),
          _CheckRow(
            label: 'Managed Node 20+ & Harness CLI',
            detail: windows
                ? r'%USERPROFILE%\.harness · harness version'
                : '~/.harness/runtime · harness version',
            status: state.steps[EnvironmentStep.harness],
            checking: probing,
          ),
        ],
      ),
    );
  }

  static String _terminalHostDetail(EnvironmentReadiness state) =>
      state.planFor(EnvironmentStep.tmux).isEmpty
      ? 'Required for every harness · harness-pty.exe'
      : 'Required for every harness · installs with the Harness CLI';

  static String _tmuxDetail(EnvironmentReadiness state) {
    const base = 'Required for every harness';
    final steps = state.planFor(EnvironmentStep.tmux);
    if (steps.isEmpty) {
      return Platform.isLinux ? '$base · tmux, ps' : base;
    }
    if (Platform.isLinux) return '$base · installs with apt';
    // macOS: one in-app step; the item's detail says whether Homebrew or the
    // managed download does it.
    return '$base · ${steps.first.detail.toLowerCase()}';
  }

  static String? get _linuxClipboardPackage {
    if ((Platform.environment['WAYLAND_DISPLAY'] ?? '').isNotEmpty) {
      return 'wl-clipboard';
    }
    if ((Platform.environment['DISPLAY'] ?? '').isNotEmpty) return 'xclip';
    return null;
  }

  static String get _linuxClipboardDetail => switch (_linuxClipboardPackage) {
    'wl-clipboard' => 'wl-copy · provided by wl-clipboard',
    'xclip' => 'xclip · required for native image paste',
    _ => 'Not applicable · image paste uses file-path fallback',
  };
}

/// What [EnvironmentSetupScreen] shows of an install, folded into the setup
/// tour's Details: the step list, a failure's command, the downloads beside
/// setup, and the log with Copy diagnostics (which lives here now, since the
/// tour has no footer for it).
class EnvironmentSetupDetails extends StatefulWidget {
  const EnvironmentSetupDetails({
    super.key,
    required this.readiness,
    this.downloadLines = const [],
  });

  final EnvironmentReadiness readiness;

  /// One line per download running beside setup (`SetupDownloads.lines`).
  final List<String> downloadLines;

  @override
  State<EnvironmentSetupDetails> createState() =>
      _EnvironmentSetupDetailsState();
}

class _EnvironmentSetupDetailsState extends State<EnvironmentSetupDetails> {
  String? _copied;
  String? _copyError;
  var _copyRevision = 0;
  Timer? _copyTimer;

  @override
  void dispose() {
    _copyTimer?.cancel();
    super.dispose();
  }

  // The setup screen's copy, with the same rule: only the latest attempt may
  // change what the button says.
  Future<void> _copy(String value) async {
    final revision = ++_copyRevision;
    _copyTimer?.cancel();
    try {
      await Clipboard.setData(ClipboardData(text: value));
      if (!mounted || revision != _copyRevision) return;
      setState(() {
        _copied = value;
        _copyError = null;
      });
      _copyTimer = Timer(const Duration(milliseconds: 1400), () {
        if (mounted && revision == _copyRevision) {
          setState(() => _copied = null);
        }
      });
    } catch (_) {
      if (!mounted || revision != _copyRevision) return;
      setState(() {
        _copied = null;
        _copyError =
            'Could not copy. Select the text to copy it, or try again.';
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    grid.AppTheme.watch(context);
    final state = widget.readiness;
    final failure = state.failure;
    final diagnostics = [...widget.downloadLines, ...state.output].join('\n');
    return Column(
      crossAxisAlignment: CrossAxisAlignment.stretch,
      children: [
        EnvironmentCheckList(readiness: state, checking: true),
        if (failure?.command != null) ...[
          const SizedBox(height: 12),
          CommandRow(
            command: failure!.command!,
            copied: _copied == failure.command,
            onCopy: () => _copy(failure.command!),
          ),
        ],
        const SizedBox(height: 12),
        Row(
          children: [
            Expanded(
              child: Text(
                'Setup log',
                style: grid.AppType.label(
                  fontWeight: FontWeight.w600,
                  color: AppColors.text,
                ),
              ),
            ),
            TextButton.icon(
              key: const ValueKey('setup-copy-diagnostics'),
              onPressed: diagnostics.isEmpty ? null : () => _copy(diagnostics),
              icon: const Icon(AppIcons.copy, size: 14),
              label: Text(
                _copied == diagnostics ? 'Copied' : 'Copy diagnostics',
              ),
            ),
          ],
        ),
        if (_copyError != null)
          Semantics(
            liveRegion: true,
            child: Text(
              _copyError!,
              style: grid.AppType.body(
                color: Theme.of(context).colorScheme.error,
              ),
            ),
          ),
        const SizedBox(height: 6),
        Container(
          constraints: const BoxConstraints(maxHeight: 180),
          decoration: BoxDecoration(
            color: AppColors.background,
            border: Border.all(color: AppColors.border),
            borderRadius: BorderRadius.circular(10),
          ),
          child: SingleChildScrollView(
            reverse: true,
            padding: const EdgeInsets.all(12),
            child: SizedBox(
              width: double.infinity,
              child: SelectableText(
                diagnostics.isEmpty ? 'Nothing logged yet.' : diagnostics,
                style: grid.AppType.monoLabel(
                  fontWeight: FontWeight.w400,
                  height: 1.55,
                  color: AppColors.textSoft,
                ),
              ),
            ),
          ),
        ),
      ],
    );
  }
}