Add attributed string postprocessor

The MarkupParser only runs when the input string changes, so there
is no way to add attributes whose source is external to the content. This adds a
postprocessing stage that runs after parsing and is re-invoked
whenever either the content or the postprocessor itself changes,
enabling content-independent customization like search highlighting
in both InlineText and StructuredText.

Author: tseylerd

Examples/TextualDemo/TextualDemo/DemoSplitView.swift

@@ -10,6 +10,7 @@ enum DemoItem: String, CaseIterable, Hashable {
   case attachmentLoaders
   case tables
   case mathExpressions
+  case postprocessor
   case gitHubReadme
 }
 
@@ -40,6 +41,8 @@ extension DemoItem {
       return Label("Tables", systemImage: "tablecells")
     case .mathExpressions:
       return Label("Math Expressions", systemImage: "x.squareroot")
+    case .postprocessor:
+      return Label("Postprocessor", systemImage: "highlighter")
     case .gitHubReadme:
       return Label("GitHub `README`", systemImage: "doc.text")
     }
@@ -75,6 +78,9 @@ extension DemoItem {
     case .mathExpressions:
       MathExpressionDemo()
         .navigationTitle("Math Expressions")
+    case .postprocessor:
+      PostprocessorDemo()
+        .navigationTitle("Postprocessor")
     case .gitHubReadme:
       GitHubReadmeDemo()
         .navigationTitle("GitHub README")

Examples/TextualDemo/TextualDemo/PostprocessorDemo.swift

@@ -0,0 +1,67 @@
+import SwiftUI
+import Textual
+
+struct PostprocessorDemo: View {
+  @State private var query = "text"
+
+  var body: some View {
+    Form {
+      Section("Search Highlighter") {
+        TextField("Search", text: $query)
+      }
+
+      Section("Inline Text") {
+        InlineText(
+          markdown: """
+            Textual renders **rich attributed text** in SwiftUI. Use a postprocessor \
+            to highlight ranges independently of the markup content.
+            """
+        )
+        .textual.attributedStringPostprocessor(SearchHighlighter(query: query))
+        .textual.textSelection(.enabled)
+      }
+
+      Section("Structured Text") {
+        StructuredText(
+          markdown: """
+            ## Overview
+
+            A postprocessor runs **after parsing and attachment resolution**, so it can
+            add attributes whose source is external to the text — for example, a
+            live search query.
+
+            - Highlights update without re-parsing
+            - Ranges are valid against the full attributed string
+            """
+        )
+        .textual.attributedStringPostprocessor(SearchHighlighter(query: query))
+        .textual.textSelection(.enabled)
+      }
+    }
+    .formStyle(.grouped)
+  }
+}
+
+private struct SearchHighlighter: AttributedStringPostprocessor {
+  let query: String
+
+  func postprocess(input: AttributedString) -> AttributedString {
+    guard !query.isEmpty else {
+      return input
+    }
+
+    var output = input
+    var start = output.startIndex
+
+    while let range = output[start...].range(of: query, options: .caseInsensitive) {
+      output[range].backgroundColor = .yellow.opacity(0.4)
+      start = range.upperBound
+    }
+
+    return output
+  }
+}
+
+#Preview {
+  PostprocessorDemo()
+}

README.md

@@ -202,11 +202,11 @@ Here's a practical example, a custom heading style that adds a subtle underline
 ```swift
 struct CustomHeadingStyle: StructuredText.HeadingStyle {
   private static let fontScales: [CGFloat] = [2, 1.5, 1.25, 1, 0.875, 0.85]
-  
+
   func makeBody(configuration: Configuration) -> some View {
     let headingLevel = min(configuration.headingLevel, 6)
     let fontScale = Self.fontScales[headingLevel - 1]
-    
+
     VStack(alignment: .leading, spacing: 0) {
       configuration.label
         .textual.fontScale(fontScale)
@@ -287,6 +287,41 @@ StructuredText(markdown: content)
 The protocol requires implementations for all block types, list markers, and inline styles. This ensures visual
 consistency across your entire document.
 
+### Postprocessing Attributed Content
+
+The `MarkupParser` only runs when the input string changes, so attributes whose source is external
+to the content (a search query, a live filter) belong in a postprocessor. A
+postprocessor transforms the parsed `AttributedString` after attachments are resolved and is
+re-invoked whenever either the parsed string or the postprocessor itself changes.
+
+Apply a postprocessor using the `textual.attributedStringPostprocessor(_:)` modifier:
+
+```swift
+struct SearchHighlighter: AttributedStringPostprocessor {
+  let query: String
+
+  func postprocess(input: AttributedString) -> AttributedString {
+    var output = input
+    var start = output.startIndex
+
+    while let range = output[start...].range(of: query, options: .caseInsensitive) {
+      output[range].backgroundColor = .yellow.opacity(0.4)
+      start = range.upperBound
+    }
+
+    return output
+  }
+}
+
+InlineText(markdown: "Hello, world")
+  .textual.attributedStringPostprocessor(SearchHighlighter(query: "world"))
+```
+
+The postprocessor receives the full attributed string with attachments already resolved; ranges
+are valid against that complete string. Equality (from `Hashable`) drives invalidation, so the
+conforming type must reflect any state that affects output in its `==` implementation — typically
+by storing that state as stored properties of a value type.
+
 ## Demos
 
 This repository includes a demo app that showcases all of Textual's features, from inline formatting and custom emoji

Sources/Textual/InlineText/InlineText.swift

@@ -112,9 +112,11 @@ public struct InlineText: View {
 
   public var body: some View {
     WithAttachments(attributedString) {
-      WithInlineStyle($0) {
-        TextFragment($0)
-          .modifier(TextSelectionInteraction())
+      WithAttributedStringPostprocessor($0) {
+        WithInlineStyle($0) {
+          TextFragment($0)
+            .modifier(TextSelectionInteraction())
+        }
       }
     }
     .coordinateSpace(.textContainer)

Sources/Textual/Internal/Postprocessing/AnyAttributedStringPostprocessor.swift

@@ -0,0 +1,39 @@
+import SwiftUI
+
+// MARK: - Overview
+//
+// `AnyAttributedStringPostprocessor` is a type-erased wrapper around any
+// `AttributedStringPostprocessor`, used to store the postprocessor in `EnvironmentValues` while
+// preserving `Equatable` semantics for `onChange`-driven invalidation.
+
+struct AnyAttributedStringPostprocessor: AttributedStringPostprocessor {
+  private let base: any AttributedStringPostprocessor
+
+  init(_ base: some AttributedStringPostprocessor) {
+    self.base = base
+  }
+
+  func postprocess(input: AttributedString) -> AttributedString {
+    base.postprocess(input: input)
+  }
+
+  static func == (lhs: Self, rhs: Self) -> Bool {
+    AnyHashable(lhs.base) == AnyHashable(rhs.base)
+  }
+
+  func hash(into hasher: inout Hasher) {
+    hasher.combine(base)
+  }
+}
+
+extension EnvironmentValues {
+  @Entry var attributedStringPostprocessor: AnyAttributedStringPostprocessor = .init(
+    IdentityAttributedStringPostprocessor()
+  )
+}
+
+fileprivate struct IdentityAttributedStringPostprocessor: AttributedStringPostprocessor {
+  func postprocess(input: AttributedString) -> AttributedString {
+    input
+  }
+}

Sources/Textual/Internal/Postprocessing/WithAttributedStringPostprocessor.swift

@@ -0,0 +1,35 @@
+import SwiftUI
+
+// MARK: - Overview
+//
+// `WithAttributedStringPostprocessor` applies an `AttributedStringPostprocessor` from the
+// environment to an `AttributedString` before it reaches the rendering pipeline.
+//
+// The view reads `attributedStringPostprocessor` from the environment, then produces a processed
+// copy of the attributed string by calling `postprocess(input:)`.
+//
+// Processing is recomputed whenever the input or the postprocessor changes.
+
+struct WithAttributedStringPostprocessor<Content: View>: View {
+  @Environment(\.attributedStringPostprocessor) private var attributedStringPostprocessor
+
+  @State private var output: AttributedString?
+
+  let attributedString: AttributedString
+  let content: (AttributedString) -> Content
+
+  var body: some View {
+    content(output ?? AttributedString())
+      .onChange(of: Tuple(attributedString, attributedStringPostprocessor), initial: true) {
+        output = attributedStringPostprocessor.postprocess(input: attributedString)
+      }
+  }
+
+  init(
+    _ attributedString: AttributedString,
+    @ViewBuilder content: @escaping (AttributedString) -> Content
+  ) {
+    self.attributedString = attributedString
+    self.content = content
+  }
+}

Sources/Textual/Postprocessing/AttributedStringPostprocessor.swift

@@ -0,0 +1,39 @@
+import SwiftUI
+
+/// Transforms an attributed string after parsing and before rendering.
+///
+/// `InlineText` and `StructuredText` parse markup into an `AttributedString` using a
+/// ``MarkupParser``, resolve attachments, and then apply a postprocessor, giving you
+/// a chance to add or modify attributes that are independent of the markup
+/// itself — for example, highlighting search matches or annotating ranges.
+///
+/// This stage is separate from the ``MarkupParser`` because the data added by a postprocessor may
+/// change independently of the markup content. A parser only runs when the input string changes,
+/// so attributes whose source is external (a search query, a live filter) belong in a
+/// postprocessor rather than in the parser. The postprocessor is re-invoked whenever either the
+/// parsed attributed string or the postprocessor itself changes.
+///
+/// Apply a postprocessor using the ``TextualNamespace/attributedStringPostprocessor(_:)`` modifier:
+///
+/// ```swift
+/// InlineText(markdown: "Hello, world")
+///   .textual.attributedStringPostprocessor(SearchHighlighter(query: "world"))
+/// ```
+///
+/// The postprocessor receives the full attributed string, including resolved attachments.
+/// Ranges are valid against that complete string. Avoid dropping runs that carry
+/// attachment attributes, as this desyncs the rendered attachments from the attributed content.
+///
+/// ### When the Postprocessor Runs
+///
+/// The postprocessor is invoked whenever the parsed attributed string or the postprocessor itself
+/// changes. Equality is used to detect changes in the postprocessor, so the
+/// conforming type must reflect any state that affects output in its `==` implementation.
+
+public protocol AttributedStringPostprocessor: Hashable {
+  /// Returns a transformed attributed string for rendering.
+  ///
+  /// - Parameter input: The parsed, attachment-resolved attributed string.
+  /// - Returns: The attributed string to render.
+  func postprocess(input: AttributedString) -> AttributedString
+}

Sources/Textual/StructuredText/StructuredText.swift

@@ -117,9 +117,11 @@ public struct StructuredText: View {
 
   public var body: some View {
     WithAttachments(attributedString) {
-      BlockContent(content: $0)
-        .modifier(TextSelectionInteraction())
-        .modifier(TextSelectionCoordination())
+      WithAttributedStringPostprocessor($0) {
+        BlockContent(content: $0)
+          .modifier(TextSelectionInteraction())
+          .modifier(TextSelectionCoordination())
+      }
     }
     .coordinateSpace(.textContainer)
     .onChange(of: markup, initial: true) {

Sources/Textual/View+Textual.swift

@@ -146,7 +146,14 @@ extension TextualNamespace where Base: View {
   public func emojiAttachmentLoader(_ loader: some AttachmentLoader) -> some View {
     base.environment(\.emojiAttachmentLoader, loader)
   }
-
+  
+  /// Sets the postprocessor used to transform attributed content before rendering.
+  public func attributedStringPostprocessor(
+    _ postprocessor: some AttributedStringPostprocessor
+  ) -> some View {
+    base.environment(\.attributedStringPostprocessor, .init(postprocessor))
+  }
+  
   /// Enables or disables text selection for ``InlineText`` and ``StructuredText``.
   @available(tvOS, unavailable)
   @available(watchOS, unavailable)

Tests/TextualTests/Postprocessing/AttributedStringPostprocessorTests.swift

@@ -0,0 +1,55 @@
+import SwiftUI
+import Testing
+
+@testable import Textual
+
+struct AttributedStringPostprocessorTests {
+  @Test func typeErasedBoxEquality() {
+    let a = AnyAttributedStringPostprocessor(Fixtures.SearchHighlighter(query: "world"))
+    let b = AnyAttributedStringPostprocessor(Fixtures.SearchHighlighter(query: "world"))
+    let c = AnyAttributedStringPostprocessor(Fixtures.SearchHighlighter(query: "Hello"))
+
+    #expect(a == b)
+    #expect(a != c)
+  }
+
+  @Test func typeErasedBoxHashability() {
+    let a = AnyAttributedStringPostprocessor(Fixtures.SearchHighlighter(query: "world"))
+    let b = AnyAttributedStringPostprocessor(Fixtures.SearchHighlighter(query: "world"))
+    let c = AnyAttributedStringPostprocessor(Fixtures.SearchHighlighter(query: "Hello"))
+
+    #expect(a.hashValue == b.hashValue)
+    #expect(a.hashValue != c.hashValue)
+  }
+
+  @Test func typeErasedBoxDelegatesToBase() {
+    let box = AnyAttributedStringPostprocessor(Fixtures.SearchHighlighter(query: "world"))
+    let input = AttributedString("Hello, world")
+    let output = box.postprocess(input: input)
+
+    let highlightedRanges = output.runs.compactMap { run -> Range<AttributedString.Index>? in
+      run.backgroundColor != nil ? run.range : nil
+    }
+
+    #expect(highlightedRanges.count == 1)
+    #expect(String(input[highlightedRanges[0]].characters) == "world")
+  }
+}
+
+private enum Fixtures {
+  struct SearchHighlighter: AttributedStringPostprocessor {
+    let query: String
+
+    func postprocess(input: AttributedString) -> AttributedString {
+      var output = input
+      var start = output.startIndex
+
+      while let range = output[start...].range(of: query, options: .caseInsensitive) {
+        output[range].backgroundColor = .yellow
+        start = range.upperBound
+      }
+
+      return output
+    }
+  }
+}