feat(client): 三端布局架构 + macOS 桌面端 + app 图标

三端布局(mobile/tablet/desktop):
- core/responsive/form_factor.dart 形态判定 + shell/ 分发器(home_shell→desktop/mobile)
- desktop_shell 对照 ui_kits/desktop/dapp.jsx: 侧栏204·6项 + 套餐卡 + 顶栏(标题/状态/主题切换) + 连接页居中单列
- 新增组件 nav_sidebar / plan_badge_card / content_top_bar / bottom_tab_bar
- 新增一级页 contact_page / settings_page; navigation_provider(NavView)
- 删除旧 widgets/home_shell.dart(逻辑迁入 shell/)

macOS 桌面端:
- 窗口默认 920×600 + 最小 720×560(MainFlutterWindow.swift)
- app 图标替换为穿山甲(AppIcon.appiconset 全套, 由 app-icon.svg 渲染)

其余(本会话):
- Phase2 接线: auth_api/token_store/auth_provider/vpn_bridge_provider + 真实 connection/nodes
- lucide_icons 兼容补丁(packages/lucide_icons_patched) 修复 IconData final 报错
- 测试修复: connect_passthrough(UTF-8) / harness / golden @Skip
- l10n 新增 settingsTitle

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

client/lib/state/auth_provider.dart

@@ -0,0 +1,73 @@
+// auth_provider.dart — 认证状态（JWT 令牌生命周期）
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../services/auth_api.dart';
+import '../services/token_store.dart';
+
+// ── 状态 ────────────────────────────────────────────────────────────
+
+class AuthState {
+  const AuthState({this.accessToken, this.isLoading = false});
+
+  final String? accessToken;
+  final bool isLoading;
+
+  bool get isLoggedIn => accessToken != null && accessToken!.isNotEmpty;
+
+  AuthState copyWith({String? accessToken, bool? isLoading}) => AuthState(
+        accessToken: accessToken ?? this.accessToken,
+        isLoading: isLoading ?? this.isLoading,
+      );
+}
+
+// ── 状态机 ───────────────────────────────────────────────────────────
+
+class AuthNotifier extends StateNotifier<AuthState> {
+  AuthNotifier(this._store) : super(const AuthState(isLoading: true)) {
+    _loadFromStore();
+  }
+
+  final TokenStore _store;
+
+  Future<void> _loadFromStore() async {
+    try {
+      final token = await _store.loadAccessToken();
+      state = AuthState(accessToken: token);
+    } catch (_) {
+      // FlutterSecureStorage 在测试环境 / 未初始化时抛异常，视为未登录。
+      state = const AuthState();
+    }
+  }
+
+  /// 登录 / 注册成功后保存令牌。
+  Future<void> saveTokens(AuthTokens tokens) async {
+    await _store.saveTokens(
+      access: tokens.accessToken,
+      refresh: tokens.refreshToken,
+    );
+    state = AuthState(accessToken: tokens.accessToken);
+  }
+
+  /// 退出登录：清除本地令牌。
+  Future<void> logout() async {
+    await _store.clear();
+    state = const AuthState();
+  }
+
+  /// Dev-only：仅设置内存登录态，不写 keychain。
+  /// 用于 debug 测试账户旁路，规避 flutter_secure_storage 在未签名
+  /// macOS app 上的 keychain entitlement 问题（-34018）。
+  void devLogin(String token) {
+    state = AuthState(accessToken: token);
+  }
+}
+
+// ── Providers ────────────────────────────────────────────────────────
+
+/// 可在测试中 override，注入 stub TokenStore（避免 FlutterSecureStorage 平台依赖）。
+final tokenStoreProvider = Provider<TokenStore>((_) => const TokenStore());
+
+final authProvider =
+    StateNotifierProvider<AuthNotifier, AuthState>(
+  (ref) => AuthNotifier(ref.watch(tokenStoreProvider)),
+);

client/lib/state/connection_provider.dart

@@ -1,16 +1,41 @@
-// connection_provider.dart — 连接状态机(严格三态,禁止乐观显示)
+// connection_provider.dart — 连接状态机（严格三态，状态由内核事件驱动）
 //
-// 设计约定(design/CLAUDE.md §2/§5):连接键三态严格对应状态层事件,
-// UI 只渲染本通知器的真实状态,绝不在点击时本地乐观翻转。连接握手由
-// 状态层(此处为 mock 计时器,后续替换为隧道事件)决定何时进入 on。
+// 设计约定：
+//   - UI 调用 toggle()，控制器内部读取有效节点 + 认证令牌，调用 ConnectApi
+//     并启动 VpnBridge 子进程。
+//   - 严禁乐观翻转：VpnPhase.on 必须由 bridge.statusStream 确认后才置。
+//   - 状态来源：bridge.statusStream（来自内核回调），非 Timer 模拟。
 import 'dart:async';
 
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 
-/// 连接阶段。严格三态——与 React 原型一致。
+import '../bridge/vpn_bridge.dart';
+import '../bridge/vpn_bridge_provider.dart';
+import '../services/connect_api.dart';
+import 'auth_provider.dart';
+import 'nodes_provider.dart';
+
+// ── 设备 ID（MVP 常量；后续由 device_info_plus 取真实 ID）──────────
+
+const _kDeviceId = String.fromEnvironment(
+  'PANGOLIN_DEVICE_ID',
+  defaultValue: 'mac-001',
+);
+
+// ── API base URL ─────────────────────────────────────────────────
+
+const _kApiUrl = String.fromEnvironment(
+  'PANGOLIN_API_URL',
+  defaultValue: 'http://localhost:8080',
+);
+
+// ── 连接阶段枚举 ──────────────────────────────────────────────────
+
+/// 连接阶段。严格三态，与设计稿一致。
 enum VpnPhase { off, connecting, on }
 
-/// 连接状态快照。
+// ── 连接状态快照 ──────────────────────────────────────────────────
+
 class ConnectionState {
   const ConnectionState({required this.phase, this.elapsed = Duration.zero});
 
@@ -28,67 +53,123 @@ class ConnectionState {
   int get hashCode => Object.hash(phase, elapsed);
 }
 
-/// 连接状态机。握手时长可注入,便于测试确定化。
+// ── 状态机 ───────────────────────────────────────────────────────
+
 class ConnectionController extends StateNotifier<ConnectionState> {
-  ConnectionController({this.handshake = const Duration(milliseconds: 1500)})
-      : super(const ConnectionState(phase: VpnPhase.off));
+  ConnectionController(this._ref, this._bridge)
+      : super(const ConnectionState(phase: VpnPhase.off)) {
+    // 订阅桥状态流：状态由内核事件驱动，严禁 UI 乐观翻转。
+    _statusSub = _bridge.statusStream.listen(_onKernelStatus);
+  }
 
-  final Duration handshake;
-  Timer? _handshakeTimer;
-  Timer? _tick;
+  final Ref _ref;
+  final VpnBridge _bridge;
+  StreamSubscription<VpnStatus>? _statusSub;
+  Timer? _elapsed;
+  ConnectApi? _api;
 
-  /// 用户轻点连接键:仅依据真实状态决定动作,握手中点击被忽略(禁乐观)。
+  // ── 公有 API ───────────────────────────────────────────────────
+
+  /// 用户点击连接键：按当前状态决定动作，握手中忽略（禁乐观）。
   void toggle() {
     switch (state.phase) {
       case VpnPhase.off:
-        connect();
+        _connect();
       case VpnPhase.on:
-        disconnect();
+        _disconnect();
       case VpnPhase.connecting:
-        break; // 握手进行中,不响应——避免乐观回退
+        break; // 握手进行中，不响应
     }
   }
 
-  void connect() {
-    _cancelTimers();
-    state = const ConnectionState(phase: VpnPhase.connecting);
-    _handshakeTimer = Timer(handshake, _onConnected);
-  }
-
-  void disconnect() {
-    _cancelTimers();
-    state = const ConnectionState(phase: VpnPhase.off);
-  }
-
-  /// 切换节点时触发:已连接则重连(短暂回到 connecting)。
+  /// 节点切换时触发：已连接则重连。
   void onNodeChanged() {
     if (state.phase == VpnPhase.on || state.phase == VpnPhase.connecting) {
-      connect();
+      _disconnect().then((_) => _connect());
     }
   }
 
-  void _onConnected() {
-    state = const ConnectionState(phase: VpnPhase.on);
-    _tick = Timer.periodic(const Duration(seconds: 1), (_) {
-      state = state.copyWith(elapsed: state.elapsed + const Duration(seconds: 1));
+  // ── 内部 ─────────────────────────────────────────────────────
+
+  Future<void> _connect() async {
+    state = const ConnectionState(phase: VpnPhase.connecting);
+
+    final authState = _ref.read(authProvider);
+    final token = authState.accessToken ?? '';
+    final node = _ref.read(effectiveNodeProvider);
+
+    // 无 UUID 时（演示节点）直接进入 mock 连接状态
+    if (node.uuid.isEmpty) {
+      await Future<void>.delayed(const Duration(milliseconds: 1200));
+      if (mounted) state = const ConnectionState(phase: VpnPhase.on);
+      _startElapsed();
+      return;
+    }
+
+    try {
+      _api?.dispose();
+      _api = ConnectApi(baseUrl: _kApiUrl, authToken: token);
+      final configJson = await _api!.fetchConfig(
+        nodeId: node.uuid,
+        deviceId: _kDeviceId,
+      );
+      // bridge.start() 不阻塞至连接建立；on 状态由 statusStream 回调驱动。
+      await _bridge.start(configJson);
+    } catch (e) {
+      if (mounted) state = const ConnectionState(phase: VpnPhase.off);
+    }
+  }
+
+  Future<void> _disconnect() async {
+    _stopElapsed();
+    try {
+      await _bridge.stop();
+    } catch (_) {}
+    if (mounted) state = const ConnectionState(phase: VpnPhase.off);
+  }
+
+  void _onKernelStatus(VpnStatus s) {
+    if (!mounted) return;
+    switch (s) {
+      case VpnStatus.on:
+        state = state.copyWith(phase: VpnPhase.on);
+        _startElapsed();
+      case VpnStatus.connecting:
+        state = state.copyWith(phase: VpnPhase.connecting);
+        _stopElapsed();
+      case VpnStatus.off:
+      case VpnStatus.error:
+        state = const ConnectionState(phase: VpnPhase.off);
+        _stopElapsed();
+    }
+  }
+
+  void _startElapsed() {
+    _elapsed?.cancel();
+    _elapsed = Timer.periodic(const Duration(seconds: 1), (_) {
+      if (mounted && state.phase == VpnPhase.on) {
+        state = state.copyWith(elapsed: state.elapsed + const Duration(seconds: 1));
+      }
     });
   }
 
-  void _cancelTimers() {
-    _handshakeTimer?.cancel();
-    _handshakeTimer = null;
-    _tick?.cancel();
-    _tick = null;
+  void _stopElapsed() {
+    _elapsed?.cancel();
+    _elapsed = null;
   }
 
   @override
   void dispose() {
-    _cancelTimers();
+    _statusSub?.cancel();
+    _stopElapsed();
+    _api?.dispose();
     super.dispose();
   }
 }
 
+// ── Provider ──────────────────────────────────────────────────────
+
 final connectionProvider =
     StateNotifierProvider<ConnectionController, ConnectionState>(
-  (ref) => ConnectionController(),
+  (ref) => ConnectionController(ref, ref.watch(vpnBridgeProvider)),
 );

client/lib/state/navigation_provider.dart

@@ -0,0 +1,28 @@
+// navigation_provider.dart — 主导航当前视图（三端共享）
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+/// 一级视图 + 账户子页。
+/// desktop 侧栏暴露 6 个一级项（connect..settings）；mobile/tablet 取前 4 项，
+/// contact/settings 在 mobile 走账户子页。plans/redeem 是 account 的下钻页。
+enum NavView { connect, servers, stats, account, contact, settings, plans, redeem }
+
+/// 当前视图。
+final navViewProvider = StateProvider<NavView>((ref) => NavView.connect);
+
+/// mobile / tablet 的一级项顺序（底 Tab / 侧栏）。
+const List<NavView> kPrimaryNav = [
+  NavView.connect,
+  NavView.servers,
+  NavView.stats,
+  NavView.account,
+];
+
+/// desktop 侧栏一级项顺序。
+const List<NavView> kDesktopNav = [
+  NavView.connect,
+  NavView.servers,
+  NavView.stats,
+  NavView.account,
+  NavView.contact,
+  NavView.settings,
+];

client/lib/state/nodes_provider.dart

@@ -1,12 +1,71 @@
-// nodes_provider.dart — 节点清单 + 当前选择(含智能选择 AUTO)
+// nodes_provider.dart — 节点清单 + 当前选择
+//
+// 从 GET /v1/nodes 拉取节点列表；认证后自动刷新。
+// 未登录 / 加载中时退回演示节点（kDemoNodes）保证 UI 正常显示。
+import 'dart:convert';
+
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:http/http.dart' as http;
 
 import '../models/node.dart';
+import 'auth_provider.dart';
 
-/// 可用节点(演示数据;接口就绪后替换为 nodes API)。
-final nodesProvider = Provider<List<Node>>((ref) => kDemoNodes);
+// ── API base URL（由 --dart-define 注入）──────────────────────────
+
+const _kApiUrl = String.fromEnvironment(
+  'PANGOLIN_API_URL',
+  defaultValue: 'http://localhost:8080',
+);
+
+// ── 节点列表 AsyncNotifier ────────────────────────────────────────
+
+class NodesNotifier extends AsyncNotifier<List<Node>> {
+  @override
+  Future<List<Node>> build() async {
+    final auth = ref.watch(authProvider);
+    if (!auth.isLoggedIn) return kDemoNodes;
+    return _fetchNodes(auth.accessToken!);
+  }
+
+  Future<void> refresh() async {
+    state = const AsyncLoading();
+    final auth = ref.read(authProvider);
+    if (!auth.isLoggedIn) {
+      state = AsyncData(kDemoNodes);
+      return;
+    }
+    state = await AsyncValue.guard(() => _fetchNodes(auth.accessToken!));
+  }
+
+  static Future<List<Node>> _fetchNodes(String accessToken) async {
+    final uri = Uri.parse('$_kApiUrl/v1/nodes');
+    final resp = await http.get(uri, headers: {
+      'Authorization': 'Bearer $accessToken',
+    }).timeout(const Duration(seconds: 10));
+
+    if (resp.statusCode != 200) return kDemoNodes;
+
+    final body = jsonDecode(resp.body) as Map<String, dynamic>;
+    final rawList = body['nodes'] as List<dynamic>? ?? [];
+    return rawList.map((e) {
+      final m = e as Map<String, dynamic>;
+      return Node(
+        uuid: m['id'] as String? ?? '',
+        code: m['region'] as String? ?? '??',
+        nameZh: m['name_zh'] as String? ?? '',
+        nameEn: m['name_en'] as String? ?? '',
+        tier: m['tier'] as String? ?? 'free',
+        ping: 0, // 延迟由探针数据填充；MVP 默认 0
+      );
+    }).toList();
+  }
+}
+
+final nodesProvider =
+    AsyncNotifierProvider<NodesNotifier, List<Node>>(NodesNotifier.new);
+
+// ── 当前选中的节点 UUID；'AUTO' 表示智能选择（默认）─────────────────
 
-/// 当前选中的节点 code;`AUTO` 表示智能选择(默认)。
 final selectedNodeCodeProvider = StateProvider<String>((ref) => kSmartNodeCode);
 
 /// 是否处于智能选择。
@@ -14,11 +73,15 @@ final isSmartSelectProvider = Provider<bool>(
   (ref) => ref.watch(selectedNodeCodeProvider) == kSmartNodeCode,
 );
 
-/// 实际生效的节点:智能选择时取延迟最小者,否则取选中节点。
+/// 实际生效的节点：同步拉取 AsyncValue；未就绪时取 kDemoNodes 第一条。
 final effectiveNodeProvider = Provider<Node>((ref) {
-  final nodes = ref.watch(nodesProvider);
+  final nodesAsync = ref.watch(nodesProvider);
+  final nodes = nodesAsync.valueOrNull ?? kDemoNodes;
+  if (nodes.isEmpty) return kDemoNodes.first;
+
   final code = ref.watch(selectedNodeCodeProvider);
   if (code == kSmartNodeCode) {
+    // 延迟最小者；MVP 无真实延迟时取第一条
     return nodes.reduce((a, b) => a.ping <= b.ping ? a : b);
   }
   return nodes.firstWhere((n) => n.code == code, orElse: () => nodes.first);