iOS: complete chip files gallery — dedup, folders, streaming viewer, previews, gallery UX, QoL

Packages/Shared/CmuxAgentChat/Sources/CmuxAgentChat/Artifacts/ArtifactByteReader.swift

@@ -7,6 +7,10 @@ import UniformTypeIdentifiers
 /// Authorization is intentionally outside this type. Callers must scope-check the
 /// requested path before invoking these methods.
 public struct ArtifactByteReader: Sendable {
+    /// Maximum immediate children returned by one directory-list request.
+    public static let maximumDirectoryEntryCount = 500
+    private static let utf8SniffByteCount = 8 * 1024
+
     /// Filesystem/decoder failures surfaced by artifact RPC handlers.
     public enum Error: Swift.Error, Sendable {
         /// The scoped path no longer exists or cannot be statted.
@@ -96,37 +100,45 @@ public struct ArtifactByteReader: Sendable {
         )
     }
 
-    /// Lists up to 500 immediate children for an already-authorized directory.
+    /// Lists up to ``maximumDirectoryEntryCount`` immediate children for an
+    /// already-authorized directory.
+    ///
+    /// One readdir pass collects child names; per-child filesystem metadata is
+    /// read only for the capped entries that the listing actually returns.
     public func list(path: String) throws -> ChatArtifactDirectoryListing {
         let stat = try stat(path: path)
         guard stat.isDirectory else { throw Error.fileNotFound }
-        let url = URL(fileURLWithPath: path, isDirectory: true)
-        let entries = try FileManager.default.contentsOfDirectory(
-            at: url,
-            includingPropertiesForKeys: [.isDirectoryKey, .fileSizeKey],
-            options: []
-        )
-        let listed = try entries
-            .sorted { $0.lastPathComponent.localizedStandardCompare($1.lastPathComponent) == .orderedAscending }
-            .prefix(500)
-            .map { entry -> ChatArtifactDirectoryEntry in
+        let names = try FileManager.default.contentsOfDirectory(atPath: path)
+        let sortedNames = names.sorted {
+            $0.localizedStandardCompare($1) == .orderedAscending
+        }
+        let directoryURL = URL(fileURLWithPath: path, isDirectory: true)
+        let listed = try sortedNames
+            .prefix(Self.maximumDirectoryEntryCount)
+            .map { name -> ChatArtifactDirectoryEntry in
+                let entry = directoryURL.appendingPathComponent(name)
                 let values = try entry.resourceValues(forKeys: [.isDirectoryKey, .fileSizeKey])
                 let isDirectory = values.isDirectory ?? false
                 return ChatArtifactDirectoryEntry(
-                    name: entry.lastPathComponent,
+                    name: name,
                     isDirectory: isDirectory,
                     size: Int64(values.fileSize ?? 0),
                     kind: kind(path: entry.path, isDirectory: isDirectory)
                 )
             }
-        return ChatArtifactDirectoryListing(entries: listed)
+        return ChatArtifactDirectoryListing(
+            entries: listed,
+            isTruncated: names.count > Self.maximumDirectoryEntryCount
+        )
     }
 
-    /// Infers preview category from a path extension and directory flag.
+    /// Infers preview category from a path extension and a bounded UTF-8 sniff.
     public func kind(path: String, isDirectory: Bool) -> ChatArtifactKind {
         if isDirectory { return .directory }
-        guard let type = UTType(filenameExtension: URL(fileURLWithPath: path).pathExtension) else {
-            return .binary
+        let fileExtension = URL(fileURLWithPath: path).pathExtension
+        let type = fileExtension.isEmpty ? nil : UTType(filenameExtension: fileExtension)
+        guard let type, !type.isDynamic else {
+            return isUTF8Text(path: path) ? .text : .binary
         }
         if type.conforms(to: .image) { return .image }
         if type.conforms(to: .text) || type.conforms(to: .sourceCode) || type.conforms(to: .json) {
@@ -135,6 +147,80 @@ public struct ArtifactByteReader: Sendable {
         return .binary
     }
 
+    private func isUTF8Text(path: String) -> Bool {
+        guard let handle = FileHandle(forReadingAtPath: path) else {
+            return false
+        }
+        defer { try? handle.close() }
+        let bytes: Data
+        do {
+            bytes = try handle.read(upToCount: Self.utf8SniffByteCount + 1) ?? Data()
+        } catch {
+            return false
+        }
+        let sample = Data(bytes.prefix(Self.utf8SniffByteCount))
+        if String(data: sample, encoding: .utf8) != nil {
+            return true
+        }
+        guard bytes.count > Self.utf8SniffByteCount else {
+            return false
+        }
+        return hasValidUTF8PrefixEndingInPartialScalar(sample)
+    }
+
+    private func hasValidUTF8PrefixEndingInPartialScalar(_ data: Data) -> Bool {
+        let bytes = Array(data)
+        guard !bytes.isEmpty else { return false }
+        let earliestCandidate = max(0, bytes.count - 4)
+        for start in stride(from: bytes.count - 1, through: earliestCandidate, by: -1) {
+            guard let expectedLength = utf8ScalarLength(leadingByte: bytes[start]) else {
+                continue
+            }
+            let actualLength = bytes.count - start
+            guard actualLength < expectedLength,
+                  utf8PartialScalarBytesAreValid(Array(bytes[start...])) else {
+                continue
+            }
+            let prefix = Data(bytes[..<start])
+            return String(data: prefix, encoding: .utf8) != nil
+        }
+        return false
+    }
+
+    private func utf8ScalarLength(leadingByte: UInt8) -> Int? {
+        switch leadingByte {
+        case 0xC2...0xDF:
+            return 2
+        case 0xE0...0xEF:
+            return 3
+        case 0xF0...0xF4:
+            return 4
+        default:
+            return nil
+        }
+    }
+
+    private func utf8PartialScalarBytesAreValid(_ bytes: [UInt8]) -> Bool {
+        guard let leadingByte = bytes.first else { return false }
+        for byte in bytes.dropFirst() where byte & 0xC0 != 0x80 {
+            return false
+        }
+        guard bytes.count > 1 else { return true }
+        let firstContinuation = bytes[1]
+        switch leadingByte {
+        case 0xE0:
+            return firstContinuation >= 0xA0
+        case 0xED:
+            return firstContinuation <= 0x9F
+        case 0xF0:
+            return firstContinuation >= 0x90
+        case 0xF4:
+            return firstContinuation <= 0x8F
+        default:
+            return true
+        }
+    }
+
     private func attributes(path: String) throws -> [FileAttributeKey: Any] {
         do {
             return try FileManager.default.attributesOfItem(atPath: path)

Packages/Shared/CmuxAgentChat/Sources/CmuxAgentChat/Artifacts/ChatArtifactDirectoryListing.swift

@@ -2,11 +2,35 @@
 public struct ChatArtifactDirectoryListing: Sendable, Equatable, Codable {
     /// Directory entries sorted by name.
     public let entries: [ChatArtifactDirectoryEntry]
+    /// Whether additional immediate children were omitted by the server cap.
+    public let isTruncated: Bool
 
     /// Creates a directory listing.
     ///
-    /// - Parameter entries: Directory entries sorted by name.
-    public init(entries: [ChatArtifactDirectoryEntry]) {
+    /// - Parameters:
+    ///   - entries: Directory entries sorted by name.
+    ///   - isTruncated: Whether the server omitted additional entries.
+    public init(entries: [ChatArtifactDirectoryEntry], isTruncated: Bool = false) {
         self.entries = entries
+        self.isTruncated = isTruncated
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case entries
+        case isTruncated = "is_truncated"
+    }
+
+    /// Decodes listings from current and legacy hosts.
+    public init(from decoder: any Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        entries = try container.decode([ChatArtifactDirectoryEntry].self, forKey: .entries)
+        isTruncated = try container.decodeIfPresent(Bool.self, forKey: .isTruncated) ?? false
+    }
+
+    /// Encodes the capped-list metadata for mobile clients.
+    public func encode(to encoder: any Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(entries, forKey: .entries)
+        try container.encode(isTruncated, forKey: .isTruncated)
     }
 }

Packages/Shared/CmuxAgentChat/Sources/CmuxAgentChat/Artifacts/ChatArtifactGalleryBuilder.swift

@@ -0,0 +1,179 @@
+import Foundation
+
+/// Builds stat-enriched, append-only pages from one transcript index snapshot.
+public struct ChatArtifactGalleryBuilder: Sendable {
+    /// Creates a gallery page builder.
+    public init() {}
+
+    /// Builds one sectioned or flat search page.
+    ///
+    /// - Parameters:
+    ///   - sessionID: Session represented by the artifact index.
+    ///   - items: De-duplicated transcript artifact references.
+    ///   - orderedItems: Optional generation-cached stable ordering of `items`.
+    ///   - generation: Stable snapshot generation carried by page cursors.
+    ///   - cursor: Per-section positions after which paging continues.
+    ///   - pageSize: Maximum entries to stat and include per section.
+    ///   - query: Optional basename or path search.
+    ///   - includeDirectories: Whether directory references are eligible for
+    ///     rows. This defaults to `false` for clients without folder capability.
+    /// - Returns: One gallery page with filesystem metadata.
+    public func page(
+        sessionID: String,
+        items: [ChatArtifactIndexedReference],
+        orderedItems: [ChatArtifactIndexedReference]? = nil,
+        generation: String,
+        cursor: ChatArtifactGalleryCursor?,
+        pageSize: Int,
+        query: String?,
+        includeDirectories: Bool = false
+    ) -> ChatArtifactGalleryPage {
+        if let cursor, cursor.generation != generation {
+            return ChatArtifactGalleryPage(
+                sessionID: sessionID,
+                generation: generation,
+                requiresPagingRestart: true
+            )
+        }
+        let ordering = ChatArtifactGalleryOrdering()
+        let stableItems = orderedItems ?? ordering.sorted(items)
+        let normalizedQuery = query?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let isSearch = normalizedQuery?.isEmpty == false
+        let createdCandidates: [ChatArtifactIndexedReference]
+        let attachedCandidates: [ChatArtifactIndexedReference]
+        let referencedCandidates: [ChatArtifactIndexedReference]
+        if let normalizedQuery, !normalizedQuery.isEmpty {
+            createdCandidates = []
+            attachedCandidates = []
+            referencedCandidates = ordering.matching(stableItems, query: normalizedQuery)
+        } else {
+            createdCandidates = stableItems.filter { $0.provenance == .created }
+            attachedCandidates = stableItems.filter { $0.provenance == .attached }
+            referencedCandidates = stableItems.filter { $0.provenance == .referenced }
+        }
+        let count = max(1, pageSize)
+        let starts = pageStarts(
+            cursor: cursor,
+            created: createdCandidates,
+            attached: attachedCandidates,
+            referenced: referencedCandidates,
+            ordering: ordering
+        )
+        // Sequential fill: a page extends the grouped list strictly at its
+        // bottom (created, then attached, then referenced), so a
+        // scroll-triggered load can never insert rows into a group the user
+        // has already scrolled past.
+        var remaining = count
+        let pageCreated = Array(createdCandidates.dropFirst(starts.created).prefix(remaining))
+        remaining -= pageCreated.count
+        let pageAttached = Array(attachedCandidates.dropFirst(starts.attached).prefix(remaining))
+        remaining -= pageAttached.count
+        let pageReferenced = Array(referencedCandidates.dropFirst(starts.referenced).prefix(remaining))
+        let nextCreatedOffset = starts.created + pageCreated.count
+        let nextAttachedOffset = starts.attached + pageAttached.count
+        let nextReferencedOffset = starts.referenced + pageReferenced.count
+        let nextCursor: String?
+        if nextCreatedOffset < createdCandidates.count
+            || nextAttachedOffset < attachedCandidates.count
+            || nextReferencedOffset < referencedCandidates.count {
+            let last = pageReferenced.last
+            nextCursor = try? ChatArtifactGalleryCursor(
+                generation: generation,
+                seq: last?.lastReferencedSeq ?? cursor?.seq ?? .max,
+                path: last?.path ?? cursor?.path ?? "",
+                createdOffset: nextCreatedOffset,
+                attachedOffset: nextAttachedOffset,
+                referencedOffset: nextReferencedOffset
+            ).token()
+        } else {
+            nextCursor = nil
+        }
+
+        return ChatArtifactGalleryPage(
+            sessionID: sessionID,
+            created: isSearch ? [] : statItems(pageCreated, includeDirectories: includeDirectories),
+            createdTotal: createdCandidates.count,
+            attached: isSearch ? [] : statItems(pageAttached, includeDirectories: includeDirectories),
+            attachedTotal: attachedCandidates.count,
+            referenced: statItems(pageReferenced, includeDirectories: includeDirectories),
+            referencedTotal: referencedCandidates.count,
+            nextCursor: nextCursor,
+            generation: generation
+        )
+    }
+
+    private func pageStarts(
+        cursor: ChatArtifactGalleryCursor?,
+        created: [ChatArtifactIndexedReference],
+        attached: [ChatArtifactIndexedReference],
+        referenced: [ChatArtifactIndexedReference],
+        ordering: ChatArtifactGalleryOrdering
+    ) -> (created: Int, attached: Int, referenced: Int) {
+        guard let cursor else { return (0, 0, 0) }
+        if let createdOffset = cursor.createdOffset,
+           let attachedOffset = cursor.attachedOffset,
+           let referencedOffset = cursor.referencedOffset {
+            return (
+                min(max(0, createdOffset), created.count),
+                min(max(0, attachedOffset), attached.count),
+                min(max(0, referencedOffset), referenced.count)
+            )
+        }
+        let remaining = ordering.items(referenced, strictlyAfter: cursor)
+        return (created.count, attached.count, referenced.count - remaining.count)
+    }
+
+    /// Counts immediate children for a gallery directory row without sorting
+    /// or per-entry metadata, stopping at the shared listing limit so the cost
+    /// never scales past the cap for large folders.
+    private func directoryChildCount(path: String) -> (count: Int, isCapped: Bool)? {
+        guard let enumerator = FileManager.default.enumerator(
+            at: URL(fileURLWithPath: path, isDirectory: true),
+            includingPropertiesForKeys: [],
+            options: [.skipsSubdirectoryDescendants]
+        ) else {
+            return nil
+        }
+        var count = 0
+        while enumerator.nextObject() != nil {
+            count += 1
+            if count > ArtifactByteReader.maximumDirectoryEntryCount {
+                return (count: ArtifactByteReader.maximumDirectoryEntryCount, isCapped: true)
+            }
+        }
+        return (count: count, isCapped: false)
+    }
+
+    private func statItems(
+        _ references: [ChatArtifactIndexedReference],
+        includeDirectories: Bool
+    ) -> [ChatArtifactGalleryItem] {
+        let reader = ArtifactByteReader()
+        return references.compactMap { reference in
+            do {
+                let stat = try reader.stat(path: reference.path)
+                guard includeDirectories || !stat.isDirectory else { return nil }
+                let children = stat.isDirectory ? directoryChildCount(path: reference.path) : nil
+                return ChatArtifactGalleryItem(
+                    path: reference.path,
+                    kind: stat.kind,
+                    displayName: URL(fileURLWithPath: reference.path).lastPathComponent,
+                    size: stat.size,
+                    modifiedAt: stat.modifiedAt,
+                    exists: stat.exists,
+                    childCount: children?.count,
+                    childCountIsCapped: children?.isCapped ?? false,
+                    provenance: reference.provenance
+                )
+            } catch {
+                return ChatArtifactGalleryItem(
+                    path: reference.path,
+                    kind: reader.kind(path: reference.path, isDirectory: false),
+                    displayName: URL(fileURLWithPath: reference.path).lastPathComponent,
+                    exists: false,
+                    provenance: reference.provenance
+                )
+            }
+        }
+    }
+}