Keep rich text backgrounds inside cards

Author: evan.zhao

Sources/ClipDock/AppCommands.swift

@@ -1164,6 +1164,9 @@ enum PinboardRealQACommand {
         )
         let githubAssets = try PanelQASamples.prepareRealGitHubSampleAssets(appSupportURL: appSupportURL)
         let sourceIconPaths = try PanelQASamples.makeSourceAppIconPaths(outputDirectory: appSupportURL)
+        let terminalRichTextPreviewURL = try PanelQASamples.makeTerminalRichTextPreviewURL(
+            outputDirectory: appSupportURL
+        )
         PanelCardAssetResolver.primePreviewImageCacheForSmoke(paths: [
             imagePreviewURL.path,
             filePreviewURL.path,
@@ -1174,7 +1177,8 @@ enum PinboardRealQACommand {
             imagePayloadPath: imageURL.path,
             filePreviewPath: filePreviewURL.path,
             linkMetadata: githubAssets.linkMetadata,
-            sourceIconPaths: sourceIconPaths
+            sourceIconPaths: sourceIconPaths,
+            terminalRichTextPreviewPath: terminalRichTextPreviewURL.path
         )
         let frame = CommandLineWindowPlacement.bottomPanelFrame(
             arguments: arguments,
@@ -1210,7 +1214,7 @@ enum PinboardRealQACommand {
 
         let mode = mode(arguments: arguments)
         let targetPinboardID = mode == "ai" ? "ai" : "untitled-new"
-        if mode == "overview" || mode == "preview" {
+        if mode == "overview" || mode == "preview" || mode == "verify-rich-text" {
             contentView.updateListState(
                 .success(RustCoreListResult(
                     items: sampleItems,
@@ -1242,6 +1246,11 @@ enum PinboardRealQACommand {
             break
         }
 
+        if mode == "verify-rich-text" {
+            try verifyRichTextCard(contentView: contentView)
+            return
+        }
+
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.25) {
             switch mode {
             case "menu":
@@ -1269,6 +1278,97 @@ enum PinboardRealQACommand {
         CommandLineArgumentReader.value(after: flag, in: arguments) ?? "toolbar"
     }
 
+    @MainActor
+    private static func verifyRichTextCard(contentView: FloatingPanelContentView) throws {
+        let itemID = "panel-smoke-text"
+        RunLoop.main.run(until: Date().addingTimeInterval(0.25))
+        contentView.layoutSubtreeIfNeeded()
+
+        let theme = ClipDockTheme.current(for: contentView)
+        guard let card = contentView.smokeCardBoxes().first(where: { $0.itemID == itemID }) else {
+            throw CommandLineQAError(message: "rich text QA card is not visible")
+        }
+        guard colorAndAlphaDistance(card.fillColor, theme.card.textItemBackgroundColor) < 0.01 else {
+            throw CommandLineQAError(message: "rich text QA card fill does not use themed text surface")
+        }
+        guard let attributed = contentView.smokeBodyAttributedStrings(itemID: itemID).first else {
+            throw CommandLineQAError(message: "rich text QA body attributed string is missing")
+        }
+        let gitRange = (attributed.string as NSString).range(of: "git")
+        guard gitRange.location != NSNotFound else {
+            throw CommandLineQAError(message: "rich text QA body does not contain terminal sample text")
+        }
+        let expectedTerminalBackground = NSColor(deviceWhite: 0.24, alpha: 1)
+        guard let renderedBackground = attributed.attribute(
+            .backgroundColor,
+            at: gitRange.location,
+            effectiveRange: nil
+        ) as? NSColor else {
+            throw CommandLineQAError(message: "rich text QA body did not preserve terminal background")
+        }
+        guard colorAndAlphaDistance(renderedBackground, expectedTerminalBackground) < 0.01 else {
+            throw CommandLineQAError(message: "rich text QA body terminal background changed")
+        }
+        guard let fadeView = descendant(in: card, identifier: "TextBodyBottomFade"),
+              let fadeColors = fadeView as? PanelTextBodyFadeColorProviding
+        else {
+            throw CommandLineQAError(message: "rich text QA bottom fade is missing")
+        }
+        guard colorAndAlphaDistance(
+            fadeColors.smokeFadeBottomColor,
+            theme.card.textBodyFadeBottomColor
+        ) < 0.01 else {
+            throw CommandLineQAError(message: "rich text QA fade does not use themed bottom color")
+        }
+
+        print("rich_text_card_verify=passed")
+        print("card_fill=\(rgbaDescription(card.fillColor))")
+        print("theme_text_surface=\(rgbaDescription(theme.card.textItemBackgroundColor))")
+        print("content_background=\(rgbaDescription(renderedBackground))")
+        print("expected_terminal_background=\(rgbaDescription(expectedTerminalBackground))")
+        print("fade_bottom=\(rgbaDescription(fadeColors.smokeFadeBottomColor))")
+        print("theme_fade_bottom=\(rgbaDescription(theme.card.textBodyFadeBottomColor))")
+    }
+
+    @MainActor
+    private static func descendant(in view: NSView, identifier: String) -> NSView? {
+        if view.identifier?.rawValue == identifier {
+            return view
+        }
+        for subview in view.subviews {
+            if let found = descendant(in: subview, identifier: identifier) {
+                return found
+            }
+        }
+        return nil
+    }
+
+    private static func colorAndAlphaDistance(_ lhs: NSColor, _ rhs: NSColor) -> CGFloat {
+        guard let lhs = lhs.usingColorSpace(.sRGB),
+              let rhs = rhs.usingColorSpace(.sRGB)
+        else {
+            return .greatestFiniteMagnitude
+        }
+
+        return abs(lhs.redComponent - rhs.redComponent)
+            + abs(lhs.greenComponent - rhs.greenComponent)
+            + abs(lhs.blueComponent - rhs.blueComponent)
+            + abs(lhs.alphaComponent - rhs.alphaComponent)
+    }
+
+    private static func rgbaDescription(_ color: NSColor) -> String {
+        guard let rgb = color.usingColorSpace(.sRGB) else {
+            return "unavailable"
+        }
+        return String(
+            format: "%.3f,%.3f,%.3f,%.3f",
+            rgb.redComponent,
+            rgb.greenComponent,
+            rgb.blueComponent,
+            rgb.alphaComponent
+        )
+    }
+
     @MainActor
     private static func installCleanDesktopBackdropIfNeeded(arguments: [String]) {
         guard arguments.contains(cleanDesktopFlag) else {

Sources/ClipDock/AppRuntime.swift

@@ -3391,6 +3391,10 @@ extension FloatingPanelContentView {
         activeListPage.visibleCards()
     }
 
+    func smokeBodyAttributedStrings(itemID: String) -> [NSAttributedString] {
+        activeListPage.visibleBodyAttributedStrings(for: itemID)
+    }
+
     func smokeOrderedCardBoxes() -> [ClipboardItemCardBox] {
         activeListPage.visibleCards()
     }

Sources/ClipDock/PanelItemCardRenderer.swift

@@ -179,6 +179,11 @@ private struct RichTextCardBodyPreview {
     let promotedBackgroundColor: NSColor?
 }
 
+@MainActor
+protocol PanelTextBodyFadeColorProviding {
+    var smokeFadeBottomColor: NSColor { get }
+}
+
 @MainActor
 final class PanelItemCardRenderer {
     private let cardAssetResolver: PanelCardAssetResolver
@@ -210,8 +215,7 @@ final class PanelItemCardRenderer {
         let richTextBodyPreviewPlan = isTextLikeItem
             ? richTextBodyPreview(
                 fallbackText: state.summaryText,
-                assetRequest: state.assetRequest,
-                defaultSurfaceColor: defaultCardBackgroundColor
+                assetRequest: state.assetRequest
             )
             : nil
         let textSurfaceStyle = textCardSurfaceStyle(
@@ -696,8 +700,7 @@ final class PanelItemCardRenderer {
 
     private func richTextBodyPreview(
         fallbackText: String,
-        assetRequest: PanelCardAssetRequest,
-        defaultSurfaceColor: NSColor
+        assetRequest: PanelCardAssetRequest
     ) -> RichTextCardBodyPreview? {
         guard let attributed = cardAssetResolver.richTextPreviewAttributedString(for: assetRequest),
               attributed.length > 0,
@@ -714,16 +717,12 @@ final class PanelItemCardRenderer {
 
         let preview = NSMutableAttributedString(string: "\u{200E}")
         preview.append(attributed.attributedSubstring(from: NSRange(location: 0, length: boundedLength)))
-        let promotedBackgroundColor = ClipboardRichTextPreviewStyler.promotedContentBackgroundColor(
-            preview,
-            surfaceColor: defaultSurfaceColor
-        )
-        let surfaceStyle = textCardSurfaceStyle(promotedBackgroundColor: promotedBackgroundColor)
+        let surfaceStyle = textCardSurfaceStyle(promotedBackgroundColor: nil)
         let displayPlan = ClipboardRichTextPreviewStyler.inlineSurfaceDisplayPlan(
             preview,
             bodyColor: surfaceStyle.bodyTextColor,
             surfaceColor: surfaceStyle.backgroundColor,
-            promotedBackgroundColor: promotedBackgroundColor
+            promotesBackgroundToSurface: false
         )
         return RichTextCardBodyPreview(
             attributedString: displayPlan.attributedString,
@@ -1396,7 +1395,7 @@ final class PanelItemCardBodyTextView: NSView {
 }
 
 @MainActor
-private final class PanelTextBodyFadeView: NSView {
+private final class PanelTextBodyFadeView: NSView, PanelTextBodyFadeColorProviding {
     private let topColor: NSColor
     private let middleColor: NSColor
     private let footerColor: NSColor
@@ -1420,6 +1419,10 @@ private final class PanelTextBodyFadeView: NSView {
         nil
     }
 
+    var smokeFadeBottomColor: NSColor {
+        bottomColor
+    }
+
     override func draw(_ dirtyRect: NSRect) {
         guard !bounds.isEmpty else { return }
         let colors = [

Sources/ClipDock/PanelItemCollectionSurface.swift

@@ -163,6 +163,10 @@ final class PanelItemCollectionCell: NSCollectionViewItem {
         view.needsLayout = true
     }
 
+    func bodyAttributedStringsForSmoke() -> [NSAttributedString] {
+        artifacts?.bodyLabels.map(\.attributedStringForTesting) ?? []
+    }
+
     func cleanupForRemoval() {
         cleanupHostedCard()
     }
@@ -484,6 +488,18 @@ final class PanelItemCollectionSurface: NSObject,
         visibleCells().compactMap(\.hostedCard)
     }
 
+    func visibleBodyAttributedStrings(for itemID: String) -> [NSAttributedString] {
+        guard let index = indexByID[itemID] else { return [] }
+        let indexPath = IndexPath(item: index, section: 0)
+        guard collectionView.indexPathsForVisibleItems().contains(indexPath),
+              let cell = collectionView.item(at: indexPath) as? PanelItemCollectionCell,
+              cell.itemID == itemID
+        else {
+            return []
+        }
+        return cell.bodyAttributedStringsForSmoke()
+    }
+
     func collectionDocumentWidth() -> CGFloat {
         updateCollectionFrameWidth()
         return collectionView.frame.width

Sources/ClipDock/PanelPreviewUI.swift

@@ -44,16 +44,18 @@ enum ClipboardRichTextPreviewStyler {
         bodyColor: NSColor,
         surfaceColor: NSColor,
         linkColor: NSColor = .linkColor,
-        promotedBackgroundColor: NSColor? = nil
+        promotedBackgroundColor: NSColor? = nil,
+        promotesBackgroundToSurface: Bool = true
     ) -> DisplayPlan {
         let mutable = NSMutableAttributedString(attributedString: source)
         let fullRange = NSRange(location: 0, length: mutable.length)
         guard fullRange.length > 0 else {
             return DisplayPlan(attributedString: mutable, promotedBackgroundColor: nil)
         }
 
-        let promotedBackgroundColor = promotedBackgroundColor
-            ?? contentBackgroundColor(in: source, surfaceColor: surfaceColor)
+        let promotedBackgroundColor = promotesBackgroundToSurface
+            ? (promotedBackgroundColor ?? contentBackgroundColor(in: source, surfaceColor: surfaceColor))
+            : nil
         mutable.enumerateAttributes(in: fullRange, options: []) { attributes, range, _ in
             let originalForeground = attributes[.foregroundColor] as? NSColor
             let preferredFallback = attributes[.link] == nil ? bodyColor : linkColor

Sources/ClipDock/QASupport.swift

@@ -19,6 +19,14 @@ enum PanelQASamples {
         let imageURL: URL
     }
 
+    private static let terminalRichTextSampleText = """
+    Last login: Sat May 23
+    16:07:44 on ttys006
+    ~/IdeaProjects
+    git clone https://github.com/appdev/siyuan-unlock.git
+    Cloning into 'siyuan-unlock'...
+    """
+
     private static let sourceAppIconFixtures: [SourceAppIconFixture] = [
         SourceAppIconFixture(
             key: "Chrome",
@@ -559,6 +567,37 @@ enum PanelQASamples {
         return url
     }
 
+    static func makeTerminalRichTextPreviewURL(outputDirectory: URL) throws -> URL {
+        let attributed = NSMutableAttributedString(
+            string: terminalRichTextSampleText,
+            attributes: [
+                .font: NSFont.monospacedSystemFont(ofSize: 13, weight: .regular),
+                .foregroundColor: NSColor.white,
+                .backgroundColor: NSColor(deviceWhite: 0.24, alpha: 1)
+            ]
+        )
+        attributed.addAttribute(
+            .foregroundColor,
+            value: NSColor.systemGreen,
+            range: (terminalRichTextSampleText as NSString).range(of: "git")
+        )
+        attributed.addAttribute(
+            .foregroundColor,
+            value: NSColor.systemBlue,
+            range: (terminalRichTextSampleText as NSString).range(of: "~/IdeaProjects")
+        )
+
+        let data = try attributed.data(
+            from: NSRange(location: 0, length: attributed.length),
+            documentAttributes: [.documentType: NSAttributedString.DocumentType.rtf]
+        )
+        let directory = outputDirectory.appendingPathComponent("styled-text", isDirectory: true)
+        try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+        let url = directory.appendingPathComponent("terminal-paste.rtf")
+        try data.write(to: url, options: .atomic)
+        return url
+    }
+
     @MainActor
     static func makePanelInteractionSmokeImageURL(outputDirectory: URL) throws -> URL {
         let image = NSImage(size: NSSize(width: 360, height: 220))
@@ -588,20 +627,27 @@ enum PanelQASamples {
         imagePayloadPath: String? = nil,
         filePreviewPath: String? = nil,
         linkMetadata: RustLinkMetadataSummary? = nil,
-        sourceIconPaths: [String: String] = [:]
+        sourceIconPaths: [String: String] = [:],
+        terminalRichTextPreviewPath: String? = nil
     ) -> [RustClipboardItemSummary] {
         let now = Int64(Date().timeIntervalSince1970 * 1000)
+        let firstText = terminalRichTextPreviewPath == nil
+            ? "ClipDock 提供本地剪贴板历史、快速预览与 Pinboard 分类管理，适合高频跨应用工作流。"
+            : terminalRichTextSampleText
         var items = [
             makeItem(
                 id: "panel-smoke-text",
                 itemType: "text",
-                summary: "ClipDock 提供本地剪贴板历史、快速预览与 Pinboard 分类管理，适合高频跨应用工作流。",
-                primaryText: "ClipDock 提供本地剪贴板历史、快速预览与 Pinboard 分类管理，适合高频跨应用工作流。",
-                sourceAppName: "备忘录",
+                summary: firstText,
+                primaryText: firstText,
+                sourceAppName: terminalRichTextPreviewPath == nil ? "备忘录" : "终端",
                 timestamp: now,
                 contentHash: "panel-smoke-panel-smoke-text",
-                sourceAppIconPath: sourceIconPaths["Notes"],
-                sizeBytes: 112
+                sourceAppIconPath: terminalRichTextPreviewPath == nil
+                    ? sourceIconPaths["Notes"]
+                    : sourceIconPaths["Terminal"],
+                previewAssetPath: terminalRichTextPreviewPath,
+                sizeBytes: Int64(firstText.utf8.count)
             ),
             makeItem(
                 id: "panel-smoke-image",

Tests/ClipboardPanelAppTests/PanelPreviewRichTextStylerTests.swift

@@ -68,6 +68,31 @@ struct PanelPreviewRichTextStylerTests {
         #expect(source.attribute(.backgroundColor, at: 0, effectiveRange: nil) != nil)
     }
 
+    @Test
+    func inlineSurfaceCanPreserveContentBackgroundWithoutPromotingIt() throws {
+        let terminalBackground = NSColor(calibratedWhite: 0.24, alpha: 1)
+        let source = NSAttributedString(
+            string: "git clone https://github.com/appdev/siyuan-unlock.git",
+            attributes: [
+                .foregroundColor: NSColor.white,
+                .backgroundColor: terminalBackground
+            ]
+        )
+
+        let plan = ClipboardRichTextPreviewStyler.inlineSurfaceDisplayPlan(
+            source,
+            bodyColor: .black,
+            surfaceColor: .white,
+            promotesBackgroundToSurface: false
+        )
+        let background = try #require(
+            plan.attributedString.attribute(.backgroundColor, at: 0, effectiveRange: nil) as? NSColor
+        )
+
+        #expect(plan.promotedBackgroundColor == nil)
+        #expect(colorAndAlphaDistance(background, terminalBackground) < 0.01)
+    }
+
     @Test
     func suppressingDefaultBackgroundPreservesSyntaxColorsAndMapsDefaultLinks() {
         let bodyColor = NSColor(calibratedWhite: 0.88, alpha: 1)