Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ All notable changes to MailBurrow are recorded here. Versions follow the app ver

- **iOS:** the bundle ID is now `com.kuncarlos91.mailburrow`, matching Android, and the bundle name is MailBurrow. Earlier TestFlight builds used `com.kuncarlos91.mailshelf`; the new ID installs as a separate app, so saved connections are entered again once.
- **Fixed:** the setup screen's introduction now names Bichon alongside Mail-Archiver and Open Archiver. In 0.5.0 it listed only the first two, though choosing Bichon worked. The introduction now derives its backend names from the selector's shared server-type list, with a regression covering every entry.
- **Changed:** exiting the demo reopens the archive that was open when the demo started, and Cancel on the Opening screen during an archive switch reopens the archive that was open before it. In 0.5.0 both returned to setup. Cancel at startup, or again while the previous archive reopens, still returns to setup, so Cancel never loops; a previous archive forgotten in the meantime is not reopened.
- README: setup screenshot updated to the 0.5.0 screen with three server types.

## 0.5.0 (build31) - 2026-11-17
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ The setup screen has a **Try the demo** button. It opens a small archive of made

- A **Demo · sample mail** bar stays on every screen. Tap its **Exit** button, or **Settings → Exit demo**, to leave. Closing the app also leaves the demo.
- The demo connects to no server, sends nothing over the network and never saves or changes a connection, so a real connection you saved earlier is kept.
- **Development builds:** leaving a demo started from an open real archive reconnects to that archive, using saved credentials and the normal Opening/Cancel flow. That reconnection contacts its server and may update its saved selection; it adds no archive. Published 0.5.0 returns to setup instead.
- Saving a demo attachment still uses the normal save dialog, and confirmed links still open in your browser, just as with a real archive.

Android in dark mode, using fictional demo mail: **browse mail** (first), then **read a message** (second).
Expand Down
4 changes: 2 additions & 2 deletions docs/PLAYBOOK.md

Large diffs are not rendered by default.

2 changes: 2 additions & 0 deletions docs/setup-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ The [website guide](https://mailburrow.pages.dev/setup.html) covers the same ste

To see what the app looks like before setting anything up, tap **Try the demo** on the setup screen: it opens fictional sample mail built into the app, with no server needed.

**Development behavior, not in published 0.5.0:** exiting a demo or cancelling an archive switch can reopen the real archive that was open before it. Reopening contacts that server using its saved credential, and shows Opening with Cancel. Startup Cancel or cancelling again during this return stops at setup; a forgotten archive is not reopened. No new archive is added, but normal reopening may update the saved selection. The website describes the released behavior until its next reviewed update.

Checked against Mail-Archiver's [REST API guide](https://github.com/s1t5/mail-archiver/blob/main/doc/API.md), Open Archiver 0.6.2, Bichon 2.4.2 Community, the TrueNAS Mail Archiver, Open Archiver and Tailscale apps, and Tailscale's HTTPS and Serve documentation, as of November 2026. Menu names can change between versions.

**iOS source identity:** development source uses `com.kuncarlos91.mailburrow`. Earlier TestFlight builds used `com.kuncarlos91.mailshelf`; the new identity installs separately and does not automatically migrate saved connections/Keychain entries. Keep the earlier app intact and enter credentials again in the new app. This source change does not establish a new TestFlight build or an iOS device pass.
Expand Down
4 changes: 2 additions & 2 deletions docs/troubleshooting/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ Save and Open have separate confirmations. There is no malware scanning; do not

| Symptom | Interpretation/next step |
| --- | --- |
| A "Demo · sample mail" bar is showing | You're in the built-in demo: all mail is fictional. Tap **Exit** on the bar, or **Settings → Exit demo**, to return to setup. |
| A "Demo · sample mail" bar is showing | You're in the built-in demo: all mail is fictional. Tap **Exit** on the bar, or **Settings → Exit demo**. In releases after 0.5.0, the app reopens the archive you had open before the demo; otherwise it returns to setup. |
| Try the demo button is missing | It's hidden while the demo is already open, for example on Connection settings opened from the demo. Exit the demo first. |
| Could not open the demo | The bundled sample data could not be read. Try again; if it keeps failing, report the app version and device. |
| My saved server is gone after the demo | The demo never changes a saved connection. On setup, use **Retry saved connection**, or reopen the app to restore it. |
Expand Down Expand Up @@ -114,6 +114,6 @@ A direct Gradle release after tests can fail on missing IntegrationTestPlugin be

A local diagnostic build can add `--dart-define=MAILSHELF_FILE_DIAGNOSTICS=true`. Default builds do not enable this tracing. Native events use only fixed MailShelfFiles categories for grant retention, saved-reference registration, release and the Open outcome; never add URIs, file names, provider exception messages, attachment bytes, server settings or keys. This is local logcat output, not an analytics upload. Read only the MailShelfFiles tag and do not share broad device logs.

While an archive is opening, Cancel is unavailable during the secure-storage commit and once the archive is open. Before that commit, cancelling returns to setup without activating the abandoned attempt; Retry starts another attempt.
While an archive is opening, Cancel is unavailable during the secure-storage commit and once the archive is open. Before that commit, cancelling never activates the abandoned attempt. In releases after 0.5.0,, cancelling a switch reopens the archive you had open before it; cancelling at startup, or again while that archive reopens, returns to setup, where Retry starts another attempt.

Reader cancellation fix: Back during a message load cancels that reader’s network calls rather than only hiding the result. Build 26 predates this fix; its successful navigation checks do not establish that its transport stopped. Validate a newer fixed APK separately, with its own source/hash and cancellation evidence.
55 changes: 47 additions & 8 deletions lib/state/archive_session.dart
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,15 @@ class ArchiveSession extends ChangeNotifier {
ArchiveBackend? _pendingCandidate;
int? _committingConnectToken;

// The saved archive that was open when the current switch began, reopened
// if that switch is cancelled. Null when nothing was open, so a Cancel
// while reopening it goes to setup instead of looping.
String? _switchReturnId;

// The saved archive that was open when the demo started, reopened when
// the demo is exited. Null when the demo started from setup.
String? _demoReturnId;

/// True while the saved archive is being opened at startup or from the
/// picker, so the progress screen can offer Cancel.
bool get canCancelOpening =>
Expand All @@ -160,13 +169,18 @@ class ArchiveSession extends ChangeNotifier {
(restoring || switchingArchive != null);

/// Stops opening an archive at startup or from the picker without waiting
/// for the server to answer or time out, and returns to setup with the
/// saved archives and Retry. The abandoned attempt's client is closed and
/// its late result is ignored; nothing is saved or activated.
/// for the server to answer or time out. The abandoned attempt's client is
/// closed and its late result is ignored; nothing is saved or activated.
///
/// A cancelled switch reopens the archive that was open before it, if it
/// is still saved. Otherwise, and at startup, setup is shown with the
/// saved archives and Retry.
Future<void> cancelOpening() async {
// Once the destination has been adopted, it is open: nothing to cancel.
if (!canCancelOpening || _disposed || api != null) return;
final switching = switchingArchive != null;
final returnId = switching ? _switchReturnId : null;
_switchReturnId = null;
_openingToken++;
_connectToken++;
_pendingCandidate?.close();
Expand All @@ -180,8 +194,23 @@ class ArchiveSession extends ChangeNotifier {
error = null;
server.clear();
keyInput.clear();
final token = _openingToken;
final connectToken = _connectToken;
bool current() => !_disposed && token == _openingToken && connectToken == _connectToken;
_notify();
await _refreshArchives();
await _refreshArchives(isCurrent: current);
await _reopen(returnId, current);
}

/// Reopens the saved archive [id] after a cancelled switch or the demo,
/// unless [id] is null or no longer saved, or [stillCurrent] reports that
/// the user has started something else meanwhile.
Future<void> _reopen(String? id, bool Function() stillCurrent) async {
if (id == null || _disposed || !stillCurrent()) return;
if (api != null || !setup || !archives.any((item) => item.id == id)) {
return;
}
await switchArchive(id);
}

/// The archive [reconnectArchiveId] names, if it is still saved.
Expand Down Expand Up @@ -355,6 +384,8 @@ class ArchiveSession extends ChangeNotifier {
final profile = archives.where((item) => item.id == id).firstOrNull;
if (profile == null) return;
if (!setup && api != null && id == activeArchiveId) return;
final previous = !demo && api != null ? activeArchiveId : null;
_switchReturnId = previous == id ? null : previous;
reconfiguring = null;
api?.close();
_invalidateRequests();
Expand Down Expand Up @@ -936,7 +967,7 @@ class ArchiveSession extends ChangeNotifier {

Future<void> forgetConnection() async {
if (demo) {
exitDemo();
await exitDemo();
return;
}
try {
Expand Down Expand Up @@ -979,6 +1010,7 @@ class ArchiveSession extends ChangeNotifier {
/// the saved connection and the setup fields are left as they are.
Future<void> startDemo() async {
if (demo && !setup) return;
if (!demo) _demoReturnId = api != null ? activeArchiveId : null;
mailRequestFailed = false;
accountSwitchGeneration++;
accountLoading = false;
Expand Down Expand Up @@ -1022,13 +1054,17 @@ class ArchiveSession extends ChangeNotifier {
}
}

/// Leaves the demo and returns to setup.
/// Leaves the demo. If a saved archive was open when the demo started, it
/// is reopened (with the Opening screen and Cancel); otherwise setup is
/// shown.
///
/// Stops demo requests and attachment copies in progress; their late
/// results are ignored. The saved connection is not touched, so
/// results are ignored. The demo itself saves nothing, so
/// "Retry saved connection" still works afterwards.
void exitDemo() {
Future<void> exitDemo() async {
if (!demo) return;
final returnId = _demoReturnId;
_demoReturnId = null;
api?.close();
_invalidateRequests();
_clearBrowsing();
Expand All @@ -1048,6 +1084,9 @@ class ArchiveSession extends ChangeNotifier {
setup = true;
busy = false;
error = null;
final token = _openingToken;
final connectToken = _connectToken;
_notify();
await _reopen(returnId, () => token == _openingToken && connectToken == _connectToken && !demo);
}
}
14 changes: 3 additions & 11 deletions test/archive_management_test.dart
Original file line number Diff line number Diff line change
Expand Up @@ -555,17 +555,9 @@ void main() {
pending!.ready.complete();
await tester.pumpAndSettle();
expect(find.text('a.example mail'), findsNothing);
await tester.scrollUntilVisible(
find.text('Retry saved connection'),
200,
scrollable: find
.descendant(
of: find.byType(SetupView),
matching: find.byType(Scrollable),
)
.first,
);
expect(find.text('Retry saved connection'), findsOneWidget);
await tester.tap(find.text('Mail'));
await tester.pumpAndSettle();
expect(find.text('b.example mail'), findsOneWidget, reason: 'previous archive reopened');
await tester.runAsync(() async {
final saved = await store.read();
expect(saved?.server, second);
Expand Down
26 changes: 20 additions & 6 deletions test/demo_session_test.dart
Original file line number Diff line number Diff line change
Expand Up @@ -179,18 +179,32 @@ void main() {
expect(session.account!.id, '2');
expect(session.messages, isNotEmpty);
await session.applyFilters(const SearchFilters(direction: 'outgoing'));
session.exitDemo();

expect(store.calls, isEmpty, reason: 'no secure-storage call');
expect(store.calls, isEmpty, reason: 'the demo makes no secure-storage call');
expect(await savedRaw(), before);
expect(session.setup, isTrue);
await session.exitDemo();

// The archive open when the demo started is reopened from its saved
// details; nothing new is added.
expect(store.calls, isNot(contains('add')));
expect(session.demo, isFalse);
expect(session.api, isNull);
expect(session.setup, isFalse);
expect(session.api, isNotNull);
expect(session.api!.server.host, 'archive.example.com');
expect(session.hasSavedConnection, isTrue);
expect(session.server.text, 'https://archive.example.com');
await expectLater(demos.single.accounts(), throwsA(isA<StateError>()));
});

test('exiting a demo started from setup with nothing open stays on setup',
() async {
FlutterSecureStorage.setMockInitialValues({'connection': savedJson});
await session.startDemo();
await session.exitDemo();
expect(store.calls, isEmpty, reason: 'nothing reopened or contacted');
expect(session.demo, isFalse);
expect(session.setup, isTrue);
expect(session.api, isNull);
});

test('forget during the demo exits without deleting the saved connection',
() async {
FlutterSecureStorage.setMockInitialValues({'connection': savedJson});
Expand Down
Loading