halkyon_app: instances, sign-in and sync plumbing for Halkyon's apps

What every Halkyon app's shell needs, taken from Halkyon Learn's and set
on halkyon_base's client: the instances a device keeps an account on,
the first start's tiles and where an instance keeps people's data, the
account switcher; signing in anonymously, with GitHub or an email code,
switching person and the start screen; the gates that build an app's
dependencies per instance and per person; and the sync service with its
status, Settings card and banner. Texts of its own in English and
German take the app's name; what only the app can say, it passes in.
Fakes for apps' tests are in testing.dart.

An instance's basics now name the app it serves (`app`, set by the
host's configuration), and an app accepts only an instance of its own.
SerialQueue and CoalescingRunner move into halkyon_core.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>

packages/halkyon_app/test/instance/country_names_test.dart

@@ -0,0 +1,16 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:halkyon_app/halkyon_app.dart';
+
+void main() {
+  test('a country is named in the language asked for, else in English, and '
+      'one without a name not at all', () async {
+    final names = MemoryCountryNames({
+      'CH': {'de': 'Schweiz', 'en': 'Switzerland'},
+    });
+
+    expect(await names.nameOf('CH', 'de'), 'Schweiz');
+    expect(await names.nameOf('ch', 'de'), 'Schweiz');
+    expect(await names.nameOf('CH', 'ja'), 'Switzerland');
+    expect(await names.nameOf('XX', 'en'), isNull);
+  });
+}

packages/halkyon_app/test/instance/flag_icons_license_test.dart

@@ -0,0 +1,27 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:halkyon_app/halkyon_app.dart';
+
+void main() {
+  TestWidgetsFlutterBinding.ensureInitialized();
+
+  test("the flags' MIT notice joins the licence list, as their licence "
+      'asks', () async {
+    registerFlagIconsLicense();
+
+    final notices = [
+      await for (final entry in LicenseRegistry.licenses)
+        if (entry.packages.contains('flag-icons'))
+          entry.paragraphs.map((paragraph) => paragraph.text).join('\n'),
+    ];
+    expect(notices, hasLength(1));
+    expect(notices.single, contains('Copyright (c) 2013 Panayiotis Lipiridis'));
+    expect(
+      notices.single,
+      contains(
+        'The above copyright notice and this permission notice shall be '
+        'included',
+      ),
+    );
+  });
+}

packages/halkyon_app/test/instance/instance_checker_test.dart

@@ -0,0 +1,67 @@
+import 'dart:convert';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:halkyon_app/halkyon_app.dart';
+import 'package:halkyon_base_client/halkyon_base_client.dart';
+import 'package:http/http.dart' as http;
+import 'package:http/testing.dart';
+
+void main() {
+  final halkyon = Instance.parse('learn.example.org')!;
+  final todo = Instance.parse('todo.example.org')!;
+  final elsewhere = Instance.parse('www.example.org')!;
+
+  /// Basics as an instance of [app] tells them.
+  http.Response basicsOf(String app) => http.Response(
+    jsonEncode(
+      InstanceBasics(
+        app: app,
+        emailSignIn: false,
+        sourceCodeUrl: 'https://code.example.org/$app',
+        minimumAppBuild: 1,
+        dataLocation: 'EU',
+        backupLocation: 'CH',
+      ).toJson(),
+    ),
+    200,
+  );
+
+  /// A checker of the app `learn` reaching instances through a fake network,
+  /// where learn.example.org answers as an instance of it, todo.example.org
+  /// as an instance of another app, and nothing else answers.
+  ServerpodInstanceChecker checker() => ServerpodInstanceChecker(
+    app: 'learn',
+    httpClient: () => MockClient(
+      (request) async => switch ((request.url.host, request.url.path)) {
+        ('learn.example.org', '/halkyon_base.instance/basics') => basicsOf(
+          'learn',
+        ),
+        ('todo.example.org', '/halkyon_base.instance/basics') => basicsOf(
+          'todo',
+        ),
+        _ => http.Response('<html>Not found</html>', 404),
+      },
+    ),
+  );
+
+  test('an instance answers when its halkyon_base tells its basics; any '
+      'other site does not', () async {
+    expect(await checker().answers(halkyon), isTrue);
+    expect(await checker().answers(elsewhere), isFalse);
+  });
+
+  test("another app's instance does not answer, so its address is refused "
+      'before the app moves there', () async {
+    expect(await checker().answers(todo), isFalse);
+    expect(await checker().locationsOf(todo), isNull);
+  });
+
+  test("says where an instance keeps people's data and its backups, and "
+      'nothing for a site that is no instance', () async {
+    expect(
+      await checker().locationsOf(halkyon),
+      const InstanceLocations(data: 'EU', backups: 'CH'),
+    );
+    expect(await checker().locationsOf(elsewhere), isNull);
+  });
+}

packages/halkyon_app/test/instance/instance_choice_test.dart

@@ -0,0 +1,86 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:halkyon_app/halkyon_app.dart';
+import 'package:halkyon_app/testing.dart';
+
+void main() {
+  final builtIn = Instance.parse('learn.halkyon.eu')!;
+  final other = Instance.parse('learn.example.org')!;
+  late MemoryInstanceStore store;
+  late List<Instance> forgotten;
+
+  InstanceChoice choice() => InstanceChoice(
+    store,
+    builtIn: builtIn,
+    forget: (instance) async {
+      forgotten.add(instance);
+    },
+  );
+
+  setUp(() {
+    store = MemoryInstanceStore();
+    forgotten = [];
+  });
+
+  test('a new install has no instance until one is chosen', () async {
+    final instances = choice();
+    await instances.load(usedBefore: false);
+
+    expect(instances.current, isNull);
+    expect(instances.known, isEmpty);
+
+    await instances.use(other);
+    expect(instances.current, other);
+    expect(store.kept?.current, other);
+    expect(store.kept?.known, [other]);
+  });
+
+  test('an install from before there was a choice goes on with the '
+      "build's instance", () async {
+    final instances = choice();
+    await instances.load(usedBefore: true);
+
+    expect(instances.current, builtIn);
+    expect(store.kept?.current, builtIn);
+    expect(store.kept?.known, [builtIn]);
+  });
+
+  test('what was chosen is read back', () async {
+    store = MemoryInstanceStore((current: other, known: [builtIn, other]));
+    final instances = choice();
+    await instances.load(usedBefore: true);
+
+    expect(instances.current, other);
+    expect(instances.known, [builtIn, other]);
+  });
+
+  test('switching keeps every account; removing one forgets what the '
+      'device holds of it, never of the one in use', () async {
+    final instances = choice();
+    await instances.load(usedBefore: true);
+    await instances.use(other);
+    await instances.use(builtIn);
+    expect(instances.known, [builtIn, other]);
+
+    await instances.remove(builtIn);
+    expect(forgotten, isEmpty, reason: 'in use');
+
+    await instances.remove(other);
+    expect(forgotten, [other]);
+    expect(instances.known, [builtIn]);
+    expect(store.kept?.current, builtIn);
+    expect(store.kept?.known, [builtIn]);
+  });
+
+  test('tells its listeners of every change', () async {
+    final instances = choice();
+    var changes = 0;
+    instances.addListener(() => changes++);
+
+    await instances.load(usedBefore: false);
+    await instances.use(other);
+    await instances.use(builtIn);
+    await instances.remove(other);
+
+    expect(changes, 4);
+  });
+}

packages/halkyon_app/test/instance/instance_test.dart

@@ -0,0 +1,51 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:halkyon_app/halkyon_app.dart';
+
+void main() {
+  test('reads an address as people type it, HTTPS unless they say not', () {
+    for (final address in [
+      'learn.example.org',
+      'https://learn.example.org',
+      ' HTTPS://Learn.Example.org/ ',
+    ]) {
+      expect(
+        Instance.parse(address)?.url,
+        Uri.parse('https://learn.example.org/'),
+        reason: address,
+      );
+    }
+    expect(
+      Instance.parse('http://localhost:8080')?.url,
+      Uri.parse('http://localhost:8080/'),
+    );
+    expect(
+      Instance.parse('example.org/learn?x=1#top')?.url,
+      Uri.parse('https://example.org/learn/'),
+    );
+  });
+
+  test('refuses what is no address', () {
+    for (final address in [
+      '',
+      '  ',
+      'learn example org',
+      'ftp://example.org',
+      'https://',
+      'https://someone@example.org',
+    ]) {
+      expect(Instance.parse(address), isNull, reason: address);
+    }
+  });
+
+  test('is named by its host, and its port if it has one', () {
+    expect(Instance.parse('learn.halkyon.eu')!.name, 'learn.halkyon.eu');
+    expect(Instance.parse('localhost:8080')!.name, 'localhost:8080');
+  });
+
+  test('is the same instance however its address was written', () {
+    expect(
+      Instance.parse('learn.example.org'),
+      Instance.parse('https://LEARN.example.org/'),
+    );
+  });
+}

packages/halkyon_app/test/instance/widget/instance_location_words_test.dart

@@ -0,0 +1,62 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:halkyon_app/halkyon_app.dart';
+import 'package:halkyon_app/l10n/halkyon_app_localizations_de.dart';
+import 'package:halkyon_app/l10n/halkyon_app_localizations_en.dart';
+
+void main() {
+  final en = HalkyonAppLocalizationsEn();
+  final de = HalkyonAppLocalizationsDe();
+  const names = {'CH': 'Switzerland', 'DE': 'Germany'};
+  String? words(InstanceLocations locations) =>
+      instanceLocationWords(en, locations, names);
+
+  test('data and backups in one place are named once', () {
+    expect(
+      words(const InstanceLocations(data: 'EU', backups: 'EU')),
+      'Data and backups: European Union',
+    );
+  });
+
+  test('data and backups apart are named a line each', () {
+    expect(
+      words(const InstanceLocations(data: 'EU', backups: 'CH')),
+      'Data: European Union\nBackups: Switzerland',
+    );
+  });
+
+  test('an instance keeping no backups says so', () {
+    expect(
+      words(
+        const InstanceLocations(
+          data: 'CH',
+          backups: InstanceLocations.noBackups,
+        ),
+      ),
+      'Data: Switzerland\nNo backups',
+    );
+  });
+
+  test('what the instance leaves unsaid is left out', () {
+    expect(words(const InstanceLocations(data: 'DE')), 'Data: Germany');
+    expect(
+      words(const InstanceLocations(backups: 'CH')),
+      'Backups: Switzerland',
+    );
+    expect(words(const InstanceLocations()), isNull);
+  });
+
+  test('a country without a name here goes by its code', () {
+    expect(words(const InstanceLocations(data: 'XK')), 'Data: XK');
+  });
+
+  test('in German too, without the articles some countries take', () {
+    expect(
+      instanceLocationWords(
+        de,
+        const InstanceLocations(data: 'EU', backups: 'CH'),
+        const {'CH': 'Schweiz'},
+      ),
+      'Daten: Europäische Union\nSicherungen: Schweiz',
+    );
+  });
+}

packages/halkyon_app/test/instance/widget/instance_tile_test.dart

@@ -0,0 +1,163 @@
+import 'package:flutter/gestures.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:halkyon_app/halkyon_app.dart';
+import 'package:lucide_icons_flutter/lucide_icons.dart';
+import 'package:material_ui/material_ui.dart';
+
+void main() {
+  late List<String> tapped;
+
+  setUp(() => tapped = []);
+
+  /// Shows a tile beside something else to move the pointer or focus to.
+  Future<void> show(WidgetTester tester, {bool? expanded}) async {
+    await tester.pumpWidget(
+      MaterialApp(
+        home: Scaffold(
+          body: Column(
+            children: [
+              TextButton(onPressed: () {}, child: const Text('Elsewhere')),
+              InstanceTile(
+                icon: const Icon(LucideIcons.globe),
+                label: 'learn.halkyon.eu',
+                tagline: 'Comes with the app',
+                expanded: expanded,
+                onTap: () => tapped.add('tile'),
+              ),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+
+  double ring(WidgetTester tester) =>
+      tester.widget<Opacity>(find.byKey(InstanceTile.ringKey)).opacity;
+
+  double tagline(WidgetTester tester) => tester
+      .widget<Opacity>(
+        find.ancestor(
+          of: find.text('Comes with the app'),
+          matching: find.byType(Opacity),
+        ),
+      )
+      .opacity;
+
+  testWidgets('without a mouse, the tagline shows from the start', (
+    tester,
+  ) async {
+    await show(tester);
+
+    expect(tagline(tester), 1);
+    expect(ring(tester), 0);
+  });
+
+  testWidgets('with a mouse, the ring and the tagline come in under the '
+      'pointer and go once it leaves', (tester) async {
+    await show(tester);
+    final mouse = await tester.createGesture(kind: PointerDeviceKind.mouse);
+    addTearDown(mouse.removePointer);
+    await mouse.addPointer(location: tester.getCenter(find.text('Elsewhere')));
+    await tester.pumpAndSettle();
+    expect(tagline(tester), 0);
+    expect(ring(tester), 0);
+
+    await mouse.moveTo(tester.getCenter(find.byType(Icon)));
+    // The frame that starts it, then halfway.
+    await tester.pump();
+    await tester.pump(InstanceTile.duration ~/ 2);
+    expect(ring(tester), inExclusiveRange(0, 1), reason: 'it fades in');
+    await tester.pumpAndSettle();
+    expect(tagline(tester), 1);
+    expect(ring(tester), 1);
+
+    await mouse.moveTo(tester.getCenter(find.text('Elsewhere')));
+    await tester.pumpAndSettle();
+    expect(tagline(tester), 0);
+    expect(ring(tester), 0);
+  });
+
+  testWidgets("the keyboard's focus rings it, and Enter chooses it", (
+    tester,
+  ) async {
+    await show(tester);
+
+    // From Elsewhere to the tile.
+    await tester.sendKeyEvent(LogicalKeyboardKey.tab);
+    await tester.sendKeyEvent(LogicalKeyboardKey.tab);
+    await tester.pumpAndSettle();
+    expect(ring(tester), 1);
+
+    await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+    expect(tapped, ['tile']);
+  });
+
+  testWidgets('it rings while pressed', (tester) async {
+    await show(tester);
+
+    final finger = await tester.startGesture(
+      tester.getCenter(find.byType(Icon)),
+    );
+    await tester.pumpAndSettle();
+    expect(ring(tester), 1);
+
+    await finger.up();
+    await tester.pumpAndSettle();
+    expect(ring(tester), 0);
+    expect(tapped, ['tile']);
+  });
+
+  testWidgets('it stays ringed while what it opens is open', (tester) async {
+    await show(tester, expanded: true);
+    expect(ring(tester), 1);
+
+    await show(tester, expanded: false);
+    await tester.pumpAndSettle();
+    expect(ring(tester), 0);
+  });
+
+  testWidgets('a screen reader hears one button, its tagline included', (
+    tester,
+  ) async {
+    await show(tester, expanded: false);
+
+    expect(
+      // The label's node is merged into the tile's.
+      tester.getSemantics(find.text('learn.halkyon.eu')),
+      matchesSemantics(
+        label: 'learn.halkyon.eu\nComes with the app',
+        isButton: true,
+        hasTapAction: true,
+        hasFocusAction: true,
+        isFocusable: true,
+        hasExpandedState: true,
+      ),
+    );
+  });
+
+  testWidgets('with animations off, it rings at once', (tester) async {
+    await tester.pumpWidget(
+      MaterialApp(
+        // The app's own MediaQuery would hide one above it.
+        builder: (context, child) => MediaQuery(
+          data: MediaQuery.of(context).copyWith(disableAnimations: true),
+          child: child!,
+        ),
+        home: Scaffold(
+          body: InstanceTile(
+            icon: const Icon(LucideIcons.globe),
+            label: 'learn.halkyon.eu',
+            tagline: 'Comes with the app',
+            expanded: false,
+            onTap: () {},
+          ),
+        ),
+      ),
+    );
+
+    await tester.startGesture(tester.getCenter(find.byType(Icon)));
+    await tester.pump();
+    expect(ring(tester), 1);
+  });
+}