feat(richtext): media spoilers (photo/video) in the rich-text composer

Per-item spoiler support for photos/videos in the rich-text editor / ChatInputContent
composer, round-tripping editor → draft → send → wire → receiver and reusing the
MediaDustNode dust + blur effect.

Model & round-trip:
- isSpoiler threads through MediaItem (editor Core) ↔ ChatInputMediaItem ↔
  InstantPageBlock.image/.video (Postbox + flatBuffers), the MTProto wire
  (pageBlockPhoto flags.1 / pageBlockVideo flags.2 — no Api regen), and both
  send converters + the Document↔ChatInputContent bridge. Back-compat: absent ⇒ false.

Authoring:
- Each media's per-cell "•••" menu carries an animated Spoiler toggle
  (Enable/DisableSpoiler) alongside Delete, in both the chat composer and the
  extended composer (RichTextAttachmentScreen). No tap-select edit menu.

Render:
- In-editor: each cell blurs its poster (chatSecretPhoto/chatSecretMessageVideo)
  under a static dust cover.
- Sent/received (InstantPage V2) + long-press-Send preview: a revealable dust +
  blur overlay above an always-sharp node; a tap plays the MediaDustNode
  expanding-mask reveal of the sharp image (matching ChatMessageInteractiveMediaNode).

Docs updated (docs/richtext-composer.md, docs/instantpage-richtext.md,
RichTextEditor/CLAUDE.md). Editor unit tests added/updated (Core + UIKit, green on
iPhone 17 Pro K3); TextFormatTests + full app build green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: isaac

docs/instantpage-richtext.md

@@ -141,6 +141,45 @@ remains produced only by real web Instant View articles.
 - **The slideshow registers under EVERY contained media index, and re-registers on an in-window rebuild.** Its stableId is positional (`.positional(.slideshow, position)`, not `.media(index)` like the static media views), so it can be reused for a *different* slideshow at the same block position; `rebuildPages()` re-runs `registerMedias()` (guarded by `window != nil`) so the new indices land in the registry. The gallery hooks iterate the live page nodes and match by `InstantPageMedia` identity, so registering one view under N indices is idempotent.
 - **The 4 static media views answer the gallery hooks with explicit per-class witnesses, NOT a shared protocol-extension override** — an extension-only implementation is statically dispatched and would silently bind to the nil default when invoked through the `InstantPageItemView`-typed registry wrapper.
 
+## InstantPage V2 media spoiler (revealable dust)
+
+A `pageBlockPhoto`/`pageBlockVideo` (and thus a collage cell) can carry a **spoiler** flag — the medium is
+hidden behind an animated "dust" cover until the recipient taps it, mirroring the regular
+`MediaSpoilerMessageAttribute` path in `ChatMessageInteractiveMediaNode`. This is how a rich message
+(`RichTextMessageAttribute` → InstantPage) carries a media spoiler; the composer-authoring side is in
+`docs/richtext-composer.md` §4.
+
+### Where things live
+
+| Concern | Location |
+|---|---|
+| model flag | `InstantPageBlock.image`/`.video` gain `spoiler: Bool` (`SyncCore_InstantPage.swift`); Postbox key `"sp"`, flatBuffers `Models/InstantPageBlock.fbs` `spoiler:bool (id:4)` |
+| wire | `ApiUtils/InstantPage.swift` reads/ORs `pageBlockPhoto` `flags.1` / `pageBlockVideo` `flags.2` — **no `TelegramApi` change** (the bit rides the existing `flags` Int32; constructor ids `1759c560`/`7c8fe7b6` unchanged) |
+| laid-out item | `InstantPageV2MediaImageItem`/`VideoItem` gain `spoiler: Bool` (`InstantPageV2Layout.swift`); single-media + collage item-constructing cases thread it |
+| render | `InstantPageV2MediaViews.swift` — `MediaSpoilerDustOverlay` hosts a `MediaDustNode` (import `InvisibleInkDustNode`) in both `InstantPageV2MediaImageView`/`VideoView` |
+
+### Non-obvious invariants
+
+- **The dust cover is NON-interactive; reveal is driven through the wrapped node's own tap.** The overlay
+  (`containerNode` + `dustNode`) is `isUserInteractionEnabled = false`, so taps fall through to the sibling
+  `InstantPageImageNode` below it. Each view's `openMedia` closure is **gated**: while `overlay.concealed`,
+  the first tap calls `overlay.reveal()` (which sets `concealed = false` synchronously and drives
+  `MediaDustNode.tap(at:)` → the wipe animation → the `revealed` callback removes the cover) and returns
+  **without** opening the gallery; once revealed, taps fall through to `handleOpenMediaTap` (gallery). This
+  mirrors `ExtendedMediaOverlayNode.reveal(animated:)` but with a non-interactive cover instead of an
+  interactive button.
+- **Reuse resets reveal state by media id.** A positionally-reused media view (`stableId = .media(index)`,
+  reconciled through `update(item:)` → `updateSpoiler`) keyed on `EngineMedia.Id`: a different id or
+  `spoiler == false` tears down the cover; the same spoiler medium keeps its (possibly already-revealed)
+  state — so scrolling can't bleed a stale reveal onto a different photo, and a re-layout of the same photo
+  doesn't re-hide it. **No `InstantPageRenderer.reuse(existingView:)` change** was needed — it already routes
+  through `update(item:)`.
+- **Collage cells inherit spoiler for free.** `layoutCollage` flattens inner `.image`/`.video` into ordinary
+  top-level `.mediaImage`/`.mediaVideo` items (see the collage section above), threading each inner block's
+  `spoiler` — so an album with one spoiler cell just works, with no collage-specific spoiler code.
+- **The long-press-Send options preview** renders through the same `InstantPageV2View`, so a spoiler'd media
+  shows the dust cover in the preview bubble automatically.
+
 ## InstantPage V2 text item height (true font line box)
 
 `layoutTextItem` (`InstantPageV2Layout.swift`) sizes a `.text` item to the **true font line height**, not the cap box. A single-line item measures exactly `fontAscent + fontDescentBelowBaseline` (`A + D`); the old behavior was the cap box `fontLineHeight = floor(fontAscent + fontDescent)` (`A − D`).

docs/richtext-composer.md

@@ -198,6 +198,28 @@ All inline / structural features round-trip losslessly through the native compos
   hosts; "Add another photo/video" is wired in the **article editor**'s more-menu only — the composer's
   in-place Add is a deferred follow-up (the composer already renders/edits multi-media from sent albums
   and drafts). Design + plan: `docs/superpowers/{specs,plans}/2026-07-08-richtext-multi-media-container*`.
+  **Media spoilers (added 2026-07-08).** A photo/video can be marked a Telegram-style spoiler (dust-covered
+  until tapped), per **item**: `MediaItem.isSpoiler` (editor Core) ↔ `ChatInputMediaItem.isSpoiler`
+  (both additive, optional-Codable, absent ⇒ `false`, so all existing docs/drafts/messages decode
+  unchanged) ↔ a `spoiler: Bool` associated value on `InstantPageBlock.image`/`.video`. **Authoring:**
+  tap-select a single medium → the edit menu's **"Spoiler"** item (`imageSelectionMenu`, toggles via
+  `toggleSelectedMediaSpoiler`); for an album, each cell's **"•••"** menu carries a per-cell "Spoiler"
+  (threaded through `MediaControlRequest.isSpoiler`/`toggleSpoiler` → `MediaControlContext` → the panel's
+  ContextUI menu). Both route to `RichTextEditorView.toggleMediaSpoiler(itemIndex:)` →
+  `DocumentCanvasView.toggleMediaSpoiler(blockID:itemIndex:)` (one undo step, in-place `MediaBlockBox`
+  rebuild like `deleteMediaItem`). **In-editor render is a NON-revealable authoring cover** — `MediaItemNodeView`
+  hosts a `MediaDustNode` (via `InvisibleInkDustNode`) per spoiler cell, `revealOnTap = false`, non-interactive
+  (taps fall through to selection); the flag reaches it through `MediaProviderItem.isSpoiler` and is folded into
+  the `syncMediaItemViews` items-signature so a toggle re-provides the cell. **On the wire, no Api
+  regeneration:** the server schema already defines `pageBlockPhoto#1759c560 spoiler:flags.1` /
+  `pageBlockVideo#7c8fe7b6 spoiler:flags.2`, so the bit is read/OR'd purely in `ApiUtils/InstantPage.swift`
+  (like `autoplay`/`loop`). The flag round-trips through Postbox Codable (`"sp"` key), the flatBuffers
+  `InstantPageBlock` path (`Models/InstantPageBlock.fbs` + the hand-written encode/decode — so it survives every
+  InstantPage persistence path, not just Postbox), and BOTH send converters (`ChatInputContentInstantPage`
+  composer + `InstantPageBuilder` article). **Sent/received message render** (revealable dust with first-tap
+  reveal → then gallery) is in `instantpage-richtext.md`. Design + plan:
+  `docs/superpowers/{specs,plans}/2026-07-08-richtext-media-spoiler*`. **All sim tests run on the iPhone 17 Pro
+  K3 sim.**
 - **Location maps:** a picked location is a `Block.media` with **`MediaKind.location`** whose `mediaID` resolves to
   a `TelegramMediaMap`. A map is an **id-less** `Media`, so the host mints a deterministic `"map:lat:long"` key
   (not the usual `namespace:id`). It renders inline as a map snapshot through the same `MediaItemNodeView` seam —

submodules/BrowserUI/Sources/BrowserMarkdown.swift

@@ -1411,7 +1411,8 @@ private func markdownBlocks(from node: MarkdownIntentNode, context: MarkdownConv
                     id: image.mediaId,
                     caption: image.caption,
                     url: image.linkUrl,
-                    webpageId: nil
+                    webpageId: nil,
+                    spoiler: false
                 )
             ]
         }

submodules/BrowserUI/Sources/BrowserReadability.swift

@@ -750,7 +750,8 @@ private func parseImage(_ input: [String: Any], _ media: inout [EngineMedia.Id:
         id: id,
         caption: caption,
         url: nil,
-        webpageId: nil
+        webpageId: nil,
+        spoiler: false
     )
 }
 
@@ -820,8 +821,8 @@ private func parseFigure(_ input: [String: Any], _ media: inout [EngineMedia.Id:
     guard var block else {
         return nil
     }
-    if let caption, case let .image(id, _, url, webpageId) = block {
-        block = .image(id: id, caption: InstantPageCaption(text: caption, credit: .empty), url: url, webpageId: webpageId)
+    if let caption, case let .image(id, _, url, webpageId, spoiler) = block {
+        block = .image(id: id, caption: InstantPageCaption(text: caption, credit: .empty), url: url, webpageId: webpageId, spoiler: spoiler)
     }
     return block
 }

submodules/GalleryData/Sources/GalleryData.swift

@@ -33,13 +33,13 @@ public enum ChatMessageGalleryControllerData {
 
 private func instantPageBlockMedia(pageId: EngineMedia.Id, block: InstantPageBlock, media: [EngineMedia.Id: EngineRawMedia], counter: inout Int) -> [InstantPageGalleryEntry] {
     switch block {
-        case let .image(id, caption, _, _):
+        case let .image(id, caption, _, _, _):
             if let m = media[id] {
                 let result = [InstantPageGalleryEntry(index: Int32(counter), pageId: pageId, media: InstantPageMedia(index: counter, media: EngineMedia(m), url: nil, caption: caption.text, credit: caption.credit), caption: caption.text, credit: caption.credit, location: InstantPageGalleryEntryLocation(position: Int32(counter), totalCount: 0))]
                 counter += 1
                 return result
             }
-        case let .video(id, caption, _, _):
+        case let .video(id, caption, _, _, _):
             if let m = media[id] {
                 let result = [InstantPageGalleryEntry(index: Int32(counter), pageId: pageId, media: InstantPageMedia(index: counter, media: EngineMedia(m), url: nil, caption: caption.text, credit: caption.credit), caption: caption.text, credit: caption.credit, location: InstantPageGalleryEntryLocation(position: Int32(counter), totalCount: 0))]
                 counter += 1

submodules/InstantPageUI/Sources/InstantPageImageNode.swift

@@ -83,6 +83,13 @@ final class InstantPageImageNode: ASDisplayNode, InstantPageNode, InstantPageExt
 
     private var themeUpdated: Bool = false
     private var externalMediaDimensionsUpdated: Bool = false
+
+    // Spoiler support: a separate heavily-blurred (`.blurBackground`) overlay node that occludes the sharp
+    // `imageNode` while concealed. A distinct node is required — `TransformImageArguments.==` ignores
+    // `resizeMode`, so flipping the main node's resizeMode alone would early-out and never re-render; and a
+    // separate node also gives an instant reveal (remove it → the always-sharp `imageNode` shows). The
+    // enclosing V2 media view drives the dust cover + reveal timing. Default off (no effect on web IV).
+    private var contentBlurredSignal: Signal<(TransformImageArguments) -> DrawingContext?, NoError>?
 
     init(context: AccountContext, sourceLocation: InstantPageSourceLocation, theme: InstantPageTheme, webPage: TelegramMediaWebpage, media: InstantPageMedia, attributes: [InstantPageImageAttribute], interactive: Bool, roundCorners: Bool, fit: Bool, openMedia: @escaping (InstantPageMedia) -> Void, longPressMedia: @escaping (InstantPageMedia) -> Void, activatePinchPreview: ((PinchSourceContainerNode) -> Void)?, pinchPreviewFinished: ((InstantPageNode) -> Void)?, imageReferenceForMedia: ((TelegramMediaImage) -> ImageMediaReference)? = nil, fileReferenceForMedia: ((TelegramMediaFile) -> FileMediaReference)? = nil, getPreloadedResource: @escaping (String) -> Data?) {
         self.context = context
@@ -119,7 +126,8 @@ final class InstantPageImageNode: ASDisplayNode, InstantPageNode, InstantPageExt
             } else {
                 let imageReference = imageReferenceForMedia?(image) ?? ImageMediaReference.webPage(webPage: WebpageReference(webPage), media: image)
                 self.imageNode.setSignal(chatMessagePhoto(postbox: context.account.postbox, userLocation: sourceLocation.userLocation, photoReference: imageReference))
-                
+                self.contentBlurredSignal = chatSecretPhoto(account: context.account, userLocation: sourceLocation.userLocation, photoReference: imageReference, ignoreFullSize: true)
+
                 if !interactive || shouldDownloadMediaAutomatically(settings: context.sharedContext.currentAutomaticMediaDownloadSettings, peerType: sourceLocation.peerType, networkType: MediaAutoDownloadNetworkType(context.account.immediateNetworkType), authorPeerId: nil, contactsPeerIds: Set(), media: image) {
                     self.fetchedDisposable.set(chatMessagePhotoInteractiveFetched(context: context, userLocation: sourceLocation.userLocation, photoReference: imageReference, displayAtSize: nil, storeToDownloadsPeerId: nil).start())
                 }
@@ -158,6 +166,7 @@ final class InstantPageImageNode: ASDisplayNode, InstantPageNode, InstantPageExt
                 } else {
                     self.imageNode.setSignal(chatMessageVideo(postbox: context.account.postbox, userLocation: sourceLocation.userLocation, videoReference: fileReference))
                 }
+                self.contentBlurredSignal = chatSecretMessageVideo(account: context.account, userLocation: sourceLocation.userLocation, videoReference: fileReference)
                 if file.isVideo {
                     self.statusNode.transitionToState(.play(.white), animated: false, completion: {})
                     self.pinchContainerNode.contentNode.addSubnode(self.statusNode)
@@ -178,6 +187,7 @@ final class InstantPageImageNode: ASDisplayNode, InstantPageNode, InstantPageExt
         } else if case let .webpage(webPage) = media.media, case let .Loaded(content) = webPage.content, let image = content.image {
             let imageReference = imageReferenceForMedia?(image) ?? ImageMediaReference.webPage(webPage: WebpageReference(webPage), media: image)
             self.imageNode.setSignal(chatMessagePhoto(postbox: context.account.postbox, userLocation: sourceLocation.userLocation, photoReference: imageReference))
+            self.contentBlurredSignal = chatSecretPhoto(account: context.account, userLocation: sourceLocation.userLocation, photoReference: imageReference, ignoreFullSize: true)
             self.fetchedDisposable.set(chatMessagePhotoInteractiveFetched(context: context, userLocation: sourceLocation.userLocation, photoReference: imageReference, displayAtSize: nil, storeToDownloadsPeerId: nil).start())
             self.statusNode.transitionToState(.play(.white), animated: false, completion: {})
             self.pinchContainerNode.contentNode.addSubnode(self.statusNode)
@@ -213,9 +223,38 @@ final class InstantPageImageNode: ASDisplayNode, InstantPageNode, InstantPageExt
         }
     }
 
-    func updateIsVisible(_ isVisible: Bool) {    
+    func updateIsVisible(_ isVisible: Bool) {
     }
-    
+
+    /// Builds a heavily-blurred (`blurred: true` secret-media signal) `TransformImageNode` for a spoiler
+    /// cover. The caller (the V2 media view's `MediaSpoilerDustOverlay`) HOSTS it above this node so the
+    /// dust's reveal mask clears both blur + dust together, exposing the always-sharp `imageNode` — matching
+    /// `ExtendedMediaOverlayNode`. Layout is via `layoutSpoilerBlurredNode(_:size:)`. Nil for media with no
+    /// image signal (e.g. maps). The sharp `imageNode` itself is never blurred.
+    func makeSpoilerBlurredNode() -> TransformImageNode? {
+        guard let contentBlurredSignal = self.contentBlurredSignal else {
+            return nil
+        }
+        let node = TransformImageNode()
+        node.contentAnimations = []
+        node.setSignal(contentBlurredSignal)
+        return node
+    }
+
+    /// Lays out a node from `makeSpoilerBlurredNode()` to fill `size` (same aspect-fill + corner-radius math
+    /// as the sharp `imageNode`); `.blurBackground` + the `blurred: true` signal draw a full blur with no
+    /// sharp foreground. Idempotent (a `TransformImageNode` no-ops on unchanged args).
+    func layoutSpoilerBlurredNode(_ node: TransformImageNode, size: CGSize) {
+        node.frame = CGRect(origin: CGPoint(), size: size)
+        guard let dimensions = self.effectiveMediaDimensions() else {
+            return
+        }
+        let imageSize = dimensions.cgSize.aspectFilled(size)
+        let radius: CGFloat = self.roundCorners ? floor(min(imageSize.width, imageSize.height) / 2.0) : 0.0
+        let apply = node.asyncLayout()(TransformImageArguments(corners: ImageCorners(radius: radius), imageSize: imageSize, boundingSize: size, intrinsicInsets: UIEdgeInsets(), resizeMode: .blurBackground, emptyColor: .clear))
+        apply()
+    }
+
     func updateLayout(size: CGSize, transition: ContainedViewLayoutTransition) {
     }
 
@@ -364,7 +403,7 @@ final class InstantPageImageNode: ASDisplayNode, InstantPageNode, InstantPageExt
             self.currentSize = size
             self.themeUpdated = false
             self.externalMediaDimensionsUpdated = false
-            
+
             self.pinchContainerNode.frame = CGRect(origin: CGPoint(), size: size)
             self.pinchContainerNode.update(size: size, transition: .immediate)
             self.imageNode.frame = CGRect(origin: CGPoint(), size: size)
@@ -417,7 +456,7 @@ final class InstantPageImageNode: ASDisplayNode, InstantPageNode, InstantPageExt
             }
         }
     }
-    
+
     func transitionNode(media: InstantPageMedia) -> (ASDisplayNode, CGRect, () -> (UIView?, UIView?))? {
         if instantPageMediaMatchesNodeIdentity(media, self.media) {
             let imageNode = self.imageNode

submodules/InstantPageUI/Sources/InstantPageLayout.swift

@@ -608,7 +608,7 @@ public func layoutInstantPageBlock(webpage: TelegramMediaWebpage, userLocation:
             }
             contentSize.height += verticalInset
             return InstantPageLayout(origin: CGPoint(), contentSize: contentSize, items: items)
-        case let .image(id, caption, url, webpageId):
+        case let .image(id, caption, url, webpageId, _):
             if case let .image(image) = media[id], let largest = largestImageRepresentation(image.representations) {
                 let imageSize = largest.dimensions
                 var filledSize = imageSize.cgSize.aspectFitted(CGSize(width: boundingWidth - safeInset * 2.0, height: 1200.0))
@@ -648,7 +648,7 @@ public func layoutInstantPageBlock(webpage: TelegramMediaWebpage, userLocation:
             } else {
                 return InstantPageLayout(origin: CGPoint(), contentSize: CGSize(), items: [])
             }
-        case let .video(id, caption, autoplay, _):
+        case let .video(id, caption, autoplay, _, _):
             if case let .file(file) = media[id], let dimensions = file.dimensions {
                 let imageSize = dimensions
                 var filledSize = imageSize.cgSize.aspectFitted(CGSize(width: boundingWidth - safeInset * 2.0, height: 1200.0))
@@ -695,11 +695,11 @@ public func layoutInstantPageBlock(webpage: TelegramMediaWebpage, userLocation:
             for subItem in innerItems {
                 var size = CGSize()
                 switch subItem {
-                    case let .image(id, _, _, _):
+                    case let .image(id, _, _, _, _):
                         if case let .image(image) = media[id], let largest = largestImageRepresentation(image.representations) {
                             size = largest.dimensions.cgSize
                         }
-                    case let .video(id, _, _, _):
+                    case let .video(id, _, _, _, _):
                     if case let .file(file) = media[id], let dimensions = file.dimensions {
                             size = dimensions.cgSize
                         }
@@ -814,7 +814,7 @@ public func layoutInstantPageBlock(webpage: TelegramMediaWebpage, userLocation:
 
             for subBlock in subItems {
                 switch subBlock {
-                    case let .image(id, caption, url, webpageId):
+                    case let .image(id, caption, url, webpageId, _):
                         if case let .image(image) = media[id], let imageSize = largestImageRepresentation(image.representations)?.dimensions {
                             let mediaIndex = mediaIndexCounter
                             mediaIndexCounter += 1