\(WebDocumentLoader.escapeHTML(AppText.localized("无法读取 DOCX 内容。", "Unable to read DOCX content.")))
" + : content.html + let html = WebDocumentLoader.pageHTML( + title: title, + body: body, + documentStyles: WebDocumentLoader.docxReaderStyles, + profile: .docx + ) + try Data(html.utf8).write(to: htmlURL, options: .atomic) + try Data(content.plainText.joined(separator: "\n\n").utf8).write(to: plainTextURL, options: .atomic) + try JSONEncoder().encode(content.tocItems.map(DOCXPreparedTOCItem.init)).write(to: tocURL, options: .atomic) + + let media = try mediaFiles(in: directory) + let contentBytes = fileSize(htmlURL) + fileSize(plainTextURL) + fileSize(tocURL) + + media.reduce(0) { $0 + $1.bytes } + guard contentBytes >= 0 else { + throw cacheError(AppText.localized("无法计算 DOCX 缓存大小。", "Unable to size the prepared DOCX cache.")) + } + let base = DOCXPreparedManifest( + schemaVersion: schemaVersion, + fingerprint: fingerprint, + title: title, + entryBytes: contentBytes, + htmlSHA256: try requiredDigest(htmlURL), + plainTextSHA256: try requiredDigest(plainTextURL), + tocSHA256: try requiredDigest(tocURL), + media: media + ) + let encoder = JSONEncoder() + encoder.outputFormatting = [.sortedKeys] + var manifest = base + var data = try encoder.encode(manifest) + for _ in 0..<5 { + let exactBytes = contentBytes + Int64(data.count) + guard exactBytes != manifest.entryBytes else { break } + manifest = DOCXPreparedManifest( + schemaVersion: base.schemaVersion, + fingerprint: base.fingerprint, + title: base.title, + entryBytes: exactBytes, + htmlSHA256: base.htmlSHA256, + plainTextSHA256: base.plainTextSHA256, + tocSHA256: base.tocSHA256, + media: base.media + ) + data = try encoder.encode(manifest) + } + try data.write(to: directory.appendingPathComponent(manifestName), options: .atomic) + return manifest.entryBytes + } + + static func cleanup(root: URL, keeping key: String, policy: DOCXPreparedCachePolicy) { + guard var entries = try? FileManager.default.contentsOfDirectory( + at: root, + includingPropertiesForKeys: [.contentModificationDateKey, .isDirectoryKey], + options: [.skipsHiddenFiles] + ).filter({ $0.lastPathComponent != key }) else { return } + entries.sort { + let left = (try? $0.resourceValues(forKeys: [.contentModificationDateKey]).contentModificationDate) ?? .distantPast + let right = (try? $1.resourceValues(forKeys: [.contentModificationDateKey]).contentModificationDate) ?? .distantPast + return left < right + } + let current = root.appendingPathComponent(key, isDirectory: true) + var totalEntries = FileManager.default.fileExists(atPath: current.path) ? 1 : 0 + var totalBytes = entryBytes(at: current) + for entry in entries { + totalEntries += 1 + totalBytes += entryBytes(at: entry) + } + while (totalEntries > policy.maximumEntries || totalBytes > policy.maximumBytes), !entries.isEmpty { + let victim = entries.removeFirst() + let bytes = entryBytes(at: victim) + if (try? FileManager.default.removeItem(at: victim)) != nil { + totalEntries -= 1 + totalBytes -= bytes + } + } + } + + static func fingerprint(url: URL, cancellationToken: DocumentLoadCancellationToken?) throws -> String { + let handle = try FileHandle(forReadingFrom: url.standardizedFileURL) + defer { try? handle.close() } + var hasher = SHA256() + while true { + try cancellationToken?.checkCancellation() + let data = handle.readData(ofLength: 1_048_576) + if data.isEmpty { break } + hasher.update(data: data) + } + return hasher.finalize().map { String(format: "%02x", $0) }.joined() + } + + private static func entryBytes(at directory: URL) -> Int64 { + let manifestURL = directory.appendingPathComponent(manifestName) + if let data = try? Data(contentsOf: manifestURL), + let manifest = try? JSONDecoder().decode(DOCXPreparedManifest.self, from: data), + manifest.entryBytes > 0 { + return manifest.entryBytes + } + guard let enumerator = FileManager.default.enumerator( + at: directory, + includingPropertiesForKeys: [.isRegularFileKey, .fileSizeKey], + options: [.skipsHiddenFiles] + ) else { return 0 } + var bytes: Int64 = 0 + for case let file as URL in enumerator { + let values = try? file.resourceValues(forKeys: [.isRegularFileKey, .fileSizeKey]) + if values?.isRegularFile == true { + bytes += Int64(values?.fileSize ?? 0) + } + } + return bytes + } + + private static func mediaFiles(in directory: URL) throws -> [DOCXPreparedMediaFile] { + let mediaRoot = directory.appendingPathComponent("word/media", isDirectory: true) + guard FileManager.default.fileExists(atPath: mediaRoot.path) else { return [] } + guard let enumerator = FileManager.default.enumerator( + at: mediaRoot, + includingPropertiesForKeys: [.isRegularFileKey, .fileSizeKey], + options: [.skipsHiddenFiles] + ) else { return [] } + var files: [DOCXPreparedMediaFile] = [] + for case let file as URL in enumerator { + let values = try file.resourceValues(forKeys: [.isRegularFileKey, .fileSizeKey]) + guard values.isRegularFile == true else { continue } + let path = EPUBPathResolver.relativeFilePath(from: directory, to: file) + guard EPUBPathResolver.safeArchivePath(path) == path else { + throw cacheError(AppText.localized("DOCX 媒体路径不安全。", "A prepared DOCX media path is unsafe."), code: -3) + } + files.append(DOCXPreparedMediaFile(path: path, bytes: Int64(values.fileSize ?? 0))) + } + return files.sorted { $0.path < $1.path } + } + + private static func fileSize(_ url: URL) -> Int64 { + let values = try? url.resourceValues(forKeys: [.isRegularFileKey, .fileSizeKey]) + guard values?.isRegularFile == true else { return -1 } + return Int64(values?.fileSize ?? -1) + } + + private static func requiredDigest(_ url: URL) throws -> String { + let value = digest(url) + guard !value.isEmpty else { + throw cacheError(AppText.localized("无法校验 DOCX 缓存。", "Unable to fingerprint a prepared DOCX file.")) + } + return value + } + + private static func digest(_ url: URL) -> String { + guard let data = try? Data(contentsOf: url, options: .mappedIfSafe) else { return "" } + return digest(data) + } + + private static func digest(_ data: Data) -> String { + SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined() + } + + private static func cacheError(_ description: String, code: Int = -4) -> Error { + NSError(domain: "LeafReader", code: code, userInfo: [NSLocalizedDescriptionKey: description]) + } +} diff --git a/mac-app/DocumentLoadMeasurement.swift b/mac-app/DocumentLoadMeasurement.swift new file mode 100644 index 0000000..1e8cd06 --- /dev/null +++ b/mac-app/DocumentLoadMeasurement.swift @@ -0,0 +1,16 @@ +import Foundation + +enum DocumentLoadStage: String, Codable { + case docxFingerprint + case docxCacheLookup + case docxArchiveExtraction + case docxRelationshipParse + case docxXMLRender + case docxCacheCommit + case docxCacheHitLoad +} + +struct DocumentLoadMeasurement: Equatable { + let stage: DocumentLoadStage + let milliseconds: Double +} diff --git a/mac-app/DocumentLoading+Archive.swift b/mac-app/DocumentLoading+Archive.swift index a6a3927..605c65a 100644 --- a/mac-app/DocumentLoading+Archive.swift +++ b/mac-app/DocumentLoading+Archive.swift @@ -141,6 +141,77 @@ extension WebDocumentLoader { try ArchiveSafetyValidator.validateExtractedTree(at: destination, policy: .document) } + static func zipEntryPaths( + in url: URL, + cancellationToken: DocumentLoadCancellationToken? = nil + ) throws -> [String] { + try cancellationToken?.checkCancellation() + try ArchiveSafetyValidator.validateZIP(at: url) + let result = try ProcessRunner.run( + executableURL: URL(fileURLWithPath: "/usr/bin/unzip"), + arguments: ["-Z1", url.path], + timeout: archiveProcessTimeout, + isCancelled: { cancellationToken?.isCancelled == true } + ) + if result.wasCancelled { + throw CancellationError() + } + guard !result.timedOut, result.terminationStatus == 0 else { + throw NSError(domain: "LeafReader", code: Int(result.terminationStatus), userInfo: [ + NSLocalizedDescriptionKey: archiveProcessErrorMessage( + prefix: "Unable to inspect \(url.lastPathComponent)", + stderr: result.stderr + ) + ]) + } + guard let output = String(data: result.stdout, encoding: .utf8) else { + throw NSError(domain: "LeafReader", code: -2, userInfo: [ + NSLocalizedDescriptionKey: "Unable to decode the archive directory for \(url.lastPathComponent)." + ]) + } + try cancellationToken?.checkCancellation() + return output.split(whereSeparator: \.isNewline).map(String.init) + } + + static func unzip( + url: URL, + to destination: URL, + entryPaths: [String], + cancellationToken: DocumentLoadCancellationToken? = nil + ) throws { + guard !entryPaths.isEmpty else { + throw NSError(domain: "LeafReader", code: -2, userInfo: [ + NSLocalizedDescriptionKey: "The document archive has no readable entries." + ]) + } + try cancellationToken?.checkCancellation() + try ArchiveSafetyValidator.validateZIP(at: url) + let result = try ProcessRunner.run( + executableURL: URL(fileURLWithPath: "/usr/bin/unzip"), + arguments: ["-qq", "-o", url.path] + entryPaths + ["-d", destination.path], + timeout: archiveProcessTimeout, + isCancelled: { cancellationToken?.isCancelled == true } + ) + if result.wasCancelled { + throw CancellationError() + } + guard !result.timedOut else { + throw NSError(domain: "LeafReader", code: -1, userInfo: [ + NSLocalizedDescriptionKey: "Unable to unpack \(url.lastPathComponent): unzip timed out." + ]) + } + guard result.terminationStatus == 0 else { + throw NSError(domain: "LeafReader", code: Int(result.terminationStatus), userInfo: [ + NSLocalizedDescriptionKey: archiveProcessErrorMessage( + prefix: "Unable to unpack \(url.lastPathComponent)", + stderr: result.stderr + ) + ]) + } + try cancellationToken?.checkCancellation() + try ArchiveSafetyValidator.validateExtractedTree(at: destination, policy: .document) + } + static func zipEntryData(in url: URL, entryPath: String) throws -> Data? { guard let entryPath = EPUBPathResolver.safeArchivePath(entryPath) else { return nil } let result = try ProcessRunner.run( diff --git a/mac-app/DocumentLoading+DOCXCache.swift b/mac-app/DocumentLoading+DOCXCache.swift index 2127d08..c8c9f2b 100644 --- a/mac-app/DocumentLoading+DOCXCache.swift +++ b/mac-app/DocumentLoading+DOCXCache.swift @@ -1,288 +1,228 @@ -import CryptoKit import Foundation -private struct DOCXPreparedTOCItem: Codable { - let title: String - let href: String - let level: Int - - init(_ item: ReaderTOCItem) { - title = item.title - href = item.href - level = item.level - } - - var readerItem: ReaderTOCItem { - ReaderTOCItem(title: title, href: href, level: level) - } -} - -private struct DOCXPreparedMediaFile: Codable { - let path: String - let bytes: Int64 -} - -private struct DOCXPreparedManifest: Codable { - let schemaVersion: Int - let fingerprint: String - let title: String - let htmlSHA256: String - let plainTextSHA256: String - let tocSHA256: String - let media: [DOCXPreparedMediaFile] -} - -private enum DOCXPreparedCache { - static let schemaVersion = 1 - static let maximumEntries = 10 - static let lock = NSLock() - static let manifestName = "manifest.json" - static let htmlName = "rendered.html" - static let plainTextName = "plain-text.txt" - static let tocName = "toc.json" - - static func root() throws -> URL { - if let override = ProcessInfo.processInfo.environment["LEAFREADER_DOCX_CACHE_ROOT"], - !override.isEmpty { - let root = URL(fileURLWithPath: override, isDirectory: true) - try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true) - return root - } - let caches = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first - ?? FileManager.default.temporaryDirectory - let root = caches - .appendingPathComponent("LeafReader", isDirectory: true) - .appendingPathComponent("DOCXPreparedCache", isDirectory: true) - try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true) - return root - } - - static func key(fingerprint: String, title: String) -> String { - digest(Data("\(schemaVersion)\u{0}\(fingerprint)\u{0}\(title)".utf8)) - } - - static func load(directory: URL, fingerprint: String, title: String) throws -> WebReadableDocument { - let manifestURL = directory.appendingPathComponent(manifestName) - let htmlURL = directory.appendingPathComponent(htmlName) - let plainTextURL = directory.appendingPathComponent(plainTextName) - let tocURL = directory.appendingPathComponent(tocName) - let manifest = try JSONDecoder().decode( - DOCXPreparedManifest.self, - from: Data(contentsOf: manifestURL, options: .mappedIfSafe) - ) - guard manifest.schemaVersion == schemaVersion, - manifest.fingerprint == fingerprint, - manifest.title == title, - digest(htmlURL) == manifest.htmlSHA256, - digest(plainTextURL) == manifest.plainTextSHA256, - digest(tocURL) == manifest.tocSHA256 else { - throw cacheError(AppText.localized("DOCX 缓存数据无效。", "The prepared DOCX cache entry is invalid.")) - } - for media in manifest.media { - guard let safePath = EPUBPathResolver.safeArchivePath(media.path), - safePath == media.path, - fileSize(directory.appendingPathComponent(safePath)) == media.bytes else { - throw cacheError(AppText.localized("DOCX 缓存媒体文件无效。", "A prepared DOCX media file is invalid.")) - } - } - let plainText = try String(contentsOf: plainTextURL, encoding: .utf8) - let toc = try JSONDecoder().decode( - [DOCXPreparedTOCItem].self, - from: Data(contentsOf: tocURL, options: .mappedIfSafe) - ).map(\.readerItem) - try? FileManager.default.setAttributes([.modificationDate: Date()], ofItemAtPath: directory.path) - return WebReadableDocument( - html: "", - htmlFileURL: htmlURL, - baseURL: directory, - plainText: plainText, - plainTextLoader: nil, - coverImageURL: nil, - tocItems: toc, - diagnostics: [], - ownedResource: nil - ) - } - - static func prepare( - sourceURL: URL, - directory: URL, - fingerprint: String, - title: String, - cancellationToken: DocumentLoadCancellationToken? - ) throws -> WebReadableDocument { - try cancellationToken?.checkCancellation() - try WebDocumentLoader.unzip( - url: sourceURL, - to: directory, - cancellationToken: cancellationToken - ) - try cancellationToken?.checkCancellation() - let relationships = try WebDocumentLoader.docxStreamingRelationships( - from: directory.appendingPathComponent("word/_rels/document.xml.rels"), - cancellationToken: cancellationToken - ) - let content = try WebDocumentLoader.docxStreamingContent( - from: directory.appendingPathComponent("word/document.xml"), - directory: directory, - relationships: relationships, - mediaReferenceStyle: .relativeToPreparedEntry, - cancellationToken: cancellationToken - ) - try cancellationToken?.checkCancellation() - let body = content.html.isEmpty - ? "\(WebDocumentLoader.escapeHTML(AppText.localized("无法读取 DOCX 内容。", "Unable to read DOCX content.")))
" - : content.html - let html = WebDocumentLoader.pageHTML( - title: title, - body: body, - documentStyles: WebDocumentLoader.docxReaderStyles, - profile: .docx - ) - let plainText = content.plainText.joined(separator: "\n\n") - let toc = content.tocItems.map(DOCXPreparedTOCItem.init) - let htmlURL = directory.appendingPathComponent(htmlName) - let plainTextURL = directory.appendingPathComponent(plainTextName) - let tocURL = directory.appendingPathComponent(tocName) - try Data(html.utf8).write(to: htmlURL, options: .atomic) - try Data(plainText.utf8).write(to: plainTextURL, options: .atomic) - try JSONEncoder().encode(toc).write(to: tocURL, options: .atomic) - let manifest = DOCXPreparedManifest( - schemaVersion: schemaVersion, - fingerprint: fingerprint, - title: title, - htmlSHA256: digest(htmlURL), - plainTextSHA256: digest(plainTextURL), - tocSHA256: digest(tocURL), - media: mediaFiles(in: directory) - ) - try JSONEncoder().encode(manifest).write( - to: directory.appendingPathComponent(manifestName), - options: .atomic - ) - return try load(directory: directory, fingerprint: fingerprint, title: title) - } - - static func cleanup(root: URL, keeping key: String) { - guard let entries = try? FileManager.default.contentsOfDirectory( - at: root, - includingPropertiesForKeys: [.contentModificationDateKey], - options: [.skipsHiddenFiles] - ), entries.count > maximumEntries else { return } - let stale = entries - .filter { $0.lastPathComponent != key } - .sorted { - let left = (try? $0.resourceValues(forKeys: [.contentModificationDateKey]).contentModificationDate) ?? .distantPast - let right = (try? $1.resourceValues(forKeys: [.contentModificationDateKey]).contentModificationDate) ?? .distantPast - return left < right - } - .prefix(entries.count - maximumEntries) - for entry in stale { - try? FileManager.default.removeItem(at: entry) - } - } - - static func fingerprint(url: URL, cancellationToken: DocumentLoadCancellationToken?) throws -> String { - let handle = try FileHandle(forReadingFrom: url.standardizedFileURL) - defer { try? handle.close() } - var hasher = SHA256() - while true { - try cancellationToken?.checkCancellation() - let data = handle.readData(ofLength: 1_048_576) - if data.isEmpty { break } - hasher.update(data: data) - } - return hasher.finalize().map { String(format: "%02x", $0) }.joined() - } - - static func digest(_ url: URL) -> String { - guard let data = try? Data(contentsOf: url, options: .mappedIfSafe) else { return "" } - return digest(data) - } - - static func digest(_ data: Data) -> String { - SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined() - } - - static func mediaFiles(in directory: URL) -> [DOCXPreparedMediaFile] { - let mediaRoot = directory.appendingPathComponent("word/media", isDirectory: true) - guard let enumerator = FileManager.default.enumerator( - at: mediaRoot, - includingPropertiesForKeys: [.isRegularFileKey, .fileSizeKey], - options: [.skipsHiddenFiles] - ) else { return [] } - return enumerator.compactMap { item in - guard let url = item as? URL, - let values = try? url.resourceValues(forKeys: [.isRegularFileKey, .fileSizeKey]), - values.isRegularFile == true else { return nil } - let prefix = directory.standardizedFileURL.path + "/" - guard url.standardizedFileURL.path.hasPrefix(prefix) else { return nil } - let path = String(url.standardizedFileURL.path.dropFirst(prefix.count)) - return DOCXPreparedMediaFile(path: path, bytes: Int64(values.fileSize ?? 0)) - } - } - - static func fileSize(_ url: URL) -> Int64 { - let values = try? url.resourceValues(forKeys: [.isRegularFileKey, .fileSizeKey]) - guard values?.isRegularFile == true else { return -1 } - return Int64(values?.fileSize ?? -1) +extension WebDocumentLoader { + static func validatedDOCXArchiveEntries(_ entries: [String]) throws -> [String] { + try DOCXPreparedCache.selectedArchiveEntries(from: entries) } - static func cacheError(_ description: String) -> Error { - NSError(domain: "LeafReader", code: -4, userInfo: [NSLocalizedDescriptionKey: description]) - } -} - -extension WebDocumentLoader { static func loadPreparedDOCX( url: URL, - cancellationToken: DocumentLoadCancellationToken? + cacheRootURL: URL? = nil, + policy: DOCXPreparedCachePolicy = DOCXPreparedCachePolicy(), + cancellationToken: DocumentLoadCancellationToken? = nil ) throws -> WebReadableDocument { + try cancellationToken?.checkCancellation() let title = url.deletingPathExtension().lastPathComponent + var measurements: [DocumentLoadMeasurement] = [] + + var startedAt = ProcessInfo.processInfo.systemUptime let fingerprint = try DOCXPreparedCache.fingerprint(url: url, cancellationToken: cancellationToken) - let root = try DOCXPreparedCache.root() + measurements.append(measurement(.docxFingerprint, since: startedAt)) + + let root: URL + do { + root = try DOCXPreparedCache.root(override: cacheRootURL) + } catch { + return try loadUncachedStreamingDOCX( + url: url, + measurements: measurements, + cancellationToken: cancellationToken + ) + } let key = DOCXPreparedCache.key(fingerprint: fingerprint, title: title) let destination = root.appendingPathComponent(key, isDirectory: true) - DOCXPreparedCache.lock.lock() - defer { DOCXPreparedCache.lock.unlock() } - try cancellationToken?.checkCancellation() + startedAt = ProcessInfo.processInfo.systemUptime if FileManager.default.fileExists(atPath: destination.path) { do { - let document = try DOCXPreparedCache.load( + try cancellationToken?.checkCancellation() + var hitMeasurements = measurements + hitMeasurements.append(measurement(.docxCacheLookup, since: startedAt)) + let loadStartedAt = ProcessInfo.processInfo.systemUptime + var document = try DOCXPreparedCache.load( directory: destination, fingerprint: fingerprint, - title: title + title: title, + measurements: hitMeasurements ) - DOCXPreparedCache.cleanup(root: root, keeping: key) + document.loadMeasurements.append(measurement(.docxCacheHitLoad, since: loadStartedAt)) + try cancellationToken?.checkCancellation() + DOCXPreparedCache.cleanup(root: root, keeping: key, policy: policy) return document } catch { + if error is CancellationError { throw error } try? FileManager.default.removeItem(at: destination) } } + measurements.append(measurement(.docxCacheLookup, since: startedAt)) - let temporary = root.appendingPathComponent("\(key)-\(UUID().uuidString)", isDirectory: true) - try FileManager.default.createDirectory(at: temporary, withIntermediateDirectories: true) + let temporary = root.appendingPathComponent( + ".building-\(key)-\(UUID().uuidString)", + isDirectory: true + ) do { - _ = try DOCXPreparedCache.prepare( - sourceURL: url, + try FileManager.default.createDirectory(at: temporary, withIntermediateDirectories: true) + try cancellationToken?.checkCancellation() + startedAt = ProcessInfo.processInfo.systemUptime + let archiveEntries = try zipEntryPaths(in: url, cancellationToken: cancellationToken) + let selectedEntries = try validatedDOCXArchiveEntries(archiveEntries) + try unzip( + url: url, + to: temporary, + entryPaths: selectedEntries, + cancellationToken: cancellationToken + ) + measurements.append(measurement(.docxArchiveExtraction, since: startedAt)) + + startedAt = ProcessInfo.processInfo.systemUptime + let relationships = try docxStreamingRelationships( + from: temporary.appendingPathComponent("word/_rels/document.xml.rels"), + cancellationToken: cancellationToken + ) + measurements.append(measurement(.docxRelationshipParse, since: startedAt)) + + startedAt = ProcessInfo.processInfo.systemUptime + let content = try docxStreamingContent( + from: temporary.appendingPathComponent("word/document.xml"), + directory: temporary, + relationships: relationships, + mediaReferenceStyle: .relativeToPreparedEntry, + cancellationToken: cancellationToken + ) + measurements.append(measurement(.docxXMLRender, since: startedAt)) + try? FileManager.default.removeItem(at: temporary.appendingPathComponent("word/document.xml")) + try? FileManager.default.removeItem(at: temporary.appendingPathComponent("word/_rels", isDirectory: true)) + try cancellationToken?.checkCancellation() + + startedAt = ProcessInfo.processInfo.systemUptime + let entryBytes = try DOCXPreparedCache.write( directory: temporary, fingerprint: fingerprint, title: title, - cancellationToken: cancellationToken + content: content ) try cancellationToken?.checkCancellation() - try FileManager.default.moveItem(at: temporary, to: destination) + measurements.append(measurement(.docxCacheCommit, since: startedAt)) + if entryBytes > policy.maximumBytes || policy.maximumEntries < 1 { + let owner = OwnedTemporaryResource(url: temporary) + return try DOCXPreparedCache.load( + directory: temporary, + fingerprint: fingerprint, + title: title, + ownedResource: owner, + measurements: measurements + ) + } + + do { + try FileManager.default.moveItem(at: temporary, to: destination) + } catch { + if FileManager.default.fileExists(atPath: destination.path), + let winner = try? DOCXPreparedCache.load( + directory: destination, + fingerprint: fingerprint, + title: title, + measurements: measurements + ) { + try cancellationToken?.checkCancellation() + try? FileManager.default.removeItem(at: temporary) + DOCXPreparedCache.cleanup(root: root, keeping: key, policy: policy) + return winner + } + throw error + } + DOCXPreparedCache.cleanup(root: root, keeping: key, policy: policy) let document = try DOCXPreparedCache.load( directory: destination, fingerprint: fingerprint, - title: title + title: title, + measurements: measurements ) - DOCXPreparedCache.cleanup(root: root, keeping: key) + try cancellationToken?.checkCancellation() return document } catch { try? FileManager.default.removeItem(at: temporary) + if error is CancellationError { throw error } + if (error as NSError).domain == "LeafReader.UnsafeArchive" { throw error } + return try loadUncachedStreamingDOCX( + url: url, + measurements: measurements, + cancellationToken: cancellationToken + ) + } + } + + private static func loadUncachedStreamingDOCX( + url: URL, + measurements initialMeasurements: [DocumentLoadMeasurement], + cancellationToken: DocumentLoadCancellationToken? + ) throws -> WebReadableDocument { + var measurements = initialMeasurements + var startedAt = ProcessInfo.processInfo.systemUptime + let directory = FileManager.default.temporaryDirectory + .appendingPathComponent("LeafReader-DOCX-\(UUID().uuidString)", isDirectory: true) + try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true) + let owner = OwnedTemporaryResource(url: directory) + do { + try cancellationToken?.checkCancellation() + let archiveEntries = try zipEntryPaths(in: url, cancellationToken: cancellationToken) + let selectedEntries = try validatedDOCXArchiveEntries(archiveEntries) + try unzip( + url: url, + to: directory, + entryPaths: selectedEntries, + cancellationToken: cancellationToken + ) + measurements.append(measurement(.docxArchiveExtraction, since: startedAt)) + + startedAt = ProcessInfo.processInfo.systemUptime + let relationships = try docxStreamingRelationships( + from: directory.appendingPathComponent("word/_rels/document.xml.rels"), + cancellationToken: cancellationToken + ) + measurements.append(measurement(.docxRelationshipParse, since: startedAt)) + + startedAt = ProcessInfo.processInfo.systemUptime + let content = try docxStreamingContent( + from: directory.appendingPathComponent("word/document.xml"), + directory: directory, + relationships: relationships, + cancellationToken: cancellationToken + ) + measurements.append(measurement(.docxXMLRender, since: startedAt)) + let title = url.deletingPathExtension().lastPathComponent + return WebReadableDocument( + html: pageHTML( + title: title, + body: content.html.isEmpty + ? "\(escapeHTML(AppText.localized("无法读取 DOCX 内容。", "Unable to read DOCX content.")))
" + : content.html, + documentStyles: docxReaderStyles, + profile: .docx + ), + htmlFileURL: nil, + baseURL: directory, + plainText: content.plainText.joined(separator: "\n\n"), + plainTextLoader: nil, + coverImageURL: nil, + tocItems: content.tocItems, + diagnostics: [], + ownedResource: owner, + loadMeasurements: measurements + ) + } catch { + owner.release() throw error } } + + private static func measurement( + _ stage: DocumentLoadStage, + since startedAt: TimeInterval + ) -> DocumentLoadMeasurement { + DocumentLoadMeasurement( + stage: stage, + milliseconds: (ProcessInfo.processInfo.systemUptime - startedAt) * 1_000 + ) + } } diff --git a/mac-app/DocumentLoading.swift b/mac-app/DocumentLoading.swift index 1994858..9aca885 100644 --- a/mac-app/DocumentLoading.swift +++ b/mac-app/DocumentLoading.swift @@ -33,6 +33,7 @@ struct WebReadableDocument { let tocItems: [ReaderTOCItem] let diagnostics: [String] let ownedResource: OwnedTemporaryResource? + var loadMeasurements: [DocumentLoadMeasurement] init( html: String, @@ -43,7 +44,8 @@ struct WebReadableDocument { coverImageURL: URL?, tocItems: [ReaderTOCItem], diagnostics: [String], - ownedResource: OwnedTemporaryResource? = nil + ownedResource: OwnedTemporaryResource? = nil, + loadMeasurements: [DocumentLoadMeasurement] = [] ) { self.html = html self.htmlFileURL = htmlFileURL @@ -54,6 +56,7 @@ struct WebReadableDocument { self.tocItems = tocItems self.diagnostics = diagnostics self.ownedResource = ownedResource + self.loadMeasurements = loadMeasurements } } diff --git a/mac-app/ReaderContentBackend.swift b/mac-app/ReaderContentBackend.swift new file mode 100644 index 0000000..e074db0 --- /dev/null +++ b/mac-app/ReaderContentBackend.swift @@ -0,0 +1,215 @@ +import CoreGraphics +import PDFKit +import WebKit + +enum ReaderContentBackendKind: Equatable { + case pdf + case web +} + +enum ReaderZoomStep: Equatable { + case increment + case decrement +} + +enum ReaderPageScrollDirection: Equatable { + case previous + case next +} + +enum ReaderPagePlacement: Equatable { + case top + case bottom +} + +struct ReaderPagedViewportAnchor: Equatable { + let pageIndex: Int + let point: CGPoint +} + +protocol ReaderContentBackend: AnyObject { + var kind: ReaderContentBackendKind { get } + var zoomPercent: Int? { get } + + func focus() + func clearSelection() + @discardableResult func setZoomPercent(_ percent: Int) -> Int? + @discardableResult func stepZoom(_ step: ReaderZoomStep) -> Int? +} + +protocol ReaderPagedBackend: ReaderContentBackend { + var currentPageIndex: Int? { get } + var pageCount: Int { get } + var viewportAnchor: ReaderPagedViewportAnchor? { get } + + @discardableResult func navigate(toPage index: Int, placement: ReaderPagePlacement) -> Bool + @discardableResult func restoreViewportAnchor(_ anchor: ReaderPagedViewportAnchor) -> Bool +} + +protocol ReaderContinuousBackend: ReaderContentBackend { + func scrollByPage(_ direction: ReaderPageScrollDirection) + func scrollToCover() + func scroll(toProgress progress: Double, animated: Bool) +} + +final class PDFKitReaderAdapter: ReaderPagedBackend { + private weak var view: PDFView? + + init(view: PDFView) { + self.view = view + } + + let kind: ReaderContentBackendKind = .pdf + + var currentPageIndex: Int? { + guard let view, let document = view.document, let page = view.currentPage else { return nil } + let index = document.index(for: page) + return index == NSNotFound ? nil : index + } + + var pageCount: Int { + view?.document?.pageCount ?? 0 + } + + var viewportAnchor: ReaderPagedViewportAnchor? { + guard let view, let document = view.document, document.pageCount > 0 else { return nil } + let anchorInView = CGPoint( + x: view.bounds.midX, + y: max(view.bounds.minY, view.bounds.maxY - ReaderSessionPolicy.pdfViewportAnchorTopInset) + ) + guard let page = view.page(for: anchorInView, nearest: true) ?? view.currentPage else { return nil } + let pageIndex = document.index(for: page) + guard pageIndex != NSNotFound else { return nil } + return ReaderPagedViewportAnchor(pageIndex: pageIndex, point: view.convert(anchorInView, to: page)) + } + + var zoomPercent: Int? { + view.map { Int(round($0.scaleFactor * 100)) } + } + + func focus() { + guard let view else { return } + view.window?.makeFirstResponder(view) + } + + func clearSelection() { + view?.clearSelection() + } + + @discardableResult + func setZoomPercent(_ percent: Int) -> Int? { + guard let view else { return nil } + view.autoScales = false + view.scaleFactor = min(max(CGFloat(percent) / 100, 0.1), 8) + return zoomPercent + } + + @discardableResult + func stepZoom(_ step: ReaderZoomStep) -> Int? { + guard let view else { return nil } + let multiplier: CGFloat = step == .increment ? 1.25 : 0.8 + view.autoScales = false + view.scaleFactor = min(max(view.scaleFactor * multiplier, 0.1), 8) + return zoomPercent + } + + @discardableResult + func navigate(toPage index: Int, placement: ReaderPagePlacement) -> Bool { + guard let view, let page = view.document?.page(at: index) else { return false } + DispatchQueue.main.async { [weak view] in + guard let view, view.document?.index(for: page) != NSNotFound else { return } + let bounds = page.bounds(for: view.displayBox) + let destinationY = placement == .top ? bounds.maxY : bounds.minY + view.go(to: PDFDestination(page: page, at: CGPoint(x: bounds.minX, y: destinationY))) + } + return true + } + + @discardableResult + func restoreViewportAnchor(_ anchor: ReaderPagedViewportAnchor) -> Bool { + guard let view, let page = view.document?.page(at: anchor.pageIndex) else { return false } + DispatchQueue.main.async { [weak view] in + guard let view, view.document?.index(for: page) != NSNotFound else { return } + view.go(to: PDFDestination(page: page, at: anchor.point)) + } + return true + } +} + +final class WebKitReaderAdapter: ReaderContinuousBackend { + private weak var view: WKWebView? + private var appliedZoomPercent: Int + + init(view: WKWebView, initialZoomPercent: Int = 100) { + self.view = view + appliedZoomPercent = initialZoomPercent + } + + let kind: ReaderContentBackendKind = .web + var zoomPercent: Int? { appliedZoomPercent } + + func focus() { + guard let view else { return } + view.window?.makeFirstResponder(view) + } + + func clearSelection() { + view?.evaluateJavaScript("window.leafReaderClearSelection && window.leafReaderClearSelection();") + } + + @discardableResult + func setZoomPercent(_ percent: Int) -> Int? { + let clamped = min(max(percent, 60), 220) + appliedZoomPercent = clamped + guard let view else { return nil } + view.pageZoom = 1 + view.evaluateJavaScript(""" + document.documentElement.style.setProperty('--reader-zoom', '\(Double(clamped) / 100)'); + """) + return clamped + } + + @discardableResult + func stepZoom(_ step: ReaderZoomStep) -> Int? { + setZoomPercent(appliedZoomPercent + (step == .increment ? 10 : -10)) + } + + func scrollByPage(_ direction: ReaderPageScrollDirection) { + let sign = direction == .previous ? "-" : "" + view?.evaluateJavaScript( + "window.scrollBy({top: \(sign)Math.max(240, window.innerHeight * 0.86), behavior: 'smooth'});" + ) + } + + func scrollToCover() { + view?.evaluateJavaScript(""" + (() => { + const cover = document.querySelector('section.reader-section[data-leaf-cover="true"]') || document.querySelector('section.reader-section'); + if (cover) { + cover.scrollIntoView({behavior:'smooth', block:'start'}); + } else { + window.scrollTo({top:0, behavior:'smooth'}); + } + })(); + """) + } + + func scroll(toProgress progress: Double, animated: Bool) { + let clampedProgress = min(1, max(0, progress)) + let behavior = animated ? "smooth" : "auto" + view?.evaluateJavaScript(""" + (() => { + const progress = \(clampedProgress); + const scroll = () => { + const scrollHeight = Math.max(1, document.documentElement.scrollHeight - window.innerHeight); + window.scrollTo({ top: scrollHeight * progress, behavior: '\(behavior)' }); + }; + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', () => requestAnimationFrame(scroll), { once: true }); + } else { + requestAnimationFrame(() => requestAnimationFrame(scroll)); + } + })(); + """) + } +} diff --git a/mac-app/ReaderWindowController+Backend.swift b/mac-app/ReaderWindowController+Backend.swift new file mode 100644 index 0000000..67dfcdf --- /dev/null +++ b/mac-app/ReaderWindowController+Backend.swift @@ -0,0 +1,13 @@ +extension ReaderWindowController { + var activeReaderBackend: ReaderContentBackend? { + currentDocumentKind == .pdf ? pdfReaderBackend : webReaderBackend + } + + var activePagedReaderBackend: ReaderPagedBackend? { + activeReaderBackend as? ReaderPagedBackend + } + + var activeContinuousReaderBackend: ReaderContinuousBackend? { + activeReaderBackend as? ReaderContinuousBackend + } +} diff --git a/mac-app/ReaderWindowController+Navigation.swift b/mac-app/ReaderWindowController+Navigation.swift index 9b47683..5e3a5ce 100644 --- a/mac-app/ReaderWindowController+Navigation.swift +++ b/mac-app/ReaderWindowController+Navigation.swift @@ -1,12 +1,12 @@ -import PDFKit +import Foundation extension ReaderWindowController { @objc func applyPageFromField() { guard currentDocumentKind == .pdf, - let document = pdfView.document, - document.pageCount > 0 else { + let backend = activePagedReaderBackend, + backend.pageCount > 0 else { updatePageLabel() - window?.makeFirstResponder(currentDocumentKind == .pdf ? pdfView : webView) + activeReaderBackend?.focus() return } @@ -19,24 +19,22 @@ extension ReaderWindowController { } guard let requestedPage = Int(pageNumberText) else { updatePageLabel() - window?.makeFirstResponder(pdfView) + backend.focus() return } - let targetIndex = min(max(requestedPage, 1), document.pageCount) - 1 - guard let page = document.page(at: targetIndex) else { + let targetIndex = min(max(requestedPage, 1), backend.pageCount) - 1 + guard backend.navigate(toPage: targetIndex, placement: .top) else { updatePageLabel() - window?.makeFirstResponder(pdfView) + backend.focus() return } clearAISelectionForNavigation() - pdfView.go(to: page) lastPageIndex = targetIndex - scrollPageToTop(page) updatePageLabel() saveSession() - window?.makeFirstResponder(pdfView) + backend.focus() } @objc func prevPage() { @@ -63,28 +61,16 @@ extension ReaderWindowController { } func scrollWebPage(direction: Int) { - let sign = direction < 0 ? "-" : "" - webView.evaluateJavaScript("window.scrollBy({top: \(sign)Math.max(240, window.innerHeight * 0.86), behavior: 'smooth'});") + activeContinuousReaderBackend?.scrollByPage(direction < 0 ? .previous : .next) } @objc func goToCover() { clearAISelectionForNavigation() guard currentDocumentKind == .pdf else { - webView.evaluateJavaScript(""" - (() => { - const cover = document.querySelector('section.reader-section[data-leaf-cover="true"]') || document.querySelector('section.reader-section'); - if (cover) { - cover.scrollIntoView({behavior:'smooth', block:'start'}); - } else { - window.scrollTo({top:0, behavior:'smooth'}); - } - })(); - """) + activeContinuousReaderBackend?.scrollToCover() return } - guard let firstPage = pdfView.document?.page(at: 0) else { return } - pdfView.go(to: firstPage) - scrollPageToTop(firstPage) + guard activePagedReaderBackend?.navigate(toPage: 0, placement: .top) == true else { return } updatePageLabel() saveSession() } @@ -102,23 +88,23 @@ extension ReaderWindowController { jumpToWebProgress(storedProgress?.scrollProgress ?? webScrollProgress, animated: true) return } - guard let document = pdfView.document, document.pageCount > 0 else { return } + guard let backend = activePagedReaderBackend, backend.pageCount > 0 else { return } let storedProgress = sessionStore.loadFarthestPDFProgress() - let targetIndex = min(max(storedProgress?.pageIndex ?? currentPageIndex() ?? 0, 0), document.pageCount - 1) - guard let page = document.page(at: targetIndex) else { return } - pdfView.go(to: page) + let targetIndex = min(max(storedProgress?.pageIndex ?? backend.currentPageIndex ?? 0, 0), backend.pageCount - 1) lastPageIndex = targetIndex if let storedProgress, ReaderSessionPolicy.isRestorablePDFScale(storedProgress.scale) { applyReadablePDFScale(storedProgress.scale) } if let anchorPoint = storedProgress?.anchorPoint { - restorePDFViewportAnchor(page: page, point: anchorPoint) + guard backend.restoreViewportAnchor( + ReaderPagedViewportAnchor(pageIndex: targetIndex, point: anchorPoint) + ) else { return } } else { - scrollPageToTop(page) + guard backend.navigate(toPage: targetIndex, placement: .top) else { return } } updatePageLabel() saveSession() - window?.makeFirstResponder(pdfView) + backend.focus() } func jumpToWebProgress(_ progressValue: Double, animated: Bool) { @@ -127,26 +113,11 @@ extension ReaderWindowController { updateWebProgressLabel(progress) scrollWebToProgress(progress, animated: animated) saveSession() - window?.makeFirstResponder(webView) + activeContinuousReaderBackend?.focus() } func scrollWebToProgress(_ progress: Double, animated: Bool) { - let behavior = animated ? "smooth" : "auto" - let script = """ - (() => { - const progress = \(progress); - const scroll = () => { - const scrollHeight = Math.max(1, document.documentElement.scrollHeight - window.innerHeight); - window.scrollTo({ top: scrollHeight * progress, behavior: '\(behavior)' }); - }; - if (document.readyState === 'loading') { - document.addEventListener('DOMContentLoaded', () => requestAnimationFrame(scroll), { once: true }); - } else { - requestAnimationFrame(() => requestAnimationFrame(scroll)); - } - })(); - """ - webView.evaluateJavaScript(script) + activeContinuousReaderBackend?.scroll(toProgress: progress, animated: animated) } @@ -165,12 +136,12 @@ extension ReaderWindowController { direction: EdgePagingPDFView.ScrollPageDirection, targetPlacement: PDFPageNavigationPlacement ) { - guard let document = pdfView.document, document.pageCount > 0 else { return } + guard let backend = activePagedReaderBackend, backend.pageCount > 0 else { return } let readingMode = currentPDFReadingMode() let currentIndex = PDFPagingPolicy.navigationPageIndex( readingMode: readingMode, - viewportPageIndex: currentPDFViewportAnchor()?.pageIndex, - currentPageIndex: currentPageIndex() + viewportPageIndex: backend.viewportAnchor?.pageIndex, + currentPageIndex: backend.currentPageIndex ) ?? 0 let targetIndex: Int switch direction { @@ -180,42 +151,20 @@ extension ReaderWindowController { targetIndex = currentIndex + 1 } guard targetIndex >= 0, - targetIndex < document.pageCount, - let page = document.page(at: targetIndex) else { + targetIndex < backend.pageCount, + backend.navigate( + toPage: targetIndex, + placement: targetPlacement == .top ? .top : .bottom + ) else { updatePageLabel() saveSession() return } - scrollPage(page, to: targetPlacement) lastPageIndex = targetIndex updatePageLabel() saveSession() } - func scrollPageToTop(_ page: PDFPage) { - scrollPage(page, to: .top) - } - - private func scrollPage(_ page: PDFPage, to placement: PDFPageNavigationPlacement) { - DispatchQueue.main.async { [weak self] in - guard let self = self, - self.pdfView.document?.index(for: page) != NSNotFound else { - return - } - let bounds = page.bounds(for: self.pdfView.displayBox) - let destinationY: CGFloat - switch placement { - case .top: - destinationY = bounds.maxY - case .bottom: - destinationY = bounds.minY - } - let destination = PDFDestination(page: page, at: NSPoint(x: bounds.minX, y: destinationY)) - self.pdfView.go(to: destination) - self.updatePageLabel() - } - } - @objc func toggleFullScreen() { window?.toggleFullScreen(nil) } diff --git a/mac-app/ReaderWindowController+Zoom.swift b/mac-app/ReaderWindowController+Zoom.swift index b5c2da2..35c35cb 100644 --- a/mac-app/ReaderWindowController+Zoom.swift +++ b/mac-app/ReaderWindowController+Zoom.swift @@ -3,72 +3,53 @@ import Cocoa extension ReaderWindowController { @objc func zoomIn() { markReaderInteraction() - guard currentDocumentKind == .pdf else { - setWebZoom(webZoomPercent + 10) - return - } - pdfView.autoScales = false - pdfView.scaleFactor = min(pdfView.scaleFactor * 1.25, 8) + guard let applied = activeReaderBackend?.stepZoom(.increment) else { return } + syncZoomPercentFromBackend(applied) updateZoomLabel() saveSession() } @objc func zoomOut() { markReaderInteraction() - guard currentDocumentKind == .pdf else { - setWebZoom(webZoomPercent - 10) - return - } - pdfView.autoScales = false - pdfView.scaleFactor = max(pdfView.scaleFactor * 0.8, 0.1) + guard let applied = activeReaderBackend?.stepZoom(.decrement) else { return } + syncZoomPercentFromBackend(applied) updateZoomLabel() saveSession() } @objc func applyZoomFromField() { markReaderInteraction() - guard currentDocumentKind == .pdf else { - let raw = zoomField.stringValue - .replacingOccurrences(of: "%", with: "") - .replacingOccurrences(of: "％", with: "") - .replacingOccurrences(of: ",", with: "") - .trimmingCharacters(in: .whitespacesAndNewlines) - guard let percent = Int(raw), percent > 0 else { - updateZoomLabel() - return - } - setWebZoom(percent) - return - } let raw = zoomField.stringValue .replacingOccurrences(of: "%", with: "") .replacingOccurrences(of: "％", with: "") .replacingOccurrences(of: ",", with: "") .trimmingCharacters(in: .whitespacesAndNewlines) - guard let percent = Double(raw), percent > 0 else { + guard let percent = Double(raw), percent > 0, + let applied = activeReaderBackend?.setZoomPercent(Int(percent.rounded())) else { updateZoomLabel() return } - pdfView.autoScales = false - pdfView.scaleFactor = min(max(percent, 10), 800) / 100 + syncZoomPercentFromBackend(applied) updateZoomLabel() saveSession() - window?.makeFirstResponder(currentDocumentKind == .pdf ? pdfView : webView) + activeReaderBackend?.focus() } func setWebZoom(_ percent: Int) { - webZoomPercent = min(max(percent, 60), 220) + guard let applied = webReaderBackend.setZoomPercent(percent) else { return } + webZoomPercent = applied zoomField.stringValue = "\(webZoomPercent)%" - applyWebZoomToPage() saveSession() - window?.makeFirstResponder(webView) + webReaderBackend.focus() } func applyWebZoomToPage() { - guard webView != nil else { return } - webView.pageZoom = 1 - webView.evaluateJavaScript(""" - document.documentElement.style.setProperty('--reader-zoom', '\(Double(webZoomPercent) / 100)'); - """) + _ = webReaderBackend.setZoomPercent(webZoomPercent) + } + + private func syncZoomPercentFromBackend(_ percent: Int) { + guard currentDocumentKind != .pdf else { return } + webZoomPercent = percent + zoomField.stringValue = "\(webZoomPercent)%" } } diff --git a/mac-app/ReaderWindowController.swift b/mac-app/ReaderWindowController.swift index 8fbf994..81b8ae6 100644 --- a/mac-app/ReaderWindowController.swift +++ b/mac-app/ReaderWindowController.swift @@ -54,6 +54,8 @@ final class ReaderWindowController: NSWindowController, NSWindowDelegate, PDFVie var pdfView: EdgePagingPDFView! var webView: ReaderWebView! + lazy var pdfReaderBackend = PDFKitReaderAdapter(view: pdfView) + lazy var webReaderBackend = WebKitReaderAdapter(view: webView) let contentArea = NSView() let pdfContainer = ClippingView() let pdfDimOverlay = PassthroughOverlayView() diff --git a/tests/DOCXStreamingParserTests.swift b/tests/DOCXStreamingParserTests.swift index efe05c6..00ac564 100644 --- a/tests/DOCXStreamingParserTests.swift +++ b/tests/DOCXStreamingParserTests.swift @@ -36,6 +36,9 @@ private func writeFixture(root: URL, title: String) throws -> URL { to: relationshipsDirectory.appendingPathComponent("document.xml.rels") ) try Data([0x89, 0x50, 0x4E, 0x47]).write(to: mediaDirectory.appendingPathComponent("image 1.png")) + let docPropsDirectory = root.appendingPathComponent("docProps", isDirectory: true) + try FileManager.default.createDirectory(at: docPropsDirectory, withIntermediateDirectories: true) + try Data("not needed by the reader".utf8).write(to: docPropsDirectory.appendingPathComponent("unused.txt")) return wordDirectory.appendingPathComponent("document.xml") } @@ -44,12 +47,35 @@ private func makeArchive(from root: URL, at archiveURL: URL) throws { let process = Process() process.executableURL = URL(fileURLWithPath: "/usr/bin/zip") process.currentDirectoryURL = root - process.arguments = ["-q", "-r", archiveURL.path, "word"] + process.arguments = ["-q", "-r", archiveURL.path, "word", "docProps"] try process.run() process.waitUntilExit() assert(process.terminationStatus == 0, "fixture archive creation should succeed") } +private func cacheEntries(in root: URL) throws -> [URL] { + guard FileManager.default.fileExists(atPath: root.path) else { return [] } + return try FileManager.default.contentsOfDirectory(at: root, includingPropertiesForKeys: nil) + .filter { !$0.lastPathComponent.hasPrefix(".") } +} + +private final class ConcurrentDOCXResults: @unchecked Sendable { + private let lock = NSLock() + private var storage: [Result