From a0080967a484bf42a23e7e7f730cbb171059c603 Mon Sep 17 00:00:00 2001
From: Andreas Stefl <stefl.andreas@gmail.com>
Date: Fri, 21 Aug 2026 17:04:41 +0200
Subject: [PATCH 1/3] Open what the core can read, and say when it cannot

A zip file opens and lists what is inside, and tapping an entry shows it.
Photos and text files the reader used to refuse open too.

The reader now asks the core what it can read rather than keeping a list of
its own, which had gone out of date. A file that will not open says so, and
offers to write to us when something went wrong on our side. Music and films
are no longer offered.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AHynmW7Vk9bXvUFxLkwu6W
---
 CHANGELOG.md                                  |  13 +
 OpenDocumentReader/Constants.swift            |   4 +
 OpenDocumentReader/CoreWrapper.swift          |  41 ++-
 OpenDocumentReader/Document.swift             |   4 +
 .../DocumentViewController.swift              | 290 ++++++++++++++----
 .../ca.lproj/Localizable.strings              |  12 +
 .../cs.lproj/Localizable.strings              |  12 +
 .../da.lproj/Localizable.strings              |  12 +
 .../de.lproj/Localizable.strings              |  12 +
 .../en.lproj/Localizable.strings              |  12 +
 .../es.lproj/Localizable.strings              |  12 +
 .../fr.lproj/Localizable.strings              |  12 +
 .../ga.lproj/Localizable.strings              |  12 +
 .../it.lproj/Localizable.strings              |  12 +
 .../ja.lproj/Localizable.strings              |  12 +
 .../pl.lproj/Localizable.strings              |  12 +
 .../pt-BR.lproj/Localizable.strings           |  12 +
 .../ru.lproj/Localizable.strings              |  12 +
 .../sl.lproj/Localizable.strings              |  12 +
 .../tr.lproj/Localizable.strings              |  12 +
 .../zh-Hans.lproj/Localizable.strings         |  12 +
 .../ArchiveDocumentTests.swift                | 263 ++++++++++++++++
 .../FailedToOpenTests.swift                   |  91 ++++++
 .../LockedDocumentTests.swift                 |  40 ++-
 .../OpenDocumentReaderTests.swift             |  34 +-
 OpenDocumentReaderTests/test.epub             | Bin 0 -> 369 bytes
 OpenDocumentReaderTests/test.pages            | Bin 0 -> 369 bytes
 OpenDocumentReaderTests/test.zip              | Bin 0 -> 369 bytes
 configs/full/Info.plist                       |   4 +-
 configs/lite/Info.plist                       |   4 +-
 scripts/make-test-fixtures.py                 |  15 +
 31 files changed, 906 insertions(+), 89 deletions(-)
 create mode 100644 OpenDocumentReaderTests/ArchiveDocumentTests.swift
 create mode 100644 OpenDocumentReaderTests/FailedToOpenTests.swift
 create mode 100644 OpenDocumentReaderTests/test.epub
 create mode 100644 OpenDocumentReaderTests/test.pages
 create mode 100644 OpenDocumentReaderTests/test.zip

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5909337..aa2a167 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,19 @@ open: **a second build under the same version goes under the already cut
 heading, not back under `Unreleased`.** Date the heading and add its compare link
 once the version tag exists.
 
+## [Unreleased]
+
+### Added
+
+- A zip file opens and lists what is inside. Tapping an entry shows it.
+- Photos and text files the reader used to refuse now open.
+
+### Changed
+
+- A file that will not open says so, and offers to write to us when something
+  went wrong on our side.
+- The app no longer offers itself for music and films.
+
 ## [1.42]
 
 ### Added
diff --git a/OpenDocumentReader/Constants.swift b/OpenDocumentReader/Constants.swift
index 6a556ce..f0d6364 100644
--- a/OpenDocumentReader/Constants.swift
+++ b/OpenDocumentReader/Constants.swift
@@ -12,6 +12,10 @@ enum Constants {
     /// Which of the house ad's rotations comes next.
     static let key_house_ad_index = "houseAdIndex"
 
+    /// Where a reader writes to when a file will not open. The same address the
+    /// message names, and the one OpenDocument.droid uses.
+    static let supportEmail = "support@opendocument.app"
+
     /// ODR Pro on the App Store. This is the *paid* app: on iOS that is `at.tomtasche.reader`,
     /// while on Android the same bundle id names the free one.
     static let proAppStoreId = 1_452_061_743
diff --git a/OpenDocumentReader/CoreWrapper.swift b/OpenDocumentReader/CoreWrapper.swift
index f59f59a..fb34ac5 100644
--- a/OpenDocumentReader/CoreWrapper.swift
+++ b/OpenDocumentReader/CoreWrapper.swift
@@ -77,14 +77,15 @@ private func selectViews(_ views: [HtmlView], _ documentType: DocumentType) -> [
     }
 }
 
-/// A csv is a *text* file to odrcore that also loads as a spreadsheet, so it
-/// answers `isDocumentFile` with false and `asDocumentFile()` fails on it.
-private func isCsv(_ file: DecodedFile) -> Bool { file.fileType == .commaSeparatedValues }
-
 @objc final class CoreWrapper: NSObject {
     @objc private(set) var pageNames: [String] = []
     @objc private(set) var pageURLs: [URL] = []
 
+    /// Whether odrcore saw only a container and the page is a listing of what is
+    /// inside it. The reader asks because the system may know the same file as a
+    /// document of its own — see `systemKnowsItAsADocument`.
+    @objc private(set) var isArchive = false
+
     /// Whether `backTranslate` has a document to apply an edit to. Only a
     /// document that said it takes one is kept, so having it *is* the answer.
     @objc var isEditable: Bool { lock.withLock { document != nil } }
@@ -105,6 +106,7 @@ private func isCsv(_ file: DecodedFile) -> Bool { file.fileType == .commaSeparat
         pageNames = []
         pageURLs = []
         document = nil
+        isArchive = false
 
         let fileTypes = (try? DecodedFile.listFileTypes(path: inputPath)) ?? []
         guard !fileTypes.isEmpty else {
@@ -126,11 +128,22 @@ private func isCsv(_ file: DecodedFile) -> Bool { file.fileType == .commaSeparat
             }
         }
 
-        // odrcore also translates images, media and fonts, but only into an
-        // `<img>` or a `<video>` the web view decodes anyway. Those go to the
-        // system instead, through the fallback in `DocumentViewController`.
-        guard file.isDocumentFile || file.isPdfFile || isCsv(file) else {
-            throw coreWrapperError(.unsupportedFileType, "not a document, a pdf or a csv")
+        // odrcore's own answer, rather than a list of formats kept here: a
+        // document, a pdf, a csv, a plain zip, a picture, a sound and a font
+        // all come back as a page it wrote. Whatever it learns to read next is
+        // read without a change on this side, and what it cannot read is the
+        // one message the reader shows.
+        guard Odr.capabilities(fileType: file.fileType).translateHtml else {
+            throw coreWrapperError(.unsupportedFileType, "odrcore does not render this file type")
+        }
+
+        // A file odrcore recognises as nothing else it calls text, so a database
+        // or a program would otherwise be shown as a page of nonsense. Its own
+        // answer for that is the charset: unnamed means the bytes are not text.
+        // The same check OpenDocument.droid makes, and to be made once in
+        // odrcore instead - opendocument-app/OpenDocument.core#728.
+        if file.isTextFile, (try? file.asTextFile())?.charset == nil {
+            throw coreWrapperError(.unsupportedFileType, "odrcore could not name a charset")
         }
 
         // the same answers OpenDocument.droid gives odrcore, so a document is
@@ -170,10 +183,11 @@ private func isCsv(_ file: DecodedFile) -> Bool { file.fileType == .commaSeparat
             service = try HtmlTranslator.translate(
                 document: document, cachePath: cachePath, config: config)
         } else {
-            // a csv and a pdf have no document behind them to open or to edit.
-            // `.unknown` keeps the combined view for both; not `.spreadsheet`,
-            // though a csv is one, because that asks for a tab per sheet and a
-            // csv's single sheet is called "csv"
+            // everything that is not a document has no document behind it to
+            // open or to edit: a pdf, a csv, a zip, a picture, a sound, a font.
+            // `.unknown` keeps the one view each of them has; not
+            // `.spreadsheet`, though a csv is one, because that asks for a tab
+            // per sheet and a csv's single sheet is called "csv"
             documentType = .unknown
             openedDocument = nil
             service = try HtmlTranslator.translate(
@@ -193,6 +207,7 @@ private func isCsv(_ file: DecodedFile) -> Bool { file.fileType == .commaSeparat
         // a document whose pages were never served
         self.document = openedDocument
 
+        isArchive = file.isArchiveFile
         pageNames = views.map(\.name)
         pageURLs = views.map { base.appendingPathComponent($0.path) }
     }
diff --git a/OpenDocumentReader/Document.swift b/OpenDocumentReader/Document.swift
index ad5eaf6..912f1b7 100644
--- a/OpenDocumentReader/Document.swift
+++ b/OpenDocumentReader/Document.swift
@@ -48,6 +48,8 @@ class Document: UIDocument {
     public var webview: WKWebView?
 
     public var isOdf = false
+    /// Whether the page is a listing of an archive - see `CoreWrapper.isArchive`.
+    public var isArchive = false
     /// Whether the menu should offer to edit this one - see `CoreWrapper.isEditable`.
     public var isEditable = false
     private var wasPageCountAnnounced = false
@@ -62,6 +64,7 @@ class Document: UIDocument {
         loadProgress.completedUnitCount = 2
 
         isOdf = false
+        isArchive = false
         isEditable = false
         result = nil
         pageURLs = nil
@@ -91,6 +94,7 @@ class Document: UIDocument {
         }
 
         isOdf = true
+        isArchive = coreWrapper.isArchive
         isEditable = coreWrapper.isEditable
 
         loadProgress.completedUnitCount = loadProgress.totalUnitCount
diff --git a/OpenDocumentReader/DocumentViewController.swift b/OpenDocumentReader/DocumentViewController.swift
index f76fa3b..159b52e 100644
--- a/OpenDocumentReader/DocumentViewController.swift
+++ b/OpenDocumentReader/DocumentViewController.swift
@@ -8,11 +8,12 @@ A view controller for displaying and editing documents.
 import StoreKit
 import UIKit
 import UIKit.UIPrinter
+import UniformTypeIdentifiers
 import WebKit
 
 // taken from: https://developer.apple.com/documentation/uikit/view_controllers/building_a_document_browser-based_app
 class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDelegate,
-    SKStoreProductViewControllerDelegate, WKNavigationDelegate
+    SKStoreProductViewControllerDelegate, WKNavigationDelegate, WKUIDelegate
 {
 
     private var browserTransition: DocumentBrowserTransitioningDelegate?
@@ -35,16 +36,6 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
         }
     }
 
-    /// The fallback for what odrcore does not render: what WKWebView and the
-    /// system decoders can show on their own. Not derived from odrcore's format
-    /// table — this is the other side of it.
-    private let systemRenderedExtensions = [
-        "pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx", "rtf", "rtfd.zip", "csv", "txt", "jpg", "jpeg", "png",
-        "gif", "svg", "pages", "pages.zip", "numbers", "numbers.zip", "key", "key.zip", "mp3", "mp4", "flv", "mkv",
-        "3gp", "aac", "bmp", "css", "htm", "html", "js", "json", "mpeg", "oga", "ogv", "sh", "tif", "tiff", "weba",
-        "webm", "webp", "xhtml", "xml",
-    ]
-
     @IBOutlet weak var toolBar: UIToolbar!
     @IBOutlet weak var searchBar: UISearchBar!
     @IBOutlet weak var pageTabBar: PageTabBar!
@@ -215,6 +206,11 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
         // would fight the first
         pageTabBar.addTarget(self, action: #selector(pageSelected(sender:)), for: .valueChanged)
         webview.navigationDelegate = self
+        webview.uiDelegate = self
+        // the way back out of a file opened from a zip's listing. There is
+        // nothing to go back to until something has been opened, so it changes
+        // nothing for a document that is only read.
+        webview.allowsBackForwardNavigationGestures = true
 
         searchBar.delegate = self
         searchBar.showsCancelButton = true
@@ -252,6 +248,25 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
         ])
     }
 
+    /// odrcore writes every link with `target="_blank"`, so opening a file from
+    /// a zip's listing asks for a window this app has none of. It is shown in
+    /// the web view that asked instead, and the swipe back leads to the listing.
+    ///
+    /// Only what odrcore serves: a link out of a document leads to the web, and
+    /// this reader is not a browser.
+    func webView(
+        _ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration,
+        for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures
+    ) -> WKWebView? {
+        guard let url = navigationAction.request.url, CoreWrapper.isServedURL(url) else {
+            return nil
+        }
+
+        webView.load(navigationAction.request)
+
+        return nil
+    }
+
     /// odrcore renders a page only once this web view asks for it, so a document
     /// that falls over halfway through translating falls over here rather than
     /// in `translate`. Only the main frame counts: a link in the document
@@ -260,11 +275,38 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
         _ webView: WKWebView, decidePolicyFor navigationResponse: WKNavigationResponse,
         decisionHandler: @escaping (WKNavigationResponsePolicy) -> Void
     ) {
-        guard navigationResponse.isForMainFrame,
-            let response = navigationResponse.response as? HTTPURLResponse,
+        guard navigationResponse.isForMainFrame, let doc = document else {
+            decisionHandler(.allow)
+
+            return
+        }
+
+        // The web view's own answer about what it can draw, asked instead of
+        // guessed from the file's name.
+        if !navigationResponse.canShowMIMEType {
+            decisionHandler(.cancel)
+
+            // the system could not draw the document after all, so odrcore's
+            // listing of what is inside it is the better of the two
+            if let listing = listingInReserve {
+                listingInReserve = nil
+
+                installFitToWidth(for: listing)
+                documentNavigation = webview.load(URLRequest(url: listing))
+
+                return
+            }
+
+            giveUp(on: doc, with: .unsupported, code: 0)
+
+            return
+        }
+
+        listingInReserve = nil
+
+        guard let response = navigationResponse.response as? HTTPURLResponse,
             response.statusCode >= 400,
-            let url = response.url, CoreWrapper.isServedURL(url),
-            let doc = document
+            let url = response.url, CoreWrapper.isServedURL(url)
         else {
             decisionHandler(.allow)
 
@@ -273,8 +315,45 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
 
         decisionHandler(.cancel)
 
-        // the fallback loads a file or an HTML string, so this cannot recurse
-        documentLoadingError(doc, error: DocumentError.pageNotServed)
+        giveUp(on: doc, with: .broken, code: response.statusCode)
+    }
+
+    /// The page never arrived — the socket went away, or the web view could make
+    /// nothing of what it was given. Same end as a document that would not
+    /// translate.
+    ///
+    /// Only what odrcore serves: a link out of a document that fails is the
+    /// web's problem, not this document's.
+    func webView(_ webView: WKWebView, didFail navigation: WKNavigation!, withError error: Error) {
+        pageFailed(error)
+    }
+
+    func webView(
+        _ webView: WKWebView, didFailProvisionalNavigation navigation: WKNavigation!, withError error: Error
+    ) {
+        pageFailed(error)
+    }
+
+    private func pageFailed(_ error: Error) {
+        guard let doc = document, let url = webview.url, CoreWrapper.isServedURL(url) else { return }
+        guard !isOurOwnDoing(error) else { return }
+
+        CrashManager.shared.log(error)
+
+        giveUp(on: doc, with: .broken, code: (error as NSError).code)
+    }
+
+    /// Whether the reader stopped this load itself. Turning a page cancels the
+    /// one before it, and answering a response with `.cancel` — which is how the
+    /// listing takes over from a document the system could not draw — is
+    /// reported here as a failure too.
+    private func isOurOwnDoing(_ error: Error) -> Bool {
+        let error = error as NSError
+
+        if error.domain == NSURLErrorDomain, error.code == NSURLErrorCancelled { return true }
+
+        // WebKitErrorFrameLoadInterruptedByPolicyChange, which has no constant
+        return error.domain == "WebKitErrorDomain" && error.code == 102
     }
 
     func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
@@ -666,11 +745,11 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
 
     /// Also reached through viewDidDisappear, so the document is dropped rather
     /// than closed a second time on the way out.
-    func closeCurrentDocument() {
+    func closeCurrentDocument(then finish: (() -> Void)? = nil) {
         document?.close()
         document = nil
 
-        self.dismiss(animated: true, completion: nil)
+        self.dismiss(animated: true, completion: finish)
     }
 
     @IBAction func showMenu(_ sender: Any) {
@@ -803,17 +882,41 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
             return
         }
 
-        installFitToWidth(for: url)
+        // odrcore saw only a container, but the system knows this file as a
+        // document of its own - an iWork one, which it draws properly and
+        // odrcore has no reader for. The listing of the parts inside is what
+        // the reader falls back to if the system cannot draw it after all.
+        //
+        // Nothing here names a format, and the day odrcore reads iWork the
+        // file stops being an archive to it and this stops firing.
+        if doc.isArchive, systemKnowsItAsADocument(doc.fileURL) {
+            listingInReserve = url
 
-        // pages come off the loopback server; a file URL needs read access
-        // granted along with it
-        if url.isFileURL {
-            documentNavigation = self.webview.loadFileURL(url, allowingReadAccessTo: url)
-        } else {
-            documentNavigation = self.webview.load(URLRequest(url: url))
+            canEdit = false
+            canSearch = false
+            documentNavigation = webview.loadFileURL(doc.fileURL, allowingReadAccessTo: doc.fileURL)
+
+            return
         }
+
+        installFitToWidth(for: url)
+
+        documentNavigation = self.webview.load(URLRequest(url: url))
     }
 
+    /// Whether the system has a type of its own for this file that says it is a
+    /// document rather than just a container. A `.pages` is composite content; a
+    /// `.zip` and a `.jar` are not.
+    private func systemKnowsItAsADocument(_ url: URL) -> Bool {
+        guard let type = UTType(filenameExtension: url.pathExtension) else { return false }
+
+        return !type.isDynamic && type.conforms(to: .compositeContent)
+    }
+
+    /// odrcore's listing of an archive, held back while the system is given the
+    /// first go at the same file.
+    private var listingInReserve: URL?
+
     func documentEncrypted(_ doc: Document) {
         // the document is opened before this controller is presented, so the
         // first attempt has nothing to present the prompt on
@@ -848,51 +951,58 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
     }
 
     func documentLoadingError(_ doc: Document, error: Error) {
-        progressBar.isHidden = true
-
-        // attention: wrong for extensions like ".pages.zip"
-        let fileType = doc.fileURL.pathExtension.lowercased()
-
-        // no password opens one of these, so asking for one would only ask
-        // again, and the web view makes nothing of a locked file either
-        let isLocked =
-            (error as NSError).domain == CoreWrapperErrorDomain
-            && (error as NSError).code == CoreWrapperError.undecryptable.rawValue
-
-        let fileName = doc.fileURL.absoluteString.lowercased()
-        if !isLocked, systemRenderedExtensions.contains(where: fileName.hasSuffix) {
-            // not odrcore's to render, but the web view knows the format
-            documentNavigation = self.webview.loadFileURL(doc.fileURL, allowingReadAccessTo: doc.fileURL)
-
-            canEdit = false
-            canSearch = false
+        let code = (error as NSError).code
+        let isFromCore = (error as NSError).domain == CoreWrapperErrorDomain
+
+        // The three ways a file does not open, and each has its own thing to
+        // say. Only the last is worth a mail to us.
+        let outcome: FailedToOpen
+        switch (isFromCore, code) {
+        case (true, CoreWrapperError.unsupportedFileType.rawValue):
+            outcome = .unsupported
+        case (true, CoreWrapperError.undecryptable.rawValue):
+            // no password opens one of these, so asking for one would only ask again
+            outcome = .locked
+        default:
+            outcome = .broken
+        }
 
-            AnalyticsManager.shared.report(
-                "load_success",
-                parameters: [
-                    AnalyticsConstants.paramItemName: doc.shortenedDocumentUrl,
-                    AnalyticsConstants.paramContentType: fileType,
-                ])
+        giveUp(on: doc, with: outcome, code: code)
+    }
 
-            return
-        }
+    /// Nothing left to try with this file, so stop showing it: the document
+    /// browser is a better answer than a page that will not appear, and the
+    /// message comes up over it — the same way OpenDocument.droid ends here.
+    ///
+    /// Runs once. A page that fails after the document was already given up on
+    /// would otherwise dismiss a reader that has gone.
+    private func giveUp(on doc: Document, with outcome: FailedToOpen, code: Int) {
+        guard !hasGivenUp else { return }
+        hasGivenUp = true
 
+        progressBar.isHidden = true
         documentNavigation = nil
-        loadMessage(
-            "<h1>\(NSLocalizedString("error", comment: ""))</h1>"
-                + NSLocalizedString(
-                    isLocked ? "toast_error_password_protected" : "toast_error_generic", comment: "")
-        )
 
         AnalyticsManager.shared.report(
             "load_error",
             parameters: [
-                "code": (error as NSError).code,
+                "code": code,
                 AnalyticsConstants.paramItemName: doc.shortenedDocumentUrl,
-                AnalyticsConstants.paramContentType: fileType,
+                // attention: wrong for extensions like ".pages.zip"
+                AnalyticsConstants.paramContentType: doc.fileURL.pathExtension.lowercased(),
             ])
+
+        // taken before the dismiss, which is what takes this controller off it
+        let host = presentingViewController
+
+        closeCurrentDocument {
+            (host ?? self).presentFailure(outcome)
+        }
     }
 
+    /// Whether this document has already ended in a message.
+    private var hasGivenUp = false
+
     func documentLoadingStarted(_ doc: Document) {
         progressBar.isHidden = false
         progressBar.observedProgress = doc.loadProgress
@@ -936,3 +1046,65 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
         pageTabBarHeight.constant = pageTabBar.isHidden ? 0 : pageTabBar.preferredHeight
     }
 }
+
+/// What to say about a file that did not open.
+enum FailedToOpen {
+    /// odrcore does not read this format at all.
+    case unsupported
+    /// A legacy Word, Excel or PowerPoint file no password opens.
+    case locked
+    /// odrcore took it and it still did not appear. This one asks to hear about it.
+    case broken
+
+    var message: String {
+        switch self {
+        case .unsupported: return NSLocalizedString("toast_error_illegal_file_reopen", comment: "")
+        case .locked: return NSLocalizedString("toast_error_password_protected", comment: "")
+        case .broken: return NSLocalizedString("dialog_broken_file", comment: "")
+        }
+    }
+
+    /// Only a file odrcore accepted and then could not show is ours to hear about.
+    var offersContact: Bool { self == .broken }
+}
+
+extension UIViewController {
+
+    /// Says why a file did not open, and for the one case that is ours offers
+    /// the way to tell us. Shown over the document browser rather than over the
+    /// reader, which is gone by now.
+    func presentFailure(_ outcome: FailedToOpen) {
+        let alert = UIAlertController(
+            title: NSLocalizedString("dialog_broken_file_title", comment: ""),
+            message: outcome.message,
+            preferredStyle: .alert)
+
+        if outcome.offersContact {
+            alert.addAction(
+                UIAlertAction(
+                    title: NSLocalizedString("action_contact", comment: ""), style: .default,
+                    handler: { _ in Self.contactSupport() }))
+        }
+
+        alert.addAction(UIAlertAction(title: NSLocalizedString("ok", comment: ""), style: .cancel))
+
+        present(alert, animated: true)
+
+        AnalyticsManager.shared.report("contact_offer")
+    }
+
+    /// A mail to us. Nothing more to say where there is no mail app: the
+    /// address is in the message either way.
+    private static func contactSupport() {
+        AnalyticsManager.shared.report("contact_tapped")
+
+        var mail = URLComponents()
+        mail.scheme = "mailto"
+        mail.path = Constants.supportEmail
+        mail.queryItems = [URLQueryItem(name: "subject", value: "OpenDocument Reader")]
+
+        guard let url = mail.url else { return }
+
+        UIApplication.shared.open(url)
+    }
+}
diff --git a/OpenDocumentReader/ca.lproj/Localizable.strings b/OpenDocumentReader/ca.lproj/Localizable.strings
index c38ada2..63fa9ad 100644
--- a/OpenDocumentReader/ca.lproj/Localizable.strings
+++ b/OpenDocumentReader/ca.lproj/Localizable.strings
@@ -94,3 +94,15 @@
 /* Buttons on the house ad */
 "house_ad_cta_go_pro" = "Passa a Pro";
 "house_ad_cta_get_pro" = "Obtén Pro";
+
+/* The title of the alert shown when a file will not open */
+"dialog_broken_file_title" = "No s'ha pogut obrir aquest fitxer";
+
+/* Its message. The address is the one users write to */
+"dialog_broken_file" = "És possible que el fitxer estigui malmès o que hi hagi hagut un problema per part nostra. Si creieu que el fitxer és correcte, escriviu-nos a support@opendocument.app";
+
+/* Opens a mail to support */
+"action_contact" = "Contacta";
+
+/* Shown for a format odrcore does not read */
+"toast_error_illegal_file_reopen" = "Format de fitxer no compatible. Proveu d'obrir-lo amb una altra aplicació.";
diff --git a/OpenDocumentReader/cs.lproj/Localizable.strings b/OpenDocumentReader/cs.lproj/Localizable.strings
index d6f414f..c38a519 100644
--- a/OpenDocumentReader/cs.lproj/Localizable.strings
+++ b/OpenDocumentReader/cs.lproj/Localizable.strings
@@ -94,3 +94,15 @@
 /* Buttons on the house ad */
 "house_ad_cta_go_pro" = "Přejít na Pro";
 "house_ad_cta_get_pro" = "Pořídit Pro";
+
+/* The title of the alert shown when a file will not open */
+"dialog_broken_file_title" = "Soubor se nepodařilo otevřít";
+
+/* Its message. The address is the one users write to */
+"dialog_broken_file" = "Soubor může být poškozený, nebo se něco pokazilo na naší straně. Pokud si myslíte, že je soubor v pořádku, napište nám na support@opendocument.app";
+
+/* Opens a mail to support */
+"action_contact" = "Kontakt";
+
+/* Shown for a format odrcore does not read */
+"toast_error_illegal_file_reopen" = "Nepodporovaný formát souboru. Zkuste jej otevřít v jiné aplikaci.";
diff --git a/OpenDocumentReader/da.lproj/Localizable.strings b/OpenDocumentReader/da.lproj/Localizable.strings
index ceab4c2..52dd76c 100644
--- a/OpenDocumentReader/da.lproj/Localizable.strings
+++ b/OpenDocumentReader/da.lproj/Localizable.strings
@@ -94,3 +94,15 @@
 /* Buttons on the house ad */
 "house_ad_cta_go_pro" = "Skift til Pro";
 "house_ad_cta_get_pro" = "Få Pro";
+
+/* The title of the alert shown when a file will not open */
+"dialog_broken_file_title" = "Kunne ikke åbne filen";
+
+/* Its message. The address is the one users write to */
+"dialog_broken_file" = "Filen er måske beskadiget, eller noget gik galt hos os. Hvis du mener, at filen er i orden, så skriv til os på support@opendocument.app";
+
+/* Opens a mail to support */
+"action_contact" = "Kontakt";
+
+/* Shown for a format odrcore does not read */
+"toast_error_illegal_file_reopen" = "Filformatet understøttes ikke. Prøv at åbne filen i en anden app.";
diff --git a/OpenDocumentReader/de.lproj/Localizable.strings b/OpenDocumentReader/de.lproj/Localizable.strings
index 9b761ae..983a200 100644
--- a/OpenDocumentReader/de.lproj/Localizable.strings
+++ b/OpenDocumentReader/de.lproj/Localizable.strings
@@ -94,3 +94,15 @@
 /* Buttons on the house ad */
 "house_ad_cta_go_pro" = "Pro holen";
 "house_ad_cta_get_pro" = "Pro kaufen";
+
+/* The title of the alert shown when a file will not open */
+"dialog_broken_file_title" = "Datei konnte nicht geöffnet werden";
+
+/* Its message. The address is the one users write to */
+"dialog_broken_file" = "Die Datei ist möglicherweise beschädigt, oder bei uns ist etwas schiefgelaufen. Wenn Sie glauben, dass die Datei in Ordnung ist, schreiben Sie uns an support@opendocument.app";
+
+/* Opens a mail to support */
+"action_contact" = "Kontakt";
+
+/* Shown for a format odrcore does not read */
+"toast_error_illegal_file_reopen" = "Dateiformat wird nicht unterstützt. Versuchen Sie, die Datei in einer anderen App zu öffnen.";
diff --git a/OpenDocumentReader/en.lproj/Localizable.strings b/OpenDocumentReader/en.lproj/Localizable.strings
index d92dd6c..37636ca 100644
--- a/OpenDocumentReader/en.lproj/Localizable.strings
+++ b/OpenDocumentReader/en.lproj/Localizable.strings
@@ -94,3 +94,15 @@
 /* Buttons on the house ad */
 "house_ad_cta_go_pro" = "Go Pro";
 "house_ad_cta_get_pro" = "Get Pro";
+
+/* The title of the alert shown when a file will not open */
+"dialog_broken_file_title" = "Couldn't open this file";
+
+/* Its message. The address is the one users write to */
+"dialog_broken_file" = "The file may be damaged, or something went wrong on our side. If you think the file is fine, tell us at support@opendocument.app";
+
+/* Opens a mail to support */
+"action_contact" = "Contact";
+
+/* Shown for a format odrcore does not read */
+"toast_error_illegal_file_reopen" = "Unsupported file format. Try opening it in another app.";
diff --git a/OpenDocumentReader/es.lproj/Localizable.strings b/OpenDocumentReader/es.lproj/Localizable.strings
index ffc86ba..923e046 100644
--- a/OpenDocumentReader/es.lproj/Localizable.strings
+++ b/OpenDocumentReader/es.lproj/Localizable.strings
@@ -94,3 +94,15 @@
 /* Buttons on the house ad */
 "house_ad_cta_go_pro" = "Hágase Pro";
 "house_ad_cta_get_pro" = "Obtener Pro";
+
+/* The title of the alert shown when a file will not open */
+"dialog_broken_file_title" = "No se ha podido abrir este archivo";
+
+/* Its message. The address is the one users write to */
+"dialog_broken_file" = "Puede que el archivo esté dañado o que algo haya fallado por nuestra parte. Si cree que el archivo está bien, escríbanos a support@opendocument.app";
+
+/* Opens a mail to support */
+"action_contact" = "Contacto";
+
+/* Shown for a format odrcore does not read */
+"toast_error_illegal_file_reopen" = "Formato de archivo no compatible. Pruebe a abrirlo en otra aplicación.";
diff --git a/OpenDocumentReader/fr.lproj/Localizable.strings b/OpenDocumentReader/fr.lproj/Localizable.strings
index 42e0b2e..9018f7d 100644
--- a/OpenDocumentReader/fr.lproj/Localizable.strings
+++ b/OpenDocumentReader/fr.lproj/Localizable.strings
@@ -94,3 +94,15 @@
 /* Buttons on the house ad */
 "house_ad_cta_go_pro" = "Passer à Pro";
 "house_ad_cta_get_pro" = "Obtenir Pro";
+
+/* The title of the alert shown when a file will not open */
+"dialog_broken_file_title" = "Impossible d'ouvrir ce fichier";
+
+/* Its message. The address is the one users write to */
+"dialog_broken_file" = "Le fichier est peut-être endommagé, ou quelque chose s'est mal passé de notre côté. Si vous pensez que le fichier est intact, écrivez-nous à support@opendocument.app";
+
+/* Opens a mail to support */
+"action_contact" = "Contact";
+
+/* Shown for a format odrcore does not read */
+"toast_error_illegal_file_reopen" = "Le format de ce fichier n'est pas pris en charge. Essayez de l'ouvrir avec une autre application.";
diff --git a/OpenDocumentReader/ga.lproj/Localizable.strings b/OpenDocumentReader/ga.lproj/Localizable.strings
index a8eb994..f60011d 100644
--- a/OpenDocumentReader/ga.lproj/Localizable.strings
+++ b/OpenDocumentReader/ga.lproj/Localizable.strings
@@ -94,3 +94,15 @@
 /* Buttons on the house ad */
 "house_ad_cta_go_pro" = "Faigh Pro";
 "house_ad_cta_get_pro" = "Ceannaigh Pro";
+
+/* The title of the alert shown when a file will not open */
+"dialog_broken_file_title" = "Níorbh fhéidir an comhad seo a oscailt";
+
+/* Its message. The address is the one users write to */
+"dialog_broken_file" = "B'fhéidir go bhfuil an comhad damáistithe, nó gur chlis rud éigin orainne. Má cheapann tú go bhfuil an comhad ceart go leor, cuir scéala chugainn ag support@opendocument.app";
+
+/* Opens a mail to support */
+"action_contact" = "Teagmháil";
+
+/* Shown for a format odrcore does not read */
+"toast_error_illegal_file_reopen" = "Ní thacaítear leis an bhformáid chomhaid seo. Bain triail as an gcomhad a oscailt in aip eile.";
diff --git a/OpenDocumentReader/it.lproj/Localizable.strings b/OpenDocumentReader/it.lproj/Localizable.strings
index 143b024..eadefd5 100644
--- a/OpenDocumentReader/it.lproj/Localizable.strings
+++ b/OpenDocumentReader/it.lproj/Localizable.strings
@@ -94,3 +94,15 @@
 /* Buttons on the house ad */
 "house_ad_cta_go_pro" = "Passa a Pro";
 "house_ad_cta_get_pro" = "Ottieni Pro";
+
+/* The title of the alert shown when a file will not open */
+"dialog_broken_file_title" = "Impossibile aprire questo file";
+
+/* Its message. The address is the one users write to */
+"dialog_broken_file" = "Il file potrebbe essere danneggiato oppure qualcosa è andato storto da parte nostra. Se pensi che il file sia integro, scrivici a support@opendocument.app";
+
+/* Opens a mail to support */
+"action_contact" = "Contattaci";
+
+/* Shown for a format odrcore does not read */
+"toast_error_illegal_file_reopen" = "Formato di file non supportato. Prova ad aprirlo in un'altra app.";
diff --git a/OpenDocumentReader/ja.lproj/Localizable.strings b/OpenDocumentReader/ja.lproj/Localizable.strings
index bcf864b..0fdd582 100644
--- a/OpenDocumentReader/ja.lproj/Localizable.strings
+++ b/OpenDocumentReader/ja.lproj/Localizable.strings
@@ -94,3 +94,15 @@
 /* Buttons on the house ad */
 "house_ad_cta_go_pro" = "Pro にする";
 "house_ad_cta_get_pro" = "Pro を入手";
+
+/* The title of the alert shown when a file will not open */
+"dialog_broken_file_title" = "このファイルを開けませんでした";
+
+/* Its message. The address is the one users write to */
+"dialog_broken_file" = "ファイルが破損しているか、こちら側で問題が起きた可能性があります。ファイルに問題がないと思われる場合は support@opendocument.app までお知らせください";
+
+/* Opens a mail to support */
+"action_contact" = "お問い合わせ";
+
+/* Shown for a format odrcore does not read */
+"toast_error_illegal_file_reopen" = "対応していないファイル形式です。別のアプリで開いてみてください。";
diff --git a/OpenDocumentReader/pl.lproj/Localizable.strings b/OpenDocumentReader/pl.lproj/Localizable.strings
index f46b9a9..d4d543b 100644
--- a/OpenDocumentReader/pl.lproj/Localizable.strings
+++ b/OpenDocumentReader/pl.lproj/Localizable.strings
@@ -94,3 +94,15 @@
 /* Buttons on the house ad */
 "house_ad_cta_go_pro" = "Przejdź na Pro";
 "house_ad_cta_get_pro" = "Kup Pro";
+
+/* The title of the alert shown when a file will not open */
+"dialog_broken_file_title" = "Nie można otworzyć tego pliku";
+
+/* Its message. The address is the one users write to */
+"dialog_broken_file" = "Plik może być uszkodzony lub coś poszło nie tak po naszej stronie. Jeśli uważasz, że plik jest w porządku, napisz do nas na support@opendocument.app";
+
+/* Opens a mail to support */
+"action_contact" = "Kontakt";
+
+/* Shown for a format odrcore does not read */
+"toast_error_illegal_file_reopen" = "Nieobsługiwany format pliku. Spróbuj otworzyć go w innej aplikacji.";
diff --git a/OpenDocumentReader/pt-BR.lproj/Localizable.strings b/OpenDocumentReader/pt-BR.lproj/Localizable.strings
index e8a03a6..64abe51 100644
--- a/OpenDocumentReader/pt-BR.lproj/Localizable.strings
+++ b/OpenDocumentReader/pt-BR.lproj/Localizable.strings
@@ -94,3 +94,15 @@
 /* Buttons on the house ad */
 "house_ad_cta_go_pro" = "Quero o Pro";
 "house_ad_cta_get_pro" = "Obter o Pro";
+
+/* The title of the alert shown when a file will not open */
+"dialog_broken_file_title" = "Não foi possível abrir este arquivo";
+
+/* Its message. The address is the one users write to */
+"dialog_broken_file" = "O arquivo pode estar danificado ou algo deu errado do nosso lado. Se você acha que o arquivo está correto, avise-nos em support@opendocument.app";
+
+/* Opens a mail to support */
+"action_contact" = "Contato";
+
+/* Shown for a format odrcore does not read */
+"toast_error_illegal_file_reopen" = "Formato de arquivo não compatível. Tente abri-lo em outro aplicativo.";
diff --git a/OpenDocumentReader/ru.lproj/Localizable.strings b/OpenDocumentReader/ru.lproj/Localizable.strings
index 34fd3f0..98adb00 100644
--- a/OpenDocumentReader/ru.lproj/Localizable.strings
+++ b/OpenDocumentReader/ru.lproj/Localizable.strings
@@ -94,3 +94,15 @@
 /* Buttons on the house ad */
 "house_ad_cta_go_pro" = "Перейти на Pro";
 "house_ad_cta_get_pro" = "Купить Pro";
+
+/* The title of the alert shown when a file will not open */
+"dialog_broken_file_title" = "Не удалось открыть этот файл";
+
+/* Its message. The address is the one users write to */
+"dialog_broken_file" = "Возможно, файл повреждён или что-то пошло не так с нашей стороны. Если вы считаете, что с файлом всё в порядке, напишите нам на support@opendocument.app";
+
+/* Opens a mail to support */
+"action_contact" = "Связаться";
+
+/* Shown for a format odrcore does not read */
+"toast_error_illegal_file_reopen" = "Формат файла не поддерживается. Попробуйте открыть его в другом приложении.";
diff --git a/OpenDocumentReader/sl.lproj/Localizable.strings b/OpenDocumentReader/sl.lproj/Localizable.strings
index bb727b0..c87614a 100644
--- a/OpenDocumentReader/sl.lproj/Localizable.strings
+++ b/OpenDocumentReader/sl.lproj/Localizable.strings
@@ -94,3 +94,15 @@
 /* Buttons on the house ad */
 "house_ad_cta_go_pro" = "Izberite Pro";
 "house_ad_cta_get_pro" = "Kupite Pro";
+
+/* The title of the alert shown when a file will not open */
+"dialog_broken_file_title" = "Te datoteke ni bilo mogoče odpreti";
+
+/* Its message. The address is the one users write to */
+"dialog_broken_file" = "Datoteka je morda poškodovana ali pa je šlo kaj narobe na naši strani. Če menite, da je datoteka v redu, nam pišite na support@opendocument.app";
+
+/* Opens a mail to support */
+"action_contact" = "Stik z nami";
+
+/* Shown for a format odrcore does not read */
+"toast_error_illegal_file_reopen" = "Nepodprta oblika datoteke. Poskusite jo odpreti v drugi aplikaciji.";
diff --git a/OpenDocumentReader/tr.lproj/Localizable.strings b/OpenDocumentReader/tr.lproj/Localizable.strings
index bb5ab44..f435bc8 100644
--- a/OpenDocumentReader/tr.lproj/Localizable.strings
+++ b/OpenDocumentReader/tr.lproj/Localizable.strings
@@ -94,3 +94,15 @@
 /* Buttons on the house ad */
 "house_ad_cta_go_pro" = "Pro'ya geç";
 "house_ad_cta_get_pro" = "Pro'yu al";
+
+/* The title of the alert shown when a file will not open */
+"dialog_broken_file_title" = "Bu dosya açılamadı";
+
+/* Its message. The address is the one users write to */
+"dialog_broken_file" = "Dosya bozuk olabilir veya bizim tarafımızda bir şeyler ters gitmiş olabilir. Dosyanın sorunsuz olduğunu düşünüyorsanız support@opendocument.app adresinden bize bildirin";
+
+/* Opens a mail to support */
+"action_contact" = "İletişim";
+
+/* Shown for a format odrcore does not read */
+"toast_error_illegal_file_reopen" = "Desteklenmeyen dosya biçimi. Başka bir uygulamada açmayı deneyin.";
diff --git a/OpenDocumentReader/zh-Hans.lproj/Localizable.strings b/OpenDocumentReader/zh-Hans.lproj/Localizable.strings
index 66c5ac0..531720e 100644
--- a/OpenDocumentReader/zh-Hans.lproj/Localizable.strings
+++ b/OpenDocumentReader/zh-Hans.lproj/Localizable.strings
@@ -94,3 +94,15 @@
 /* Buttons on the house ad */
 "house_ad_cta_go_pro" = "升级 Pro";
 "house_ad_cta_get_pro" = "获取 Pro";
+
+/* The title of the alert shown when a file will not open */
+"dialog_broken_file_title" = "无法打开此文件";
+
+/* Its message. The address is the one users write to */
+"dialog_broken_file" = "文件可能已损坏，也可能是我们这边出了问题。如果您认为文件没有问题，请通过 support@opendocument.app 告诉我们";
+
+/* Opens a mail to support */
+"action_contact" = "联系我们";
+
+/* Shown for a format odrcore does not read */
+"toast_error_illegal_file_reopen" = "不支持的文件格式。请尝试用其他应用打开。";
diff --git a/OpenDocumentReaderTests/ArchiveDocumentTests.swift b/OpenDocumentReaderTests/ArchiveDocumentTests.swift
new file mode 100644
index 0000000..ceb3f2c
--- /dev/null
+++ b/OpenDocumentReaderTests/ArchiveDocumentTests.swift
@@ -0,0 +1,263 @@
+import WebKit
+import XCTest
+
+@testable import OpenDocumentReader
+
+/// The app offers itself for a zip, because that is the type every ODF and
+/// Office file conforms to. One that is only a zip has to open too: odrcore
+/// lists what is inside it, and the listing's links have to lead somewhere.
+class ArchiveDocumentTests: XCTestCase {
+    private let temporaryDirectory = NSTemporaryDirectory()
+    private var documentURL: URL!
+    private var window: UIWindow!
+    private var controller: DocumentViewController!
+    private var document: Document!
+
+    override func setUpWithError() throws {
+        documentURL = try copyFixture()
+    }
+
+    override func tearDown() {
+        window?.isHidden = true
+        window = nil
+        controller = nil
+        document = nil
+    }
+
+    /// Out of the read-only test bundle, and away from the temporary directory
+    /// translating uses for its cache and output.
+    private func copyFixture(ofType pathExtension: String = "zip") throws -> URL {
+        let documentsURL = try FileManager.default.url(
+            for: .documentDirectory, in: .userDomainMask, appropriateFor: nil, create: false)
+
+        let url = documentsURL.appendingPathComponent("test." + pathExtension)
+        try? FileManager.default.removeItem(at: url)
+
+        let bundlePath = try XCTUnwrap(
+            Bundle(for: Self.self).path(forResource: "test", ofType: pathExtension))
+        try FileManager.default.copyItem(at: URL(fileURLWithPath: bundlePath), to: url)
+
+        return url
+    }
+
+    /// One page, the listing, rather than the error a zip used to be.
+    func testAZipTranslatesIntoItsListing() throws {
+        let wrapper = CoreWrapper()
+
+        try wrapper.translate(
+            documentURL.path, cache: temporaryDirectory, into: temporaryDirectory, with: nil, editable: false)
+
+        XCTAssertEqual(wrapper.pageNames, ["files"])
+    }
+
+    /// Nothing in a zip is editable, whatever the file inside it is.
+    func testAZipIsNotEditable() throws {
+        let wrapper = CoreWrapper()
+
+        try wrapper.translate(
+            documentURL.path, cache: temporaryDirectory, into: temporaryDirectory, with: nil, editable: true)
+
+        XCTAssertFalse(wrapper.isEditable)
+    }
+
+    /// The listing names every file in the zip, and its links answer with them.
+    func testTheListingOpensWhatIsInside() throws {
+        let wrapper = CoreWrapper()
+
+        try wrapper.translate(
+            documentURL.path, cache: temporaryDirectory, into: temporaryDirectory, with: nil, editable: false)
+
+        let listingURL = try XCTUnwrap(wrapper.pageURLs.first)
+        let (data, _) = try fetch(listingURL)
+        let html = try XCTUnwrap(String(data: data, encoding: .utf8))
+
+        for name in ["notes.txt", "holiday/photo.jpg", "holiday/second.jpg"] {
+            XCTAssertTrue(html.contains(name), html)
+        }
+
+        for href in hrefs(in: html) {
+            let url = try XCTUnwrap(URL(string: href, relativeTo: listingURL)?.absoluteURL)
+            let (entry, response) = try fetch(url)
+
+            XCTAssertEqual((response as? HTTPURLResponse)?.statusCode, 200, href)
+            XCTAssertFalse(entry.isEmpty, href)
+        }
+    }
+
+    /// End to end: the reader shows the listing, not the message it shows for a
+    /// file it cannot open.
+    func testAZipReachesTheReader() throws {
+        try present(documentURL)
+
+        let opened = expectation(description: "opened")
+        document.open { _ in opened.fulfill() }
+        wait(for: [opened], timeout: 60)
+
+        waitForPage(where: "document.body.innerText.length > 0")
+
+        let shown = try XCTUnwrap(evaluate("document.body.innerText") as? String)
+        XCTAssertTrue(shown.contains("notes.txt"), shown)
+        XCTAssertFalse(shown.contains(NSLocalizedString("toast_error_generic", comment: "")), shown)
+    }
+
+    /// odrcore has no iWork reader, so a `.pages` is a zip to it — but the
+    /// system knows it as a document and draws it properly. It gets the first
+    /// go, and the listing is only what the reader falls back to.
+    func testADocumentTheSystemKnowsIsLeftToTheSystem() throws {
+        try present(try copyFixture(ofType: "pages"))
+
+        let opened = expectation(description: "opened")
+        document.open { _ in opened.fulfill() }
+        wait(for: [opened], timeout: 60)
+
+        let shown = try XCTUnwrap(waitForURL { $0.isFileURL })
+
+        XCTAssertEqual(shown.lastPathComponent, "test.pages")
+        XCTAssertNil(controller.presentedViewController, "it said the file would not open")
+    }
+
+    /// And when the system turns out not to be able to draw it after all, the
+    /// listing takes over rather than a message — an `.epub` is composite
+    /// content to the system, which has no reader for it either.
+    func testAnArchiveTheSystemCannotDrawFallsBackToTheListing() throws {
+        try present(try copyFixture(ofType: "epub"))
+
+        let opened = expectation(description: "opened")
+        document.open { _ in opened.fulfill() }
+        wait(for: [opened], timeout: 60)
+
+        let shown = try XCTUnwrap(waitForURL { CoreWrapper.isServedURL($0) })
+
+        XCTAssertEqual(shown.lastPathComponent, "files.html")
+        XCTAssertNil(controller.presentedViewController, "it said the file would not open")
+    }
+
+    private func waitForURL(_ matches: (URL) -> Bool) -> URL? {
+        let deadline = Date().addingTimeInterval(30)
+
+        while Date() < deadline {
+            if let url = controller.webview.url, matches(url) { return url }
+
+            _ = XCTWaiter.wait(for: [expectation(description: "a turn of the run loop")], timeout: 0.1)
+        }
+
+        return controller.webview.url
+    }
+
+    /// odrcore writes the listing's links with `target="_blank"`, and a web view
+    /// with nobody to answer that drops the tap on the floor.
+    func testFollowingALinkOpensTheFileInTheSameWebView() throws {
+        try present(documentURL)
+
+        let opened = expectation(description: "opened")
+        document.open { _ in opened.fulfill() }
+        wait(for: [opened], timeout: 60)
+
+        waitForPage(where: "document.body.innerText.length > 0")
+
+        let listingURL = controller.webview.url
+        evaluate("document.querySelector('.odr-files-name a').click()")
+
+        waitForPage(where: "true")
+        let deadline = Date().addingTimeInterval(30)
+        while Date() < deadline, controller.webview.url == listingURL {
+            _ = XCTWaiter.wait(for: [expectation(description: "a turn of the run loop")], timeout: 0.1)
+        }
+
+        let reached = try XCTUnwrap(controller.webview.url)
+        XCTAssertNotEqual(reached, listingURL)
+        XCTAssertTrue(CoreWrapper.isServedURL(reached), reached.absoluteString)
+
+        let settled = Date().addingTimeInterval(30)
+        while Date() < settled, !controller.webview.canGoBack {
+            _ = XCTWaiter.wait(for: [expectation(description: "a turn of the run loop")], timeout: 0.1)
+        }
+
+        XCTAssertTrue(controller.webview.canGoBack, "no way back to the listing")
+    }
+
+    // MARK: - helpers
+
+    private func hrefs(in html: String) -> [String] {
+        var found: [String] = []
+        var rest = html[...]
+
+        while let start = rest.range(of: "href=\"") {
+            let tail = rest[start.upperBound...]
+            guard let end = tail.firstIndex(of: "\"") else { break }
+
+            let href = String(tail[..<end])
+            // the download links carry the same targets, and a `data:` one is
+            // not the server's to answer
+            if !href.hasPrefix("data:"), !found.contains(href) {
+                found.append(href)
+            }
+            rest = tail[end...]
+        }
+
+        return found
+    }
+
+    private func fetch(_ url: URL) throws -> (Data, URLResponse) {
+        var result: Result<(Data, URLResponse), Error> = .failure(URLError(.timedOut))
+        let done = expectation(description: "GET \(url)")
+
+        URLSession.shared.dataTask(with: url) { data, response, error in
+            if let data, let response {
+                result = .success((data, response))
+            } else if let error {
+                result = .failure(error)
+            }
+
+            done.fulfill()
+        }.resume()
+
+        wait(for: [done], timeout: 30)
+
+        return try result.get()
+    }
+
+    private func present(_ url: URL) throws {
+        let storyboard = UIStoryboard(name: "Main", bundle: Bundle(for: DocumentViewController.self))
+        controller = try XCTUnwrap(
+            storyboard.instantiateViewController(withIdentifier: "TextDocumentViewController")
+                as? DocumentViewController)
+
+        document = Document(fileURL: url)
+        controller.document = document
+
+        window = UIWindow(frame: CGRect(x: 0, y: 0, width: 390, height: 844))
+        window.rootViewController = controller
+        window.makeKeyAndVisible()
+
+        controller.view.layoutIfNeeded()
+    }
+
+    private func waitForPage(
+        where condition: String, file: StaticString = #filePath, line: UInt = #line
+    ) {
+        let deadline = Date().addingTimeInterval(60)
+
+        while Date() < deadline {
+            if evaluate(condition) as? Bool == true { return }
+
+            _ = XCTWaiter.wait(for: [expectation(description: "a turn of the run loop")], timeout: 0.1)
+        }
+
+        XCTFail("timed out waiting for \(condition)", file: file, line: line)
+    }
+
+    @discardableResult
+    private func evaluate(_ script: String) -> Any? {
+        let done = expectation(description: "evaluated")
+        var result: Any?
+
+        controller.webview.evaluateJavaScript(script) { value, _ in
+            result = value
+            done.fulfill()
+        }
+        wait(for: [done], timeout: 30)
+
+        return result
+    }
+}
diff --git a/OpenDocumentReaderTests/FailedToOpenTests.swift b/OpenDocumentReaderTests/FailedToOpenTests.swift
new file mode 100644
index 0000000..a63ec93
--- /dev/null
+++ b/OpenDocumentReaderTests/FailedToOpenTests.swift
@@ -0,0 +1,91 @@
+import WebKit
+import XCTest
+
+@testable import OpenDocumentReader
+
+/// What the reader says about a file that does not open, and which of those is
+/// worth asking to hear about.
+class FailedToOpenTests: XCTestCase {
+    private let temporaryDirectory = NSTemporaryDirectory()
+    private var window: UIWindow!
+    private var controller: DocumentViewController!
+    private var document: Document!
+
+    override func tearDown() {
+        window?.isHidden = true
+        window = nil
+        controller = nil
+        document = nil
+    }
+
+    /// A format nothing here reads is not ours to hear about; a file odrcore
+    /// took and could not show is.
+    func testOnlyABrokenFileOffersContact() {
+        XCTAssertFalse(FailedToOpen.unsupported.offersContact)
+        XCTAssertFalse(FailedToOpen.locked.offersContact)
+        XCTAssertTrue(FailedToOpen.broken.offersContact)
+
+        XCTAssertEqual(
+            FailedToOpen.broken.message, NSLocalizedString("dialog_broken_file", comment: ""))
+        XCTAssertEqual(
+            FailedToOpen.unsupported.message,
+            NSLocalizedString("toast_error_illegal_file_reopen", comment: ""))
+    }
+
+    /// The address is in the message, so a reader with no mail app still knows
+    /// where to write.
+    func testTheMessageNamesTheAddress() {
+        XCTAssertTrue(
+            FailedToOpen.broken.message.contains(Constants.supportEmail),
+            FailedToOpen.broken.message)
+    }
+
+    /// End to end: no page, and the message says the format is the problem.
+    func testAFileOdrcoreCannotReadEndsInTheMessage() throws {
+        let url = URL(fileURLWithPath: temporaryDirectory).appendingPathComponent("nonsense.odt")
+        // every byte value: text in no encoding, so odrcore has nothing to read
+        try Data((0..<2).flatMap { _ in (0...255).map(UInt8.init) }).write(to: url)
+
+        try present(url)
+
+        let opened = expectation(description: "opened")
+        document.open { _ in opened.fulfill() }
+        wait(for: [opened], timeout: 60)
+
+        let alert = try XCTUnwrap(waitForAlert())
+
+        XCTAssertEqual(alert.title, NSLocalizedString("dialog_broken_file_title", comment: ""))
+        XCTAssertEqual(alert.message, NSLocalizedString("toast_error_illegal_file_reopen", comment: ""))
+        XCTAssertEqual(alert.actions.map(\.title), [NSLocalizedString("ok", comment: "")])
+    }
+
+    // MARK: - helpers
+
+    private func waitForAlert() -> UIAlertController? {
+        let deadline = Date().addingTimeInterval(30)
+
+        while Date() < deadline {
+            if let alert = controller.presentedViewController as? UIAlertController { return alert }
+
+            _ = XCTWaiter.wait(for: [expectation(description: "a turn of the run loop")], timeout: 0.1)
+        }
+
+        return nil
+    }
+
+    private func present(_ url: URL) throws {
+        let storyboard = UIStoryboard(name: "Main", bundle: Bundle(for: DocumentViewController.self))
+        controller = try XCTUnwrap(
+            storyboard.instantiateViewController(withIdentifier: "TextDocumentViewController")
+                as? DocumentViewController)
+
+        document = Document(fileURL: url)
+        controller.document = document
+
+        window = UIWindow(frame: CGRect(x: 0, y: 0, width: 390, height: 844))
+        window.rootViewController = controller
+        window.makeKeyAndVisible()
+
+        controller.view.layoutIfNeeded()
+    }
+}
diff --git a/OpenDocumentReaderTests/LockedDocumentTests.swift b/OpenDocumentReaderTests/LockedDocumentTests.swift
index 62e6ec8..dbe1178 100644
--- a/OpenDocumentReaderTests/LockedDocumentTests.swift
+++ b/OpenDocumentReaderTests/LockedDocumentTests.swift
@@ -57,8 +57,8 @@ class LockedDocumentTests: XCTestCase {
         }
     }
 
-    /// `.doc` is one of the formats the reader otherwise falls back to the web
-    /// view for, so the message has to beat the fallback.
+    /// Its own message rather than the one that asks to hear about a broken
+    /// file: nothing is wrong with it, and no password opens it.
     func testALockedLegacyFileSaysWhyItDidNotOpen() throws {
         try present(documentURL)
 
@@ -66,12 +66,38 @@ class LockedDocumentTests: XCTestCase {
         document.open { _ in opened.fulfill() }
         wait(for: [opened], timeout: 60)
 
-        waitForPage(where: "document.body.innerText.length > 0")
+        let alert = try XCTUnwrap(waitForAlert())
 
-        let shown = try XCTUnwrap(evaluate("document.body.innerText") as? String)
-        XCTAssertTrue(
-            shown.contains(NSLocalizedString("toast_error_password_protected", comment: "")), shown)
-        XCTAssertFalse(controller.webview.url?.isFileURL ?? false, "the file was handed to the web view")
+        XCTAssertEqual(alert.message, NSLocalizedString("toast_error_password_protected", comment: ""))
+        XCTAssertEqual(
+            alert.actions.map(\.title), [NSLocalizedString("ok", comment: "")],
+            "a locked file is not ours to hear about")
+    }
+
+    /// The reader is taken off the screen first, the same way OpenDocument.droid
+    /// drops back to its landing screen.
+    func testTheReaderIsClosedBeforeTheMessage() throws {
+        try present(documentURL)
+
+        let opened = expectation(description: "opened")
+        document.open { _ in opened.fulfill() }
+        wait(for: [opened], timeout: 60)
+
+        _ = waitForAlert()
+
+        XCTAssertNil(controller.document, "the reader is still holding the document")
+    }
+
+    private func waitForAlert() -> UIAlertController? {
+        let deadline = Date().addingTimeInterval(30)
+
+        while Date() < deadline {
+            if let alert = controller.presentedViewController as? UIAlertController { return alert }
+
+            _ = XCTWaiter.wait(for: [expectation(description: "a turn of the run loop")], timeout: 0.1)
+        }
+
+        return nil
     }
 
     // MARK: - helpers
diff --git a/OpenDocumentReaderTests/OpenDocumentReaderTests.swift b/OpenDocumentReaderTests/OpenDocumentReaderTests.swift
index fe6748d..f18375f 100644
--- a/OpenDocumentReaderTests/OpenDocumentReaderTests.swift
+++ b/OpenDocumentReaderTests/OpenDocumentReaderTests.swift
@@ -159,18 +159,18 @@ class OpenDocumentReaderTests: XCTestCase {
     }
 
     /// A png is one of the formats odrcore translates but we leave to the system.
-    func testImageIsLeftToTheSystem() throws {
+    /// odrcore renders a picture too, so the reader no longer keeps a list of
+    /// what to hand to the web view instead.
+    func testImageIsTranslated() throws {
         let wrapper = CoreWrapper()
 
         let image = URL(fileURLWithPath: temporaryDirectory).appendingPathComponent("test.png")
         try Data([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]).write(to: image)
 
-        XCTAssertThrowsError(
-            try wrapper.translate(
-                image.path, cache: temporaryDirectory, into: temporaryDirectory, with: nil, editable: false)
-        ) { error in
-            XCTAssertEqual((error as NSError).code, CoreWrapperError.unsupportedFileType.rawValue)
-        }
+        try wrapper.translate(
+            image.path, cache: temporaryDirectory, into: temporaryDirectory, with: nil, editable: false)
+
+        XCTAssertEqual(wrapper.pageNames, ["image"])
     }
 
     /// And it has no document behind it, so the menu must not offer to edit one.
@@ -361,12 +361,17 @@ class OpenDocumentReaderTests: XCTestCase {
         }
     }
 
+    /// The one thing the reader still decides for itself: odrcore recognising
+    /// nothing at all is the message, not a page.
     func testUnsupportedFileTypeReportsTypedError() throws {
         let wrapper = CoreWrapper()
 
         let notADocument = URL(fileURLWithPath: temporaryDirectory)
             .appendingPathComponent("not-a-document.odt")
-        try "definitely not an office document".write(to: notADocument, atomically: true, encoding: .utf8)
+        // Every byte value, which is text in no encoding. Not random bytes: a
+        // short enough run of those is often taken for one, and odrcore reads
+        // anything it cannot name as text.
+        try Data((0..<2).flatMap { _ in (0...255).map(UInt8.init) }).write(to: notADocument)
 
         XCTAssertThrowsError(
             try wrapper.translate(
@@ -378,6 +383,19 @@ class OpenDocumentReaderTests: XCTestCase {
         }
     }
 
+    /// The other side of it: real text has a charset, and must still open.
+    func testTextFileIsTranslated() throws {
+        let wrapper = CoreWrapper()
+
+        let notes = URL(fileURLWithPath: temporaryDirectory).appendingPathComponent("notes.txt")
+        try "Alpha\nBeta\n".write(to: notes, atomically: true, encoding: .utf8)
+
+        try wrapper.translate(
+            notes.path, cache: temporaryDirectory, into: temporaryDirectory, with: nil, editable: false)
+
+        XCTAssertEqual(wrapper.pageNames, ["text"])
+    }
+
     func testTranslatePerformance() throws {
         let wrapper = CoreWrapper()
         let path = documentURL.path
diff --git a/OpenDocumentReaderTests/test.epub b/OpenDocumentReaderTests/test.epub
new file mode 100644
index 0000000000000000000000000000000000000000..9c750c84062c200fd04b0d9dea6974c90b186fdc
GIT binary patch
literal 369
zcmWIWW@Zs#U|`^2c+@5uyZ1w`CNGf34aA&4oR?pcTC7)6QBr(H^MuEfA}?LfCrk_h
zD0*5~l$`{rbpc{QAkN6o$xKPC)Gx@$FUi--DoFob|M)*M8y6!UeL_h3ic^#G^HR_>
zGBSxU<8~%cHyAW9f+)D71H4hSp}Q2KiGiVk(FDlEa5p~fAP2)h17i-53Db^net<VC
Q8%PZ^5N-p~OF<k40OM&>6aWAK

literal 0
HcmV?d00001

diff --git a/OpenDocumentReaderTests/test.pages b/OpenDocumentReaderTests/test.pages
new file mode 100644
index 0000000000000000000000000000000000000000..6c3a612154d0dbe714eb5e79c4b05a2f70f14f5e
GIT binary patch
literal 369
zcmWIWW@Zs#U|`^2xL73`yZ1w`CNGf34aA&4oR?pcTC7)6QBr(H^MuEfA}?LfCrk_h
zD0*5~l$`{rbpc{QAkN6o$xKPC)Gx@$FUi--DoFob|M)*M8y6!UeL_h3ic^#G^HR_>
zGBSxU<8~%cHyAW9f+)D71H4hSp}Q2KiGiVk(FDlEa5p~fAP2)h17i-53Db^net<VC
Q8%PZ^5N-p~OF<k408S}VW&i*H

literal 0
HcmV?d00001

diff --git a/OpenDocumentReaderTests/test.zip b/OpenDocumentReaderTests/test.zip
new file mode 100644
index 0000000000000000000000000000000000000000..f8adf0289647eaf184fa7dea72ae305c31824178
GIT binary patch
literal 369
zcmWIWW@Zs#U|`^2;HeUg-TNU|lNZS224YSi&dV=JE!HckC@DUpdBWpKk(aLL6DEcL
z6g{mg%1(mRx&W~t5NG7)WTqrm>KA0>m*neZ6{P>JfBc`Bjf)YFJ|QH1#i_~pc`0Zb
z8JR?waXS;J8w?s4K@{B40p6(E&|M1A#K6$NXaZznxEr5#kb_~MfiVZjglR`OKfs%n
Q4Wxz{2)6<0r63Li09GYU$N&HU

literal 0
HcmV?d00001

diff --git a/configs/full/Info.plist b/configs/full/Info.plist
index 459ce6d..c8cc167 100644
--- a/configs/full/Info.plist
+++ b/configs/full/Info.plist
@@ -31,9 +31,11 @@
 			<string>Alternate</string>
 			<key>LSItemContentTypes</key>
 			<array>
+				<!-- No audiovisual type: odrcore plays a sound or a film because
+				     OpenDocument.droid once did, and a document reader should not
+				     be offered as the handler for an mp3. -->
 				<string>public.text</string>
 				<string>public.image</string>
-				<string>public.audiovisual-content</string>
 				<string>public.composite-content</string>
 				<!-- The broad types above miss these: a system type that conforms
 				     to none of them, and the six below that iOS has no type for
diff --git a/configs/lite/Info.plist b/configs/lite/Info.plist
index 0303725..215c99e 100644
--- a/configs/lite/Info.plist
+++ b/configs/lite/Info.plist
@@ -31,9 +31,11 @@
 			<string>Alternate</string>
 			<key>LSItemContentTypes</key>
 			<array>
+				<!-- No audiovisual type: odrcore plays a sound or a film because
+				     OpenDocument.droid once did, and a document reader should not
+				     be offered as the handler for an mp3. -->
 				<string>public.text</string>
 				<string>public.image</string>
-				<string>public.audiovisual-content</string>
 				<string>public.composite-content</string>
 				<!-- The broad types above miss these: a system type that conforms
 				     to none of them, and the six below that iOS has no type for
diff --git a/scripts/make-test-fixtures.py b/scripts/make-test-fixtures.py
index a2c062a..0c29b96 100644
--- a/scripts/make-test-fixtures.py
+++ b/scripts/make-test-fixtures.py
@@ -168,6 +168,15 @@ def write(path: Path, mimetype: str, content_xml: str) -> None:
     print(f"wrote {path}")
 
 
+def archive(path: Path) -> None:
+    """A zip that is only a zip: nothing inside it makes it a document."""
+    with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as package:
+        package.writestr("notes.txt", "Alpha\nBeta\n")
+        package.writestr("holiday/photo.jpg", b"\xff\xd8\xff\xe0" + bytes(64))
+        package.writestr("holiday/second.jpg", b"\xff\xd8\xff\xe0" + bytes(64))
+    print(f"wrote {path}")
+
+
 def main() -> None:
     tests = Path(__file__).resolve().parent.parent / "OpenDocumentReaderTests"
 
@@ -190,6 +199,12 @@ def main() -> None:
     encrypt_pdf(path, encrypted)
     print(f"wrote {encrypted}")
 
+    archive(tests / "test.zip")
+    # zips the system knows as documents rather than as containers: it draws the
+    # first itself, and cannot draw the second, which falls back to the listing
+    archive(tests / "test.pages")
+    archive(tests / "test.epub")
+
 
 if __name__ == "__main__":
     main()

From 3505f4b0a7fd36715d50ff62b0ef60bf803df0c7 Mon Sep 17 00:00:00 2001
From: Andreas Stefl <stefl.andreas@gmail.com>
Date: Fri, 21 Aug 2026 17:13:19 +0200
Subject: [PATCH 2/3] Wait for the screen before saying a file did not open

The browser opens a file before it puts the reader on screen, so one that
fails straight away had nowhere to show its message and it was lost. It now
waits for the screen it is about to be given.

Only a message that really offers the way to write to us is counted as one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AHynmW7Vk9bXvUFxLkwu6W
---
 .../DocumentViewController.swift              | 30 +++++++++++++++-
 .../FailedToOpenTests.swift                   | 34 +++++++++++++++++++
 2 files changed, 63 insertions(+), 1 deletion(-)

diff --git a/OpenDocumentReader/DocumentViewController.swift b/OpenDocumentReader/DocumentViewController.swift
index 159b52e..0df7318 100644
--- a/OpenDocumentReader/DocumentViewController.swift
+++ b/OpenDocumentReader/DocumentViewController.swift
@@ -433,6 +433,14 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
     override func viewDidAppear(_ animated: Bool) {
         super.viewDidAppear(animated)
 
+        if let outcome = failureAwaitingTheScreen {
+            failureAwaitingTheScreen = nil
+
+            close(with: outcome)
+
+            return
+        }
+
         // the consent form is modal, so it has to wait for the window hierarchy - viewWillAppear
         // is too early. This runs again on every reappearance, hence the flag.
         guard Features.withAds, !hasStartedAds else {
@@ -992,6 +1000,20 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
                 AnalyticsConstants.paramContentType: doc.fileURL.pathExtension.lowercased(),
             ])
 
+        close(with: outcome)
+    }
+
+    /// Takes the reader off the screen and says why. The document is opened
+    /// before this controller is presented, so a file that fails on the first
+    /// try has nothing to dismiss and nowhere to put the message yet — it waits
+    /// for the screen it is about to be given, the way the password prompt does.
+    private func close(with outcome: FailedToOpen) {
+        guard viewIfLoaded?.window != nil else {
+            failureAwaitingTheScreen = outcome
+
+            return
+        }
+
         // taken before the dismiss, which is what takes this controller off it
         let host = presentingViewController
 
@@ -1003,6 +1025,10 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
     /// Whether this document has already ended in a message.
     private var hasGivenUp = false
 
+    /// A message raised before this controller was on screen. Shown as soon as
+    /// it is, rather than into a window hierarchy it is not part of.
+    private var failureAwaitingTheScreen: FailedToOpen?
+
     func documentLoadingStarted(_ doc: Document) {
         progressBar.isHidden = false
         progressBar.observedProgress = doc.loadProgress
@@ -1090,7 +1116,9 @@ extension UIViewController {
 
         present(alert, animated: true)
 
-        AnalyticsManager.shared.report("contact_offer")
+        if outcome.offersContact {
+            AnalyticsManager.shared.report("contact_offer")
+        }
     }
 
     /// A mail to us. Nothing more to say where there is no mail app: the
diff --git a/OpenDocumentReaderTests/FailedToOpenTests.swift b/OpenDocumentReaderTests/FailedToOpenTests.swift
index a63ec93..0631ec7 100644
--- a/OpenDocumentReaderTests/FailedToOpenTests.swift
+++ b/OpenDocumentReaderTests/FailedToOpenTests.swift
@@ -59,6 +59,40 @@ class FailedToOpenTests: XCTestCase {
         XCTAssertEqual(alert.actions.map(\.title), [NSLocalizedString("ok", comment: "")])
     }
 
+    /// The document browser opens the file before it presents the reader, so a
+    /// file that fails on the first try fails while this controller is still
+    /// off screen. The message has to wait for the screen rather than be shown
+    /// into a window hierarchy the controller is not part of.
+    func testAFailureBeforeTheReaderIsOnScreenWaitsForIt() throws {
+        let url = URL(fileURLWithPath: temporaryDirectory).appendingPathComponent("nonsense.odt")
+        try Data((0..<2).flatMap { _ in (0...255).map(UInt8.init) }).write(to: url)
+
+        let storyboard = UIStoryboard(name: "Main", bundle: Bundle(for: DocumentViewController.self))
+        controller = try XCTUnwrap(
+            storyboard.instantiateViewController(withIdentifier: "TextDocumentViewController")
+                as? DocumentViewController)
+
+        document = Document(fileURL: url)
+        controller.document = document
+        // loaded but in no window, which is where the browser opens it from
+        controller.loadViewIfNeeded()
+
+        let opened = expectation(description: "opened")
+        document.open { _ in opened.fulfill() }
+        wait(for: [opened], timeout: 60)
+
+        for _ in 0..<10 { _ = XCTWaiter.wait(for: [expectation(description: "a turn")], timeout: 0.1) }
+        XCTAssertNil(controller.presentedViewController, "the message went into no window")
+
+        // and now it gets a screen, as the browser presenting it would give it
+        window = UIWindow(frame: CGRect(x: 0, y: 0, width: 390, height: 844))
+        window.rootViewController = controller
+        window.makeKeyAndVisible()
+
+        let alert = try XCTUnwrap(waitForAlert())
+        XCTAssertEqual(alert.message, NSLocalizedString("toast_error_illegal_file_reopen", comment: ""))
+    }
+
     // MARK: - helpers
 
     private func waitForAlert() -> UIAlertController? {

From 9f1a98a761ca57222c48abd2c57ec1ddd0705778 Mon Sep 17 00:00:00 2001
From: Andreas Stefl <stefl.andreas@gmail.com>
Date: Sat, 22 Aug 2026 00:00:41 +0200
Subject: [PATCH 3/3] Shorten the comments in the new code

The explanations of why the reader does what it does were longer than the
code they sat above. What is left says what is not plain from reading it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SNdCgkkN5mytCQT5RwPzse
---
 OpenDocumentReader/Constants.swift            |  3 +-
 OpenDocumentReader/CoreWrapper.swift          | 23 ++----
 .../DocumentViewController.swift              | 75 +++++--------------
 .../ArchiveDocumentTests.swift                | 30 +++-----
 .../FailedToOpenTests.swift                   | 16 ++--
 .../LockedDocumentTests.swift                 |  6 +-
 .../OpenDocumentReaderTests.swift             | 11 +--
 scripts/make-test-fixtures.py                 |  3 +-
 8 files changed, 49 insertions(+), 118 deletions(-)

diff --git a/OpenDocumentReader/Constants.swift b/OpenDocumentReader/Constants.swift
index f0d6364..76abbfa 100644
--- a/OpenDocumentReader/Constants.swift
+++ b/OpenDocumentReader/Constants.swift
@@ -12,8 +12,7 @@ enum Constants {
     /// Which of the house ad's rotations comes next.
     static let key_house_ad_index = "houseAdIndex"
 
-    /// Where a reader writes to when a file will not open. The same address the
-    /// message names, and the one OpenDocument.droid uses.
+    /// The address the "file will not open" message names.
     static let supportEmail = "support@opendocument.app"
 
     /// ODR Pro on the App Store. This is the *paid* app: on iOS that is `at.tomtasche.reader`,
diff --git a/OpenDocumentReader/CoreWrapper.swift b/OpenDocumentReader/CoreWrapper.swift
index fb34ac5..334658b 100644
--- a/OpenDocumentReader/CoreWrapper.swift
+++ b/OpenDocumentReader/CoreWrapper.swift
@@ -81,9 +81,7 @@ private func selectViews(_ views: [HtmlView], _ documentType: DocumentType) -> [
     @objc private(set) var pageNames: [String] = []
     @objc private(set) var pageURLs: [URL] = []
 
-    /// Whether odrcore saw only a container and the page is a listing of what is
-    /// inside it. The reader asks because the system may know the same file as a
-    /// document of its own — see `systemKnowsItAsADocument`.
+    /// Whether odrcore saw only a container, so the page is a listing of what is inside it.
     @objc private(set) var isArchive = false
 
     /// Whether `backTranslate` has a document to apply an edit to. Only a
@@ -128,20 +126,12 @@ private func selectViews(_ views: [HtmlView], _ documentType: DocumentType) -> [
             }
         }
 
-        // odrcore's own answer, rather than a list of formats kept here: a
-        // document, a pdf, a csv, a plain zip, a picture, a sound and a font
-        // all come back as a page it wrote. Whatever it learns to read next is
-        // read without a change on this side, and what it cannot read is the
-        // one message the reader shows.
         guard Odr.capabilities(fileType: file.fileType).translateHtml else {
             throw coreWrapperError(.unsupportedFileType, "odrcore does not render this file type")
         }
 
-        // A file odrcore recognises as nothing else it calls text, so a database
-        // or a program would otherwise be shown as a page of nonsense. Its own
-        // answer for that is the charset: unnamed means the bytes are not text.
-        // The same check OpenDocument.droid makes, and to be made once in
-        // odrcore instead - opendocument-app/OpenDocument.core#728.
+        // odrcore calls a file it recognises as nothing else text, so an unnamed
+        // charset means the bytes are not text at all
         if file.isTextFile, (try? file.asTextFile())?.charset == nil {
             throw coreWrapperError(.unsupportedFileType, "odrcore could not name a charset")
         }
@@ -183,11 +173,8 @@ private func selectViews(_ views: [HtmlView], _ documentType: DocumentType) -> [
             service = try HtmlTranslator.translate(
                 document: document, cachePath: cachePath, config: config)
         } else {
-            // everything that is not a document has no document behind it to
-            // open or to edit: a pdf, a csv, a zip, a picture, a sound, a font.
-            // `.unknown` keeps the one view each of them has; not
-            // `.spreadsheet`, though a csv is one, because that asks for a tab
-            // per sheet and a csv's single sheet is called "csv"
+            // nothing to edit, and `.unknown` keeps the single view each of
+            // these has - `.spreadsheet` would ask for a tab per sheet
             documentType = .unknown
             openedDocument = nil
             service = try HtmlTranslator.translate(
diff --git a/OpenDocumentReader/DocumentViewController.swift b/OpenDocumentReader/DocumentViewController.swift
index 0df7318..f1ec09f 100644
--- a/OpenDocumentReader/DocumentViewController.swift
+++ b/OpenDocumentReader/DocumentViewController.swift
@@ -207,9 +207,7 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
         pageTabBar.addTarget(self, action: #selector(pageSelected(sender:)), for: .valueChanged)
         webview.navigationDelegate = self
         webview.uiDelegate = self
-        // the way back out of a file opened from a zip's listing. There is
-        // nothing to go back to until something has been opened, so it changes
-        // nothing for a document that is only read.
+        // the way back out of a file opened from a zip's listing
         webview.allowsBackForwardNavigationGestures = true
 
         searchBar.delegate = self
@@ -248,12 +246,8 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
         ])
     }
 
-    /// odrcore writes every link with `target="_blank"`, so opening a file from
-    /// a zip's listing asks for a window this app has none of. It is shown in
-    /// the web view that asked instead, and the swipe back leads to the listing.
-    ///
-    /// Only what odrcore serves: a link out of a document leads to the web, and
-    /// this reader is not a browser.
+    /// odrcore writes every link with `target="_blank"`, and this app has no
+    /// second window: what odrcore serves opens in the web view that asked.
     func webView(
         _ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration,
         for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures
@@ -281,13 +275,10 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
             return
         }
 
-        // The web view's own answer about what it can draw, asked instead of
-        // guessed from the file's name.
         if !navigationResponse.canShowMIMEType {
             decisionHandler(.cancel)
 
-            // the system could not draw the document after all, so odrcore's
-            // listing of what is inside it is the better of the two
+            // the system could not draw it after all, so fall back to the listing
             if let listing = listingInReserve {
                 listingInReserve = nil
 
@@ -318,12 +309,8 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
         giveUp(on: doc, with: .broken, code: response.statusCode)
     }
 
-    /// The page never arrived — the socket went away, or the web view could make
-    /// nothing of what it was given. Same end as a document that would not
-    /// translate.
-    ///
-    /// Only what odrcore serves: a link out of a document that fails is the
-    /// web's problem, not this document's.
+    /// The page never arrived. Only what odrcore serves counts: a link out of a
+    /// document that fails is the web's problem.
     func webView(_ webView: WKWebView, didFail navigation: WKNavigation!, withError error: Error) {
         pageFailed(error)
     }
@@ -343,10 +330,8 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
         giveUp(on: doc, with: .broken, code: (error as NSError).code)
     }
 
-    /// Whether the reader stopped this load itself. Turning a page cancels the
-    /// one before it, and answering a response with `.cancel` — which is how the
-    /// listing takes over from a document the system could not draw — is
-    /// reported here as a failure too.
+    /// Whether the reader stopped this load itself: turning a page cancels the
+    /// one before it, and a response answered with `.cancel` lands here too.
     private func isOurOwnDoing(_ error: Error) -> Bool {
         let error = error as NSError
 
@@ -890,13 +875,8 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
             return
         }
 
-        // odrcore saw only a container, but the system knows this file as a
-        // document of its own - an iWork one, which it draws properly and
-        // odrcore has no reader for. The listing of the parts inside is what
-        // the reader falls back to if the system cannot draw it after all.
-        //
-        // Nothing here names a format, and the day odrcore reads iWork the
-        // file stops being an archive to it and this stops firing.
+        // only a container to odrcore, but a document to the system: it gets
+        // the first go, with the listing kept in reserve
         if doc.isArchive, systemKnowsItAsADocument(doc.fileURL) {
             listingInReserve = url
 
@@ -912,17 +892,15 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
         documentNavigation = self.webview.load(URLRequest(url: url))
     }
 
-    /// Whether the system has a type of its own for this file that says it is a
-    /// document rather than just a container. A `.pages` is composite content; a
-    /// `.zip` and a `.jar` are not.
+    /// Whether the system's type for this file says document rather than
+    /// container: a `.pages` is composite content, a `.zip` is not.
     private func systemKnowsItAsADocument(_ url: URL) -> Bool {
         guard let type = UTType(filenameExtension: url.pathExtension) else { return false }
 
         return !type.isDynamic && type.conforms(to: .compositeContent)
     }
 
-    /// odrcore's listing of an archive, held back while the system is given the
-    /// first go at the same file.
+    /// odrcore's listing, held back while the system has the first go.
     private var listingInReserve: URL?
 
     func documentEncrypted(_ doc: Document) {
@@ -962,8 +940,6 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
         let code = (error as NSError).code
         let isFromCore = (error as NSError).domain == CoreWrapperErrorDomain
 
-        // The three ways a file does not open, and each has its own thing to
-        // say. Only the last is worth a mail to us.
         let outcome: FailedToOpen
         switch (isFromCore, code) {
         case (true, CoreWrapperError.unsupportedFileType.rawValue):
@@ -978,12 +954,8 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
         giveUp(on: doc, with: outcome, code: code)
     }
 
-    /// Nothing left to try with this file, so stop showing it: the document
-    /// browser is a better answer than a page that will not appear, and the
-    /// message comes up over it — the same way OpenDocument.droid ends here.
-    ///
-    /// Runs once. A page that fails after the document was already given up on
-    /// would otherwise dismiss a reader that has gone.
+    /// Nothing left to try: close the reader and say why. Runs once, so a page
+    /// failing afterwards cannot dismiss a reader that has gone.
     private func giveUp(on doc: Document, with outcome: FailedToOpen, code: Int) {
         guard !hasGivenUp else { return }
         hasGivenUp = true
@@ -1003,10 +975,8 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
         close(with: outcome)
     }
 
-    /// Takes the reader off the screen and says why. The document is opened
-    /// before this controller is presented, so a file that fails on the first
-    /// try has nothing to dismiss and nowhere to put the message yet — it waits
-    /// for the screen it is about to be given, the way the password prompt does.
+    /// Dismisses the reader and shows the message over the browser. A file that
+    /// fails before this controller is on screen waits for the screen.
     private func close(with outcome: FailedToOpen) {
         guard viewIfLoaded?.window != nil else {
             failureAwaitingTheScreen = outcome
@@ -1025,8 +995,7 @@ class DocumentViewController: UIViewController, DocumentDelegate, UISearchBarDel
     /// Whether this document has already ended in a message.
     private var hasGivenUp = false
 
-    /// A message raised before this controller was on screen. Shown as soon as
-    /// it is, rather than into a window hierarchy it is not part of.
+    /// A message raised before this controller was on screen.
     private var failureAwaitingTheScreen: FailedToOpen?
 
     func documentLoadingStarted(_ doc: Document) {
@@ -1079,7 +1048,7 @@ enum FailedToOpen {
     case unsupported
     /// A legacy Word, Excel or PowerPoint file no password opens.
     case locked
-    /// odrcore took it and it still did not appear. This one asks to hear about it.
+    /// odrcore took it and it still did not appear.
     case broken
 
     var message: String {
@@ -1096,9 +1065,7 @@ enum FailedToOpen {
 
 extension UIViewController {
 
-    /// Says why a file did not open, and for the one case that is ours offers
-    /// the way to tell us. Shown over the document browser rather than over the
-    /// reader, which is gone by now.
+    /// Says why a file did not open, and offers the way to tell us where that helps.
     func presentFailure(_ outcome: FailedToOpen) {
         let alert = UIAlertController(
             title: NSLocalizedString("dialog_broken_file_title", comment: ""),
@@ -1121,8 +1088,6 @@ extension UIViewController {
         }
     }
 
-    /// A mail to us. Nothing more to say where there is no mail app: the
-    /// address is in the message either way.
     private static func contactSupport() {
         AnalyticsManager.shared.report("contact_tapped")
 
diff --git a/OpenDocumentReaderTests/ArchiveDocumentTests.swift b/OpenDocumentReaderTests/ArchiveDocumentTests.swift
index ceb3f2c..9986f57 100644
--- a/OpenDocumentReaderTests/ArchiveDocumentTests.swift
+++ b/OpenDocumentReaderTests/ArchiveDocumentTests.swift
@@ -3,9 +3,8 @@ import XCTest
 
 @testable import OpenDocumentReader
 
-/// The app offers itself for a zip, because that is the type every ODF and
-/// Office file conforms to. One that is only a zip has to open too: odrcore
-/// lists what is inside it, and the listing's links have to lead somewhere.
+/// A zip that is only a zip: odrcore lists what is inside it, and the listing's
+/// links have to lead somewhere.
 class ArchiveDocumentTests: XCTestCase {
     private let temporaryDirectory = NSTemporaryDirectory()
     private var documentURL: URL!
@@ -24,8 +23,7 @@ class ArchiveDocumentTests: XCTestCase {
         document = nil
     }
 
-    /// Out of the read-only test bundle, and away from the temporary directory
-    /// translating uses for its cache and output.
+    /// Out of the read-only test bundle, and away from the cache directory.
     private func copyFixture(ofType pathExtension: String = "zip") throws -> URL {
         let documentsURL = try FileManager.default.url(
             for: .documentDirectory, in: .userDomainMask, appropriateFor: nil, create: false)
@@ -40,7 +38,7 @@ class ArchiveDocumentTests: XCTestCase {
         return url
     }
 
-    /// One page, the listing, rather than the error a zip used to be.
+    /// One page: the listing.
     func testAZipTranslatesIntoItsListing() throws {
         let wrapper = CoreWrapper()
 
@@ -84,8 +82,7 @@ class ArchiveDocumentTests: XCTestCase {
         }
     }
 
-    /// End to end: the reader shows the listing, not the message it shows for a
-    /// file it cannot open.
+    /// End to end: the reader shows the listing, not an error.
     func testAZipReachesTheReader() throws {
         try present(documentURL)
 
@@ -100,9 +97,8 @@ class ArchiveDocumentTests: XCTestCase {
         XCTAssertFalse(shown.contains(NSLocalizedString("toast_error_generic", comment: "")), shown)
     }
 
-    /// odrcore has no iWork reader, so a `.pages` is a zip to it — but the
-    /// system knows it as a document and draws it properly. It gets the first
-    /// go, and the listing is only what the reader falls back to.
+    /// A `.pages` is a zip to odrcore, but a document to the system, which gets
+    /// the first go.
     func testADocumentTheSystemKnowsIsLeftToTheSystem() throws {
         try present(try copyFixture(ofType: "pages"))
 
@@ -116,9 +112,8 @@ class ArchiveDocumentTests: XCTestCase {
         XCTAssertNil(controller.presentedViewController, "it said the file would not open")
     }
 
-    /// And when the system turns out not to be able to draw it after all, the
-    /// listing takes over rather than a message — an `.epub` is composite
-    /// content to the system, which has no reader for it either.
+    /// And when the system cannot draw it after all, the listing takes over
+    /// rather than a message.
     func testAnArchiveTheSystemCannotDrawFallsBackToTheListing() throws {
         try present(try copyFixture(ofType: "epub"))
 
@@ -144,8 +139,8 @@ class ArchiveDocumentTests: XCTestCase {
         return controller.webview.url
     }
 
-    /// odrcore writes the listing's links with `target="_blank"`, and a web view
-    /// with nobody to answer that drops the tap on the floor.
+    /// The listing's links carry `target="_blank"`, which a web view drops
+    /// unless someone answers it.
     func testFollowingALinkOpensTheFileInTheSameWebView() throws {
         try present(documentURL)
 
@@ -187,8 +182,7 @@ class ArchiveDocumentTests: XCTestCase {
             guard let end = tail.firstIndex(of: "\"") else { break }
 
             let href = String(tail[..<end])
-            // the download links carry the same targets, and a `data:` one is
-            // not the server's to answer
+            // a `data:` href is not the server's to answer
             if !href.hasPrefix("data:"), !found.contains(href) {
                 found.append(href)
             }
diff --git a/OpenDocumentReaderTests/FailedToOpenTests.swift b/OpenDocumentReaderTests/FailedToOpenTests.swift
index 0631ec7..e4bb866 100644
--- a/OpenDocumentReaderTests/FailedToOpenTests.swift
+++ b/OpenDocumentReaderTests/FailedToOpenTests.swift
@@ -3,8 +3,7 @@ import XCTest
 
 @testable import OpenDocumentReader
 
-/// What the reader says about a file that does not open, and which of those is
-/// worth asking to hear about.
+/// What the reader says about a file that does not open.
 class FailedToOpenTests: XCTestCase {
     private let temporaryDirectory = NSTemporaryDirectory()
     private var window: UIWindow!
@@ -18,8 +17,7 @@ class FailedToOpenTests: XCTestCase {
         document = nil
     }
 
-    /// A format nothing here reads is not ours to hear about; a file odrcore
-    /// took and could not show is.
+    /// Only a file odrcore took and could not show is ours to hear about.
     func testOnlyABrokenFileOffersContact() {
         XCTAssertFalse(FailedToOpen.unsupported.offersContact)
         XCTAssertFalse(FailedToOpen.locked.offersContact)
@@ -32,8 +30,7 @@ class FailedToOpenTests: XCTestCase {
             NSLocalizedString("toast_error_illegal_file_reopen", comment: ""))
     }
 
-    /// The address is in the message, so a reader with no mail app still knows
-    /// where to write.
+    /// The address is in the message, for a reader with no mail app.
     func testTheMessageNamesTheAddress() {
         XCTAssertTrue(
             FailedToOpen.broken.message.contains(Constants.supportEmail),
@@ -59,10 +56,7 @@ class FailedToOpenTests: XCTestCase {
         XCTAssertEqual(alert.actions.map(\.title), [NSLocalizedString("ok", comment: "")])
     }
 
-    /// The document browser opens the file before it presents the reader, so a
-    /// file that fails on the first try fails while this controller is still
-    /// off screen. The message has to wait for the screen rather than be shown
-    /// into a window hierarchy the controller is not part of.
+    /// A failure before the reader is on screen has to wait for the screen.
     func testAFailureBeforeTheReaderIsOnScreenWaitsForIt() throws {
         let url = URL(fileURLWithPath: temporaryDirectory).appendingPathComponent("nonsense.odt")
         try Data((0..<2).flatMap { _ in (0...255).map(UInt8.init) }).write(to: url)
@@ -84,7 +78,7 @@ class FailedToOpenTests: XCTestCase {
         for _ in 0..<10 { _ = XCTWaiter.wait(for: [expectation(description: "a turn")], timeout: 0.1) }
         XCTAssertNil(controller.presentedViewController, "the message went into no window")
 
-        // and now it gets a screen, as the browser presenting it would give it
+        // and now it gets a screen
         window = UIWindow(frame: CGRect(x: 0, y: 0, width: 390, height: 844))
         window.rootViewController = controller
         window.makeKeyAndVisible()
diff --git a/OpenDocumentReaderTests/LockedDocumentTests.swift b/OpenDocumentReaderTests/LockedDocumentTests.swift
index dbe1178..b723344 100644
--- a/OpenDocumentReaderTests/LockedDocumentTests.swift
+++ b/OpenDocumentReaderTests/LockedDocumentTests.swift
@@ -57,8 +57,7 @@ class LockedDocumentTests: XCTestCase {
         }
     }
 
-    /// Its own message rather than the one that asks to hear about a broken
-    /// file: nothing is wrong with it, and no password opens it.
+    /// Its own message rather than the broken-file one: no password opens it.
     func testALockedLegacyFileSaysWhyItDidNotOpen() throws {
         try present(documentURL)
 
@@ -74,8 +73,7 @@ class LockedDocumentTests: XCTestCase {
             "a locked file is not ours to hear about")
     }
 
-    /// The reader is taken off the screen first, the same way OpenDocument.droid
-    /// drops back to its landing screen.
+    /// The reader is taken off the screen before the message.
     func testTheReaderIsClosedBeforeTheMessage() throws {
         try present(documentURL)
 
diff --git a/OpenDocumentReaderTests/OpenDocumentReaderTests.swift b/OpenDocumentReaderTests/OpenDocumentReaderTests.swift
index f18375f..86d056e 100644
--- a/OpenDocumentReaderTests/OpenDocumentReaderTests.swift
+++ b/OpenDocumentReaderTests/OpenDocumentReaderTests.swift
@@ -158,9 +158,7 @@ class OpenDocumentReaderTests: XCTestCase {
         XCTAssertFalse(wrapper.isEditable)
     }
 
-    /// A png is one of the formats odrcore translates but we leave to the system.
-    /// odrcore renders a picture too, so the reader no longer keeps a list of
-    /// what to hand to the web view instead.
+    /// odrcore renders a picture too.
     func testImageIsTranslated() throws {
         let wrapper = CoreWrapper()
 
@@ -361,16 +359,13 @@ class OpenDocumentReaderTests: XCTestCase {
         }
     }
 
-    /// The one thing the reader still decides for itself: odrcore recognising
-    /// nothing at all is the message, not a page.
+    /// odrcore recognising nothing at all is the message, not a page.
     func testUnsupportedFileTypeReportsTypedError() throws {
         let wrapper = CoreWrapper()
 
         let notADocument = URL(fileURLWithPath: temporaryDirectory)
             .appendingPathComponent("not-a-document.odt")
-        // Every byte value, which is text in no encoding. Not random bytes: a
-        // short enough run of those is often taken for one, and odrcore reads
-        // anything it cannot name as text.
+        // every byte value: text in no encoding, so odrcore has nothing to read
         try Data((0..<2).flatMap { _ in (0...255).map(UInt8.init) }).write(to: notADocument)
 
         XCTAssertThrowsError(
diff --git a/scripts/make-test-fixtures.py b/scripts/make-test-fixtures.py
index 0c29b96..5cc7ca3 100644
--- a/scripts/make-test-fixtures.py
+++ b/scripts/make-test-fixtures.py
@@ -200,8 +200,7 @@ def main() -> None:
     print(f"wrote {encrypted}")
 
     archive(tests / "test.zip")
-    # zips the system knows as documents rather than as containers: it draws the
-    # first itself, and cannot draw the second, which falls back to the listing
+    # zips the system knows as documents: it draws a .pages, but not an .epub
     archive(tests / "test.pages")
     archive(tests / "test.epub")